|
|
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.
|
|
|
|
|
|
```python
|
|
|
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](2.0/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.
|
|
|
|
|
|
```python
|
|
|
manage(command_name: str,
|
|
|
sandbox_location: Union[str, Path],
|
|
|
machines: Optional[List[str]] = None,
|
|
|
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](3.0/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.
|
|
|
|
|
|
### 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`:
|
|
|
|
|
|
| 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:
|
|
|
|
|
|
```python
|
|
|
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!")
|
|
|
``` |
|
|
\ No newline at end of file |