You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: config.yml.example
+33-3
Original file line number
Diff line number
Diff line change
@@ -38,20 +38,28 @@ monitors:
38
38
params:
39
39
thresholdMinPeers: 10
40
40
41
+
- file: MonitorAS
42
+
channel: misconfiguration
43
+
name: asn-monitor
44
+
params:
45
+
thresholdMinPeers: 2
46
+
41
47
reports:
42
48
- file: reportFile
43
49
channels:
44
50
- hijack
45
51
- newprefix
46
52
- visibility
47
53
- path
54
+
- misconfiguration
48
55
49
56
# - file: reportEmail
50
57
# channels:
51
58
# - hijack
52
59
# - newprefix
53
60
# - visibility
54
61
# - path
62
+
# - misconfiguration
55
63
# params:
56
64
# showPaths: 5 # Amount of AS_PATHs to report in the alert
57
65
# senderEmail: bgpalerter@xxxx
@@ -62,6 +70,7 @@ reports:
62
70
# host: localhost
63
71
# port: 25
64
72
# secure: false # If true the connection will use TLS when connecting to server. If false it will be still possible doing connection upgrade via STARTTLS
73
+
# ignoreTLS: false # If true TLS will be completely disabled, including STARTTLS. Set this to true if you see certificate errors in the logs.
Copy file name to clipboardexpand all lines: docs/configuration.md
+83-2
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,11 @@ The following are common parameters which it is possible to specify in the confi
16
16
|logging.zippedArchive| Indicates if when a file gets rotates it has to be zipped or not. | A boolean | true | Yes |
17
17
|logging.maxSize| Indicates the maximum file size allowed before to be rotated (by adding .number ad the end). This allows to rotate files when logRotatePattern still the same but the file is too big | A string (indicating an amount and a unit of measure) | 20m | Yes |
18
18
|logger.maxFiles| Indicates the maximum amount of files or the maximum amount of days the files are retained. When this threshold is passed, files get deleted. | A string (a number or an amount of days ending with "d") | 14d | Yes |
19
-
|checkForUpdatesAtBoot| Indicates if at each booth the application should check for updates. If an update is available, a notification will be sent to the default group. If you restart the process often (e.g. debugging, experimenting etc.) set this to false to avoid notifications. Anyway, BGPalerter checks for updates every 10 days.| A boolean | true | Yes |
19
+
|checkForUpdatesAtBoot| Indicates if at each booth the application should check for updates. If an update is available, a notification will be sent to the default group. If you restart the process often (e.g. debugging, experimenting etc.) set this to false to avoid notifications. Anyway, BGPalerter checks for updates every 10 days.| A boolean | true | Yes |
20
+
|uptimeMonitor| A dictionary of parameters containing the configuration for the uptime monitor feature. The API showing the status of BGPalerter is available at The API is reachable at `http://localhost:8011/status`||| No |
21
+
|uptimeMonitor.active| A boolean that if set to true enables the monitor. When set to false none of the monitoring components and dependencies are loaded (and no port has to be open).| A boolean | true | No |
22
+
|uptimeMonitor.useStatusCodes| A boolean that if set to true enables HTTP status codes in the response. Nothing changes in the JSON output provided by the API. | A boolean | true | No |
23
+
|uptimeMonitor.port| The port on which the API will be reachable.| An integer | 8011 | No |
20
24
21
25
22
26
## Composition
@@ -27,6 +31,11 @@ You can compose the tool with 3 main components: connectors, monitors, and repor
27
31
* Monitors analyze the data flow and produce alerts. Different monitors try to detect different issues.
28
32
* Reports send/store the alerts, e.g. by email or to a file.
29
33
34
+
> In config.yml.example there are all the possible components declarations (similar to the one of the example below). You can enable the various components by uncommenting the related block.
35
+
36
+
37
+
Example of composition:
38
+
30
39
```yaml
31
40
connectors:
32
41
- file: connectorRIS
@@ -127,20 +136,92 @@ Parameters for this monitor module:
127
136
|thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
128
137
129
138
139
+
#### monitorPath
140
+
141
+
This monitor detects BGP updates containing AS_PATH which match particular regular expressions.
142
+
143
+
> Example:
144
+
> The prefixes list of BGPalerter has an entry such as:
145
+
> ```yaml
146
+
> 165.254.255.0/24:
147
+
> asn: 15562
148
+
> description: an example on path matching
149
+
> ignoreMorespecifics: false
150
+
> path:
151
+
> match: ".*2194,1234$"
152
+
> notMatch: ".*5054.*"
153
+
> matchDescription: detected scrubbing center
154
+
> ```
155
+
> An alert will be generated when a BGP announcements for 165.254.255.0/24 or a more specific contains an AS_PATH
156
+
> terminating in 2194,1234 but not containing 5054. The generated alert will report the matchDescription field.
157
+
158
+
More path matching options are available, see the entire list [here](prefixes.md#prefixes-fields)
159
+
160
+
Parameters for this monitor module:
161
+
162
+
|Parameter| Description|
163
+
|---|---|
164
+
|thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
165
+
166
+
167
+
168
+
130
169
#### monitorNewPrefix
131
170
132
-
This monitor has the logic to detect unexpected change of configuration in the form of new prefixes announced by the correct AS.
171
+
This monitor has the logic to detect unexpected change of configuration in the form of new more specific prefixes announced by the correct AS.
172
+
133
173
In particular, it will monitor for all the declared prefixes and will trigger an alert when:
134
174
* A sub-prefix of the monitored prefix starts to be announced by the same AS declared for the prefix.
135
175
176
+
> Example:
177
+
> The prefixes list of BGPalerter has an entry such as:
178
+
> ```yaml
179
+
> 50.82.0.0/20:
180
+
> asn: 58302
181
+
> description: an example
182
+
> ignoreMorespecifics: false
183
+
> ```
184
+
> If in config.yml monitorNewPrefix is enabled you will receive alerts every time a more specific prefix (e.g. 50.82.4.0/24) is announced by AS58302.
185
+
136
186
Parameters for this monitor module:
137
187
138
188
|Parameter| Description|
139
189
|---|---|
140
190
|thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
141
191
142
192
193
+
#### monitorAS
194
+
195
+
This monitor will listen for all announcements produced by the monitored Autonomous Systems and will detect when a prefix, which is not in the monitored prefixes list, is announced.
196
+
This is useful if you want to be alerted in case your AS starts announcing something you didn't intend to announce (e.g. misconfiguration, typo).
197
+
198
+
199
+
> Example:
200
+
> The prefixes list of BGPalerter has an options.monitorASns list declared, such as:
201
+
> ```yaml
202
+
> 50.82.0.0/20:
203
+
> asn: 58302
204
+
> description: an example
205
+
> ignoreMorespecifics: false
206
+
>
207
+
> options:
208
+
> monitorASns:
209
+
> 58302:
210
+
> group: default
211
+
> ```
212
+
> If in config.yml monitorAS is enabled, you will receive alerts every time a prefix not already part of the prefixes list is announced by AS58302.
213
+
>
214
+
>If AS58302 starts announcing 45.230.23.0/24 an alert will be triggered. This happens because such prefix is not already monitored (it's not a sub prefix of 50.82.0.0/20).
215
+
216
+
You can generate the options block in the prefixes list automatically. Refer to the options `-s` and `-m` in the [auto genere prefixes documentation](prefixes.md#generate).
143
217
218
+
Parameters for this monitor module:
219
+
220
+
|Parameter| Description|
221
+
|---|---|
222
+
|thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
Copy file name to clipboardexpand all lines: docs/prefixes.md
+40-5
Original file line number
Diff line number
Diff line change
@@ -15,11 +15,13 @@ Below the list of possible parameters. **Remember to prepend them with a `--` in
15
15
| Parameter | Description | Expected format | Example | Required |
16
16
|---|---|---|---|---|
17
17
| -o | The YAML output file | A string ending in ".yml" | prefixes.yml | Yes |
18
-
| -a | The AS number(s) you want to generate the list for | A comma-separated list of integers | 2914,3333 | No (one among -a, -p, -pf is required) |
18
+
| -a | The AS number(s) you want to generate the list for | A comma-separated list of integers | 2914,3333 | No (one among -a, -p, -l is required) |
19
19
| -e | Prefixes to exclude from the list | A comma-separated list of prefixes | 165.254.255.0/24,192.147.168.0/24 | No |
20
20
| -i | Avoid monitoring delegated prefixes. If a more specific prefix is found and it results announced by an AS different from the one declared in -a, then set `ignore: true` and `ignoreMorespecifics: true` | Nothing | | No
21
-
| -p | Prefixes for which the list will be generated | A comma-separated list of prefixes | 165.254.255.0/24,192.147.168.0/24 | No (one among -a, -p, -pf is required) |
22
-
| -pf | A file containing the prefixes for which the list will be generated | A text file having a prefix for each line | prefixes.txt | No (one among -a, -p, -pf is required) |
21
+
| -p | Prefixes for which the list will be generated | A comma-separated list of prefixes | 165.254.255.0/24,192.147.168.0/24 | No (one among -a, -p, -l is required) |
22
+
| -l | A file containing the prefixes for which the list will be generated | A text file having a prefix for each line | prefixes.txt | No (one among -a, -p, -l is required) |
23
+
| -s | A list of ASns to be monitored. See [monitorASns](#monitorASns) for more information | A comma separated list of integer | 2914,3333 | No |
24
+
| -m | Monitor all ASns which are origin of at least one of the monitored prefixes. This option is the same of `-s` except that the list of ASns is automatically generated by detecting the origin AS of all the monitored prefixes. See [monitorASns](#monitorASns) for more information | Nothing || No |
23
25
24
26
25
27
## <aname="prefixes-fields"></a>Prefixes list fields
@@ -43,7 +45,6 @@ The prefix list is a file containing a series of blocks like the one below, one
43
45
matchDescription: detected scrubbing center
44
46
maxLength: 128
45
47
minLength: 2
46
-
47
48
```
48
49
49
50
###### <aname="array"></a>
@@ -73,6 +74,40 @@ Below the complete list of attributes (the dot notation is used to represent yml
73
74
| group | The name of the group that will receive alerts about this monitored prefix. By default all alerts are sent to the "default" group. | A string | No |
74
75
75
76
77
+
### Options entry
78
+
79
+
Optionally the prefixes list can contain an `options` entry, such us:
80
+
81
+
```yaml
82
+
options:
83
+
monitorASns:
84
+
2914:
85
+
group: default
86
+
```
87
+
88
+
The `options` entry allows the configuration of additional monitoring options directly from the prefixes list file.
89
+
90
+
| Option | Description |
91
+
|---|---|
92
+
| monitorASns | A dictionary of ASns to be monitored. Each entry of the dictionary has the ASn as key. Each value of the dictionary contains the monitoring settings.|
93
+
94
+
#### monitorASns
95
+
96
+
Allows for generic monitoring (not related to specific prefixes) of Autonomous Systems.
97
+
98
+
An example of monitorASns configuration is:
99
+
100
+
```yaml
101
+
monitorASns:
102
+
2914:
103
+
group: ntt
104
+
3333:
105
+
group: ripencc
106
+
```
107
+
108
+
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.
109
+
110
+
The monitor in charge of doing this type of detection is [monitorAS (click for more information)](configuration.md#monitoras).
76
111
77
112
### Optimized regular expressions for AS path matching
78
113
@@ -82,6 +117,6 @@ To drastically optimize the process, try to use one of the following regular exp
82
117
83
118
* "789$" - match paths that originate with AS789
84
119
* "456" - match any path that traverses AS456 at any point
85
-
* "^123,456" - match paths where the last traversed ASNs were 123 and 456 (in that order)
120
+
* "^123,456" - match paths where the last traversed ASns were 123 and 456 (in that order)
86
121
* "^123,456,789$" - match the exact path [123, 457, 789]
87
122
* "[789,101112]" - match paths containing the AS_SET {789, 101112}
0 commit comments