Flows

Overview

The Flows module is a comprehensive, end-to-end cloud automation engine powered by AFScript.

Flows can help you to automate AttackForge with nearly unlimited systems. You can streamline processes across your organization to save time and focus on what's important.

Some examples you can do with Flows:

• Integrate your vulnerability data with ticketing tools like Atlassian JIRA, ServiceNow, Azure DevOps, BMC Helix and others.

• Visualize your pentesting data in powerful tools like Power BI and Tableau

• Help make better risk decisions by sending your vulnerability data to GRC platforms like RSA Archer, MetricStream, OneTrust and LogicGate.

• Trigger automated scanning activities in your security toolset.

• Create messages on collaboration platforms like Slack and Teams.

• Prioritize vulnerabilities with threat-informed custom risk scoring.

• Create custom webhooks.

• Send custom email notifications on events.

Getting Access to Flows

Flows is included in all AttackForge Enterprise plans, and in the AttackForge Core SME plan. For all others plans, Flows can be add-on from the Administration -> Subscriptions page.

To get started with building a Flow:

• You must have access to at least one (1) Event; or

• You must be granted access to another person's existing Flow

Flow Overview

A Flow is comprised of the following:

• Name - the name of the Flow.

• Event Trigger - the trigger which initiates a Run.

• Actions - a sequence of steps which are executed in order during a Run.

• Secrets - any piece of sensitive information that needs to be kept confidential, such as passwords and API keys.

Run Overview

A Run refers to a single execution of a Flow, meaning when a set of actions defined in your Flow is triggered and carried out from start to finish, that is considered one "Run" of the flow; essentially, it's a single instance of your Flow being executed.

Key points about a Run:

• Triggered by an Event - A Run is initiated by a Trigger, like a new vulnerability or an update to a project, or a manual action.

• Trackable status - You can monitor the status of a Run, including whether it succeeded, failed, or is currently running.

• Provides details - Each Run has details like start time, duration, and the specific Actions taken within the Flow.

IMPORTANT: A normal Run will only be executed in the context of the Flow Owner and related Event Trigger. For example, if the Event Trigger was "vulnerability-created" - the Run will only initiate for the vulnerability for which the Flow Owner has access to the vulnerability. Test runs can be manually executed with test data at any time.

Sharing Flows with Teams

When a Flow is created, it belongs to the user who created the Flow (the Flow Owner). Flow Owners cannot be changed (for the time being).

Only Flow Owners are allowed to share their Flows with other users.

To share your Flow:

• Open your Flow and click on the Settings button

• Click on Add Access

• Insert the user's email address or look up and select the user

Once a user has been given access to a Flow, they will be able to do the following:

• Manually run the Flow

• Edit the Flow, including changing Name, Event Trigger, Actions and Secrets

• Enable/Disable the Flow

• View Run history and individual Runs, including Re-run

• Export the Flow

You can remove a users' access to your Flows from the Settings.

Triggers

A Trigger is an action which initiates a Run. Triggers can be initiated from Events or manually initiated.

The following Triggers are currently supported:

• Project Created

• Project Updated

• Project Request Created

• Project Request Updated

• Project Retest Requested

• Project Retest Completed

• Project Retest Cancelled

• Vulnerability Created

• Vulnerability Updated

• Vulnerability Remediation Note Created

• Vulnerability Remediation Note Updated

• Vulnerability Evidence Created

• Vulnerability Evidence Updated

A Flow can be assigned to only one Trigger.

Triggers can be assigned to a Flow when either creating or editing the Flow.

COMING SOON! Ability to create your own custom Triggers which are invoked from custom URLs. This will allow you to execute a Flow on-demand whenever you would need it to run, and also allow for creating custom webhook receivers for your security toolsets and systems to communicate back to AttackForge.

Secrets

Secrets are any piece of sensitive information that needs to be kept confidential, such as passwords and API keys.

You can create Secrets which belong to the Flow. Only users with access to the Flow would be able to view the associated Secrets.

To create a Secret, start by clicking on the Secrets button when creating or editing a Flow.

From here, you can see and manage all of the existing Secrets associated to the Flow.

Click on Add Secret to create a new Secret and enter a Key and a Value. Note the Key must be letters, numbers and underscores only.

You can also view, manage and create secrets in the Request Script and in the Response Script:

NOTE: Secrets are stored encrypted in the database.

COMING SOON: You will be able to create User Secrets which belong to the user and are managed in one place. This makes is easy to rotate passwords and credentials without having to update the Flows.

There are two (2) ways in which you can refer to your Secrets in your Flow:

1. Select the Secret directly in the Headers

2. Refer to the Secret in the Request Script or Response Script

Secrets in Headers

When creating or modifying Headers within the Action, you can select 'Secret' for the header type. This will then allow you to select from an existing Secret, or create a new Secret.

Secrets in Request/Response Scripts

When creating or modifying the Request Script or the Response Script, you can refer to secrets using the following syntax:

secrets.<KEY>

Where <KEY> is replaced with the Key associated with the Secret.

IMPORTANT: Make sure to select Use Secrets to ensure your secrets are used in your script.

Actions

Actions are either one activity, or a sequence of activities, which are executed in order during a Run.

For example, if the use case for your Flow is:

• to create a JIRA Issue every time a Vulnerability is created

You may choose to include two (2) Actions in your Flow:

• Action 1 - Create JIRA Issue

  • This involves formatting the vulnerability into the necessary JIRA Create Issue API format, and making a HTTPS request to the JIRA API to create the issue.

• Action 2 - Update Vulnerability with JIRA Issue Key

  • This involves making a HTTPS request to the Update Vulnerability Self-Service API to set the JIRA Issue Key custom field.

The primary purpose of an Action is to make an update to a system. The system could be AttackForge (via the Self-Service APIs) or an external system.

Every Action is made up of a Request and a Response.

• The Request is the HTTP request which is made by the Action.

• The Response is the HTTP response from the server which received the HTTP request.

Every Action is made up of the following components:

• Method - this is the HTTP method i.e. GET, POST, PUT, etc. that will be used for the Request

• URL - this is the URL that will be used for the Request.

• Verify Certificate - this determines whether to verify if the TLS certificate is valid for the URL.

• Headers - these are the headers that will be sent when the Request is made.

• Request Script - this is the script which will execute before the Request is made.

• Response Script - this is the script which will execute after the Response is returned.

IMPORTANT: When more than one Action is included in a Flow, the output of an Action will become the input into the next Action.

Methods

Methods are the HTTP methods/verbs that will be used for the Request i.e. GET, POST, PUT, etc.

The following methods are supported:

• GET

• POST

• PUT

• PATCH

• DELETE

Methods can be selected when editing the Action:

Methods can also be programatically set in your Request Script in the Return Statement:

return {
    decision: { 
        status: 'continue'
    },
    request: {
        url: url,
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': secrets.jira_auth
        },
        body: {
            fields: {
                summary: summary,
                description: description,
                priority: {
                    name: priority
                },
                issuetype: {
                    name: 'Bug'
                },
                labels: labels
            }
        }
    }
};

URL

The URL is the web address that will be used for the Request, for example https://acmecorp.atlassian.net/rest/api/2/issue

The URL can be entered in when editing the Action:

The URL can also be programatically set in your Request Script in the Return Statement. This is useful if your URL has a dynamic component which needs to be computed:

const url = 'https://demo.attackforge.com/api/ss/vulnerability/' + data.vulnerability_id;

return {
    decision: { 
        status: 'continue'
    },
    request: {
        url: url,
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json',
            'x-ssapi-key': secrets.af_auth
        },
        body: {
            project_id: project_id,
            custom_fields: [
                {
                    key: 'jira_issue_key',
                    value: jira_issue_key
                }
            ]
        }
    }
};

Headers

The Headers are the HTTP headers that will be sent when the Request is made.

The Headers can be manually entered in when editing the Action:

The Headers can also be programatically set in your Request Script in the Return Statement. This is useful if your Headers have a dynamic component which needs to be computed:

const customHeaderName = 'X_CUSTOM_HEADER_' + customHeader;
const customHeaderValue = customValue;

return {
    decision: { 
        status: 'continue'
    },
    request: {
        url: url,
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            customHeaderName: customHeaderValue,
            'Authorization': secrets.custom_auth
        },
        body: {
            super_secret_something: "..."
        }
    }
};

Request

The Request is a HTTP/HTTPS request to a web address.

The Request is made up of the following components:

• URL

• Method

• Headers

• Body - an optional HTTP body. This is typically required for POST, PUT and PATCH HTTP requests.

• Request Script

IMPORTANT: Requests can be made over both HTTP and HTTPS.

Response

The Response is the HTTP server response to a Request.

The Response is made of the of the following components:

• Response Object

• Response Script

Request Script

The Request Script is the script which will execute before the Request is made.

The Request Script is made up of the following components:

• Code

• Data

• Return Statement

Response Script

The Response Script is the script which will execute after the Response is returned.

The Request Script is made up of the following components:

• Code

• Data

• Return Statement

Code

Flows support AFScript - a powerful interpreted programming language created by AttackForge.

This makes it possible to write logic to help you handle all various use cases for how you want your Flows to work.

You can take advantage of Logging in AFScript to help you to debug and test your code.

You can test and debug your code using the Run option:

If your code fails after running it, you will see an error message with the relevant stack trace:

Data

Data is contextually relevent information for your Request Script and Response Script.

You can reference the information included within Data as follows:

data.<KEY>

Where <KEY> is replaced with the associated key on the Data Object.

For more information on Data, please see Data Object.

The Data Object

Data is contextually relevant information for your Request Script and Response Script.

The Data Object is an Object that holds the Data.

The first Action in your Flow will contain Data in the Request Script which is relevent to your Trigger Event. For example, if your Flow was assigned to the "vulnerability-created" Event, then your Data Object will contain all of the information relating to the vulnerability.

However from this point forward, you can control how you would like your Data Object to look for the Response Script and any subsequent Actions going forward.

In the following example, we can see that Data Object has vulnerability-related information due to the "vulnerability-created" Event.

You can refer to keys on the Data Object using the following syntax:

data.<KEY>

Using the example above, if you wanted to store the vulnerability Id in a constant, you could do the following:

const vuln_id = data.vulnerability_id;

Keeping with the example above, if you wanted to extract the project Id for the vulnerability, you could do the following:

let project_id = undefined;

if (data.vulnerability_projects) {
    for (let x = 0; x < data.vulnerability_projects.length; x++) {
        if (data.vulnerability_projects[x].id) {
            project_id = data.vulnerability_projects[x].id;
        }
    }
}

If you needed to pass this information to the next step of this Flow, which using the example above will be the Response Script on the first Action - you can include the "data" key in your Response Object and pass in an Object with key/value pairs as follows:

return {
    decision: { 
        status: 'continue'
    },
    data: {
        af_project_id: project_id,
        af_vuln_id: vuln_id,
        af_vuln: data
    }
}
   

Continuing with this example, the Response Script will now have the following Data Object:

data = {
    af_project_id: "...",
    af_vuln_id: "...",
    af_vuln: {
        "vulnerability_title": "...",
        ...
    }
}

When viewing the details of a Run - you can see what Data was passed as input and output into an Action.

If you would need to log the Data Object for visibility or debugging during execution of a Run you can do the following:

Logger.debug('Data:');
Logger.debug(JSON.stringify(data));

You can then view the details in the Run Logs

The Response Object

The Response Object is the HTTP information which is sent back from the server during the Response.

The Response Object is available in the Response Script.

The Response Object is made up of the following:

• HTTP Response Status Code

• HTTP Response Headers

• HTTP Response Body

You can refer to keys on the Response Object using the following syntax:

response.<KEY>

An example of the Response Object:

response = {
    "statusCode": 200,
    "headers": {},
    "body": ""
}

• The statusCode will be accessible as a Number.

• The headers will be accessible as a Object.

• The body will be accessible as a String.

If you are expecting the body to be returned as a JSON payload (which is common for RESTful APIs) - you must first parse the body into JSON format before you can access it using dot or bracket notation, see example below:

const body = JSON.parse(response.body);

When viewing the details of a Run - you can see the Response Status Code and Body:

If you would need to log the Response Object for visibility or debugging during execution of a Run you can do the following:

Logger.debug('Response:');
Logger.debug(JSON.stringify(response));

You can then view the details in the Run Logs

The Return Statement

Runs

Manually Run Flow

Run Logs

Re-Run

Importing/Exporting Flows

Examples

The following examples can help you to automate and integrate with common security and enterprise tools. Each example includes a Flow which can be imported in to your own AttackForge to help you get started fast!

NOTE: These are just some common examples so far. We are constantly adding more Flow examples as we continue to roll out Flows. Remember - Flows can interact with any HTTP interface, including AttackForge Self-Service API and any other external systems! Unleash your imagination and creativity 😄

Create JIRA Issue

Update JIRA Issue

Create ServiceNow Incident

Create Azure DevOps Work Item

Create Slack Message

Create Teams Message

Add Threat-Informed Prioritization & Custom Score Vulnerability

Send Custom Email