Skip to content

Latest commit

 

History

History
259 lines (225 loc) · 7.75 KB

report-http.md

File metadata and controls

259 lines (225 loc) · 7.75 KB
Raw

Send alerts with HTTP requests

BGPalerter can send alerts by means of HTTP requests to a provided URL. This can be done by configuring the module reportHTTP. Read here to understand how.

For configuring reportHTTP, essentially you need to specify two things:

  • The URL
  • A template of the request.

If you are using user groups, you can specify a URL for every user group. This can be done inside hooks, a dictionary containing API URLs grouped by user group (key: group, value: URL). The default user group is mandatory.
Example:

      hooks:
        default: https://MY_WEB_HOOK/
        noc: https://MY_WEB_HOOK_FOR_THE_NOC_GROUP

You can also specify a template for each type of alert (channel). More information about templates is available here. Example:

      isTemplateJSON: true
      templates:
        default: '{"message": "${summary}", "color": "blue"}'
        visibility: '{"message": "${summary}", "color": "orange"}'

Templates are expressed as strings. If the parameter isTemplateJSON is set to true, the string will be converted to JSON before to be posted.

What follows is a list of examples showing how to adapt this module to some well-known applications.

Mattermost

Mattermost is an open source messaging platform.

reports:
  - file: reportHTTP
    channels:
      - hijack
      - newprefix
      - visibility
      - path
      - misconfiguration
      - rpki
    params:
      templates:
        default: '{"attachments": [
              {
                "author_name" : "BGPalerter",
                "fields": [ 
                      {"title": "Event type:", "value": "${type}", "short": "true"},
                      {"title": "First event:", "value": "${earliest} UTC", "short": "true"},
                      {"title": "Last event:", "value": "${latest} UTC", "short": "true"}
                ], 
                "text": "${channel}: ${summary}", "color": "#ffffff"
              }
          ]}'
      isTemplateJSON: true
      headers:
      showPaths: 0 # Amount of AS_PATHs to report in the alert
      hooks:
        default: WEBHOOK_URL

Thanks to @fstolba.

Pushover

Pushover is an app that makes it easy to get real-time notifications on your Android, iPhone, iPad, and Desktop.

reports:
  - file: reportHTTP
    channels:
      - hijack
      - newprefix
      - visibility
      - path
      - misconfiguration
      - rpki
    params:
      templates:
        default: '{"message": "${channel}: ${summary}", "title": "BGPalerter", "priority": "1", "token": "_YOUR_API_TOKEN_HERE_", "user": "_YOUR_USER_KEY_HERE_"}'
      headers:
      isTemplateJSON: true
      showPaths: 0
      hooks:
        default: https://api.pushover.net/1/messages.json

Thanks to Hugo Salgado.

MS Teams

Microsoft Teams is a communication platform developed by Microsoft, as part of the Microsoft 365 family of products.

reports:
  - file: reportHTTP
    channels:
      - hijack
      - newprefix
      - visibility
      - path
      - misconfiguration
      - rpki
    params:
      templates:
        default: '{
                    "@type": "MessageCard",
                    "@context": "http://schema.org/extensions",
                    "themeColor": "d76100",
                    "summary": "BGPalerter",
                    "sections": [{
                        "activityTitle": "BGPalerter",
                        "activitySubtitle": "${channel}",
                        "facts": [{
                            "name": "Summary",
                            "value": "${summary}"
                        }, {
                            "name": "Event type",
                            "value": "${type}"
                        }, {
                            "name": "First event",
                            "value": "${earliest} UTC"
                        }, {
                            "name": "Last event",
                            "value": "${latest} UTC"
                        }],
                        "markdown": true
                    }]
                }'
      isTemplateJSON: true
      headers:
      showPaths: 0 # Amount of AS_PATHs to report in the alert
      hooks:
        default: https://WEBHOOK_URL

Thanks arpanet-creeper for the help.

OpsGenie

OpsGenie is an alert management tool by Atlassian. It's also a good example of how to use HTTP headers with reportHTTP.

reports:
  - file: reportHTTP
    channels:
      - hijack
      - newprefix
      - visibility
      - path
      - misconfiguration
      - rpki
    params:
      templates:
        default: '
            {
                "message": "BGPalerter ${channel} ${description}",
                "description": "${summary}",
                "details":
                    {
                        "prefix": "${prefix}",
                        "bgplay": "${bgplay}",
                        "earliest": "${earliest}",
                        "latest": "${latest}",
                        "channel": "${channel}",
                        "type": "${type}",
                        "asn": "${asn}",
                        "paths": "${paths}",
                        "peers": "${peers}"
                    }
            }'
      headers:
        'Content-Type': 'application/json'
        'Authorization': 'GenieKey 00000000-1111-2222-3333-444444444444'
      isTemplateJSON: true
      showPaths: 5
      hooks:
        default: https://api.opsgenie.com/v2/alerts

RocketChat

RocketChat is an open source messaging platform.

reports:
  - file: reportHTTP
    channels:
      - hijack
      - newprefix
      - visibility
      - path
      - misconfiguration
      - rpki
    params:
      templates:
        default: '{"username": "BGPalerter", "channel": "_CHANNEL_NAME_", "text": "${channel}: ${summary}"}'
      headers:
      isTemplateJSON: true
      showPaths: 0
      hooks:
        default: https://_RC_URL/hooks/_YOUR_KEY_

Configure the "CHANNEL_NAME" in the template. Start with @ for user or # for channel. Eg: @john or #general

Thanks to cadirol.

Jira

Jira is a project management tool developed by Atlassian.

To make this integration work, you need:

reports:
  - file: reportHTTP
    channels:
     - hijack
     - newprefix
     - visibility
     - path
     - misconfiguration
     - rpki
    params:
      templates:
      default: '{
        "fields": {
          "project": {
              "id": "_YOUR_PROJECT_ID_"
          }, 
          "summary": "BGPalerter - event: ${type}",
          "description":  "${summary} \nEarliest: ${earliest} \nLatest: ${latest}",
          "issuetype": {
              "id": "_YOUR_ISSUETYPE_ID_"
          }
        }
      }'
      isTemplateJSON: true
      headers:
        'Content-Type': 'application/json'
        'Authorization': 'Basic BASE64(_USER_EMAIL_:_TOKEN_)'
      showPaths: 0
      hooks:
       default: _API_URL_

Thanks @momorientes and @PacketVis.