Merge branch 'dev'

README.md

@@ -43,6 +43,11 @@ Please uncomment the related section and configure according to your needs.
         - [Connectors](docs/configuration.md#connectors)
         - [Monitors](docs/configuration.md#monitors)
         - [Reports](docs/configuration.md#reports)
+            - [reportFile](docs/configuration.md#reportfile)
+            - [reportEmail](docs/configuration.md#reportemail)
+            - [reportSlack](docs/configuration.md#reportslack)
+            - [reportKafka](docs/configuration.md#reportkafka)
+    - [Uptime monitor](docs/uptime-monitor.md)
 - [More information for developers](docs/develop.md)
     - [All npm commands](docs/develop.md#all-npm-commands)
 

config.yml.example

@@ -38,20 +38,28 @@ monitors:
     params:
       thresholdMinPeers: 10
 
+  - file: MonitorAS
+    channel: misconfiguration
+    name: asn-monitor
+    params:
+      thresholdMinPeers: 2
+
 reports:
   - file: reportFile
     channels:
       - hijack
       - newprefix
       - visibility
       - path
+      - misconfiguration
 
 #  - file: reportEmail
 #    channels:
 #      - hijack
 #      - newprefix
 #      - visibility
 #      - path
+#      - misconfiguration
 #    params:
 #      showPaths: 5 # Amount of AS_PATHs to report in the alert
 #      senderEmail: bgpalerter@xxxx
@@ -62,6 +70,7 @@ reports:
 #        host: localhost
 #        port: 25
 #        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
+#        ignoreTLS: false # If true TLS will be completely disabled, including STARTTLS. Set this to true if you see certificate errors in the logs.
 #        auth:
 #          user: username
 #          pass: password
@@ -72,13 +81,14 @@ reports:
 #        default:
 #          - [email protected]
 #          - [email protected]
-#
+
 #  - file: reportSlack
 #    channels:
 #      - hijack
 #      - newprefix
 #      - visibility
 #      - path
+#      - misconfiguration
 #    params:
 #      colors:
 #        hijack: '#d60b1c'
@@ -87,13 +97,14 @@ reports:
 #        path: '#42cbf5'
 #      hooks:
 #        default: _YOUR_SLACK_WEBHOOK_URL_
-#
+
 #  - file: reportKafka
 #    channels:
 #      - hijack
 #      - newprefix
 #      - visibility
 #      - path
+#      - misconfiguration
 #    params:
 #      host: localhost:9092
 #      topics:
@@ -128,4 +139,23 @@ logging:
   maxSize: 80m
   maxFiles: 14d
 
-checkForUpdatesAtBoot: true
+checkForUpdatesAtBoot: true
+
+
+############################
+# Uptime monitor settings:
+# The uptime monitor enables an API (http://localhost:8011/status) which shows the current status of BGPalerter
+# If any component reports an invalid state, the "warning" field will be set to true and the HTTP status code will be 500.
+#
+# - 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).
+# - 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.
+# - port - The port on which the API will be reachable.
+
+uptimeMonitor:
+  active: false
+  useStatusCodes: true
+  port: 8011
+
+############################

docs/configuration.md

@@ -16,7 +16,11 @@ The following are common parameters which it is possible to specify in the confi
 |logging.zippedArchive| Indicates if when a file gets rotates it has to be zipped or not. | A boolean | true | Yes |
 |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 |
 |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 |
-|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 | 
+|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 |
+|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 | 
+|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 | 
+|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 | 
+|uptimeMonitor.port| The port on which the API will be reachable.| An integer | 8011 | No | 
 
 
 ## Composition
@@ -27,6 +31,11 @@ You can compose the tool with 3 main components: connectors, monitors, and repor
 * Monitors analyze the data flow and produce alerts. Different monitors try to detect different issues.
 * Reports send/store the alerts, e.g. by email or to a file.
 
+> 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.
+
+
+Example of composition:
+
 ```yaml
 connectors:
   - file: connectorRIS
@@ -127,20 +136,92 @@ Parameters for this monitor module:
 |thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
 
 
+#### monitorPath
+
+This monitor detects BGP updates containing AS_PATH which match particular regular expressions.
+
+> 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
+> ```
+> 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)
+
+Parameters for this monitor module:
+
+|Parameter| Description| 
+|---|---|
+|thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
+
+
+
+
 #### monitorNewPrefix
 
-This monitor has the logic to detect unexpected change of configuration in the form of new prefixes announced by the correct AS.
+This monitor has the logic to detect unexpected change of configuration in the form of new more specific prefixes announced by the correct AS.
+
 In particular, it will monitor for all the declared prefixes and will trigger an alert when:
 * A sub-prefix of the monitored prefix starts to be announced by the same AS declared for the prefix.
 
+> Example: 
+> The prefixes list of BGPalerter has an entry such as:
+> ```yaml
+> 50.82.0.0/20:
+>    asn: 58302
+>    description: an example
+>    ignoreMorespecifics: false
+> ```
+> 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.
+
 Parameters for this monitor module:
 
 |Parameter| Description| 
 |---|---|
 |thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
 
 
+#### monitorAS
+
+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.
+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).
+
+
+> Example: 
+> The prefixes list of BGPalerter has an options.monitorASns list declared, such as:
+> ```yaml
+> 50.82.0.0/20:
+>    asn: 58302
+>    description: an example
+>    ignoreMorespecifics: false
+> 
+> options:
+>  monitorASns:
+>    58302:
+>      group: default
+> ```
+> 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.
+> 
+>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).
+
+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).
 
+Parameters for this monitor module:
+
+|Parameter| Description| 
+|---|---|
+|thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. |
+
+
 ### Reports
 
 Possible reports are:

docs/prefixes.md

@@ -15,11 +15,13 @@ Below the list of possible parameters. **Remember to prepend them with a `--` in
 | Parameter | Description  | Expected format | Example  |  Required |
 |---|---|---|---|---|
 | -o  | The YAML output file | A string ending in ".yml" | prefixes.yml | Yes |
-| -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) |
+| -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) |
 | -e  | Prefixes to exclude from the list | A comma-separated list of prefixes | 165.254.255.0/24,192.147.168.0/24 | No |
 | -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
-| -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) |
-| -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) |
+| -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) |
+| -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) |
+| -s  | A list of ASns to be monitored. See [monitorASns](#monitorASns) for more information | A comma separated list of integer | 2914,3333 | No |
+| -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 |
 
 
 ## <a name="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
     matchDescription: detected scrubbing center
     maxLength: 128
     minLength: 2
-    
 ```
 
 ###### <a name="array"></a>
@@ -73,6 +74,40 @@ Below the complete list of attributes (the dot notation is used to represent yml
 | 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 |
 
 
+### Options entry
+
+Optionally the prefixes list can contain an `options` entry, such us:
+
+```yaml
+options:
+  monitorASns:
+    2914:
+      group: default
+```
+
+The `options` entry allows the configuration of additional monitoring options directly from the prefixes list file.
+
+| Option | Description |
+|---|---|
+| 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.|
+
+#### monitorASns
+
+Allows for generic monitoring (not related to specific prefixes) of Autonomous Systems.
+
+An example of monitorASns configuration is:
+
+```yaml
+monitorASns:
+    2914:
+      group: ntt
+    3333:
+      group: ripencc
+```
+
+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
 
@@ -82,6 +117,6 @@ To drastically optimize the process, try to use one of the following regular exp
 
 * "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" - 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}

docs/uptime-monitor.md

@@ -0,0 +1,22 @@
+# Uptime Monitor
+
+The Uptime Monitor is a feature that allows to monitor the status of BGPalerter.
+The API is reachable at `http://localhost:8011/status`. 
+The API, in addition to the JSON answer, can use HTTP status codes for an easier integration with Nagios and similar.
+
+When this feature is disabled, no extra dependencies are loaded and no open port is required. 
+Please, see [configuration](configuration.md) for all the possible configuration parameters.
+
+The following is an example of the API output.
+
+```
+{
+    "warning": false,
+    "connectors": [
+            {
+                "name": "ConnectorRIS",
+                "connected": true
+            }
+        ]
+}
+```