From 09e8ab94811a75a9a4d0d9eddf3b2c6386e3f2f6 Mon Sep 17 00:00:00 2001 From: Kushal Das Date: Mon, 12 Apr 2021 18:36:11 +0530 Subject: [PATCH 1/5] Adds details about OSSEC rule addition --- docs/development/updating_ossec.rst | 92 +++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/docs/development/updating_ossec.rst b/docs/development/updating_ossec.rst index c20726141..a20e4dcec 100644 --- a/docs/development/updating_ossec.rst +++ b/docs/development/updating_ossec.rst @@ -82,6 +82,98 @@ a failing test which you then can make pass with a patch to the OSSEC rules: .. _syscheck: https://ossec-docs.readthedocs.io/en/latest/docs/manual/syscheck/index.html .. _2134: https://github.com/freedomofpress/securedrop/issues/2134 + +How to add a new OSSEC rule? +============================= + +There are two main files involved in this. + +- `install_files/securedrop-ossec-server/var/ossec/rules/local_rules.xml` the rules file +- `install_files/securedrop-ossec-server/var/ossec/etc/local_decoder.xml` the decoder file + + +The decoder file +----------------- + +:: + + + + fwupd + + +In the above example, we are creating a new `decoder` based on the +`program_name` value. We can find this `program_name` value using the +`/var/ossec/bin/ossec-logtest` command, you can paste the login as input to +this, and it will give you some parsed output. + +:: + + **Phase 1: Completed pre-decoding. + full event: 'Mar 1 13:22:53 app fwupd[133921]: 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. + + +The rules +--------- + +We decided to use the above mentioned `decoder` along with a group of rules. +Here, we are making sure that the rules have proper unique `id` number, and +they are written in the correct (sorted) place in the rules XML file. + + +:: + + + + fwupd + Error opening directory + fwupd error + no_email_alert + + + fwupd + Failed to load SMBIOS + fwupd error for auto updates + no_email_alert + + + + +Verify the configuration change +-------------------------------- + +On the monitor server you can use the following command as `root` to verify the changes. + +:: + + /var/ossec/bin/ossec-analysisd -t + + +Adding an automated test for staging +------------------------------------- + +You can then add a test for the `molecule/testinfra/mon/test_ossec_ruleset.py` +file. Here the test loops over different log lines mentioned in +`log_events_without_ossec_alerts` variable in +`molecule/testinfra/vars/staging.yml`, and makes sure that the `rule_id` and +`level` matches. + + + Deployment ---------- From 6c054e17517e419fc7c12991c0ea6b1156d8379f Mon Sep 17 00:00:00 2001 From: Cory Francis Myers Date: Tue, 26 Oct 2021 16:28:27 -0700 Subject: [PATCH 2/5] introduces OSSEC's "decoder" and "rule" concepts thread: https://github.com/freedomofpress/securedrop-docs/pull/199#discussion_r613222949 --- docs/development/updating_ossec.rst | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/development/updating_ossec.rst b/docs/development/updating_ossec.rst index a20e4dcec..36fd4e202 100644 --- a/docs/development/updating_ossec.rst +++ b/docs/development/updating_ossec.rst @@ -86,11 +86,25 @@ a failing test which you then can make pass with a patch to the OSSEC rules: How to add a new OSSEC rule? ============================= -There are two main files involved in this. +OSSEC processes events in two steps: -- `install_files/securedrop-ossec-server/var/ossec/rules/local_rules.xml` the rules file -- `install_files/securedrop-ossec-server/var/ossec/etc/local_decoder.xml` the decoder file +1. `Decoders `_ + parse and filter log events that meet certain criteria for subsequent processing. + SecureDrop's custom rules are defined in + ``install_files/securedrop-ossec-server/var/ossec/rules/local_rules.xml``. +2. `Rules `_ + check decoded events against conditions and optionally yield alerts. + SecureDrop's custom rules are defined in + ``install_files/securedrop-ossec-server/var/ossec/etc/local_decoder.xml``. + +A basic decoder filters log events by ``program_name`` (e.g., ``fwupd``). +If a decoder is already defined for the program of interest, you can go straight +to :ref:`defining a new rule ` unless you have a reason to add additional +:ref:`decoders ` for further filtering. + + +.. _the_decoder_file: The decoder file ----------------- @@ -125,7 +139,8 @@ this, and it will give you some parsed output. Level: '2' Description: 'Unknown problem somewhere in the system.' **Alert to be generated. - + +.. _the_rules: The rules --------- From 4d907c07f7e784786f2a397ff8f41156614e683d Mon Sep 17 00:00:00 2001 From: Cory Francis Myers Date: Thu, 28 Oct 2021 11:12:12 -0700 Subject: [PATCH 3/5] demonstrates use of ossec-logtest threads: - https://github.com/freedomofpress/securedrop-docs/pull/199#discussion_r669945844 - https://github.com/freedomofpress/securedrop-docs/pull/199#discussion_r669945844 --- docs/development/updating_ossec.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/development/updating_ossec.rst b/docs/development/updating_ossec.rst index 36fd4e202..f6dde1d2f 100644 --- a/docs/development/updating_ossec.rst +++ b/docs/development/updating_ossec.rst @@ -23,6 +23,8 @@ 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. +.. _using_ossec_logtest : + Using ``ossec-logtest`` ----------------------- @@ -109,6 +111,9 @@ to :ref:`defining a new rule ` unless you have a reason to add additi The decoder file ----------------- +For example, to add a decoder for log events from ``fwupd``, we can add to +``local_decoder.xml``: + ::