polytracker.containerization

containerization classes

DockerCommand

class polytracker.containerization.DockerCommand(argument_parser: ArgumentParser)

Bases: Command

__init__(argument_parser: ArgumentParser)

container: DockerContainer

extension_types: List[Type['CommandExtension']] | None = None: An auto-populated list of eny extensions to this command.

property full_name: str

help: str = 'commands for seamlessly running PolyTracker in a Docker container': Help string for this command.

name: str = 'docker': The name of this plugin.

parent: 'Plugin' | None: The parent of this plugin, if it is a sub-plugin.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

parser: ArgumentParser

run(args)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type['Subcommand']] | None = [<class 'polytracker.containerization.DockerExists'>, <class 'polytracker.containerization.DockerPull'>, <class 'polytracker.containerization.DockerRebuild'>, <class 'polytracker.containerization.DockerRun'>]: An auto-populated list of subcommands of this command.

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

DockerContainer

class polytracker.containerization.DockerContainer(image_name: str = 'trailofbits/polytracker', tag: str | None = None)

Bases: object

__init__(image_name: str = 'trailofbits/polytracker', tag: str | None = None)

property client: DockerClient

exists() → Image | None

last_build_time() → int | None: Returns the last time this image was rebuilt as the number of seconds since the UNIX epoch, or None if the container has not yet been built

property name: str

out_of_date_sources() → List[Path]: Returns the PolyTracker source files that were modified after this container was built

pull(latest: bool = False) → Image

rebuild(nocache: bool = False, tag_as_latest: bool = True)

run(*args: str, build_if_necessary: bool = True, check_if_docker_out_of_date: bool = True, remove: bool = True, interactive: bool = True, mounts: Iterable[Tuple[str | Path, str | Path]] | None = None, env: Dict[str, str] | None = None, stdin=None, stdout=None, stderr=None, cwd=None) → int

DockerExists

class polytracker.containerization.DockerExists(argument_parser: ArgumentParser, parent: Plugin | None = None)

Bases: DockerSubcommand

__init__(argument_parser: ArgumentParser, parent: Plugin | None = None)

property container: DockerContainer

extension_types: List[Type['CommandExtension']] | None = None: An auto-populated list of eny extensions to this command.

property full_name: str

help: str = 'checks whether the Docker container already exists': Help string for this command.

name: str = 'exists': The name of this plugin.

parent: 'Plugin' | None: The parent of this plugin, if it is a sub-plugin.

property parent_command: C: Returns the parent command associated with this subcommand.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

parent_type: alias of DockerCommand

run(args)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type['Subcommand']] | None = None: An auto-populated list of subcommands of this command.

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

DockerOutOfDateError

class polytracker.containerization.DockerOutOfDateError(message: str, container: DockerContainer)

Bases: RuntimeError

An error when the docker image is older than the PolyTracker source code

__init__(message: str, container: DockerContainer)

add_note(): Exception.add_note(note) – add a note to the exception

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

DockerPull

class polytracker.containerization.DockerPull(argument_parser: ArgumentParser, parent: Plugin | None = None)

Bases: DockerSubcommand

__init__(argument_parser: ArgumentParser, parent: Plugin | None = None)

property container: DockerContainer

extension_types: List[Type['CommandExtension']] | None = None: An auto-populated list of eny extensions to this command.

property full_name: str

help: str = 'pulls the latest PolyTracker Docker image from DockerHub': Help string for this command.

name: str = 'pull': The name of this plugin.

parent: 'Plugin' | None: The parent of this plugin, if it is a sub-plugin.

property parent_command: C: Returns the parent command associated with this subcommand.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

parent_type: alias of DockerCommand

run(args)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type['Subcommand']] | None = None: An auto-populated list of subcommands of this command.

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

DockerRebuild

class polytracker.containerization.DockerRebuild(argument_parser: ArgumentParser, parent: Plugin | None = None)

Bases: DockerSubcommand

__init__(argument_parser: ArgumentParser, parent: Plugin | None = None)

property container: DockerContainer

extension_types: List[Type['CommandExtension']] | None = None: An auto-populated list of eny extensions to this command.

property full_name: str

help: str = 'rebuilds the Docker container': Help string for this command.

name: str = 'rebuild': The name of this plugin.

parent: 'Plugin' | None: The parent of this plugin, if it is a sub-plugin.

property parent_command: C: Returns the parent command associated with this subcommand.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

parent_type: alias of DockerCommand

run(args)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type['Subcommand']] | None = None: An auto-populated list of subcommands of this command.

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

DockerRun

class polytracker.containerization.DockerRun(argument_parser: ArgumentParser, parent: Plugin | None = None)

Bases: DockerSubcommand

__init__(argument_parser: ArgumentParser, parent: Plugin | None = None)

property container: DockerContainer

extension_types: List[Type['CommandExtension']] | None = None: An auto-populated list of eny extensions to this command.

property full_name: str

help: str = 'runs the Docker container': Help string for this command.

name: str = 'run': The name of this plugin.

parent: 'Plugin' | None: The parent of this plugin, if it is a sub-plugin.

property parent_command: C: Returns the parent command associated with this subcommand.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

parent_type: alias of DockerCommand

run(args)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

static run_on(container: DockerContainer | None = None, args=(), interactive: bool | None = None, notty: bool = False, **kwargs) → int

Runs PolyTracker inside Docker and returns the exit code.

Running with no arguments will enter into an interactive Docker session, mounting the current working directory to /workdir.

subcommand_types: List[Type['Subcommand']] | None = None: An auto-populated list of subcommands of this command.

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

DockerSubcommand

class polytracker.containerization.DockerSubcommand(argument_parser: ArgumentParser, parent: Plugin | None = None)

Bases: Subcommand[DockerCommand], ABC

__init__(argument_parser: ArgumentParser, parent: Plugin | None = None)

__init_arguments__(parser: ArgumentParser)

Initializes this command’s argument parser.

Subclasses should extend this function and add any necessary options to parser.

property container: DockerContainer

extension_types: List[Type['CommandExtension']] | None = None: An auto-populated list of eny extensions to this command.

property full_name: str

help: str: Help string for this command.

name: str: The name of this plugin.

parent: 'Plugin' | None: The parent of this plugin, if it is a sub-plugin.

property parent_command: C: Returns the parent command associated with this subcommand.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

parent_type: alias of DockerCommand

abstract run(args: Namespace)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type['Subcommand']] | None = None: An auto-populated list of subcommands of this command.

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

Dockerfile

class polytracker.containerization.Dockerfile(path: Path)

Bases: object

__init__(path: Path)

__len__() → int: Returns the number of lines in the file

dir() → Path

exists() → bool

get_line(step_command: str, starting_line: int = 0) → int | None: Returns the line number of the associated step command