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

# Module: parser.py

Purpose:

  This module provides the functionality for parsing a module into an abstract syntax tree for analysis.

  The primary parsing work is carried out by the builtin `ast.parse()` method.

Platform:

  Linux/Windows | Python 3.10+

Developer:

  J Berendt

Email:

  development@s3dev.uk

Comments:

  n/a

Example:

  Example code use:

      >>> from badsnakes.libs.parse import Parser

      >>> p = Parser()
      >>> p.parse(path='hello.py')

      # Access the abstract syntax tree.
      >>> p.ast_
      <ast.Module at 0x123456789012>

      # Access the code's text stream.
      >>> p.code
      <_io.StringIO at 0x123456789000>

class badsnakes.libs.parser.Parser

  Bases: `object`

  Using the `ast` built-in, parse a module’s code into its various elements.

  AST elements which are used for code analysis are:

  > - Arguments: Arguments which are passed into function calls.

  >   - Generally used to detect base64 strings (or the like) being passed into functions.

  > - Assignments: Generally used to detect unusually long strings.

  > - Attributes: Used to detect access to modules which are generally used for suspicious activity.

  > - Function calls: Used to detect calls to functions which may be suspicious.

  > - Function declarations: Used to detect unusual (obfuscated) function names in the module.

  > - Imports: Used for capturing a module’s import statements (or the lack thereof).

  > - Strings: Used to capture the strings used in a module.

  property ast_: Module

    Public accessor to the module’s abstract syntax tree.

  property code: StringIO

    Public accessor to the code as a text stream.

  property path: str

    Public accessor to the module’s file path.

  display_syntax_tree()

    Display the syntax tree as parsed by `ast`.

  parse(path: str)

    Parse a module into an abstract syntax tree.

    Additionally, a the code itself is stored into the `_code` attribute for additional analysis as an `_io.StringIO` text stream object.

    Parameters:

      path (str) – Full path to the module.

  rewind()

    Rewind the code stream to the beginning.