Add README for the BGP hijacking demo

CONTRIBUTING.md

@@ -11,15 +11,16 @@ others and perhaps some accompanying lessons.
 Adding a new topology is straightforward.
 
 1. Create a new directory in the `topology` directory.
-2. Create a `topo.py` file and define a class `NetTopo` that inherits from
+2. Create an empty `__init__.py` file in the new directory.
+3. Create a `topo.py` file and define a class `NetTopo` that inherits from
    `mininet.topo.Topo` and build your new topology in its constructor.
    `WARNING:` Mininet will number the interfaces according to the order they
    are added to a given node.  Make sure the `README.md` reflects this.
-3. Create a `zebra` directory and populate it with configuration files for the
+4. Create a `zebra` directory and populate it with configuration files for the
    `zebra` daemon to configure the interfaces in your topology.
-4. Create a `staticd` directory and populate it with configuration files for
+5. Create a `staticd` directory and populate it with configuration files for
    the `staticd` daemon to configure the default routes on hosts.
-5. Create a `README.md` file to describe your topology.
+6. Create a `README.md` file to describe your topology.
 
 The easiest way to start would be to copy some other topology and customise it
 as appropriate.  Once ready, the topology should be automatically detected by
@@ -31,9 +32,10 @@ By default all topologies support the `plain` and `basic` scenarios.  Adding a
 additional scenarios is also pretty straightforward.
 
 1. In the topology's directory, make sure there is a `scenario` directory.
-   Create one if it doesn't exist.
+   Create one if it doesn't exist.  If you had to create the directory, add an
+   empty `__init__.py` file to it.
 2. In the `scenario` directory create a new directory for your specific
-   scenario.
+   scenario.  Add an empty `__init__.py` file to it.
 3. In your new directory create one directory for each daemon you intend to
    run.  You don't need to do this for `zebra` or `staticd` unless you want to
    override the topology defaults.

README.md

@@ -5,6 +5,10 @@ It uses the [Free Range Routing (FRR)](https://frrouting.org/) protocol
 implementations running on top of a network setup locally using
 [Mininet](http://mininet.org/).
 
+This project was inspired by [Vimal Kumar's BGP hijacking
+demo](https://bitbucket.org/jvimal/bgp) from the [Mininet
+Wiki](https://github.com/mininet/mininet/wiki/BGP-Path-Hijacking-Attack-Demo).
+
 ## Introduction
 
 ### Motivation
@@ -219,12 +223,14 @@ additionally starts up `zebra` and `staticd` to configure addresses and default
 routes.
 
 Scenarios are defined for a particular topology and thus they can be found in
-the `scenario` directory within the topology directories.  There is no python
-code associated with a scenario, only FRR configuration files.  Each scenario
+the `scenario` directory within the topology directories.  Each scenario
 (excluding the special ones) should have a directory in the `scenario`
 directory.  Within the particular scenario directory, each daemon that is to be
 run must have a its own directory.  The configuration files should be created
 in the appropriate daemon directory with the name `<node_name>.conf`.
+Scenarios may also have an optional `scenario.py` file for a given scenario in
+which a `script` function should be defined.  This function is then run after
+Mininet and FRR are started and just before handing control over to the user.
 
 The `zebra` and `staticd` daemons are special and have their own directories
 directly in the topology directory.  If a scenario has its own `zebra` and/or

topology/line_03_and_rogue/scenario/bgp_hijack/README.md

@@ -0,0 +1,94 @@
+# BGP Path Hijacking Attack Demo
+
+This demo is entirely taken from the [Mininet
+Wiki](https://github.com/mininet/mininet/wiki/BGP-Path-Hijacking-Attack-Demo)
+and modified to run in Route 0.  All credit for this demo go to the authors of
+the Mininet Wiki entry and its [code](https://bitbucket.org/jvimal/bgp).
+
+You can read more about what BGP hijacking is and how the demo works on the
+[Mininet
+Wiki](https://github.com/mininet/mininet/wiki/BGP-Path-Hijacking-Attack-Demo)
+entry.  This `README.md` only adapts the step-by-step instructions from the
+Wiki to work with the Route 0 framework.
+
+## Demo Instructions
+
+### Step 1
+
+1. Go into your `route0` repository.
+2. Start the `bgp_hijack` scenario with
+
+```
+sudo python route0.py --topology line_03_and_rogue --scenario bgp_hijack
+```
+
+Keep this shell running throughout this demonstration.
+
+### Step 2
+
+1. In another terminal, let's start a session with AS1's routing daemon:
+
+```
+sudo python attach.py --node R1 --daemon bgpd
+```
+
+The password is `route0`.
+
+### Step 3
+
+Let's see AS1's routing entries by typing the command `sh ip bgp`.
+
+Notice that on AS1, the chosen AS path to reach 13.0.0.0/8 is "2 3" (i.e., via
+AS2 and AS3).
+
+### Step 4
+
+Keep the above shell running in a separate window.  Now, let's visit a default
+web server that Mininet started in AS3 and verify that we can reach it from
+host h1_1 connected to AS1. We're going to run the command "curl -s 13.0.1.1"
+from AS1 in a loop. We have created a script `website.sh` that does this for
+you automatically:
+
+```
+topology/line_03_and_rogue/scenario/bgp_hijack/website.sh
+```
+
+### Step 5
+
+Now, in another window, let us start the rogue AS using the command
+
+```
+topology/line_03_and_rogue/scenario/bgp_hijack/start_rogue.sh
+```
+
+The rogue AS will connect to AS1 and advertise a route to 13.0.0.0/8 using a
+shorter path (i.e., a direct path from AS1 to AS4).  Thus, AS1 will choose this
+shorter path by default.
+
+After some time (for BGP convergence), you should see the output of
+`website.sh` script change to the attacker's message.
+
+You can also inspect the routing table using the shell you started in step 2.
+If the shell closed (due to inactivity), you can start it again (see step 2).
+You can see AS4's chosen path and also AS3's path in the routing information
+base of AS1.  Since the AS path length to reach 13.0.0.0/8 is smaller through
+AS4, R1 chooses AS4 as its next hop.
+
+### Step 6
+
+You can stop the attack by killing R4's routing daemon
+
+```
+topology/line_03_and_rogue/scenario/bgp_hijack/stop_rogue.sh
+```
+
+You will notice that convergence is quick: the traffic is almost immediately
+redirected to the legitimate web server.
+
+### Step 7
+
+You can stop the experiment by typing `exit` at the Mininet prompt, Control-C
+in the window where you started the website, and type `exit` in the terminal
+where you connected to R1's terminal.
+
+That's it!