Automations (Beta)

The Automations feature is currently in Beta.

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

Tip
 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, task 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 task, or sending an email notification.

Not all Actions are useful with all Events. For example, a "Modify task status" Action is not applicable to a "Project was created" Event as no tasks 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 [settings] menu.

automations list page.png
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 task 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.png

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.

Task Status Changed

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

A Task Status Changed event has either:

  1. Occurred over a time period

  2. Not occurred over a time period

1. Has occurred over a time period

Criteria

Description

Placeholders

Notes

Task / task (Optional)

The task that had its status changed.

None.

None.

Task Status / status (Optional)

The status that the task transitioned to.

  • TS1: Complete

  • TS2: Incomplete

  • TS3: Not Applicable.

  • Custom statuses are supported

2. Has not occurred over a time period

Task 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 over a time period

  2. Not occurred over a time period

1. Has occurred over a time period

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)

2. Has not occurred over a time period

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

Actions for Automations

Transition Task Status

Action that transitions a task to a specific status.

Criteria

Description

Placeholders

Task / task_id

The task to automatically transition.

  • TS1: Complete

  • TS2: Incomplete

  • TS3: Not Applicable.

  • Custom statuses are supported

None.

Status / status_id

The status to automatically transition a task to.

None.

Add note / note_enabled

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

All

Note / note (Optional)

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

All

Add Task Note

Action that adds a note to a task.

Criteria

Description

Placeholders

Task / task_id

The task 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

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 over a time period 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.

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 task, "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 tasks, see Process Tasks.

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 Tasks and Activities

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

results matching ""

    No results matching ""