This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

  • 1:
    • 2:

      Sysdig Python Client

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

      The Sysdig Platform is built on the Sysdig REST API, a few functions of which have been documented for public consumption. Until the REST API is more formally documented, we just provide some basic conventions; see Sysdig REST API Conventions.

      Learn more about using the sdcclient library and scripts:

      1 -

      Sysdig Python Script Library and Sample Scripts

      The Python Script Library and Function List, as well as the collection of sample scripts, are stored on GitHub, as summarized below.

      Script Library and Function List

      Access the latest library at Sysdig SDK Library

      Sample Scripts

      Access the scripts on GitHub:

      Recent scripts include:

      2 -

      Getting Started with SDCClient

      Follow the steps below to install and instantiate the Sysdig Python client library and scripts.


      • Python version 3.6 or above

      • pip version 1.3 or above

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

      • virtualenv (recommended)

      • Have your Sysdig API token on-hand

      Retrieve the Sysdig API Token

      When using the Sysdig API with custom scripts or applications, an API security token (specific to each team) must be supplied.

      1. Log in to Sysdig Monitor or Sysdig Secure and select Settings.

      2. Select User Profile.The Sysdig Monitor or Sysdig Secure API token is displayed (depending on which interface and team you logged in to).

      3. You can 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

      The library and example scripts are available in the Sysdig GitHub repository.

      Install the Sysdig Python client (sdcclient) using one of the following methods:

      Option 1 Use Pip Command

      Install the client by using pip. Run the following command:

      pip install sdcclient

      On-Premises Installs

      For On-Premises Sysdig platform installations, additional configuration is necessary to point to your API server rather than the default SaaS-based one, and also to easily connect when using a self-signed certificate for SSL.

      One way to handle this is by setting environment variables before running your Python scripts:

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

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

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

      Instantiate the Library Classes

      The library exports two classes, SdMonitorClient and SdSecureClient which are used to connect to the Sysdig Monitor/Secure back end and execute actions. (For backwards compatibility purposes, a third class SdcClient is exported which is an alias of SdMonitorClient.)

      They can be instantiated like this:

      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/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 this output, take a look at a simple example like

      Using Logs for Learning Purposes

      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
      requests_log = logging.getLogger("requests.packages.urllib3")
      requests_log.propagate = True

      Then run as normal.

      Next Steps