Build custom integrations

This document explains the workflows for building custom integrations for Google SecOps. The current best practice is to develop integrations locally using your preferred IDE and manage them via GitHub using modern GitOps workflows. For legacy environments or quick prototypes, you can also build integrations directly inside the built-in SOAR IDE.

Local IDE & GitHub workflow (recommended)

Developing integrations locally and managing them via GitHub is the recommended workflow. This approach aligns with modern GitOps practices, allowing for better version control, collaboration, and automated dependency management.

Conceptual workflow overview

To develop custom integrations locally, it is recommended that you follow this GitOps lifecycle. For the exact, up-to-date syntax of these commands, see the official MP CLI documentation on GitHub.

1. Fork and clone: Clone the official content-hub repository to your local development machine.
2. Install tools: Install the mp CLI tool and the uv Python package manager.
3. Authenticate: Log in to your Google SecOps environment via the MP CLI using your instance URL and API keys.
4. Develop locally: Use your preferred IDE (like VS Code or PyCharm) to write your integration code, taking advantage of local debugging and testing tools.
5. Manage dependencies: Use uv to declare and manage dependencies (like TIPCommon) in your local pyproject.toml file.
6. Synchronize: Use mp pull and mp push commands to synchronize your local code with your Google SecOps instance for testing and deployment.

Alternative: Create a custom integration in the built-in IDE

If you are maintaining legacy integrations, testing a script quickly, or working in an environment where local development is restricted, you can use the built-in IDE.

Use case: Build a custom Armis integration

To create the custom integration in the IDE, follow these steps:

1. In the main menu, go to Response > IDE.
2. Click addCreate New Item and select Integration.
3. Enter a name and click Create.

The integration is now listed with the settings Settings option, indicating it's a custom integration.

Click settings Settings to display the integration settings where you can define the icon, description, Python dependencies, and integration parameters.

Create a custom manager

Managers are wrappers for third-party tool APIs. Although not mandatory, we recommend them for integrations that interact with external tools. Managers shouldn't import from the SDK. After creation, import them into connectors, actions, and jobs.

To create a custom manager, follow these steps:

1. In the IDE, click addCreate New Item and select Manager.
2. Select the Armis integration and enter a manager's name.
   
3. Edit and run the following script:

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) The response to validate
       :param error_msg: (str) The error message to display
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

Parameters, Google SecOps Content Hub configuration, and the Ping action

Parameters defined in the integration settings appear in the Google SecOps Content Hub configuration. The parameters include:

• API Root: The base URL for the service you're connecting to.
• API Secret: A confidential key used to authenticate your application with the service.
• Verify SSL checkbox: If enabled, verifies that the SSL certificate for the connection to the Armis server is valid.
• Run Remotely checkbox: A setting that determines whether the code or task will be executed on a remote server instead of locally. When this option is enabled, the system sends the necessary instructions and data to a dedicated server for processing.

To update the parameters, follow these steps:

1. Enter the correct credentials.
2. Click Save > Test.

If the Ping action is missing, the Test button fails and displays a red X.

Implement a Ping action

The logic of the Ping action acts like a successful authentication.

To implement a Ping action, do the following:

1. In the IDE, create a new Action in the Armis integration named Ping.
2. Use the ArmisManager auth method to verify authentication.

Enable the integration

To enable the integration, follow these steps:

1. In Response > IDE, click the Enable/Disable toggle to the ON position.
2. Click Save. A green toggle confirms success. Credentials from the Content Hub are passed to ArmisManager. If auth completes without errors, the Test button shows a green checkmark.

Use the extract_configuration_param method to import parameters from the integration configuration. Alternatively, use extract_action_param to define parameters within the action itself. However, the Ping action should always use configuration parameters, as those are tested by the Content Hub.

View custom integrations

Go to the Content Hub and search for the custom integration you created. If you didn't create an image during the initial configuration, the default custom image will be assigned to it. Note that Content Hub updates don't override or delete any custom integrations.

Export and import in the IDE

Do one of the following actions:

• To import integrations, do the following:
1. Upload a ZIP file with the correct folder structure; the integration appears in the IDE and the Content Hub.
2. Click Import. The integration appears in both the IDE and the Content Hub.
3. The system generates a ZIP file containing the definition, scripts, and configuration. The Managers folder is not included automatically.
• To export integrations, do the following:
• Click Export to download the package.