Updating OSSEC Rules¶
SecureDrop uses the OSSEC open source host-based intrusion detection system (IDS) for log analysis, file integrity checking, policy monitoring, rootkit detection and real-time alerting. Refer to our OSSEC guide to learn more about how SecureDrop admins set up and monitor OSSEC alerts.
The goals of the OSSEC alerts in SecureDrop is to notify admins of:
Suspicious security events
Changes that require some kind of admin action
Other important notifications regarding system state.
If an alert is purely informational and there is no realistic action an admin is expected to take, you should think carefully before suggesting a rule for it. Each additional alert that admins must read and/or respond to takes time. Alerts that are unimportant or otherwise require no action can lead to alert fatigue and thus to critical alerts being ignored.
Development on the OSSEC rules should be done from the staging environment.
mon-staging, there is a utility installed as part of OSSEC called
ossec-logtest that you can use to test log events. In order to evaluate
whether an alert will be produced, and if so, what rule triggered it and its
level, you can simply pass the event to
root@mon-staging:/home/vagrant# sudo echo "Feb 10 23:34:40 app-prod kernel: [ 124.188641] grsec: denied RWX mmap of <anonymous mapping> by /usr/sbin/apache2[apache2:1328] uid/euid:33/33 gid/egid:33/33, parent /usr/sbin/apache2[apache2:1309] uid/euid:0/0 gid/egid:0/0" | /var/ossec/bin/ossec-logtest 2017/08/16 22:28:25 ossec-testrule: INFO: Reading local decoder file. 2017/08/16 22:28:25 ossec-testrule: INFO: Started (pid: 18973). ossec-testrule: Type one log per line. **Phase 1: Completed pre-decoding. full event: 'Feb 10 23:34:40 app-prod kernel: [ 124.188641] grsec: denied RWX mmap of <anonymous mapping> by /usr/sbin/apache2[apache2:1328] uid/euid:33/33 gid/egid:33/33, parent /usr/sbin/apache2[apache2:1309] uid/euid:0/0 gid/egid:0/0' hostname: 'app-prod' program_name: 'kernel' log: '[ 124.188641] grsec: denied RWX mmap of <anonymous mapping> by /usr/sbin/apache2[apache2:1328] uid/euid:33/33 gid/egid:33/33, parent /usr/sbin/apache2[apache2:1309] uid/euid:0/0 gid/egid:0/0' **Phase 2: Completed decoding. decoder: 'iptables' **Phase 3: Completed filtering (rules). Rule id: '100101' Level: '7' Description: 'grsec error was detected' **Alert to be generated.
This is the utility we use in automated tests of OSSEC.
Writing Automated Tests for OSSEC Rules¶
We strongly recommend before making changes to OSSEC rules to attempt to write a failing test which you then can make pass with a patch to the OSSEC rules:
Identify a log event you can use to trigger the alert.
Be sure to use only log events from test SecureDrop instances or those you have verified do not contain any sensitive data.
Write a Testinfra test to verify that the log event does or does not trigger an alert.
Apply your patch to the OSSEC rule on the relevant VM (likely
Restart the service via
sudo service ossec restarton
Adding new OSSEC rules¶
OSSEC processes events in two steps:
Decoders parse and filter log events that meet certain criteria for subsequent processing. SecureDrop’s custom rules are defined in
Rules check decoded events against conditions and optionally yield alerts. SecureDrop’s custom rules are defined in
A basic decoder filters log events by
If a decoder is already defined for the program of interest, you can go straight
to defining a new rule unless you have a reason to add additional
decoders for further filtering.
The decoder file¶
For example, to add a decoder for log events from
fwupd, you can add to
<!-- The default fwupd tries to auto-update and generates error. --> <decoder name="fwupd"> <program_name>fwupd</program_name> </decoder>
You can find this
program_name value using the “ossec-logtest” command. Copy-paste the log event as input to this command, and
it will give you some parsed output:
$ echo "Mar 1 13:22:53 app fwupd: 13:22:53:0883 FuPluginUefi Error opening directory â€œ/sys/firmware/efi/esrt/entriesâ€�: No such file or directory" | sudo /var/ossec/bin/ossec-logtest [...] **Phase 1: Completed pre-decoding. full event: 'Mar 1 13:22:53 app fwupd: 13:22:53:0883 FuPluginUefi Error opening directory â€œ/sys/firmware/efi/esrt/entriesâ€�: No such file or directory' hostname: 'app' program_name: 'fwupd' log: '13:22:53:0883 FuPluginUefi Error opening directory â€œ/sys/firmware/efi/esrt/entriesâ€�: No such file or directory' **Phase 2: Completed decoding. No decoder matched. **Phase 3: Completed filtering (rules). Rule id: '1002' Level: '2' Description: 'Unknown problem somewhere in the system.' **Alert to be generated.
Next, you can add one or more rules corresponding to the new decoder, making
sure that the rules have proper unique id numbers and are written in the
correct (sorted) place in the
<group name="fwupd"> <rule id="100111" level="0"> <decoded_as>fwupd</decoded_as> <match>Error opening directory</match> <description>fwupd error</description> <options>no_email_alert</options> </rule> <rule id="100112" level="0"> <decoded_as>fwupd</decoded_as> <match>Failed to load SMBIOS</match> <description>fwupd error for auto updates</description> <options>no_email_alert</options> </rule> </group>
Verify the new OSSEC rule¶
On the monitor server you can use the following command as root to verify the new rule:
ossec-analysisd will receive log messages and compare them to our rules,
including the new rule you just added. Then it creates alerts when a log message
matches an applicable rule.
Adding an automated test for staging¶
You can then add tests in the
file. Here the test loops over the entries in the
molecule/testinfra/vars/staging.yml and makes sure that the
level match. See Writing Automated Tests for OSSEC Rules
The OSSEC rules and associated configuration files are distributed via Debian packages maintained by Freedom of the Press Foundation. Any changes made to OSSEC configuration files will land on production SecureDrop monitoring servers as part of each SecureDrop release. This upgrade will occur automatically.
The use of automatic upgrades for release deployment means that any changes made locally by admins to their OSSEC rules will not persist after a SecureDrop update.