mirror/nttgin-BGPalerter
1
0
Fork 0
mirror of https://github.com/nttgin/BGPalerter.git synced 2024-05-19 06:50:08 +00:00
Code Issues Releases Wiki Activity

better documentation for path matching, explain regex (#318)

Browse Source
This commit is contained in:
Massimo Candela
2020-09-14 21:32:58 +02:00
parent 427c17333b
commit b57b0824df
3 changed files with 74 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/configuration.md
View File

@ -174,7 +174,7 @@ Parameters for this monitor module:
|maxDataSamples| Maximum number of collected BGP messages for each alert which doesn't reach yet the `thresholdMinPeers`. Default to 1000. As soon as the `thresholdMinPeers` is reached, the collected BGP messages are flushed, independently from the value of `maxDataSamples`.|
#### monitorPath
``
This monitor detects BGP updates containing AS_PATH which match particular regular expressions.
> Example:
@ -185,14 +185,20 @@ This monitor detects BGP updates containing AS_PATH which match particular regul
> description: an example on path matching
> ignoreMorespecifics: false
> path:
> match: ".*2194,1234$"
> notMatch: ".*5054.*"
> matchDescription: detected scrubbing center
> - match: ".*2194,1234$"
> notMatch: ".*5054.*"
> matchDescription: detected scrubbing center
> - match: ".*123$"
> notMatch: ".*5056.*"
> matchDescription: other match
> ```
> An alert will be generated when a BGP announcements for 165.254.255.0/24 or a more specific contains an AS_PATH
> terminating in 2194,1234 but not containing 5054. The generated alert will report the matchDescription field.
More path matching options are available, see the entire list [here](prefixes.md#prefixes-fields)
Path is a list of matching rules, in this way multiple matching rules can be defined for the same prefix (rules are in OR).
More about path matching [here](path-matching.md).
> An alert will be generated for example when a BGP announcements for 165.254.255.0/24 or a more specific contains an AS_PATH
> terminating in 2194,1234 but not containing 5054. The generated alert will report the matchDescription field.
Example of alert:
> Matched "an example on path matching" on prefix 98.5.4.3/22 (including length violation) 1 times

59
docs/path-matching.md Normal file
View File

@ -0,0 +1,59 @@
# Path matching
The component `monitorPath` allows to specify rules in order to get notified when specific conditions are matched on AS_PATHs.
The rules must be expressed with regular expressions (if you need to refresh your skills or test a regular expression, we suggest [this](https://regex101.com/)).
The AS_PATH parsed by BGPalerter are in the form `137,3333,1335,2914`.
> Example:
> The prefixes list of BGPalerter has an entry such as:
> ```yaml
> 165.254.255.0/24:
> asn: 15562
> description: an example on path matching
> ignoreMorespecifics: false
> path:
> - match: ".*2194,1234$"
> notMatch: ".*5054.*"
> matchDescription: detected scrubbing center
> - match: ".*123$"
> notMatch: ".*5056.*"
> matchDescription: other match
> ```
Each item in the path list is a matching rule.
Each matching rule in the path list is composed of:
* match, the regular expression that will be tested on each AS path. If the expression tests positive, the BGP message triggers an alert. ASns are comma separated (see example above).
* notMatch, the regular expression that will be tested on each AS path. If the expression tests positive, the BGP message will not triggers an alert. ASns are comma separated (see example above).
* matchDescription, the description that will be reported in the alert in case the regex test results in a match.
* maxLength, the maximum length allowed for an AS path. Longer paths will trigger an alert.
* minLength, the minimum length allowed for an AS path. Shorter paths will trigger an alert.
> Remember, the various matching rules are in OR among each other, while the fields inside a single matching rule are in AND.
> This means that in the example above, the user will receive an alert if (".*2194,1234$" AND NOT ".*5054.*") OR (".*123$" AND NOT ".*5056.*")
## Some common examples
* `(,|^)789$` - match paths that originate with AS789, no matter what they have in front (including nothing in front);
* `(,|^)456,` - match any path that traverses AS456 at any point, except origin;
* `(,|^)456(,|$)` - match any path that traverses AS456 at any point (including as origin, or as last AS);
* `^123,456,` - match paths where the last traversed ASns were 123 and 456 (in that order);
* `^123,456,789$` - match the exact path [123, 457, 789];
* `\[789,101112\]` - match paths containing the AS_SET {789, 101112}.
### Match regular expression with multiple conditions in AND
If you want to specify multiple conditions in the same match parameter, you can use the positive lookahead construct offered natively by regular expressions.
A positive lookahead is in the form `(?=exp1)(?=exp2)` where `exp1` and `exp2` are regular expressions
Example:
> (?=.*(137|2914),32934$)(?=.*13335,2914,32934$)
which tests for `AS32934 must only be visible via path 137 or 2914` AND `if it transits AS13335, it must be through AS2914`
Positive lookaheads work also for negative conditions (e.g. `(?!exp)`), but in most of the cases this is redundant with the `notMatch` parameter.

21
docs/prefixes.md
View File

@ -69,12 +69,7 @@ Below the complete list of attributes (the dot notation is used to represent yml
| ignore | Exclude the current prefix from monitoring. Useful when you are monitoring a prefix and you want to exclude a particular sub-prefix| A boolean | No |
| includeMonitors | The list of monitors you want to run on this prefix. If this attribute is not declared, all monitors will be used. Not compatible with excludeMonitors. | An array of strings (monitors name according to config.yml) | No |
| excludeMonitors | The list of monitors you want to exclude on this prefix. Not compatible with includeMonitors. Use monitors `name` attributes, as defined in the monitor listy in [config.yml](https://github.com/nttgin/BGPalerter/blob/master/config.yml.example). | An array of strings (monitors name according to config.yml) | No |
| path | A dictionary containing all sub-attributes for path matching. All the sub-attributes are in AND.| Sub-attributes (as follows) | No |
| path.match | The regular expression that will be tested on each AS path. If the expression tests positive the BGP message triggers an alert. ASns are comma separated (see example above). **Please, use optimized regular expression as described [in the following sub-section](#optimized-regular-expressions-for-as-path-matching)** | A string (valid RegEx) | No |
| path.notMatch | The regular expression that will be tested on each AS path. If the expression tests positive the BGP message will not triggers an alert. ASns are comma separated (see example above). | A string (valid RegEx) | No |
| path.matchDescription | The description that will be reported in the alert in case the regex test results in a match. | A string | No |
| path.maxLength | The maximum length allowed for an AS path. Longer paths will trigger an alert. | A number | No |
| path.minLength | The minimum length allowed for an AS path. Shorter paths will trigger an alert. | A number | No |
| path | A list path matching rules, read more [here](path-matching.md). | | No |
| group | The name of the group that will receive alerts about this monitored prefix. By default all alerts are sent to the "default" group. See [here](usergroups.md).| A string | No |
@ -111,16 +106,4 @@ monitorASns:
The AS2914 and AS3333 will be monitored. The alerts related to AS2914 will be sent to the "ntt" user group and the alerts for AS3333 to the "ripencc" user group.
The monitor in charge of doing this type of detection is [monitorAS (click for more information)](configuration.md#monitoras).
### Optimized regular expressions for AS path matching
The following simple regular expressions will drastically reduce CPU and network usage when applied to the `path.match` attribute. Instead, there are no benefits in applying the following regular expressions to the `path.notMatch` attribute.
To drastically optimize the process, try to use one of the following regular expression for `path.match` attribute. If the obtained filter is too loose, add additional (complex) constraints in `path.notMatch`. In this way the more complex `path.notMatch` will be tested only on the subset produced by the faster `path.match`.
* "789$" - match paths that originate with AS789
* "456" - match any path that traverses AS456 at any point
* "^123,456" - match paths where the last traversed ASns were 123 and 456 (in that order)
* "^123,456,789$" - match the exact path [123, 457, 789]
* "[789,101112]" - match paths containing the AS_SET {789, 101112}
The monitor in charge of doing this type of detection is [monitorAS (click for more information)](configuration.md#monitoras).