Escape CLI¶

The Escape CLI provides a command-line interface to automate Escape scans. It serves as a wrapper around the Escape V3 API, allowing seamless integration into your workflows. It is a fully open-source project written in Golang available from the Escape CLI GitHub Releases page.

Escape CLI and Private Locations

The Escape CLI also enables you to register and manage Private Locations. For more details, refer to the Private Locations documentation.

Installation¶

Using Curl (Unix-based Systems)¶

For Linux or macOS, run the following command to install the Escape CLI:

curl -sf https://raw.githubusercontent.com/Escape-Technologies/cli/refs/heads/main/scripts/install.sh | sudo bash

# Check installation
escape-cli version

Using PowerShell (Windows)¶

For Windows, run the following PowerShell command:

powershell -c "irm https://raw.githubusercontent.com/Escape-Technologies/cli/refs/heads/main/scripts/install.ps1 | iex"

# Check installation
escape-cli version

Docker Installation¶

The Escape CLI is also available as a Docker image. To run it via Docker, use the following command:

docker run -e ESCAPE_API_KEY="${ESCAPE_API_KEY}" -it --rm escapetech/cli:latest version

Configuration¶

To use the Escape CLI with your Escape instance, you need to configure the ESCAPE_API_KEY environment variable.

Obtain the API Key: Visit your user profile settings to retrieve your API Key.
Set the Environment Variable: Add the ESCAPE_API_KEY to your shell configuration (e.g., .bashrc, .zshrc) or to your CI/CD pipeline.

Optional Configuration Variables¶

ESCAPE_K8S_INTEGRATION: Controls Kubernetes integration. By default, this is set to true. Set it to false to disable Kubernetes integration.

Usage¶

To get started with the Escape CLI, you can run the following commands:

List Available Commands¶

escape-cli help

or

escape-cli help-all

Get Help for a Specific Command¶

escape-cli help scans start

List Your Private Locations¶

escape-cli locations list

Output in Different Formats¶

You can use the --output flag to specify the format of the results:

escape-cli locations list --output json

Cookbooks¶

Running a Scan and Saving Results in JSON Format¶

Here is an example of how to run a scan and save the results to a JSON file:

# Run the Escape CLI version command to ensure it is installed
escape-cli version
# Replace with your profile ID
PROFILE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# Start a scan and output the results in JSON format
escape-cli scan start "${PROFILE_ID}" -o json | tee scan.json
# Extract the scan ID from the JSON output
SCAN_ID=$(cat scan.json | jq -r '.id')
echo "SCAN_ID: ${SCAN_ID}"

# Monitor the scan until it completes. This command will block until the scan is finished
escape-cli scan watch "${SCAN_ID}"
# Once the scan is complete, retrieve the issues
escape-cli scans issues "${SCAN_ID}"
# Optionally, output the issues in JSON format
escape-cli scans issues "${SCAN_ID}" -o json | tee issues.json

Creating an Asset¶

# Run the Escape CLI version command to ensure it is installed
escape-cli version
# Create a json file with the asset data (see the asset schema in the API reference https://public.escape.tech/v3/#tag/assets)
cat <<EOF > asset.json
{
  "asset_class": "HOST",
  "asset_type": "DNS",
  "address": "example.com"
}
EOF
# Create the asset
escape-cli asset create <asset.json
# or
cat asset.json | escape-cli asset create

Adding a list of assets from file¶

Let's say you have a file with on each line the url of a REST API.

You can run this code to import all the assets in Escape:

while read -r url; do
cat <<EOF | escape-cli asset create
{
  "asset_class": "API_SERVICE",
  "asset_type": "REST",
  "url": "$url"
}
EOF
done < assets.txt

You can also update this script to parse a CSV or a JSON file.

For example, if the CSV looks like this:

date,domain,comment
2025-01-01,example.com,This is a comment
2025-01-02,example.io,This is a comment
2025-01-03,example.net,This is a comment

To create all assets of type DNS, you can run this code:

# using sed 1d to remove first line (header)
sed 1d assets.csv | while read -r line; do
# Extract domain: the second column
domain=$(echo "$line" | cut -d ',' -f 2)
cat <<EOF | escape-cli asset create
{
  "asset_class": "HOST",
  "asset_type": "DNS",
  "address": "$domain"
}
EOF
done