# NCDS - Network Cyber Deception System #

Please make sure that you have Python, Scapy, POX and Mininet installed on your Linux system.

# Before you start

Make sure that the virtual network view config file config.conf is located at /home/mininet/config.conf
The SDN Controller and the Deception Server will read this file on startup to load a virtual network view.
The config file has to point to a virtual network view file, the default value is /home/mininet/Desktop/nv.nv
Network view files (e.g. nv.nv) can be written manually or auto-generated with our Virtual View Generator.
A network view file (*.nv) contains the information ncessary to simulate a virtual network view.

The following values are stored in network view file. Each line in a *.nv file starts with a component name.
A list of components for a virtual network view are: #Target, #Node, #Honeypot, #Honeyrouter, #Route, #Gateyway

The components are explained in detail as follows:

----------------------------------------
Target: The node in a network that has the current virtual network view applied to. A target node is configured as follows:
#Target,#Shortname,#DeceptiveIP,#RealMAC,#PortOnSDNSwitch

Example:
Target,h1,10.0.3.220,00:00:00:00:00:02,2

Only one target node can exists in a view file.

----------------------------------------
Node: A node component specifies all the other real hosts that are accessible by the target node. It is configured as follows:
#Node,#Shortname,#RealIP,#DeceptiveIP,#RealMAC,#PortOnSDNSwitch

Example:
Node,h2,10.0.0.3,10.0.1.229,00:00:00:00:00:03,3

Multiple nodes can exists in a network view.

----------------------------------------
Honeypot: A honeypot specifies a fake node which acts as a trap for adversarial scanners.
A honeypot points to a port where a real end host is located that acts as a honeypot. Multiple honeypots in a network view can point to the same physical honeypot. A honeypot is configured as follows:

#Honeypot,#Shortname,#RealIP,#DeceptiveIP,#RealMAC,#DeceptiveMAC,#PortOnSDNSwitch

Example:
Honeypot,hp2,10.0.0.5,10.0.1.24,00:00:00:00:00:05,b4:fb:5e:6c:2f:14,5 

Multiple honeypots can exists in a network view.

----------------------------------------
Honeyrouter: Honeyrouters specify virtual routers that connect nodes and honeypots in a virtual network view.
Multiple hops between nodes in a virtual network can be simulated with honeyrouters. A honeyrouter always has to point to the port on an SDN switch where the deception server is located.
A honeyrouter is configured as follows:

#Honeyrouter,#Shortname,#DeceptiveIP,#DeceptiveMAC,#PortToDeceptionServer

Example:
Honeyrouter,hr1,10.0.3.1,4a:87:71:13:c8:43,1

Multiple honeyrouters can exists in a network view.

----------------------------------------
Route: A route specifies the topological path between different hosts in a network view.
A route can be configured as follows:

#Route,#ShortnameOfStartNode,#ShortnameOfEndNode,[#Honeyrouter1, #Honeyrouter2,...]

A route has to consist of a start node, which can be a #Target, #Node or #Honeypot and 0 or more #Honeyrouters on the path between them.

Example:
Route,h1,h2,hr1,hr2

Multiple routes can exists in a network view.

----------------------------------------
Gateway: The gateway specifies the #Honeyrouter how the subnet where the #Target is located is connected to the rest of the virtual network. A gateway can be configured by pointing to the #Honeyrouter of the subnet of the target node:

#Gateway, #HoneyrouterOfTargetSubnet

Example:
Gateway,hr1

One one gateway can exist in a network view.

----------------------------------------

After a network view file is configured the system can be started as follows:

### Start the SDN Controller ###

Copy the SDN Controller directory into the POX folder (e.g. /home/mininet/pox/pox/SDNController_ncds)
With the following command the SDN controller has to be started on a terminal: "./pox.py log.level --DEBUG SDNController_ncds.Controller"
Here "SDNController_ncds" is the directory of the NCDS SDN controller, "Controller" is the python file of the NCDS SDN controller. 

### Start the deception server ###

To begin the Mininet network emulator has to be started. As an example the command "sudo mn --topo=single,12 --mac --controller=remote" Mininet starts emulating a network with a single SDN switch and 12 nodes. The controller is specified as remote and will automatically connect with the POX NCDS SDN controller. The option --mac will set the MAC addresses of nodes in increasing order starting at "00:00:00:00:00:01". By default the IP address of nodes in Mininet is starting at "10.0.0.1" and increasing.

After Mininet is started and connected to the SDN NCDS controller, the controller will automatically start reading the network view file and loading the appropriate SDN flow rules into the SDN switch of the subnet where the target node is located.

In a Mininet-Environment, the deception server has to be started at the node which is located on port 1 of the SDN switch (this option can be changes in the source code). The deception server has to be started with root privileges. To start the deception server in the terminal of the node located at port 1 type for example: "/home/mininet/DeceptionServer# python main.py"

After the server is running a terminal at the target node, e.g. node that is located on port 2 of the SDN switch, has to request a DHCP lease to be able to connect to the network. This should be done by executing the following commands on the node located on port 2: "dhclient -r" (will release the current DHCP lease), "dhclient h2-eth0" (will request a new DHCP lease from the deception server at the specified network interface (here "h2-eth0").

Now the network will appear to the target node as specified in the network view file. This can be evaluated by scanning the network with a tool like NMAP (or ZenMAP to visualize the virtual topology). To map a virtual network, as specified in our example view file "nv.nv" ZenMAP can be started with the following command: "nmap -T4 -A -v --traceroute 10.0.1.0/24 10.0.2.0/24 10.0.3.0/24"

The target node is able to connect to the specified #Nodes in the same way as in a normal network.

### Generate Virtual Network View Files ###

Before a network view file can be auto-generated, it has to be specified in the "Main.py" file, located in the "/ViewGenerator" directory.

The following code specifies a virtual network view file:

-------------------------------------------------------------
RealHosts={}
RealHosts[1]="10.0.0.1/00:00:00:00:00:01"
RealHosts[2]="10.0.0.2/00:00:00:00:00:02"
RealHosts[3]="10.0.0.3/00:00:00:00:00:03"
RealHosts[4]="10.0.0.4/00:00:00:00:00:04"
RealHosts[5]="10.0.0.5/00:00:00:00:00:05"
RealHosts[6]="10.0.0.6/00:00:00:00:00:06"
RealHosts[7]="10.0.0.7/00:00:00:00:00:07"
RealHosts[8]="10.0.0.8/00:00:00:00:00:08"
RealHosts[9]="10.0.0.9/00:00:00:00:00:09"
RealHosts[10]="10.0.0.10/00:00:00:00:00:0a"
RealHosts[11]="10.0.0.11/00:00:00:00:00:0b"
RealHosts[12]="10.0.0.12/00:00:00:00:00:0c"

SubnetSpace="10.0.1"

TargetPort=2
NCDSPort=1
HoneyPotPort=5
NumberSubnets=3
MinNumHoneyPotsInSubnet=10
MaxNumHoneyPotsInSubnet=15
MaxSubnets=48
MaxHosts=255 
-------------------------------------------------------------

A view starts with a list of IP and MAC addresses of real hosts that will be accessible in a virtual network view.
The "SubnetSpace" variable specifies to subnetwork prefix of a subnet in the virtual network view (starting with first subnet prefix).
The "TargetPort" variable specifies the port on the SDN switch the target node is located at.
The "NCDSPort" specifies the switch port of the Deception Server.
The "HoneyPotPort" specifies the switch port where the honeypot traffic is routed to.
The "NumberSubnets" specifies how many subnets will be simulated in a virtual network view.
The "MinNumHoneyPotsInSubnet" and "MaxNumHoneyPotsInSubnet" specfies a range of how many honeypots should be located in each virtual subnet.
The "MaxSubnets" variable specifies the maximum IP address prefix of a sunbet address, for example MaxSubnets=48 specifies a maximum subnet address of "10.0.48.0/24" in the given example (255 is the maximum value for this variable).
The "MaxHost" variable specifies the maximum address number of a deceptive host IP address that will be assigned to a host in a virtual network view. For example MaxHosts=255 would result in a maximum IP address of "10.0.48.255" in the given example (255 is the maximum value for this variable).