Sysdig Python SDK

Sysdig provides Sysdig Python SDK and Platfrom CLI to manage Sysdig Monitor and Sysdig Secure operations programmatically.

Sysdig Platform CLI

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

Access the Platform CLI Documentation

See sysdig-platform-cli.

Guidelines

  • For information on locating the SDC_MONITOR_TOKEN or SDC_SECURE_TOKEN, see Retrieve the Sysdig API Token

  • For SDC\_MONITOR\_URL and SDC\_SECURE\_URL: Use the endpoint for where your Sysdig application is deployed.

  • On-Premises: To disable SSL verification, usually needed for on-prem installs due to self-signed certificates, add the environmental option SDC_SSL_VERIFY with the value FALSE. The default value is TRUE.

Sysdig Python SDK

Sysdig Python SDK includes a Python library and a collection of Python sample scripts to expose and use some of the most common Sysdig API functions. Sysdig Python SDK is also known as the sdcclient. Typically, operations are either making minor modifications to a sample Python script to automate something simple, such as creating users or adding users to teams, or working along with the Sysdig professional services to customize samples and create more complex application integrations

This topic helps you install and instantiate the sdcclient using the Sysdig Platform CLI. For the latest information, see the following:

Prerequisites

  • Python version 3.8 or above

  • Latest pip version

    pip is installed as part of the Python package for versions 2.7 and later

  • virtualenv (recommended)

  • Sysdig API token

Retrieve the Sysdig API Token

When using the Sysdig API with custom scripts or applications, you must supply an API security token specific to each team.

  1. Log in to Sysdig Monitor or Sysdig Secure.

  2. Select Settings > User Profile.

The API token is displayed (depending on which interface and team you logged in to).

  1. Copy the token for use, or click the Reset Token button to generate a new one.

    When reset, the previous token issued will immediately become invalid and you will need to make appropriate changes to your programs or scripts.

Install the Python Client

Use the following methods to install sdcclient:

Use the Pip Command

Install the client by using pip:

pip install sdcclient

Identify Your API Server

SAAS

Use the endpoint for where your Sysdig application is deployed. Open it in a browser and check the drop-down to verify the API URL you should use in the client installation script.


The default region is US East and the URL is app.sysdig.cloud.com.

On-Premises

For the On-Premises Sysdig Platform installations, you need to use the hostame or IP where your Sysdig API server is running.

Option 1

To do so, set the following environment variables before running your Python scripts:

export SDC_URL='https://<YOUR-API-SERVER-HOSTNAME-OR-IP>'

If you are using a self-signed certificate, set following variable:

export SDC_SSL_VERIFY='false'

Disable the SSL verification only if you don’t have a valid certificate.

Option 2

Alternatively, you can specify the additional arguments in your Python scripts as you instantiate sdcclient:

client = SdMonitorClient(api_token, sdc_url='https://<YOUR-API-SERVER-HOSTNAME-OR-IP>', ssl_verify=False)

Proxy Support

The sdcclient supports the following environment variables:

  • HTTP_PROXY
  • HTTPS_PROXY
  • NO_PROXY

Open the terminal and set the HTTPS_PROXY and NO_PROXY environment variables:

export HTTPS_PROXY="http://myproxy.domain.com:8080"
export NO_PROXY="127.0.0.1,localhost,.myinternal.domain.com"

Alternatively, you can add the following setting to your Python scripts as folllows.

import os

os.environ['HTTPS_PROXY'] = 'http://myproxy.domain.com:8080'
os.environ['NO_PROXY'] = '127.0.0.1,localhost,.myinternal.domain.com'

Instantiate the Library Classes

The library exports two classes, SdMonitorClient and SdSecureClient which are used to connect to the Sysdig Monitor and Secure backend and execute actions.

For backwards compatibility purposes, a third class sdcclient is exported which is an alias of SdMonitorClient.

They are instantiated as follows:

from sdcclient import SdMonitorClient

api_token ="MY_API_TOKEN"

#
# Instantiate the Sysdig Monitor client
#
client = SdMonitorClient(api_token)

Once instantiated, all the methods documented in the Python Script Library can be called on the object.

Return Values

Every method in the SdMonitorClient or SdSecureClient classes returns a list with two entries. The first one is a boolean value indicating if the call was successful. The second entry depends on the result:

  • If the call was successful, it’s a dictionary reflecting the json returned by the underlying REST call

  • If the call failed, it’s a string describing the error

For an example on how to parse the output, see get_data_simple.py

Use Logs for Learning

If your goal is to interact with the REST API directly, you can use the Python client library to understand the REST interactions by logging the actions it takes. This is useful because full documentation of the REST API has not yet been created; it also provides a complete example of known working operations.

  • Use or modify an example, or write a new script against the Python sdcclient module.

  • Log the HTTP requests made by the script.

To log all the requests made by your script in significant detail, add to your script:

import logging
import httplib
httplib.HTTPConnection.debuglevel = 1

logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
logging.getLogger().setLevel(logging.DEBUG)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

Then run the command as normal.

Next Steps