Module: badsnakes.py — badsnakes - v0.2.0 Documentation

# 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.

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

    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(path: str = 'badsnakes')

    Create a log file if instructed via the CLI.

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

    Parameters:

      path (str, optional) – Path from which the log’s filename is to be derived. Defaults to ‘badsnakes’.

  _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.