[asterisk-commits] russell: branch group/security_events r200768 - in /team/group/security_event...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Mon Jun 15 20:33:58 CDT 2009


Author: russell
Date: Mon Jun 15 20:33:55 2009
New Revision: 200768

URL: http://svn.asterisk.org/svn-view/asterisk?view=rev&rev=200768
Log:
Move documentation into the tex docs as a new chapter

Added:
    team/group/security_events/doc/tex/security-events.tex   (with props)
Removed:
    team/group/security_events/security_events.txt
Modified:
    team/group/security_events/doc/tex/asterisk.tex
    team/group/security_events/doc/tex/channelvariables.tex

Modified: team/group/security_events/doc/tex/asterisk.tex
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/security_events/doc/tex/asterisk.tex?view=diff&rev=200768&r1=200767&r2=200768
==============================================================================
--- team/group/security_events/doc/tex/asterisk.tex (original)
+++ team/group/security_events/doc/tex/asterisk.tex Mon Jun 15 20:33:55 2009
@@ -32,7 +32,7 @@
 
 
 \author{Asterisk Development Team \\ Asterisk.org}
-\title{Asterisk Reference Information \\ Version ASTERISKVERSION}
+\title{Asterisk Reference Information \\ Version SVN-group-security\_events-r200704M-/trunk}
 
 \begin{document}
 \maketitle
@@ -138,6 +138,9 @@
 \chapter{Calendaring}
   \input{calendaring.tex}
 
+\chapter{Asterisk Security Framework}
+  \input{security-events.tex}
+
 \chapter{Development}
   \section{Backtrace}
   \input{backtrace.tex}

Modified: team/group/security_events/doc/tex/channelvariables.tex
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/security_events/doc/tex/channelvariables.tex?view=diff&rev=200768&r1=200767&r2=200768
==============================================================================
--- team/group/security_events/doc/tex/channelvariables.tex (original)
+++ team/group/security_events/doc/tex/channelvariables.tex Mon Jun 15 20:33:55 2009
@@ -1012,3 +1012,4 @@
 ${CONNECTED_LINE_SEND_CALLEE_MACRO_ARGS}   Arguments to pass to ${CONNECTED_LINE_SEND_CALLEE_MACRO}
 ${CONNECTED_LINE_SEND_CALLER_MACRO}        Macro to call before sending a connected line update to the caller
 ${CONNECTED_LINE_SEND_CALLER_MACRO_ARGS}   Arguments to pass to ${CONNECTED_LINE_SEND_CALLER_MACRO}
+\end{verbatim}

Added: team/group/security_events/doc/tex/security-events.tex
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/security_events/doc/tex/security-events.tex?view=auto&rev=200768
==============================================================================
--- team/group/security_events/doc/tex/security-events.tex (added)
+++ team/group/security_events/doc/tex/security-events.tex Mon Jun 15 20:33:55 2009
@@ -1,0 +1,250 @@
+\section{Introduction}
+
+   Attacks on Voice over IP networks are becoming increasingly more common.  It
+has become clear that we must do something within Asterisk to help mitigate
+these attacks.
+
+   Through a number of discussions with groups of developers in the Asterisk
+community, the general consensus is that the best thing that we can do within
+Asterisk is to build a framework which recognizes and reports events that could
+potentially have security implications.  Each channel driver has a different
+concept of what is an "event", and then each administrator has different
+thresholds of what is a "bad" event and what is a restorative event.  The
+process of acting upon this information is left to an external program to
+correlate and then take action - block traffic, modify dialing rules, etc.  It
+was decided that embedding actions inside of Asterisk was inappropriate, as the
+complexity of construction of such rule sets is difficult and there was no
+agreement on where rules should be enabled or how they should be processed.  The
+addition of a major section of code to handle rule expiration and severity
+interpretation was significant.  As a final determining factor, there are
+external programs and services which already parse log files and act in concert
+with packet filters or external devices to protect or alter network security
+models for IP connected hosts.
+
+\section{Framework Overview}
+
+    This section discusses the architecture of the Asterisk modifications being
+proposed.
+
+    There are two main components that we propose for the initial
+implementation of the security framework:
+
+\begin{itemize}
+    \item Security Event Generation
+    \item Security Event Logger
+\end{itemize}
+
+\subsection{Security Event Generation}
+
+    The ast\_event API is used for the generation of security events.  That
+way, the events are in an easily interpretable format within Asterisk to
+make it easy to write modules that do things with them.  There are also some
+helper data structures and functions to aid Asterisk modules in reporting these
+security events with the proper contents.
+
+    Section 3 of this document contains the current list of security events
+being proposed.  Each security event type has some required pieces of
+information and some other optional pieces of information.
+
+    Subscribing to security events from within Asterisk can be done by
+subscribing to events of type AST\_EVENT\_SECURITY.  These events have an
+information element, AST\_EVENT\_IE\_SECURITY\_EVENT, which identifies the security
+event sub-type (from the list described in section 3).  The result of the
+information elements in the events contain the required and optional meta data
+associated with the event sub-type.
+
+\subsection{Security Event Logger}
+
+    In addition to the infrastructure for generating the events, one module that
+is a consumer of these events has been implemented.
+
+    Asterisk trunk was recently updated to include support for dynamic logger
+channels.  This module takes advantage of this functionality to create a
+custom "security" logger channel.  Then, when this module is in use, logger.conf
+can configured to put security events into a file:
+
+\begin{verbatim}
+    security_log => security
+\end{verbatim}
+
+    The content of this file are a well defined and easily interpretable
+format for external scripts to read and act upon.  The definition for the format
+of the log file is the subject of Section 4 of this document.
+
+\section{Events to Log}
+
+\begin{verbatim}
+(-) required
+(+) optional
+
+Invalid Account ID
+  (-) Local address family/IP/addr/port/transport
+  (-) Remote address family/IP/addr/port/transport
+  (-) Service (SIP, AMI, IAX2, ...)
+  (-) System Name
+  (+) Module
+  (+) Account ID (username, etc)
+  (+) Session ID (CallID, etc)
+  (+) Session timestamp (required if Session ID present)
+  (-) Event timestamp (sub-second precision)
+
+Failed ACL match
+  -> everything from invalid account ID
+  (+) Name of ACL (when we have named ACLs)
+
+Invalid Challenge/Response
+  -> everything from invalid account ID
+  (-) Challenge
+  (-) Response
+  (-) Expected Response
+
+Invalid Password
+  -> everything from invalid account ID
+
+Successful Auth
+  -> informational event
+  -> everything from inval account ID
+
+Invalid formatting of Request
+  -> everything from inval account ID
+  -> account ID optional
+  (-) Request Type
+  (+) Request parameters
+
+Session Limit Reached (such as a call limit)
+  -> everything from inval account ID
+
+Mem Limit Reached
+  -> everything from inval account ID
+
+Max Load Avg Reached
+  -> everything from inval account ID
+
+Request Not Allowed
+  -> everything from inval account ID
+  (-) Request Type
+  (+) Request parameters
+
+Request Not Supported
+  -> everything from inval account ID
+  (-) Request Type
+
+Auth Method Not Allowed
+  -> everything from inval account ID
+  (-) Auth Method attempted
+
+In dialog message from unexpected host
+  -> everything from inval account ID
+  (-) expected host
+\end{verbatim}
+
+\section{Security Log File Format}
+
+    The beginning of each line in the log file is the same as it is for other
+logger channels within Asterisk.
+
+\begin{verbatim}
+    [Feb 11 07:57:03] SECURITY[23736] res_security_log.c: <...>
+\end{verbatim}
+
+    The part of the log entry identified by <...> is where the security event
+content resides.  The security event content is a comma separated list
+of key value pairs.  The key is the information element type, and the value is a
+quoted string that contains the associated meta data for that information
+element.  Any embedded quotes within the content are escaped with a
+backslash.
+
+\begin{verbatim}
+    INFORMATION_ELEMENT_1="IE1 content",INFORMATION_ELEMENT_2="IE2 content"
+\end{verbatim}
+
+The following table includes potential information elements and what the
+associated content looks like:
+
+\begin{verbatim}
+IE: SecurityEvent
+Content: This is the security event sub-type.
+Values: FailedACL, InvalidAccountID, SessionLimit, MemoryLimit, LoadAverageLimit,
+        RequestNotSupported, RequestNotAllowed, AuthMethodNotAllowed,
+        ReqBadFormat, UnexpectedAddress, ChallengeResponseFailed,
+        InvalidPassword
+
+IE: EventVersion
+Content: This is a numeric value that indicates when updates are made to the
+         content of the event.
+Values: Monotonically increasing integer, starting at 1
+
+IE: Service
+Content: This is the Asterisk service that generated the event.
+Values: TEST, SIP, AMI
+
+IE: Module
+Content: This is the Asterisk module that generated the event.
+Values: chan_sip
+
+IE: AccountID
+Content: This is a string used to identify the account associated with the
+         event.  In most cases, this would be a username.
+
+IE: SessionID
+Content: This is a string used to identify the session associated with the
+         event.  The format of the session identifier is specific to the
+         service.  In the case of SIP, this would be the call ID.
+
+IE: SessionTV
+Content: The time that the session associated with the SessionID started.
+Values: <seconds>-<microseconds> since epoch
+
+IE: ACLName
+Content: This is a string that identifies which named ACL is associated with
+         this event.
+
+IE: LocalAddress
+Content: This is the local address that was contacted to for the related event.
+Values: <Address Family>/<Transport>/<Address>/<Port>
+Examples:
+     -> IPV4/UDP/192.168.1.1/5060
+     -> IPV4/TCP/192.168.1.1/5038
+
+IE: RemoteAddress
+Content: This is the remote address associated with the event.
+Examples:
+     -> IPV4/UDP/192.168.1.2/5060
+     -> IPV4/TCP/192.168.1.2/5038
+
+IE: ExpectedAddress
+Content: This is the address that was expected to be the remote address.
+Examples:
+     -> IPV4/UDP/192.168.1.2/5060
+     -> IPV4/TCP/192.168.1.2/5038
+
+IE: EventTV
+Content: This is the timestamp of when the event occurred.
+Values: <seconds>-<microseconds> since epoch
+
+IE: RequestType
+Content: This is a service specific string that represents the invalid request
+
+IE: RequestParams
+Content: This is a service specific string that represents relevant parameters
+         given with a request that was considered invalid.
+
+IE: AuthMethod
+Content: This is a service specific string that represents an authentication
+         method that was used or requested.
+
+IE: Challenge
+Content: This is a service specific string that represents the challenge
+         provided to a user attempting challenge/response authentication.
+
+IE: Response
+Content: This is a service specific string that represents the response
+         received from a user attempting challenge/response authentication.
+
+IE: ExpectedResponse
+Content: This is a service specific string that represents the response
+         that was expected to be received from a user attempting 
+         challenge/response authentication.
+
+\end{verbatim}
+

Propchange: team/group/security_events/doc/tex/security-events.tex
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/group/security_events/doc/tex/security-events.tex
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/group/security_events/doc/tex/security-events.tex
------------------------------------------------------------------------------
    svn:mime-type = text/plain




More information about the asterisk-commits mailing list