core: Remove disabled code.
[asterisk/asterisk.git] / README-SERIOUSLY.bestpractices.txt
index 15c117c..0d3e670 100644 (file)
@@ -4,25 +4,31 @@
 
 The purpose of this document is to define best practices when working with
 Asterisk in order to minimize possible security breaches and to provide tried
-examples in field deployments. This is a living document and is subject to 
+examples in field deployments. This is a living document and is subject to
 change over time as best practices are defined.
 
 --------
 Sections
 --------
 
-* Filtering Data: 
+* Filtering Data:
         How to protect yourself from redial attacks
 
-* Proper Device Naming: 
+* Proper Device Naming:
         Why to not use numbered extensions for devices
 
-* Secure Passwords: 
+* Secure Passwords:
         Secure passwords limit your risk to brute force attacks
 
-* Reducing Pattern Match Typos: 
+* Reducing Pattern Match Typos:
         Using the 'same' prefix, or using Goto()
 
+* Manager Class Authorizations:
+        Recognizing potential issues with certain classes of authorization
+
+* Avoid Privilege Escalations:
+        Disable the ability to execute functions that may escalate privileges
+
 ----------------
 Additional Links
 ----------------
@@ -33,14 +39,17 @@ security are listed below.
 * Seven Steps to Better SIP Security:
         http://blogs.digium.com/2009/03/28/sip-security/
 
+* Asterisk VoIP Security (webinar):
+        http://www.asterisk.org/security/webinar/
+
 
 ==============
 Filtering Data
 ==============
 
-In the Asterisk dialplan, several channel variables contain data potentially 
-supplied by outside sources. This could lead to a potential security concern 
-where those outside sources may send cleverly crafted strings of data which 
+In the Asterisk dialplan, several channel variables contain data potentially
+supplied by outside sources. This could lead to a potential security concern
+where those outside sources may send cleverly crafted strings of data which
 could be utilized, e.g. to place calls to unexpected locations.
 
 An example of this can be found in the use of pattern matching and the ${EXTEN}
@@ -48,14 +57,14 @@ channel variable. Note that ${EXTEN} is not the only system created channel
 variable, so it is important to be aware of where the data you're using is
 coming from.
 
-For example, this common dialplan takes 2 or more characters of data, starting 
+For example, this common dialplan takes 2 or more characters of data, starting
 with a number 0-9, and then accepts any additional information supplied by the
 request.
 
 [NOTE: We use SIP in this example, but is not limited to SIP only; protocols
        such as Jabber/XMPP or IAX2 are also susceptible to the same sort of
        injection problem.]
-       
+
 
 [incoming]
 exten => _X.,1,Verbose(2,Incoming call to extension ${EXTEN})
@@ -74,7 +83,7 @@ to dial extension 500 (which in our example above would create the string
 SIP/500 and is then used by the Dial() application to place a call), someone
 could potentially send a string like "500&SIP/itsp/14165551212".
 
-The string "500&SIP/itsp/14165551212" would then be contained within the 
+The string "500&SIP/itsp/14165551212" would then be contained within the
 ${EXTEN} channel variable, which is then utilized by the Dial() application in
 our example, thereby giving you the dialplan line of:
 
@@ -85,11 +94,18 @@ your ITSP in a place where you didn't expect to allow it. There are a couple of
 ways in which you can mitigate this impact: stricter pattern matching, or using
 the FILTER() dialplan function.
 
+The CALLERID(num) and CALLERID(name) values are other commonly used values that
+are sources of data potentially supplied by outside sources.  If you use these
+values as parameters to the System(), MixMonitor(), or Monitor() applications
+or the SHELL() dialplan function, you can allow injection of arbitrary operating
+system command execution.  The FILTER() dialplan function is available to remove
+dangerous characters from untrusted strings to block the command injection.
+
 Strict Pattern Matching
 -----------------------
 
 The simple way to mitigate this problem is with a strict pattern match that does
-not utilize the period (.) or bang (!) characters to match on one-or-more 
+not utilize the period (.) or bang (!) characters to match on one-or-more
 characters or zero-or-more characters (respectively). To fine tune our example
 to only accept three digit extensions, we could change our pattern match to
 be:
@@ -112,8 +128,8 @@ application which will contain dynamic information passed to Asterisk from an
 external source. Lets take a look at how we can use FILTER() to control what
 data we allow.
 
-Using our previous example to accept any string length of 2 or more characters, 
-starting with a number of zero through nine, we can use FILTER() to limit what 
+Using our previous example to accept any string length of 2 or more characters,
+starting with a number of zero through nine, we can use FILTER() to limit what
 we will accept to just numbers. Our example would then change to something like:
 
 [incoming]
@@ -225,21 +241,21 @@ first ones added to the dictionary for brute force attacks.
 Secure Passwords
 ================
 
-Secure passwords are necessary in many (if not all) environments, and Asterisk 
+Secure passwords are necessary in many (if not all) environments, and Asterisk
 is certainly no exception, especially when it comes to expensive long distance
 calls that could potentially cost your company hundreds or thousands of dollars
 on an expensive monthly phone bill, with little to no recourse to fight the
 charges.
 
 Whenever you are positioned to add a password to your system, whether that is
-for a device configuration, a database connection, or any other secure 
+for a device configuration, a database connection, or any other secure
 connection, be sure to use a secure password. A good example of a secure
 password would be something like:
 
 aE3%B8*$jk^G
 
 Our password also contains 12 characters with a mixture of upper and
-lower case characters, numbers, and symbols. Because these passwords are likely 
+lower case characters, numbers, and symbols. Because these passwords are likely
 to only be entered once, or loaded via a configuration file, there is
 no need to create simple passwords, even in testing. Some of the holes found in
 production systems used for exploitations involve finding the one test extension
@@ -290,3 +306,71 @@ same => n,Hangup()
 exten => error,1,Verbose(2,Unable to lookup technology or device for extension)
 same => n,Playback(silence/1&num-not-in-db)
 same => n,Hangup()
+
+
+============================
+Manager Class Authorizations
+============================
+
+Manager accounts have associated class authorizations that define what actions
+and events that account can execute/receive.  In order to run Asterisk commands
+or dialplan applications that affect the system Asterisk executes on, the
+"system" class authorization should be set on the account.
+
+However, Manager commands that originate new calls into the Asterisk dialplan
+have the potential to alter or affect the system as well, even though the
+class authorization for origination commands is "originate".  Take, for example,
+the Originate manager command:
+
+Action: Originate
+Channel: SIP/foo
+Exten: s
+Context: default
+Priority: 1
+Application: System
+Data: echo hello world!
+
+This manager command will attempt to execute an Asterisk application, System,
+which is normally associated with the "system" class authorication.  While some
+checks have been put into Asterisk to take this into account, certain dialplan
+configurations and/or clever manipulation of the Originate manager action can
+circumvent these checks.  For example, take the following dialplan:
+
+exten => s,1,Verbose(Incoming call)
+same => n,MixMonitor(foo.wav,,${EXEC_COMMAND})
+same => n,Dial(SIP/bar)
+same => n,Hangup()
+
+Whatever has been defined in the variable EXEC_COMMAND will be executed after
+MixMonitor has finished recording the call.  The dialplan writer may have
+intended that this variable to be set by some other location in the dialplan;
+however, the Manager action Originate allows for channel variables to be set by
+the account initiating the new call.  This could allow the Originate action to
+execute some command on the system by setting the EXEC_COMMAND dialplan variable
+in the Variable: header.
+
+In general, you should treat the Manager class authorization "originate" the
+same as the class authorization "system".  Good system configuration, such as
+not running Asterisk as root, can prevent serious problems from arising when
+allowing external connections to originate calls into Asterisk.
+
+===========================
+Avoid Privilege Escalations
+===========================
+
+External control protocols, such as Manager, often have the ability to get and
+set channel variables; which allows the execution of dialplan functions.
+
+Dialplan functions within Asterisk are incredibly powerful, which is wonderful
+for building applications using Asterisk. But during the read or write
+execution, certain diaplan functions do much more. For example, reading the
+SHELL() function can execute arbitrary commands on the system Asterisk is
+running on. Writing to the FILE() function can change any file that Asterisk has
+write access to.
+
+When these functions are executed from an external protocol, that execution
+could result in a privilege escalation. Asterisk can inhibit the execution of
+these functions, if live_dangerously in the [options] section of asterisk.conf
+is set to no.
+
+In Asterisk 12 and later, live_dangerously defaults to no.