# Wiki source code of BGP Alerter on Ubuntu

Last modified by Jean Franco on 2022/10/30 16:13
Export
Office Formats
Export as PDF Export as ODT Export as RTF
Other Formats

Select the pages to export:

select all/ none

Legend:
  Created Page
  Modified Extension Page
  Clean Extension Page

Export as HTML

Show last authors

author | version | line-number | content
--- | --- | --- | ---
|  | 1 | === Introduction ===
|  | 2 |
|  | 3 | [[BGP (Border Gateway Protocol)>>url:https://en.wikipedia.org/wiki/Border_Gateway_Protocol]] is one of the core protocols responsible for routing packets across the internet, so when it goes wrong, significant outages can occur. For example, in 2019, a small ISP made a BGP misconfiguration that unfortunately propagated upstream and [[took large parts of Cloudflare and AWS offline for over an hour>>url:https://blog.cloudflare.com/how-verizon-and-a-bgp-optimizer-knocked-large-parts-of-the-internet-offline-today/]]. Also, a year earlier, [[a BGP hijack took place in order to intercept traffic to a well-known cryptocurrency wallet provider>>url:https://blog.cloudflare.com/bgp-leaks-and-crypto-currencies/]] and steal the funds of unsuspecting customers.
|  | 4 |
|  | 5 | [[BGPalerter>>url:https://github.com/nttgin/BGPalerter]] is an open-source BGP network monitoring tool that can provide real-time alerts on BGP activity, including route visibility and new route announcements, as well as potentially nefarious activity such as [[route hijacks or route leaks>>url:https://www.digitalocean.com/community/tutorials/how-to-monitor-bgp-announcements-and-routes-using-bgpalerter-on-ubuntu-18-04#step-4-%E2%80%94-interpreting-bgpalerter-alerts]].
|  | 6 |
|  | 7 | **Note:** BGPalerter automatically ingests publicly available network routing information, meaning that it does not have to have any level of privileged access or integration into the network(s) that you wish to monitor. All monitoring is fully compliant with the Computer Misuse Act, Computer Fraud and Abuse Act, and other similar laws. However, it is recommended to responsibly disclose any relevant findings to the affected network operator.
|  | 8 |
|  | 9 | In this tutorial, you’ll install and configure BGPalerter to monitor your important networks for potentially suspicious activity.
|  | 10 |
|  | 11 | == Prerequisites ==
|  | 12 |
|  | 13 | To complete this tutorial, you will need:
|  | 14 |
|  | 15 | * An Ubuntu 18.04 server set up by following the [[Initial Server Setup with Ubuntu 18.04>>url:https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-18-04]], including a sudo non-root user.
|  | 16 | * (((
|  | 17 | One or more networks or devices that you wish to monitor, for example:
|  | 18 |
|  | 19 | * A server that you maintain
|  | 20 | * Your company network
|  | 21 | * Your local ISP
|  | 22 |
|  | 23 | For each device or network you’ll need to identify either the individual IP address, IP address range, or Autonomous System number that it is part of. This is covered in Step 1.
|  | 24 | )))
|  | 25 |
|  | 26 | Once you have these ready, log in to your server as your non-root user to begin.
|  | 27 |
|  | 28 | == Step 1 — Identifying the Networks to Monitor ==
|  | 29 |
|  | 30 | In this step, you will identify the relevant details of the networks that you want to monitor.
|  | 31 |
|  | 32 | BGPalerter can monitor based on individual IP addresses or network prefixes. It can also monitor entire networks based on their Autonomous System (AS) number, which is a globally unique identifier for a network owned by a particular administrative entity.
|  | 33 |
|  | 34 | In order to find this information, you can use the [[IP-to-ASN WHOIS lookup service>>url:https://www.team-cymru.com/IP-ASN-mapping.html]] provided by threat intelligence service [[Team Cymru>>url:https://www.team-cymru.com/]]. This is a custom WHOIS server designed for looking up IP address and network routing information.
|  | 35 |
|  | 36 | If you don’t already have whois installed, you can install it using the following commands:
|  | 37 |
|  | 38 | {{{
|  | 39 | }}}
|  | 40 |
|  | 41 | 1. sudo apt update
|  | 42 | 1. sudo apt install whois
|  | 43 |
|  | 44 | Once you’ve confirmed that whois is installed, begin by performing a lookup for the IP address of your own server, using the -h argument to specify a custom server:
|  | 45 |
|  | 46 | {{{
|  | 47 | }}}
|  | 48 |
|  | 49 | 1. whois -h whois.cymru.com your-ip-address
|  | 50 |
|  | 51 | This will output a result similar to the following, which shows the AS name and number that your server is a part of. This will usually be the AS of your server hosting provider, for example, DigitalOcean.
|  | 52 |
|  | 53 | {{{
|  | 54 | }}}
|  | 55 |
|  | 56 | Output
|  | 57 |
|  | 58 | AS | IP | AS Name 14061 | your-ip-address | DIGITALOCEAN-ASN, US
|  | 59 |
|  | 60 | Next, you can perform a lookup to identify the network prefix/range that your server is a part of. You do this by adding the -p argument to your request:
|  | 61 |
|  | 62 | {{{
|  | 63 | }}}
|  | 64 |
|  | 65 | 1. whois -h whois.cymru.com " -p your-ip-address"
|  | 66 |
|  | 67 | The output will be very similar to the previous command, but will now show the IP address prefix that the IP address of your server belongs to:
|  | 68 |
|  | 69 | {{{
|  | 70 | }}}
|  | 71 |
|  | 72 | Output
|  | 73 |
|  | 74 | AS | IP | BGP Prefix | AS Name 14061 | your-ip-address | 157.230.80.0/20 | DIGITALOCEAN-ASN, US
|  | 75 |
|  | 76 | Finally, you can look up further details of the AS that your server is a part of, including the geographic region and allocation date.
|  | 77 |
|  | 78 | Substitute in the AS number that you identified using the previous commands. You use the -v argument to enable verbose output, which ensures that all relevant details are shown:
|  | 79 |
|  | 80 | {{{
|  | 81 | }}}
|  | 82 |
|  | 83 | 1. whois -h whois.cymru.com " -v as14061"
|  | 84 |
|  | 85 | The output will show further information about the AS:
|  | 86 |
|  | 87 | {{{
|  | 88 | }}}
|  | 89 |
|  | 90 | Output
|  | 91 |
|  | 92 | AS | CC | Registry | Allocated | AS Name 14061 | US | arin | 2012-09-25 | DIGITALOCEAN-ASN, US
|  | 93 |
|  | 94 | You’ve identified key details about the network(s) that you wish to monitor. Keep a note of these details somewhere, as you’ll need them later on. Next, you’ll begin the setup of BGPalerter.
|  | 95 |
|  | 96 | == Step 2 — Creating a Non-Privileged User for BGPalerter ==
|  | 97 |
|  | 98 | In this step, you will create a new non-privileged user account for BGPalerter, as the program doesn’t need to run with sudo/root privileges.
|  | 99 |
|  | 100 | Firstly, create a new user with a disabled password:
|  | 101 |
|  | 102 | {{{
|  | 103 | }}}
|  | 104 |
|  | 105 | 1. sudo adduser ~-~-disabled-password bgpalerter
|  | 106 |
|  | 107 | You do not need to set up a password or SSH keys, as you’ll use this user only as a service account for running/maintaining BGPalerter.
|  | 108 |
|  | 109 | Log in to the new user using su:
|  | 110 |
|  | 111 | {{{
|  | 112 | }}}
|  | 113 |
|  | 114 | 1. sudo su bgpalerter
|  | 115 |
|  | 116 |
|  | 117 | You’ll now be logged in as the new user:
|  | 118 |
|  | 119 | {{{bgpalerter@droplet:/home/user$
|  | 120 | }}}
|  | 121 |
|  | 122 | Use the cd command to move to the home directory of your new user:
|  | 123 |
|  | 124 | {{{bgpalerter@droplet:/home/user$ cd
|  | 125 | bgpalerter@droplet:~$
|  | 126 | }}}
|  | 127 |
|  | 128 | You’ve created a new non-privileged user for BGPalerter. Next, you will install and configure BGPalerter on your system.
|  | 129 |
|  | 130 | == Step 3 — Installing and Configuring BGPalerter ==
|  | 131 |
|  | 132 | In this step, you will install and configure BGPalerter. Make sure that you’re still logged in as your new non-privileged user.
|  | 133 |
|  | 134 | Firstly, you need to identify the latest release of BGPalerter, in order to ensure that you download the most up-to-date version. Browse to the [[BGPalerter Releases>>url:https://github.com/nttgin/BGPalerter/releases]] page and take a copy of the download link for the most recent Linux x64 release.
|  | 135 |
|  | 136 | You can now download a copy of BGPalerter using wget, making sure to substitute in the correct download link:
|  | 137 |
|  | 138 | {{{
|  | 139 | }}}
|  | 140 |
|  | 141 | 1. wget https:~/~/github.com/nttgin/BGPalerter/releases/download/v1.24.0/bgpalerter-linux-x64
|  | 142 |
|  | 143 |
|  | 144 | Once the file has finished downloading, mark it as executable:
|  | 145 |
|  | 146 | {{{
|  | 147 | }}}
|  | 148 |
|  | 149 | 1. chmod +x bgpalerter-linux-x64
|  | 150 |
|  | 151 |
|  | 152 | Next, check that BGPalerter has been downloaded and installed successfully by checking the version number:
|  | 153 |
|  | 154 | {{{
|  | 155 | }}}
|  | 156 |
|  | 157 | 1. ./bgpalerter-linux-x64 ~-~-version
|  | 158 |
|  | 159 |
|  | 160 | This will output the current version number:
|  | 161 |
|  | 162 | {{{
|  | 163 | }}}
|  | 164 |
|  | 165 | Output
|  | 166 |
|  | 167 | 1.24.0
|  | 168 |
|  | 169 | Before you can run BGPalerter properly, you’ll need to define the networks that you wish to monitor within a configuration file. Create and open the prefixes.yml file in your favourite text editor:
|  | 170 |
|  | 171 | {{{
|  | 172 | }}}
|  | 173 |
|  | 174 | 1. nano ~~/prefixes.yml
|  | 175 |
|  | 176 |
|  | 177 | In this config file, you’ll specify each of the individual IP addresses, IP address ranges, and AS numbers that you want to monitor.
|  | 178 |
|  | 179 | Add the following example and adjust the configuration values as required by using the network information that you identified in [[Step 1>>url:https://www.digitalocean.com/community/tutorials/how-to-monitor-bgp-announcements-and-routes-using-bgpalerter-on-ubuntu-18-04#step-1-%E2%80%94-identifying-the-networks-to-monitor]]:
|  | 180 |
|  | 181 | ~~/prefixes.yml
|  | 182 |
|  | 183 | {{{your-ip-address/32:
|  | 184 | description: My Server
|  | 185 | asn:
|  | 186 | - 14061
|  | 187 | ignoreMorespecifics: false
|  | 188 |
|  | 189 | 157.230.80.0/20:
|  | 190 | description: IP range for my Server
|  | 191 | asn:
|  | 192 | - 14061
|  | 193 | ignoreMorespecifics: false
|  | 194 |
|  | 195 | options:
|  | 196 | monitorASns:
|  | 197 | '14061':
|  | 198 | group: default
|  | 199 | }}}
|  | 200 |
|  | 201 | You can monitor as many IP address ranges or AS numbers as you want. To monitor individual IP addresses, represent them using /32 for IPv4, and /128 for IPv6.
|  | 202 |
|  | 203 | The ignoreMorespecifics value is used to control whether BGPalerter should ignore activity for routes that are more specific (smaller) than the one that you’re monitoring. For example, if you’re monitoring a /20 and a routing change is detected for a /24 within it, this is considered to be more specific. In most cases, you don’t want to ignore these, however if you are monitoring a large network with multiple delegated customer prefixes, this may help to reduce background noise.
|  | 204 |
|  | 205 | You can now run BGPalerter for the first time in order to begin monitoring your networks:
|  | 206 |
|  | 207 | {{{
|  | 208 | }}}
|  | 209 |
|  | 210 | 1. ./bgpalerter-linux-x64
|  | 211 |
|  | 212 | If BGPalerter starts successfully, you’ll see output similar to the following. Note that it can sometimes take a few minutes for the monitoring to begin:
|  | 213 |
|  | 214 | {{{
|  | 215 | }}}
|  | 216 |
|  | 217 | Output
|  | 218 |
|  | 219 | Impossible to load config.yml. A default configuration file has been generated. BGPalerter, version: 1.24.0 environment: production Loaded config: /home/bgpalerter/config.yml Monitoring 157.230.80.0/20 Monitoring your-ip-address/32 Monitoring AS 14061
|  | 220 |
|  | 221 | BGPalerter will continue to run until you stop it using Ctrl+C.
|  | 222 |
|  | 223 | In the next step, you will interpret some of the alerts that BGPalerter can generate.
|  | 224 |
|  | 225 | == Step 4 — Interpreting BGPalerter Alerts ==
|  | 226 |
|  | 227 | In this step, you will review some example BGPalerter alerts. BGPalerter will output alerts to the main output feed, and also optionally to any additional reporting endpoints that can be configured within config.yml, as described in the [[BGPalerter documentation>>url:https://github.com/nttgin/BGPalerter/blob/master/docs/configuration.md#reports]].
|  | 228 |
|  | 229 | By default, BGPalerter monitors and alerts on the following:
|  | 230 |
|  | 231 | * [[Route hijacks>>url:https://github.com/nttgin/BGPalerter/blob/master/docs/configuration.md#monitorhijack]]: occur when an AS announces a prefix that it is not permitted to, causing traffic to be erroneously routed. This could be either a deliberate attack, or an accidental configuration error.
|  | 232 | * [[Loss of route visibility>>url:https://github.com/nttgin/BGPalerter/blob/master/docs/configuration.md#monitorvisibility]]: A route is considered visible when a majority of BGP routers on the internet are able to reliably route to it. Loss of visibility refers to your network potentially being unavailable, for example if your [[BGP peering>>url:https://en.wikipedia.org/wiki/Border_Gateway_Protocol#Extensions_negotiation]] has stopped working.
|  | 233 | * [[New sub-prefix announcements>>url:https://github.com/nttgin/BGPalerter/blob/master/docs/configuration.md#monitornewprefix]]: is when an AS begins announcing a prefix that is smaller that what is anticipated. This could be indicative of an intended configuration change, an accidental misconfiguration, or in some cases an attack.
|  | 234 | * [[Activity within your AS>>url:https://github.com/nttgin/BGPalerter/blob/master/docs/configuration.md#monitoras]]: will usually refer to new route announcements. A route is considered “new” if BGPalerter doesn’t yet know about it.
|  | 235 |
|  | 236 | Following are some example alerts, along with a short description of their meaning:
|  | 237 |
|  | 238 | Alert #1
|  | 239 |
|  | 240 | {{{The prefix 203.0.113.0/24 is announced by AS64496 instead of AS65540
|  | 241 | }}}
|  | 242 |
|  | 243 | This alert shows evidence of a route hijack, where AS64496 has announced 203.0.113.0/24 when it is expected that this route would be announced by AS65540. This is a strong indicator of a misconfiguration leading to a route leak, or a deliberate hijack by an attacker.
|  | 244 |
|  | 245 | Alert #2
|  | 246 |
|  | 247 | {{{The prefix 203.0.113.0/24 has been withdrawn. It is no longer visible from 6 peers
|  | 248 | }}}
|  | 249 |
|  | 250 | This alert shows that the 203.0.113.0/24 network is no longer visible. This could be because of an upstream routing issue, or a router has suffered a power failure.
|  | 251 |
|  | 252 | Alert #3
|  | 253 |
|  | 254 | {{{A new prefix 203.0.113.0/25 is announced by AS64496. It should be instead 203.0.113.0/24 announced by AS64496
|  | 255 | }}}
|  | 256 |
|  | 257 | This alert shows that a more-specific prefix has been announced where it is not anticipated, for example by announcing a /25 when only a /24 is expected. This is most likely a misconfiguration, however in some cases could be evidence of a route hijack.
|  | 258 |
|  | 259 | Alert #4
|  | 260 |
|  | 261 | {{{AS64496 is announcing 192.0.2.0/24 but this prefix is not in the configured list of announced prefixes
|  | 262 | }}}
|  | 263 |
|  | 264 | Finally, this alert shows that AS64496 has announced a prefix that BGPalerter does not yet know about. This could be because your are legitimately announcing a new prefix, or it could be indicative of a misconfiguration resulting in you accidentally announcing a prefix owned by someone else.
|  | 265 |
|  | 266 | In this step, you reviewed some example BGPalerter alerts. Next, you’ll configure BGPalerter to run automatically at boot.
|  | 267 |
|  | 268 | == Step 5 — Starting BGPalerter at Boot ==
|  | 269 |
|  | 270 | In this final step, you’ll configure BGPalerter to run at boot.
|  | 271 |
|  | 272 | Ensure that you’re still logged in as your new non-privileged user, and then open the crontab editor:
|  | 273 |
|  | 274 | {{{
|  | 275 | }}}
|  | 276 |
|  | 277 | 1. crontab -e
|  | 278 |
|  | 279 |
|  | 280 | Next, add the following entry to the bottom of the crontab file:
|  | 281 |
|  | 282 | crontab
|  | 283 |
|  | 284 | {{{@reboot sleep 10; screen -dmS bgpalerter "./bgpalerter-linux-x64"
|  | 285 | }}}
|  | 286 |
|  | 287 | Every time your system boots, this will create a detached screen session called ‘bgpalerter’, and start BGPalerter within it.
|  | 288 |
|  | 289 | Save and exit the crontab editor. You may now wish to reboot your system in order to make sure that BGPalerter correctly starts at boot.
|  | 290 |
|  | 291 | You’ll first need to log out of your BGPalerter user:
|  | 292 |
|  | 293 | {{{
|  | 294 | }}}
|  | 295 |
|  | 296 | 1. logout
|  | 297 |
|  | 298 |
|  | 299 | Then proceed with a normal system reboot:
|  | 300 |
|  | 301 | {{{
|  | 302 | }}}
|  | 303 |
|  | 304 | 1. sudo reboot
|  | 305 |
|  | 306 |
|  | 307 | Once your system has rebooted, log back in to your server and use su to access your BGPalerter user again:
|  | 308 |
|  | 309 | {{{
|  | 310 | }}}
|  | 311 |
|  | 312 | 1. sudo su bgpalerter
|  | 313 |
|  | 314 |
|  | 315 | You can then attach to the session at any time in order to view the output from BGPalerter:
|  | 316 |
|  | 317 | {{{
|  | 318 | }}}
|  | 319 |
|  | 320 | 1. screen -r bgpalerter
|  | 321 |
|  | 322 |
|  | 323 | In this final step, you configured BGPalerter to run at boot.
|  | 324 |
|  | 325 | == Conclusion ==
|  | 326 |
|  | 327 | In this article you set up BGPalerter and used it to monitor networks for BGP routing changes.
|  | 328 |
|  | 329 | If you wish to make BGPalerter more user-friendly, you can configure it to send alerts to a Slack channel via a webhook:
|  | 330 |
|  | 331 | * [[Configure Slack Reporting for BGPalerter>>url:https://github.com/nttgin/BGPalerter/blob/master/docs/configuration.md#reportslack]]
|  | 332 |
|  | 333 | If you wish to learn more about BGP itself, but do not have access to a production BGP environment, you may enjoy using DN42 to experiment with BGP in a safe, isolated environment:
|  | 334 |
|  | 335 | * [[Decentralized Network 42>>url:https://dn42.us/]]

# Applications

# Tips

Did you know that you can improve XWiki? Take 5 minutes to fill this survey and help this open source project!

Maila Networks
XWiki Debian 14.4.1