Awesome
FragScapy
This project is a command-line tool that can be used to generate
'fragroute-like' tests using Scapy.
Fragroute's goal was to
intercept network packets and modify them "on-the-fly" according to the
configuration defined in a config file. So automating tests of different
modifications, requires to kill Fragroute, write a new config file and restart
Fragroute over and over.
Fragscapy is a rewrite in Python using fnfqueue
and scapy
packages that
aims to generate a test suite based on a config file. In a certain way, it
will generates a series of 'fragroute-like' tests and run them consecutively
without having to reload everything. Moreover, the modifications can be
extended by adding some python modules to the project. So instead of fragroute,
the set of possible modifications is not definitive and any modification can be
applied to packets as long one can write them using Scapy.
Setup
Building dependencies
The project requires some tools to be installed. Those are:
- git (for cloning the repository)
- python >= 3.5
- python-dev >= 3.5 (for building the dependencies with pip)
- gcc (for building the dependencies with pip)
- cffi (for building the dependencies with pip
- make (for simplification of tasks)
- pip (installed by default in a venv)
The recommended setup is to use a virtual environment. Once it is started (or not if using a global installation), the Makefile can do most of the common tasks.
On Debian or Ubuntu:
apt install -y git python3 python3-dev gcc python3-cffi-backend make python3-venv
python3 -m venv venv
source venv/bin/activate
Install
To install fragscapy, run:
make install
Development install
Fragscapy can be installed in development mode. It means the changes made to the code will be taken into account without the need to rebuild everything each time:
make install-dev
Documentation
To build the development documentation, run:
make build-doc
It is then accessible as HTML files under docs/_build/
Usage
Once installed, there are 3 ways to access fragscapy features:
- Using the command
fragscapy
. It was installed together with the package. - Using the python module directly :
python -m fragscapy
. It is nearly the same as using the command except options can be passed to the python interpreter. - Importing the package in a python interpreter: e.g.
from fragscapy.mod import ModList
Command line options
Run fragscapy [-h | --help]
for displaying the usage.
Configuration files
The main way (except if using fragscapy as an imported python package) to
run a test suite is to describe everything in a config file and pass it to the
command line as an argument.
These config files have a predefined syntax that needs to be respected, else
errors will be thrown.
Examples of possible configuration files and templates can be found under the config_examples directory and the config_common directory.
The command fragscapy checkconfig
can be used to verify a config file is
valid and understandable. It checks that a maximum of operations will run
without errors (but never runs the command itself).
Modifications
Various modifications are already available but more can be added. To list
the modifications that are currently detected (and can be used), run
fragscapy list
. For the details about the options and how to use a specific
modifications, run fragscapy usage <mod>
.
Results
At the end of the tests, a summary of the results is displayed based on the
exit code of the command: 0
means the test succeeded and any other value
means the test failed. To adapt any command that does not respect this
convention, one the following can be appended to the command in the
configuration file:
my_cmd; if [ $? -eq 4 ]; then return 0; else return 1; fi
my_cmd; e=$?; if [ $e -eq 3 ] || [ $e -eq 2 ]; then return 0; else return $e; fi
Adding modifications
Adding a modifications is meant to be as easy as possible: a python module
needs to be added to the fragscapy/modifications/ directory and that's all,
it will be detected automatically.
However, the content of the file needs to respect specific rules to work
correctly:
- The name of the file should be the name of the modification using snake_case. It is used to import the correct module based on the modification name.
- The module should define a class whose name is the name of the modification using UpperCamelCase/CapWords. It is used to import the correct object based on the modification name.
- This class should subclass
fragscapy.modifications.mod.Mod
class. It is used to define the default behavior and an interface every modification should respect. - This class should override the
__init__(self, *args)
method whereargs
contains a list of strings with the options to create the modification - This class should override the
apply(self, pkt_list)
method wherepkt_list
is aPacketList
object that contains the scapy packets to modify. This is all the rules that need to be respected. Anything else (adding other classes, methods, sumodules, ...) is left to the developer to decide according to its needs.
The already existing mods can be used as a reference on how to develop a mod since they all respect these rules too.
Code architecture
Here is a schema of how the different objects interact together and what they are doing.