cryton-cli 2022.2.1

Command line interface for Cryton Core

[[TOC]]

Cryton CLI

Description

Cryton CLI is a command line interface used to interact with Cryton Core (its API).

To be able to execute attack scenarios, you also need to install Cryton Core and Cryton Worker tools.

Cryton toolset is tested and targeted primarily on Debian and Kali Linux. Please keep in mind that only the latest version is supported and issues regarding different OS or distributions may not be resolved.

Link to the documentation.

Settings

Cryton CLI uses environment variables for its settings. Please update them to your needs.

name	value	example	description
CRYTON_CLI_TIME_ZONE	string	AUTO	What timezone to use for scheduling (for example when scheduling a Run). Use the AUTO value to use your system timezone.
CRYTON_CLI_API_HOST	string	127.0.0.1	Cryton Core's API address.
CRYTON_CLI_API_PORT	int	8000	Cryton Core's API port.
CRYTON_CLI_API_SSL	boolean	false	Use SSL to connect to REST API.
CRYTON_CLI_API_ROOT	string	api/	REST API URL. (do not change, if you don't know what you're doing)
CRYTON_CLI_APP_DIRECTORY	string	~/.local/cryton-cli/	Path to the Cryton CLI directory. (do not change/set/export, if you don't know what you're doing) If changed, update the commands in this guide accordingly.

To save the settings create an app directory:

mkdir ~/.local/cryton-cli/

Next, we download example settings (change the version to match the app version):

curl -o ~/.local/cryton-cli/.env https://gitlab.ics.muni.cz/cryton/cryton-cli/-/raw/<version>/.env

Update these settings to your needs.

Overriding the settings

To override the persistent settings, you can set/export the variables yourself using the export command (use unset to remove the variable). For example:

export CRYTON_CLI_API_HOST=127.0.0.1

Some environment variables can be overridden in CLI. Try using cryton-cli --help.

Installation

Cryton CLI is available in the PyPI and can be installed using pip (pip install --user cryton-cli). However, we highly recommend installing the app in an isolated environment using pipx.

Requirements

Install the following requirements:

• Python >=3.8
• pipx

Installing with pipx

Once you have pipx ready on your system, you can start the installation:

pipx install cryton-cli

Make sure you've correctly set the settings.

Optionally, you can set up shell completion.

Everything should be set, check out the usage section.

Development

To install Cryton CLI for development, you must install Poetry.

Clone the repository:

git clone https://gitlab.ics.muni.cz/cryton/cryton-cli.git

Then go to the correct directory and install the project:

cd cryton-cli
poetry install

To spawn a shell use:

poetry shell

Make sure you've correctly set the settings.
To override the settings quickly, you can use this handy one-liner:

export $(grep -v '^#' .env | xargs)

Optionally, you can set up shell completion.

Everything should be set. Check out the usage section.

Usage

Use the following to invoke the app:

cryton-cli

You should see a help page:

Usage: cryton-cli [OPTIONS] COMMAND [ARGS]...

  A CLI wrapper for Cryton API.

Options:
  ...

Please keep in mind that the Cryton Core must be running and its API must be reachable.

To change the default API host/port use -H and -p options (to change them permanently, see the settings section).

cryton-cli -H 127.0.0.1 -p 8000 <your command>

To learn about each command's options use:

cryton-cli <your command> --help

For a better understanding of the results, we highlight the successful ones with green and the others with red color.

Example

1. Create plan template

Create a plan template using a file containing the desired plan YAML.

cryton-cli plan-templates create my-plan.yml

Desired output:

Template successfully created! (<response detail>).

2. Create Plan instance

Create a Plan instance with the saved plan template.

cryton-cli plans create 1

Create a Plan instance using the template and an inventory file.

cryton-cli plans create 1 -i inventory_file

Desired output:

Plan successfully created! (<response detail>).

3. Create Worker

To execute Plans (Runs) we have to define a Worker(s).

cryton-cli workers create customName -d "This is my first Worker!"

Desired output:

Worker successfully created! (<response detail>).

4. Create Run

Create a Run by choosing a Plan instance and providing a list of Workers for execution.

cryton-cli runs create 1 1

Desired output:

Run successfully created! (<response detail>).

5. Schedule or execute Run

You can either schedule the Run for a specific date/time or execute it directly. Run will then be executed on every Worker simultaneously.

Execute Run

cryton-cli runs execute 1

Desired output:

Run successfully executed! (Run 1 was executed.).

Schedule Run
You can schedule a Run using the local timezone.

cryton-cli runs schedule 1 2020-06-08 10:00:00

Desired output:

Run successfully scheduled! (Run 1 is scheduled for 2020-06-08 10:00:00.).

Or you can schedule it using UTC timezone with the flag --utc-timezone. Otherwise, your preset timezone is used.

6. Read Run report

A report can be generated anytime during the execution (also compliant with YAML format). It contains a list of Stages/Steps and their results.

cryton-cli runs report 1

Desired output:

Successfully created Run's report! (file saved at: /tmp/report_run_1_2020-06-08-10-15-00-257994_xdQeV)

Timestamps are displayed in UTC timezone by default. Use the --localize flag to display them using your preset timezone.

Shell completion

Shell completion is available for the Bash, Zsh, and Fish shell and has to be manually enabled (the tool must be installed first).

Bash

First, create an app directory (if you haven't already):

mkdir ~/.local/cryton-cli/

Generate and save the completion script:

_CRYTON_CLI_COMPLETE=bash_source cryton-cli > ~/.local/cryton-cli/cryton-cli-complete.bash

Source the file in the ~/.bashrc file:

echo ". ~/.local/cryton-cli/cryton-cli-complete.bash" >> ~/.bashrc

You may need to restart your shell for the changes to take effect.

Zsh

First, create an app directory (if you haven't already):

mkdir ~/.local/cryton-cli/

Generate and save the completion script:

_CRYTON_CLI_COMPLETE=zsh_source cryton-cli > ~/.local/cryton-cli/cryton-cli-complete.zsh

Source the file in the ~/.zshrc file:

echo ". ~/.local/cryton-cli/cryton-cli-complete.zsh" >> ~/.zshrc

You may need to restart your shell for the changes to take effect.

Fish

Generate and save the completion script:

_CRYTON_CLI_COMPLETE=fish_source cryton-cli > ~/.config/fish/completions/cryton-cli-complete.fish

You may need to restart your shell for the changes to take effect.