# Integrate AlgoSec with
Google SecOps

This document explains how to integrate AlgoSec with Google Security Operations.

## Use cases

The AlgoSec integration uses Google SecOps capabilities to
support the following use cases:

- **Automated threat containment**: Block malicious IP addresses across managed
  firewalls by submitting automated drop traffic change requests during security
  investigations.

- **Controlled traffic authorization**: Allow legitimate business traffic to
  verified destination IP addresses by creating standardized allow rules in
  AlgoSec FireFlow.

- **Template discovery and governance**: Retrieve available FireFlow change
  request templates to align automated response actions with organizational
  change management policies.

- **Asynchronous change lifecycle tracking**: Monitor submitted traffic change
  requests until they reach target operational statuses such as resolved or
  implement.

## Before you begin

Before you configure the AlgoSec integration in Google SecOps,
verify that your environment meets the following requirements:

- **Network connectivity** : Make sure that Google SecOps (or a
  deployed remote agent for on-premises environments) can reach your AlgoSec
  server over HTTPS on TCP port `443`.

- **FireFlow templates** : Enable at least one traffic change request template
  (such as `Standard`) in AlgoSec FireFlow before running actions that submit
  change requests.

- **Least-privilege user permissions**: Configure a dedicated AlgoSec FireFlow
  service account with the minimum permissions required for the actions used in
  your playbooks, as detailed in the following table:

| Action | Required AlgoSec FireFlow permissions |
|---|---|
| `Allow IP` | Authenticate with FireFlow, create traffic change requests for allow rules, and read traffic change request details. |
| `Block IP` | Authenticate with FireFlow, create traffic change requests for drop rules, and read traffic change request details. |
| `List Templates` | Authenticate with FireFlow and view available change request templates. |
| `Ping` | Authenticate with FireFlow and view available change request templates to validate connectivity. |
| `Wait for Change Request Status Update` | Authenticate with FireFlow and read traffic change request details and lifecycle statuses. |

For more information about configuring FireFlow roles, user accounts, and
change request templates, refer to the official AlgoSec FireFlow documentation.

## Integration parameters

The AlgoSec integration requires the following parameters:

| Parameter | Description |
|---|---|
| `API Root` | Required. The base URL of the AlgoSec server, formatted as `https://SERVER_ADDRESS`. |
| `Username` | Required. The username of the AlgoSec FireFlow account used for authentication. |
| `Password` | Required. The password of the AlgoSec FireFlow account used for authentication. |
| `Verify SSL` | Required. If selected, the integration validates the SSL certificate when connecting to the AlgoSec server. Enabled by default. |


For instructions about how to configure an integration in
Google SecOps, see [Configure
integrations](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/configure-integrations).

You can make changes at a later stage, if needed. After you configure an
integration instance, you can use it in playbooks. For more information about
how to configure and support multiple instances, see [Supporting
multiple instances](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/supporting-multiple-instances).

<br />

## Actions


For more information about actions, see [Respond to pending actions from your workdesk](https://docs.cloud.google.com/chronicle/docs/soar/overview-and-introduction/your-workdesk/respond-to-pending-actions-from-workdesk.md.txt) and [Run a
manual action in your case](https://docs.cloud.google.com/chronicle/docs/soar/investigate/working-with-cases/what-actions-can-you-take-on-a-case#run-manual-action).

### Allow IP

Use the **Allow IP** action to submit a traffic change request in AlgoSec
FireFlow that allows traffic to the case's `IP Address` entities (used as the
destination addresses).

This action runs on the `IP Address` Google SecOps entity.

#### Action inputs

The **Allow IP** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Template` | Required. The name of the AlgoSec FireFlow template to use for the traffic change request. The default value is `Standard`. |
| `Source` | Required. A comma-separated list of source IP addresses or network objects for the allow rule, or the keyword `all` to include all sources. The action converts all values to lowercase. The default value is `all`. |
| `Service` | Required. A comma-separated list of network services to allow, formatted as protocol and port pairs such as `tcp/80`, or the keyword `all` to allow all services. The default value is `ALL`. |
| `Subject` | Optional. A subject line for the traffic change request in AlgoSec FireFlow. The default value is `Siemplify Allow IP request`. |
| `Owner` | Optional. A username or identifier of the user who owns the change request. If you don't provide a value, AlgoSec assigns the authenticated user who created the ticket as the owner. |
| `Due Date` | Optional. A target completion date and time for the change request in ISO 8601 format, such as `2021-08-13T08:16:10Z`. |
| `Expiration Date` | Optional. An expiration date and time for the allowed traffic rule in ISO 8601 format, such as `2021-08-13T08:16:10Z`. |
| `Custom Fields` | Optional. Additional FireFlow change request fields provided as key-value pairs, such as `{"Owner": "admin@example.com", "Subject": "Allow IP request"}`. If provided, this parameter overrides the `Subject`, `Owner`, `Due Date`, and `Expiration Date` parameters. |

#### Action outputs

The **Allow IP** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Available |
| Case wall table | Not available |
| Entity enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall link

The **Allow IP** action provides the following link on the Case Wall:

- **Link title** : `Change Request Link`

- **Link target**: Opens the created traffic change request in the AlgoSec
  FireFlow web interface.

##### JSON result

The following example shows the JSON result output received when using the
**Allow IP** action:

```json
{
    "status": "Success",
    "messages": [],
    "data": {
        "id": 10,
        "fields": [
            {
                "name": "Owner",
                "values": [
                    "admin@example.com"
                ]
            },
            {
                "name": "Creator",
                "values": [
                    "admin@example.com"
                ]
            },
            {
                "name": "Due",
                "values": [
                    "2021-08-31 00:00:00"
                ]
            },
            {
                "name": "LastUpdated",
                "values": [
                    "2021-08-13 12:31:23"
                ]
            },
            {
                "name": "Requestor",
                "values": [
                    "admin@example.com"
                ]
            }
        ],
        "originalTraffic": [
            {
                "source": {
                    "items": [
                        {
                            "value": "all"
                        }
                    ]
                },
                "destination": {
                    "items": [
                        {
                            "value": "192.0.2.3"
                        }
                    ]
                },
                "service": {
                    "items": [
                        {
                            "value": "ALL"
                        }
                    ]
                },
                "application": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "user": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "action": "Allow"
            }
        ],
        "plannedTraffic": [
            {
                "source": {
                    "items": [
                        {
                            "value": "0.0.0.0-255.255.255.255"
                        }
                    ]
                },
                "destination": {
                    "items": [
                        {
                            "value": "192.0.2.3"
                        }
                    ]
                },
                "service": {
                    "items": [
                        {
                            "value": "tcp/*"
                        },
                        {
                            "value": "udp/*"
                        },
                        {
                            "value": "ospf"
                        },
                        {
                            "value": "icmp/*"
                        },
                        {
                            "value": "gre"
                        },
                        {
                            "value": "ipsec_50"
                        },
                        {
                            "value": "ipsec_51"
                        }
                    ]
                },
                "application": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "user": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "action": "Allow"
            }
        ]
    }
}
```

##### Output messages

The **Allow IP** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Successfully created a traffic change request to allow traffic to the provided entities in AlgoSec` | The action succeeded. |
| `Error executing action AlgoSec - Allow IP. Reason: ERROR_REASON` | The action failed. Verify that the AlgoSec server URL and credentials are valid, confirm that the specified template name exists in FireFlow, format date parameters in ISO 8601 format, and format any custom fields as valid key-value pairs. |

##### Script result

The following table lists the value for the script result output when using the
**Allow IP** action:

| Script result name | Value |
|---|---|
| `is_success` | `true` or `false` |

### Block IP

Use the **Block IP** action to submit a traffic change request in AlgoSec
FireFlow that blocks traffic to the case's `IP Address` entities (used as the
destination addresses).

This action runs on the `IP Address` Google SecOps entity.

#### Action inputs

The **Block IP** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Template` | Required. The name of the AlgoSec FireFlow template to use for the traffic change request. The default value is `Standard`. |
| `Source` | Required. A comma-separated list of source IP addresses or network objects for the block rule, or the keyword `all` to include all sources. The action converts all values to lowercase. The default value is `all`. |
| `Service` | Required. A comma-separated list of network services to block, formatted as protocol and port pairs such as `tcp/80`, or the keyword `all` to block all services. The default value is `ALL`. |
| `Subject` | Optional. A subject line for the traffic change request in AlgoSec FireFlow. The default value is `Siemplify Block IP request`. |
| `Owner` | Optional. A username or identifier of the user who owns the change request. If you omit this parameter, AlgoSec assigns the authenticated user who created the ticket as the owner. |
| `Due Date` | Optional. A target completion date and time for the change request in ISO 8601 format, such as `2021-08-13T08:16:10Z`. |
| `Expiration Date` | Optional. An expiration date and time for the blocked traffic rule in ISO 8601 format, such as `2021-08-13T08:16:10Z`. |
| `Custom Fields` | Optional. Additional FireFlow change request fields provided as key-value pairs, such as `{"Owner": "admin@example.com", "Subject": "Block IP request"}`. If provided, this parameter overrides the `Subject`, `Owner`, `Due Date`, and `Expiration Date` parameters. |

#### Action outputs

The **Block IP** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Available |
| Case wall table | Not available |
| Entity enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall link

The **Block IP** action provides the following link on the Case Wall:

- **Link title** : `Change Request Link`

- **Link target**: Opens the created traffic change request in the AlgoSec
  FireFlow web interface.

##### JSON result

The following example shows the JSON result output received when using the
**Block IP** action:

```json
{
    "status": "Success",
    "messages": [],
    "data": {
        "id": 11,
        "fields": [
            {
                "name": "Owner",
                "values": [
                    "admin@example.com"
                ]
            },
            {
                "name": "Creator",
                "values": [
                    "admin@example.com"
                ]
            },
            {
                "name": "Due",
                "values": [
                    "2021-08-31 00:00:00"
                ]
            },
            {
                "name": "LastUpdated",
                "values": [
                    "2021-08-13 12:35:10"
                ]
            },
            {
                "name": "Requestor",
                "values": [
                    "admin@example.com"
                ]
            }
        ],
        "originalTraffic": [
            {
                "source": {
                    "items": [
                        {
                            "value": "all"
                        }
                    ]
                },
                "destination": {
                    "items": [
                        {
                            "value": "192.0.2.3"
                        }
                    ]
                },
                "service": {
                    "items": [
                        {
                            "value": "ALL"
                        }
                    ]
                },
                "application": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "user": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "action": "Drop"
            }
        ],
        "plannedTraffic": [
            {
                "source": {
                    "items": [
                        {
                            "value": "0.0.0.0-255.255.255.255"
                        }
                    ]
                },
                "destination": {
                    "items": [
                        {
                            "value": "192.0.2.3"
                        }
                    ]
                },
                "service": {
                    "items": [
                        {
                            "value": "tcp/*"
                        },
                        {
                            "value": "udp/*"
                        },
                        {
                            "value": "ospf"
                        },
                        {
                            "value": "icmp/*"
                        },
                        {
                            "value": "gre"
                        },
                        {
                            "value": "ipsec_50"
                        },
                        {
                            "value": "ipsec_51"
                        }
                    ]
                },
                "application": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "user": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "action": "Drop"
            }
        ]
    }
}
```

##### Output messages

The **Block IP** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Successfully created a traffic change request to block traffic to the provided entities in AlgoSec` | The action succeeded. |
| `Error executing action AlgoSec - Block IP. Reason: ERROR_REASON` | The action failed. Verify that the AlgoSec server URL and credentials are valid, confirm that the specified template name exists in FireFlow, format date parameters in ISO 8601 format, and format any custom fields as valid key-value pairs. |

##### Script result

The following table lists the value for the script result output when using the
**Block IP** action:

| Script result name | Value |
|---|---|
| `is_success` | `true` or `false` |

### List Templates

Use the **List Templates** action to retrieve available change request templates
configured in AlgoSec FireFlow. You can filter templates by name to identify the
exact template name required when automating traffic change requests.


This action doesn't run on Google SecOps entities.

#### Action inputs

The **List Templates** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Filter Logic` | Optional. The matching logic applied when filtering template names using the `Filter Value` parameter. The possible values are as follows: - `Equal` - `Contains` The default value is `Equal`. |
| `Filter Value` | Optional. The case-sensitive template name or substring used to filter available templates based on the selected `Filter Logic`. If you don't specify a filter value, the action returns all templates up to the configured limit. |
| `Max Templates To Return` | Optional. The maximum number of templates to return. The default value is `50`. |

#### Action outputs

The **List Templates** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Available |
| Entity enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **List Templates** action provides the following table on the Case Wall:

- **Table name** : `Available Templates`

- **Columns**:

  - `Name`
  - `Description`
  - `Type`

##### JSON result

The following example shows the JSON result output received when using the
**List Templates** action:

```json
[
    {
        "id": 142,
        "name": "110: Multi-Approval Request",
        "description": "Create a traffic change request which requires multiple approvals",
        "type": "Traffic Change",
        "enabled": true
    },
    {
        "id": 597,
        "name": "190: Verbatim Rule Addition",
        "description": "Create a traffic change request for bulk rules addition as specified",
        "type": "Traffic Change",
        "enabled": true
    },
    {
        "id": 550,
        "name": "Basic Change Traffic Request",
        "description": "Create a basic change traffic request",
        "type": "Traffic Change",
        "enabled": true
    }
]
```

##### Output messages

The **List Templates** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Successfully found templates for the provided criteria in AlgoSec.` | The action succeeded. |
| `No templates were found for the provided criteria in AlgoSec.` | The action failed. Verify that templates exist in AlgoSec FireFlow and check the spelling and letter case of the `Filter Value` parameter, or change `Filter Logic` to `Contains`. |
| `Error executing action AlgoSec - List Templates. Reason: ERROR_REASON` | The action failed. Verify that the AlgoSec server connection parameters are valid and that `Max Templates To Return` is set to a number greater than `0`. |

##### Script result

The following table lists the value for the script result output when using the
**List Templates** action:

| Script result name | Value |
|---|---|
| `is_success` | `true` or `false` |

### Ping

Use the **Ping** action to test connectivity and authentication to the AlgoSec
server using the configured integration parameters.


This action doesn't run on Google SecOps entities.

#### Action inputs

None.

#### Action outputs

The **Ping** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Entity enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Ping** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Successfully connected to the AlgoSec server with the provided connection parameters!` | The action succeeded. |
| `Failed to connect to the AlgoSec server! Error is ERROR_REASON` | The action failed. Verify that the `API Root` URL is reachable from Google SecOps, check that the `Username` and `Password` credentials are valid, and confirm your SSL certificate settings. |

##### Script result

The following table lists the value for the script result output when using the
**Ping** action:

| Script result name | Value |
|---|---|
| `is_success` | `true` or `false` |

### Wait for Change Request Status Update

Use the **Wait for Change Request Status Update** action to monitor a traffic
change request in AlgoSec FireFlow until it reaches a target status.

> [!NOTE]
> **Note:** This action runs asynchronously. Adjust the script timeout value in the Google SecOps IDE if approval workflows require extended wait times.


This action doesn't run on Google SecOps entities.

#### Action inputs

The **Wait for Change Request Status Update** action requires the following
parameters:

| Parameter | Description |
|---|---|
| `Request ID` | Required. The numeric identifier of the AlgoSec traffic change request to monitor. |
| `Status` | Required. A comma-separated list of target lifecycle statuses that complete the action when matched. The action ignores invalid status names if you provide at least one valid status. The possible values are as follows: - `resolved` - `reconcile` - `open` - `check` - `implementation plan` - `implement` - `validate` The default value is `resolved`. |

#### Action outputs

The **Wait for Change Request Status Update** action provides the following
outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Entity enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### JSON result

The following example shows the JSON result output received when using the
**Wait for Change Request Status Update** action:

```json
{
    "status": "Success",
    "messages": [],
    "data": {
        "id": 6,
        "subChangeRequests": [
            12
        ],
        "fields": [
            {
                "name": "Risk Level",
                "values": [
                    "No Risk"
                ]
            },
            {
                "name": "Owner",
                "values": [
                    "admin@example.com"
                ]
            },
            {
                "name": "Creator",
                "values": [
                    "admin@example.com"
                ]
            },
            {
                "name": "LastUpdated",
                "values": [
                    "2021-08-13 13:50:58"
                ]
            },
            {
                "name": "Requestor",
                "values": [
                    "admin@example.com"
                ]
            },
            {
                "name": "Form Type",
                "values": [
                    "Traffic Change"
                ]
            },
            {
                "name": "Risks Number",
                "values": [
                    "0"
                ]
            },
            {
                "name": "Initial Plan status",
                "values": [
                    "Result OK"
                ]
            },
            {
                "name": "Workflow",
                "values": [
                    "Basic"
                ]
            },
            {
                "name": "Subject",
                "values": [
                    "1"
                ]
            },
            {
                "name": "status",
                "values": [
                    "resolved"
                ]
            }
        ],
        "originalTraffic": [
            {
                "source": {
                    "items": [
                        {
                            "value": "all"
                        }
                    ]
                },
                "destination": {
                    "items": [
                        {
                            "value": "192.0.2.2"
                        }
                    ]
                },
                "service": {
                    "items": [
                        {
                            "value": "tcp/80"
                        }
                    ]
                },
                "application": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "user": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "action": "Allow"
            }
        ],
        "plannedTraffic": [
            {
                "source": {
                    "items": [
                        {
                            "value": "0.0.0.0-255.255.255.255"
                        }
                    ]
                },
                "destination": {
                    "items": [
                        {
                            "value": "192.0.2.2"
                        }
                    ]
                },
                "service": {
                    "items": [
                        {
                            "value": "tcp/80"
                        }
                    ]
                },
                "application": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "user": {
                    "items": [
                        {
                            "value": "any"
                        }
                    ]
                },
                "action": "Allow"
            }
        ]
    }
}
```

##### Output messages

The **Wait for Change Request Status Update** action provides the following
output messages:

| Output message | Message description |
|---|---|
| `Status of the change request with ID REQUEST_ID was updated to status: STATUS.` | The action succeeded. |
| `Waiting for a change request to be updated...` | The action is still running and polling AlgoSec FireFlow until the change request reaches one of the target statuses. |
| `Error executing action AlgoSec - Wait for Change Request Status Update. Reason: action ran into a timeout during execution. Current status of the change request: STATUS. Please increase the timeout for the action in the IDE.` | The action failed. Increase the action execution timeout in the Google SecOps IDE or verify that the change request is progressing through its approval workflow in AlgoSec FireFlow. |
| `Error executing action AlgoSec - Wait for Change Request Status Update. Reason: ERROR_REASON` | The action failed. Verify that the `Request ID` corresponds to an existing traffic change request, confirm that you provided at least one valid value in the `Status` parameter, and check that the AlgoSec server credentials are valid. |

##### Script result

The following table lists the value for the script result output when using the
**Wait for Change Request Status Update** action:

| Script result name | Value |
|---|---|
| `is_success` | `true` or `false` |

**Need more help?** [Get answers from Community members and Google SecOps professionals.](https://security.googlecloudcommunity.com/)