This page describes the Python interface of the Cyber Sandbox Creator, which can be used to create, build or destroy sandboxes directly from a Python script. It provides all functionality of the Cyber Sandbox Creator command-line script (which also uses this interface internally).

Create

sandboxcreator.creator

The create function generates an intermediate definition from a sandbox definition.

create(topology: Union[str, Path],
       output_dir: Optional[Union[str, Path]] = None,
       ansible_installed: bool = False,
       provisioning_dir: Optional[Union[str, Path]] = None,
       extra_vars: Optional[Union[str, Path]] = None,
       generate_provisioning: bool = False,
       verbose_ansible: bool = False,
       working_dir: Optional[Union[str, Path]] = None) -> None

Attributes

topology

• Path to a topology definition YAML file.
• It is the only mandatory attribute without a default value.
• The path can be passed as a str or a pathlib Path.

output_dir

• Path to a directory where the intermediate definition will be generated.
• If the directory does not exist, it will be created.
• If the directory exists, it will regenerate the Vagrantfile and the basic VM configuration. The provisioning directory is not regenerated unless the generate_provisioning attribute is True.
• If the attribute is not defined (or it is None or ""), the intermediate definition will be generated inside the sandbox directory in the same location as the topology definition file.
• The path can be passed as a str or a pathlib Path.

ansible_installed

• Whether Ansible installed on the host machine should be used.
• The default is False, which is compatible with all host OSes and does not require Ansible installed on the host.
• This optimization cannot be used on Windows hosts (it should always be set to False).

provisioning_dir

• Path to a directory with user provisioning files.
• If the attribute is defined, the whole directory will be copied to the intermediate definition to the appropriate location.
• The given directory must contain a playbook.yml file, which Ansible will use during the provisioning.
• The directory can also contain requirements.yml listing Ansible Galaxy dependencies. If the file exists, it will be used during the provisioning.
• The path can be passed as a str or a pathlib Path.

extra_vars

• Path to a YAML file with additional attributes for Ansible.
• See Building a Sandbox about the details on this file.
• The path can be passed as a str or a pathlib Path.

generate_provisioning

• Whether the user provisioning file should be regenerated.
• By default (generate_provisioning = False), if the provisioning directory already exists in the required output directory, it is not altered. Changing this attribute to True forces CSC to delete the provisioning directory and generate a sample provisioning directory instead.

verbose_ansible

• Sets Ansible to give a verbose output (vv) during the sandbox building.

working_dir

• An absolute path to a directory, which helps to resolve relative paths in other arguments.
• It is a safety measure to correctly resolve relative paths on every platform (especially Windows).
• It is ignored if only absolute paths are used in arguments or when the absolute paths can be determined another way.
• The path can be passed as a str or a pathlib Path.

Manager

sandboxcreator.manager

The manage function can build, destroy or execute other commands on the sandbox defined in an intermediate definition.

manage(command_name: str,
       sandbox_location: Union[str, Path],
       machines: Optional[List[str]] = None,
       ansible_vars: str = "",
       output: OutputLocation = OutputLocation.DEVNULL,
       error: OutputLocation = OutputLocation.DEVNULL) -> None

Attributes

command_name

• Command to perform on a sandbox.
• Mandatory attribute without a default value.
• The possible values are listed in Building-and-Using-a-Sandbox

sandbox_location

• Path to the sandbox directory (containing the Vagrantfile). (Usually the intermediate definition directory.)
• Mandatory attribute without a default value.

machines

• A list of names of virtual machines on which the command should be performed.
• If the list is empty or None (default), the command will be executed on all defined virtual machines.

ansible_vars

• Additional Ansible variables that are passed to Ansible before building a sandbox.
• All variables are expected to be in a single string: var1:val1;var2:val2
• Does not work with intermediate definitions generated before v3.0.0.

output and error

• The device to which the output and the error output of Vagrant and Ansible should be sent.
• The possible values are defined as an Enum Output in cyber-sandbox-creator.manager:

Example

Here is a simple example of how the Python API can be used to build an instance of a sandbox directly from the topology definition:

import os
from sandboxcreator import creator, manager
from sandboxcreator.commands.command_attributes import OutputLocation

working_dir: str = os.getcwd()
topology_path: str = working_dir + "/topology.yml"
sandbox_path: str = working_dir + "/sandbox"

creator.create(topology_path)
print("Intermediate definition was successfully generated!")

print("Building the sandbox...")
manager.manage("build", sandbox_path, output=manager.OutputLocation.DEVNULL)
print("Your new sandbox is ready to use!")