Module: badsnakes.py
This module provides the primary interface and processing controller for
the badsnakes
command line utility.
- App:
badsnakes
- Purpose:
The badsnakes project is designed to help detect malware in Python projects.
The project accepts the following formats for analysis:
Directories
Python modules
Python wheels
- Platform:
Linux/Windows | Python 3.10+
- Developer:
J Berendt
- Email:
- Comments:
n/a
- Examples:
Example for analysing a single module:
>>> from badsnakes.libs.module import Module >>> from badsnakes.libs.reporter import ReporterModule >>> path = '/path/to/project/module.py' >>> # Analyse the module. >>> m = Module(path=path) >>> m.analyse() >>> # Report the findings. >>> r = ReporterModule(modules=[m]) >>> r.report()
Example for analysing multiple modules:
>>> import os >>> from glob import glob >>> from badsnakes.libs.module import Module >>> from badsnakes.libs.reporter import ReporterModule >>> modules = [] >>> paths = glob(os.path.join('/.../site-packages/pip/_internal/', '*.py')) >>> # Call Module.analyse for each path and store each module object. >>> for path in paths: >>> m = Module(path=path) >>> m.analyse() >>> modules.append(m) >>> # Report all findings at once. >>> r = ReporterModule(modules=modules) >>> r.report()
Example for analysing a Python wheel:
>>> from badsnakes.libs.collector import Collector >>> from badsnakes.libs.module import Module >>> from badsnakes.libs.reporter import ReporterModule >>> modules = [] >>> path = '../dist/badsnakes-0.1.0-py3-none-any.whl' >>> # Collect all non-binary files from thw wheel. >>> c = Collector(paths=path) >>> c.collect() >>> for pkg in c.files: >>> # Call Module.analyse for each path and store each module object. >>> for path in pkg: >>> # Analyse the module. >>> m = Module(path=path) >>> m.analyse() >>> modules.append(m) >>> # Report the findings. >>> r = ReporterModule(modules=modules) >>> r.report()
- class badsnakes.badsnakes.BadSnakes[source]
Bases:
object
Primary project entry-point and controller class.
- __init__()[source]
BadSnakes class initialiser.
- Attrs:
_clf: Maximum classification from all files analysed. This is reported at the end.
_files: List of files to be analysed. This same list is used for all analysis types and is populated by the
_collect_files()
method._modules: List of modules analysed. If logging is invoked, this list of modules is given to the logger.
- main()[source]
Start a badsnakes analysis.
- Tasks:
Collect files to be analysed.
Determine if specific or generic logging should be used.
Analyse each collected file.
Report the overall (worst) classification, per package.
Create a log file, if instructed by the CLI by the
--log
argument.
- _analyse(path: str)[source]
Analyse the provided module file.
- Parameters:
path (str) – Full path to the file to be analysed.
- Tasks:
Create a
Module
object and analyse.Report the findings (verbose/non-verbose).
Set the maximum (worst) classification.
- _collect_files()[source]
Collect all files to be analysed.
This method is used to populate the
_files
attribute, which contains the files to be analysed.- Logic:
Create an instance of the
badsnakes.libs.collector.Collector
class and call thecollect()
method.The Collector class is designed to 1) identify the input type, and 2) return the associated file(s).
The list of files returned by the collector is assigned to the
_files
attribute.Finally, any paths listed by the
--exclude_dirs
argument are removed from the_files
list.
This method must store the collector into a class attribute to preserve the life of the wheel collector’s temporary directory object.