[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