Sysdig Cloud Python Script Library

This page documents the functions available in the Python Script Library for Sysdig Cloud. It is is a wrapper around the Sysdig Cloud API.

Function List

class sdcclient.SdMonitorClient(token='', sdc_url='https://app.sysdigcloud.com', ssl_verify=True, custom_headers=None)[source]
add_dashboard_panel(dashboard, name, panel_type, metrics, scope=None, sort_direction='desc', limit=None, layout=None)[source]
Description
Adds a panel to the dashboard. A panel can be a time series, or a top chart (i.e. bar chart), or a number panel.
Arguments
  • dashboard: dashboard to edit
  • name: name of the new panel
  • panel_type: type of the new panel. Valid values are: timeSeries, top, number
  • metrics: a list of dictionaries, specifying the metrics to show in the panel, and optionally, if there is only one metric, a grouping key to segment that metric by. A metric is any of the entries that can be found in the Metrics section of the Explore page in Sysdig Monitor. Metric entries require an aggregations section specifying how to aggregate the metric across time and groups of containers/hosts. A grouping key is any of the entries that can be found in the Show or Segment By sections of the Explore page in Sysdig Monitor. Refer to the examples section below for ready to use code snippets. Note, certain panels allow certain combinations of metrics and grouping keys:
    • timeSeries: 1 or more metrics OR 1 metric + 1 grouping key
    • top: 1 or more metrics OR 1 metric + 1 grouping key
    • number: 1 metric only
  • scope: filter to apply to the panel; must be based on metadata available in Sysdig Monitor; Example: kubernetes.namespace.name=’production’ and container.image=’nginx’.
  • sort_direction: Data sorting; The parameter is optional and it’s a string identifying the sorting direction (it can be desc or asc)
  • limit: This parameter sets the limit on the number of lines/bars shown in a timeSeries or top panel. In the case of more entities being available than the limit, the top entities according to the sort will be shown. The default value is 10 for top panels (for timeSeries the default is defined by Sysdig Monitor itself). Note that increasing the limit above 10 is not officially supported and may cause performance and rendering issues
  • layout: Size and position of the panel. The dashboard layout is defined by a grid of 12 columns, each row height is equal to the column height. For example, say you want to show 2 panels at the top: one panel might be 6 x 3 (half the width, 3 rows height) located in row 1 and column 1 (top-left corner of the viewport), the second panel might be 6 x 3 located in row 1 and position 7. The location is specified by a dictionary of row (row position), col (column position), size_x (width), size_y (height).
Success Return Value
A dictionary showing the details of the edited dashboard.
Example
examples/dashboard.py
clear_agents_config()[source]
static convert_scope_string_to_expression(scope)[source]

Description Internal function to convert a filter string to a filter object to be used with dashboards.

create_alert(name=None, description=None, severity=None, for_atleast_s=None, condition=None, segmentby=[], segment_condition='ANY', user_filter='', notify=None, enabled=True, annotations={}, alert_obj=None)[source]
Description
Create a threshold-based alert.
Arguments
  • name: the alert name. This will appear in the Sysdig Monitor UI and in notification emails.
  • description: the alert description. This will appear in the Sysdig Monitor UI and in notification emails.
  • severity: syslog-encoded alert severity. This is a number from 0 to 7 where 0 means ‘emergency’ and 7 is ‘debug’.
  • for_atleast_s: the number of consecutive seconds the condition must be satisfied for the alert to fire.
  • condition: the alert condition, as described here https://app.sysdigcloud.com/apidocs/#!/Alerts/post_api_alerts
  • segmentby: a list of Sysdig Monitor segmentation criteria that can be used to apply the alert to multiple entities. For example, segmenting a CPU alert by [‘host.mac’, ‘proc.name’] allows to apply it to any process in any machine.
  • segment_condition: When segmentby is specified (and therefore the alert will cover multiple entities) this field is used to determine when it will fire. In particular, you have two options for segment_condition: ANY (the alert will fire when at least one of the monitored entities satisfies the condition) and ALL (the alert will fire when all of the monitored entities satisfy the condition).
  • user_filter: a boolean expression combining Sysdig Monitor segmentation criteria that makes it possible to reduce the scope of the alert. For example: kubernetes.namespace.name=’production’ and container.image=’nginx’.
  • notify: the type of notification you want this alert to generate. Options are EMAIL, SNS, PAGER_DUTY, SYSDIG_DUMP.
  • enabled: if True, the alert will be enabled when created.
  • annotations: an optional dictionary of custom properties that you can associate to this alert for automation or management reasons
  • alert_obj: an optional fully-formed Alert object of the format returned in an “alerts” list by get_alerts() This is an alternative to creating the Alert using the individual parameters listed above.
Success Return Value
A dictionary describing the just created alert, with the format described at this link
Example
examples/create_alert.py
create_dashboard(name)[source]
Description
Creates an empty dashboard. You can then add panels by using add_dashboard_panel.
Arguments
  • name: the name of the dashboard that will be created.
Success Return Value
A dictionary showing the details of the new dashboard.
Example
examples/dashboard.py
create_dashboard_from_dashboard(newdashname, templatename, filter, shared=False, public=False)[source]
Description
Create a new dasboard using one of the existing dashboards as a template. You will be able to define the scope of the new dasboard.
Arguments
  • newdashname: the name of the dashboard that will be created.
  • viewname: the name of the dasboard to use as the template, as it appears in the Sysdig Monitor dashboard page.
  • filter: a boolean expression combining Sysdig Monitor segmentation criteria defines what the new dasboard will be applied to. For example: kubernetes.namespace.name=’production’ and container.image=’nginx’.
  • shared: if set to True, the new dashboard will be a shared one.
  • public: if set to True, the new dashboard will be shared with public token.
Success Return Value
A dictionary showing the details of the new dashboard.
Example
examples/create_dashboard.py
create_dashboard_from_file(dashboard_name, filename, filter, shared=False, public=False)[source]
Description

Create a new dasboard using a dashboard template saved to disk. See save_dashboard_to_file() to use the file to create a dashboard (usefl to create and restore backups).

The file can contain the following JSON formats: 1. dashboard object in the format of an array element returned by get_dashboards() 2. JSON object with the following properties:

  • version: dashboards API version (e.g. ‘v2’)
  • dashboard: dashboard object in the format of an array element returned by get_dashboards()
Arguments
  • dashboard_name: the name of the dashboard that will be created.
  • filename: name of a file containing a JSON object
  • filter: a boolean expression combining Sysdig Monitor segmentation criteria defines what the new dasboard will be applied to. For example: kubernetes.namespace.name=’production’ and container.image=’nginx’.
  • shared: if set to True, the new dashboard will be a shared one.
  • public: if set to True, the new dashboard will be shared with public token.
Success Return Value
A dictionary showing the details of the new dashboard.
Example
examples/dashboard_save_load.py
create_dashboard_from_template(dashboard_name, template, scope, shared=False, public=False)[source]
create_dashboard_from_view(newdashname, viewname, filter, shared=False, public=False)[source]
Description
Create a new dasboard using one of the Sysdig Monitor views as a template. You will be able to define the scope of the new dashboard.
Arguments
  • newdashname: the name of the dashboard that will be created.
  • viewname: the name of the view to use as the template for the new dashboard. This corresponds to the name that the view has in the Explore page.
  • filter: a boolean expression combining Sysdig Monitor segmentation criteria that defines what the new dasboard will be applied to. For example: kubernetes.namespace.name=’production’ and container.image=’nginx’.
  • shared: if set to True, the new dashboard will be a shared one.
  • public: if set to True, the new dashboard will be shared with public token.
Success Return Value
A dictionary showing the details of the new dashboard.
Example
examples/create_dashboard.py
create_dashboard_with_configuration(configuration)[source]
create_email_notification_channel(channel_name, email_recipients)[source]
create_notification_channel(channel)[source]
create_sysdig_capture(hostname, capture_name, duration, capture_filter='', folder='/')[source]
Description
Create a new sysdig capture. The capture will be immediately started.
Arguments
  • hostname: the hostname of the instrumented host where the capture will be taken.
  • capture_name: the name of the capture.
  • duration: the duration of the capture, in seconds.
  • capture_filter: a sysdig filter expression.
  • folder: directory in the S3 bucket where the capture will be saved.
Success Return Value
A dictionary showing the details of the new capture.
Example
examples/create_sysdig_capture.py
create_team(name, memberships=None, filter='', description='', show='host', theme='#7BB0B2', perm_capture=False, perm_custom_events=False, perm_aws_data=False)[source]
Description
Creates a new team
Arguments
  • name: the name of the team to create.
  • memberships: dictionary of (user-name, team-role) pairs that should describe new memberships of the team.
  • filter: the scope that this team is able to access within Sysdig Monitor.
  • description: describes the team that will be created.
  • show: possible values are host, container.
  • theme: the color theme that Sysdig Monitor will use when displaying the team.
  • perm_capture: if True, this team will be allowed to take sysdig captures.
  • perm_custom_events: if True, this team will be allowed to view all custom events from every user and agent.
  • perm_aws_data: if True, this team will have access to all AWS metrics and tags, regardless of the team’s scope.
Success Return Value
The newly created team.
Example
examples/user_team_mgmt.py
create_user_invite(user_email, first_name=None, last_name=None, system_role=None)[source]
Description
Invites a new user to use Sysdig Monitor. This should result in an email notification to the specified address.
Arguments
  • user_email: the email address of the user that will be invited to use Sysdig Monitor
  • first_name: the first name of the user being invited
  • last_name: the last name of the user being invited
  • system_role: system-wide privilege level for this user regardless of team. specify ‘ROLE_CUSTOMER’ to create an Admin. if not specified, default is a non-Admin (‘ROLE_USER’).
Success Return Value
The newly created user.
Examples
delete_alert(alert)[source]
Description
Deletes an alert.
Arguments
  • alert: the alert dictionary as returned by get_alerts().
Success Return Value
None.
Example
examples/delete_alert.py
delete_dashboard(dashboard)[source]
Description
Deletes a dashboard.
Arguments
  • dashboard: the dashboard object as returned by get_dashboards().
Success Return Value
None.
Example
examples/delete_dashboard.py
delete_event(event)[source]
Description
Deletes an event.
Arguments
  • event: the event object as returned by get_events().
Success Return Value
None.
Example
examples/delete_event.py
delete_notification_channel(channel)[source]
delete_team(name)[source]
Description
Deletes a team from Sysdig Monitor.
Arguments
  • name: the name of the team that will be deleted from Sysdig Monitor
Example
examples/user_team_mgmt.py
delete_user(user_email)[source]
Description
Deletes a user from Sysdig Monitor.
Arguments
  • user_email: the email address of the user that will be deleted from Sysdig Monitor
Example
examples/user_team_mgmt.py
download_sysdig_capture(capture_id)[source]
Description
Download a sysdig capture by id.
Arguments
  • capture_id: the capture id to download.
Success Return Value
The bytes of the scap
edit_team(name, memberships=None, filter=None, description=None, show=None, theme=None, perm_capture=None, perm_custom_events=None, perm_aws_data=None)[source]
Description
Edits an existing team. All arguments are optional. Team settings for any arguments unspecified will remain at their current settings.
Arguments
  • name: the name of the team to edit.
  • memberships: dictionary of (user-name, team-role) pairs that should describe new memberships of the team.
  • filter: the scope that this team is able to access within Sysdig Monitor.
  • description: describes the team that will be created.
  • show: possible values are host, container.
  • theme: the color theme that Sysdig Monitor will use when displaying the team.
  • perm_capture: if True, this team will be allowed to take sysdig captures.
  • perm_custom_events: if True, this team will be allowed to view all custom events from every user and agent.
  • perm_aws_data: if True, this team will have access to all AWS metrics and tags, regardless of the team’s scope.
Success Return Value
The edited team.
Example
examples/user_team_mgmt.py
edit_user(user_email, firstName=None, lastName=None, systemRole=None)[source]
find_dashboard_by(name=None)[source]
Description
Finds dashboards with the specified name. You can then delete the dashboard (with delete_dashboard()) or edit panels (with add_dashboard_panel() and remove_dashboard_panel())
Arguments
  • name: the name of the dashboards to find.
Success Return Value
A list of dictionaries of dashboards matching the specified name.
Example
examples/dashboard.py
get_agents_config()[source]
get_alerts()[source]
Description
Retrieve the list of alerts configured by the user.
Success Return Value
An array of alert dictionaries, with the format described at this link
Example
examples/list_alerts.py
get_connected_agents()[source]
Description
Return the agents currently connected to Sysdig Monitor for the current user.
Success Return Value
A list of the agents with all their attributes.
get_dashboard(dashboard_id)[source]
Description
Return a dashboard with the pased in ID. This includes the dashboards created by the user and the ones shared with them by other users.
Success Return Value
A dictionary containing the requested dashboard data.
Example
examples/dashboard_basic_crud.py
get_dashboards()[source]
Description
Return the list of dashboards available under the given user account. This includes the dashboards created by the user and the ones shared with her by other users.
Success Return Value
A dictionary containing the list of available sampling intervals.
Example
examples/list_dashboards.py
get_data(metrics, start_ts, end_ts=0, sampling_s=0, filter='', datasource_type='host', paging=None)[source]
Description
Export metric data (both time-series and table-based).
Arguments
  • metrics: a list of dictionaries, specifying the metrics and grouping keys that the query will return. A metric is any of the entries that can be found in the Metrics section of the Explore page in Sysdig Monitor. Metric entries require an aggregations section specifying how to aggregate the metric across time and containers/hosts. A grouping key is any of the entries that can be found in the Show or Segment By sections of the Explore page in Sysdig Monitor. These entries are used to apply single or hierarchical segmentation to the returned data and don’t require the aggregations section. Refer to the Example link below for ready-to-use code snippets.
  • start_ts: the UTC time (in seconds) of the beginning of the data window. A negative value can be optionally used to indicate a relative time in the past from now. For example, -3600 means “one hour ago”.
  • end_ts: the UTC time (in seconds) of the end of the data window, or 0 to indicate “now”. A negative value can also be optionally used to indicate a relative time in the past from now. For example, -3600 means “one hour ago”.
  • sampling_s: the duration of the samples that will be returned. 0 means that the whole data will be returned as a single sample.
  • filter: a boolean expression combining Sysdig Monitor segmentation criteria that defines what the query will be applied to. For example: kubernetes.namespace.name=’production’ and container.image=’nginx’.
  • datasource_type: specify the metric source for the request, can be container or host. Most metrics, for example cpu.used.percent or memory.bytes.used, are reported by both hosts and containers. By default, host metrics are used, but if the request contains a container-specific grouping key in the metric list/filter (e.g. container.name), then the container source is used. In cases where grouping keys are missing or apply to both hosts and containers (e.g. tag.Name), datasource_type can be explicitly set to avoid any ambiguity and allow the user to select precisely what kind of data should be used for the request. examples/get_data_datasource.py contains a few examples that should clarify the use of this argument.
  • paging: if segmentation of the query generates values for several different entities (e.g. containers/hosts), this parameter specifies which to include in the returned result. It’s specified as a dictionary of inclusive values for from and to with the default being { "from": 0, "to": 9 }, which will return values for the “top 10” entities. The meaning of “top” is query-dependent, based on points having been sorted via the specified group aggregation, with the results sorted in ascending order if the group aggregation is min or none, and descending order otherwise.
Success Return Value
A dictionary with the requested data. Data is organized in a list of time samples, each of which includes a UTC timestamp and a list of values, whose content and order reflect what was specified in the metrics argument.
Examples
get_data_retention_info()[source]
Description
Return the list of data retention intervals, with beginning and end UTC time for each of them. Sysdig Monitor performs rollups of the data it stores. This means that data is stored at different time granularities depending on how far back in time it is. This call can be used to know what precision you can expect before you make a call to get_data().
Success Return Value
A dictionary containing the list of available sampling intervals.
Example
examples/print_data_retention_info.py
get_events(name=None, from_ts=None, to_ts=None, tags=None)[source]
Description
Returns the list of Sysdig Monitor events.
Arguments
  • name: filter events by name.
  • from_ts: filter events by start time. Timestamp format is in UTC (seconds).
  • to_ts: filter events by end time. Timestamp format is in UTC (seconds).
  • tags: filter events by tags. Can be, for example tag1 = 'value1'.
Success Return Value
A dictionary containing the list of events.
Example
examples/list_events.py
get_explore_grouping_hierarchy()[source]
Description
Return the user’s current grouping hierarchy as visible in the Explore tab of Sysdig Monitor.
Success Return Value
A list containing the list of the user’s Explore grouping criteria.
Example
examples/print_explore_grouping.py
get_metrics()[source]
Description
Return the metric list that can be used for data requests/alerts/dashboards.
Success Return Value
A dictionary containing the list of available metrics.
Example
examples/list_metrics.py
get_n_connected_agents()[source]
Description
Return the number of agents currently connected to Sysdig Monitor for the current user.
Success Return Value
An integer number.
get_notification_channel(id)[source]
get_notification_ids(channels=None)[source]
Description
Get an array of all configured Notification Channel IDs, or a filtered subset of them.
Arguments
  • channels: an optional array of dictionaries to limit the set of Notification Channel IDs returned. If not specified, IDs for all configured Notification Channels are returned. Each dictionary contains a type field that can be one of the available types of Notification Channel (EMAIL, SNS, PAGER_DUTY, SLACK, OPSGENIE, VICTOROPS, WEBHOOK) as well as additional elements specific to each channel type.
Success Return Value
An array of Notification Channel IDs (integers).
Examples
get_notifications(from_ts, to_ts, state=None, resolved=None)[source]
Description
Returns the list of Sysdig Monitor alert notifications.
Arguments
  • from_ts: filter events by start time. Timestamp format is in UTC (seconds).
  • to_ts: filter events by start time. Timestamp format is in UTC (seconds).
  • state: filter events by alert state. Supported values are OK and ACTIVE.
  • resolved: filter events by resolution status. Supported values are True and False.
Success Return Value
A dictionary containing the list of notifications.
Example
examples/list_alert_notifications.py
get_sysdig_captures(from_sec=None, to_sec=None, scope_filter=None)[source]
Description
Returns the list of sysdig captures for the user.
Arguments
  • from_sec: the start of the timerange for which to get the captures
  • end_sec: the end of the timerange for which to get the captures
  • scope_filter: this is a SysdigMonitor-like filter (e.g ‘container.image=ubuntu’). When provided, events are filtered by their scope, so only a subset will be returned (e.g. ‘container.image=ubuntu’ will provide only events that have happened on an ubuntu container).
Success Return Value
A dictionary containing the list of captures.
Example
examples/list_sysdig_captures.py
get_team(name)[source]
Description
Return the team with the specified team name, if it is present.
Arguments
  • name: the name of the team to return
Success Return Value
The requested team.
Example
examples/user_team_mgmt.py
get_team_ids(teams)[source]
get_teams(team_filter='')[source]
Description
Return the set of teams that match the filter specified. The team_filter should be a substring of the names of the teams to be returned.
Arguments
  • team_filter: the team filter to match when returning the list of teams
Success Return Value
The teams that match the filter.
get_topology_map(grouping_hierarchy, time_window_s, sampling_time_s)[source]
get_user(user_email)[source]
get_user_api_token(username, teamname)[source]
get_user_ids(users)[source]
get_user_info()[source]
Description
Get details about the current user.
Success Return Value
A dictionary containing information about the user, for example its email and the maximum number of agents it can install.
Example
examples/print_user_info.py
get_user_token()[source]
Description
Return the API token of the current user.
Success Return Value
A string containing the user token.
get_users()[source]
Description
Return a list containing details about all users in the Sysdig Monitor environment. The API token must have Admin rights for this to succeed.
Success Return Value
A list user objects
get_view(name)[source]
get_views_list()[source]
lasterr = None[source]
list_memberships(team)[source]
Description
List all memberships for specified team.
Arguments
  • team: the name of the team for which we want to see memberships
Result
Dictionary of (user-name, team-role) pairs that should describe memberships of the team.
Example
examples/user_team_mgmt_extended.py
list_notification_channels()[source]
Description
List all configured Notification Channels
Arguments
none
Success Return Value
A JSON representation of all the notification channels
poll_sysdig_capture(capture)[source]
Description
Fetch the updated state of a sysdig capture. Can be used to poll the status of a capture that has been previously created and started with create_sysdig_capture().
Arguments
  • capture: the capture object as returned by get_sysdig_captures() or create_sysdig_capture().
Success Return Value
A dictionary showing the updated details of the capture. Use the status field to check the progress of a capture.
Example
examples/create_sysdig_capture.py
post_event(name, description=None, severity=None, event_filter=None, tags=None)[source]
Description
Send an event to Sysdig Monitor. The events you post are available in the Events tab in the Sysdig Monitor UI and can be overlied to charts.
Arguments
  • name: the name of the new event.
  • description: a longer description offering detailed information about the event.
  • severity: syslog style from 0 (high) to 7 (low).
  • event_filter: 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'.
  • tags: a list of key-value dictionaries that can be used to tag the event. Can be used for filtering/segmenting purposes in Sysdig Monitor.
Success Return Value
A dictionary describing the new event.
Examples
remove_dashboard_panel(dashboard, panel_name)[source]
Description
Removes a panel from the dashboard. The panel to remove is identified by the specified name.
Arguments
  • name: name of the panel to find and remove
Success Return Value
A dictionary showing the details of the edited dashboard.
Example
examples/dashboard.py
remove_memberships(team, users)[source]
Description
Remove user memberships from specified team.
Arguments
  • team: the name of the team from which user memberships are removed
  • users: list of usernames which should be removed from team
Example
examples/user_team_mgmt_extended.py
save_dashboard_to_file(dashboard, filename)[source]
Description

Save a dashboard to disk. See create_dashboard_from_file() to use the file to create a dashboard (usefl to create and restore backups).

The file will contain a JSON object with the following properties: * version: dashboards API version (e.g. ‘v2’) * dashboard: dashboard object in the format of an array element returned by get_dashboards()

Arguments
  • dashboard: dashboard object in the format of an array element returned by get_dashboards()
  • filename: name of a file that will contain a JSON object
Example
examples/dashboard_save_load.py
save_memberships(team, memberships)[source]
Description
Create new user team memberships or update existing ones.
Arguments
  • team: the name of the team for which we are creating new memberships
  • memberships: dictionary of (user-name, team-role) pairs that should describe new memberships
Example
examples/user_team_mgmt_extended.py
set_agents_config(config)[source]
set_explore_grouping_hierarchy(new_hierarchy)[source]
Description
Changes the grouping hierarchy in the Explore panel of the current user.
Arguments
  • new_hierarchy: a list of sysdig segmentation metrics indicating the new grouping hierarchy.
update_alert(alert)[source]
Description
Update a modified threshold-based alert.
Arguments
  • alert: one modified alert object of the same format as those in the list returned by get_alerts().
Success Return Value
The updated alert.
Example
examples/update_alert.py
update_dashboard(dashboard_data)[source]
Description
Updates dashboard with provided in data. Please note that the dictionary will require a valid ID and version field to work as expected.
Success Return Value
A dictionary containing the updated dashboard data.
Example
examples/dashboard_basic_crud.py
update_notification_channel(channel)[source]
update_notification_resolution(notification, resolved)[source]
Description
Updates the resolution status of an alert notification.
Arguments
  • notification: notification object as returned by get_notifications().
  • resolved: new resolution status. Supported values are True and False.
Success Return Value
The updated notification.
Example
examples/resolve_alert_notifications.py
class sdcclient.SdSecureClient(token='', sdc_url='https://secure.sysdig.com', ssl_verify=True, custom_headers=None)[source]
add_compliance_task(name, module_name='docker-bench-security', schedule='06:00:00Z/PT12H', scope=None, enabled=True)[source]
Description
Add a new compliance task.
Arguments
  • name: The name of the task e.g. ‘Check Docker Compliance’.
  • module_name: The name of the module that implements this task. Separate from task name in case you want to use the same module to run separate tasks with different scopes or schedules. [ ‘docker-bench-security’, ‘kube-bench’ ]
  • schedule: The frequency at which this task should run. Expressed as an ISO 8601 Duration
  • scope: The agent will only run the task on hosts matching this scope or on hosts where containers match this scope.
  • enabled: Whether this task should actually run as defined by its schedule.
Success Return Value
A JSON representation of the compliance task.
add_falco_list(name, items)[source]
Description
Create a new list
Arguments
  • name: A name for this object. Should exactly be the value of the “list” property of the yaml object.
  • items: the array of items as represented in the yaml List.
Success Return Value
A JSON object representing the falco list.
add_falco_macro(name, condition)[source]
Description
Create a new macro
Arguments
  • name: A name for this object. Should exactly be the value of the “macro” property of the yaml object.
  • condition: the full condition text exactly as represented in the yaml file.
Success Return Value
A JSON object representing the falco macro.
add_policy(name, description, rule_names=[], actions=[], scope=None, severity=0, enabled=True, notification_channels=[])[source]
Description
Add a new policy.
Arguments
  • name: A short name for the policy
  • description: Description of policy
  • rule_names: Array of rule names. (They must be names instead of ids, as the rules list view is by name, to account for multiple rules having the same name).
  • actions: It can be a stop, pause and/or capture action
  • scope: Where the policy is being applied- Container, Host etc.. (example: “container.image.repository = sysdig/agent”)
  • enabled: True if the policy should be considered
  • severity: How severe is this policy when violated. Range from 0 to 7 included.
  • notification_channels: ids of the notification channels to subscribe to the policy
Success Return Value
The string “OK”
add_policy_json(policy_json)[source]
Description
Add a new policy using the provided json.
Arguments
  • policy_json: a description of the new policy
Success Return Value
The string “OK”
Example
examples/add_policy.py
add_rule(name, details={}, description='', tags=[])[source]
Description
Create a new rule
Arguments
  • name: A name for this object. Should exactly be the value of the “rule” property of the yaml object.
  • details: The rule description as a python dictionary.
  • description: A description of this rule. No newlines/formatting.
  • tags: The set of tags.
Success Return Value
A JSON object representing the rule.
clear_agents_config()[source]
create_default_policies()[source]
Description
Create new policies based on the currently available set of rules. For now, this only covers Falco rules, but we might extend the endpoint later. The backend should use the defaultPolicies property of a previously provided FalcoRulesFiles model as guidance on the set of policies to create. The backend should only create new policies (not delete or modify), and should only create new policies if there is not an existing policy with the same name.
Arguments
  • None
Success Return Value
JSON containing details on any new policies that were added.
Example
examples/create_default_policies.py
create_email_notification_channel(channel_name, email_recipients)[source]
create_notification_channel(channel)[source]
create_sysdig_capture(hostname, capture_name, duration, capture_filter='', folder='/')[source]
Description
Create a new sysdig capture. The capture will be immediately started.
Arguments
  • hostname: the hostname of the instrumented host where the capture will be taken.
  • capture_name: the name of the capture.
  • duration: the duration of the capture, in seconds.
  • capture_filter: a sysdig filter expression.
  • folder: directory in the S3 bucket where the capture will be saved.
Success Return Value
A dictionary showing the details of the new capture.
Example
examples/create_sysdig_capture.py
create_team(name, memberships=None, filter='', description='', show='host', theme='#7BB0B2', perm_capture=False, perm_custom_events=False, perm_aws_data=False)[source]
Description
Creates a new team
Arguments
  • name: the name of the team to create.
  • memberships: dictionary of (user-name, team-role) pairs that should describe new memberships of the team.
  • filter: the scope that this team is able to access within Sysdig Monitor.
  • description: describes the team that will be created.
  • show: possible values are host, container.
  • theme: the color theme that Sysdig Monitor will use when displaying the team.
  • perm_capture: if True, this team will be allowed to take sysdig captures.
  • perm_custom_events: if True, this team will be allowed to view all custom events from every user and agent.
  • perm_aws_data: if True, this team will have access to all AWS metrics and tags, regardless of the team’s scope.
Success Return Value
The newly created team.
Example
examples/user_team_mgmt.py
create_user_invite(user_email, first_name=None, last_name=None, system_role=None)[source]
Description
Invites a new user to use Sysdig Monitor. This should result in an email notification to the specified address.
Arguments
  • user_email: the email address of the user that will be invited to use Sysdig Monitor
  • first_name: the first name of the user being invited
  • last_name: the last name of the user being invited
  • system_role: system-wide privilege level for this user regardless of team. specify ‘ROLE_CUSTOMER’ to create an Admin. if not specified, default is a non-Admin (‘ROLE_USER’).
Success Return Value
The newly created user.
Examples
delete_all_policies()[source]
Description
Delete all existing policies. The falco rules file is unchanged.
Arguments
  • None
Success Return Value
The string “Policies Deleted”
Example
examples/delete_all_policies.py
delete_compliance_task(id)[source]
Description
Delete the compliance task with the given id
Arguments
  • id: the id of the compliance task to delete
delete_event(event)[source]
Description
Deletes an event.
Arguments
  • event: the event object as returned by get_events().
Success Return Value
None.
Example
examples/delete_event.py
delete_falco_list(id)[source]
Description
Delete the list with given id.
Arguments
  • id: The list id
Success Return Value
A JSON object representing the list.
delete_falco_macro(id)[source]
Description
Delete the macro with given id.
Arguments
  • id: The macro id
Success Return Value
A JSON object representing the macro.
delete_notification_channel(channel)[source]
delete_policy_id(id)[source]
Description
Delete the policy with the given id
Arguments
  • id: the id of the policy to delete
Success Return Value
The JSON object representing the now-deleted policy.
Example
examples/delete_policy.py
delete_policy_name(name)[source]
Description
Delete the policy with the given name.
Arguments
  • name: the name of the policy to delete
Success Return Value
The JSON object representing the now-deleted policy.
Example
examples/delete_policy.py
delete_rule(id)[source]
Description
Delete the rule with given id.
Arguments
  • id: The rule id
Success Return Value
A JSON object representing the rule.
delete_team(name)[source]
Description
Deletes a team from Sysdig Monitor.
Arguments
  • name: the name of the team that will be deleted from Sysdig Monitor
Example
examples/user_team_mgmt.py
delete_user(user_email)[source]
Description
Deletes a user from Sysdig Monitor.
Arguments
  • user_email: the email address of the user that will be deleted from Sysdig Monitor
Example
examples/user_team_mgmt.py
download_sysdig_capture(capture_id)[source]
Description
Download a sysdig capture by id.
Arguments
  • capture_id: the capture id to download.
Success Return Value
The bytes of the scap
edit_team(name, memberships=None, filter=None, description=None, show=None, theme=None, perm_capture=None, perm_custom_events=None, perm_aws_data=None)[source]
Description
Edits an existing team. All arguments are optional. Team settings for any arguments unspecified will remain at their current settings.
Arguments
  • name: the name of the team to edit.
  • memberships: dictionary of (user-name, team-role) pairs that should describe new memberships of the team.
  • filter: the scope that this team is able to access within Sysdig Monitor.
  • description: describes the team that will be created.
  • show: possible values are host, container.
  • theme: the color theme that Sysdig Monitor will use when displaying the team.
  • perm_capture: if True, this team will be allowed to take sysdig captures.
  • perm_custom_events: if True, this team will be allowed to view all custom events from every user and agent.
  • perm_aws_data: if True, this team will have access to all AWS metrics and tags, regardless of the team’s scope.
Success Return Value
The edited team.
Example
examples/user_team_mgmt.py
edit_user(user_email, firstName=None, lastName=None, systemRole=None)[source]
get_agents_config()[source]
get_command_audit(id, metrics=[])[source]
Description
Get a command audit.
Arguments
  • id: the id of the command audit to get.
Success Return Value
A JSON representation of the command audit.
get_compliance_results(id)[source]
Description
Retrieve the details for a specific compliance task run result.
Arguments
  • id: the id of the compliance task run to get.
Success Return Value
A JSON representation of the compliance task run result.
get_compliance_results_csv(id)[source]
Description
Retrieve the details for a specific compliance task run result in csv.
Arguments
  • id: the id of the compliance task run to get.
Success Return Value
A CSV representation of the compliance task run result.
get_compliance_task(id)[source]
Description
Get a compliance task.
Arguments
  • id: the id of the compliance task to get.
Success Return Value
A JSON representation of the compliance task.
get_connected_agents()[source]
Description
Return the agents currently connected to Sysdig Monitor for the current user.
Success Return Value
A list of the agents with all their attributes.
get_data(metrics, start_ts, end_ts=0, sampling_s=0, filter='', datasource_type='host', paging=None)[source]
Description
Export metric data (both time-series and table-based).
Arguments
  • metrics: a list of dictionaries, specifying the metrics and grouping keys that the query will return. A metric is any of the entries that can be found in the Metrics section of the Explore page in Sysdig Monitor. Metric entries require an aggregations section specifying how to aggregate the metric across time and containers/hosts. A grouping key is any of the entries that can be found in the Show or Segment By sections of the Explore page in Sysdig Monitor. These entries are used to apply single or hierarchical segmentation to the returned data and don’t require the aggregations section. Refer to the Example link below for ready-to-use code snippets.
  • start_ts: the UTC time (in seconds) of the beginning of the data window. A negative value can be optionally used to indicate a relative time in the past from now. For example, -3600 means “one hour ago”.
  • end_ts: the UTC time (in seconds) of the end of the data window, or 0 to indicate “now”. A negative value can also be optionally used to indicate a relative time in the past from now. For example, -3600 means “one hour ago”.
  • sampling_s: the duration of the samples that will be returned. 0 means that the whole data will be returned as a single sample.
  • filter: a boolean expression combining Sysdig Monitor segmentation criteria that defines what the query will be applied to. For example: kubernetes.namespace.name=’production’ and container.image=’nginx’.
  • datasource_type: specify the metric source for the request, can be container or host. Most metrics, for example cpu.used.percent or memory.bytes.used, are reported by both hosts and containers. By default, host metrics are used, but if the request contains a container-specific grouping key in the metric list/filter (e.g. container.name), then the container source is used. In cases where grouping keys are missing or apply to both hosts and containers (e.g. tag.Name), datasource_type can be explicitly set to avoid any ambiguity and allow the user to select precisely what kind of data should be used for the request. examples/get_data_datasource.py contains a few examples that should clarify the use of this argument.
  • paging: if segmentation of the query generates values for several different entities (e.g. containers/hosts), this parameter specifies which to include in the returned result. It’s specified as a dictionary of inclusive values for from and to with the default being { "from": 0, "to": 9 }, which will return values for the “top 10” entities. The meaning of “top” is query-dependent, based on points having been sorted via the specified group aggregation, with the results sorted in ascending order if the group aggregation is min or none, and descending order otherwise.
Success Return Value
A dictionary with the requested data. Data is organized in a list of time samples, each of which includes a UTC timestamp and a list of values, whose content and order reflect what was specified in the metrics argument.
Examples
get_data_retention_info()[source]
Description
Return the list of data retention intervals, with beginning and end UTC time for each of them. Sysdig Monitor performs rollups of the data it stores. This means that data is stored at different time granularities depending on how far back in time it is. This call can be used to know what precision you can expect before you make a call to get_data().
Success Return Value
A dictionary containing the list of available sampling intervals.
Example
examples/print_data_retention_info.py
get_default_falco_rules_files()[source]
Description
Get the set of falco rules files from the backend. The _files programs and endpoints are a
replacement for the system_file endpoints and allow for publishing multiple files instead of a single file as well as publishing multiple variants of a given file that are compatible with different agent versions.
Arguments
  • None
Success Return Value
A dict with the following keys:
  • tag: A string used to uniquely identify this set of rules. It is recommended that this tag change every time the set of rules is updated.
  • files: An array of dicts. Each dict has the following keys:
    • name: the name of the file
    • variants: An array of dicts with the following keys:
      • requiredEngineVersion: the minimum falco engine version that can read this file
      • content: the falco rules content
An example would be:
{‘tag’: ‘v1.5.9’,
‘files’: [
{

‘name’: ‘falco_rules.yaml’, ‘variants’: [

{
‘content’: ‘- required_engine_version: 29
  • list: foo
‘,
‘requiredEngineVersion’: 29

}, {

‘content’: ‘- required_engine_version: 1
  • list: foo
‘,
‘requiredEngineVersion’: 1

}

]

}, {

‘name’: ‘k8s_audit_rules.yaml’, ‘variants’: [

{
‘content’: ‘# some comment
‘,
‘requiredEngineVersion’: 0

}

]

}

]

}

Example
examples/get_default_falco_rules_files.py
get_events(name=None, from_ts=None, to_ts=None, tags=None)[source]
Description
Returns the list of Sysdig Monitor events.
Arguments
  • name: filter events by name.
  • from_ts: filter events by start time. Timestamp format is in UTC (seconds).
  • to_ts: filter events by end time. Timestamp format is in UTC (seconds).
  • tags: filter events by tags. Can be, for example tag1 = 'value1'.
Success Return Value
A dictionary containing the list of events.
Example
examples/list_events.py
get_falco_list_id(id)[source]
Description
Retrieve info about a single falco list
Arguments
  • id: the id of the falco list
Success Return Value
A JSON object representing the falco list.
get_falco_lists_group(name)[source]
Description
Retrieve a group of all falco lists having the given name. This is used to show how a base list is modified by later lists that override/append to the list.
Arguments
  • name: the name of the falco lists group
Success Return Value
A JSON object representing the list of falco lists.
get_falco_macro_id(id)[source]
Description
Retrieve info about a single falco macro
Arguments
  • id: the id of the falco macro
Success Return Value
A JSON object representing the falco macro.
get_falco_macros_group(name)[source]
Description
Retrieve a group of all falco groups having the given name. This is used to show how a base macro is modified by later macrosthat override/append to the macro.
Arguments
  • name: the name of the falco macros group
Success Return Value
A JSON object representing the list of falco macros.
get_image_profile(profileId)[source]
Description
Find the image profile with a (partial) profile ID <profileId> and return its json description.
Arguments
  • name: the name of the image profile to fetch
Success Return Value
A JSON object containing the description of the image profile. If there is no image profile with the given name, returns False. Moreover, it could happen that more than one profile IDs have a collision. It is due to the fact that a partial profile ID can be passed and interpreted; in this case a set of collision profiles is returned, and the full complete ID string is printed. In this case, it returns false.
get_more_policy_events(ctx)[source]
Description
Fetch additional policy events after an initial call to get_policy_events_range() / get_policy_events_duration() or a prior call to get_more_policy_events.
Arguments
Success Return Value
An array containing:
  • A context object that should be passed to later calls to get_more_policy_events()
  • An array of policy events, in JSON format. Each policy event contains the following:
    • hostMac: the mac address of the machine where the event occurred
    • severity: a severity level from 1-7
    • timestamp: when the event occurred (ns since the epoch)
    • version: a version number for this message (currently 1)
    • policyId: a reference to the policy that generated this policy event
    • output: A string describing the event that occurred
    • id: a unique identifier for this policy event
    • isAggregated: if true, this is a combination of multiple policy events
    • containerId: the container in which the policy event occurred

When the number of policy events returned is 0, there are no remaining events and you can stop calling get_more_policy_events().

Example
examples/get_secure_policy_events.py
get_n_connected_agents()[source]
Description
Return the number of agents currently connected to Sysdig Monitor for the current user.
Success Return Value
An integer number.
get_notification_channel(id)[source]
get_notification_ids(channels=None)[source]
Description
Get an array of all configured Notification Channel IDs, or a filtered subset of them.
Arguments
  • channels: an optional array of dictionaries to limit the set of Notification Channel IDs returned. If not specified, IDs for all configured Notification Channels are returned. Each dictionary contains a type field that can be one of the available types of Notification Channel (EMAIL, SNS, PAGER_DUTY, SLACK, OPSGENIE, VICTOROPS, WEBHOOK) as well as additional elements specific to each channel type.
Success Return Value
An array of Notification Channel IDs (integers).
Examples
get_policy(name)[source]
Description
Find the policy with name <name> and return its json description.
Arguments
  • name: the name of the policy to fetch
Success Return Value
A JSON object containing the description of the policy. If there is no policy with the given name, returns False.
Example
examples/get_policy.py
get_policy_events_duration(duration_sec, sampling=None, aggregations=None, scope_filter=None, event_filter=None)[source]
Description
Fetch all policy events that occurred in the last duration_sec seconds. This method is used in conjunction with get_more_policy_events() to provide paginated access to policy events.
Arguments
  • duration_sec: Fetch all policy events that have occurred in the last duration_sec seconds.
  • sampling: Sample all policy events using sampling interval.
  • aggregations: When present it specifies how to aggregate events (sampling does not need to be specified, because when it’s present it automatically means events will be aggregated). This field can either be a list of scope metrics or a list of policyEvents fields but (currently) not a mix of the two. When policy events fields are specified, only these can be used= severity, agentId, containerId, policyId, ruleType.
  • scope_filter: this is a SysdigMonitor-like filter (e.g ‘container.image=ubuntu’). When provided, events are filtered by their scope, so only a subset will be returned (e.g. ‘container.image=ubuntu’ will provide only events that have happened on an ubuntu container).
  • event_filter: this is a SysdigMonitor-like filter (e.g. policyEvent.policyId=3). When provided, events are filtered by some of their properties. Currently the supported set of filters is policyEvent.all(which can be used just with matches, policyEvent.policyId, policyEvent.id, policyEvent.severity, policyEvent.ruleTye, policyEvent.ruleSubtype.
Success Return Value
An array containing:
  • A context object that should be passed to later calls to get_more_policy_events.
  • An array of policy events, in JSON format. See get_more_policy_events() for details on the contents of policy events.
Example
examples/get_secure_policy_events.py
get_policy_events_id_duration(id, duration_sec, sampling=None, aggregations=None, scope_filter=None, event_filter=None)[source]
Description
Fetch all policy events with id that occurred in the last duration_sec seconds. This method is used in conjunction with get_more_policy_events() to provide paginated access to policy events.
Arguments
  • id: the id of the policy events to fetch.
  • duration_sec: Fetch all policy events that have occurred in the last duration_sec seconds.
  • sampling: Sample all policy events using sampling interval.
  • aggregations: When present it specifies how to aggregate events (sampling does not need to be specified, because when it’s present it automatically means events will be aggregated). This field can either be a list of scope metrics or a list of policyEvents fields but (currently) not a mix of the two. When policy events fields are specified, only these can be used= severity, agentId, containerId, policyId, ruleType.
  • scope_filter: this is a SysdigMonitor-like filter (e.g ‘container.image=ubuntu’). When provided, events are filtered by their scope, so only a subset will be returned (e.g. ‘container.image=ubuntu’ will provide only events that have happened on an ubuntu container).
  • event_filter: this is a SysdigMonitor-like filter (e.g. policyEvent.policyId=3). When provided, events are filtered by some of their properties. Currently the supported set of filters is policyEvent.all(which can be used just with matches, policyEvent.policyId, policyEvent.id, policyEvent.severity, policyEvent.ruleTye, policyEvent.ruleSubtype.
Success Return Value
An array containing:
  • A context object that should be passed to later calls to get_more_policy_events.
  • An array of policy events, in JSON format. See get_more_policy_events() for details on the contents of policy events.
Example
examples/get_secure_policy_events.py
get_policy_events_id_range(id, from_sec, to_sec, sampling=None, aggregations=None, scope_filter=None, event_filter=None)[source]
Description
Fetch all policy events with id that occurred in the time range [from_sec:to_sec]. This method is used in conjunction with get_more_policy_events() to provide paginated access to policy events.
Arguments
  • id: the id of the policy events to fetch.
  • from_sec: the start of the timerange for which to get events
  • end_sec: the end of the timerange for which to get events
  • sampling: sample all policy events using sampling interval.
  • scope_filter: this is a SysdigMonitor-like filter (e.g ‘container.image=ubuntu’). When provided, events are filtered by their scope, so only a subset will be returned (e.g. ‘container.image=ubuntu’ will provide only events that have happened on an ubuntu container).
  • event_filter: this is a SysdigMonitor-like filter (e.g. policyEvent.policyId=3). When provided, events are filtered by some of their properties. Currently the supported set of filters is policyEvent.all(which can be used just with matches, policyEvent.policyId, policyEvent.id, policyEvent.severity, policyEvent.ruleTye, policyEvent.ruleSubtype.
  • aggregations: When present it specifies how to aggregate events (sampling does not need to be specified, because when it’s present it automatically means events will be aggregated). This field can either be a list of scope metrics or a list of policyEvents fields but (currently) not a mix of the two. When policy events fields are specified, only these can be used= severity, agentId, containerId, policyId, ruleType.
Success Return Value
An array containing:
  • A context object that should be passed to later calls to get_more_policy_events.
  • An array of policy events, in JSON format. See get_more_policy_events() for details on the contents of policy events.
Example
examples/get_secure_policy_events.py
get_policy_events_range(from_sec, to_sec, sampling=None, aggregations=None, scope_filter=None, event_filter=None)[source]
Description
Fetch all policy events that occurred in the time range [from_sec:to_sec]. This method is used in conjunction with get_more_policy_events() to provide paginated access to policy events.
Arguments
  • from_sec: the start of the timerange for which to get events
  • end_sec: the end of the timerange for which to get events
  • sampling: sample all policy events using sampling interval.
  • aggregations: When present it specifies how to aggregate events (sampling does not need to be specified, because when it’s present it automatically means events will be aggregated). This field can either be a list of scope metrics or a list of policyEvents fields but (currently) not a mix of the two. When policy events fields are specified, only these can be used= severity, agentId, containerId, policyId, ruleType.
  • scope_filter: this is a SysdigMonitor-like filter (e.g ‘container.image=ubuntu’). When provided, events are filtered by their scope, so only a subset will be returned (e.g. ‘container.image=ubuntu’ will provide only events that have happened on an ubuntu container).
  • event_filter: this is a SysdigMonitor-like filter (e.g. policyEvent.policyId=3). When provided, events are filtered by some of their properties. Currently the supported set of filters is policyEvent.all(which can be used just with matches, policyEvent.policyId, policyEvent.id, policyEvent.severity, policyEvent.ruleTye, policyEvent.ruleSubtype.
Success Return Value
An array containing:
  • A context object that should be passed to later calls to get_more_policy_events.
  • An array of policy events, in JSON format. See get_more_policy_events() for details on the contents of policy events.
Example
examples/get_secure_policy_events.py
get_policy_id(id)[source]
Description
Find the policy with id <id> and return its json description.
Arguments
  • id: the id of the policy to fetch
Success Return Value
A JSON object containing the description of the policy. If there is no policy with the given name, returns False.
get_rule_id(id)[source]
Description
Retrieve info about a single rule
Arguments
  • id: the id of the rule
Success Return Value
A JSON object representing the rule.
get_rules_group(name)[source]
Description
Retrieve a group of all rules having the given name. This is used to show how a base rule is modified by later rules that override/append to the rule.
Arguments
  • name: the name of the rule group
Success Return Value
A JSON object representing the list of rules.
get_sysdig_captures(from_sec=None, to_sec=None, scope_filter=None)[source]
Description
Returns the list of sysdig captures for the user.
Arguments
  • from_sec: the start of the timerange for which to get the captures
  • end_sec: the end of the timerange for which to get the captures
  • scope_filter: this is a SysdigMonitor-like filter (e.g ‘container.image=ubuntu’). When provided, events are filtered by their scope, so only a subset will be returned (e.g. ‘container.image=ubuntu’ will provide only events that have happened on an ubuntu container).
Success Return Value
A dictionary containing the list of captures.
Example
examples/list_sysdig_captures.py
get_system_falco_rules()[source]
Description
Get the system falco rules file in use for this customer. See the Falco wiki for documentation on the falco rules format.
Arguments
  • None
Success Return Value
The contents of the system falco rules file.
Example
examples/get_secure_system_falco_rules.py
get_team(name)[source]
Description
Return the team with the specified team name, if it is present.
Arguments
  • name: the name of the team to return
Success Return Value
The requested team.
Example
examples/user_team_mgmt.py
get_team_ids(teams)[source]
get_teams(team_filter='')[source]
Description
Return the set of teams that match the filter specified. The team_filter should be a substring of the names of the teams to be returned.
Arguments
  • team_filter: the team filter to match when returning the list of teams
Success Return Value
The teams that match the filter.
get_topology_map(grouping_hierarchy, time_window_s, sampling_time_s)[source]
get_user(user_email)[source]
get_user_api_token(username, teamname)[source]
get_user_falco_rules()[source]
Description
Get the user falco rules file in use for this customer. See the Falco wiki for documentation on the falco rules format.
Arguments
  • None
Success Return Value
The contents of the user falco rules file.
Example
examples/get_secure_user_falco_rules.py
get_user_ids(users)[source]
get_user_info()[source]
Description
Get details about the current user.
Success Return Value
A dictionary containing information about the user, for example its email and the maximum number of agents it can install.
Example
examples/print_user_info.py
get_user_token()[source]
Description
Return the API token of the current user.
Success Return Value
A string containing the user token.
get_users()[source]
Description
Return a list containing details about all users in the Sysdig Monitor environment. The API token must have Admin rights for this to succeed.
Success Return Value
A list user objects
lasterr = None[source]
list_commands_audit(from_sec=None, to_sec=None, scope_filter=None, command_filter=None, limit=100, offset=0, metrics=[])[source]
Description
List the commands audit.
Arguments
  • from_sec: the start of the timerange for which to get commands audit.
  • end_sec: the end of the timerange for which to get commands audit.
  • scope_filter: this is a SysdigMonitor-like filter (e.g ‘container.image=ubuntu’). When provided, commands are filtered by their scope, so only a subset will be returned (e.g. ‘container.image=ubuntu’ will provide only commands that have happened on an ubuntu container).
  • command_filter: this is a SysdigMonitor-like filter (e.g. command.comm=”touch”). When provided, commands are filtered by some of their properties. Currently the supported set of filters is command.comm, command.cwd, command.pid, command.ppid, command.uid, command.loginshell.id, command.loginshell.distance
  • limit: Maximum number of commands in the response.
  • metrics: A list of metric values to include in the return.
Success Return Value
A JSON representation of the commands audit.
list_compliance_results(limit=50, direction=None, cursor=None, filter='')[source]
Description
Get the list of all compliance tasks runs.
Arguments
  • limit: Maximum number of alerts in the response.
  • direction: the direction (PREV or NEXT) that determines which results to return in relation to cursor.
  • cursor: An opaque string representing the current position in the list of alerts. It’s provided in the ‘responseMetadata’ of the list_alerts response.
  • filter: an optional case insensitive filter used to match against the completed task name and return matching results.
Success Return Value
A JSON list with the representation of each compliance task run.
list_compliance_tasks()[source]
Description
Get the list of all compliance tasks.
Arguments
  • None
Success Return Value
A JSON list with the representation of each compliance task.
list_falco_lists()[source]
Description
Returns the list of falco lists in the system. These are grouped by name and do not necessarily represent individual falco list objects, as multiple falco lists can have the same name.
Arguments
  • None
Success Return Value
A JSON object representing the list of falco lists.
list_falco_macros()[source]
Description
Returns the list of macros in the system. These are grouped by name and do not necessarily represent individual macro objects, as multiple macros can have the same name.
Arguments
  • None
Success Return Value
A JSON object representing the list of falco macros.
list_image_profiles()[source]
Description
List the current set of image profiles.
Arguments
  • None
Success Return Value
A JSON object containing the details of each profile.
list_memberships(team)[source]
Description
List all memberships for specified team.
Arguments
  • team: the name of the team for which we want to see memberships
Result
Dictionary of (user-name, team-role) pairs that should describe memberships of the team.
Example
examples/user_team_mgmt_extended.py
list_notification_channels()[source]
Description
List all configured Notification Channels
Arguments
none
Success Return Value
A JSON representation of all the notification channels
list_policies()[source]
Description
List the current set of policies.
Arguments
  • None
Success Return Value
A JSON object containing the number and details of each policy.
Example
examples/list_policies.py
list_rules()[source]
Description
Returns the list of rules in the system. These are grouped by name and do not necessarily represent individual rule objects, as multiple rules can have the same name.
Arguments
  • None
Success Return Value
A JSON object representing the list of rules.
load_default_falco_rules_files(save_dir)[source]
Description
Given a file and directory layout as described in save_default_falco_rules_files(), load those files and return a dict representing the contents. This dict is suitable for passing to set_default_falco_rules_files().
Arguments
  • save_dir: a directory path from which to load the files.
Success Return Value
  • A dict matching the format described in get_default_falco_rules_files.
Example
examples/set_default_falco_rules_files.py
policy_v2[source]

Description True if policy V2 API is available

poll_sysdig_capture(capture)[source]
Description
Fetch the updated state of a sysdig capture. Can be used to poll the status of a capture that has been previously created and started with create_sysdig_capture().
Arguments
  • capture: the capture object as returned by get_sysdig_captures() or create_sysdig_capture().
Success Return Value
A dictionary showing the updated details of the capture. Use the status field to check the progress of a capture.
Example
examples/create_sysdig_capture.py
post_event(name, description=None, severity=None, event_filter=None, tags=None)[source]
Description
Send an event to Sysdig Monitor. The events you post are available in the Events tab in the Sysdig Monitor UI and can be overlied to charts.
Arguments
  • name: the name of the new event.
  • description: a longer description offering detailed information about the event.
  • severity: syslog style from 0 (high) to 7 (low).
  • event_filter: 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'.
  • tags: a list of key-value dictionaries that can be used to tag the event. Can be used for filtering/segmenting purposes in Sysdig Monitor.
Success Return Value
A dictionary describing the new event.
Examples
remove_memberships(team, users)[source]
Description
Remove user memberships from specified team.
Arguments
  • team: the name of the team from which user memberships are removed
  • users: list of usernames which should be removed from team
Example
examples/user_team_mgmt_extended.py
save_default_falco_rules_files(fsobj, save_dir)[source]
Description
Given a dict returned from get_default_falco_rules_files, save those files to a set of files below save_dir.
The first level below save_dir is a directory with the tag name and an optional default_policies.yaml file, which groups rules into recommended default policies. The second level is a directory per file. The third level is a directory per variant. Finally the files are at the lowest level, in a file called “content”.
For example, using the example dict in get_default_falco_rules_files(), the directory layout would look like:
save_dir/

default_policies.yaml v1.5.9/

falco_rules.yaml/
29/
content: a file containing “- required_engine_version: 29
  • list: foo
1/
content: a file containing “- required_engine_version: 1
  • list: foo
k8s_audit_rules.yaml/
0/
content: a file containing “# some comment”
Arguments
  • fsobj: a python dict matching the structure returned by get_default_falco_rules_files()
  • save_dir: a directory path under which to save the files. If the path already exists, it will be removed first.
Success Return Value
  • None
Example
examples/get_default_falco_rules_files.py
save_memberships(team, memberships)[source]
Description
Create new user team memberships or update existing ones.
Arguments
  • team: the name of the team for which we are creating new memberships
  • memberships: dictionary of (user-name, team-role) pairs that should describe new memberships
Example
examples/user_team_mgmt_extended.py
set_agents_config(config)[source]
set_default_falco_rules_files(rules_files)[source]
Description
Update the set of falco rules files to the provided set of files. See the Falco wiki for documentation on the falco rules format.
The _files programs and endpoints are a replacement for the system_file endpoints and allow for publishing multiple files instead of a single file as well as publishing multiple variants of a given file that are compatible with different agent versions.
Arguments
  • rules_files: a dict with the same structure as returned by get_default_falco_rules_files.
Success Return Value
The contents of the default falco rules files that were just updated.
Example
examples/set_default_falco_rules_files.py
set_system_falco_rules(rules_content)[source]
Description
Set the system falco rules file in use for this customer. NOTE: This API endpoint can only be used in on-premise deployments. Generally the system falco rules file is only modified in conjunction with Sysdig support. See the Falco wiki for documentation on the falco rules format.
Arguments
  • A string containing the system falco rules.
Success Return Value
The contents of the system falco rules file that were just updated.
Example
examples/set_secure_system_falco_rules.py
set_user_falco_rules(rules_content)[source]
Description
Set the user falco rules file in use for this customer. See the Falco wiki for documentation on the falco rules format.
Arguments
  • A string containing the user falco rules.
Success Return Value
The contents of the user falco rules file that were just updated.
Example
examples/set_secure_user_falco_rules.py
update_compliance_task(id, name=None, module_name=None, schedule=None, scope=None, enabled=None)[source]
Description
Update an existing compliance task.
Arguments
  • id: the id of the compliance task to be updated.
  • name: The name of the task e.g. ‘Check Docker Compliance’.
  • module_name: The name of the module that implements this task. Separate from task name in case you want to use the same module to run separate tasks with different scopes or schedules. [ ‘docker-bench-security’, ‘kube-bench’ ]
  • schedule: The frequency at which this task should run. Expressed as an ISO 8601 Duration
  • scope: The agent will only run the task on hosts matching this scope or on hosts where containers match this scope.
  • enabled: Whether this task should actually run as defined by its schedule.
Success Return Value
A JSON representation of the compliance task.
update_falco_list(id, items)[source]
Description
Update info associated with a list
Arguments
  • id: The rule id
  • items: the array of items as represented in the yaml List.
Success Return Value
A JSON object representing the list.
update_falco_macro(id, condition)[source]
Description
Update info associated with a macro
Arguments
  • id: The rule id
  • condition: the full condition text exactly as represented in the yaml file.
Success Return Value
A JSON object representing the macro.
update_notification_channel(channel)[source]
update_policy(id, name=None, description=None, rule_names=None, actions=None, scope=None, severity=None, enabled=None, notification_channels=None)[source]
Description
Update policy with the provided values.
Arguments
  • id: the id of the policy to update
  • name: A short name for the policy
  • description: Description of policy
  • rule_names: Array of rule names. (They must be names instead of ids, as the rules list view is by name, to account for multiple rules having the same name).
  • actions: It can be a stop, pause and/or capture action
  • scope: Where the policy is being applied- Container, Host etc.. (example: “container.image.repository = sysdig/agent”)
  • enabled: True if the policy should be considered
  • severity: How severe is this policy when violated. Range from 0 to 7 included.
  • notification_channels: ids of the notification channels to subscribe to the policy
Success Return Value
The string “OK”
update_policy_json(policy_json)[source]
Description
Update an existing policy using the provided json. The ‘id’ field from the policy is used to determine which policy to update.
Arguments
  • policy_json: a description of the new policy
Success Return Value
The string “OK”
Example
examples/update_policy.py
update_rule(id, details={}, description='', tags=[])[source]
Description
Update info associated with a rule
Arguments
  • id: The rule id
  • details: The rule description as a python dictionary.
  • description: A description of this rule. No newlines/formatting.
  • tags: The set of tags.
Success Return Value
A JSON object representing the rule.