# Flows
## Overview
Flows is a comprehensive, end-to-end workflow automation engine powered by [AFScript](https://support.attackforge.com/attackforge-enterprise/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:
* Create bespoke workflows - QA, risk management, reporting, bi-directional integrations, and more.
* Prioritize vulnerabilities with full context, including threat-intelligence like [VulnDB](https://flashpoint.io/ignite/vulnerability-intelligence/)
* Integrate your vulnerability data with ticketing tools like [Atlassian JIRA](https://www.atlassian.com/software/jira), [ServiceNow](https://www.servicenow.com/), [Azure DevOps](https://azure.microsoft.com/en-us/products/devops), [BMC Helix](https://www.bmc.com/it-solutions/bmc-helix.html) and others.
* Visualize your pentesting data in powerful tools like [Power BI](https://www.microsoft.com/en-us/power-platform/products/power-bi) and [Tableau](https://www.tableau.com/)
* Integrate your Bug Bounty and VDP data from platforms like [HackerOne](https://hackerone.com/) and [BugCrowd](https://www.bugcrowd.com/)
* Help make better risk decisions by sending your vulnerability data to GRC platforms like [RSA Archer](https://www.archerirm.com/), [MetricStream](https://www.metricstream.com/), [OneTrust](https://www.onetrust.com/) and [LogicGate](https://www.logicgate.com/).
* Create workflow automations by chaining together [AttackForge Self-Service APIs](https://support.attackforge.com/attackforge-enterprise/modules/self-service-restful-api)
* Trigger automated scanning activities in your security toolset like [Rapid7](https://www.rapid7.com/), [Tenable](https://www.tenable.com/) and [Qualys](https://www.qualys.com/).
* Create messages on collaboration platforms like [Slack](https://slack.com/intl/en-au/) and [Teams](https://www.microsoft.com/en-au/microsoft-teams/group-chat-software).
* Create custom webhooks.
* Send custom email notifications on events.
{% embed url="" %}
## 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 **Create** access to [Event Triggers](#internal-events), [HTTP Triggers](#external-events), [Schedule Triggers](#scheduled-events) or [Action Triggers](#action-events)
As an Administrator, go to `Users > (Select User) > Access > Flows` and enable access to the desired triggers.
### Event Trigger Access Level
* **None** - user is unable to create or import flows with the [Event Trigger](#internal-events) type. Any existing Event Trigger flows for which they are the owner of will also not run.
* **Run** - user is able to trigger flows with the [Event Trigger](#internal-events) type they are the owner of, so long as the flow is enabled and they have access to the matching [event type](#internal-events).
* **Create** - user is able to create or import flows with the [Event Trigger](#internal-events) type. Any existing Event Trigger flows for which they are the owner of will run so long as the flow is enabled and the user has access to the matching [event type](#internal-events).
### HTTP Trigger - Authentication (None) Access Level
HTTP Triggers can be [configured with no authentication](#http-trigger-authentication). This means that the flow will not check for authentication before the flow runs.
* **None** - user is unable to create or import flows with the non-authenticated [HTTP Trigger](#external-events) type. Any existing non-authenticated HTTP Trigger flows for which they are the owner of will also not run.
* **Run** - user is able to trigger flows with the non-authenticated [HTTP Trigger](#external-events) type they are the owner of, so long as the flow is enabled.
* **Create** - user is able to create or import flows with the non-authenticated [HTTP Trigger](#external-events) type. Any existing non-authenticated HTTP Trigger flows for which they are the owner of will run so long as the flow is enabled.
### HTTP Trigger - Authentication (User API Key) Access Level
HTTP Triggers can be [configured with authentication](#http-trigger-authentication). This means that the flow will check for authentication before the flow runs.
* **None** - user is unable to create or import flows with the authenticated [HTTP Trigger](#external-events) type. Any existing authenticated HTTP Trigger flows for which they are the owner of will also not run.
* **Run** - user is able to trigger flows with the authenticated [HTTP Trigger](#external-events) type they are the owner of, so long as the flow is enabled and an authorized [User Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-api-key) is supplied in the nominated header.
* **Create** - user is able to create or import flows with the authenticated [HTTP Trigger](#external-events) type. Any existing authenticated HTTP Trigger flows for which they are the owner of will run so long as the flow is enabled and an authorized [User Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-api-key) is supplied in the nominated header.
### Schedule Trigger
* **None** - user is unable to create or import flows with the [Schedule Trigger](#scheduled-events) type. Any existing Schedule Trigger flows for which they are the owner of will also not run.
* **Run** - user is able to trigger flows with the [Schedule Trigger](#scheduled-events) type they are the owner of, so long as the flow is enabled.
* **Create** - user is able to create or import flows with the [Schedule Trigger](#scheduled-events) type. Any existing Schedule Trigger flows for which they are the owner of will run so long as the flow is enabled.
### Action Trigger
* **None** - user is unable to create or import flows with the [Action Trigger](#action-events) type. Any existing Action Trigger flows for which they are the owner of will also not run.
* **Run** - user is able to trigger flows with the [Action Trigger](#action-events) type they are the owner of, so long as the flow is enabled.
* **Create** - user is able to create or import flows with the [Action Trigger](#action-events) type. Any existing Action Trigger flows for which they are the owner of will run so long as the flow is enabled.
## Flow Overview
A Flow is comprised of the following:
* **Name** - the name of the Flow.
* [**Trigger**](#triggers) - the trigger which initiates a [Run](#run-overview).
* [**Actions**](#actions) - a sequence of steps which are executed in order during a [Run](#run-overview).
* [**Secrets**](#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 a Trigger -** A Run is initiated by a [Trigger](#triggers), 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](#actions) taken within the Flow.
> **IMPORTANT:** A normal Run will only be executed in the context of the [Flow Owner](#sharing-flows-with-teams) and related [Trigger](#triggers). For example, if the [Trigger](#triggers) was "vulnerability-created" - the Run will only initiate for the vulnerability for which the [Flow Owner](#sharing-flows-with-teams) 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 can be [transferred](#transferring-flows) however a Flow can only ever run under the context of a single user.
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 if permitted, look up and select the user. Assign an access level to the flow.
### Access Levels
* **None** - the user explicitly does not have access to the flow.
* **Info** - the user is able to view basic information about the flow, including:
* Name of the flow
* Current status, last run, trigger, enabled/disabled
* Flow owner
* Readme
* If [HTTP Trigger](#external-events) - HTTP Method, Trigger URL, Trigger Id
* **View** - the user is able to access read-only information for the flow, including:
* Name of the flow
* Current status, last run, trigger, enabled/disabled
* Flow owner
* Readme
* If [HTTP Trigger](#external-events) - HTTP Method, Trigger URL, Trigger Id
* View all [Runs](#runs)
* View all [Actions](#actions)
* View [Run details](#run-logs) and logs
* [Export](#importing-exporting-flows) the flow
* **Edit** - the user is able to modify the flow, including:
* Name of the flow
* Current status, last run, trigger, enabled/disabled
* Flow owner
* Readme
* If [HTTP Trigger](#external-events) - HTTP Method, Trigger URL, Trigger Id
* View all [Runs](#runs)
* View all [Actions](#actions)
* View [Run details](#run-logs) and logs
* Edit the flow
* Save and Run the flow
* [Export](#importing-exporting-flows) the flow
* Disable the flow
### Trigger Access
Trigger access is used for controlling authentication to triggering a [Flow Run](#runs) using authenticated [HTTP Triggers](#external-events) based on the [User Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-api-key) supplied in the nominated header.
* **No** - user is not able to trigger the flow.
* **Yes** - user is able to trigger the flow provided they enter their valid [User Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-api-key) into the flows' nominated authentication header.
> **IMPORTANT:** Administrators have implicit permissions to view access for all flows.
## Triggers
A Trigger is an action which initiates a [Run](#run-overview). Triggers can be initiated from [Events](https://support.attackforge.com/attackforge-enterprise/modules/self-service-events-api) or manually initiated.
### Internal Events
Internal Events (or Event Triggers) are events which occur when something *inside* AttackForge changes.
The following Internal Events are currently supported:
* Project Created
* Project Updated
* Project Request Created
* Project Request Updated
* Project Retest Requested
* Project Retest Completed
* Project Retest Cancelled
* Project Reporting Updated
* Project Reporting File Uploaded
* Project Summary Updated
* Project Summary File Uploaded
* Project Test Case Updated
* Project Workspace File Uploaded
* Vulnerability Created
* Vulnerability Updated
* Vulnerability Remediation Note Created
* Vulnerability Remediation Note Updated
* Vulnerability Evidence Created
* Vulnerability Evidence Updated
* Writeup Created
* Writeup Updated
Access to events can be granted by Administrators in [`Users > (Select User) > Access > Events (Flows / Self Service API)`](https://support.attackforge.com/attackforge-enterprise/modules/users#self-service-events-api)
### External Events
External Events (or HTTP Triggers) are events which occur when something *outside* of AttackForge changes.
For example, if an update happens in an external system - that system can use [Webhooks](https://hookdeck.com/webhooks/guides/what-are-webhooks-how-they-work) to send the message to AttackForge in *real-time*.
External Events can also be called from within any other Flow, creating possibilities for modularisation of your flows.
### Scheduled Events
Time-Based Events are events which occur at a specified time for example each day at 9am, or on a specified frequency for example every hour. Time-Based Events are particularly useful when something needs to happen on a automated time basis.
For example, *each day - find all vulnerabilities which have just exceeded their risk-acceptance date, change their status to open, create a ticket in an external system and notify the vulnerability owner(s) and security team by email and by chat message.*
### Action Events
Action Events are triggered when [Actions](#actions) are clicked by a user within the application user interface.
Action Events can be restricted to `Entities` which helps to scope where Action Events can be accessed from within the application user interface by Actions. This helps to avoid Action Events getting linked to Actions which are not related to the Action Event.
### Assigning Events
A Flow can be assigned to only one Trigger.
Triggers can be assigned to a Flow when either creating or editing the Flow.
### HTTP Trigger - Authentication
[External Events](#external-events) (HTTP Triggers) can be either authenticated or non-authenticated.
Authentication is a way to protect the flow by ensuring that the user who is sending data to the [Trigger URL](#http-trigger-url) is authorized to do so. Authentication is recommended where it is practical to implement on the system sending data to AttackForge, via custom headers.
An authenticated HTTP Trigger flow will check for authentication before the flow runs.
A non-authenticated HTTP Trigger flow will not check for authentication before the flow runs.
Authentication is configured as a custom header. You have control over what the header name should be.
A user interacting with an authenticated HTTP Trigger flow must include their [User Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-api-key) in the specified header. They must also be [granted access to the Flow with Trigger access](#trigger-access), unless they are the [Flow Owner](#sharing-flows-with-teams) whom has implicit access to trigger their flows.
### HTTP Trigger URL
After creating a HTTP Trigger flow, you will receive the Trigger URL and Trigger Id. The Trigger URL is the URL which your external systems and scripts will use to interact and send data to your flow.
The Trigger URL and Trigger ID are unique for every flow.
> **IMPORTANT**: For non-authenticated HTTP Trigger flows, protect your Trigger URL and Trigger ID as if it was a secret. Without authentication, anybody who knows the URL and HTTP Method can attempt to trigger your flow.
You can rotate your Trigger URL and Trigger ID by clicking on the regenerate button:
### Trigger Configuration
Triggers have different configuration options which are supported.
* **Redact user API Key** - this option can be used to prevent anybody working on an authenticated HTTP Trigger flow from gaining access to the [User Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-api-key) supplied in the authentication header, such as through logging.
* **Redact all headers except specified** - this option can be used to specify a [*whitelist*](https://en.wikipedia.org/wiki/Whitelist) of headers which are allowed to be passed into the flow. This option is useful to prevent anybody working on an authenticated HTTP Trigger flow from gaining access to headers which they should not have access to, for example session tokens from external systems.
* **Redact specified headers** - this option can be used to specify a [*blacklist*](https://en.wikipedia.org/wiki/Blacklist_\(computing\)) of headers which will not be passed into the flow. This option is useful to prevent anybody working on an authenticated HTTP Trigger flow from gaining access to headers which they should not have access to, for example session tokens from external systems.
## 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.
You can also reference [Secrets which belong to users](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#secrets). User Secrets make it easy to rotate passwords and credentials without having to update flows.
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.
Note the Key must be letters, numbers and underscores only.
You can create a Local Secret:
Or select from one of your [User Secrets](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#secrets):
You can also view, manage and create secrets in the [Request Script](#request-script) and in the [Response Script](#response-script):
> **NOTE:** Secrets are stored encrypted in the database.
There are two (2) ways in which you can refer to your Secrets in your Flow:
1. Select the Secret directly in the [Headers](#headers)
2. Refer to the Secret in the [Request Script](#request-script) or [Response Script](#response-script)
### Secrets in Headers
When creating or modifying [Headers](#headers) within the [Action](#actions), 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](#request-script) or the [Response Script](#response-script), you can refer to secrets using the following syntax:
```javascript
secrets.
```
Where `` 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](#run-overview).
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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post) 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](https://support.attackforge.com/attackforge-enterprise/modules/self-service-restful-api/updatevulnerability) to set the JIRA Issue Key custom field.
### Action Types
The following Action Types are supported:
* [**HTTP Action**](#http-action)
* The primary purpose of a HTTP Action is to make a HTTP request. The HTTP request can be against the AttackForge [Self-Service APIs](https://support.attackforge.com/attackforge-enterprise/modules/self-service-restful-api) or any external system or endpoint outside of AttackForge.
* [**Script Action**](#script-action)
* The primary purpose of a Script Action is to execute user-defined logic.
### Script Action
Script Actions can be leveraged to execute user-defined logic.
Script Actions can receive input from [Data](#data) and output [Data](#data) into the proceeding Action.
In the example below:
* **Action 1 (HTTP)**: Retrieves vulnerabilities from the AttackForge Self-Serviced APIs.
* **Action 2 (Script)**: Takes the vulnerabilities from Action 1; groups them into the required format, then passes them into Action 3.
* **Action 3 (HTTP)**: Sends the formatted vulnerabilities to an external security platform.
The Script Action contains a single code editor where the script can be input.
### HTTP Action
Every HTTP Action is made up of a [**Request**](#request) and a [**Response**](#response).
* The [Request](#request) is the HTTP request which is made by the Action.
* The [Response](#response) is the HTTP response from the server which received the HTTP request.
Every HTTP Action is made up of the following components:
* [**Method**](#methods) - this is the HTTP method i.e. GET, POST, PUT, etc. that will be used for the [Request](#request)
* [**URL**](#url) - this is the URL that will be used for the [Request](#request).
* **Verify Certificate** - this determines whether to verify if the TLS certificate is valid for the URL.
* [**Headers**](#headers) - these are the headers that will be sent when the [Request](#request) is made.
* [**Request Script**](#request-script) - this is the script which will execute *before* the [Request](#request) is made.
* [**Response Script**](#response-script) - this is the script which will execute *after* the [Response](#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](#request) i.e. GET, POST, PUT, etc.
The following methods are supported:
* GET
* POST
* PUT
* PATCH
* DELETE
Methods can be selected when editing the HTTP [Action](#actions):
Methods can also be programatically set in your [Request Script](#request-script) in the [Return Statement](#the-return-statement):
```javascript
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](#request), for example `https://acmecorp.atlassian.net/rest/api/2/issue`
The URL can be entered in when editing the HTTP [Action](#actions):
The URL can also be programatically set in your [Request Script](#request-script) in the [Return Statement](#the-return-statement). This is useful if your URL has a dynamic component which needs to be computed:
```javascript
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](#request) is made.
The Headers can be manually entered in when editing the HTTP [Action](#actions):
The Headers can also be programatically set in your [Request Script](#request-script) in the [Return Statement](#the-return-statement). This is useful if your Headers have a dynamic component which needs to be computed:
```javascript
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](#url)
* [Method](#methods)
* [Headers](#headers)
* Body - an optional HTTP body. This is typically required for POST, PUT and PATCH HTTP requests.
* [Request Script](#request-script)
> **IMPORTANT:** Requests can be made over both HTTP and HTTPS.
### Response
The Response is the HTTP server response to a [Request](#request).
The Response is made of the of the following components:
* [Response Object](#the-response-object)
* [Response Script](#response-script)
### Request Script
The Request Script is the script which will execute *before* the [Request](#request) is made.
The Request Script is made up of the following components:
* [Code](#code)
* [Data](#data)
* [Return Statement](#the-return-statement)
### Response Script
The Response Script is the script which will execute *after* the [Response](#response) is returned.
The Request Script is made up of the following components:
* [Code](#code)
* [Data](#data)
* [Return Statement](#the-return-statement)
### Code
Flows support [AFScript](https://support.attackforge.com/attackforge-enterprise/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](https://support.attackforge.com/attackforge-enterprise/afscript#logging) in [AFScript](https://support.attackforge.com/attackforge-enterprise/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](#request-script) and [Response Script](#response-script).
You can reference the information included within Data as follows:
```javascript
data.
```
Where `` is replaced with the associated key on the [Data Object](#the-data-object).
For more information on Data, please see [Data Object](#the-data-object).
### The Data Object
[Data](#data) is contextually relevant information for your [Request Script](#request-script) and [Response Script](#response-script).
The Data Object is an [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) that holds the [Data](#data).
The first [Action](#actions) in your Flow will contain [Data](#data) in the [Request Script](#request-script) which is relevent to your [Trigger Event](#triggers). 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](#response-script) and any subsequent [Actions ](#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:
```javascript
data.
```
Using the example above, if you wanted to store the vulnerability Id in a constant, you could do the following:
```javascript
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:
```javascript
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](#response-script) on the first [Action](#actions) - you can include the "data" key in your [Response Object](#the-response-object) and pass in an [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) with key/value pairs as follows:
```javascript
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](#response-script) will now have the following Data Object:
```javascript
data = {
af_project_id: "...",
af_vuln_id: "...",
af_vuln: {
"vulnerability_title": "...",
...
}
}
```
When viewing the details of a [Run](#run-overview) - you can see what [Data](#data) was passed as input and output into an [Action.](#actions)
If you would need to log the Data Object for visibility or debugging during execution of a [Run](#run-overview) you can do the following:
```javascript
Logger.debug('Data:');
Logger.debug(JSON.stringify(data));
```
You can then view the details in the [Run Logs](#runlogs)
When working on [Action Events](#action-events) - you can select which test context(s) you would like to access for the purposes of building and testing your flows.
For example, if your Action Event was restricted to `Project` and `Projects` entities - you can load a test context for either entity:
### The Response Object
The Response Object is the HTTP information which is sent back from the server during the [Response](#response).
The Response Object is available in the [Response Script](#response-script).
The Response Object is made up of the following:
* [HTTP Response Status Code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
* [HTTP Response Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)
* [HTTP Response Body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages)
You can refer to keys on the Response Object using the following syntax:
```javascript
response.
```
An example of the Response Object:
```json
response = {
"statusCode": 200,
"headers": {},
"body": ""
}
```
* The **statusCode** will be accessible as a [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number).
* The **headers** will be accessible as a [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).
* The **body** will be accessible as a [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
If you are expecting the body to be returned as a [JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) payload (which is common for [RESTful APIs](https://developer.mozilla.org/en-US/docs/Glossary/REST)) - you must first parse the body into JSON format before you can access it using [dot or bracket notation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors), see example below:
```javascript
const body = JSON.parse(response.body);
```
When viewing the details of a [Run](#run-overview) - you can see the [Response](#response) [Status Code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) and Response Headers and Response Body:
If you would need to log the Response Object for visibility or debugging during execution of a [Run](#run-overview) you can do the following:
```javascript
Logger.debug('Response:');
Logger.debug(JSON.stringify(response));
```
You can then view the details in the [Run Logs](#runlogs)
### The Return Statement
The Return Statement is the action to take for your [Request Script](#request-script) and [Response Script](#response-script).
The Return Statement is made up of the following components:
* [Decision](#decision)
* [Request](#request)
* [Data](#data-1)
```javascript
return {
decision: {
status: 'continue',
message: 'Payload is valid, proceed to submit request',
},
request: {
url: 'https://www.attackforge.com/api',
body: {},
headers: {},
method: 'GET',
},
data: {}
};
```
#### Decision
The following Flow Return Decisions are supported:
* Continue
* Finish
* Abort
* Next
* Repeat
```javascript
return {
decision: {
status: 'continue',
message: 'Payload is valid, proceed to submit request',
}
};
```
The decision is the action that your script will take. A decision is made up of the following components:
* status - a supported status (see below)
* message - an optional message to display in the logs
* delay - an optional number in milliseconds to wait until proceeding with the [Request](#request) or the next [Action](#actions). The minimum delay is 0. The maximum delay is 86400000 (24 hours).
```javascript
return {
decision: {
status: 'continue',
message: 'Payload is valid, wait 5 seconds then proceed to submit request',
delay: 5000
}
};
```
You can also include the decision as a string if you do not need to include a message:
```javascript
return {
decision: "continue" //also supports "next", "abort", "finish"
};
```
The following statuses are supported:
**CONTINUE**
Continue will instruct your script to continue with normal execution. For example, continuing in the [Request Script](#request-script) will result in the [Request](#request) being made. Continuing in the [Response Script](#response-script) will result in executing the next [Action](#actions).
Example using Continue:
```javascript
return {
decision: {
status: 'continue',
message: 'Payload is valid, proceed to submit request',
}
};
```
**NEXT**
Next will instruct your [Request Script](#request-script) or [Response Script](#response-script) to move to the next [Action](#actions). This is useful if a [Request](#request) in your Flow is conditional i.e. it may or may not need to be made.
Example using Next:
```javascript
return {
decision: {
status: 'next',
message: 'Asset already exists. Move to create vulnerability',
}
};
```
**REPEAT**
Repeat will instruct your [Action](#actions) to repeat. This is useful for the following use cases:
* Create a 'for loop' Action over a list of data - for example create a new vulnerability for each record in a long list.
* Interact with paginated endpoints to retrieve the full list of results.
* Request failed; update the payload and try again.
When you repeat an action, you can also modify its [Data](#the-data-object). This means you can pass in new data and context to the Action.
**Example Action using Repeat**
***Request Script***
***Response Script***
***Example 1: Process list of data***
Say you have 100 vulnerabilities in a list. The purpose of your Action is to create a new vulnerability.
On the *first iteration* of the Action, you create vulnerability `1 out of 100` - leaving 99 more to go.
You can then repeat the Action, updating the list to remove the vulnerability which was just created.
On the *second iteration* of the Action, you create vulnerability `2 out of 100` - leaving 98 more to go.
This process repeats until you have 0 vulnerabilities left in the list to process, then you call *next* to move on to the next Action in your Flow, or *finish* to gracefully end your Flow.
***Example 2: Interact with paginated endpoints***
Say you have 1000 vulnerabilities you need to access, however the page length of the API endpoint only returns 50 at a time. The purpose of your Action is to fetch a page of vulnerabilities.
On the *first iteration* of the Action, you fetch vulnerabilities `1 to 50 out of 1000` - leaving 950 more to go.
You can then repeat the Action, updating the page marker to fetch the next page.
On the *second iteration* of the Action, you fetch vulnerabilities `51 to 100 out of 1000` - leaving 900 more to go.
This process repeats until you have 0 pages left to fetch, then you call *next* to move to the next Action in your Flow, or *finish* to gracefully end your Flow.
When an Action repeats, the logs for each iteration will be visible to you in the [Flow Run](https://support.attackforge.com/attackforge-enterprise/modules/flows#run-overview) logs.
**ABORT**
Abort will terminate your Flow as an error condition. This is useful in cases where your Flow can no longer proceed due to various reasons.
Example using Abort:
```javascript
return {
decision: {
status: 'abort',
message: 'Auth token not generated. Check if credentials are valid?',
}
};
```
**FINISH**
Finish will terminate your Flow as an success condition. This is how you would normally terminate a Flow.
Example using Finish:
```javascript
return {
decision: {
status: 'finish',
message: 'Vulnerability created!',
}
};
```
#### Request
The Request is the HTTP Request information that your [Request Script](#request-script) will use. Request is made up of the following components:
* url
* body
* headers
* method
```javascript
return {
decision: {
status: 'continue',
message: 'Payload is valid, proceed to submit request',
},
request: {
url: 'https://www.attackforge.com/api',
body: {},
headers: {},
method: 'GET',
}
};
```
**URL**
The URL is the URL that the [Request](#request) will be sent to. This field is optional. If it is not specified, the [URL](#url) set in the [Action](#actions) will prevail. If it is specified, it will take precedence over the [URL](#url) set in the [Action](#actions).
**BODY**
The Body is the payload body that will be sent in the [Request](#request). This field is optional. If it is not specified, no body will be sent in the [Request](https://support.attackforge.com/attackforge-enterprise/self-service-restful-api/getprojectrequest#request).
Example with a JSON Body:
```javascript
return {
decision: {
status: 'continue'
},
request: {
body: {
fields: {
project: {
key: jiraProjectKey
},
summary: summary,
description: description,
priority: {
name: priority
},
issuetype: {
name: 'Bug'
},
labels: labels
}
}
}
};
```
**HEADERS**
The Headers are the HTTPS Headers that the [Request](#request) will use. This field is optional. If it is not specified, the [Headers](#headers) set in the [Action](#actions) will prevail. If it is specified, it will take precedence over the [Headers](#headers) set in the [Action](#actions).
Example Headers:
```javascript
return {
decision: {
status: 'continue',
},
request: {
headers: {
'Content-Type': 'application/json',
'x-ssapi-key': secrets.af_auth,
}
}
};
```
**METHOD**
The Method is the HTTPS Method that the [Request](#request) will be sent to. This field is optional. If it is not specified, the [Method](#methods) set in the [Action](#actions) will prevail. If it is specified, it will take precedence over the [Method](#methods) set in the [Action](#actions).
Example Headers:
```javascript
return {
decision: {
status: 'continue',
},
request: {
method: 'GET' //supports GET, POST, PUT, PATCH, DELETE
}
};
```
#### Data
Data is an object that can be used to pass information between [Request Script](#request-script) to [Response Script](#response-script), and from [Response Script](#response-script) to the next [Action](#actions).
The Data in the [Request Script](#request-script) for the first [Action](#actions) of the Flow will be the Event information, for example "vulnerability-created" fields. From then onwards, you can override what the data will be in the [Response Script](#response-script) and beyond.
Example with Data in the [Request Script](#request-script) of the first [Action](#actions) in the Flow:
```javascript
return {
decision: {
status: 'continue',
},
data: {
af_project_id: afProjectId,
af_vuln: data
}
};
```
Example with Data in the [Response Script](#response-script) of the first [Action](#actions) in the Flow. This example will pass on the "af\_project\_id" and "af\_vuln" that was passed in the Data from the [Request Script](#request-script) on to the next [Action](#actions) in the Flow.
```javascript
return {
decision: {
status: 'continue',
},
data: {
af_project_id: data.af_project_id,
af_vuln: data.af_vuln
}
};
```
### Downloading Files using Flows
Flows can be used to download [HTTP Response](#response) data as a file.
To download data from a HTTP Response, open the [Action](#actions) - click on **Options** then select **Download Response**.
Then inside the HTTP Response, the response will contain a **fileId** which is the reference to the file after Flows has automatically downloaded the file. You can then refer to this fileId in subsequent Actions to use the file, for example upload it to some place.
### Uploading Files using Flows
Flows can be used to upload [previously downloaded files](#downloading-files-using-flows).
To upload a file, you must have first downloaded the file and stored the **fileId** - see [Downloading Files using Flows](#downloading-files-using-flows).
Once you have the **fileId**, you can upload it using a **multipart/form-data** [HTTP Request](#request).
## Runs
Flow Runs is where you can view the history of each [Run](#run-overview) you have access to, across all of your Flows. It is a consolidated view for every [Run](#run-overview). You can access this page from the Flows module.
You can also view [Runs](#run-overview) for a specific Flow by clicking on Flows and then clicking on the name of a Flow.
### Run Logs
When clicking on a [Run](#run-overview), you will see an overview of the history for that [Run](#run-overview), including the following information:
* **Run Status -** Whether the [Run](#run-overview) was Completed or Failed.
* **Event -** the related Event which triggered the Flow.
* **Started -** the timestamp of when the [Run](#run-overview) started execution.
* **Duration -** the duration (in milliseconds) for execution of the [Run](#run-overview) until completion or failure.
* **Actions -** the [Actions](#actions) in-scope during the [Run](#run-overview).
* **Data -** the input and output of each [Action](#actions).
* **HTTP -** the [URL](#url), [Method](#methods), [Headers](#headers), [Request Body](#request-script), Response Status Code and [Response Body](#response-script) for each [Action](#actions) in the Flow.
* **Logs -** the logs for each [Action](#actions).
If you include [Logging](https://support.attackforge.com/attackforge-enterprise/afscript#logging) in your [Request Script](#request-script) or [Response Script](#response-script), you will be able to see the logs here during execution of a Flow.
### Manually Run Flow
You can manually run a Flow at any time. This is useful for testing your Flow. When you manually run a Flow, the input into the first [Action](#actions) will be test data. You can modify the test data to match your testing needs.
### Re-Run
You can manually re-run a Flow at any time. When you Re-Run a Flow, it will execute with exactly the same input data into the first [Action](#actions).
After a Flow has Re-Run, you will notice the [Event Trigger](#triggers) will show that it was Re-Run.
### Accessing Previous Runs
When a HTTP Triggered Flow is invoked, the Flow will Run asynchronously.
Due to the asynchronous nature of the [Flow Run](#runs), will you immediately receive a **Flow Run Id** in the response:
The Flow Run Id can then be used to poll and fetch the results of the Flow Run once it has reached its terminal state.
To fetch the results of the Flow Run, you would need to make the following API request:
```bash
curl --request GET \
--url 'https://{{tenant}}/api/flows/runs/{{flowRunId}}' \
--header 'content-type: application/json' \
--header 'x-user-key: {{api-key}}'
```
The result of the Flow Run will then be returned:
And we can confirm that this is what should have been returned based on a successful Flow Run:
If accessing the Flow through the browser, for example if the Flow is a GET request and attached to a button in an email - you can set a user friendly response page by appending `?format=html` to the URL:
```bash
curl --request GET \
--url 'https://{{tenant}}/api/flows/runs/{{flowRunId}}?format=html' \
--header 'content-type: application/json' \
```
A `successful` response will appear as follows:
A `failed` response will appear as follows:
### Flow Run Statuses
The following Flow Run Statuses are available:
* **Running -** the Flow is currently running.
* **Completed -** the Flow Run has completed.
* **Failed** - the Flow Run has failed. This happens when a Flow Return decision is set to Abort; or when there is a runtime error in the script.
* **Dropped** - the Flow Run was detected as a duplicate and dropped.
* **Missed** - the Flow Run was scheduled, however did not run as per schedule, for example if the AttackForge server was restarted.
* **Terminated** - the Flow Run was manually terminated.
## Flow Readme
Every flow can have a readme which helps to detail key information such as:
* How the flow works
* How to operate the flow
* Links to external documentation
* Contact information for key persons
You can create and edit the readme when creating or editing the flow:
## Importing/Exporting Flows
You can export your existing Flows and import Flows at any time. This utility can help to:
* Share Flows with others, without giving them access to your Flows
* Create a backup of your Flows
* Bootstrap a new Flow based on a template
To export a Flow, click on the `Export Flow` button. The Flow will be exported with a `.flow` extension format.
> **IMPORTANT**: Exported Flows do not contain the values of [Secrets](#secrets). However for compatibility and convenience, the [Secret](#secrets) key/name will be included in the export.
To import a Flow, click on `Import Flow`:
Select the Flow you would like to import (.flow file):
You will have an opportunity to review and adjust the Flow prior to saving.
## Transferring Flows
Flows run under the context of an Owner. That means, when the event happens for the Owner, the Flow will trigger.
You can transfer ownership of Flows when required, so that the Flow can operate under the context of another user.
To transfer ownership of your Flow - open the Flow settings page and click on `Transfer`
Select the user or enter in their email address and click `Transfer`
The user will immediately receive ownership of the Flow, however it will be disabled until they review the Flow and chose to enable it.
