Commits

ddpbsd committed b58a63b Merge

Update from upstream.

Comments (0)

Files changed (9)

docs/manual/output/database-output.rst

 These configurations options can be specified in the server or local install ossec.conf file.
 
 
-.. include:: ../../syntax/ossec_config.database_output.rst 
+.. include:: ../../syntax/ossec_config.database_output.trst 
 
 
 Enabling Database Support

docs/manual/output/granular-email-output.rst

 
 Granular to many E-Mail addresses 
-=================================
+============================
 
 OSSEC allows very granular options for the e-mail alerting and its format (full or SMS).
 
     section of the configuration or no emails will be sent at all.
 
 
+
+
+Example 1: Group alerts 
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to e-mail *xx@y.z* for every event in the group syslog you can add the following to ossec
+
+
+.. code-block:: xml
+
+    <email_alerts>
+        <email_to>xx@y.z</email_to>
+        <group>syslog</group>
+    </email_alerts>
+
+Example 2: Message Format 
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To e-mail (in the SMS format) *aa@y.z* for every event with severity higher than 10
+
+.. note::
+
+    Note that the SMS format is not grouped, so the e-mail is sent immediately).
+
+.. code-block:: xml
+
+    <email_alerts>
+        <email_to>aa@y.z</email_to>
+        <level>10</level>
+        <format>sms</format>
+    </email_alerts>
+
+Example 3: Email based on Rule ID's
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To e-mail *bb@y.z* for every event from rule 123 or rule 124 (without grouping):
+
+.. code-block:: xml 
+     <email_alerts>
+         <email_to>bb@y.z</email_to>
+         <rule_id>123, 124</rule_id>
+         <do_not_delay />
+         <do_not_group />
+     </email_alerts>
+
+Example 4: Email based on severity and agent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To e-mail *cc@y.z* for every event with severity higher than 12, from agent qwert or agt1, without any delay (immediately):=====
+
+.. code-block:: xml
+
+    <email_alerts>
+        <email_to>cc@y.z</email_to>
+        <level>12</level>
+        <event_location>qwerty|agt1</event_location>
+        <do_not_delay />
+    </email_alerts>
+
+Example 5: Multiple granular options together=====
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can have as many granular options as you want. In this example, we want the following:
+
+* Email cc@y.z for every alert from agents qwerty and agt1
+* Email john@y.z for every alert from agent secsys, lowsys and aixsys
+* Email mike@y.z for every alert from /log/secure (from any agent)
+* Email l@y.z for every alert from 192.168.0.0/24 network
+* Email boss@y.z for every alert above level 10.
+
+
+.. code-block:: xml 
+
+    <ossec_config>
+        <email_alerts>
+            <email_to>cc@y.z</email_to>
+            <event_location>qwerty|agt1</event_location>
+        </email_alerts>
+
+        <email_alerts>
+            <email_to>john@y.z</email_to>
+            <event_location>secsys|lowsys|aixsys</event_location>
+        </email_alerts>
+
+        <email_alerts>
+            <email_to>mike@y.z</email_to>
+            <event_location>/log/secure$</event_location>
+        </email_alerts>
+
+        <email_alerts>
+            <email_to>l@y.z</email_to>
+            <event_location>192.168.</event_location>
+        </email_alerts>
+
+        <email_alerts>
+            <email_to>boss@y.z</email_to>
+            <level>12</level>
+        </email_alerts>
+    </ossec_config>
+
+

docs/manual/output/syslog-output.rst

 Syslog output allows you to send the OSSEC alerts to one or more syslog servers
 (granularly).
 
+Configuration options
+---------------------
+
+These configurations options can be specified in the server or local install ossec.conf file.
+
+.. include:: ../../syntax/ossec_config.syslog_output.trst 
+
+Enable Database output in the configuration
+------------------------------------------
+
+
 You can configure OSSEC with the syslog servers of your choice. In my example
 here, I am sending everything to server 192.168.4.1 and only the alerts above
 level 10 to 10.1.1.1:

docs/manual/rules-decoders/create-custom.rst

+.. _manual_rules_decoder_custom:
+
+.. note:: 
+    
+    This page orgianl was created by @j_hen on her blog http://jentalkstoomuch.blogspot.com/2010/09/writing-custom-ossec-rules-for-your.html
+
+
+Create Custom decoder and rules 
+===============================
+
+OSSEC monitors system logs, checks for rootkits and system configuration changes, 
+and does a pretty good job of letting us know what's happening on our systems. 
+OSSEC provides a slew of helpful components and rules for commonly-used services, 
+but of course, it can't parse our custom log files out-of-the-box. While 
+setting our custom rules up, I thought I'd go ahead and document the process, 
+as I was having trouble finding a comprehensive beginning-to-end tutorial (this 
+will also help me when I forget it later, of course).
+
+Add the log files you want to monitor to ossec.conf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Open up ``/var/ossec/etc/ossec.conf`` and, near the end of the file (before 
+``</ossec_config>``), add the following:
+
+.. code-block:: xml 
+
+    <localfile>
+      <log_format>syslog</log_format>
+      <location>/var/log/my_app_log.log</location>
+    </localfile>
+
+I used syslog here as it's recommended for log files that have one entry per line. 
+Available values for log_format are syslog, snort-full, snort-fast, squid, iis, 
+eventlog (for Windows event logs), mysql_log, postgresql_log, nmapg or apache.
+
+If you're monitoring log files that contain changeable dates, OSSEC understands 
+strftime variables, so, for example, if your log file is 
+``/var/log/apache2/access.log.2010-09-25``, you can set location to 
+``<location>/var/log/apache2/access.log.%Y-%m-%d.``
+
+.. note:: 
+    You can render a strftime variable at the command line to verify it quickly. Just 
+    type ``date +%X`` at the command line, where X is the stftime variable. ``date +%Y-%m-%d``
+    gives us the string we need for our access logs, ``date +%s`` gives us Epoch time UTC.
+
+
+Create a custom decoder
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
+OSSEC uses decoders to parse log files. After it finds the proper decoder for a log, it 
+will parse out fields defined in ``/var/ossec/etc/decoders.xml``, then compare these values 
+to values in rule files - and will trigger an alert when values in the deciphered log 
+file match values specified in rule files. These values can also be passed to 
+active-response commands, if you've got them enabled.
+
+The log line I want to trigger an alert for looks something like this: ::
+
+    2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!
+
+
+Open up ``/var/ossec/etc/local_decoder.xml`` (you can also use ``decoder.xml``, which 
+already exists, but using ``local_decoder.xml`` will assure that you don't overwrite 
+it on upgrade). First, we want to create a decoder that will match the first part of 
+the log entry. We'll use the date and first few characters to grab it using a regular 
+expression. 
+
+.. note::
+
+    Note that OSSEC has its own sort of interpretation of regex, so don't try to get fancy. 
+    I spent a lot of time pulling my hair out after using \d{4} type regex syntax - think 
+    simpler and you'll have more success: you have to use \d\d\d\d instead.
+
+In the following decoder, we start at the beginning of the line (^), then match the digits 
+in YYYY-MM-DD HH:MM:SS. After the date and time, I may have a few different log levels 
+listed, INFO, WARN, DEBUG, etc., so I'll just match any number of characters greater 
+than 0 (\w+). We also want to end on something relatively unique since the log level 
+regex I used is so loosy-goosy, and I know this is a ForceField alert and all ForceField 
+alerts will contain ForceField, so I'll use the following.
+
+.. code-block:: xml
+
+    <decoder name="forcefield">
+      <prematch>^\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d \w+ ForceField</prematch>
+    </decoder>
+
+Let's take a break here, and see if this triggers our alert. Save and exit ``local_decoder.xml``, 
+then run ``/var/ossec/bin/ossec-logtest``.
+
+When it comes up, paste your log line: ::
+
+    2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield
+
+    **Phase 1: Completed pre-decoding.
+    full event: '2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!'
+    hostname: 'my_system'
+    program_name: '(null)'
+    log: '2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!'
+    **Phase 2: Completed decoding.
+    decoder: 'forcefield'
+
+You should see forcefield show up as the decoder. Great! Now, let's parse out the values 
+we care about.
+
+Re-open ``local_decoder.xml`` and, beneath your forcefield decoder, create a new decoder:
+
+.. code-block:: xml 
+
+    <decoder name="forcefield-alert">
+      <parent>forcefield</parent>
+      <regex offset="after_parent">IP:(\d+.\d+.\d+.\d+)@(\w+): (forcefield \w+); (\.*)</regex>
+      <order>srcip,url,action,extra_data</order>
+    </decoder>
+
+So, what'd we do here?
+
+The obvious stuff first: We gave it a name, and designated forcefield-alert as a child of 
+forcefield. Whenever a log matches the forcefield decoder, it'll then be decoded using 
+forcefield-alert to extract the data fields to match on.
+
+Now for the fun stuff...First, we set the offset to "``after_parent``" - this means that 
+OSSEC starts looking for matches after the 'prematch' stuff (date, time, & ForceField) 
+we specified inside the parent forcefield.
+
+So our log line actually looks like this: ::
+
+    2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!
+
+But after extracting the pre-match data, our log line, in OSSEC's brain, looks like this: ::
+
+    IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!
+
+So what do we care about? What fields do we want to test again? A good rule is to decode 
+any data that you want to match inside a rule as well as any data you might need to 
+initiate an active response. I set these items to bold below: ::
+
+    IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!
+
+OSSEC only allows specific field definitions. These can be found at the top of the 
+``local_decoder.xml`` file. For the purposes of our log file, we'll want the IP, 
+the script, the action taken by the system, and the additional data. 
+
+When creating the regex for OSSEC, we extract all data inside parenthesis, so we 
+build our regex like this: ::
+
+    IP:(\d+.\d+.\d+.\d+)@(\w+): (forcefield \w+); (\.*)
+
+Then, to specify which parenthetical regex is which field, you add the ``<order>`` line, 
+using available fields in decoders.xml:
+
+.. code-block:: xml 
+
+    <order>srcip,url,action,extra_data</order>
+
+Save your local_decoder.xml and let's run the log file through ossec-logtest again.
+
+.. code-block:: sh 
+
+    ossec-testrule: Type one log per line.
+    2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!
+    **Phase 1: Completed pre-decoding.
+    full event: '2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!'
+    hostname: 'my_system'
+    program_name: '(null)'
+    log: '2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!'
+    **Phase 2: Completed decoding.
+    decoder: 'forcefield'
+    srcip: '127.0.0.1'
+    url: 'script_x'
+    action: 'forcefield on'
+    extra_data: 'enabled forcefield arbitrarily!'
+
+Looks good! It found our decoder and extracted the fields the way we want 'em. Now, 
+we're ready to write local rules.
+
+Write custom rules
+~~~~~~~~~~~~~~~~~~
+
+Open ``/var/ossec/local_rules.xml`` and add rules. First, we create a group, and a 
+"catch-all" rule to run against any log that is decoded by our forcefield decoder. We set 
+this as level 0 because we don't want it to trigger an alert:
+
+.. code-block:: xml
+
+    <group name="forcefield">
+        <rule id="700005" level="0">
+            <decoded_as>forcefield</decoded_as>
+            <description>Custom Forcefield Alert</description>
+        </rule>
+    </group>
+
+Next, we add dependent rules that trigger if the action matches what's specified in the rule. 
+<if_sid> specifies the dependency:
+
+.. code-block:: xml 
+
+    <group name="forcefield">
+        <rule id="700005" level="0">
+            <decoded_as>forcefield</decoded_as>
+            <description>Custom Forcefield Alert</description>
+        </rule>
+        <!-- Alert if forcefield enabled -->
+        <rule id="700006" level="12">
+            <if_sid>700005</if_sid>
+            <action>forcefield on</action>
+            <description>Forcefield enabled!</description>
+        </rule>
+        <!-- Alert if forcefield disabled -->
+            <rule id="700007" level="7">
+            <if_sid>700005</if_sid>
+            <action>forcefield off</action>
+            <description>Forcefield off!</description>
+        </rule>
+        <rule id="700008" level="14">
+            <if_sid>700005</if_sid>
+            <action>forcefield hyperdrive</action>
+            <description>Forcefield in hyperdrive, watch out!</description>
+        </rule>
+    </group>
+
+Save your local_rules.xml file, and let's test it again:
+
+.. code-block:: sh 
+
+    ossec-testrule: Type one log per line.
+    2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!
+    **Phase 1: Completed pre-decoding.
+    full event: '2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!'
+    hostname: 'my_system'
+    program_name: '(null)'
+    log: '2010-09-25 15:28:42 WARN ForceField IP:127.0.0.1@script_x: forcefield on; enabled forcefield arbitrarily!'
+    **Phase 2: Completed decoding.
+    decoder: 'forcefield'
+    srcip: '127.0.0.1'
+    url: 'script_x'
+    action: 'forcefield on'
+    extra_data: 'enabled forcefield arbitrarily!'
+    **Phase 3: Completed filtering (rules).
+    Rule id: '700006'
+    Level: '12'
+    Description: 'Forcefield enabled!'
+    **Alert to be generated.
+
+Cool - now we're ready to restart OSSEC and check alerts. When restarting OSSEC, you 
+may find that the new log file that you're using should exist before you restart 
+OSSEC--if it doesn't find it, it ignores it. Also, when writing your own rules, 
+set levels specific to your OSSEC deployment - for example, if you've enabled active 
+response and want to trigger it, make sure you extract the srcip using your decoder 
+and set the level in the rule to match the level specific to your active response 
+command in ossec.conf.
+
+You'll probably find that you need to do some tuning, and that some of the alerts you 
+receive will trigger unwanted alerts if they fall through the decoder sieve. I haven't 
+figured out a way to exclude the file from inspection if it fails to match any decoder 
+(if you know of one, let me know!), but the solution I've used is to create a new local 
+rule that matches based on the syslog sid and match, like so:
+
+.. code-block:: xml 
+
+    <rule id="100009" level="0">
+        <if_sid>1002</if_sid>
+        <match>Some string in the log I don't want to see</match>
+        <description>Don't syslog alert on this one</description>
+    </rule>
+
+Repeat for each false positive. It'd be really useful to only allow a single decoder to 
+work on a log file - if anyone knows how to do that, let me know!
+

docs/manual/rules-decoders/index.rst

 
     testing
     rule-lists
+    create-custom
+    rule_decoder_dir

docs/manual/rules-decoders/rule_decoder_dir.rst

+.. _manual_rule_decoder_dir:
+
+Directory path loading of rules and decoders
+============================================
+
+To allow whole directories of files to be loaded as decoders, lists, or rules
+by ossec-anaylistd.
+
+Use case
+--------
+
+Great simplifies working with decoders as their can be as many files as needed.
+Also will make packaging of rules and decoders a simple unzip/untar and restart
+operations. This will also greatly reduce the amount of code needed to manage
+the upgrade scripts of ossec.
+
+Details
+-------
+
+Syntax for OSSEC
+~~~~~~~~~~~~~~~~
+
+All Directory loading is done in alphabetical form. This is much like init.d
+where the use of numeric prefixes on file names can effect the order of
+loading. Example of file names and the order they would be loaded:
+
+#. 00_sshd_rules.xml
+#. 01_local_sshd_rules.xml
+#. 99_shun_rules.xml
+
+Directory loading 
+^^^^^^^^^^^^^^^^^
+
+The basic for selection of rules file is as follows. This will load all files in
+the rules dir that match the regex ``_rules.xml$``
+
+.. code-block:: xml
+
+    <ossec_config>
+        <rules>
+            <rules_dir pattern="_rules.xml">rules</rules_dir>
+
+The pattern is optional and defaults to _rules.xml for rules loading so this
+could be writen as:
+
+.. code-block:: xml 
+
+    <ossec_config>
+        <rules>
+            <rules_dir>rules</rules_dir>
+
+Order of the directives in ossec.conf is still respected, and duplicate files
+will not be loaded. In the following example 00_setup_rules.xml is always
+loaded first, and will *NOT* be loaded a second time by the rules_dir
+directive.
+
+.. code-block:: xml 
+
+    <ossec_config>
+        <rules>
+            <include>rules/00_setup_rules.xml</include>
+            <rules_dir>rules</rules_dir>
+
+For full details on all the Syntax see :xml:`rule_dir` and :xml:`decoder_dir`
+
+Compete Examples of syntax 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an example where the decoders and rules have been broken out into
+subdirectories.
+
+* rules/ 
+
+    * 00_rules_config.xml 
+    * 50_apache_rules.xml
+    * 50_arpwatch_rules.xml
+    * plugins/ 
+
+        * 50_wimax_rules.xml
+        * 50_wimax_decoders.xml 
+
+* etc/
+
+    * decoder.xml 
+    * local_decoder.xml 
+
+
+.. code-block:: xml 
+
+    <ossec_config>
+        <rules>
+            <decoder>etc/decoder.xml</decoder>
+            <decoder_dir>rules/plugins</decoder_dir>
+
+            <rule>rules/rules/00_rules_config.xml</rule>
+            <rules_dir pattern=".xml$">rules/</rules_dir>
+            <rules_dir>rules/plugins</rules_dir>
+        </rules>  
+    </ossec_config>
+
+        
+
+

docs/syntax/head_ossec_config.rules.rst

 Options
 -------
 
-.. include:: ossec_config.rules.rst 
+.. include:: ossec_config.rules.trst 

docs/syntax/head_ossec_config.syslog_output.rst

+
+.. _ossec_config.syslog_output: 
+
+ossec.conf: Syslog Output options
+=================================
+
+Overview 
+--------
+
+Supported types 
+^^^^^^^^^^^^^^^
+
+Database Output options are available in the the following installation types:
+
+* server
+* local 
+
+Location 
+^^^^^^^^
+
+All syslog_output options must be configured in the /var/ossec/etc/ossec.conf 
+and used within the <ossec_config> tag.  
+
+XML excerpt to show location:
+
+.. code-block:: xml 
+
+    <ossec_config> 
+        <syslog_output> 
+            <!-- 
+            Database Output options here
+            --> 
+        </syslog_output> 
+    </ossec_config> 
+
+
+Options
+-------
+
+.. include:: ossec_config.syslog_output.trst 

docs/syntax/ossec_config.syslog_output.trst

+
+.. xml:element:: syslog_output 
+
+
+.. xml:element:: syslog_output.server
+
+    IP Address of the syslog server. 
+
+    **Allowed:** any valid IP address 
+
+.. xml:element:: syslog_output.level
+
+    Alert level of the alerts to forward
+
+    **Allowed:** 1 - 16 
+