{"id":13650703,"url":"https://github.com/AMOSSYS/Fragscapy","last_synced_at":"2025-04-22T18:32:21.729Z","repository":{"id":50917903,"uuid":"207994753","full_name":"AMOSSYS/Fragscapy","owner":"AMOSSYS","description":"Fragscapy is a command-line tool to fuzz network protocols by automating the modification of outgoing network packets. It can run multiple successive tests to determine which options can be used to evade firewalls and IDS.","archived":false,"fork":false,"pushed_at":"2021-05-27T20:01:11.000Z","size":138,"stargazers_count":71,"open_issues_count":3,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-17T09:40:00.299Z","etag":null,"topics":["evasion","firewall","fuzzing","ids","network"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AMOSSYS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-12T07:50:47.000Z","updated_at":"2024-11-04T09:44:25.000Z","dependencies_parsed_at":"2022-08-27T05:11:48.785Z","dependency_job_id":null,"html_url":"https://github.com/AMOSSYS/Fragscapy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AMOSSYS%2FFragscapy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AMOSSYS%2FFragscapy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AMOSSYS%2FFragscapy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AMOSSYS%2FFragscapy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AMOSSYS","download_url":"https://codeload.github.com/AMOSSYS/Fragscapy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250297495,"owners_count":21407222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["evasion","firewall","fuzzing","ids","network"],"created_at":"2024-08-02T02:00:39.655Z","updated_at":"2025-04-22T18:32:21.472Z","avatar_url":"https://github.com/AMOSSYS.png","language":"Python","readme":"# FragScapy\n\nThis project is a command-line tool that can be used to generate\n'fragroute-like' tests using Scapy.  \n[Fragroute](https://www.monkey.org/~dugsong/fragroute/)'s goal was to\nintercept network packets and modify them \"on-the-fly\" according to the\nconfiguration defined in a config file. So automating tests of different\nmodifications, requires to kill Fragroute, write a new config file and restart\nFragroute over and over.  \nFragscapy is a rewrite in Python using `fnfqueue` and `scapy` packages that\naims to generate a test suite based on a config file. In a certain way, it\nwill generates a series of 'fragroute-like' tests and run them consecutively\nwithout having to reload everything. Moreover, the modifications can be\nextended by adding some python modules to the project. So instead of fragroute,\nthe set of possible modifications is not definitive and any modification can be\napplied to packets as long one can write them using Scapy.\n\n\n## Setup\n\n### Building dependencies\n\nThe project requires some tools to be installed. Those are:\n* git  (for cloning the repository)\n* python \u003e= 3.5\n* python-dev \u003e= 3.5  (for building the dependencies with pip)\n* gcc  (for building the dependencies with pip)\n* cffi (for building the dependencies with pip\n* make (for simplification of tasks)\n* pip  (installed by default in a venv)\n\nThe recommended setup is to use a\n[virtual environment](https://docs.python.org/3.5/library/venv.html). Once it\nis started (or not if using a global installation), the Makefile can do most\nof the common tasks.\n\nOn Debian or Ubuntu:\n```bash\napt install -y git python3 python3-dev gcc python3-cffi-backend make python3-venv\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n### Install\n\nTo install fragscapy, run:\n```bash\nmake install\n```\n\n### Development install\n\nFragscapy can be installed in development mode. It means the changes made to\nthe code will be taken into account without the need to rebuild everything\neach time:\n```bash\nmake install-dev\n```\n\n## Documentation\n\nTo build the development documentation, run:\n```bash\nmake build-doc\n```\nIt is then accessible as HTML files under _docs/\\_build/_\n\n\n## Usage\n\nOnce installed, there are 3 ways to access fragscapy features:\n1. Using the command `fragscapy`. It was installed together with the package.\n2. Using the python module directly : `python -m fragscapy`. It is nearly the\n    same as using the command except options can be passed to the python\n    interpreter.\n3. Importing the package in a python interpreter: e.g. ```from fragscapy.mod import ModList```\n\n\n### Command line options\n\nRun `fragscapy [-h | --help]` for displaying the usage.\n\n\n### Configuration files\n\nThe main way (except if using fragscapy as an imported python package) to\nrun a test suite is to describe everything in a config file and pass it to the\ncommand line as an argument.  \nThese config files have a predefined syntax that needs to be respected, else\nerrors will be thrown.\n\nExamples of possible configuration files and templates can be found under the\n[_config\\_examples_ directory](config_examples) and the [_config\\_common_ directory](config_common).\n\nThe command `fragscapy checkconfig` can be used to verify a config file is\nvalid and understandable. It checks that a maximum of operations will run\nwithout errors (but never runs the command itself).\n\n\n### Modifications\n\nVarious modifications are already available but more can be added. To list\nthe modifications that are currently detected (and can be used), run\n`fragscapy list`. For the details about the options and how to use a specific\nmodifications, run `fragscapy usage \u003cmod\u003e`.\n\n\n### Results\n\nAt the end of the tests, a summary of the results is displayed based on the\nexit code of the command: `0` means the test succeeded and any other value\nmeans the test failed. To adapt any command that does not respect this\nconvention, one the following can be appended to the command in the\nconfiguration file:\n```bash\nmy_cmd; if [ $? -eq 4 ]; then return 0; else return 1; fi\nmy_cmd; e=$?; if [ $e -eq 3 ] || [ $e -eq 2 ]; then return 0; else return $e; fi\n```\n\n\n## Adding modifications\n\nAdding a modifications is meant to be as easy as possible: a python module\nneeds to be added to the _fragscapy/modifications/_ directory and that's all,\nit will be detected automatically.  \nHowever, the content of the file needs to respect specific rules to work\ncorrectly:\n1. The name of the file should be the name of the modification using\n    [snake_case](https://en.wikipedia.org/wiki/Snake_case). It is used to\n    import the correct module based on the modification name.\n2. The module should define a class whose name is the name of the modification\n    using [UpperCamelCase/CapWords](https://en.wikipedia.org/wiki/Camel_case).\n    It is used to import the correct object based on the modification name.\n3. This class should subclass `fragscapy.modifications.mod.Mod` class. It is\n    used to define the default behavior and an interface every modification\n    should respect.\n4. This class should override the `__init__(self, *args)` method where `args`\n    contains a list of strings with the options to create the modification\n5. This class should override the `apply(self, pkt_list)` method where\n    `pkt_list` is a `PacketList` object that contains the scapy packets to\n    modify.\nThis is all the rules that need to be respected. Anything else (adding other\nclasses, methods, sumodules, ...) is left to the developer to decide according\nto its needs.\n\nThe already existing mods can be used as a reference on how to develop a mod\nsince they all respect these rules too.\n\n## Code architecture\n\nHere is a schema of how the different objects interact together and what they\nare doing.\n\n![media/architecture.png](media/architecture.png \"The architecture of the project\")\n","funding_links":[],"categories":["Tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAMOSSYS%2FFragscapy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAMOSSYS%2FFragscapy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAMOSSYS%2FFragscapy/lists"}