Sysdig Platform CLI

A CLI client for Sysdig Monitor and Sysdig Secure

The Sysdig Platform CLI (abbreviated sdc-cli) is a unified tool implemented using Sysdig Python SDK to manage Sysdig Monitor and Sysdig Secure using your terminal.

With a single tool, you can control most of the configuration in Monitor and Secure from the command line and conveniently automate them through scripts.

Set up

You can set up or install the Sysdig Platform CLI in several ways:

Installing using pip

Prerequisites

You need Python 3.8 or later version. Make sure to upgrade your Python version if required, you may consider using PyEnv if neccesary.

You also need pip installed and upgraded to latest version.

$ python3 -V
Python 3.8.5

$ pip -V
pip 20.2.3 from /home/user/.local/lib/python3.8/site-packages/pip (python 3.8)

Install using pip globally

$ pip install sdccli

Check that the binary is correctly installed

$ sdc-cli

Bash/Zsh Complete

To enable bash completion add the following to your .bashrc:

$ eval "$(_SDC_CLI_COMPLETE=source sdc-cli)"

Or for zsh add in your .zshrc:

$ eval "$(_SDC_CLI_COMPLETE=source_zsh sdc-cli)"

Usage via Docker image

If you already have Docker or other container runtime, you just have to be able to acess Dockerhub public repository from your machine.

Executing a sdc-cli command passing Monitor and Secure tokens as environment variables via command line can be achieved this way:

$ docker run -v $(pwd):/data -e SDC_MONITOR_TOKEN=<token> -e SDC_SECURE_TOKEN=<token> sysdiglabs/sdc-cli [options]

You only need to provide the token required for the operation you are executing. For example, to operate with dashboards, you only require SDC_MONITOR_TOKEN, while for doing a full backup of your account, you require both SDC_MONITOR_TOKEN and SDC_SECURE_TOKEN.

Executing a sdc-cli command passing tokens and extra configuration via a config.yml configuration file can be achieved this way:

$ docker run -v $(pwd):/data -v /path/to/config.yaml:/etc/sdc-cli/config.yml sysdiglabs/sdc-cli [options]

Be careful as you are mounting the current directory to perform operations, and the Docker image is executing inside the container as root, any file created will be owned by root.

$ docker run -v $(pwd):/data -e SDC_MONITOR_TOKEN=<token> -e SDC_SECURE_TOKEN=<token> sysdiglabs/sdc-cli backup dump mybackup
$ ls -la
drwxr-xr-x  2 user  user    4096 Oct  5 22:12 ./
drwxr-xr-x 39 user  user    4096 Oct  5 18:39 ../
-rw-r--r--  1 root  root  400954 Oct  5 22:12 mybackup

You can change ownership of the generated file using chown:

sudo chown $(id -u):$(id -g) mybackp

Or you can avoid it specifying with this command to use the same user and group id for the docker image command execution:

docker run -v $(pwd):/data --user $(id -u):$(id -g) -e SDC_MONITOR_TOKEN=<token> -e SDC_SECURE_TOKEN=<token> sysdiglabs/sdc-cli backup dump mybackup

It may be useful to create an alias for the full command including your chosend method of configuration:

$ alias sdc-cli="docker run -v $(pwd):/data --user $(id -u):$(id -g) -e SDC_MONITOR_TOKEN=<token> -e SDC_SECURE_TOKEN=<token> sysdiglabs/sdc-cli"
$ alias sdc-cli2="docker run -v $(pwd):/data --user $(id -u):$(id -g) -v /path/to/config.yaml:/etc/sdc-cli/config.yml sysdiglabs/sdc-cli"

Configuration

The sdc-cli tool receives its configuration either via environment variables, or via a config file.

Environment variables

The following environment variables are supported:

Env Var Description Default
SDC_ENV Environment to use if using the config file main
SDC_MONITOR_TOKEN API Token for Sysdig Monitor -
SDC_MONITOR_URL URL for Sysdig Monitor https://app.sysdigcloud.com
SDC_SECURE_TOKEN API Token for Sysdig Secure -
SDC_SECURE_URL URL for Sysdig Secure https://secure.sysdig.com
SDC_TOKEN General Token for Sysdig Platform. Overrides SDC_MONITOR_TOKEN and SDC_SECURE_TOKEN -
SDC_URL General URL for Sysdig Platform. Overrides SDC_MONITOR_URL and SDC_SECURE_URL -
SDC_SSL_VERIFY Verify API SSL certificate. Deactivate if you are using an on-prem installation True

The SDC_MONITOR_TOKEN or the SDC_SECURE_TOKEN are required variables for commands executed on Sysdig Monitor or Sysdig Secure.

As an alternative to global environment variables, you can use Bash ability to define temporal environment variables preceeding the executing command, as is shown in this example:

$ SDC_TOKEN=<token> sdc-cli scanning runtime list

Configuration file

The configuration file is a bit more rich when it comes to configuring multiple environments, and removes the need to specify environment variables. The CLI tries to find a config file in the following paths and reads the first one that matches:

The format of the file is the following:

envs:
    main:                                                         # Main environment, default target if -e is not specified
      monitor:
        token: 00000000-1111-2222-3333-444444444444               # Required if not specified via ENV var.
        url: https://ec2-00-000-000-00.compute-1.amazonaws.com    # Optional. Default is https://app.sysdigcloud.com
        disable_ssl_verification: true                            # Optional. Default is false
        extra_headers:                                            # Optional. Any extra header added here will be used for the HTTP queries
          Connection: close
          Proxy-Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
      secure:
        token: 11111111-2222-3333-4444-555555555555               # Required if not specified via ENV var.
        url: https://ec2-11-222-333-44.compute-1.amazonaws.com    # Optional. Default is https://secure.sysdig.com
        disable_ssl_verification: false                           # Optional. Default is false
        extra_headers:                                            # Optional. Any extra header added here will be used for the HTTP queries
          Connection: keep-alive
          Proxy-Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
    saas:                                                         # Another environment, can be referenced with -e <name> or with the SDC_ENV variable
      monitor:
        token: 22222222-3333-4444-5555-666666666666
      secure:
        token: 33333333-4444-5555-6666-777777777777

Usage

There are different subcommands available, run it without parameters or execute sdc-cli --help to see all the options:

$ sdc-cli --help
Usage: sdc-cli [OPTIONS] COMMAND [ARGS]...

  You can provide the monitor/secure tokens by the SDC_MONITOR_TOKEN and
  SDC_SECURE_TOKEN environment variables.

Options:
  -c, --config TEXT  Uses the provided file as a config file. If the config
                     file is not provided, it will be searched at
                     ~/.config/sdc-cli/config.yml and /etc/sdc-cli/config.yml.

  -e, --env TEXT     Uses a preconfigured environment in the config file. If
                     it's not provided, it will use the 'main' environment or
                     retrieve it from the env var SDC_ENV.

  --json             Output raw API JSON
  -v, --version      Show the version and exit.
  --help             Show this message and exit.

Commands:
  alert         Sysdig Monitor alert operations
  backup        Backup operations
  capture       Sysdig capture operations
  command       Sysdig Secure commands audit operations
  compliance    Sysdig Secure compliance operations
  dashboard     Sysdig Monitor dashboard operations
  dashboard_v2  Sysdig Monitor dashboard operations
  event         Sysdig Monitor events operations
  event_v1      Sysdig Monitor events operations, v1 endpoints
  policy        Sysdig Secure policy operations
  profile       Sysdig Secure image profile operations
  scanning      Scanning operations
  settings      Settings operations

Run it with --help to see all the documentation of a subcommand:

$ sdc-cli event add --help
Usage: sdc-cli event add [OPTIONS] NAME

  NAME: the name of the new event.

Options:
  --description TEXT  a longer description offering detailed information about
                      the event.
  --severity INTEGER  syslog style from 0 (high) to 7 (low).
  --filter TEXT       metadata, in Sysdig Monitor format, of nodes to
                      associate with the event, e.g. ``host.hostName =
                      'ip-10-1-1-1' and container.name = 'foo'``.
  --tag TEXT          A key=value that can be used to tag the event. Can be
                      used for filtering/segmenting purposes in Sysdig
                      Monitor.
  --help              Show this message and exit.

Full command documentation

💡 All list and get subcommands for each of the following sections accepts the --json option for JSON output, but it MUST be specified after the sdc-cli part, for example: sdc-cli --json <section> get

Visit the following links for more information about each command

Examples

Some examples:

$ sdc-cli scanning image list
Full Tag                                  Image ID                                                                Analysis Status
[...]
docker.io/debian:latest                   a0bd3e1c8f9eb8ff9d65828e8062ae9284b60cb83abe59fe46c74d77d88eb952        analyzed

$ sdc-cli scanning image get docker.io/debian:latest

$ sdc-cli capture --secure add --duration 120 mycapture myhost

Output JSON format

Every command can be run with --json to get the full json response:

$ sdc-cli --json scanning runtime list
{
    "scope": "",
    "time": {
        "from": 1552936553745052,
        "to": 1552936613745052
    },
    "images": [
        {
            "imageId": "c6ff8a6aa5f62c37f1e47d61baaf635ab0d10aa784ceeed16f340f95292fcfc6",
            "repo": "docker.io/wallabag/wallabag",
            "tag": "latest",
            "digest": "sha256:8a80a21a2c3492a6c34c198e8d0a27795bdd741dcdf8448ad862292cc143f06f",
            "analysisStatus": "analyzed",
            "policyEvalStatus": "fail",
            "containers": [
                {
                    "containerId": "fbfb5fbd20f0"
                }
            ]
        }
    ]
}

Date format

Many commands accept dates and date ranges. sdc-cli is very permissive on date formats. Some examples of valid dates and their translations are: