• 1:
• 1.1:
• 2:
• 2.1:
• 2.2:
• 2.3:
• 3:
• 3.1:
• 3.1.1:
• 3.1.2:
• 3.1.3:
• 3.1.4:
• 3.1.5:
• 3.1.6:
• 3.1.7:
• 3.1.8:
• 3.1.9:
• 3.1.10:
• 3.1.11:
• 3.2:
• 4:
• 4.1:
• 4.2:
• 5:
• 6:
• 7:
• 8:
• 8.1:
• 8.2:
• 9:
• 9.1:
• 9.2:
• 9.2.1:
• 9.2.2:
• 9.2.3:
• 9.2.4:
• 9.3:
• 9.3.1:
• 9.3.2:
• 9.3.3:
• 9.3.4:
• 9.4:
• 9.5:
• 10:
• 11:
• 12:

1 -

User Profile and Password

Access the User Profile page to review and perform necessary actions:

Access the User Profile Page

1. Log in to Sysdig Monitor or Sysdig Secure and select Settings from the user menu.

2. Select User Profile.

   

3. Review settings and perform actions below.

Review User Email, Role, and Current Team

The current user’s login email address, current team, and role on that team are listed in the User Profile section.

Change Admin Settings

This option is visible to admins only.

If logged on as Administrator, you can access Admin Settings on this page which apply globally.

Hide Agent Install: Toggle this slider to hide the Agent Installation link in the Settings menu from non-admin users.

See Navigate the Settings Panel: Admin vs User and Agent Installation: Overview and Key for more information.

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 from the user menu.

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.

Change Your Password

Use the Password Management fields to change this user’s password.

Required: Minimum 8 characters, not the last password used.

Recommended: We advise following NIST’s most up-to-date recommendations, with an emphasis on length and uniqueness.

Enable Beta Functions from Sysdig Labs

Toggle the feature settings listed under Sysdig Labs to enable/disable specific beta functionalities to your installation. Data that has already been stored will not be affected by beta toggles.

(If there are no beta features, Sysdig Labs will not be displayed.)

1.1 -

Retrieve the Sysdig API Token

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

1. Log in to Sysdig Monitor or Sysdig Secure and select Settings from the user menu.

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.

2 -

User and Team Administration

This page describes the concepts behind Sysdig’s users, teams, and role permissions.

Understanding Sysdig Users

Users in Sysdig are identified by user name, email address, and password or third-party authentication option.

Users are either:

• Invited manually by an Administrator via the Sysdig UI

• Authenticated through a third-party system

• Entered directly in the Sysdig database through the Admin API, which can bypass the invitation process if needed.

When invited, the new user is created in the Sysdig database upon the user’s first successful login to the Sysdig UI. Before the user accepts the invitation, enters a password, and logs in, they have a “pending” status.

System-Based Privileges

From the outset, users in the Sysdig environment have one of three types of system privileges

• (Super) Admin: This is the administrator whose email address is associated with the Sysdig billing account. This user has administrator access to everything. Most relevant in on-prem installations.

• Administrator: Any administrator can grant Admin system privileges to any user. Administrators are automatically members of all teams.

  Administrators can create/delete users; create/configure/delete teams; create/delete notification channels; manage licenses; and configure Agents from links in the Settings menu that are hidden from non-admins.

• User (non-admin): By default, new users have read/write privileges to create, delete, and edit content in the Sysdig interface. They do not see options in the Settings menu that are restricted to Administrators.

  User rights are further refined based on team and team role assignments, as described below.

When a user is created, it is automatically assigned to a default team (described below).

Understanding Sysdig Teams

Teams can be thought of as service-based access control. Teams are created and assigned separately in Sysdig Monitor and Sysdig Secure.

Purpose of Teams

Organizing users into teams enables enforcing data-access security policies while improving users’ workflows. There are different team roles, each of which has read/write access to different aspects of the app.

This limits the exposure of data to those who actually need it, and also makes users more productive by focusing them on data that is relevant to them.

The following are some potential use cases for Teams.

• “Dev” vs “Prod”: Many organizations prefer to limit access to production data. Permits isolating physical infrastructure and the applications on top.

• Microservices: Scoping data for individual dev teams to see their own dashboards and field their own alerts. Permits team creation based on logical isolation using orchestration or config management metadata in Sysdig Monitor.

• Platform as a Service: Where Ops teams need to see the entire platform. Enabling certain people to see all data for all services as well as the underlying hardware. This is perfect for managed service providers who are managing a multi-tenant environment, or devops teams using a similar model within their own organization.

• Restricted environments: Limiting data access for security and compliance. Certain services, such as authentication and billing, may have a very specific set of individuals authorized to access them.

• Organizations that need to segment monitoring for efficiency: Wide-ranging use case from very large organizations forming teams to simplify access, to smaller orgs creating ephemeral troubleshooting teams, to teams formed to optimize QA and Support access to system data.

Operations Teams and Default Teams

Out of the box, the Sysdig Platform has one immutable team for each product. Depending on licensing, an organization may use one or both:

• Monitor Operations team

• Secure Operations team

Key traits of the immutable Operations teams:

• The teams cannot be deleted

• Users in Operations teams have full visibility to all resources in that product

• Administrators must switch to the Operations team before changing configuration settings for any team

Administrators create additional teams and can designate any team to become the default team for that product. The number of teams allowed in an environment is determined by licensing.

Users entered in the Sysdig Monitor UI are auto-assigned to the Monitor default team; users entered in the Sysdig Secure UI are auto-assigned to the Secure default team.

Team-Based Roles and Privileges

Users can be assigned roles that expand or limit their basic system privileges on a per-team basis.

How Team Membership Affects Users’ Experience of the UI

Team membership affects user experience of the Sysdig Monitor or Sysdig Secure UIs in various ways.

At the highest level, the dashboards, alerts, and policy events you see are limited by the settings of the team you are switched to.

In more detail, team settings affect the following:

• Default landing page: The UI entry point is set on a per-team basis.

• Explore tab and dashboards: These are set per-team, per-user and can be shared with the team.

  On first login, all team members see the same Dashboards Assigned to Me view. If a user changes those dashboards, only that user will see the changes.

  Dashboards created while part of a team are only visible to the user when logged in to that team, and if shared, are only visible to other team members.

• Visible data: A team’s scope settings limit the data visible to team members while they are switched to that team, even if a user belongs to other teams with different settings that reveal additional data. In Sysdig Secure, for example, only the policy events that fired within your scope will be visible.

• Alert and Event: These settings are team-wide. Any member of a team can change the team’s alert settings, and any additions or edits are visible to all members of the team.

• Captures: Can only be taken on hosts/containers visible to team members, and members see only the list of captures initiated by other members who were switched to the current team.

• API Token: Note that the Sysdig Monitor API Token found under Settings > User Profile is unique per-user, per-team. (See User Profile and Password. This is necessary to enable the generation of Custom Events via the API to target a specific team.

Switching Teams in the UI

Users can switch between all teams to which they’ve been assigned, and Administrators can switch between all teams that have been created.

To do so:

1. Click the user menu in the lower-left corner of the navigation bar.

   The assigned teams for this user are listed under Switch Teams.

   

2. NOTE: With version 3.6.0, you can also search for the teams in the user menu.

3. Click another team name.

   A popup window gives an overview of the new team-based view of the environment. The UI changes according to the team settings.

Onboarding Best Practices

Plan teams and roles strategically to isolate access to data, customize interfaces, and streamline workflows.

In general, administrators should:

• Create teams, invite users, and set roles in a planned manner

• Start with some dashboards and alerts for given teams to get started with

When a user logs in to a team for first time, they will see a wizard introducing dashboards, alerts, etc. specific to that team.

Restricting New User Rights by Default

By default, new users (added manually or through a third-party authenticator) are assigned Advanced User rights. If a administrator wants to limit new users’ rights further, there are several ways to do so.

• Between sending the invitation and the user’s first log in, change the user’s Role in the default Monitor team to Read User.

  Note that there could theoretically be a lag in which the user would briefly have had Edit status.

• Integrate users into Sysdig via the Admin API and define read-only permissions upon import.

• Create a default team, in either Sysdig Monitor or Sysdig Secure, with very limited scope and visibility. Manually assign users to additional teams with broader permissions as needed.

Custom Roles

If Team-Based Roles and Privileges don’t meet the specific needs of your organization, you can create your own custom roles. See .

Integrating Users and Teams via API

If you are working with Sysdig Support Engineers to provision users and teams via the Sysdig API, note how the user and team role names within the UI map to the API ROLE names.

User roles

Regular (non-admin) = ROLE_USER

Admin = ROLE_CUSTOMER

Team roles

Advanced user = ROLE_TEAM_EDIT

Standard user = ROLE_TEAM_STANDARD

View-only user = ROLE_TEAM_READ

Team manager = ROLE_TEAM_MANAGER

Service manager (Sysdig Secure only) = ROLE_TEAM_SERVICE_MANAGER

2.1 -

Manage Users

This page describes how to add, delete, and configure user information from within the Sysdig Monitor or Sysdig Secure UI.

Create a User

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and select Settings from the user menu.

2. Select Users.

3. Click the Add User link.

4. Enter the user’s email address, first name and last name:

   

5. Click Save to send the user invite, or click Cancel to discard the user.

   For on-premises environments, you may need to have pre-configured your SMTP parameters in your Replicated or Kubernetes installation configmap.

The new user will be added to the User Management table. Their status will be listed as Pending until the invitation is accepted.

Edit User Information

To edit an existing user:

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and select Settings from the user menu.

2. Select Users.

3. Select the user from the User Management table.

4. Optional: Edit the first name / last name.

5. Optional: Toggle the Admin switch to enable/disable administrator privileges.

6. Click Save to save the changes, or Cancel to revert the unsaved changes.

   User emails are read-only, and cannot be changed.

Delete a User

To delete an existing user:

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and select Settings from the user menu. `

2. Select Users.

3. Select the user from the User Management table.

4. Click Delete User.

5. Click Yes, delete to confirm the change.

   You can optionally delete the dashboards and artifacts that the user have created.

2.2 -

Manage Custom Roles

A custom role is a admin-defined role which allows Sysdig administrators to bundle a set of permissions and allocate it to one or more users or teams. This page describes how to create and use custom roles.

Custom Roles is supported only on SaaS regions. The feature is not currently available for on-prem environments.

Understand Custom Roles

Custom roles gives you the ability to provide granular access to users according to a selected list of permissions. If the Sysdig Roles don’t meet the specific needs of your organization, you can create your own custom roles. Select the permissions you want them to have based on the resource they should have the access to and bundle it together. Just like built-in Sysdig roles, you can assign custom roles to users and teams. Custom roles ensures that the users have only the permission they need and help prevent unwanted access to other resources.

Custom roles operate on concepts similar to roles-based access control system (RBAC).

Benefits of Using Custom Roles

• Allow you to give access to a specific set of predefined dashboards to a group of users, who should not be able to view any additional data, nor change or share these dashboards.

• Allow you to create a service account for Sysdig Secure that is not tied to a particular user but can be used to automate your CI/CD pipeline.

  • Give custom set of permissions to the CI/CD account
  • Give permission to create these accounts to a certain set of users

• Allow you to identify the owner of a particular image so the security issue can be assigned to the actual team who owns the issue.

• Create a team role that can only invite users but not actually manage the team.

Create a Custom Role

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

2. Select Roles.

3. Click New Role. The New Role page is displayed.

4. Specify the following:

   • Role Name: A unique name to identify the role you create.
   • Role Description: A short explanation of the role that you have created.
   • Product: A filter that gives a fine-grained view of the product-specific features.

5. Select the features and do one of the following:

   • From the drop-down, select one of the following: No Access, Read Only, Full Access, Custom.
   • Click Customize to provide grant granular permissions to a sub-set of features. This is an alternative to clicking Custom from the drop-down.

6. Click Save New Role.

Assign a Custom Role to Teams

You can set up a custom role as the default user role for teams. To do so:

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

2. Select Teams.

3. Do one of the following:

   • Select the relevant team from the list of teams.
   • Click Add Team.

4. From the Default User Role drop-down, select one of the custom role you have created.

   

5. Complete creating or editing the team as given in Manage Teams and Role.

6. Click Save.

Custom Roles and Privileges

Click Customize to view and select granular permissions for each product features. Alternatively, use the drop-down to grant read access or full access to all the privileges simultaneously.

Sysdig Monitor

Sysdig Secure

2.3 -

Manage Teams and Roles

The use of teams provides a strategic way to organize groups, streamline workflows, or protect data, as needed by an organization. Administrators who design and implement teams should have in-depth knowledge of organizational infrastructure and goals.

For more information, including foundational concepts, see User and Team Administration.

Create a Team

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and

   select Settings from the user menu.

2. Select Teams.

3. Click Add Team.

4. Configure the team options and click Save.

For more information on each configuration option, refer to Team Settings.

Team Settings

Configure an Entry Page or Dashboard for a Team

Some Sysdig Monitor teams benefit from using a default entry point other than the usual Explore page, as users who don’t need in-depth monitoring information can onboard and navigate Sysdig Monitor more efficiently.

Use the Default Entry Point setting on the Team page, as shown in Create a Team.

Note: If selecting a dashboard, open the secondary Dashboard drop-down menu, or type the name of the dashboard to select it.

The dropdown is only populated with shared dashboards accessible by anyone on the team.

Add and Configure Team Members

Users can be assigned to multiple teams. Team assignment is made from the Team page (not the User page), and must be done by an Administrator or Team Manager.

Assign a User to a Team

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and

   select Settings from the user menu.

2. Select Teams.

3. Select the relevant team from the list, or search for it with the search box, and then select the relevant team.

4. In the Team Users section, click the Assign User button.

5. Select the user from the drop-down list, or search for it and then select it.

6. Click the Role drop-down menu to select the user role:

   

7. Optional: Repeat steps 3 to 5 for each additional user.

8. Click Save.

Assign a Team-Based Role to Users

Review Team-Based Roles and Privileges for an overview.

Note that the Advanced User permission can be further refined into either a View-only user or a Team Manager.

Managers can add or delete members from a team, or toggle members' rights between Edit, Read, or Manager.

Note that Admins have universal rights and are not designated as Team Managers, Advanced Users, View-Only users, or Standard users.

Manager or Advanced User permissions can be assigned even to Pending users; administrators do not have to wait for the user’s first login to set these roles.

To assign a role to a user on a team:

1. Log in to Sysdig Monitor or Sysdig Secure as Administrator and either create a team or select a team to edit.

2. Add a user or select a user from the list of team members.

3. Select the appropriate role from the drop-down menu.

   

   Reminder of the role privileges:

   Admin: Member of every team with full permissions. Can create/delete/configure all users and teams.

   Team Manager: Advanced User privileges + ability to add/delete team members or change team member permissions.

   Advanced User:

   In Sysdig Monitor: Read/write access to the components of the application available to the team. Can create/edit/delete dashboards, alerts, or other content.

   In Sysdig Secure: Read/write access to the components of the application available to the team. Can create, delete, or update runtime policies, image scanning policies or any other content.

   View-Only:

   In Sysdig Monitor: Read access to the environment within team scope, but cannot create, edit, or delete dashboards, alerts, or other content.

   In Sysdig Secure: Read access to every Secure feature in the team scope, but cannot modify runtime policies, image scanning policies or any other content.

   Standard User:

   In Sysdig Monitor: An Advanced User with no access to the Explore page (e.g. for developers who are not interested in Monitoring information).

   In Sysdig Secure: Can send container images to the scanning queue, view image scanning results, and display the runtime security events within the team scope. Standard Users cannot access Benchmarks, Activity Audit, Policy definitions, or certain write functions within other Secure features.

   Service Manager: Sysdig Secure only. Same as Standard User, plus ability to invite existing users to the team and manage the notifications channels assigned to the team.

4. Save edits.

Edit Team Configuration

To configure an existing team:

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and

   select Settings from the user menu.

2. Select Teams.

3. Select the relevant team from the list, or search for it with the search box, and then select the relevant team.

4. Edit as needed, and click Save.

For more information regarding the configuration options, see Table 1: Team Settings.

Delete a Team

When a team is deleted, some users may become “orphans”, as they are no longer a part of any team. These users will be moved to the default team.

The default team cannot be deleted. A new default team must be selected before the old default team can be deleted.

To delete a created team:

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and

   select Settings from the user menu.

2. Select Teams.

3. Select the relevant team from the list, or search for it with the search box, and then select the relevant team.

4. Click Delete Team, then Yes, delete to confirm the change.

3 -

Notifications Management

Alerts are used in Sysdig Monitor when Event thresholds have been crossed, and in Sysdig Secure when Policy violations have occurred. Alerts can be sent over a variety of supported notification channels.

Notification Management describes how to add, edit, or delete a variety of notification channel types, and how to disable or delete notifications when they are not needed, for example, during scheduled downtime.

3.1 -

Set Up Notification Channels

Alerts are used in Sysdig Monitor when Event thresholds have been crossed, and in Sysdig Secure when Policy violations have occurred. Alerts can be sent over a variety of supported notification channels.

In the Settings panel of either Sysdig Monitor or Sysdig Secure, set up the notification channels to be used for alerting.

Notification channel management can be finessed by role-based access as follows:

• Notification channels can now be “global” or limited to a particular team

• Global channels can be managed by admins and can be viewed/used by other roles, while team-limited channels are available only to team members

• Team Manager , Advanced User, and Service Manager (Secure) roles can create/update/delete team-scoped notification channels, they can also read and use the global ones

• Standard and View Only roles can read team-limited and global notification channels

• Admins will be able to create global notification channels and migrate channels from “global” to “team-limited”, and also from one team to another.

Add a Notification Channel

To add a new notification channel:

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and select Settings from the user menu.

2. Select Notification Channels.

   The Notifications main page is displayed:

3. Click Add Notification Channel +, and select the desired notification channel.

   

4. Follow the channel-specific steps to complete the configuration process:

   • Amazon SNS Notifications

   • Email Notifications

   • Team Email Notifications

   • PagerDuty Notifications

   • Slack Notifications

   • VictorOps Notifications

   • OpsGenie Notifications

   • Configure a Webhook Channel

   • Configure IBM Cloud Functions Channel

Edit a Notification Channel

To edit a notification channel:

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

2. Select Notification Channels.

3. Locate the target channel and click the Edit button.

4. Make the edits and click Done Editing to save the changes.

Test a Notification Channel

To test a notification channel:

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

2. Select Notification Channels.

3. Select the three dots next to a created Notification Channel and click Test Channel.

   

3.1.1 -

Amazon SNS Notifications

Sysdig Monitor integrates easily with AWS Simple Notification Service (SNS).

On the AWS side:

To automatically push Sysdig Monitor alerts to the SNS topic of your choice:

1. From the AWS console, open the SNS management console

2. In the Create topic section, Create a new topic (if needed).

   The topic’s Name, ARN, (optional) Display name, and Topic owner’s AWS account ID are displayed in the Details section.

3. Select the topic on the list.

4. Expand Access policy - optional.

5. Select Basic (By default).

6. Under Define who can publish messages to the topic, select Only the specified AWS accounts and enter the Sysdig Monitor account ID: 273107874544 (US-East Only).

   

   For account IDs corresponding to other regions, see SaaS Regions and IP Ranges.

7. Click Create topic.

8. Ensure that you subscribe to the created topic.

   1. On the navigation panel, choose Subscriptions.

   2. On the Create subscription page, enter the Topic ARN of the topic you created earlier.

   3. Specify other details and click Create subscription.

For further information about AWS SNS, refer to the AWS documentation.

For SNS notification, you can click the ‘help’ button for tips on setting up your SNS topic.

You will need to allow publishing rights to the Sysdig Monitor account ID corresponding to your region.

This can be done by creating a new policy on your SNS topic in AWS Console as shown in the below images:

1. Select “Edit topic policy” as shown below from “Other topic actions.”

   

2. In the “Basic view” tab of the “Edit topic policy” dialog, select “Only these AWS users” from the publisher’s list and enter the Sysdig ID.

   

In the Sysdig Monitor UI:

1. Complete steps 1-3 in Set Up a Notification Channel to log in to the Sysdig UI and select Amazon SNS Topic.

   

2. Enter the Topic created on the AWS side, along with a Channel Name, Enablement, and Notification toggles as appropriate.

3. From Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

4. Click Save.

3.1.2 -

Email Notifications

To send an alert notification via email, you must first set up the email notification channel.

To do so, complete steps 1-3 in Set Up a Notification Channel, then:

1. Select Email.

2. Enter the relevant details for the email notification:

   

3. From Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

4. Click Save.

   If you enabled Test notification, a test email will be sent.

You can now configure an alert to use email notifications.

3.1.3 -

Team Email Notifications

You can notify all the users of a team when an alert is triggered. Sysdig allows you to create a new notification channel where you can select a team from a list of existing ones as the target of the channel.

To send an alert notification via email to a team, you must first set up the team email notification channel. To do so, complete steps 1-3 in Set Up a Notification Channel, then:

1. Select Team Email.

2. Enter the relevant details for the email notification:

   

   Select the Team Name and specify a Channel Name to identify the channel you are creating.

3. From Shared With drop-down, choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

4. Click Save.

   If you enabled Test notification, a test email will be sent.

You can now configure an alert to use email notifications.

3.1.4 -

PagerDuty Notifications

To send an alert notification via PagerDuty, you must first set up the PagerDuty notification channel.

Prerequisites

• Have an account configured at PagerDuty.com.

• Have your PagerDuty credentials available (account, password, and service).

• Have the base user role of Manager. With a PagerDuty base user role of Manager, you can auto-fetch the service information during the Sysdig/PagerDuty integration process.

• Check your team and base user permissions. If your PagerDuty team permissions are Manager but base user permissions are Responder or lower, you can enter the necessary data in the Sysdig UI manually.

  

  Base user roles in the PagerDuty UI.

Configure PagerDuty

1. To launch the process from the Sysdig UI, complete steps 1-3 in Set Up Notification Channels and select PagerDuty.

2. Do one of the following:

   • Select Auto-fetch when prompted. Ensure that you have the base user role of Manager or higher in PagerDuty.

   • Select Manual and enter the necessary configuration parameter. Skip to Step 5 for details.

   Once you complete the pre-configuration, the PagerDuty Integration screen is displayed.

   

3. Do one of the following:

   • Enter the email and password associated with your PagerDuty account, and click Sign In.

   • Enter the appropriate PagerDuty subdomain for single sign-on and click Sign In Using Your Identity Provider.

4. A PagerDuty service selection screen is displayed.

   • Option 1: If you have never integrated before, you are prompted to choose a PagerDuty Servicename.

   • Option 2: If at least one service has already been integrated, you can select that one.

   

5. Click Connect.

   Once integration is authorized, the Sysdig page for a new PagerDuty notification channel is displayed, with the information auto-filled.

   

6. From Shared With, choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

7. Do one of the following:

   • Confirm the auto-populated information and click Save.

   • If you chose Manual entry in Step 2, then type the information and click Save.

You can now Add an Alert to use PagerDuty notifications.

Known Issues

There is a known issue whereby changing a notification from “Acknowledged” to “Unacknowledged” does not update correctly in PagerDuty.

What occurs:

• Event has triggered Notification, Notification is sent to PagerDuty.

• Open Event and click on “Acknowledge” button in Sysdig.

• Notification is sent to PagerDuty, and status is changed to “Acknowledged.”

• Open Event and click on “UnAcknowledge” button in Sysdig.

  

  Status is not changed in PagerDuty. It remains “Acknowledged” rather than changing to “Triggered” in PagerDuty.

Unknown issues & support

Sysdig support section.

3.1.5 -

Slack Notifications

To send an alert notification via Slack you must first set up the Slack notification channel.

To do so:

Prerequisite:

Have a Slack account configured at Slack.com and know which notification channel to use for notifications.

1. To launch the process from the Sysdig UI, complete steps 1-3 in Set Up Notification Channels and select Slack.

   You will be prompted to log in to your Slack account.

2. Select a Slack channel from the drop-down list to be used for notifications and click Authorize.

3. From Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

4. Complete configuration as desired and click Done.

   

5. Click Test to check the new functionality.

You can now configure an alert to use Slack notifications.

3.1.6 -

VictorOps Notifications

To integrate with your VictorOps

1. Log in to VictorOps.

2. Go to Settings > Alert Behavior > Integrations in the VictorOps interface.

3. Select REST from the list of Featured Integrations.

   

4. Complete steps 1-3 in Set Up a Notification Channel to log in to the Sysdig UI and select VictorOps.

   

5. Enter the VictorOps parameters in the Sysdig Notification Channel fields, as follows:

   API Key: everything between "/alert/" and “/$routing_key” in the REST URL

   Routing Key: A VictoOps way of routing alerts to appropriate teams. See their Routing Keys documentation for details, if needed.

   Channel Name: Choose a meaningful name like “VictorOps”.

   Enable the channel and desired notification types.

6. From Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

7. Click Save.

3.1.7 -

OpsGenie Notifications

1. Go directly to the OpsGenie Integrations Page to configure the integration on the OpsGenie side.

   OpsGenie maintains documentation on how to integrate with Sysdig products (formerly called Sysdig Cloud) here.

2. Complete steps 1-3 in Set Up a Notification Channel to log in to the Sysdig UI and select OpsGenie.

   

3. Copy/paste your OpsGenie integration API key and add a Channel Name, Enablement, and Notification toggles as appropriate.

4. From Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

5. Click Save.

3.1.8 -

Configure a Microsoft Teams Channel

Sysdig Monitor supports sending an alert notification to Microsoft teams. Microsoft Teams has different types of integrations for third-party applications, of which Sysdig supports Incoming Webhooks.

About Incoming Webhooks

Incoming Webhooks are a type of Connector in Teams that provide a simple way for an external app to share content in team channels. They are often used as tracking and notification tools. Microsoft Teams provides a unique URL to which you can send a JSON payload with the message that you want to POST, typically in a card format. Cards are UI containers that contain content and actions related to a single topic and are a way to present message data in a consistent way.

You will need to enter the URL that you copied from the Connector. Sysdig will format a message by using a custom card template and send it to the channel. The message will show up as a new notification in the Microsoft application.

Prerequisites

• Have the destination URL handy. You can copy it from the Connectors > Incoming Webhook window on the Microsoft Teams UI. For more information, see Add an incoming webhook to a Teams channel.

  

• Webhooks via HTTPS work only if a signed or valid certificate is in use.

Enable Microsoft Teams

1. Complete steps 1-3 in Set Up a Notification Channel and choose Microsoft Teams.

   

2. Enter the configuration options:

   • URL: The destination URL you have copied from Microsoft Teams UI.

   • Channel Name: Add a meaningful name for your Microsoft Teams channel.

   • Enabled: Toggle on or off.

   • Notification options: Toggle for notifications when alerts are resolved or acknowledged.

   • Test notification: Toggle to be notified that the configured URL is working.

   • Shared With: Choose whether to apply this channel globally. All Teams or to a specific team from the drop-down.

3. Click Save.

3.1.9 -

Configure a Webhook Channel

Sysdig Monitor and Sysdig Secure support sending an alert notification to a destination, such as a website, custom application, and so on for which Sysdig does not have a native integration. Do this using a custom Webhook channel.

Prerequisites

• Webhooks via HTTPS only work if a signed/valid certificate is in use.

• Have your desired destination URL on hand.

Enable Webhook

1. Complete steps 1-3 in Set Up a Notification Channel and choose Webhook.

   

2. Enter the webhook channel configuration options:

   • URL: The destination URL to which notifications will be sent.

   • Channel Name: Add a meaningful name, such as Ansible, PagerDuty, OpsGenie, and so on.

   • Enabled: Toggle on and off notifications.

   • Notification options: Toggle for notifications when alerts are resolved or acknowledged.

   • Test notification: Toggle to be notified that the configured URL is working.

   • Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

   • Allow insecure connections: Enable if you want to skip the TLS verification.

   • Custom headers: Add custom headers to your alert notification.

     If your webhook integrations require additional headers you specify them by using a custom header.

     For example, Ansible uses token-based authentication, which requires an entry for the bearer token. This entry is not included in the default header, but you can add it using a custom header.

     Alternatively, you can choose to add custom headers programmatically as described in Configure Custom Headers and Custom Data Programmatically.

   • Custom Data: Specify the custom data you want to attach to the alert notification. The data must be a valid JSON document. This information will be included in the request body of the HTTP call. Systems that receive these webhook alerts can parse the data and take action based on the contents.

3. Click Save.

When the channel is created, you can use it on any alerts you create.

Then, when the alert fires, the notification will be sent as a POST in JSON format to your webhook endpoint. (See Alert Output, below.)

For testing purposes, you can use a third-party site to create a temporary endpoint to see exactly what a Sysdig alert will send in any specific notification.

Configure Custom Headers and Custom Data Programmatically

By default, alert notifications follow a standard format (see Description of POST Data, below).

However, some integrations require additional headers and/or data, which you can append to the alert format using a custom header or custom data entry.

For example, Ansible uses token-based authentication, which requires an entry for the bearer token. This entry is not included in the default alert template built into Sysdig, but you can add it using a custom header.

In addition to the Webhook UI option, you can do this from the command line, as described below.

Sample Use Case

This example adds two custom headers and defines additional custom data, as well as the format for that data.

1. Use the curl command to retrieve all configured notification channels:

   curl -X GET https://app.sysdigcloud.com/api/notificationChannels -H 'Authorization: Bearer API-KEY'
   

2. Add the custom headers and execute the request:

   curl -X PUT https://app.sysdigcloud.com/api/notificationChannels/1 -H 'Authorization: Bearer API-KEY' -H 'Content-Type: application/json' -d '{
     "notificationChannel": {
       "id": 1,
       "version": 1,
       "type": "WEBHOOK",
       "enabled": true,
       "name": "Test-Sysdig",
       "options": {
         "notifyOnOk": true,
         "url": "https://hookb.in/v95r78No",
         "notifyOnResolve": true,
         "customData": {
           "String-key": "String-value",
           "Double-key": 2.3,
           "Int-key": 23,
           "Null-key": null,
           "Boolean-key": true
         },
         "additionalHeaders": {
           "Header-1": "Header-Value-1",
           "Header-2": "Header-Value-2"
         }
       }
     }
   }'
   

Standard Alert Output

Alerts that use a custom webhook for notification send a JSON-format with the following data.

Description of POST Data

{
  "timestamp": 1620222000000000, // Time when the alert triggered in microseconds
  "timespan": 60000000, // duration of the alert in microseconds (how long the value should be true before triggering)
  "alert": {
    "severity": 2, // severity from 0 to 7, use severityLabel for a human readable version
    "editUrl": "https://app-staging.sysdigcloud.com/#/alerts/21998727", // alert edit URL
    "severityLabel": "Medium", // human readable version of severity
    "subject": "CPU temp is High on homebridge:9100 is Triggered", // Alert subject
    "scope": null, // scope of the alert if set from the UI
    "name": "CPU temp is High", // name of the alert
    "description": null, // description, not used ATM
    "id": 21998727, // alert id
    "body": "CPU temp is High on homebridge:9100 is Triggered\n\n\nEvent Generated:\n\nSeverity:         Medium\n    Metric:\n    node_hwmon_temp_celsius = 65.8121\nSegment:\n    instance = 'homebridge:9100'\nScope:\n    Everywhere\n\nTime:             05/05/2021 01:40 PM UTC\nState:            Triggered\nNotification URL: https://app-staging.sysdigcloud.com/#/events/notifications/l:2419200/14918845/details\n\n------\n\nTriggered by Alert:\n\nName:         CPU temp is High\nTeam:         Monitor Operations\nScope:\n    Everywhere\nSegment by:   instance\nWhen:         avg(avg(node_hwmon_temp_celsius)) > 40\nFor at least: 1 m\nAlert URL:    https://app-staging.sysdigcloud.com/#/alerts/21998727\n\n\n"
  },
  "event": {
    "id": 14918845, // id of the generated event
    "url": "https://app-staging.sysdigcloud.com/#/events/notifications/l:604800/14918845/details" // url of the event in the feed
  },
  "state": "ACTIVE", // status of the alert, can be ACTIVE or OK
  "resolved": true,
  "entities": [ // list of entities that triggered the alert, at the moment we send a notification per entity, so this array will always contain a single object
    {
      "entity": "instance = 'homebridge:9100'", // segment that triggered
      "metricValues": [ // value of the metric at the time of triggering
        {
          "metric": "node_hwmon_temp_celsius",
          "aggregation": "avg",
          "groupAggregation": "avg",
          "value": 65.812167
        }
      ]
    }
  ],
  "endEntities": [ // list of entities when the alert was resolved (same as "entities")
    {
      "entity": "instance = 'homebridge:9100'",
      "metricValues": [
        {
          "metric": "node_hwmon_temp_celsius",
          "aggregation": "avg",
          "groupAggregation": "avg",
          "value": 39.812167
        }
      ]
    }
  ],
  "condition": "avg(avg(node_hwmon_temp_celsius)) > 40", // alert condition in string form
  "source": "Sysdig Cloud", // source of the event
  "labels": { // list of labels associated to this event (they strongly depend on the segmentation and scope of the alert)
    "instance": "homebridge:9100"
  }
}

Example of Failure

$ curl -X GET https://app.sysdigcloud.com/api/notificationChannels -H 'authorization: Bearer dc1a42cc-2a5a-4661-b4d9-4ba835fxxxxx'

{"timestamp":1543419336542,"status":401,"error":"Unauthorized","message":"Bad credentials","path":"/api/notificationChannels"}

Example of Success

$ curl -X GET https://app.sysdigcloud.com/api/notificationChannels -H 'Authorization: Bearer dc1a42cc-2a5a-4661-b4d9-4ba835fxxxxx'
{"notificationChannels":[{"id":18968,"version":2,"createdOn":1543418691000,"modifiedOn":1543419020000,"type":"WEBHOOK","enabled":true,"sendTestNotification":false,"name":"robin-webhook-test","options":{"notifyOnOk":true,"url":"https://postb.in/6dtwzz7l","notifyOnResolve":true}}]}
$

The webhook feature is used to integrate the following channels:

• Configure ServiceNow

3.1.10 -

Configure ServiceNow

Sysdig can be integrated with ServiceNow using a custom webhook.

ServiceNowSetup

Prerequisites

• Have a ServiceNow account set up and working.

• If necessary, refer to ServiceNow developer documentation here.

Create Scripted Rest API Details in ServiceNow GUI

1. Login to ServiceNow (developer entry) and create a Scripted REST API:

   

2. Click New and submit the form with the following:

   Name: SysdigAlert API ID: sysdigalert

3. Return to the Scripted REST APIs and open the resource just created.

   Scroll down to the related list area, select Resources, and click New. This will create a new Scripted REST API resource.

4. Fill in the Name field e.g. Demo.

   

5. Scroll down to Security and clear the checkbox that requires authentication.

   

6. Change the HTTP method from GET to POST.

The resource is created.

Add Code to the New Scripted API

Now give the resource the code to execute.

The default objects to work with in a Scripted REST API Resource are response and request.

For more details on request and response see Scripted_REST_Request_API and Scripted_REST_Response_API

The created resource will already have some example code:

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {

    // implement resource here

})(request, response);

1. Change this default code to:

   (function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
   
    gs.info(request.body.dataString);
   
   })(request, response);
   

2. Note the following resource path to this newly created resource is now visible: /api/snc/sysdigalert.

   The url to this resource would be https://yourInstance.service-now.com/<resource_Path or https://yourInstance.service-now.com/api/snc/sysdigalert ``

   

3. Click Submit/Update on this resource.

Sysdig Webhook Setup

Now that the custom API endpoint in ServiceNow is created, you can configure Sysdig alerts to use a custom webhook to trigger the ServiceNow integration.

API URL: your instance name URL

Name: ServiceNow (or whatever name you’d like for this Sysdig alert webhook)

Notify when OK: Optional

Notify when Resolved: Optional

Test Notification: Use this toggle and/or set up a test alert as described in the following section.

Test Integration

To test if this ServiceNow integration is set up and working correctly, you can set up a test alert to trigger.

For example, you could create an alert for CPU usage:

In ServiceNow, navigate to System Log > All to see a sample triggered webhook.

3.1.11 -

Configure IBM Cloud Functions Channel

Sysdig supports automatically sending alert notifications to an IBM Cloud Functions Channel. You generally use it for the following use cases.

• Configure an IBM Functions as a new notification channel in Sysdig Monitor.

• Pass extra parameters to IBM Functions.

• Modify an IBM Functions.

• Delete an IBM Functions.

The following notification channel types are supported:

• Public (with or without X-Require-Whisk-Auth header)

• Private (using IAM token)

To configure IBM Cloud Functions Channel:

1. Log in to the Sysdig UI and select IBM Cloud Functions Channel by completing steps 1-3 as described in Set Up a Notification Channel.

   

2. Specify the channel URL.

   You can specify one of the following channel types.

   • Public: The public channels are of type IBM Web Action. They require no authentication and can be used to implement HTTP handlers that respond with headers, status code, and body content of different types.

     URL: An example URL is https://eu-gb.functions.cloud.ibm.com/api/v1/namespaces/13eeeeee-623b-4776-ba35-4065bcbfee7b/actions/hello-world/myaction

   • Private: The private channels are of type IAM Secured action. These actions require IAM token-based authentication.

     URL: An example URL is https://eu-gb.functions.cloud.ibm.com/api/v1/web/namespaces/13eeeeee-623b-4776-ba35-4065bcbfee7b/actions/hello-world/helloworld?param=true

3. Continue with one of the following:

   • Configure a Private Channel

   • Configure a Public Channel

Configure a Private Channel

Specify the following:

• IAM API Key:

• Channel Name: A unique name to identify the channel.

• Enable the channel and desired notification types:

  • Enabled: The toggle button to enable or disable the IBM channel.

  • Notify when Resolved: Send a new notification when the alert condition is no longer triggered. Enable or disable the notification toggle as appropriate.

  • Notify when Acknowledged: Send a new notification when the alert is manually acknowledged by a user. Enable or disable the notification toggle as appropriate.

  • Test notification: Send a notification when the changes are saved. Enable or disable the notification toggle as appropriate.

• Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

• Additional Parameters: Specify optional parameters to pass to the function. For example, name: jane is passed to the action as {name: "Jane"}.

Configure a Public Channel

Specify the following:

• Whisk Auth Token (optional): Optionally provide the Whisk authentication token. If you specify one, the public channel (web action) can only be invoked by requests that provide appropriate authentication credentials. See Securing web actions for more details.

• Channel Name: A unique name to identify the channel.

• Enable the channel and desired notification types:

  • Enabled: The toggle button to enable or disable the IBM channel.

  • Notify when Resolved: Send a new notification when the alert condition is no longer triggered. Enable or disable the notification toggle as appropriate.

  • Notify when Acknowledged: Send a new notification when the alert is manually acknowledged by a user. Enable or disable the notification toggle as appropriate.

  • Test notification: Send a notification when the changes are saved. Enable or disable the notification toggle as appropriate.

• Shared With: Choose whether to apply this channel globally (All Teams) or to a specific team from the drop-down.

• Additional Parameters: Specify optional parameters to pass to the function. For example, hostname: BLR is passed to the action as {hostname: "BLR"}. The URL would be /demo/hello.http?hostname=BLR.

3.2 -

Disable or Delete a Notification Channel

Temporarily Disable a Notification Channel

To temporarily disable a notification channel:

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

2. Select Notification Channels.

3. Toggle the Enabled slider to off.

Mute Notifications During Downtime

Administrators can choose to turn off all alert events and notifications if desired, for example, during a scheduled system downtime.

Muting notifications affects all channels globally. When muting is switched on, no notifications will be sent through any configured channel. You can choose whether to notify specific channels that notifications are temporarily disabled. Muting and re-enabling notifications is a MANUAL process.

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

   

2. Select Notification Channels.

3. Select the Downtime toggle.

   Optional: check the Yes box to Notify Channels when prompted, and select the desired channels.

   At this time, only Email and Slack channels can be notified when downtime is started/stopped.

   

Delete a Notification Channel

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

2. Select Notification Channels.

3. Select the three dots next to a created channel and click Delete Channel.

   

Configure an Alert Start-Up Delay (On-Premises Only)

Sysdig alert jobs begin immediately at start-up. However, in instances where Sysdig goes down unexpectedly, or without proper shutdown/startup procedures implemented, data can be missing, triggering alert notifications.

A start-up delay in alert jobs can be configured in on-premises environments, by setting the draios.alerts.startupDelay parameter. The parameter requires a duration value; the example below shows a duration of 10 minutes:

draios.alerts.startupDelay=10m

This parameter can be configured for either Replicated or Kubernetes environments:

• For Replicated environments, add the parameter to the Sysdig application JVM options list. For more information, refer to the Sysdig Install with Replicated documentation.

• For Kubernetes environments, add the parameter to the **sysdigcloud.jvm.worker.options **parameter in the configmap. For more information on editing the configmap refer to the On-Premises Installation documentation.

4 -

AWS: Integrate AWS Account and CloudWatch Metrics (Optional)

When the Sysdig agent is installed in an AWS environment, the Sysdig Platform can collect both general metadata and various types of CloudWatch metrics.

There are three ways to integrate an AWS account into Sysdig:

• By manually entering an AWS access key and secret key, and manually managing/rotating them as needed

• By passing a parameter that allows Sysdig to autodetect an AWS ECS role and its permissions, passing an “implicit key” (On-Prem only).

  The implicit option requires no manual key rotation as AWS handles those permissions behind the scenes.

• Using AWS Role delegation. Role delegation is an alternative to the existing integration methods using the access keys. This method is considered secure as sharing developer access keys with third-parties is not recommended by Amazon.

The Sysdig Monitor UI includes links to help easily integrate CloudWatch metrics into Sysdig Monitor, as described below.

Entry Point in the Sysdig UI

The Sysdig interface prompts you to perform this integration from the administrator’s Settings menu.

Access from the Settings Menu

Once an agent has been installed, log in to Sysdig Monitor or Sysdig Secure as administrator to perform integration steps or review/modify existing AWS settings.

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and select Settings from the user menu.

2. Choose AWS Accounts.

   

   A page showing manual key integration, with access key and secret key fields displayed.

   NOTE: If there is no AWS integration yet then click on ADD and provide the access key and secret key.

Integrate AWS Account Manually

Have your AWS EC2 account details available. Integration begins on the AWS side and is completed in the Sysdig Monitor UI.

In AWS

Create an IAM Policy for Sysdig Access

1. In AWS, select IAM and create a policy to be used for Sysdig. (Sample policy name: SysdigMonitorPolicy.)

2. Using the JSON editor view, copy/paste the Sysdig-specific policy code into the new policy and save it.

3. You can review the policy in the Visual Editor.

When reviewing the completed policy in the Visual editor, you should see something like:

Create an IAM User and Grant Programmatic Access

Use an existing IAM user, or (best practice) create a specific IAM user for the Sysdig Backend to programmatically access CloudWatch and use its data.

1. In the IAM Console, add a User.

2. Select AWS Access Type: Programmatic Access.

3. Select ‘Attach existing policies directly’, search for and then select the newly created policy (Sample policy name: SysdigMonitorPolicy.)

4. Select ‘Create User’ option.

5. Copy and save the resulting access key and secret key (Note: the Secret is only displayed once, so make sure to download the credentials file or store the key securely that you can reference again.)

In the Sysdig Monitor UI

Enter the Access and Secret Key

1. Log in to Sysdig Monitor or Sysdig Secure as the administrator and select Settings from the user menu.

2. Select AWS.

   

3. Add an account by entering the User Access Key and Secret Key, then clicking Save.

   The credentials will be listed with a Status of OK checked.

Enable CloudWatch Integration

1. Navigate to the AWS page in the Sysdig Monitor UI, if you are not already there.

2. Toggle the CloudWatch Integration Status to Enabled.

   Sysdig Monitor will poll the CloudWatch API every five minutes. Note that this incurs additional charges from AWS.

Refetch Credentials

If the integrated AWS account changes on the AWS side, an Error will be listed in the Credentials Status on the Settings > AWS page.

Use the Refetch Now button to re-establish the integration.

Integrate AWS Account Using the Implicit Key (On-Prem Only)

If Sysdig is installed in an EC2 instance, you can take advantage of the existing EC2 IAM role of that instance. This can simplify administration, as you do not have to manually rotate public and private keys provided to the Sysdig backend.

Use Implicit Key

Prerequisites

Have your on-premises Sysdig platform installed in an AWS EC2 instance that has a proper IAM role.

To enable implicit key, you must set the following parameter:

-Ddraios.providers.aws.implicitProvider=true

In the Settings > AWS page, the former credentials will be overwritten it will show implicit key.

Enablement steps depend on whether you are using Kubernetes or Replicated as your orchestrator.

Kubernetes

1. Edit the config.yaml to add to the following entries (in the Data section of config.yaml):

   sysdigcloud.jvm.api.options:
   sysdigcloud.jvm.worker.options:
   sysdigcloud.jvm.collector.options:
   

   

2. If you are switching from manual to implicit keys, you must also restart the API, worker, and collector components.

   See To Make Configuration Changes for details.

3. Enable Cloudwatch integration in the Sysdig UI.

Changing the AWS Services that are Polled

Sysdig is designed to collect metadata for particular AWS services, which are reflected in the IAM policy code.

The services are:

• DynamoDB

• EC2 hosts

• ECS

• Elasticache

• RDS

• SQS

When you implement the code and integration steps as described above, it will trigger two types of collection: first the metadata for each service is collected, and then Sysdig will poll for the metrics about the metadata returned. So, if the service is not enabled in your environment, no metadata (and no metrics) are collected about it. If it is enabled, but you do not want to poll metrics, then delete the lines of code related to that service from the IAM policy. This will avoid potential unwanted AWS API requests and potential AWS charges.

See also AWSin the Metrics Dictionary.

Security Groups

If you have an on-premises Sysdig Backend, and have restricted outbound security groups, you may need to allow HTTPS & DNS access in order for the Sysdig Backend components to make connection to the Amazon APIs. As Amazon API endpoints are referenced by name and have a large number of IP’s, this may need to be full 0.0.0.0/0 outbound access for HTTPS & DNS.

If you need to filter just to Amazon IP ranges, you can use the following as a guide: https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html

Retrieving CloudWatch Data for Particular AWS Regions

To enable metrics collection from only certain AWS regions in your environment, it is necessary to open a ticket with Sysdig Support. See Contact Support for details.

Related Information

For information on the resulting AWS services visible in Sysdig Monitor, see the AWS-related information in the Metrics Dictionary (also available from within the Sysdig Monitor UI).

For information on how licensing affects AWS service views, see About AWS Cloudwatch Licensing.

4.1 -

IAM Policy Code to Use

Best Practice: Create a Sysdig-specific IAM policy to be used for granting programmatic access to Sysdig. Copy/paste the code snippet below into this policy. It enables Sysdig to collect metadata and CloudWatch metrics from the following services, as applicable to your environment:

• Dynamodb

• EC2 hosts

• ECS

• Elasticache

• RDS

• SQS

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "autoscaling:Describe*",
                "cloudwatch:Describe*",
                "cloudwatch:Get*",
                "cloudwatch:List*",
                "dynamodb:ListTables",
                                "dynamodb:Describe*",
                "ec2:Describe*",
                "ecs:Describe*",
                "ecs:List*",
                "elasticache:DescribeCacheClusters",
                "elasticache:ListTagsForResource",
                "elasticloadbalancing:Describe*",
                "rds:Describe*",
                "rds:ListTagsForResource",
                "sqs:ListQueues",
                "sqs:GetQueueAttributes",
                "sqs:ReceiveMessage"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

See Changing the AWS Services that are Polled for more detail.

4.2 -

Integrate with AWS Role Delegation

This section describes how to configure Sysdig Monitor to utilize the Amazon Web Service (AWS) AssumeRole functionality and authorize Sysdig Monitor to discover cloud assets, grab CloudWatch metrics from your AWS account, and utilize custom S3 bucket for storing captures. Upon integrating with an AWS role, you can delegate access to AWS resources that are not associated with your Sysdig AWS account.

Setting up cross-account access through roles eliminates the need to create individual IAM users in each account. In addition, users don’t have to sign out of one account and sign in to another in order to access resources in different AWS accounts.

Role delegation is an alternative to the existing integration method using the access keys. This method is considered secure as sharing developer access keys with third-parties is not recommended by Amazon.

Prerequisites and Guidelines

This topic assumes that you have the following ready and you are familiar with AWS.

• Sysdig Monitor API Token

• External ID

• API endpoint. In this topic, it is referred to as {{host}}

  • SaaS: See SaaS Regions and IP Ranges and identify the correct domain URL associated with your Sysdig application and region. For example, in US East, the endpoints are:

    • Monitor: https://app.sysdigcloud.com

    • Secure: https://secure.sysdig.com

    For other regions, the format is https://<region>.app.sysdig.com. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com.

  • On-Prem: Depends on the on-prem deployment.

• Administrator privileges to configure AWS integration

• API client. Examples in this topic use curl

• AWS account ID

  • SaaS: The default AWS account ID is 273107874544 (US East region). For other regions, check AWS account IDs .

  • On-Prem: Customer-specific.

Enable AWS Role Delegation with API

This section describes how to enable AWS role delegation using an API.

Instructions for SaaS

1. Get Your External ID.

2. Configure Role Delegation.

3. Get Role ARN.

4. Add the AWS Account.

Instructions for On-Prem

1. Get Your External ID.

2. Configure Role Delegation.

3. Get Role ARN.

4. Add the AWS Account.

5. Follow Additional Configuration for On-Prem.

Get Your External ID

Retrieve your external ID as follows:

curl -k --request GET \

--url host/api/users/me \

--header 'authorization: Bearer e71d7c0f-501e-47d4-a159-39da8b716f44' | jq '.[] | .customer | .externalId'

An example of External ID from the response will be 04acdd59-4c98-4d11-8ee5-424326248161.

Configure Role Delegation

Integrating the Sysdig Platform with Amazon Web Services requires configuring role delegation using AWS IAM.

1. Create a new role in the AWS IAM Console:

   

   1. For the role type, select Another AWS account.

   2. (SaaS) Enter the Sysdig account ID for Account ID.

      This means that you are granting read-only access to your AWS data.

   3. Select Require external ID and enter the one you retrieved in the previous step. Leave MFA disabled.

2. Click Next: Permissions.

3. Create the following policies:

   • sysdig_cloudwatch: Gives access to the list and describe supported AWS resources and get CloudWatch metrics for them.

   • sysdig_s3: Defines the bucket name where we wish to store the captures

     For more information on policies, see IAM Policy Code to Use.

   For detailed instructions on how to create a policy, see Integrate AWS Account Manually.

   1. If a policy has already been created, search for it on this page and select it, then skip to step. Otherwise, click Create Policy, which opens in a new window.

   2. Click Review policy.

   3. Name the policy and provide an apt description. For example, sysdig_cloudwatch.

   4. Click Create Policy.

      You can now close this window.

4. In the Create role window, refresh the list of policies and select the policies you just created.

5. Click Next: Review.

6. Give the role a name and an apt description. For example, sysdig_role.

7. Click Create Role.

Get Role ARN

1. Select Roles > sysdig-role.

   

2. Copy Role ARN.

Add the AWS Account

Using the role that you have created, add an AWS account on the Sysdig Monitor side. Use the following API call:

curl --request POST \
  --url {{host}}/api/providers \
  --header 'authorization: Bearer e71d7c0f-501e-47d4-a159-39da8b716f44' \
  --header 'content-type: application/json' \
  --data '{"name": "aws","credentials": {"role": "<Role_ARN>"},"alias": "role_delegation"}'

Replace <Role_ARN> with the one that you have copied in the previous section.

The response lists all the providers. An example response is given below:

{

  "provider": {

    "id": 7,
    "name": "aws",
    "credentials": {

      "id": "role_delegation",
      "role": "arn:aws:iam::485365068658:role/sysdig-access3"
    },
    "tags": [],
    "status": {

      "status": "configured",
      "lastUpdate": null,
      "percentage": 0,
      "lastProviderMessages": []
    },
    "alias": "role_delegation"
  }
}

Verify the role delegation has been created.

1. Log in to Sysdig Monitor or Sysdig Secure as an administrator.

2. Do one of the following:

   • Select Integrations > AWS CloudWatch.

   • From the user menu, select Settings > AWS.

   The role that you have been created will be added to the list of AWS Accounts.

3. Proceed to enable CloudWatch and AWS S3 bucket.

   See AWS: Integrate AWS Account and CloudWatch Metrics (Optional) for more information.

Additional Configuration for On-Prem

1. Create an AWS user that will be used to fetch temporary credentials.

2. Assign a policy to the user to allow AssumeRole. For example:

   {
     "Version": "2012-10-17",
     "Statement": {
       "Effect": "Allow",
       "Action": "sts:AssumeRole",
       "Resource": "arn:aws:iam::{ACCOUNT-ID}:role/{ROLE_NAME}*"
     }
   }
   

3. Make the access keys available to users from one of the sources:

   • Environment variables

   • Java system properties

   • Instance profile credentials delivered through the Amazon EC2 metadata service.

     EC2 metadata service is recommended if the installation is on AWS.

Example: Set Environment Variables on a Kubernetes Installation

1. Create Secret:

   apiVersion: v1
   kind: Secret
   metadata:
     name: aws-credentials
   type: Opaque
   data:
     aws.accessKey: {{BASE64_ENCODED_ACCESS_KEY_ID}}
     aws.secretKey: {{BASE64_ENCODED_ACCESS_KEY_SECRET}}
   

2. Expose variables in deployment descriptors (sysdigcloud-collector, sysdigcloud-worker, sysdigcloud-api) and reference values in the newly created secret:

   - name: AWS_ACCESS_KEY_ID
       valueFrom:
       secretKeyRef:
           key: aws.accessKey
           name: aws-credentials
   - name: AWS_SECRET_ACCESS_KEY
       valueFrom:
       secretKeyRef:
           key: aws.secretKey
           name: aws-credentials
   

   Add variables to descriptors on each platform update until new variables are part of the installer.

Set Up Resource Discovery

The supported AWS are EC2, RDS, Elastic Load Balancer (ELB), ElastiCache, SQS, DynamoDB, and Application Load Balancer (ALB).

By default, all the resources are fetched for all regions supported by AWS. You can avoid this by whitelisting regions when creating a provider key via the API. Example body of the provider key request when whitelisting regions:

{
    "name": "aws",
    "credentials": {
        "role": "arn:aws:iam::676966947806:role/test-assume-role"
    },
    "additionalOptions": "{\"regions\":[\"US_EAST_1\",\"US_EAST_2\"]}"
}

Enable AWS Role Delegation with UI

Use the AWS option in the Settings menu to configure AWS role delegation.

1. Log in to the Sysdig Monitor as an administrator

2. Do one of the following:

   • Select Integrations > AWS CloudWatch.

   • From the user menu, select Settings > AWS.

     The AWS Account page is displayed.

     

3. Click Add Accounts.

   The Identity Authentication page opens to the Role Delegation tab.

4. Specify the following:

   

   • Role ARN: The Role ARN associated with the role you have created for role delegation. The ID is available on the summary page of the role on the AWS console. For more information, see Integrate with AWS Role Delegation.

   • AWS External ID: Ensure that AWS External ID is displayed on the page.

     • SaaS: For account IDs corresponding to your region, see SaaS Regions and IP Ranges

     • On-Prem: Customer-specific.

5. Click Save.

5 -

Storage: Configure Options for Capture Files

The Sysdig Capture feature allows you to record detailed system trace data via remote connection from any of your agent-installed hosts. In SaaS installations, by default, this data will be stored on Sysdig’s secure Amazon S3 storage location. This location will have a separate partition for your account. In on-premises installations, by default, the data will be stored in the Cassandra database.

This page describes two custom alternatives: using an AWS S3 bucket (available for SaaS and on-prem) and using custom S3 storage.

Configure AWS S3 Storage

To configure this option, use the fields provided by Sysdig Settings UI and then append some code to the IAM Policy you created in AWS for Sysdig integration.

Prerequisites

• Your AWS account must be integrated with Sysdig, but the CloudWatch feature is not required to be enabled.

  See AWS: Integrate AWS Account and CloudWatch Metrics (Optional)

• Ensure that your S3 bucket name is available.

• To use your own AWS S3 bucket to store Sysdig capture files, append the following code snippets to the **AWS Identity and Access Management (IAM) **page.

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Action": [
                  "s3:Put*",
                  "s3:List*",
                  "s3:Delete*",
                  "s3:Get*"
              ],
              "Effect": "Allow",
              "Resource": [
              "arn:aws:s3:::BUCKET_NAME",
              "arn:aws:s3:::BUCKET_NAME/*"
              ]
          }
      ]
  }
  

• If you are using AWS KMS for AWS S3 encryption, ensure that necessary privileges are given to the Sysdig Account or Role to use the custom key.

  

  Use the Key users option to do so:

  

In the Sysdig UI

1. Log in as an Administrator to Sysdig Monitor or Sysdig Secure.

2. From the user menu in the lower-left navigation, do one of the following:

   • Select Integrations > Capture Storage.
   • Select Settings > Capture Storage.

   

3. Enable the **Use a custom S3 bucket**toggle and enter your AWS S3 bucket name.

To Test: Capture a Trace File in Sysdig Monitor UI

When enabled, you will have the option to select between “Sysdig Monitor Storage” or your own storage bucket when configuring a file capture. See Create a Sysdig Capture File.

(SaaS) Configure Custom S3 Storage Endpoint

You can set up a custom Amazon-S3-compatible storage, such as Minio or IBM Cloud Object Storage, for storing Captures in a Sysdig SaaS deployment. The capture storage location can be used for both Sysdig Monitor and Sysdig Secure. This is an API-only functionality and currently, no UI support is available.

The following APIs are supported for this functionality:

• List existing AWS integrations

• Create a new AWS integration

• Update an existing AWS integration

• Configure storage configuration

Prerequisites

• Ensure that the feature is enabled for your account.

• Use the access key and secret as the credentials.

• Configure a new AWS integration. Set the skipFetch field to true. This will cause the AWS integration to ignore fetching data from this account. Therefore, both the AWS metadata and AWS CloudWatch will not be fetched and you can use this storage exclusively for Sysdig Capture.

• Configure the storage interface with the new account, by specifying the AWS integration ID to use to authenticate the endpoint, bucket name, and the path specified in the bucket.

Limitation

The AWS account ID is currently shown as null on the UI.

List Existing AWS Integration

The API returns the list of configured AWS integrations.

REST Resource: Providers

GET {{host}}/api/providers
Authorization: Bearer {{API_Token}}

Response Parameters

Sample Response

{
  "providers": [
    {
      "id": 2398,
      "name": "aws",
      "credentials": {
        "id": "AKIA4JRXW5ZVZU6MHNPE",
        "role": null
      },
      "skipFetch" : false,
      "status": {
        "status": "done",
        "lastUpdate": 1617274193293,
        "percentage": 100,
        "lastProviderMessages": []
      },
      "alias": null,
      "accountId": "845151661675"
    }
  ]
}

Create a New AWS Integration

REST Resource: Providers

POST {{host}}/api/providers
content-type: application/json
Authorization: Bearer {{API_Token}}

{
    "name":"aws",
    "skipFetch": false,
    "credentials": {
        "id":"<AWS_Access_Key_ID>",
        "role":null,
        "key":"<AWS_SecretKey>"
    }
}

Request Parameters

Update Custom Storage Settings

To update existing storage settings, perform a PUT HTTP call to the endpoint as follows:

REST Resource: Settings

PUT {{host}}/api/sysdig/settings
content-type: application/json
Authorization: Bearer {{API_Token}}

{
    "enabled":true,
    "buckets":[
        {
            "folder":"/folder1/folder2",
            "name":"bucketName",
            "providerKeyId": 3,
            "endpoint": "http://127.0.0.1:9009"
        }
    ]
}

Request Parameters

(On-Prem) Configure Custom S3 Endpoint

You can set up a custom Amazon-S3-compatible storage, such as Minio or IBM Cloud Object Storage, for storing Captures in a Sysdig on-premises deployment. The capture storage location can be used for both Sysdig Monitor and Sysdig Secure. This is an API-only functionality and currently, no UI support is available.

You must configure values.yaml corresponding to your Sysdig installation in order for this configuration to work.

Prerequisites

• Your on-premise installation is Installer-based. If you have installed Sysdig Platform manually and you want to configure custom S3 buckets to store your capture files, contact your Sysdig representative.

• Ensure that AWS-client compatible credentials used for authentication are present in the environment.

• Ensure that the list, get, and put operations are functional on the S3 bucket that you wish to use. Confirm this by using the S3 native tools, for example, as described in AWS CLI for IBM Cloud.

Configure Installer

Configure the following parameters in the values.yaml file so that collectors, workers, and the API server are aware of the custom endpoint configuration.

• sysdig.s3.enabled

  Required: true
  Description: Specifies if storing Sysdig Captures in S3 or S3-compatible storage is enabled or not.
  Options:true|false
  Default:false
  

  For example:

  sysdig:
    s3:
      enabled: true
  

• sysdig.s3.endpoint

  Required: true
  Description: The S3 or S3-compatible endpoint for the bucket. This option is ignored if sysdig.s3.enabled is not configured.
  

  For example:

  sysdig:
    s3:
      endpoint: <your S3-Compatible custom bucket>
  

• sysdig.s3.capturesFolder

   Required: false
   Description: Name of the folder in S3 bucket to be used for storing captures, this option is ignored if sysdig.s3.enabled is not configured.
  

  For example:

  sysdig:
    s3:
      capturesFolder: my_captures_folder
  

  The path to the capture folder in the S3 bucket will be ​{​​customerId​​}/{​my_captures_folder​​}​​. For on-prem deployments, the ​customerID​ is ​1​​. If ​finance​ is your capture folder, the path to the folder in the S3 bucket will be 1/finance​​.

• sysdig.s3.bucketName

  Required: true
  Description: The name of the S3 or S3-compatible bucket to be used for captures. This option is ignored if sysdig.s3.enabled is not configured
  

  For example:

  sysdig:
    s3:
      bucketName: <Name of the S3-compatible bucket to be used for captures>
  

• sysdig.accessKey

  Required: true
  Description: The AWS or AWS-compatible access key to be used by Sysdig components to write captures in the S3 bucket.
  

  For example:

  sysdig:
    accessKey: <AWS-compatible access key>
  

• sysdig.secretKey

  Required: true
  Description: The AWS or AWS-compatible secret key to be used by Sysdig components to write captures in the s3 bucket.
  

  For example:

  sysdig:
    secretKey: <AWS-compatible secret key>
  

For example, the following AWS CLI command uploads a Sysdig Capture file to a Minio bucket:

aws --profile minio --endpoint http://10.101.140.1:9000 s3 cp <Sysdig Capture filename> s3://test/

In this example, the endpoint is http://10.101.140.1:9000/ and the name of the bucket is test.

When you finish the S3 configuration, continue with the instructions on on-premise installation by using the Installer.

6 -

Find Your Customer ID and Name

SaaS customers of Sysdig can be identified by a unique customer number and name, provided by email when the Sysdig environment is first provisioned. While it is generally unnecessary to know the customer number and it is not prominently displayed in the user interface, some configuration settings may require it.

On the UI

To retrieve the customer ID:

1. Log into the Sysdig interface.

2. Select one of the following from the user menu:

   • Authentication (SSO)
   • Settings > Authentication.

   

   The Authentication section lists the Customer ID and Customer Name associated with your account.

Using the API

To retrieve the customer ID:

1. Log into the Sysdig interface.

2. Navigate to the URL endpoint /api/user/me?_product=SDC.

   E.g. https://app.sysdigcloud.com/api/user/me?_product=SDC

   The JSON file contents are displayed in the browser.

3. Find the customer:id portion of the JSON to determine the customer ID and name:

   

7 -

Agent Installation: Overview and Key

The Agent Installation page provides a shortcut for copy/pasting the necessary code lines for different flavors of agent installation.

You can also retrieve the agent access key (copy/paste).

This page can be hidden from non-admins if administrators choose. See also Change Admin Settings in the User Profile page.

Retrieve the Agent Access Key

To retrieve the key or use the agent install code snippets:

1. Log in to Sysdig Monitor or Sysdig Secure as an administrator.

2. Select one of the following:

   • Integrations > Agent Installation.
   • Settings > Agent Installation.

3. Choose Agent Installation.

4. Optional: Use the Copy button to copy the access key at the top of the page.

   Optional: Review and use the sample code to install an agent, as listed.

8 -

Subscription

Try all of Sysdig’s features for free; when you are ready to upgrade, contact Sysdig sales.

See also: Getting Started with Sysdig Monitor and Getting Started with Sysdig Secure.Getting Started with Sysdig Monitor

Subscription Types

Free Tier

With Free Tier, use *Sysdig Secure for cloud *functions free forever:

• For one single account in one cloud region (AWS for v1)

• Manage cloud posture with a daily run of CIS Benchmarks

• Detect threats with out-of-the-box CloudTrail detection rules based on Falco

• Scan containers (ECR/Fargate) automatically and within your cloud environment for up to 250 images a month

30-Day Trial

Test all the features of Sysdig Monitor and/or Sysdig Secure with the free 30-day trial.

After 30 days, your account will be disabled and you can contact Sysdig sales to upgrade to an Enterprise license.

Enterprise Tier

You can license Sysdig Secure, Sysdig Monitor, or both (Sysdig Platform). For details, see https://sysdig.com/pricing/.

Review Current Subscription

1. Log on as Administrator to Sysdig Monitor or Sysdig Secure.

2. From the Selector button in the left-hand navigation, choose Settings > Subscription.

   Your current plan details are displayed.

   

You can license each of these elements independently:  

• Sysdig agents (host agents)

• Cloud accounts (Secure only, see also: Data Sources)

• Fargate tasks/serverless agents  (Secure only, see also Serverless Agents)

The number of licenses purchased has the following effects on how Sysdig is used:

• The agent count defines the maximum number of connected host agents you can deploy. E.g if you purchase 100 licenses, you can install 100 agents.

  • In AWS Service Monitoring powered by Cloudwatch, it also determines the number of AWS objects that can be viewed in the Sysdig Monitor Dashboards (unrelated to the number of agents actually installed). In other words, if you have 100 licenses purchased, you can only see 100 AWS objects per region, per service type.

• **Fargate Tasks using Sysdig Serverless Agents: ** Defines the number of serverless agents connected to Sysdig backend.

• Cloud accounts- licensed number: Number of cloud accounts you can connect to Sysdig backend.

About Host Agent Licenses

Reserved vs On-Demand Agents

The distinction between reserved and on-demand agents is financial, not technical; when on-demand agents are used they perform exactly like reserved agents.

Reserved Agents

Reserved agents are dedicated agents that are provisioned for a user regardless of usage. You can purchase reserved agents on a monthly or annual basis. As a Sysdig SaaS account administrator, you can increase your reserved agents at any time from within the Sysdig application.

On-Demand Agents

On-demand agents are for short-term use and you pay only for what you use at an hourly rate. You have the ability to add and control on-demand agents. For example, an organization might schedule scale testing for two days and license an extra 500 on-demand agents for that time frame.

 In the Sysdig application, use the Customize Your Plan > Enable On-demand Agents option on the Subscription page to add or remove agents. There is a hard limit of 500 agents for any account. If the total of reserved and on-demand exceeds this limit, you will not be able to purchase additional agents. On-demand agents are available only in Sysdig SaaS applications.

Connect Agents to the Backend

The Sysdig platform uses a concurrent licensing model in determining when to allow an installed agent to connect to the back-end servers and report on host metrics. This means you can install Sysdig agents onto any number of instances. However, only the licensed number of agents will be allowed to connect and send metrics for recording and reporting.

Agents connect on a “first-come, first-served” basis and in the event of an over-subscription (more agents wanting to communicate than are licensed) they will attempt to reconnect on a periodic basis. Once an existing communicating instance goes down and disconnects, the next agent attempting to connect will be allowed in.

To avoid having agents refused connection due to over-subscription, monitor the number of established and allowed connections. To see how many licenses are in use, see the Settings > Subscription page. Use this information to either purchase additional license capacity from the UI, or to shut down lower-priority agents via normal orchestration and system administration means.

Technical Details

Multiple Installs: An agent is essentially an “install” of the software. If your system changes external IP addresses, or if you shut down a VM image and bring it back up elsewhere, this will remain the same agent connection. However, identical installs that are simultaneously sending data (usually an accident) will be considered two connections. A MAC address is used to identify a host for licensing purposes.

Time Lag for License Release: When shutting down a host for any reason, the agent’s license will not be immediately released. This permits the agent to retain its licensing slot for short outages or a reboot. The time-out interval can take up to 20 minutes, and if the connection has not been re-established within the interval the license will be released for use by the next host waiting to connect.

8.1 -

Time Series Billing

Sysdig Monitor allows you to consume custom metrics through a flexible and cost-effective Time Series Billing model aligned with your usage. With the enhanced billing experience, you can view your time-series consumption at a glance, analyze trends, and change subscription plans if need be.

Use the Sysdig Subscription page to control your licensing, and thereby usage and spending. Based on your current subscription tier, time-series usage, and the number of active agents, you can estimate the bill and take further actions.

Time Series Billing works only in SaaS environments and is not currently available in on-prem environments.

Benefits of Time Series Billing

• You consume more than the per-agent limit because Time Series Billing accounts for the following:

  • Time series through Monitoring Integrations

    For example, Nginx and Redis.

  • Time series through Prometheus Remote Write

  • Time series through optional Pay as you Go (PAYG) and metric packs.

  See Use Cases for more details.

  Previously, the technical limit was 10K, no PAYG and metrics packs mechanisms, no system in place to bill metrics collected outside agents.

• Validate what you are being charged on, understand and control metric usage, and drop the data that is not required, either by metric or by the scope of the metric. See Control Time Series Ingestion.

• Pay as you go and metric pack.

Consume Time Series

Time series consumption is calculated by using the reserved time series included in the subscription. The basic plan includes 2000 time series per agent, and you can purchase more by adding on-demand agents or metric packs.

Sysdig meters and bills only custom metrics.

• Prometheus

• JMX

• StatsD

• App checks

Reserved Time Series

The number of time series included with the subscription. The value is calculated as (the number of reserved agents + the number of connected on-demand agents) * the number of time series per agent. Time series consumed beyond your subscription limit will be charged and is aggregated across all agents running in your environment. What it means is that you can consume 3000 metrics on an agent and 1000 on another without incurring additional charges.

Contact Sales to purchase beyond your subscription limit.

Time Series Billing limit of 2000 is applicable only to custom metrics, while Sysdig and Sysdig KSM are included at no additional charges.

Metric Pack

A metric pack includes 1000 time series and is charged per month.

View Your Subscription

Time Series Visualization

To help you so, Sysdig provides an at-a-glance visualization of the following:

• Time Series Usage

  • Reserved: See Reserved Time Series.

  • Overage: Time series ingested beyond Reserved time series is Overage.

  • Ingested: The time series that are collected, analyzed, processed for storage.

• Time Series Usage Dashboard

• Reserved and On-Demand Agents

• Agent Usage Dashboard

• Usage history in CSV format

Edit Subscription

1. On the Subscription page, under Subscription Details , click the three dots.

2. Click Edit Subscription.

   The Subscription Plan page gives you the directions to change the subscription plan.

Monitor Time Series Usage

Time Series Metrics

To help you identify the usage trends that are important to you, Sysdig provides the following metrics:

• sysdig_ts_usage: The metric reports the number of time series ingested for a user in a 20-minutes interval. The dashboard reports the 1-hour usage, which is the sum of the maximum of three 20-minute sysdig_ts_usage measurements taken in an hour. This metric can be segmented on metric categories as well.

• sysdig_ts_usage_10s: The metric reports the number of time series ingested for a user in every 10-seconds window, per host (agent), and per metric category.

Download Usage

You can download the usage report in a CSV file. On the Subscription page, under Subscription Details, click Download Usage to download a copy of the usage report. You can view the following:

• User ID

• Time

• Number of Reserved Agents

• Number of Connected On-Demand Agents

• Time Series included per agent

• Total used time series

• The ratio of used and reserved time series

Time Series Usage Dashboard

Sysdig provides a Time Series Usage Dashboard with insight into the usage data. You can view time series ingestion at a glance and discover and analyze trends. The dashboard shows the average number of active time series per host; current ingestion rate; churn percentage; and so on.

Access the Time Series Dashboard

On the Subscription page, under Usage, click Time Series Dashboard. You can view the following:

• Current 1 Hour Ingestion

• Current Ingestion from Agents

• Churn Percentage

• The average number of time series per host

• The number of time series ingested per category

• Host-level ingestion

Calculate Time Series Usage

Time series usage is calculated by using the sysdig_ts_usage metric. The metric reports the number of time series ingested for a user in an hour (sum of the maximum of three 20-minutes). For each hour, the number of time series ingested is calculated, and then the value is deducted from the number of reserved time series. This value is stored as the usage record.

An hour period is considered in order to take the churn into account. Sysdig uses the sysdig_ts_usage_10s metric to calculate the spikes caused by churns and provides you the churn percentage in the dashboard.

Sysdig uses the 95th percentile to calculate the exceeding cost of usage. At the end of the month, the 95th percentile of the total number of active series ingested per hour is calculated. Calculating the 95th percentile reduces the chances of billing you for unexpected spikes causes by churns.

Churn Rate

When a time series stops receiving new data points, it becomes inactive. This event is called time series churn. It occurs more often during an upgrade in a Kubernetes cluster or when containers are replaced by new ones. Restarts, redeploys, dynamic workloads also cause churn and generate additional time series.

In such cases, the container_id label in a container metric changes, and subsequently, all the existing time series are replaced by new time series (with the new container_id value).

The churn rate is the number of time series that churn over time. Sysdig uses the sysdig_ts_usage_10s metric to analyze these scenarios.

The Time Series Usage Dashboard provides a ratio of time series detected at 1-hour period and 10-seconds period. This ratio is known as the churn percentage and it is expressed as this PromQL query:

(sum(sysdig_ts_usage{metric_category!='PROMETHEUS_REMOTE_WRITE'}) - sum(sysdig_ts_usage_10s)) / sum(sysdig_ts_usage{metric_category!='PROMETHEUS_REMOTE_WRITE'}) * 100

The time series collected by Prometheus Remote Write are excluded from this ratio because they are not collected by the Sysdig agent.

Example

The billing is calculated per month. A basic subscription will provide you 2000 time series per agent. This limit is applicable only to custom metrics, while you can continue consuming Sysdig and KSM metrics without incurring additional costs. Time series consumed beyond your subscription limit will be charged and is aggregated across all agents running in your environment.

For example, if you have three agents running with the following consumption:

• Agent 1 collecting 2000 time series per hour

• Agent 2 collecting 1000 time series per hour

• Agent 3 collecting 4000 time series per hour

Time series billing is calculated as follows:

Total consumption = 7000

Allowed number of time series per hour: 3 * 2000 = 6000

Effectively, you are paying only for (7000 - 6000) = 1000 because the cost is calculated on the aggregated time series consumed across all the agents running in your environment.

Control Time Series Ingestion

For more information on controlling metric usage, see the following:

• Include/Exclude Custom Metrics

• Pricing

Use Cases

Agent and Remote Write Plan

See the following example with the following configuration:

• Two Prometheus Servers

  • Prometheus Server 1 generates 50,000 time series

  • Prometheus Server 2 generates 150,000 time series

• A Sysdig agent that collects 1000 time series

• A subscription capacity of 2000 time series

The billing for the month is calculated as follows:

Time series usage: Total usage - Subscription capacity

(50,000 + 150,00 + 1000) - 2000 = 199,000

If the base price is $7.5 for up to a unit of 1K time series per month, the total base cost is calculated as follows:

The number of units consumed = (199,000 / 1000) = 199

The total cost = $7.5 * 199 = $1592.50

Agents, Remote Write, and Metric Pack Plan

See the following example with the following configuration:

• Two Prometheus Servers

  • Prometheus Server 1 generates 50,000 time series

  • Prometheus Server 2 generates 150,000 time series

• A Sysdig agent that collects 1000 time series

• 100 metric pack, which is equivalent to 100000 time series

The billing for the month is calculated as follows:

Total subscription capacity: Total usage - (subscription capacity + time series from metric pack)

201,000 - (100,000 + 2000) = 99,000

If the base price is $7.5 for up to a unit of 1K time series per month and $5 for a metric pack of 1K time series, the total base cost is calculated as follows:

The number of units consumed = (199,000 / 1000) = 199

The total cost = Cost of metric pack + cost of total usage

($7.5 * 199) + (100 * $5) = $2092.50

8.2 -

About AWS Cloudwatch Licensing

In the Explore tab or Dashboards of Sysdig Monitor, the number of metrics displayed for each AWS service is limited by the number of agent licenses purchased and/or used, by region.

The license count:

• Includes Reserved agents plus On-Demand agents (even if not in use).

• Is used to determine how many AWS resources are displayed for each service in each region.

• Is not transferable between different AWS services.

AWS Service Type Priorities and Limits

For each AWS service type, services are displayed in the following priority:

• EC2: Pick instances with agents installed, then instances belonging to ECS, instance is launched before another, alphabetically by instance ID, up to license count.

• RDS: Pick by creation time, oldest instances first, up to license count.

• ELB: Pick by number of balanced instances (larger ELBs 1st), then by creation time, oldest first, up to license count.

• ElastiCache: Sort by name and display up to license count items.

• SQS: Sort queues by name and pick up to license count number of queues to fetch. Data is shown only for queues that are reporting metrics.

• DynamoDB: Sort by name and display up to license count items.

• ALB: Sort by name and display up to license count items.

For more information on AWS metrics, see AWS in the Metrics Dictionary.

Sample Use Case

Suppose you have 200 AWS instances, have purchased 100 Sysdig agent licenses, and have actually installed 50 agents.

The following limits would apply to your views of AWS services, per region:

• EC2: The 50 instances with agents installed would be shown first, then 50 more instances, first from EC2, then from ECS, then per uptime.

• RDS: 100 RDS listings would be shown, oldest first.

• ELB: 100 ELBs would be shown (largest first), then by creation time, oldest first.

• ElastiCache: 100 ElastiCache objects would be shown, alphabetically by name.

• SQS: 100 SQS queues that are reporting metrics would be shown.

• DynamoDB: 100 DynamoDBs would be shown, alphabetically by name.

• ALB: 100 ALBs would be shown, alphabetically by name.

To increase the limit of items in the AWS Services views, contact Sysdig Sales to enable additional resources depending on your license agreement.

9 -

Authentication and Authorization (SaaS)

Sysdig Monitor and Sysdig Secure are designed to work with several user authentication/authorization methods:

The user’s view:

The pages in this section describe the integration and enablement steps required for SAML or OpenID Connect, and the Identity Provider (IdP) services that support these protocols, such as Okta, OneLogin, Keycloak.

In the SaaS environment, Google login can be enabled with a simple drop-down selection; the integration has already been performed.

See SaaS Regions and IP Ranges before proceeding to configure authentication.

Workflow

With the new Authorization UI, the basic process of enabling a Single Sign-On (SSO) option is:

1. Determine which SSO option (GoogleOAuth, SAML, OpenID) your enterprise uses, and which IdP service (Okta, OneLogin, etc.) is used, if any.

2. Enter the required connection settings for the chosen SSO on the appropriate Authentication tab. (Note: for Google, the settings are already entered.)

3. Configure any associated IdP settings on the IdP side.

4. Select the SSO option from the Enabled Single Sign-On drop-down and click Save Authentication.

5. If enabling for both Sysdig Monitor and Sysdig Secure, repeat the process on the second application.

View of the Authentication page for Google OAuth in the SaaS environment.

9.1 -

Google OAuth (SaaS)

In the SaaS environment, Google users have the option to log in via Google OAuth.

As the SaaS platform is preconfigured to permit such logins, environments that already use Google services (such as G Suite) may find this the most convenient approach for simplified login.

Enable Google OAuth

Since Google OAuth is pre-configured by Sysdig, the administrator needs only select it as the chosen Authentication option to enable it.

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

2. Select Authentication.

   (Select the Google OAuth tab if you want to see the preconfigured (un-editable) settings. )

   

3. Select Google OAuth from the Enabled Single Sign-On dropdown and click Save Authentication.

4. Repeat for Sysdig Monitor or Sysdig Secure, if you want to enable on both applications.

User Experience

Note the following requirements for successful Google OAuth login:

For such a user to log in via Google OAuth, click the Log in with Google button.

See also User and Team Administration for information on creating users.

9.2 -

SAML (SaaS)

SAML support in the Sysdig platform allows authentication via your choice of Identity Provider (IdP).

The Sysdig platform ordinarily maintains its own user database to hold a username and password hash. SAML instead allows for redirection to your organization’s IdP to validate username/password and other policies necessary to grant access to Sysdig application(s). Upon successful authentication via SAML, a corresponding user record in the Sysdig platform’s user database is automatically created, though the password that was sent to the IdP is never seen nor stored by the Sysdig platform.

This section describes how to integrate and enable SAML with both Sysdig Monitor and Sysdig Secure.

For specific IdP integration information, refer to:

• Okta (SAML)

• OneLogin (SAML)

• ADFS (SAML)

• Azure Active Directory (SAML)

See also Caveats

Basic Enablement Workflow

Administrator Steps

Configure IdP

Select the appropriate IdP from the list below, and follow the instructions:

• Okta (SAML)

• OneLogin (SAML)

• ADFS (SAML)

• Azure Active Directory (SAML)

Enable SAML in Settings

To enable baseline SAML functionality:

Enter SAML Connection Settings

1. Log in to Sysdig Monitor or Sysdig Secure as administrator and select Settings from the User Profile button in the left navigation.

2. Select Authentication.

3. Select the SAML tab.

4. Enter the relevant parameters (see table below) and click Save.

   It is strongly recommended that “Signed Assertion” and “Validate Signature” are enabled to ensure that the SAML SSO process is as secure as possible.

Select SAML for SSO

1. Select SAML from the Enabled Single Sign-On dropdown

2. Click Save Authentication.

3. Repeat entire enablement process for Sysdig Monitor or Sysdig Secure, if you want to enable on both applications.

Configure SAML Single Logout

Sysdig supports SAML Single Logout (SLO).

SLO is a feature in federated authentication where Sysdig users can sign out of both their Sysdig session (Service Provider) and associated IdP (Identity Provider) simultaneously. SLO allows you to terminate all sessions established via SAML SSO by initiating a single logout process. Closing all user sessions prevents unauthorized users from gaining access to Sysdig resources.

SLO Process

When a user initiates a logout, Sysdig sends a digitally-signed logout request to the IdP. The IdP validates the request and terminates the current login session, then redirects the user back to the Sysdig login page.

Caveats

• SLO is currently supported only in US-West and EU-Central regions.

• Sysdig does not support HTTP Post binding for single logout, and therefore, SLO with Okta is not functional at this point.

Configure IdP

1. Configure logout URLs:

   • Monitor: <base_URL>/api/saml/slo/logout

   • Secure: <base_URL>/api/saml/slo/secureLogout

2. Choose HTTP Redirect as the binding method.

   This option is an alternative to the HTTP POST method, which Sysdig does not support currently.

3. If your IdP mandates, upload the public key for Sysdig.

   Contact Sysdig Support to retrieve the public key associated with your deployment.

   Certain IDPs, such as Azure, don’t require uploading the public key.

Configure Sysdig

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

   For on-prem deployments, log in as the super admin.

2. Navigate to Settings > Authentication, and select SAML under Connection Settings.

3. Enter the SAML configuration.

4. Ensure that Enable SAML single logout is toggled on.

   

5. Click Save.

6. Ensure that you select SAML from the Enable Single Sign On drop-down.

User Experience

As noted in the Basic Enablement Workflow above, you can offer users three ways to log in with a SAML configuration:

• They can begin at the Sysdig SaaS URL and click the SAML button.

  See SaaS Regions and IP Ranges and identify the correct Sysdig SaaS URL associated with your Sysdig application and region. For example, URLs of Monitor and Secure for US East are:

  Monitor: app.sysdigcloud.com

  Secure: secure.sysdig.com

  They will be prompted to enter a Company Name, so the Sysdig platform can redirect the browser to your IdP for authentication.

  Contact Sysdig Support to set your company name on the account.

  

• You can provide an alternative URL to avoid the user having to enter a company name, in the format:

  Sysdig Monitor: https://app.sysdigcloud.com/api/saml/ COMPANY_NAME

  Sysdig Secure: https://secure.sysdig.com/api/saml/ COMPANY_NAME?product=SDS

  For other regions, the format is https://<region>.app.sysdig.com/api/saml/auth. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Secure in the EU, you use https://eu1.app.sysdig.com/api/saml/secureAuth.

• You can configure an IdP-initiated login flow when configuring your IdP. The users then select the Sysdig application from your IDP’s app directory and do not browse directly to a Sysdig application URL at all.

See also User and Team Administration for information on creating users.

Caveats

• SAML Assertion Encryption/Decryption is not currently supported.

9.2.1 -

Okta (SAML)

Review SAML (SaaS) before you begin.

Configure Sysdig Monitor and/or Sysdig Secure as a SAML application using Okta’s documentation for Setting Up a SAML Application in Okta. The notes below call out specific steps that require additional action.

Sysdig-Specific Steps for Okta Configuration

IDP-initiated Login Flow

If you don’t intend to configure IDP-initiated login flow, check the boxes for “Do not display application icon to users” and “Do not display application icon in the Okta Mobile app”.

URL, URI and RelayState Values

Enter the values shown in the table below. If you wish to configure IDP-initiated login flow, replace CUSTOMER-ID-NUMBER with the number retrieved as described in Find Your Customer Number.

See SaaS Regions and IP Ranges and identify the correct URLs associated with your Sysdig application and region. For example, in US East, the endpoints are:

For other regions, the format is https://<region>.app.sysdig.com. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com/api/saml/auth.

Email and Name Values

Instead of the values shown in the Okta example, add the values:

Note that the attributes are case sensitive, so use caution when entering them.

Only email is required. However, including first/last name is recommended, since these values will now be included in the records created in the Sysdig platform’s database when new users successfully login via SAML for the first time.

SAML Configuration Metadata Value

Copy the URL and paste in the Metadata entry on the SAML Configuration page in the SAML connection settings.

Test Metadata (Optional)

To ensure the metadata URL you copy at the end of the IDP configuration procedure is correct, you can test it by directly accessing it via your browser.

When accessing the URL, your browser should immediately download an XML file that begins similarly to the example shown below. No entry of credentials or other security measures should be required to successfully download it. If this is not the case, revisit the IDP configuration steps.

9.2.2 -

OneLogin (SAML)

Review SAML (SaaS) before you begin.

Configure Sysdig Monitor and/or Sysdig Secure as a SAML application using OneLogin’s article titled Use the OneLogin SAML Test Connector. The notes below call out specific steps that require additional action.

Sysdig-Specific Steps for OneLogin Configuration

Adding the SAML Test Connector

At the step for “Adding the SAML Test Connector”, select SAML Test Connector (IdP w/ attr w/ sign response). If you don’t intend to configure IDP-initiated login flow, uncheck the slider so it will no longer be “Visible in portal”.

Test Connector Configuration Page Settings

At the “Test Connector Configuration Page”, enter the values shown in the table below. If you wish to configure IDP-initiated login flow, replace CUSTOMER-ID-NUMBER with the number retrieved as described in the Find Your Customer Number article.

See SaaS Regions and IP Ranges and identify the correct URLs associated with your Sysdig application and region. For example, given below are the URLs for the US East region.

For other regions, the format is https://<region>.app.sysdig.com. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com/api/saml/auth.

(Optional) If you want the user’s First Name and Last Name to be included in the records created in the Sysdig platform’s database when new users successfully login via SAML for the first time, click to the Parameters tab. Click Add parameter and create each of two New Fields, checking the box each time to Include in SAML assertion. Then click to Edit each field and select the Value shown from the drop-down menu before clicking Save.

Note that the Field Names are case sensitive, so be careful to enter them as all lowercase.

The following shows an example of a correctly-configured field for First Name:

Issuer URL

Click to the SSO tab, copy the Issuer URL, and paste in the Metadata entry on the SAML Configuration page in the SAML connection settings.

Test Metadata (Optional)

To ensure the metadata URL you copy at the end of the IDP configuration procedure is correct, you can test it by directly accessing it via your browser.

When accessing the URL, your browser should immediately download an XML file that begins similarly to the example shown below. No entry of credentials or other security measures should be required to successfully download it. If this is not the case, revisit the IDP configuration steps.

9.2.3 -

ADFS (SAML)

Review SAML (SaaS) before you begin.

These instructions assume you already have a working, Internet-accessible ADFS ( Active Directory Federation Service) server. Interoperability testing has been performed specifically with ADFS on Windows Server 2012 R2.

Follow the instructions below to configure ADFS with the ADFS Management tool in the Windows Server Manager.

For Service-Provider-Initiated Login Flow

1. Right-click to Service > Edit Federation Service Properties. Note the hostname in the Federation Service Identifier, as this will be used in the metadata URL that you paste in the Metadata entry on the SAML Configuration page in the Sysdig authentication settings. Specifically, the metadata URL will be of the format https://HOSTNAME/FederationMetadata/2007-06/FederationMetadata.xml. Also, so that the Sysdig platform can access this URL directly, this host must resolve in DNS and have a valid (not self-signed) SSL/TLS certificate.

   

2. Add a Relying Party Trust configuration for the Sysdig application.

   1. Right-click to Relying Party Trusts > Add Relying Party Trust and click Start to begin the wizard.

      

   2. In the Select Data Source step, click the button to Enter data about the relying party manually, then click Next

      

   3. Enter a Display name of your choosing (e.g. “Sysdig Monitor” or “Sysdig Secure”), then click Next

      

   4. Click Next to accept the default option to use AD FS profile

      

   5. Click Next to skip the selection of an optional token encryption certificate (Sysdig does not support this option)

      

   6. Check the box to Enable support for the SAML 2.0 Web SSO protocol, then enter one of the following values for Relying party SAML 2.0 SSO service URL:

      If configuring Sysdig Monitor, enter: https://app.sysdigcloud.com/api/saml/auth

      If configuring Sysdig Secure, enter: https://secure.sysdig.com/api/saml/secureAuth

      Then click Next.

      

   7. For the Relying party trust identifier, enter one of the following values:

      If configuring Sysdig Monitor, enter: https://app.sysdigcloud.com

      If configuring Sysdig Secure, enter: https://secure.sysdig.com

      Then click Add, then click Next

      

   8. Click Next to skip configuration of multi-factor authentication

      

   9. Choose a policy for whether users will be permitted to login to the Sysdig application. The default to Permit all users to access the relying party will typically be acceptable. Click Next.

      

   10. Review the summary and click Next to complete the configuration of the Relying Party Trust

       

   11. The next step will involve adding Claim Rules, so you can leave the box checked to Open the Edit Claim Rules dialog and click the Close button to be brought immediately into the Claim Rules editor

       

3. Ensure that the SamlResponseSignature option matches the Sysdig authentication configuration.

   1. Use the Set-AdfsRelyingPartyTrust/Get-AdfsRelyingPartyTrust cmdlets via PowerShell to configure SamlResponseSignature .

      -SamlResponseSignature
      Specifies the response signatures that the relying party expects. The acceptable values for this parameter are:
      
      AssertionOnly
      MessageAndAssertion
      MessageOnly
      

      For more information, see Set-AdfsRelyingPartyTrust.

   2. Navigate to Settings > Authentication on the Sysdig app and check the Sysdig authentication setting maps to the SamlResponseSignature :

      

      For MessageAndAssertion, enable both the options.

4. Next, use the Claim Rules to ensure that login data is sent as needed to the Sysdig platform. A user’s login to the Sysdig platform is based on an email address, and a default ADFS configuration would not send the email address as required. The following configuration ensures the correct field from Active Directory is delivered in the claim.

   1. If not already in the Claim Rules editor from the previous step, navigate to it by right-clicking on the Relying Party Trust that was just created and selecting Edit Claim Rules

      

   2. Click Add Rule. At the following screen, accept the default rule template to Send LDAP Attributes as Claims and click Next.

      

   3. Enter a name for the rule, select Active Directory as the Attribute store, then use the pull-down selectors to pick E-Mail Address as both the LDAP Attribute and Outgoing Claim Type, then similarly make pull-down selections for Given Name and Surname. Once these selections are made, click Finish.

      

   4. Now click Add Rule again, this time selecting the template for Transform an incoming claim

      

   5. Enter a name for the rule, then use the pull-downs to select an Incoming claim type of E-Mail Address, an Outgoing claim type of Name ID, and an Outgoing name ID format of Email, then click Finish.

      

   6. (Optional) If you want the user’s First Name and Last Name to be included in the records created in the Sysdig platform database when new users successfully login via SAML for the first time, additional Transform rules must also be created. Only the email-based username is strictly required and we already created a rule for this, so this step is optional.

      If you wish to do this, click Add Rule and once again select the template for Transform an incoming claim. Enter a name for the rule, then use the pull-down to select an Incoming claim type of Given Name, and for the Outgoing claim type, directly type first name into the field. After clicking Finish, click Add Rule and create a similar rule to transform the Incoming claim type of Surname to the Outgoing claim type of last name.

      

   7. Having clicked Finish after creating your last rule, you will see all rules now in the editor. Click Ok, and your ADFS configuration for your Sysdig application is complete.

      

For IdP-Initiated Login Flow (Optional)

(Optional) The steps above represent a Service-Provider-Initiated SAML configuration. If you would prefer an IdP-initiated SAML configuration, this is also possible with ADFS, but requires the additional steps described below.

1. The Sysdig platform requires a specific setting of RelayState in order to accept IdP-initiated login flows. On the ADFS versions tested, we’ve found this use of RelayState is disabled by default, and a Microsoft article describes the topic in detail. To enable it, as described in a Microsoft forum thread, on your ADFS host, edit %systemroot%\ADFS\Microsoft.IdentityServer.Servicehost.exe.config and add <useRelayStateForIdpInitiatedSignOn enabled="true" /> to the <microsoft.identityserver.web> section. Once the modification is saved, restart ADFS services for the change to take effect.

2. You will need to retrieve your Sysdig customer number as described in the Find Your Customer Number article.

3. You will then need to generate an IdP-initiated login URL.

   In addition to having the correct settings, it must be properly URL encoded. To ease this configuration, use this ADFS RelayState Generator tool. When launched, enter the values below, then hit the Generate URL button.

   • For the IDP URL String, enter https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx

   • For the Relying Party Identifier, enter one of the following values:

     • If configuring Sysdig Monitor, enter https://app.sysdigcloud.com

     • If configuring Sysdig Secure, enter https://secure.sysdig.com

     For other regions, the format is https://<region>.app.sysdig.com. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com/. See SaaS Regions and IP Ranges for more information.

   • For the Relay State/Target App, enter #/&customer=CUSTOMER-ID-NUMBER, substituting the CUSTOMER-ID-NUMBER you retrieved in the previous step

     

     This Results URL will be used in the metadata URL that you paste in the Metadata entry in the SAML connection settings .

4. Use the Results URL from the tool to test your IdP-initiated login. Note that per this Microsoft forum thread, it is apparently not possible to configure ADFS to use such a URL when your users select the application from the pull-down menu at https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx. However, you may embed the URL into a custom portal or bookmarks list.

5. Now you can test login using an Active Directory user that has an Email address configured.

   

Test Metadata (Optional)

To ensure the metadata URL you copy at the end of the IDP configuration procedure is correct, you can test it by directly accessing it via your browser.

When accessing the URL, your browser should immediately download an XML file that begins similarly to the example shown below. No entry of credentials or other security measures should be required to successfully download it. If this is not the case, revisit the IDP configuration steps.

9.2.4 -

Azure Active Directory (SAML)

This topic explains how to configure SAML Single Sign On (SSO) with Azure Active Directory (AD) and helps you configure Sysdig to allow users to access Sysdig application by using SSO.

Prerequisites

Administrator privileges on Sysdig and Azure.

Configure the Sysdig Application in Azure AD

1. Log in to the Azure AD portal.

2. Select Azure Active Directory, then click Enterprise Applications.

   The Enterprise applications - All application screen is displayed.

3. Click New Application.

4. On the Add an Application screen, select Non-gallery application.

5. Give your application a name, and click Add at the bottom of the page.

   

6. On the menu, select Single sign-on.

   

7. Choose SAML as the sign-on method.

8. Edit the Basic SAML Configuration as follows:

   1. In the configuration page, click the edit icon.

      

   2. Specify the following:

      

      • Identifier (Entity ID): Uniquely identifies the Sysdig application. Azure AD sends the identifier to the Sysdig application as the audience parameter of the SAML token. Sysdig validates this as part of the SSO process.

        For example, the identifier for Sysdig Monitor for the EU region is https://eu1.app.sysdig.com.

        See SaaS Regions and IP Ranges for the complete list of entity IDs for different regions.

      • Reply URL: Specifies where Sysdig expects to receive the SAML token.

        For example, the identifier for Sysdig Monitor for the EU region is https://eu1.app.sysdig.com/api/saml/auth.

      • See SaaS Regions and IP Ranges for the complete list of reply URLs for different regions.

      • Relay State: Specifies to the application where to redirect the user after authentication is completed. Typically the value is a valid URL for Sysdig. If you are configuring SSO for SaaS, change the relay state to reflect the correct customer number associated with your Sysdig application. For on-prem installations, the customer number is always 1.

        The format is:

        #/&customer=1234
        

      • Sign on URL: It is the sign-in page for the Sysdig application that will perform the service provider-initiated SSO. Leave it blank if you want to perform identity-provider-initiated SSO.

      For more information on configuration parameters, see Configure SAML-based single sign-on to non-gallery applications.

Sysdig-Specific Steps for Active Directory Configuration

1. Under SAML Signing Certificate, copy the App Federation Metadata URL.

   

2. Log in to your Sysdig instance as an admin.

   For on-prem deployments, log in as the super admin.

3. Navigate to Settings > Authentication, and select SAML under Connection Settings.

4. Enter the following:

   • Metadata: Enter the App Federation Metadata URL you copied.

   • Email Parameter: Set the value to emailaddress.

     Azure AD claims are:

     saml = AD
     givenname = user.givenname
     surname = user.surname
     emailaddress = user.mail
     name = user.userprincipalname
     Unique User Identifier = user.userprincipalname
     

     In the Sysdig application, you need to set the email to emailaddress which is what Azure AD sends to Sysdig in the SAML assertion. Alternatively, Azure AD can be modified to send another attribute.

5. Click Save.

6. Select SAML from the Enable Single Sign On drop-down.

Create a User in Azure Active Directory Domain

1. Log in to the Azure AD portal.

2. Click Azure Active Directory, and note down the domain name.

3. Select Azure Active Directory, then Users.

   The Users - All Users screen is displayed.

4. Select New Users .

   You can either create a new user or invite an existing AD.

5. Enter name, username, and other details, then click Create.

6. In the Profile page, add the Email and Alternate Email parameters. The values can match

Assign the User to the Sysdig Application

1. Navigate to the Sysdig application.

2. Click Users and Group, then click the Add user button.

3. Select the Users and Groups checkbox, then choose the newly created user to add to the application.

4. Click Select, then Assign at the bottom of the screen.

Enable Authentication Settings in the Sysdig Instance

Ensure that Flag to enable/disable create user on login is enabled. Typically this setting is enabled by default.

If you are using both Sysdig Monitor and Secure, ensure that the user accounts are created on both the products. A user that is created only on one Sysdig application will not be able to log in to another by using SAML SSO.

(Optional) Configure Sysdig as a New Application

If Azure Active Directory does not allow you to create Sysdig as a Non- Gallery application, perform the following:

1. In Azure AD, click Enterprise Applications > New Application.

2. Select Application you’re developing.

   

   You will be taken to the app registration page:

3. Select New Registration:

4. Provide a name for the application you are registering.

   

5. Enter the redirect URI.

   For example, the redirect URI for Sysdig Monitor for the EU region is https://eu1.app.sysdig.com/api/saml/auth. See SaaS Regions and IP Ranges for the redirect URLs for other regions.

6. Click Register to complete the registration.

7. In the Overview tab click Add an Application ID URI:

   

8. Click Add a scope.

9. Add the application ID URI as follows:

   https://<your_sysdig_url>:443
   

   Replace <*your_sysdig_*url> with the URL appropriate to your application and region. See SaaS Regions and IP Ranges for more information.

10. In the Overview tab, click Endpoints, and copy the Federation Metadata URL.

11. Log in to Sysdig, navigate to SAML Authentication screen, and enter the Federation Metadata URL.

    You will still need to ensure that the user creation on the login option is enabled.

12. Save the settings.

9.3 -

OpenID Connect (SaaS)

OpenID support in the Sysdig platform allows authentication via your choice of Identity Provider (IdP). This section describes how to integrate and enable OpenID Connect with both Sysdig Monitor and Sysdig Secure.

Overview

Summary of OpenID Functionality in Sysdig

The Sysdig platform ordinarily maintains its own user database to hold a username and password hash. OpenID instead allows for redirection to your organization’s IdP to validate username/password and other policies necessary to grant access to Sysdig application(s). Upon successful authentication via OpenID, a corresponding user record in the Sysdig platform’s user database is automatically created, though the password that was sent to the IdP is never seen nor stored by the Sysdig platform.

Basic Enablement Workflow

Administrator Steps

Configure IdP

Select the appropriate IdP link below, and follow the instructions:

• Okta (OpenID)

• OneLogin (OpenID)

• Keycloak (OpenID)

• Azure (OpenID)

Enable OpenID in Settings

To enable baseline OpenID functionality:

Enter OpenID Basic Connection Settings

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

2. Select Authentication.

3. Select the OpenID tab.

   

4. Enter the relevant parameters (see table below) and click Save.

Enter OpenID Additional Settings (if needed)

In some cases, an OpenID IdP may not support metadata auto-discovery, and additional configuration settings must be entered manually.

In this case:

1. On the OpenID tab, toggle the Metadata Discovery button to OFF to display additional entries on the page.

   

2. Enter the relevant parameters derived from your IdP (see table below) and click Save.

Select OpenID for SSO

1. Select OpenID from the Enabled Single Sign-On dropdown.

2. Click Save Authentication.

3. Repeat entire enablement process for Sysdig Monitor or Sysdig Secure, if you want to enable on both applications.

User Experience

As noted in the Basic Enablement Workflow above, you can offer users three ways to log in with an OpenID configuration:

• They can begin at the Sysdig SaaS URL and click the OpenID button.

  See SaaS Regions and IP Ranges and identify the correct SaaS URL associated with your Sysdig application and region. For example, URLs of Monitor and Secure for US East are:

  Monitor: app.sysdigcloud.com

  Secure: secure.sysdig.com

  For other regions, the format is https://<region>.app.sysdig.com. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com.

  They will be prompted to enter a Company Name, so the Sysdig platform can redirect the browser to your IdP for authentication.

  =

  

• You can provide an alternative URL to avoid the user having to enter a company name, in the format:

  Monitor: https://app.sysdigcloud.com/api/oauth/openid/ CompanyName Secure: https://secure.sysdig.com/api/oauth/openid/ CompanyName?product=SDS

• You can configure an IdP-initiated login flow when configuring your IdP. The users then select the Sysdig application from your IDP’s app directory and do not browse directly to a Sysdig application URL at all.

9.3.1 -

Okta (OpenID)

OpenID Provider Configuration for Okta

Review OpenID Connect (SaaS) before you begin.

The notes below describe minimal steps to be taken in Okta. You may need to adjust the steps based on the specifics of your environment.

1. Log in to your Okta organization as a user with administrative privileges and click to the Admin dashboard

2. Click on the Add Applications shortcut, then click the Create New App button

3. Select Web as the Platform type, then click OpenID Connect as the Sign-on method, then click Create

4. Create a new application:

   • Enter your choice of General Settings.

   • For Login redirect URIs, enter one of the following values:

     See SaaS Regions and IP Ranges and identify the correct domain URL (redirect URL) associated with your Sysdig application and region. For example, domain URLs of Monitor and Secure for US East are:

     • Sysdig Monitor: https://app.sysdigcloud.com/api/oauth/openid/auth

     • Sysdig Secure: https://secure.sysdig.com/api/oauth/openid/secureAuth

     For other regions, the format is https://<region>.app.sysdig.com.

     Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com/api/oauth/openid/auth.

   • Click Save.

5. You should next be placed in a General tab. Take note of the Client ID and Client secret that are shown.

   You will enter them on the OpenID Configuration page in the Sysdig authentication settings.

6. Click to the Sign On tab. Take note of the Issuer URL that is shown, as it will need to be sent to Sysdig Support.

   You will enter it in the OpenID Configuration page in the OpenID settings.

9.3.2 -

OneLogin (OpenID)

OpenID Provider Configuration for OneLogin

Review OpenID Connect (SaaS) before you begin.

The notes below describe minimal steps to be taken in OneLogin. You may need to adjust the steps based on the specifics of your environment.

1. Log in to your OneLogin organization as a user with administrative privileges and click to Apps > Custom Connectors, then click the New Connector button.

2. Create a new Connector:

   • Enter your choice of connector name.

   • Select a Sign on Method of OpenID Connect.

   • For Redirect URI, enter one of the following values:

     See SaaS Regions and IP Ranges and identify the correct domain URL (redirect URL) associated with your Sysdig application and region. For example, domain URLs of Monitor and Secure for US East are:

     • Sysdig Monitor: https://app.sysdigcloud.com/api/oauth/openid/auth

     • Sysdig Secure: https://secure.sysdig.com/api/oauth/openid/secureAuth

     For other regions, the format is https://<region>.app.sysdig.com.

     Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Secure you use https://eu1.sysdig.com/api/oauth/openid/secureAuth.

   • Click Save.

3. From the More Actions pull-down menu, select Add App to Connector

4. Click Save to add the app to your catalog. Once clicked, additional tabs will appear.

5. Click to the SSO tab. Change the setting in the Token Endpoint drop-down to POST, then click Save.

   

6. While still on the SSO tab, take note of the Client ID and Client Secret that are shown (click Show client secret to reveal it).

   You will enter them in the OpenID settings.

7. Note that the Issuer URL will consist of https://YOUR-ONELOGIN-DOMAIN.onelogin.com/oidc

   You will enter them in the OpenID settings.

9.3.3 -

Keycloak (OpenID)

Configure OpenID Provider for Keycloak

Review OpenID Connect (SaaS) before you begin.

The notes below describe minimal steps to be taken in Keycloak. You may need to adjust the steps based on the specifics of your environment.

1. Log in to your Keycloak server’s Administrative Console.

2. Select a realm or create a new one.

3. Click Clients, then click the Create button.

4. Enter the Client ID of your choosing (e.g. “SysdigMonitor”) and take note of it.

   You will enter it in the OpenID Configuration page in the Sysdig Authentication Settings.

5. Make sure the Client Protocol drop-down has openid-connect selected. Click the Save button.

6. Configure OpenID Connect client:

   • Click the toggle for Authorization Enabled to ON

   • For Valid Redirect URI, enter one of the following values:

     See SaaS Regions and IP Ranges and identify the correct domain URL (Redirect URI) associated with your Sysdig application and region. For example, domain URLs of Monitor and Secure for US East are:

     • Sysdig Monitor: https://app.sysdigcloud.com/api/oauth/openid/auth

     • Sysdig Secure: https://secure.sysdig.com/api/oauth/openid/secureAuth

     For other regions, the format is https://<region>.app.sysdig.com.

     Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor you use https://eu1.app.sysdig.com/api/oauth/openid/auth.

   • Click Save .

7. Click to the Credentials tab. Take note of the Secret that is shown.

   You will enter it in the OpenID settings

8. Note that the Issuer URL will consist of https://KEYCLOAK_SERVER_ADDRESS/auth/realms/REALM_NAME, where KEYCLOAK_SERVER_ADDRESS and REALM_NAME are derived from your environment where you just created the configuration. You will enter it in the OpenID settings.

9.3.4 -

Azure (OpenID)

OpenID Connect is a security-token based extension of the OAuth 2.0 authorization protocol to do single sign-on. Azure Active Directory provides an implementation of OpenID Connect (OIDC) protocol and Sysdig supports it for single sign-on and API access to Sysdig application.

Enabling Azure OpenID Connect for single sign-on to Sysdig applications include configuration on the Microsoft Active Directory as well as on the Sysdig application.

Prerequisites

Administrator privileges on Sysdig and Azure Active Directory (AD).

Configuring Sysdig Application in Azure AD

1. Log in to the Azure AD portal.

2. Search for Azure Active Directory and do one of the following:

   • Select your Active Directory service

   • Create a new one.

3. Click App registration > New registration.

4. In the Register an application page, specify the following:

   • Name: Display name to identify your Sysdig application. For example, Sysdig Secure.

   • Supported account types: For Sysdig SaaS, choose Accounts in this organizational directory only (Default Directory only - Single tenant). All user and guest accounts created in your active directory can use Sysdig application and API.

   • Redirect URI: Authenticated Sysdig users are redirected to this URI.

     See SaaS Regions and IP Ranges and identify the correct domain URL associated with your Sysdig application and region. For example, domain URLs of Monitor and Secure for US East are:

     • For Sysdig Secure: https://secure.sysdig.com/api/oauth/openid/secureAuth

     • For Sysdig Monitor: https://app.sysdigcloud.com/api/oauth/openid/auth

     For other regions, the format is:

     https://<region>.app.sysdig.com

     Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor you use https://eu1.app.sysdig.com/api/oauth/openid/auth.

     For on-prem installations, the redirect URI will be deployment-specific.

     You can add only a single redirect URI on this page. Use the Authentication page associated with your application to add additional redirect URIs.

5. Click Register.

6. Add additional redirect URIs.

   1. Select your application from App registration.

   2. Click Authentication from the left navigation.

   3. Add the redirect URIs corresponding to Monitor and Secure.

      

7. Create a Secret for the Sysdig application.

   It is a string that the Sysdig application uses to prove its identity when requesting a token.

   1. Click Certificates & secrets.

      

   2. Under Client Secrets, click New client secret.

   3. Enter a description that identifies the secret and choose an expiration period.

   4. Click Add.

   5. Copy the client secret. You will need the client secret while configuring OpenID Connect SSO on the Sysdig application.

8. Copy the Client ID and OpenID Connect endpoints corresponding to the application that you have created.

   1. Select your application from App registration.

   2. Copy the Application (client) ID.

      You will need the client ID while configuring OpenID Connect SSO on the Sysdig application.

   3. Click Endpoints.

      

   4. Copy the OpenID Connect metadata document and open it in a browser.

   5. Copy the OpenID Connect URI (Issuer URI).

      For example, https://login.microsoftonline.com/5a4b56fc-dceb-4a64-94ff-21e08e5892f5/v2.0

Configure Sysdig Settings

To enable Azure OpenID functionality on the Sysdig application, you need the following:

• Client ID

• Client Secret

• Issuer URL.

See Enable OpenID in Settings to learn how to complete your configuration.

9.4 -

Disable Password Authentication (SaaS)

Sysdig Platform supports disabling password-based authentication on both SaaS and on-prem deployments. As an administrator (super administrator for on-prem), you can use an API to achieve it. This configuration is applicable to those who use single sign-on.

SaaS Deployments

As an administrator, perform the following:

1. Get the Sysdig Platform settings:

   See SaaS Regions and IP Ranges and identify the correct domain URL associated with your Sysdig application and region. For example, for Sysdig Monitor on US East is:

   GET https://app.sysdigcloud.com/api/auth/settings/
   

   For other regions, the format is https://<region>.app.sysdig.com/api/auth/settings. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com/api/auth/settings.

2. Find the ID of the active SSO setup:

   GET https://app.sysdigcloud.com/api/auth/settings/active
   

3. Retrieve the specific settings associated with the SSO setup:

   GET https://app.sysdigcloud.com/api/auth/settings/{id}
   

   The setting is displayed in a JSON file.

4. In the JSON file, change the following from false to true:

   settings/forbidPasswordLogin: True
   

5. Update the setting with a request to the same URL with the same JSON, with the changed parameter. URL depends on the type of deployment.

   PUT https://app.sysdigcloud.com/api/auth/settings/{id}
   

9.5 -

Configure Customized Session Expiration

(For SaaS) When you want inactive sessions to deactivate after a time-out period, you can configure it on the Sysdig application. You can determine how long a user’s browser can be idle after which they will be automatically logged out from the session.

To do so

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

2. Select Authentication.

3. Scroll down and locate the Session Expiration settings.

   

4. Specify the Session Expiration setting:

   1. Enable session expiration by using the Terminate session after inactivity period (in minutes) of slider.

   2. Specify the time-out period in minutes.

   3. Click Save.

10 -

Configure Theme Preference

A theme specifies the visual appearance of the Sysdig applications. Theme Preferences allows you to change the look and feel of the Sysdig applications to match your visual and accessibility requirements. The list of available themes includes Light, Dark, Match OS Preferences.

To configure a theme:

1. Log in to Sysdig Secure or Sysdig Monitor.

2. Navigate to User Menu. Select Theme from the upper right corner of the User Menu, OR click the Settings gear and choose Users.

   

3. Select a desirable theme from the Theme Preferences drop-down.

   

   Match OS Preferences: The theme will be aligned with that of your operating system. For example, if your Desktop theme is Dark, the app theme will also be set to Dark.

   Your OS theme will override the application theme preferences. For example, changing the OS theme to Dark while your application theme preference is Light will automatically switch the application theme to Dark.

11 -

Certificates Management

The Certificates Management module for Sysdig Secure provides a simple interface for administrators to create, upload, update, or delete the certificates that are used for content exported from the Sysdig environment.

Specifically, it:

• Optimizes the secure handling of certificates
• Supports .csr flows
• Provides a UI for certificate management
• Adds support for client-side certificates in the events forwarder

At this time, the feature is for Sysdig Secure SaaS only, and is integrated with the appropriate event forwarding options:

• Splunk
• Syslog
• Webhook

(Note: Kafka authentication is handled through a different mechanism.)

Access the Certificates Management Page

1. Log in to Sysdig Secure as admin and navigate to Settings from your user profile.

2. Select Certificates Management.

   

Create a Certificate

Certificate creation requires several steps, defined below.

Thereafter, you can assign the certificate to the event forwarding integrations.

Generate a CA-Signed Key and Cert

You must have a signed key and certificate from a Certificate Authority (CA), a step that your organization may already have done. If not, follow these steps:

1. Generate the CA key:

   openssl genrsa -out ca.key 4096
   

2. Generate the CA certificate, setting the expiration to 10 years from now:

   openssl req -x509 -new -nodes -key ca.key -sha256 -days 1825 -out ca.pem
   

You will be prompted to provide details to populate the certificate information. Be as thorough as possible. Save the resulting ca.pem file.

Obtain the Certificate Signing Request (CSR)

The Certificates Management UI streamlines the process of obtaining a certificate-signing request (CSR).

1. Log in to Sysdig Secure as admin and select Settings > Certificates Management.

2. Select New CSR and copy the text using the Copy and Next button.

   

   You will be prompted to leave the Sysdig UI to finish generating the certificate in an external tool.

Generate the .crt Certificate File Externally

Use a 3rd-party tool, such as OpenSSL or Digicert, to generate the .crt file. Follow the instructions given with that tool, using the CSR you generated.

Upload the .crt in the Sysdig UI

1. Return to the Certificates Management page in the Sysdig Secure Settings and either click Next in the popup window or select Upload Certificate.

   

2. Assign the certificate a meaningful name.

3. Click Upload and Create.

   The certificate will appear in the certificates list and can be applied as needed.

Apply Certificate to Event Forwarding

1. Log in to Sysdig Secure as admin and select Settings > Event Forwarding.

2. Choose an existing or new integration for Splunk, Syslog, or Webhook.

   

3. Select the correct uploaded certificate from the Certificate field and Save.

Manage Certificate Use

Check Where Certs Are Used

Remove a Certificate

Update a Certificate

12 -

Configure Login Message

Use this setting to create a customized login banner to help your organization comply with its security standards.

To create a custom banner:

1. Navigate to Settings > Login Message from Sysdig Monitor or Sysdig Secure.

   

2. Enter your desired message text, using Markdown to format.

3. Click Preview to review. Click Save.

4. Log out and log back in to see the message displayed.