Software Defined Network Situational Awareness
This challenge is a joint challenge between two IQT Labs: Lab41 and Cyber Reboot. Current software defined network offerings lack tangible security emphasis much less methods to enhance operational security. Without situational awareness and context, defending a network remains a difficult proposition. This challenge will utilize SDN and machine learning to determine what is on the network, and what is it doing. This goal will help sponsors leverage SDN to provide situational awareness and better defend their networks.
Poseidon currently supports two different SDN controllers, Big Cloud Fabric and FAUCET.
Before getting started, one of these two controllers needs to running and accessible to where Poseidon will be deployed. Skip to the controller section that you wish to deploy.
You will need to add support for moving arbitrary endpoint data around your network. The BigSwitch config will need an admin who will need to add:
- span-fabric
- interface-group
! span-fabric
span-fabric vent
active
destination interface-group ig1
priority 1
! interface-group
interface-group ig1
description 'packets get mirrored here to be processed'
mode span-fabric
member switch YOUR_LEAF_SWITCH interface YOUR_INTERFACE_WHERE_VENT_WILL_RECORD_TRAFFIC_FROM
If the interface-group ig1 is reserved in your install, you will need to modify dest-interface-group in:
poseidon/poseidonMonitor/NorthBoundControllerAbstraction/proxy/bcf/bcf.py: "dest-interface-group": "ig1",
poseidon/poseidonMonitor/NorthBoundControllerAbstraction/proxy/bcf/sample_state.py: "dest-interface-group": "ig1",
If the span-fabrc vent is reserved in your install, you will need to modify the span_name, and other variables in:
/poseidon/poseidonMonitor/NorthBoundControllerAbstraction/proxy/bcf/bcf.py
/poseidon/poseidonMonitor/NorthBoundControllerAbstraction/proxy/bcf/test_bcf.py
/poseidon/poseidonMonitor/NorthBoundControllerAbstraction/proxy/bcf/sample_state.py
Poseidon will connect to BCF using its REST API, so you'll need the API endpoint and credentials to it. The easiest way to set these values so that Poseidon can use them is in environment variables like so (assuming the controller is running at 192.168.1.10):
export controller_type=bcf
export controller_uri=https://192.168.1.10:8443/api/v1/
export controller_user=user
export controller_pass=pass
BCF is now configured and ready for use with Poseidon, continue on to the Starting Poseidon using Vent section.
Unless Poseidon and FAUCET are running on the same host, Poseidon will connect to FAUCET using SSH. So you'll need to create an account that can SSH to the machine running FAUCET and that has rights to modify the configuration file faucet.yaml (currently Poseidon expects it to be in the default /etc/ryu/faucet/faucet.yaml location and dps must all be defined in this file for Poseidon to update the network posture correctly). The easiest way to set these values so that Poseidon can use them is in environment variables like so (assuming the controller is running at 192.168.1.10):
export controller_type=faucet
export controller_uri=192.168.1.10
export controller_user=user
export controller_pass=pass
export controller_log_file=/var/log/ryu/faucet/faucet.log
export controller_config_file=/etc/ryu/faucet/faucet.yaml
export controller_mirror_ports='{"switch1":3}' # a python dictionary of switch names (from faucet.yaml) and switch port numbers for mirroring to
If Poseidon and FAUCET are running on the same host, the controller_uri, controller_user and controller_pass do not need to be set.
FAUCET is now configured and ready for use with Poseidon, continue on to the Starting Poseidon using Vent section.
Vent is a platform we built to automate network collection and analysis pipelines, such as the ones that Poseidon would need. Leveraging Vent, we can specify all of the actions we expect Poseidon to be able to do from network event (i.e. new device plugged in), to network capture, to analysis, and closing the loop by feeding back an actionable decision.
In order to run Poseidon in Vent, regardless of the SDN controller chosen, a few additional environment variables need to be set:
export collector_nic=eth0 # set the NIC of the machine that traffic will be mirrored to
export max_concurrent_reinvestigations=1 # if running FAUCET, this should be set to 1, if BCF, it can be a larger number
Start Vent with:
./helpers/run
Once Vent is finished starting things up, you'll be able to see the logs of everything, including Poseidon by running:
docker logs -f cyberreboot-vent-syslog-master
If you quit out of the vent container, you can start it again with:
docker start vent
And then attach to the console with:
docker attach vent
- Note: if use Docker for Mac, you'll need to create a directory
/opt/vent_filesand add it to shared directories in preferences.
If you prefer to orchestrate all of the pieces for Poseidon yourself without Vent, then follow these directions:
git clone https://github.com/CyberReboot/poseidon.git
cd poseidon
*editor* config/poseidon.config
docker build -f ./Dockerfile.poseidon -t poseidon .
docker run poseidon
config/poseidon.config
[Monitor]
rabbit_server = RABBIT_SERVER # ip address of the rabbit-mq server
rabbit_port = RABBIT_PORT # rabbit-mq server server port
collector_nic = COLLECTOR_NIC # name of the network interface that will be listening for packets
vent_ip = vent_ip # ip address of server running vent
vent_port = VENT_PORT # vent server port
[NorthBoundControllerAbstraction:Update_Switch_State]
controller_uri = https://CONTROLLER_SERVER:8443/api/v1/ # example for BCF controller ip
controller_user = USERNAME # username for BCF login
controller_pass = PASSWORD # password for BCF login
controller_type = CONTROLLER # either `bcf` or `faucet`
You can use make to simplify the building process. This is primarily useful for development.
To build the container, simply run:
git clone https://github.com/CyberReboot/poseidon.git
cd poseidon
make build_poseidon
To build and run the container, run this command from inside the poseidon directory:
make run_poseidon
This first builds poseidon, then runs it. After it finishes running, the container is removed.
To populate the current volume with the contents of the containers' "poseidonWork/" directory, run:
make run_dev
To run poseidon with sh as entrypoint, run:
make run_sh
This also removes the container after it has finished running.
If you want to build the docs, then invoke:
make build_docs
To build and then open the docs in a container on port 8080:
make run_docs
To run tests:
make run_tests
Tests are currently written in py.test for Python. The tests are automatically run when opening Pull Requests to Poseidon.
Want to contribute? Awesome! Issue a pull request or see more details here.
See also the list of contributors who participated in this project.
This project is licensed under the Apache License - see the LICENSE.md file for details