sip fuzz stirshaken

Summary

Fuzz STIR/SHAKEN identity header

What it does

Perform a SIP fuzzing test on SIP servers that validate the identity header as specified in STIR/SHAKEN. This tool allows testers to check the robustness of the parser involved in decoding and validating the Identity header by sending mutated SIP Identity headers to the target.

Tool functionality

The STIR/SHAKEN fuzzer sends mutated JWT tokens and Identity header values to find security issues in the implementation of the STIR/SHAKEN protocols.

It does this by mutating one of the following randomly before starting a call:

• the JWT header JSON string with a valid signature
• the JWT payload JSON string with a valid signature
• the entire SIP header value with the signed base64 JWT token and other parameters

Command format

sipvicious sip fuzz stirshaken <target1 [target2 [target3 ...]]> [flags]

Flags

      --auth-config strings          Specify SIP authentication configuration. See documentation for details e.g. algorithm:sha-256
  -c, --conn-count int               Number of sockets to use (per target) (default 30)
  -u, --credentials string           Set the username and password in the following format: username:password[:realm] (e.g. 1000:test123:snowflake). Realm is optional
  -D, --domain string                Override domain name for the SIP address
  -e, --extension string             Specify a target extension or SIP URI to call; if not specified, a random numeric extension is used
  -f, --from string                  Specify a from extension or SIP URI to call from; if not specified, a random numeric extension is used
      --max-requests int             Set the maximum number of requests to send
      --mutator string               Specify the mutator to use (radamsa|zzuf|none) (default "radamsa")
      --rate string                  Specify how many packets to send for each period of time; format: packets/duration; e.g. 100/30ms
      --register                     Register before making a call; requires -u
      --stir-shaken-config strings   Specify values to build the Identity header used for STIR/SHAKEN; see the tool documentation for full definition (default [privatekey:private.pem,alg:ES256])

Flags inherited from parent commands

      --ca-cert string       TLS CA Certificate
      --client-cert string   TLS client certificate
      --client-key string    TLS client private key
  -C, --config string        configuration file to use (may be JSON, TOML or YAML)
      --debug                set log level to debug
  -T, --duration duration    Stop the tool after a certain amount of time; e.g. 30s
      --logfile string       specify a log filename
      --results string       specify the filename for the result output, defaults to standard output. See documentation for information on file extension meanings
      --srtp string          Specify if either none, dtls or sdes to enforce SRTP for calls; format: method or method:parameters; see full documentation for details (default "none")
      --templates string     Directory to search for template overrides (default ".")
      --tls-key-log string   TLS key log

Examples

sipvicious sip fuzz stirshaken tcp://demo.sipvicious.pro:5060

Advanced examples

# launch a fuzzing exercise, specifying the private key file and the values for x5u and info
sipvicious sip fuzz stirshaken  tcp://demo.sipvicious.pro:5060 \
--stir-shaken-config privatekey:private.pem \
--stir-shaken-config x5u:http://demo.sipvicious.pro/1 \
--stir-shaken-config info:http://demo.sipvicious.pro/2

# launch a fuzzing exercise, specifying the HMAC secret in the x5u and as the private key to
# sign the identity header with; tries to exploit Signature Algorithm Confusion
sipvicious sip fuzz stirshaken  tcp://demo.sipvicious.pro:5060 \
--stir-shaken-config alg:HS256 \
--stir-shaken-config x5u:http://demo.sipvicious.pro/hmac.txt \
--stir-shaken-config privatekey:hmac.txt

# launch a fuzzing exercise, with JWT alg set to None and no signing included
sipvicious sip fuzz stirshaken  tcp://demo.sipvicious.pro:5060 \
--stir-shaken-config x5u:http://demo.sipvicious.pro \
--stir-shaken-config alg:None

Exit codes

Full flag documentation

Flag: --auth-config

Specify SIP authentication configuration. This flag accepts the following values:

• algorithm:value where value may be md5, md5-sess, sha-256, sha-256-sess, sha-512-256 or sha-512-256-sess. This value will force the tool to calculate the authorization response based on the first WWW-Authenticate or Proxy-Authenticate header field that matches this algorithm. If no match is found then the first WWW-Authenticate or Proxy-Authenticate header is selected.

Flag: --ca-cert

The CA cert can be passed when making use of client certificate authentication. The file should be formatted as PEM.

Flag: --client-cert

The client certificate must be passed when making use of client certificate authentication. The file should be formatted as PEM.

Flag: --client-key

The client key must be passed when making use of client certificate authentication. The file should be formatted as PEM.

Flag: -C, --config

Specify a configuration file which may be a JSON, TOML and YAML config format. To get the default settings and figure out which settings are available, one may run the sipvicious utils dump config command. This is typically used to create a template configuration that can then be edited as need be.

These settings may be overwritten when the corresponding flag is explicitly set, if one is present.

Flag: -c, --conn-count

The default connection behaviour is to try to keep all connections alive or, in the case of UDP, to reuse the same socket. This flag overrides this behaviour so that the connection is closed after each message is sent. This can uncover vulnerabilities related to socket handling in relation to SIP signalling.

Flag: -u, --credentials

Specify valid credentials so that SIP fuzzing can be done authenticated. The following format is used username:password (e.g. 1000:test123). When not specified, if required, the tool will send fake challenge responses.

Additionally, a realm may be specified as a third parameter (e.g. 1000:test123:snowflake).

Note: This does not set the correct SIP To and From headers, which might cause authorization checks to fail. Set the -e and --from flags if this is required.

Flag: --debug

Tells the logger to print out debug messages.

Flag: -D, --domain

A domain name can be specified so that the SIP URI contains that particular domain rather than the one specified as the target. This is useful for targets that expect a particular domain name.

Flag: -T, --duration

Specify the maximum duration of the attack so that it stops after a certain time. Examples include:

• 30s
• 10m
• 24h

Flag: -e, --extension

This flag allows users to target a particular extension, overriding the default behaviour of targeting random extensions. The value can be either just the SIP extension/username (e.g. 1234) or a SIP URI (e.g. sip:user@example.org).

Flag: -f, --from

This flag allows users to set the From address, overriding the default behaviour of setting a random extension or the username in the credentials when one is provided. The value can be either just the SIP extension/username (e.g. 1234) or a SIP URI (e.g. sip:user@example.org).

Flag: --logfile

When the logfile flag is specified, a log file is created in the location specified and logs are generated in this file instead of being sent to standard output. If the filename ends with a .json file extension, then the output format is in JSON, otherwise it defaults to text format.

Flag: --max-requests

Specify the maximum number of messages to send before stopping the attack.

Flag: --mutator

Choose the mutation engine to use. Currently supported are the following:

• radamsa
• zzuf
• none

The none mutator can be specified for debugging reasons, for example, to ensure that the SIP messages are generated correctly. When using this value, no fuzzing is actually done.

Flag: --rate

Rate allows one to limit the attack below a certain rate. If the value is 100/30ms, that means that 100 packets should be spread out evenly across 30 milliseconds across all the connections per target.

Flag: --register

Register requires credentials to be passed so that a REGISTER message is sent to authenticate with a registrar server before starting the attack. The registration is maintained as per SIP standards, so that authentication does not time out.

Flag: --results

When the results flag is specified, upon completing the test, it outputs the results to the specified filename. The format for this output file is text unless the filename ends with a .json file extension. In that case, the result output is that of JSON.

The schema for the JSON output for this submodule can be found here.

Flag: --srtp

The srtp flag when specified, allows users to set the SRTP mode. By default, outgoing calls do not make use of SRTP, while incoming calls automatically handle SRTP depending on the SDP body of the incoming INVITE message. When the srtp flag is set to none, incoming calls do not make use of SRTP, regardless of the SDP body in an incoming INVITE. The srtp mode can also be either dtls or sdes. In both dtls and sdes modes, the parameters are not required and will be generated randomly as need be.

Options for both dtls and sdes mode may be passed after a colon. For example:

• --srtp dtls:cert.crt:cert.key[:ca.crt] where the first argument after the mode (dtls) is the public certificate cert.crt, then the private key cert.key and finally, the optional certificate authority file ca.crt
• --srtp sdes:d0RmdmcmVCspeEc3QGZiNWpVLFJhQX1cfHAwJSoj where the argument is the base64 encoded cryptographic master key appended with the master salt.

Note that in the case of sdes key, the master key needs to be a valid length, which is 30 octets, for the default crypto-suite AES_CM_128_HMAC_SHA1_80.

Flag: --stir-shaken-config

Set the Identity header and specify the STIR/SHAKEN configuration. This flag accepts the following values:

• alg:algorithm where the algorithm may be ES256, HS256 or None
• privatekey:filename where the filename points to a PEM encoded private key in the case of ES256, or a file containing the HMAC secret in the case of HS256
• x5u:url sets the URL in the x5u part of the JWT header
• info:url sets the URL in the info parameter within the Identity header
• origid:string - sets the value of the origination identifier value in the JWT body
• dest:string - sets the dest tn value in the JWT body
• orig:xxx - sets the orig tn value in the JWT body
• attest:string sets the attest value in the JWT body

Flag: --templates

Allows one to set the template directory which is used to load (or save) the SIP templates.

To get the default SIP templates, make use of the sipvicious sip utils dump templates command.

Flag: --tls-key-log

The TLS key log creates a file with the TLS key that can then be used to decrypt the TLS stream in tools that support it, such as Wireshark.

Future enhancements

This tool is works in progress.

JSON schema

The following is the JSON schema for the JSON output of this tool:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "returncode": { "type": "integer" },
        "description": { "type": "string" }
      }
    },
    "targets": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "target": { "type": "string" },
          "status": {
            "type": "object",
            "properties": {
              "returncode": { "type": "integer" },
              "description": { "type": "string" }
            }
          },
          "results": {
            "type": "object",
            "properties": {
            }
          },
          "issues": {
            "type": "object",
            "properties": {
            }
          }
        }
      }
    }
  }
}