{% extends "siem/base.html" %}

{% block sub-title %}Rule Documentation | {% endblock %}

{% block content-main %}

<h1>Rule Documentation</h1>

<ul>
    <li><a href="#daemon">Sentry Daemon</a></li>
    <li><a href="#limitrules">Limit Rules</a><ul>
        <li><a href="#rulevlog">Rule vs. Log Events</a></li>
        <li><a href="#reverse-matching">Reverse Matching</a></li>
        <li><a href="#filters">Filters</a></li>
        <li><a href="#match-lists">Match Lists</a></li>
        <li><a href="#magnitude">Magnitude Calculation</a></li>
        </ul>
    </li>
</ul>

<hr>
<a name="daemon"></a>
<h2>Sentry Daemon</h2>
<p>The sentry daemon watches the database, checking for criteria defined by rules. If a rule's criteria are met (i.e. the rule is broken), the sentry creates a rule event (defined by the rule), and optionally emails alerts (if email has been configured).</p>
<hr>
<a name="limitrules"></a>
<h2>Limit Rules</h2>
<p>Limit rules define a set of event criteria, an event limit, and a time interval. If the number of events that meet the criteria in a time interval is over the event limit, a rule event is created (and email alerts can be sent, if email is configured). Rules can also have a defined number of allowable log sources, and some attributes for calculating the magnitude of rule events. A severity and some modifiers that are used to calculate magnitude, based on the ratio of event count to event limit.</p>

<a name="rulevlog"></a>
<h3>Rule vs. Log Events</h3>
<p>If a rule's rule_events attribute is set to True, it will monitor rule events; otherwise, it will monitor log events.</p>

<a name="reverse-matching"></a>
<h3>Reverse Matching</h3>
<p>Limit rules have a <b>reverse_logic</b> attribute. If set to true, the rule will go off if the conditions are <i><b>not</b></i> met (i.e. a dead process rule).</p>

<a name="filters"></a>
<h3>Filters</h3>
<p>Filters check to see if a certain field contains a certain string. They are case insensitive. If left blank, they will always match. If all of the filters in a rule are met, the rule is considered to be broken. Most fields can use regular expressions.</p>
<p>Rules can filter on the following fields:</p>
<table>
    <tr><th>Field</th><th>Event<br>Type</th><th>Regex?</th></tr>
    <tr><td>message</td><td>Any</td><td>Yes</td></tr>
    <tr><td>raw_text</td><td>Log</td><td>Yes</td></tr>
    <tr><td>log_source</td><td>Log</td><td>Yes</td></tr>
    <tr><td>process</td><td>Log</td><td>Yes</td></tr>
    <tr><td>action</td><td>Log</td><td>Yes</td></tr>
    <tr><td>command</td><td>Log</td><td>Yes</td></tr>
    <tr><td>interface</td><td>Log</td><td>Yes</td></tr>
    <tr><td>status</td><td>Log</td><td>Yes</td></tr>
    <tr><td>source_host</td><td>Log</td><td>Yes</td></tr>
    <tr><td>source_port</td><td>Log</td><td>Yes</td></tr>
    <tr><td>dest_host</td><td>Log</td><td>Yes</td></tr>
    <tr><td>dest_port</td><td>Log</td><td>Yes</td></tr>
    <tr><td>source_user</td><td>Log</td><td>Yes</td></tr>
    <tr><td>target_user</td><td>Log</td><td>Yes</td></tr>
    <tr><td>path</td><td>Log</td><td>Yes</td></tr>
    <tr><td>parameters</td><td>Log</td><td>Yes</td></tr>
    <tr><td>referrer</td><td>Log</td><td>Yes</td></tr>
    <tr><td>source_rule__name</td><td>Rule</td><td>Yes</td></tr>
    <tr><td>magnitude</td><td>Rule</td><td>No</td></tr>
</table>
<p>In addition to these filters, rule events have an optional event_type attribute. Event types must match exactly, if present.</p>

<a name="match-lists"></a>
<h3>Match Lists</h3>
<p>Rules can also compare a field in events to a file containing one item per line. Events will only be counted toward the rule if the specified field matches a line in the file (this can be reversed by setting the <b>match_allowlist</b> attribute to `True`).</p>

<p>To configure a match list, set the <b>match_list_path</b> attribute to the desired file or directory, and set the <b>match_field</b> attribute to the desired field. Choose from the following fields:</p>

<ul>
    <li><b>log_source</b> - must equal line from list</li>
    <li><b>source_host</b> - must contain line from list</li>
    <li><b>dest_host</b> - must contain line from list</li>
    <li><b>source_user</b> - must equal line from list</li>
    <li><b>target_user</b> - must equal line from list</li>
    <li><b>command</b> - must contain line from list</li>
    <li><b>interface</b> - must equal line from list</li>
    <li><b>path</b> - must contain line from list</li>
    <li><b>referrer</b> - must contain line from list</li>
    <li><b>status</b> - must equal line from list</li>
    <li><b>ext0</b> - must contain line from list</li>
    <li><b>ext1</b> - must contain line from list</li>
    <li><b>ext2</b> - must contain line from list</li>
    <li><b>ext3</b> - must contain line from list</li>
    <li><b>ext4</b> - must contain line from list</li>
    <li><b>ext5</b> - must contain line from list</li>
    <li><b>ext6</b> - must contain line from list</li>
    <li><b>ext7</b> - must contain line from list</li>
</ul>

<p>Match lists are only evaluated on rules that watch log events.</p>

<a name="magnitude"></a>
<h3>Magnitude Calculation</h3>
<p>Rule event magnitude is calculated using the following factors:</p>
<ul>
    <li>Rule severity (0-7; 0 is the most severe)</li>
    <li>Event limit</li>
    <li>Event count</li>
    <li>Severity modifier</li>
    <li>Overkill modifier</li>
</ul>
<p>The actual calculation:</p>
<pre>
((event_count / (event_limit + 1)) * overkill_modifier)

*

((8 - severity) * severity_modifier)
</pre>
<p>(Formatting added to aid in comprehension)</p>

{% endblock %}