From a6ad195431ea85fcc3df6aec16510a57a5f0e637 Mon Sep 17 00:00:00 2001 From: Matthew Virga <89219147+mvirga-sumo@users.noreply.github.com> Date: Fri, 26 Jul 2024 10:15:16 -0400 Subject: [PATCH 1/2] Update cloud-soar-bridge.md - Ammend SIEM_URL setting --- docs/cloud-soar/cloud-soar-bridge.md | 135 ++++++++++++++------------- 1 file changed, 68 insertions(+), 67 deletions(-) diff --git a/docs/cloud-soar/cloud-soar-bridge.md b/docs/cloud-soar/cloud-soar-bridge.md index 2ec3947d60..769ef78d26 100644 --- a/docs/cloud-soar/cloud-soar-bridge.md +++ b/docs/cloud-soar/cloud-soar-bridge.md @@ -5,6 +5,7 @@ sidebar_label: Automation Bridge description: Learn how to install a bridge for Cloud SOAR to allow running custom actions or integrations in an on-premise environment. --- + import useBaseUrl from '@docusaurus/useBaseUrl'; You can only run custom actions or integrations outside of the Sumo Logic cloud in an "on-premise" environment. For on-premise environments, you need to install a bridge as described below. @@ -23,17 +24,21 @@ You can only run custom actions or integrations outside of the Sumo Logic cloud * Network card: 1 ### Network requirements - -The Bridge must be able to resolve DNS hostnames and reach the below destinations. +The Bridge has to be able to resolve DNS hostnames and needs to reach the below destinations | DESTINATION | PROTOCOL | PORT | | :-- | :-- | :-- | -| soar-cloud-url | TCP | 443 | -| siem-cloud-url | TCP| 443| -| 784093250948.dkr.ecr.eu-central-1.amazonaws.com | TCP| 443| -| 784093250948.dkr.ecr.us-east-1.amazonaws.com | TCP| 443| -| 784093250948.dkr.ecr.us-west-2.amazonaws.com | TCP| 443| +| sumo-logic-api-url | TCP| 443| +| siem-cloud-url | TCP| 443| +| 926226587429.dkr.ecr.us-west-2.amazonaws.com | TCP| 443| +| 926226587429.dkr.ecr.us-east-1.amazonaws.com | TCP| 443| +| 926226587429.dkr.ecr.ap-southeast-2.amazonaws.com | TCP| 443| +| 926226587429.dkr.ecr.eu-central-1.amazonaws.com | TCP| 443| +| 926226587429.dkr.ecr.ap-south-1.amazonaws.com | TCP| 443| +| 926226587429.dkr.ecr.ap-northeast-1.amazonaws.com | TCP| 443| +| 926226587429.dkr.ecr.ca-central-1.amazonaws.com | TCP| 443| +| 926226587429.dkr.ecr.eu-west-1.amazonaws.com | TCP| 443| | index.docker.io* | TCP| 443| | registry-1.docker.io* | TCP| 443| | auth.docker.io* | TCP| 443| @@ -46,25 +51,24 @@ The Bridge must be able to resolve DNS hostnames and reach the below destination 1. Install Docker-CE following the [installation instructions in Docker Docs](https://docs.docker.com/engine/install/). Install at least version 20.10 (do not use nightly build). 1. As soon as the Docker daemon is installed, start it with: - ```sh + ``` systemctl start docker ``` 1. Enable it on boot: - ```sh + ``` systemctl enable docker ``` -### Using a proxy - +### Using a proxy 1. If Docker has to use a proxy to pull images, follow the below instructions: ```sh mkdir -p /etc/systemd/system/docker.service.d ``` 1. Create a file named `/etc/systemd/system/docker.service.d/http-proxy.conf`, and add: - ```sh + ``` [Service] - Environment="HTTP_PROXY=http://proxy.example.com:8080\" - Environment="HTTPS_PROXY=http://proxy.example.com:8080\" + Environment="HTTP_PROXY=http://proxy.example.com:8080" + Environment="HTTPS_PROXY=http://proxy.example.com:8080" ``` 1. Reload the systemd daemon with: ```sh @@ -77,36 +81,29 @@ The Bridge must be able to resolve DNS hostnames and reach the below destination ## Get installation token -Log in to Sumo Logic and create a new [installation token](/docs/manage/security/installation-tokens/) with the name prefix `csoar-bridge-token`. +Login to Sumo Logic and create a new [installation token](/docs/manage/security/installation-tokens/) with name prefix `csoar-bridge-token`. -Installation token +Installation token -## Automation installation +## Automation bridge installation ### Ubuntu - -1. Click the **?** icon in the top right. -1. Click the **UBUNTU** button. + +1. In the main Sumo Logic menu, select **Automation** and then click the **?** icon in the top right. +1. In the **Automation Bridge Manual** box, click **UBUNTU**. 1. Click **Download** to download the `automation-bridge-X.X.deb` file. -1. Copy the file to the bridge virtual machine. You can use SCP - see example below: - ```sh - scp -r -i /path/to/private_key /path/to/local/folder remote_user@remote_ip:/path/to/remote/folder - ``` -3. To install the package run from ssh: +1. Copy the file to the bridge virtual machine. +1. To install the package run from ssh: ```sh sudo dpkg -i automation-bridge-X.X.deb ``` ### CentOS/RedHat -1. Click the **?** icon in the top right. -1. In the **Automation Bridge** box, click **CENTOS/REDHAT**. +1. In the main Sumo Logic menu, select **Automation** and then click the **?** icon in the top right. +1. In the **Automation Bridge Manual** box, click **CENTOS/REDHAT**. 1. Click **Download** to download the `automation-bridge-X.X.rpm` file. -1. Copy the file to the bridge virtual machine (You can use SCP, see example below). - ```sh - scp -r -i /path/to/private_key /path/to/local/folder remote_user@remote_ip:/path/to/remote/folder - ``` +1. Copy the file to the bridge virtual machine. 1. To install the package run from ssh: ```sh sudo yum install automation-bridge-X.X.rpm @@ -127,44 +124,48 @@ An example of a configuration file would be: { "SOAR_URL":"API_ENDPOINT_FROM_FIREWALL_DOC_FOR_YOUR_REGION", "SOAR_TOKEN":"TOKEN_FROM_ADMINISTRATION_-->_SECURITY_-->_INSTALLATION TOKEN", - "SIEM_URL":"https://YOUR_CSE_URL/sec", + "SIEM_URL":"The HTTPS Source Endpoint URL From a Hosted Sumo Logic Collector", "ALIAS":"YOUR_ALIAS_NO_SPACES_LESS_THAN_20_CHARACTERS" } ``` +To create a Hosted Sumo Logic Collector See: [Sumo Logic Hosted Collector](/docs/send-data/hosted-collectors/) +To add an HTTPS Source to a Hosted Collector See: [Sumo Logic HTTP Logs and Metrics Source](https://help.sumologic.com/docs/send-data/hosted-collectors/http-source/logs-metrics/) + +By adding this endpoint to SIEM_URL, this will enable the automation-bridge logs to be forwarded to Sumo Logic Log Analytics / CIP ### Bridge ALIAS -With bridge ALIAS, it is possible to distinguish which integration resources will be executed with this automation bridge. When a new integration resource is created or edited, it is possible to select the default ALIAS or to create a new one. So every automatic action configured to use this resource will be performed with the Bridge that has the same ALIAS. +With bridge ALIAS, it is possible to distinguish which integration resources will be executed with this automation bridge. When a new integration resource is created or edited it is possible to select the default ALIAS or to create a new one. So every automatic action configured to use this resource will be performed with the Bridge that has the same ALIAS. -Create ALIAS bridge +Create ALIAS bridge -Use default ALIAS bridge +Use default ALIAS bridge ### Automation bridge update -For Ubuntu and CentOS/RedHat, the update process works as the installation process. Follow the same steps described in [Automation bridge installation](#automation-installation) above. +For Ubuntu and CentOS/RedHat, the update process works as the installation process. Follow the same steps described in [Automation bridge installation](#automation-bridge-installation) above. :::note If you are not using the SIEM: 1. Set `SIEM_URL` to `NONE`. 1. Restart the service with: - ```sh + ``` systemctl restart automation-bridge ``` 1. If you need to allow automation-bridge communication through a proxy, edit the file `/etc/opt/automation-bridge/automation-bridge.conf` and set the correct value. Below is an example: - ```sh - HTTP_PROXY="http://proxy.example.com:8080" - HTTPS_PROXY="http://proxy.example.com:8080" + ``` + HTTP_PROXY="http://proxy.example.com:8080\" + HTTPS_PROXY="http://proxy.example.com:8080\" ``` 1. Restart the service with: - ```sh + ``` systemctl restart automation-bridge ``` ::: ### Configuring the automation bridge for high availability -You may elect to deploy and register multiple bridges to your Cloud SOAR tenant for high availability. To cluster automation bridges together logically within Cloud SOAR and ensure high availability, you must set the same ALIAS for each bridge within the cluster in each respective `user-configuration.conf` file upon installation. +You may elect to deploy and register multiple bridges to your tenant for high availability. To cluster automation bridges together logically within the Automation Service and ensure high availability, you must set the same ALIAS for each bridge within the cluster in each respective `user-configuration.conf` file upon installation. When multiple bridges are registered with the same ALIAS, they will appear as active. If one or more bridges within the cluster go offline, playbooks will execute via the active nodes utilizing the same ALIAS. So long as there is parity between the nodes and there is at least one active node registered, there will be no disruption in playbook execution. @@ -177,11 +178,11 @@ To check if the bridge is running correctly, run the following command: ps faux |grep automation-bridge ``` -This is an example of running `automation-bridge`:
Example of running automation-bridge +This is an example of running `automation-bridge`:
Example of running automation-bridge + +On the **Bridge** tab in the [Automation Service UI](/docs/platform-services/automation-service/about-automation-service/#automation-service-ui), a list of live bridge agents will be displayed along with their status. -On the SOAR instance, a list of live bridge agents will be displayed along with their status: -1. Click the gear icon Settings menu icon in the top right, select **Automation**, and then select **Bridge** in the left nav bar. -1. Verify that the bridge is installed and operational. +Bridge screen ### Configuring the automation bridge for CyberArk @@ -195,13 +196,13 @@ If you are using CyberArk, you must add the following certificates provided by C #### Enable Podman socket 1. Run the following commands: - ```bash - systemctl enable podman.socket && systemctl start podman.socket - ``` + ```bash + systemctl enable podman.socket && systemctl start podman.socket + ``` 1. Create a symbolic link: - ```bash - ln -s /run/podman/podman.sock /var/run/docker.sock - ``` + ```bash + ln -s /run/podman/podman.sock /var/run/docker.sock + ``` #### Change automation bridge configuration @@ -219,7 +220,7 @@ ExecStop=/bin/kill -s TERM $MAINPID Restart=on-failure TimeoutStartSec=10 RestartSec=10 - +## NoNewPrivileges=yes PrivateTmp=yes PrivateDevices=yes @@ -232,25 +233,25 @@ WantedBy=multi-user.target This is the current solution and it needs to run service as `root`. ::: -## Cloud SOAR automation bridge for Docker +## Automation bridge for Docker -This repository provides Docker images to run the Sumo Logic Cloud SOAR automation bridge. The images contain an automation bridge able to connect to the Sumo Logic SOAR environment. +This repository provides Docker images to run the Sumo Logic automation bridge. The images contain an automation bridge able to connect to the Automation Service environment. ### Use the Docker automation bridge image There are images tagged `latest` and for specific versions to run the automation bridge. -When run, the automation bridge listens on the Docker Unix socket to be able to execute the Cloud SOAR integration or run a standalone daemon. +When run, the automation bridge listens on the Docker Unix socket to be able to execute the integration or to run a standalone daemon. -The Cloud SOAR automation bridge needs to be able to communicate with the Docker API to work. +The automation bridge needs to be able to communicate with the Docker API to work. ### Prerequisites and configuration -|Environment Variable |Description |Default | -|:--|:--|:--| -|`API_URL_HERE` |To determine which is the correct SOAR_URL, see [Sumo Logic Endpoints by Deployment and Firewall Security](/docs/api/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) and get the URL under the API Endpoint column. For example: `https://api.eu.sumologic.com/api/` | | -|`SOAR_TOKEN_HERE`|Log in to Sumo Logic and create a new [installation token](/docs/manage/security/installation-tokens/) with the name prefix `csoar-bridge-token`. | | -|`SIEM_URL_HERE` | The HTTP Sumo Logic collector to send the bridge logs. | NONE | +|Environment Variable |Description |Default | +|:------------------------------------|:---------------|:----------| +|`API_URL_HERE` | To determine which is the correct SOAR_URL, see [Sumo Logic Endpoints by Deployment and Firewall Security](/docs/api/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) and get the URL under the API Endpoint column. For example: `https://api.eu.sumologic.com/api/` | | +|`SOAR_TOKEN_HERE` | Log in to Sumo Logic and create a new [installation token](/docs/manage/security/installation-tokens/) with the name prefix `csoar-bridge-token`. | | +|`SIEM_URL_HERE` | The HTTPS Source Endpoint URL From a Hosted Sumo Logic Collector | NONE | |`BRIDGE_ALIAS_HERE` | Provide the alias name. With bridge ALIAS, it is possible to distinguish which integration resources will be executed with this automation bridge. When a new integration resource is created or edited, it is possible to select the default ALIAS or to create a new one. So every automatic action configured to use this resource will be performed with the bridge that has the same ALIAS. | NONE | ### Methodologies @@ -275,15 +276,15 @@ public.ecr.aws/u5z5f8z6/sumologic/csoar-automation-bridge:latest In the DooD approach, you use the Docker daemon from the host system to interact with containers. Containers themselves do not have their own Docker runtime; they communicate with the host's Docker. This offers some distinct advantages, including simplicity in managing the containers and resource efficiency, as containers do not need to run their own Docker daemon. -This way, the main container will have access to the Docker socket and can start containers. The only difference is that instead of starting “child” containers, it will start “sibling” containers. +This way, the main container will have access to the Docker socket and will, therefore, be able to start containers. The only difference is that instead of starting “child” containers, it will start “sibling” containers. ![Mounting Docker socket](https://cdn.hashnode.com/res/hashnode/image/upload/v1693178230450/3b5e8d84-a6e6-40b9-acce-8b2f623e67be.png?auto=compress,format&format=webp) -It's useful to share pulled images with all bridges running on the host machine. +It's useful to sharing pulled image with all bridges running on host machine. #### With privileged option - ```bash +```bash docker run -d \ --privileged \ -e SOAR_URL=API_URL_HERE \ @@ -293,7 +294,7 @@ docker run -d \ -e DOCKER_TLS_CERTDIR=/certs \ -v docker-certs-ca:/certs/ca -v docker-certs-client:/certs/client \ public.ecr.aws/u5z5f8z6/sumologic/csoar-automation-bridge:latest - ``` +``` Privileged containers are special containers with elevated privileges and direct access to the host system. Unlike their non-privileged counterparts, which are isolated and restricted in their capabilities, privileged containers can perform tasks requiring higher-level access. They achieve this by interacting with the host kernel and accessing sensitive resources, including hardware devices and network interfaces. From b174fc0b4ad721358ff9c6a90dec260ae6cbdf80 Mon Sep 17 00:00:00 2001 From: John Pipkin Date: Fri, 26 Jul 2024 10:09:59 -0500 Subject: [PATCH 2/2] Updates from review --- docs/cloud-soar/cloud-soar-bridge.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/cloud-soar/cloud-soar-bridge.md b/docs/cloud-soar/cloud-soar-bridge.md index 769ef78d26..7eab53c310 100644 --- a/docs/cloud-soar/cloud-soar-bridge.md +++ b/docs/cloud-soar/cloud-soar-bridge.md @@ -25,7 +25,7 @@ You can only run custom actions or integrations outside of the Sumo Logic cloud ### Network requirements -The Bridge has to be able to resolve DNS hostnames and needs to reach the below destinations +The Bridge has to be able to resolve DNS host names and needs to reach the below destinations: | DESTINATION | PROTOCOL | PORT | | :-- | :-- | :-- | @@ -81,7 +81,7 @@ The Bridge has to be able to resolve DNS hostnames and needs to reach the below ## Get installation token -Login to Sumo Logic and create a new [installation token](/docs/manage/security/installation-tokens/) with name prefix `csoar-bridge-token`. +Log in to Sumo Logic and create a new [installation token](/docs/manage/security/installation-tokens/) with name prefix `csoar-bridge-token`. Installation token @@ -89,7 +89,7 @@ Login to Sumo Logic and create a new [installation token](/docs/manage/security/ ### Ubuntu -1. In the main Sumo Logic menu, select **Automation** and then click the **?** icon in the top right. +1. Click the **?** icon in the top right. 1. In the **Automation Bridge Manual** box, click **UBUNTU**. 1. Click **Download** to download the `automation-bridge-X.X.deb` file. 1. Copy the file to the bridge virtual machine. @@ -100,7 +100,7 @@ Login to Sumo Logic and create a new [installation token](/docs/manage/security/ ### CentOS/RedHat -1. In the main Sumo Logic menu, select **Automation** and then click the **?** icon in the top right. +1. Click the **?** icon in the top right. 1. In the **Automation Bridge Manual** box, click **CENTOS/REDHAT**. 1. Click **Download** to download the `automation-bridge-X.X.rpm` file. 1. Copy the file to the bridge virtual machine. @@ -128,10 +128,9 @@ An example of a configuration file would be: "ALIAS":"YOUR_ALIAS_NO_SPACES_LESS_THAN_20_CHARACTERS" } ``` -To create a Hosted Sumo Logic Collector See: [Sumo Logic Hosted Collector](/docs/send-data/hosted-collectors/) -To add an HTTPS Source to a Hosted Collector See: [Sumo Logic HTTP Logs and Metrics Source](https://help.sumologic.com/docs/send-data/hosted-collectors/http-source/logs-metrics/) +To create a Hosted Sumo Logic Collector, see [Hosted Collectors](/docs/send-data/hosted-collectors/). To add an HTTPS Source to a Hosted Collector, see [HTTP Logs and Metrics Source](/docs/send-data/hosted-collectors/http-source/logs-metrics/). -By adding this endpoint to SIEM_URL, this will enable the automation-bridge logs to be forwarded to Sumo Logic Log Analytics / CIP +By adding this endpoint to `SIEM_URL`, this will enable the automation-bridge logs to be forwarded to Sumo Logic Log Analytics. ### Bridge ALIAS @@ -251,7 +250,7 @@ The automation bridge needs to be able to communicate with the Docker API to wor |:------------------------------------|:---------------|:----------| |`API_URL_HERE` | To determine which is the correct SOAR_URL, see [Sumo Logic Endpoints by Deployment and Firewall Security](/docs/api/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) and get the URL under the API Endpoint column. For example: `https://api.eu.sumologic.com/api/` | | |`SOAR_TOKEN_HERE` | Log in to Sumo Logic and create a new [installation token](/docs/manage/security/installation-tokens/) with the name prefix `csoar-bridge-token`. | | -|`SIEM_URL_HERE` | The HTTPS Source Endpoint URL From a Hosted Sumo Logic Collector | NONE | +|`SIEM_URL_HERE` | The HTTPS Source endpoint URL from a hosted Sumo Logic Collector. | NONE | |`BRIDGE_ALIAS_HERE` | Provide the alias name. With bridge ALIAS, it is possible to distinguish which integration resources will be executed with this automation bridge. When a new integration resource is created or edited, it is possible to select the default ALIAS or to create a new one. So every automatic action configured to use this resource will be performed with the bridge that has the same ALIAS. | NONE | ### Methodologies @@ -280,7 +279,7 @@ This way, the main container will have access to the Docker socket and will, the ![Mounting Docker socket](https://cdn.hashnode.com/res/hashnode/image/upload/v1693178230450/3b5e8d84-a6e6-40b9-acce-8b2f623e67be.png?auto=compress,format&format=webp) -It's useful to sharing pulled image with all bridges running on host machine. +It's useful to share the pulled image with all bridges running on the host machine. #### With privileged option