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
Learn more about using the sdcclient library and scripts:
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
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.
Log in to Sysdig Monitor or Sysdig Secure and select
User Profile.The Sysdig Monitor or Sysdig Secure API token
is displayed (depending on which interface and team you logged in
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
Install the Sysdig Python client (sdcclient) using one of the following
Option 1 Use Pip Command
Install the client by using pip. Run the following command:
pip install sdcclient
For On-Premises Sysdig platform
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:
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,
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
They can be instantiated like this:
from sdcclient import SdMonitorClient
# 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.
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
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
Log the HTTP requests made by the script.
To log all the requests made by your script in significant detail, add
to your script:
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.