polytracker.containerization¶

containerization classes¶

DockerCommand¶

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

Bases: Command

__init__(argument_parser: ArgumentParser)¶

container: DockerContainer¶

extension_types: Optional[List[Type['CommandExtension']]] = 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: Optional['Plugin']¶: 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: Optional[List[Type['Subcommand']]] = [<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: Optional[Any] = None¶: A subparser, auto-populated if subcommand_types is not None.

DockerContainer¶

class polytracker.containerization.DockerContainer(image_name: str = 'trailofbits/polytracker', tag: Optional[str] = None)¶

Bases: object

__init__(image_name: str = 'trailofbits/polytracker', tag: Optional[str] = None)¶

property client: DockerClient¶

exists() → Optional[Image]¶

last_build_time() → Optional[int]¶: 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: Optional[Iterable[Tuple[Union[str, Path], Union[str, Path]]]] = None, env: Optional[Dict[str, str]] = None, stdin=None, stdout=None, stderr=None, cwd=None) → int¶

DockerExists¶

class polytracker.containerization.DockerExists(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

Bases: DockerSubcommand

classmethod __class_getitem__(params)¶

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

property container: DockerContainer¶

extension_types: Optional[List[Type['CommandExtension']]] = 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: Optional['Plugin']¶: 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: Optional[List[Type['Subcommand']]] = None¶: An auto-populated list of subcommands of this command.

subparser: Optional[Any] = 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: Optional[Plugin] = None)¶

Bases: DockerSubcommand

classmethod __class_getitem__(params)¶

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

property container: DockerContainer¶

extension_types: Optional[List[Type['CommandExtension']]] = 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: Optional['Plugin']¶: 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: Optional[List[Type['Subcommand']]] = None¶: An auto-populated list of subcommands of this command.

subparser: Optional[Any] = None¶: A subparser, auto-populated if subcommand_types is not None.

DockerRebuild¶

class polytracker.containerization.DockerRebuild(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

Bases: DockerSubcommand

classmethod __class_getitem__(params)¶

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

property container: DockerContainer¶

extension_types: Optional[List[Type['CommandExtension']]] = 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: Optional['Plugin']¶: 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: Optional[List[Type['Subcommand']]] = None¶: An auto-populated list of subcommands of this command.

subparser: Optional[Any] = None¶: A subparser, auto-populated if subcommand_types is not None.

DockerRun¶

class polytracker.containerization.DockerRun(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

Bases: DockerSubcommand

classmethod __class_getitem__(params)¶

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

property container: DockerContainer¶

extension_types: Optional[List[Type['CommandExtension']]] = 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: Optional['Plugin']¶: 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: Optional[DockerContainer] = None, args=(), interactive: Optional[bool] = 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: Optional[List[Type['Subcommand']]] = None¶: An auto-populated list of subcommands of this command.

subparser: Optional[Any] = None¶: A subparser, auto-populated if subcommand_types is not None.

DockerSubcommand¶

class polytracker.containerization.DockerSubcommand(argument_parser: ArgumentParser, parent: Optional[Plugin] = None)¶

Bases: Subcommand[DockerCommand], ABC

classmethod __class_getitem__(params)¶

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(argument_parser: ArgumentParser, parent: Optional[Plugin] = 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: Optional[List[Type['CommandExtension']]] = 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: Optional['Plugin']¶: 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: Optional[List[Type['Subcommand']]] = None¶: An auto-populated list of subcommands of this command.

subparser: Optional[Any] = 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) → Optional[int]¶: Returns the line number of the associated step command