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:

development@s3dev.uk

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

Bases: object

Primary project entry-point and controller class.

__init__()

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()

Start a badsnakes analysis.

Tasks:

• Collect files to be analysed.

• Analyse each collected file.

• Report the overall (worst) classification.

• Create a log file, if instructed by the CLI by the --log argument.

_analyse(path: str)

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()

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 the collect() 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.

_create_log()

Create a log file if instructed via the CLI.

If the --log argument was passed to the CLI, this method will be triggered.

_exclude_directories()

Remove any paths starting in an --exclude_dirs path.

_report_worst_classification()

Report the worst overall classification.

badsnakes.badsnakes.main()

Entry-point exposed for the executable.

The "badsnakes.badsnakes:main" value is set in pyproject.toml’s [project.scripts] table as the entry-point for the installed executable.