badsnakes Library Documentation
Overview
The badsnakes
project is a CPython library and command line utility
which plugs the gap in malware analysis for Python-based malware by
employing code and syntax analysis, searching for various patterns and
techniques used by threat actors.
After a Python module is analysed, a report can be generated showing the module’s ‘classification’ as OK, SUSPECT or DANGEROUS. If run in verbose mode, each offending statement is displayed to the terminal. Additionally, all SUSPECT and DANGEROUS statements can be written to a log file for further inspection and analysis.
Note
This tool will flag false-positives, as we feel it’s better to fail-safe.
Many lower-level libraries use similar techniques to threat actors by leveraging the inner-workings of the Python language beyond PEP-oriented or production-style code. As such, this is an advisory system designed to highlight statements which may be considered suspect, and worth investigating further.
Toolset
The current toolset enables malware inspection from the following input sources, either as a library, to be imported and wrapped by your own project(s), or as a command line utility.
Directory search
Single or multiple Python modules
Single or multiple Python wheels
For descriptive usage, please refer to the Using the Library or From the Command Line sections.
If you have any questions that are not covered by this documentation, or if you spot any bugs, issues or have any recommendations, please feel free to contact us or raise an issue on GitHub.
Installation
The easiest way to install badsnakes
is using pip
after activating
your virtual environment:
pip install badsnakes
This will install both the library and the command line utility.
Additional (older) releases can be found either at PyPI or in GitHub Releases.
Using the Library
This documentation suite contains detailed explanation and example usage for each of the library’s importable modules. For detailed documentation, usage examples and links the source code itself, please refer to the Libary API Documentation page.
If there is a specific module or method which you cannot find, a search field is built into the navigation bar to the left.
From the Command Line
In addition to being an importable library, badsnakes
is also a
command line utility, capable of analysing, reporting and logging the
following input types:
Directories
Single or multiple Python modules
Single or multiple Python wheels
To call up the help menu, simply type:
$ badsnakes --help
Troubleshooting
No guidance at this time.
Documentation Contents
Indices and Tables
Footnotes
Last updated: 14 Mar 2025