Skip to end of metadata
Go to start of metadata

Project Requirements

Asterisk 1.8 introduced the security events API, which is defined in include/asterisk/security_events.h. The SIP channel driver, chan_sip, needs to be updated to take advantage of this API for reporting events that potentially have security implications.

Icon

This section is incomplete.

Summary

Problem: Attacks or unintentional configuration problems on various IP-based communications mechanisms (VoIP signalling, or IM, or media channels, or manager or...?) can lead to conditions in Asterisk that create denial-of-service circumstances, permit brute-force password attacks, or message/media confusion. Other attack results, including application or system security issues, may be exposed as a result of high-volume packet floods or malformed packets from trusted or untrusted sources.

Root problem: Asterisk has no sophisticated method of defining packet or signaling profile groups and taking action based on desired or undesired patterns.

Proposed Solution: Implement attack detection on a per-channel driver basis, reporting up to a generic socket API for blocking/logging. Create named ACLs for passive as well as dynamic packet examination/filtering. Create dynamic filter capability based on attack detection, and allow all channels to utilize a common filtering framework. Permit external exportation of passive and dynamic filters to external third-party attack mitigation tools.

Details

Details on threats: There are several vulnerabilities that can occur when exposing the various IP-based protocol stacks to the public (or private) Internet(s). These include but are not limited to:

  1. Denial of Service from one or more attack origin IP addresses
    1. Random packet garbage
    2. Syntactically valid but session-invalid packet garbage
    3. Session-valid but malformed packet garbage
  2. Brute-force password attacks on VoIP protocols from one or more IP addresses
  3. System penetration via buffer overflow or other methods

Other problems that a robust filtering/rate-limiting package may provide:

  1. Protection against DDoS amplification
  2. Protection against runaway UA messaging
  3. Arbitrary re-direction of VoIP call signaling to alternate servers

Resolved:

  • It is desirable to have named access-lists that are available across all channel drivers
  • It is desirable to have both IP-generic (flooding) security as well as protocol-specific filtering built into Asterisk
  • It is desirable to have each channel driver able to define what is "bad" and then describe what actions to take in the event of "bad" packets.
  • It is desirable to have a packet filtering mechanism that is re-usable across all channel types.
  • It may be desirable to have the ability to export actions to external programs based on filters defined in the channels, as whatever protective measures that are built into Asterisk may be insufficient or otherwise inappropriate based on the attack method.
  • ACLs and actions should be capable of acting on channel-specific events, IP src/dst pattern matching, port pattern matching, session pattern matching, volume pattern matching
  • Actions based on "bad" events should be both passive (standard ACLs) and active (dynamic filters that change based on behaviors)
  • Actions and filters should APPLY IN BOTH DIRECTIONS OF IP COMMUNICATIONS. This means as an example and somewhat counter-intuitively, that SIP packets outbound from Asterisk to some remote endpoint should be able to be limited. This is in response to some remote devices being incapable of handling large volumes of certain packet types, or having call volumes (CPS) of a particular limit. It also helps reduce the (unusual) chance of Asterisk being an amplifier in DoS attacks.
  • Dynamic filters should be stored across instantiations of Asterisk, including timers.
  • External filters should be flushed and re-added at instantiations of Asterisk BEFORE channels are loaded.

Programming:

  • RED and other dynamic algorithms for filtering may be found in ipfw, which is BSD-licensed (note: Luigi Rizzo is/was an ipfw programmer?)
  • named and grouped ACLs are part of ipfw also
  • All syntaxes and configurations should support IPv4 and IPv6 addresses and methods to avoid the nightmare of backwards-reengineering when IPv6 is embedded

References:

Channel-specific notes:

SIP:

  • "calls per second" - should apply only to INVITEs?
  • RTP media dynamic filters: should support dynamic updating of filters based on RTP expected from one or more endpoints. This should block the problem with unauthorized media insertion, or media cross-confusion.
  • actions: all actions have an optional ability to also be applied to dynamic filters. All actions have the optional ability to log a message. All actions have the ability to inform external programs.

Action types of -

  • permit
  • deny (drop silently)
  • deny (with reply to non-local end)
  • replies: replies can be any SIP message in the 3xx, 4xx, 5xx, or 6xx fields as noted by http://www.iana.org/assignments/sip-parameters. Note that 3xx replies need to be able to contain different redirection pointers to allow load shedding.

Sample configuration file

[general]
; blah blah blah
;
; flush old rules - should be done here? specifiable?

; How often do we write out rules to astdb? In seconds.
astdb-inteval=20

; stanzas can be of two "types" - "filter" or "action"

[keys]
; maybe we put in this file the lists of all the certs that
;  we use elsewhere in Asterisk as a centralized config.
;

[filterA]
type=filter
;
;
; src-range - an IP address range, in CIDR notation, which describes
;  the origins of an IP packet.  One IP address range per line,
;  though there can be multiple lines describing address ranges.
;  IP addresses specified without CIDR notation will be interpreted
;  as /32 ranges automatically.
;
src-range=128.0.0.0/8
src-range=124.0.0.0/8
;
;
; dst-range - an IP address range, in CIDR notation, which describes
;  the destination of an IP packet.  One IP address range per line,
;  though there can be multiple lines describing address ranges.
;  IP addresses specified without CIDR notation will be interpreted
;  as /32 ranges automatically.
;  **IF NO DST-RANGE IS SPECIFIED, ASTERISK WILL ALWAYS CREATE A
;  LIST OF /32's DESCRIBING ALL IP ADDRESSES LOCAL TO THE SYSTEM** 
;  (excluding localhost.)  If you create a dst-range, be careful to 
;  specifically include all your interfaces otherwise only the specified
;  dst-range will be used.  This also means if you create a filter that
;  is for some reason incomplete, it will fire for an unpredictably large
;  number of packets since they will all match at least one of your
;  interfaces as a destination.
;
;dst-range=10.0.0.0/8
;
;
; Proto is the protocol of the packets.  Currently, only TCP and UDP
;  are supported since those are the only protocols Asterisk should
;  be seeing!
;
proto=UDP,TCP
;
;
; Port ranges.  Can be single integers (0-65535), ranges,
;  or a comma delimited list of both.  There can be multiple
;  ports descriptions, which are accretive.
;
ports=5060-5062,50600
;
;
; Deep packet data.
;
; authentication-name is the username or authentication identifier
;  that is used in the authentication portion of the protocol being
;  used.  
;     SIP: This is the Contact: name to the left of the @ sign
;    IAX2: This is username IE in the start of the session.
;    H323: This is **blah in the **blah.
;    SCCP: This is **blah in the **blah.
;     AMI: This is the Username: portion of the AMI auth transaction.
;  Note that using authentication-name is more computationally intensive,
;   since the packet reaches the channel driver and has to be examined after
;   what is often a "half-authentication" process.
;  Special keyword: you can specify the special username of "^ANY" which 
;   will create a dynamic list of authentication names over the time-interval
;   you specify in the filter (see below.)  This means that you can try to
;   catch brute-force attackers who are attacking particular 
;authentication-name=alice
;

;
;
; Volumes.  While simple packet filters may be used, additional more complex
;  algorithms can be invoked as additional trigger methods included in filters.
;  These are sometimes related specifically to channel-types, or sometimes
;  they are more generic.  

signaling packets per second
initiations or commands per second
    manager commands
    usernames on SIP, IAX2, ami, etc.
    INVITE, UPDATE, REGISTERs, etc (see iana methods list)
    IAX2 new session requests
    IAX2 message elements
    H.323 new call requests
    XMPP messaging requests
    MGCP
    http server
    SCCP
    
media mapping (include unmapping rule, include nostore options)
initiation connection failures:
    usernames on SIP, IAX2, ami, etc.
    bad call creations per second
    bad TCP socket connections
    bad TCP/TLS socket connections (bad keys, no data, etc?)
bad auth per second
    bad username/password for manager
    bad key exchanges for TLS
    bad http-digest exchange for SIP
    bad password on IAX
bad packets per second
    malformed packets on SIP, IAX, H.323, etc.



[actionB]
; 
; Set the type to "action" to specify that this is something that 
;  describes a set of things to do.  
;
type=action
;
; actions can be:
;  accept
;  drop
;  drop-response
;
; "accept" will allow the packet through unmodified.
; "drop" will deny the packet, and send no message back
;   to the originator.
; "drop-response" will send a message
;
action=drop-response
;
;
; drop-method describes how packets are dropped. There are various
;  ways to select packets to drop, ranging from completely dropping
;  all packets, to 
drop-method=

;
; sip-drop-response
; 
; This describes the specific behaviors we can have SIP use to 
;  respond to action requests.  Each protocol has its own set of
;  specific response capabilities.
; 
; The global variable $SIP-DROP-RESPONSE can be used here, in
;  case your system has some logic that gets executed in dialplans
;  that would set that value from time to time.  This could be
;  used to set a different failover/load shedding system destination
;  via a 3xx reply.
;
; NOTE: Some 3xx replies are handled specially if specified.  They will look
;  at the value stored in sip-drop-response in a special way, as described
;  below. Note that the "sip-drop-response-msg" message will take precedence over a
;  global variable $SIP-DROP-RESPONSE-MSG which can be used to semi-dynamically
;  change the forwarding destination.
;
;    301=Moved Permanently.  If you include a full URI (i.e.: "alice@foo.com")
;         then that full URI is what will be sent back as the Contact.  If you
;         only include a domain portion, the original user from the INVITE will 
;         be filled in to the Contact: with the new domain as the suffix.
;    301=Moved Permanently.  If you include a full URI (i.e.: "alice@foo.com")
;         then that full URI is what will be sent back as the Contact.  If you
;         only include a domain portion, the original user from the INVITE will 
;         be filled in to the Contact: with the new domain as the suffix.
;    305=Use Proxy.  Include only a domain name of a new proxy.
;    380=Alternative Service.  Include only a domain name of a new proxy.
;
sip-drop-response=305
sip-drop-response-msg=poor-impulse-control@floodproof.domain.net




; ext-action - External Action
;  syntax: command name
;  example: /bin/sh my-iptables-script.sh
;
; The ext-action identifier allows various external programs
;  to be informed of events and then to act on those events
;  as necessary.  This may be something like a script that calls
;  an entry into iptables, or perhaps creates an ACL on some
;  more sophisticated off-platform firewall component.
;
; These are the elements that are written out to the
;  system call.  These are filled in by the Asterisk security
;  event system.  Your script/application can listen to or 
;  ignore the fields as necessary.
;
;  ARG1 = IP address of violation origin/filter request (includes CIDR netmask)
;  ARG2 = destination IP address of violation origin/filter request (includes CIDR netmask)
;  ARG3 = port destination of violation packet
;  ARG4 = prototype of violation packet (TCP, UDP)
;  ARG5 = action as reported by internal Asterisk modules (ACCEPT, DROP)
;  ARG6 = number of iterations that has triggered pattern match 
;  ARG7 = duration expectation of action (0 for infinite)
;  ARG8 = interface name of reporting interface (i.e.: eth0, eth1, etc.)
;  ARG9 = longint counter which is incremented by +1 every time ext-action is called
;
ext-action="iptables -A INPUT -s ${ARG1} -j DROP"
;
; Other examples:
;ext-action="iptables -A INPUT -p ${ARG4} -s ${ARG1} --dport ${ARG3} -m limit --limit 10/min -j ACCEPT;  iptables -A INPUT -p ${ARG4} -s ${ARG1} --dport ${ARG3} -j DROP"
;
; Which translates to this in a situation where 172.16.3.2 on SIP is the attacker:
;  iptables -A INPUT -p UDP -s 172.16.3.2/32 --dport 5060 -m limit --limit 10/min -j ACCEPT;  iptables -A INPUT -p UDP -s 172.16.3.2/32 --dport 5060 -j DROP
;
; logging







[filterC]
; filters are parsed in order, like with the dialplan.  
; 
; Each filter includes:
;  pattern - what is being matched?
;  action  - what is done when a match is made?
;  logging - what is the notification method?

include=filterC
include=actionB

logging constantly, logging on first, logging on interval?

possibly include pcap output



; Additional CLI commands
;
; 

  • No labels