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 apathlib
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. Theprovisioning
directory is not regenerated unless thegenerate_provisioning
attribute isTrue
. - If the attribute is not defined (or it is
None
or""
), the intermediate definition will be generated inside thesandbox
directory in the same location as the topology definition file. - The path can be passed as a
str
or apathlib
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 apathlib
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 apathlib
Path
.
generate_provisioning
- Whether the user
provisioning
file should be regenerated. - By default (
generate_provisioning = False
), if theprovisioning
directory already exists in the required output directory, it is not altered. Changing this attribute toTrue
forces CSC to delete theprovisioning
directory and generate a sampleprovisioning
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 apathlib
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
incyber-sandbox-creator.manager
:
Value | Description |
---|---|
Output.DEVNULL | The output is thrown away. |
Output.STDOUT | The output is sent to standard output. |
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!")