Automations

Automations are created by configuring an Event Filter in SD Elements with one or more Action Plans.

For step-by-step examples of Automations, see Automations use cases

Each Event Filter can be configured to watch for a certain Event that satisfies some criteria. Some examples of such Events are verification scans, Countermeasure status changes, and new project creation. When one of these Events occurs, an automation might then execute an Action, like adding a note to a Countermeasure, or sending an email notification.

Not all Actions are useful with all Events. For example, a "Modify Countermeasure status" Action is not applicable to a "Project was created" Event as no Countermeasures exist in a brand new project.

You can manage Automations through either the API or the UI. In the UI, the Automations page can be accessed through the gear icon menu.

automations list page
500

User permissions

To create and edit Automations, a user needs permissions for:

  • Automations → Create and edit automations

Security context

Automations run as "SD Elements Service-Bot", not the user that created the Automation. Service-Bot is an account used for scheduled issue tracker syncs and security tool imports, as well as Automations. The account has full access to all data in an instance. Be aware that if a user has the Automations permission, that user indirectly has access to perform Actions with full administrative access.

What are Events?

Events are specific outcomes that occur in SD Elements with predefined criteria. Events are used to trigger Actions, or automated responses. For example, when the Event of a SAST code scanner running and importing results into SD Elements with zero high and zero critical findings occurs, SD Elements can automatically fulfill the Action of marking the relevant Countermeasure as 'Complete'.

What are Actions?

Actions are specific tasks that are performed based on predefined criteria. Actions can be carried out automatically based on how they are defined.

automations supported workflow

What are placeholders?

Placeholders are variable strings that can be used in Actions. They are replaced with real values from the Event when it is executed.

Each Event defines a set of placeholders that are available to use in the Actions. Refer to the section on a specific Event to see what placeholders it provides.

Example:

An Event Filter using the "Project Created" Event provides the placeholder ${project_name} amongst others. An email notification is added with the following subject.

"subject": "New project: ${project_name} created"

When a user creates a new project called "Mobile App", configured recipients will receive an email with the subject line: "New project: Mobile App created"

Available placeholders

Placeholders for: project created, project survey locked

Placeholder

Description

${application_name}

The name of the project’s parent application.

${business_unit_name}

The name of the project’s parent business unit.

${project_members}

A string of comma-separated email addresses of members of the project.

${project_name}

The name of the project.

${survey_url}

A URL that links to the survey page for the project.

Placeholders for: Verification tool ran

Placeholder

Description

${scanner_name}

The name of the scanner tool if available.

${scan_results_url}

The URL to scan results if available.

${scan_details}

The metadata information reported by the scanning tool with details of the scan. It has the following template:

Scanner category: <scanner category>
Reference: <analysis scan reference>
Normalized findings:
  <category>:
    <severity: <count>
    <severity: <count>
Time of scan: <time of scan>

Details

Events and Actions are described with the following details:

  • Description: An explanation of the Event or Action.

  • Criteria: A list of all parameters that can be accepted by the Event or Action. This is indicated by the parameter’s label in the user interface and its API key (Label / API Key).

  • Placeholders: A list of all placeholders that can be accepted by the Event or Action.

  • Notes: Important information particular to an Event or Action.

Events for Automations

Project Created

Represents an Event where a project was created.

Criteria

Description

Placeholders

Notes

Application / application_id (Optional)

The application in which the new project was created.

  • ${application_name}

  • ${business_unit_name}

  • ${project_members}

  • ${project_name}

  • ${survey_url}

Should not be combined with TransitionTaskStatus.

Business Unit / business_unit_id (Optional)

The business unit in which the new project was created.

Project Survey Locked

Represents an Event where a project survey was locked.

Criteria

Description

Placeholders

Notes

Application / application_id (Optional)

The application in which a project’s survey was locked.

  • ${application_name}

  • ${business_unit_name}

  • ${project_members}

  • ${project_name}

  • ${survey_url}

None.

Business Unit / business_unit_id (Optional)

The business unit in which a project’s survey was locked.

Countermeasure Status Changed

Represents an Event where a Countermeasure’s status was modified.

A Countermeasure Status Changed event has either:

  1. Occurred

  2. Not occurred over a time period

Criteria shared by Occurred and Has Not Occurred events

Criteria

Description

Placeholders

Notes

Countermeasure / countermeasure (Optional)

The Countermeasure that had its status changed.

None.

None.

Countermeasure Status / status (Optional)

The status that the Countermeasure transitioned to.

  • TS1: Complete

  • TS2: Incomplete

  • TS3: Not Applicable.

  • Custom statuses are supported

Criteria unique to Has Not Occurred events

Countermeasure Status Changed Events that are marked as having not occurred over a time period require a threshold.

Verification tool ran

Represents an Event where a verification integration process was run. This event occurs when you import scan results through a manual upload or a remote connection sync.

A Verification tool ran event has either:

  1. Occurred

  2. Not occurred over a time period

Criteria shared by Occurred and Has Not Occurred events

Criteria

Description

Placeholders

Notes

vulnerability_report (Optional)

  • ${scanner_name}

  • ${scan_results_url}

  • ${scan_details}

The criteria for this Event must be in JSON for both the UI and the API. Provide the criteria in this format:

    {
        "vulnerability_report": {
            "<scanner category>": {
                "<severity>": <max allowable>,
                ...
            }
        }
    }

  • categories: DAST, IAST, INFRASTRUCTURE, MANUAL, SAST, SCA

  • severities: critical, high, medium, low, info, unknown

    • This example will match scans that return a SAST result with no critical findings.

    {
        "vulnerability_report": {
            "SAST": {
                "critical": 0
            }
        }
    }

category (Optional)

Used only if the "has not occurred over a time period" option is selected.

severity_counts (Optional)

Criteria unique to Has Not Occurred events

Verification tool ran Events that are marked as having not occurred over a time period require a threshold.

User Login

Represents an Event where a user logs into SDE. The User Login Event tracks if a user login has either:

  1. Occurred

  2. Not occurred over a time period

Criteria shared by Occurred and Has Not Occurred events

Criteria

Description

Placeholders

Notes

Members: All Users <→ Select Users all_users_option

This toggle allows you to choose between including all users/global roles or selecting specific set users/global roles.

None

Members all_users_option will alter the other criteria to either exclude (if true) or include (if false)parameters within the event

emails will be listed as a string of email addresses and global_role will be listed as a string of global role ID’s

    {
    "criteria": {
        "all_users_option": true,
        "emails": "admin@example.com"
        "global_roles": "UR1"
            }
        }
    }

Response return provides additional details under emails and global_role parameters

    {
    "criteria": {
        "emails": [
            {
                "email": "admin@example.com",
                "label": "admin@example.com"
            }
        ],
        "global_roles": [
            {
                "label": "User",
                "value": "UR1"
            }
        ],
        "all_users_option": True
            }
        }
    }

Exclude/Include Filters:

  1. Users / emails

  2. Global Roles / global_roles

The users that exist within SD Elements that will either be excluded or included in the event.

Criteria unique to Has Not Occurred events

User Login Events that are marked as having not occurred over a time period include the same criteria above, but require a threshold.

Actions for Automations

Transition Countermeasure Status

Action that transitions a Countermeasure to a specific status.

Criteria

Description

Placeholders

Countermeasure / task_id

The Countermeasure to automatically transition.

  • TS1: Complete

  • TS2: Incomplete

  • TS3: Not Applicable.

  • Custom statuses are supported

None.

Status / status_id

The status to automatically transition a Countermeasure to.

None.

Add note / note_enabled

A flag that enables a note to be added to a Countermeasure after a successful transition. Defaults to 'true'.

All

Note / note (Optional)

Custom text to use for the note that is added to the Countermeasure after a successful transition. If left empty, it uses the default message: "Countermeasure status automatically transitioned to <new status>."

All

Add Countermeasure Note

Action that adds a note to a Countermeasure.

Criteria

Description

Placeholders

Countermeasure / task_id

The Countermeasure to receive the note.

None.

Note / note

The text to appear in the note. Has access to placeholders.

None.

Send Email Notification

Action that sends an email to a list of recipients.

Criteria

Description

Placeholders

Recipients / recipients

The list of email addresses the email is sent to.

${project_members}

Subject / subject

Subject line of the email.

All

Message / body

Body of the email.

All

Deactivate a User

Action that will automatically deactivate a user by setting that user’s status to "inactive".

Limits and restrictions

  • The Project Created Event can perform only Send Email Notification as an Action.

  • If an event of the type being configured in the automation wizard has never occurred, automation will be unable to complete that event.

  • The option has occurred* has a slightly different criteria format from the option has not occurred over a time period**.

    • Selecting the option has not occurred over a time period requires you to indicate a time period in days, such as 30 days.

  • The number of Recipients is limited to 100. If it expands to over 100 because of the project_members placeholder, it will fail.

  • You can save an Event without an Action, but it will not perform anything.

  • The Deactivate a User action is only found under the User Login Event

    • It can only be used if the option has not occured over a time period is selected

    • If you have created event with this action and switch over to "has occurred", it will reset all actions

    • You can only select this action once within the event

Threshold

Some Events support Threshold criteria. Threshold criteria are configured to perform Actions when the chosen Event has not occurred for some period of time.

For example, you can configure a 14-day Threshold on a Verification tool ran Event, and add a Send email notification Action. At the end of the first sprint, someone runs a Verification scan on the project. If, after 14 days, no one runs a Verification scan on this project again, an email will be sent to the recipients configured in the Action.

When does a notification email send with a 14-day Threshold?

Condition 1: A Threshold of 14 days passes (1 sprint)

Condition 2: No Verification scan has run since the last scan

Days passed

Verification tool ran Event

Email Action

<14

Has not run

Not sent

<14

Has run

Not sent

14

Has run

Not sent

14

Has not run

Sent

In this example, the email notification will only send once both conditions are satisfied.

Threshold configuration

Threshold criteria must be configured as its own automation. To do this, create a separate Automation using Verification tool ran to detect actual Verification scans.

A user can set additional criteria on Threshold Events, such as scanner categories or findings. This additional criteria allows a user to create an Automation to set a specific process Countermeasure, "T1368: Perform security testing using SAST tools", to 'Incomplete' if a SAST scan with no critical findings has not occurred in a set period of time. For more information about process Countermeasures, see Process Countermeasures.

Threshold limitations

The date and time of the last matching Event is used to determine whether a Threshold is crossed. One limitation of configuring findings in the criteria is that if all past scans had findings that exceeded the criteria settings, then there is no last matching Event to use in checking the Threshold. In these cases, the Threshold Event will never perform its Actions until at least one matching Event has occurred.

For instance, if you want to be notified if 6 months have passed since there was a scan with zero critical findings, the Threshold will never trigger if you never have a scan with no critical findings.

The Threshold looks for a scan with zero critical findings, and then sees how long ago that was. With no initial successful scan, the feature has no Event or date to use as a baseline to determine if the Event occurred beyond the Threshold time. If there is no starting line, it can never start.

Process Countermeasures and Activities

For more details about Process Countermeasures and Activities, please see Process Countermeasures.

results matching ""

    No results matching ""