DOCSEARCHbyAlgolia
Submit Docs

BGPalerter Documentation

repository·main·Indexed 21 days ago

https://github.com/nttgin/bgpalerter

BGPalerter is a real-time BGP and RPKI monitoring tool (version 2.0.1) designed to detect hijacks, visibility loss, RPKI invalid announcements, and unexpected AS path changes. It connects to public BGP data repositories, such as RIPE RIS, to monitor network events without requiring local network integration. The tool features a pipeline architecture consisting of Connectors, Monitors, and Reports, with alerting capabilities for Email, Slack, Kafka, and file logs, all managed via a single config.yml file.

Tokens
24.7K
Snippets
64
Records
93
Agent score
76%

What's inside BGPalerter

  1. Overview of BGPalerter Capabilities

    main

    BGPalerter is a self-configuring, real-time BGP monitoring tool. It connects to public BGP data repositories to monitor for various network events without requiring integration into your local network infrastructure.

    Key monitoring capabilities include:

    • Prefix Visibility: Detects if any of your prefixes lose visibility.
    • Hijacking: Detects if any of your prefixes are hijacked.
    • RPKI Compliance:
      • Detects RPKI invalid announcements (e.g., prefix length mismatches).
      • Detects announcements not covered by ROAs.
      • Monitors for expiring ROAs or ROAs covering prefixes that are no longer reachable.
      • Detects RPKI Trust Anchor malfunctions.
      • Detects changes (added/deleted/edited) to ROAs involving your prefixes or ASes.
    • AS Path Monitoring:
      • Detects unexpected upstream (left-side) or downstream (right-side) ASes in an AS path.
      • Allows matching AS paths against user-defined conditions.
    • New Announcements:
      • Detects when your AS announces a new prefix that was never announced before.
      • Detects announcements of more specifics.

    Alerting Mechanisms: Alerts can be delivered via files, email, Kafka, Slack, and several other platforms (see Configuration documentation for the full list).

  2. Understand BGPalerter User Groups

    main

    BGPalerter uses user groups to route alerts to specific people based on the resource (prefix or ASN) or the type of alert (channel).

    By default, two groups exist:

    • noc: Receives only alerts related to BGP monitoring. This group is optional.
    • default: Receives administrative and error communications, plus any alerts that couldn't be matched to a specific user group. This group is mandatory and must be defined for all report modules.

    You can create custom groups to monitor specific customers or resources without sending them administrative noise.

  3. Use positive lookaheads for multiple AND conditions

    main

    If you need to satisfy multiple conditions within a single match parameter (AND logic), use the regular expression positive lookahead construct: (?=exp1)(?=exp2).

    While negative conditions can be expressed via negative lookaheads (?!exp), it is generally recommended to use the dedicated notMatch parameter for clarity and simplicity.

  4. Understand the BGPalerter Volume concept

    main

    The volume parameter (or the -d flag) allows you to confine BGPalerter to a specific directory. This directory will contain all files used by the application, such as logs and configuration.

    This is useful for:

    1. Virtual Environments: Running multiple isolated instances of BGPalerter on a single installation by pointing each to a different directory.
    2. Docker Persistence: Ensuring that configuration and alert logs persist across container restarts by mapping a host directory to /opt/bgpalerter/volume.

  5. How BGPalerter components compose together

    main

    BGPalerter is built using three main functional components that work in a pipeline:

    1. Connectors: Retrieve or listen to BGP data from various sources (like RIPE RIS) and transform it into a common internal format. Connectors always send BGP updates to all available channels.
    2. Monitors: Analyze the data flow from connectors to detect specific issues (e.g., hijacks, visibility loss, or RPKI invalidity) and produce alerts.
    3. Reports: Listen to specific channels and send or store the alerts (e.g., via email or to a file).

    You configure these by declaring them in your config.yml file. You can enable components by uncommenting their respective blocks in the config.yml.example file.

    connectors:
  - file: connectorRIS
    name: ris
    
monitors:
  - file: monitorHijack
    channel: hijack
    name: basic-hijack-detection

reports:
  - file: reportFile
    channels:
      - hijack
    params:
      persistAlertData: false

  6. Configure Reports for alert delivery and storage

    main
    Reports are responsible for sending or storing alerts (e.g., via email or writing to a file). They can also include the specific data that triggered the alert in the notification. For detailed configuration of specific report types, refer to the dedicated reports documentation.

  7. Use report context tags in templates

    main

    All report modules in BGPalerter inherit the getContext method from the Report superclass. This method provides a dictionary of pre-computed tags that can be used to compose textual reports or populate templates in config.yml.

    To use these tags, use the ${tag_name} syntax within your template strings. For example, a template string like The alert involves ${prefix} in ${earliest} will be interpolated into a human-readable format such as The alert involves 1.2.3.4/24 in 2020-04-14 04:02:13.

    Important for API templates: If you are writing a template for an API call that requires a JSON payload, you must convert the JSON structure to a string (e.g., '{"text": "${summary}"}').

    # Example template usage
The alert involves ${prefix} in ${earliest}

# Example API JSON template
'{"text": "${summary}"}'

  8. How connectors, monitors, and reports compose BGPalerter

    main

    BGPalerter is built by composing three main components. If you are extending the tool, you must follow these inheritance rules:

    1. Connectors: Must extend the Connector class. They handle the connection to data sources.
    2. Monitors: Must extend the Monitor class. They implement the logic for detecting specific BGP events.
    3. Reports: Must extend the Report class. They handle the output of alerts.

    Note on Reports: Reports receive both the alerts themselves and the raw data that triggered the alert. This allows you to store the context of an event and replay it for debugging or analysis later.

  9. Configure BGPalerter for research environments

    main

    To use BGPalerter for research purposes (e.g., monitoring the entire address space rather than specific prefixes), set the environment parameter to research in your config.yml. This disables certain production-enforced rules to allow for higher throughput and broader analysis.

    Troubleshooting Performance Issues

    If messages are being dropped (check logs):

    1. Verify that your custom code is not taking too long to process individual BGP messages.
    2. Increase maxMessagesPerSecond (e.g., 10000 is a recommended starting point, depending on CPU).
    3. Set multiProcess to true to utilize two processes.

    If memory consumption increases drastically:

    1. Check for memory leaks in your custom monitor code.
    2. Avoid accumulating too many async calls in the stack. For example, do not perform a single network call per BGP message; instead, bundle calls together or use a more efficient filter function.
    3. Ensure your squashAlerts method is working correctly. If it returns null, the BGP messages will remain in memory until the next alert with the same signature is received.
    4. Reduce fadeOffSeconds to drop BGP messages that take too long to be processed by squashAlerts.

  10. Notify specific users about specific prefixes or ASNs

    main

    To route alerts to specific users based on the resource being monitored, you must perform two steps:

    1. Associate groups with resources in your prefix configuration file (e.g., prefixes.yml). You can assign a group to a specific prefix or to an entire ASN under monitorASns.
    2. Define the group members in your main config.yml within the params section of each report module.

    Precedence Rule: User groups associated with specific prefixes always take precedence over user groups associated with ASNs.

    # prefixes.yml
165.254.225.0/24:
  description: my description 1
  asn: 2914
  group: group1

options:
  monitorASns:
    2914:
      group: group1

# config.yml
reports:
  - file: reportEmail
    channels:
      - hijack
    params:
      notifiedEmails:
        default:
          - admin@org.com
        group1:
          - joh@example.com
          - max@example.com

  11. Install Node.js on CentOS using yum

    main

    To install Node.js (version 18.x) on CentOS/RHEL-based systems, use the NodeSource setup script followed by yum install.

    curl -sL https://deb.nodesource.com/setup_18.x | sudo bash -
sudo yum install nodejs

  12. Run BGPalerter from Source Code

    main

    To run BGPalerter directly from the repository:

    1. Clone the repository.
    2. Ensure Node.js (version >= 12) and npm are installed.
    3. Run npm install to install dependencies.
    4. Run npm run serve to start the application.
    git clone <repo_url>
npm install
npm run serve