DDOS simulator
Project description
lib_ddos_simulator
This package contains functionality to simulate, graph, and animate various attack/defense scenarios for DDOS attacks. It is also easily extendable to allow for easy testing of defense techniques. The purpose of this library is to determine which DDOS defense techniques from published literature work the best in practice.
- lib_ddos_simulator
- Description
- Simulation Setup
- Usage
- Installation
- Testing
- Development/Contributing
- History
- Credits
- Licence
- Todo and Possible Future Improvements
- FAQ
- Developer Notes (to be written)
- Simulation Script
- Managers
- Manager (Base class)
- Bounded Manager
- KPO Manager
- Miad Manager
- Protag Manager
- Sieve Manager
- Graphers
- Animater
- Grapher
- Combination_Grapher
- Attackers
- Attacker (Base)
- Basic Attacker
- Lone Attacker
- Even Turn Attacker
- Fifty Percent Attacker
- Ten Percent Attacker
- Wait for x addition Attacker
- Mixed Attacker
- Simulation Objects
- User
- Bucket
- Utils
- Logging
- API
Package Description
There are 6 main sections to this python package. Managers, Graphers, Attackers, Users, API, and Utils. Manager is the term used to describe a defense technique - essentially, the manager of the system. Graphers collect data from the simulation and turn it into a readable format. Attackers contain the different types of attackers. Users contain the different types of users. Utils contains auxiliary functions that may be useful across all categories. The API contains functionality to call the managers shuffle functions.
The simulator is the main script in the package, called ddos_simulator. You can pass several arguments into the simulator that will allow you to run any attack or defense scenario. You can also use the graphers, which call the simulator several times to compare statistics for many scenarios. Usage details below.
Simulation Setup
The simulation works like the following:
- Simulation is initialized with arguments to specify attack/defense scenario (see Usage)
- Users and attackers are shuffled together
- Managers are initialized with the same starting configuration of users
- Each turn, buckets are attacked
- Each turn, the grapher captures the data
- Each turn, the manager detects attackers and shuffles (according to that manager's algorithm
- Each turn, all buckets are reset
- The grapher represents the data after all turns are complete
Assumptions:
- Static set of users
- No maximum capacity to a bucket
- Managers have unlimited number of potential buckets
Usage
There are three ways to run this package. NOTE: greater utility = better manager
- Gather statistics per round (cost, percent serviced, utility (users/bucket), percent detected), for each manager specified
- At the end of all the rounds, gather the utility of the manager and compare it with all other managers
- Animate the simulator for each manager one at a time
- Use the API to manage live users (and protect from DDOS attacks)
Running One Scenario
This way of running the simulator will chart (for each manager) cost, percent serviced, utility, percent detected, etc. for every round.
NOTE: greater utility = better manager
From the command line:
lib_ddos_simulator
with some additional parameters:
lib_ddos_simulator --num_users 9 --num_attackers 1 --num_buckets 3 --debug
Optional command line parameters:
| Parameter | Default | Description |
|---|---|---|
| num_users | 1000 | Number of good users |
| num_attackers | 10 | Number of attackers |
| num_buckets | 100 | Number of buckets |
| threshold | 10 | Threshold for suspicion removal. Legacy code. |
| rounds | 20 | Number of rounds to run |
| debug | False | Display debug info |
| tikz | False | Saves plots as tikz |
| save | False | Stores graphs or shows them |
| high_res | False | Uses higher resolution (slower) |
| graph_dir | "/tmp/lib_ddos_simulator" | graph_dir |
From a script:
Note the optional parameters included below These are all the possible parameters to supply
import logging
from lib_ddos_simulator import DDOS_Simulator, Protag_Manager_Merge, Basic_Attacker
num_users = 10
num_attackers = 1
num_buckets = 5
# Threshold is legacy code
threshold = .1
# All the managers to run. See manager section for a list
manager_child_classes = [Protag_Manager_Merge]
# The following options are the defaults, you can omit
# these or change them if you wish
stream_level = logging.INFO
graph_dir = "/tmp/lib_ddos_simulator"
# The type of attacker. See attacker section for a list
attacker_cls = Basic_Attacker
sim = DDOS_Simulator(num_users,
num_attackers,
num_buckets,
threshold,
manager_child_classes,
stream_level=stream_level,
graph_dir=graph_dir,
attacker_cls=attacker_cls,
save=False,
high_res=False)
# Num rounds can be changed as needed
num_rounds = 10
sim.run(num_rounds)
Running Animations
This way of running the simulator will animate the simulations
WARNING: Don't crash your computer by rendering a simulation that is too heavy. Only show simulations that are small. Only save simulations low resolution (that should also be small).
From the command line:
lib_ddos_simulator --animate
with some additional parameters:
lib_ddos_simulator --num_users 9 --num_attackers 1 --num_buckets 3 --debug --save --high_res
Optional command line parameters:
| Parameter | Default | Description |
|---|---|---|
| num_users | 1000 | Number of good users |
| num_attackers | 10 | Number of attackers |
| num_buckets | 100 | Number of buckets |
| threshold | 10 | Threshold for suspicion removal. Legacy code. |
| rounds | 20 | Number of rounds to run |
| debug | False | Display debug info |
| animate | False | Save animations |
| save | False | Stores graphs or shows them |
| high_res | False | Uses higher resolution (slower) |
| graph_dir | "/tmp/lib_ddos_simulator" | graph_dir |
A note on these parameters:
- If you choose to not save the animations and instead let it run, the animation will have lower dpi and quality because that is meant for debugging purposes. I turned off several moving parts for this to speed things up.
- If you choose to save the animations it will take much longer to run
- If you choose to save the animations with high res, it will take quite a long time depending on the simulation you are running and how many users/buckets you have in your simulation (and how long it takes). Note that when I run this for large simulations, it takes up to 15GB of RAM.
From a script:
Note the optional parameters included below These are all the possible parameters to supply
import logging
from lib_ddos_simulator import DDOS_Simulator, Protag_Manager_Merge, Basic_Attacker
num_users = 10
num_attackers = 1
num_buckets = 5
# Threshold is legacy code
threshold = .1
# All the managers to run. See manager section for a list
manager_child_classes = [Protag_Manager_Merge]
# The following options are the defaults, you can omit
# these or change them if you wish
stream_level = logging.INFO
graph_dir = "/tmp/lib_ddos_simulator"
# The type of attacker. See attacker section for a list
attacker_cls = Basic_Attacker
sim = DDOS_Simulator(num_users,
num_attackers,
num_buckets,
threshold,
manager_child_classes,
stream_level=stream_level,
graph_dir=graph_dir,
attacker_cls=attacker_cls,
save=False,
high_res=False)
# Num rounds can be changed as needed
num_rounds = 10
sim.run(num_rounds, animate=True, graph_trials=False)
Running Manager Comparisons
This way of running the simulator will chart (for each scenario) the utility over all the rounds, and will chart all managers on one plot. The X axis will be percentage of users that are attackers.
Note, higher utility = better manager
From the command line:
lib_ddos_simulator --graph_combos
To display debug info:
lib_ddos_simulator --debug
Optional command line parameters:
| Parameter | Default | Description |
|---|---|---|
| debug | False | Display debug info |
| tikz | False | Saves plots as tikz |
| save | False | Stores graphs or shows them |
| high_res | False | Uses higher resolution (slower) |
| graph_dir | "/tmp/lib_ddos_simulator" | graph_dir |
| trials | 50 | Number of trials to run |
From a script:
Note the optional parameters included below These are all the possible parameters to supply
import logging
from lib_ddos_simulator import Combination_Grapher, Sieve_Manager_Base, Attacker
# stream_level and graph_path defaults, can be omitted
grapher = Combination_Grapher(stream_level=logging.INFO,
graph_dir="/tmp/lib_ddos_simulator",
tikz=False,
save=False,
high_res=False)
# For the full list of managers that is run by default, see Managers section
grapher.run(managers=Sieve_Manager_Base.runnable_managers,
attackers=Attacker.runnable_attackers,
num_buckets_list=[10],
users_per_bucket_list=[10 ** i for i in range(1,3)],
num_rounds_list=[10 ** i for i in range(1,3)],
trials=50)
# NOTE: If you are confused by these lists, what gets graphed is essentially:
# for num_buckets in num_buckets_list:
# for users_per_bucket in users_per_bucket_list:
# for num_rounds in num_rounds_list:
# for attacker in attackers:
# generate_graph(managers, trials)
API
Runs a STATEFUL API. Note that this should NEVER be run in a production environment. Also note that you use this AT YOUR OWN RISK. Just assume it's broken.
To see commands, go to http://localhost:5000/apidocs/
From the command line:
lib_ddos_simulator --api
To display debug info:
lib_ddos_simulator --debug
From a script:
from lib_ddos_simulator import create_app
create_app().run(debug=False)
I don't want to duplicate documentation, so to see endpoints, go to http://localhost:5000/apidocs/
Installation
As far as system requirements goes, I run this off my laptop. The more cores, the faster the combination_grapher will run, although it only parallelizes by scenario. I use Linux, it's possible it will work on other OSes, although the graph paths would probably have to be changed.
Install python and pip if you have not already. Then run:
pip3 install wheel
pip3 install lib_ddos_simulator
This will install the package and all of it's python dependencies.
If you want to install the project for development:
git clone https://github.com/jfuruness/lib_ddos_simulator.git
cd lib_ddos_simulator
pip3 install wheel
pip3 install -r requirements.txt --upgrade
python3 setup.py develop
Note that if you plan on doing animations, make sure to do:
sudo apt-get install ffmpeg
To test the development package, cd into the root directory and run pytest. To test from pip install:
pip3 install wheel
pip3 install lib_ddos_simulator --install-option test
Testing
You can test the package if in development by moving/cd into the directory where setup.py is located and running:
sudo python3 setup.py test
To test a specific submodule, run pytest --markers. Then you can run pytest -m <submodule_name> and only tests from that submodule will be run.
Also note that slow tests are marked as slow. So you can not run slow tests by doing pytest -m "not slow".
All the skipped tests are for the interns to fill in. I have completed these tests manually and am confident they will succeed, and I have been told by my bosses to move on to other tasks.
To test from pip install:
pip3 install wheel
pip3 install lib_ddos_simulator --install-option test
Development/Contributing
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request
- Email me at jfuruness@gmail.com because idk how to even check those messages
Adding a Manager
To be written
Adding an Attacker
To be written
History
- lib_ddos_simulator
- 0.0.3
- README updates
- default trial change
- logging removed due to inhibiting mp
- animation resolution fixed, animation bug where users don't go into buckets fixed
- 0.0.2 - Fixed bug where it always through pytest was running - multiprocessing now works correctly. Moved conftest.py and added other credits.
- 0.0.1 - Added APIs, multiple managers, animations, etc
- 0.0.0 - Basic simulation capabilities, no API
- 0.0.3
Credits
Many thanks to Anna Gorbenko for helping code the managers with me as well as other parts of this library, as well as lots of DDOS theory
Many thanks to Amir Herzberg for direction in research and help with DDOS theory as well as coming up with many improvements
HUGE Credits to Cameron Morris for helping me fix video resolution problems
Thanks to the Nikhil for working with us to test out the API portion of this library for deployment
Many thanks to all the stack overflow questions and sites that have helped in development of this package:
- https://stackoverflow.com/a/16910957/8903959
- https://stackoverflow.com/a/4701285/8903959
- https://stackoverflow.com/a/48958260/8903959
- https://matplotlib.org/3.1.0/gallery/lines_bars_and_markers/gradient_bar.html
- https://stackoverflow.com/a/43057166/8903959
- http://matplotlib.1069221.n5.nabble.com/How-to-turn-off-matplotlib-DEBUG-msgs-td48822.html
- https://matplotlib.org/3.1.1/gallery/text_labels_and_annotations/custom_legends.html
- https://riptutorial.com/matplotlib/example/32429/multiple-legends-on-the-same-axes
- https://stackoverflow.com/a/26305286/8903959
- https://stackoverflow.com/a/1987484/8903959
- https://stackoverflow.com/a/14666461/8903959
- https://stackoverflow.com/a/58866220/8903959
- https://stackoverflow.com/a/29127933/8903959
- https://medium.com/@george.shuklin/mocking-complicated-init-in-python-6ef9850dd202
- https://flask.palletsprojects.com/en/1.1.x/testing/
Also thanks to the pathos library. Amazing way to multiprocess.
License
Four Clause BSD License (see license file)
TODO/Possible Future Improvements
See Jira Board
FAQ
Q: More links to some research
Developer Notes
TO BE WRITTEN
For later
- api is stateful due to complexity of the managers
- You must call the api at equivalent intervals, even if no buckets where attacked to track user stats
- NEVER append or manipulate in any way self.buckets. Use self.get_new_bucket() to get a new bucket. To reset, set the users to be []. Use self.used_buckets. Never remove empty buckets. Never add new ones.
- Never remove or create buckets - call self.get_new_bucket()
- Never remove or create users - move to self.eliminated_users
- If logging isn't here, it was removed due to mp issues
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for lib_ddos_simulator-0.0.3b0.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | e9c3ab7246148a69e41beaba9ea10760240df677a54dfa381657677162f7824c |
|
| MD5 | beedd4cda7be3a02757b0800928a2ffa |
|
| BLAKE2b-256 | d4df67697439457095051e1a7aa60c05627b6acb6c0e7993174b62043eb9ff3d |
Hashes for lib_ddos_simulator-0.0.3b0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f7b14ad9e552e74c448fd1fc99d9634a131408a32a4aa40961b1b4656a3c0796 |
|
| MD5 | ca69a7c1b878a7484db65d5e669e9798 |
|
| BLAKE2b-256 | f01d87f06796da6edf2cb36c73722cf0a9a45a87b564c2fc4eb5d8145608e7c0 |
