Wait for calls and handle them
Listen for a call and handle incoming calls. If the register flag is specified, it will register against that target otherwise it will listen on the specified target address. In that case, the address would need to be assigned to the local machine.
This tool receives calls (i.e. incoming
INVITE messages) and handles them according to the behaviour specified by the
flag. By default, the tool accepts the call and plays an internal audio file
music.raw, if the file does not exist in the current directory and hangup if the tool is terminated. It handles the normal SIP traffic, including SIP Re-INVITE and other in-dialog traffic.
This tool is useful when simulating a system that automatically handles calls (e.g. auto-answer or auto-answer and then hangup after 1 second), perhaps as part of a security test that requires that functionality.
By default, the tool will attempt to listen on the target address that is specified unless the
register flag is used. This means that the target address needs to be associated with the local machine. When the
register flag is used, the tool will register against the specified target (a SIP registrar) and listen on a random port which is advertised in the SIP
Contact header per the SIP standard.
The following is an example logging of the tool when run with the default settings:
INFO Listening on 0.0.0.0:5060 INFO Registered with udp://example.org:5060 as sip:6uUCKS9d@demo.sipvicious.pro INFO Incoming INVITE from 192.168.99.2:5060 INFO Accepting call and playing music.raw INFO BYE received, terminating call
sipvicious sip utils callee [target1] [flags]
--callee-mode string specify how to behave during the call attempt; format: action or action:duration or action:duration:destination; (ignore|hangup-call|never-hangup|refer) (default "never-hangup") --codec strings Specify the codec that should be used for the RTP stream (ulaw|alaw|opus) (default [ulaw,alaw,opus]) -u, --credentials string set the username and password in the following format: username:password (e.g. 1000:test123) -D, --domain string override domain name for the SIP address --duration duration set how long to keep the tool going before quitting -f, --from string specify the from header address; if not specified, the from address is constructed from the credentials, otherwise a random numeric extension is used --max-calls int32 Set the maximum number of calls to handle before quitting --register register with the specified target --rtp-payload string specify the RTP payload for the audio (e.g. music.wav or 2600hz.raw) (default "music.wav")
--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 --logfile string specify a log filename --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, - for stdout
sipvicious sip utils callee sipvicious sip utils callee tcp://target:5060 --register --credentials username:password sipvicious sip utils callee tcp://target:5060 --callee-mode hangup-call:10s sipvicious sip utils callee udp://0.0.0.0:5060 --callee-mode hangup-call
# register with target with given credentials and a duration sipvicious sip utils callee tcp://demo.sipvicious.pro:5060 --register -u 1000:1500 --duration 20s # listen on 0.0.0.0 on the TCP port 5060, and hangup incoming calls after 10 seconds while only allowing the alaw codec sipvicious sip utils callee tcp://0.0.0.0:5060 --callee-mode hangup-call:10s --codec alaw --max-calls 10 # listen on 0.0.0.0 on the UDP port 5060 and use a specific rtp payload for incoming calls along with a custom from address sipvicious sip utils callee udp://0.0.0.0:5060 --rtp-payload 2600hz.raw -f email@example.com
Standard exit codes for SIPVicious apply. This tool does not run a security test and so exit code 3 has no definition.
The CA cert can be passed when making use of client certificate authentication. The file should be formatted as PEM.
callee-mode allows one to specify how to behave during a call. The value of this flag could be one of the following actions:
ignorewhich does not respond to SIP INVITE requests
hangup-callwhich hangs up (by sending a
BYE) after picking up the incoming call (i.e. when a
200 OKis sent)
never-hangupwhich handles the call flow normally without hanging up
referwhich transfers the call to another SIP URI
Additionally, the action value may be preceded by a colon and a duration value. This duration should be specified when the action should be taken after a specific time (e.g. 2s or 300ms). For example,
hangup-ringing:300ms. To hangup a call after 30 seconds, the value of
callee-mode should be
refer is specified, the parameters take a SIP address after the duration value. This is the address to refer the call to. For example:
NOTE: The following
callee-mode values cannot be combined with other
The client certificate must be passed when making use of client certificate authentication. The file should be formatted as PEM.
The client key must be passed when making use of client certificate authentication. The file should be formatted as PEM.
Specify the codec to be supported for the SDP and also in the RTP stream. Currently supported are ulaw, alaw and opus. You may pass multiple codecs by delimiting using a comma, as follows:
When rates and channels need to be passed, they can be provided after the codec name, separated by a slash. For example:
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
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.
Specify valid credentials so that the registration can be done authenticated. The following format is used
Tells the logger to print out debug messages.
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.
Specify how long to keep the tool going. Example:
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.
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.
Set the maximum number of calls to handle (according to the
callee-mode setting) before the tool exits.
This is useful when using the tool as part of automation.
Register may use credentials to be passed so that a
REGISTER message is sent to authenticate with a registrar server before starting the call. The registration is maintained as per SIP standards, so that authentication does not time out.
rtp-payload parameter allows the setting of a file that is used for the RTP stream. The following file types are supported:
.raw, for raw audio to be passed to the RTP stream without any transcoding
.wav, for wave files to be transcoded for the RTP stream
The audio is looped unless a
noloop parameter is passed after a comma, e.g.
If a blank filename, i.e.
"", is passed, then no RTP is sent during the call and no SDP is set.
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
srtp mode can also be either
sdes. In both
sdes modes, the parameters are not required and will be generated randomly as need be.
Options for both
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.keyand finally, the optional certificate authority file
--srtp sdes:d0RmdmcmVCspeEc3QGZiNWpVLFJhQX1cfHAwJSojwhere 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
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.
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.
See call documentation.