# Built-in filters

Pyruse comes with a few very simple filters.

## `=`, `≤`, `≥`, `in`

The filters `filter_equals`, `filter_lowerOrEquals`, and `filter_greaterOrEquals` simply check equality on inequality between a given field, given by the parameter `field`, and a constant value, given py the parameter `value`.
Both parameters are mandatory.
Here are two examples:

```json
{
  "filter": "filter_greaterOrEquals",
  "args": { "field": "IPfailures", "value": 6 }
}

{
  "filter": "filter_equals",
  "args": { "field": "_SYSTEMD_UNIT", "value": "nginx.service" }
}
```

Filter `filter_in` works the same way as `filter_equals` does, except that instead of a single `value`, a `values` list is given, and equality between the field’s contents and any of the list’s items is considered a success.
Here is an example:

```json
{
  "filter": "filter_in",
  "args": { "field": "PRIORITY", "values": [ 2, 3 ] }
}
```

For any of these filters, the constant values must be of the same type as the typical contents of the chosen field.

## Perl-compatible regular expressions (pcre)

Filter `filter_pcre` should only be used on character strings.
Like the above filters, it works on a field given by the `field` parameter, and the [regular expression](https://docs.python.org/3/library/re.html) being looked for is given by the `re` parameter.
Both parameters are mandatory.

The regular expression in the `re` parameter may contain capturing groups:

* Named capturing groups use the `(?P<groupName>…)` notation; the captured value is always stored under the key `groupName` in the current entry.
* Anonymous capturing groups stem from the use of simple parenthesis: `(…)`; these are not saved by default, but a `save` parameter (a list) may be specified, so that the captured values get stored in the current entry, using the names given by `save`.

Here are two identical examples:

```json
{
  "filter": "filter_pcre",
  "args": {
    "field": "MESSAGE",
    "re": "^\\{core\\} Login failed: '(.*)' \\(Remote IP: '(.*)'\\)",
    "save": [ "thatUser", "thatIP" ]
  }
}

{
  "filter": "filter_pcre",
  "args": {
    "field": "MESSAGE",
    "re": "^\\{core\\} Login failed: '(?P<thatUser>.*)' \\(Remote IP: '(?P<thatIP>.*)'\\)"
  }
}
```

Filter `filter_pcreAny` is to `filter_pcre` what `filter_in` is to `filter_equals`.
It works the same way as `filter_pcre`, except that instead of a single regular expression, its `re` parameter contains a list of regular expressions, and a match in the field’s contents is accepted with any of these regular expressions.

In contrast with `filter_pcre`, `filter_pcreAny` does not accept the `save` parameter: the order of fields cannot be guaranted to be the same accross several regular expressions.

Here is an example:

```json
{
  "filter": "filter_pcreAny",
  "args": {
    "field": "MESSAGE",
    "re": [
      "^Failed password for (?P<thatUser>.*) from (?P<thatIP>(?!192\\.168\\.1\\.201 )[^ ]*) port",
      "^Invalid user (?P<thatUser>.*) from (?P<thatIP>(?!192\\.168\\.1\\.201 )[^ ]*) port"
    ]
  }
}
```

## User existence

Filter `filter_userExists` knows of only one —mandatory— parameter: `field`.
This filter is passing, if the system reports the user whose name is the value of the chosen field [as existing](https://docs.python.org/3/library/pwd.html#pwd.getpwnam), and non-passing otherwise.

Here is an example:

```json
{
  "filter": "filter_userExists",
  "args": { "field": "thatUser" }
}
```