Secure State Integrations

This content has moved and will no longer be updated. Please go to https://docs.vmware.com/en/CloudHealth-Secure-State/ for the latest version. Please see the latest What's new for the more details about the move.

Last updated on February 10, 2022

Introduction

CloudHealth Secure State integrations allow users to incorporate third party applications like Slack, Splunk, SQS and more into the Secure State workflow for monitoring, alerting, and remediating misconfigurations.

About integrations

Secure State is designed as an open platform that meets you where you are. Whether you plan to use it as the central hub for monitoring and tracking cloud security issues across your entire or organization or as one more tool in a larger security framework, integrations let you fit Secure State into your organization the way you need it to.

Secure State integrations are categorized by how they handle data, and what they can help you do.

Inbound integrations receive security findings from other sources (like Amazon GuardDuty) so you can review them directly in Secure State, building a more complete overview of your organization's security posture. With inbound integrations, you don't need to look at multiple tools to understand your security risks.

Outbound integrations send data from Secure State to an external application. These integrations are often used to create notifications and build them into your existing processes and tools so that you stay current, lean, and responsive to potential threats.

Configuring an integration

Review these instructions for information on whether an integration is useful for your organization and how to enable it. You can disable these integrations at any time if needed, see Managing an integration for specific directions.

Inbound integrations

Amazon GuardDuty

When enabled for an AWS cloud account, this integration allows Secure State to ingest and display third-party findings for that account from the Amazon GuardDuty service.

For convenience this integration is automatically created when you onboard a new AWS cloud account, but it must still be enabled to receive findings from GuardDuty. Review Third-party findings for more details.

Azure Security Center

When enabled for an Azure cloud account, this integration allows Secure State to ingest and display third-party findings for that account from Azure Security Center.

For convenience this integration is automatically created when you onboard a new Azure cloud account, but it must still be enabled to receive findings from Security Center. Review Third-party findings for more details.

Outbound integrations

Email

You can configure monitoring alerts to send you an email notification when Secure State detects a security misconfiguration.

If you have an account in Secure State, then the integration is already active, and should be available to select when creating a new alert.

Jira Cloud

The Secure State Jira Cloud integration can be used to create issues from security findings, where they can be tracked and resolved through your team's existing ticketing framework.

  1. From your Secure State dashboard, navigate to Settings > Integrations.
  2. Under Jira Cloud, select Add New.
  3. Enter the following required values:
    • Integration name - Choose a name for your integration.
    • Username - Enter the email address you use to log in to your Jira organization.
    • API token - Click on the provided API token link to create a token with Jira. Copy the value into this field.
    • Organization name - You can find the organization name in the URL for your Jira Cloud page, which should be yourcompany.atlassian.net. In this case, the organization name would be "yourcompany".
    • Project key - The project key is the prefix you have your issue IDs. For example, if your "JRA-123" is how your organization assigns IDs, the JRA is the project key.
    • Issue type - Your options for this field depend on which issue types your organization supports. See the documentation Jira Cloud Issue Types for more information.
    • Custom fields - This field is optional, but allows you to add important information unique to your organization as key:value pairs, where the key should be the value for your custom field's key property and the value is whatever you need to enter under for the field. For example, a custom field for Requestors might be entered as "<Requestor Key Value>:<Requestor1>, <Requestor2>...". To gather all fields used in your project, use this API - https://your-domain.atlassian.net/rest/api/3/field.
  4. If you're an organization admin, you can select the context (Organization or Project) you want the integration to have access to on the next page.
  5. Click Test to verify a working connection, then click Save.

After you've set up the integration, you must create an alert to begin creating issues from rules violations.

Slack

If you have a Slack workspace, the Secure State integration lets you receive real-time alerts about security findings on a specific slack channel. You can set up one integration per Slack workspace.

  1. From your Secure State dashboard, navigate to Settings > Integrations 2.0.
  2. Under Slack, select Add New.
  3. Enter the name of your integration. You may toggle the Enable switch to activate the integration after saving or leave it as-is and enable it later.
  4. If you're an organization admin, you'll be prompted to select the context you want the integration to have access to (Organization or Project).
  5. Once you've made your choices, click Get Auth, then Allow on the pop-up screen to connect your Slack Workspace with Secure State.
  6. On the next step, enter the name of the slack channel you want to send a test message to (it must be a public channel) and click Test to verify the connection.
  7. Once you've confirmed the integration is working, click Save.

If your channel isn't receiving test messages, make sure it's public and that the authorization in step 5 was successful. You may need to cancel the process and start over.

Splunk

The Splunk integration sends security findings from Secure State to an S3 bucket, where they can be incorporated into your Splunk instance like any other data.

  1. From your Secure State dashboard, Navigate to Settings > Integrations 2.0.

  2. Under Splunk, select Add New.

  3. Enter the name of your integration and the name of the S3 bucket you want to associate, and the S3 object prefix if desired. You may toggle the Enable switch to activate the integration after saving or leave it as-is and enable it later.

  4. If you're an organization admin, you'll be prompted to select the context you want the integration to have access to (Organization or Project).

  5. Follow the instructions to generate a new IAM role and enter both the IAM role ARN and external ID. Refer to the AWS IAM tutorial if you need more specific instructions to create an IAM role.

    Note: The external ID must be at least 16 characters long.

  6. Click Test to verify a successful connection between the integration and your Splunk instance.

  7. After receiving a successful response, click Save.

SQS

Secure State can integrate with AWS SQS to send findings to an SQS queue. From there, you can set up automatic actions like cloud functions and application triggers based on specific security findings.

  1. From your Secure State dashboard, navigate to Settings > Integrations 2.0.

  2. Under SQS, select Add New.

  3. Enter the name of your integration and the SQS URL from your AWS portal.

  4. If you're an organization admin, you'll be prompted to select the context you want the integration to have access to (Organization or Project).

  5. Follow the instructions to generated a new IAM role and enter both the IAM role ARN and external ID. Refer to the AWS IAM tutorial if you need more specific instructions to create an IAM role.

    Note: The external ID must be at least 16 characters long.

  6. Click Test to verify a successful connection between the integration and your SQS queue.

  7. After receiving a successful response, click Save.

Webhook

You can use the webhook integration to send security findings to a URL destination in a custom format (JSON, XML, HTML, plain text, and so on). This lets you send findings data to third-party applications that don't have a specific integration for Secure State as long as they can process the custom format. Microsoft Teams, ServiceNow, and PagerDuty are just a few examples of the services you can include in your security posture through webhook integration.

  1. From your Secure State dashboard, navigate to Settings > Integrations.

  2. Under Webhook, select Add New.

  3. Enter the following information:

    • Integration name: This is the name of your integration.
    • Headers: Any headers you need to include with your requests, such as authorization or content types, are entered here in key:value format. An example would be content-type:application/json.
    • URL: Enter the URL destination you want to send findings data to.
  4. Click Enable if you want this integration to be active immediately upon saving.

  5. Select the Template you want to use for your finding data. Secure State currently offers three pre-made templates, one for generic use, and two others for Microsoft Teams and PagerDuty, respectively. You can also create a custom template; see the content after these instructions for more details.

    Note: If implementing the Microsoft Teams template, you may want to review the supporting Microsoft Teams documentation for creating an incoming webhook.

  6. Click Next.

  7. If you're an organization admin, you'll be prompted to select integration's context (Organization or Project).

  8. Click Test to verify a successful connection between the integration and your receiving URL. All headers attached to the request appear in the preview window available on this screen.

  9. After receiving a successful response, click Save.

Create a custom webhook template

Secure State's webhook templates are written in the Mustache format. If you want to create your own template, you should review the official Mustache documentation here in addition to these instructions.

This JSONC data structure for a single alert lists all the available input fields you can use when constructing your Mustache template, with descriptions in the comments:

{
    "Name": "SecureState Alert 1", // Name of your alert.
    "Message": "This is a SecureState Alert", // Additional message sent to the recipient.
    "Findings": [
        // A list of findings related to the alert.
        {
            "ID": "00000000-0000-0000-0000-000000000000", // Unique ID for the finding.
            "RuleDisplayName": "Azure AD group has administrator access", // Public name of the rule for the triggered finding.
            "RuleName": "azure-active-directory-group-admin-access", // Database name of the rule for the triggered finding.
            "RuleService": "ActiveDirectory", // Service type of the triggered finding.
            "RuleSeverity": "Medium", // Severity of the triggered finding (High, Medium, or Low).
            "CloudAccountID": "00000000-0000-0000-0000-000000000000", // ID of the cloud account where your affected resource resides.
            "CloudAccountName": "azure-active-directory-group-admin-access", // Name of the cloud account where your affected resource resides.
            "CloudAccountEnvironment": "development", // The environment type assigned to the cloud account in Secure State (Example: production, development).
            "CloudAccountProjectID": "00000000-0000-0000-0000-000000000000", // ID of the Secure State project where the cloud account resides.
            "Source": "Native", // Specifies if the finding is from a native or third-party rule.
            "Provider": "azure", // Provider associated with the cloud account where the affected resource resides.
            "Service": "ActiveDirectory", // Service type of the affected resource.
            "Region": "global", // Region of the affected resource.
            "RiskScore": 40, // Risk score of the finding.
            "Tags": [
                // A list of tags associated with affected resource.
                {
                    "Key": "Owner", // Name of the tag.
                    "Value": "user@vmware.com", // Value of the tag.
                    "Last": false // Indicates the last tag in the list.
                }
            ],
            "Timestamp": "2020-01-01T12:00:00.000Z", // Time stamp from when the event was observed.
            "Last": false // Indicates the last finding in the list. Can be used with the {{ >comma }} Mustache partial.
        }
    ]
}

When creating your own template, you can add any of the input variables described above with the format {{ Variable }}.

Note that the Findings and Tags fields are arrays of objects. One of the challenges with using a Mustache template to generate valid JSON payloads for your webhook integration is adding commas after each object in an array. To resolve that, Secure State has added the {{ >comma }} partial for use with any data type in a Mustache template that includes the Last boolean field. This screenshot demonstrates how the partial is used:

Note: For the template to render correctly, all finding properties must be added after {{ #Findings }} and before {{ >comma }} {{ /Findings }}. See the following screenshot for an example of correct usage.

Alert JSON

You can add a custom template by either writing or pasting it into the Template field. When you do this, Secure State creates a third template with the label "Custom". This action doesn't change the generic or Microsoft Teams templates, regardless of which one you have selected at the time.

Only one custom template is supported per individual webhook integration, and any change made in the Template field immediately overwrites previously saved custom content. To prevent losing information, save a copy of your custom template in a secure location.

Webhook examples

This section demonstrates just some of the different types of webhook integrations you can create.

PagerDuty

You can use webhook to automatically export findings as PagerDuty incidents with these examples as a reference. All you need from PagerDuty is an API auth token.

  1. Create an auth token in PagerDuty.

  2. Create a new webhook integration in Secure State:

    Headers

    • Accept: application/vnd.pagerduty+json;version=2
    • Authorization: Token token <token>
    • Content-Type: application/json
    • From: Securestate@vmware.com

    URL: https://api.pagerduty.com/incidents

    Template: Select the PagerDuty template and customize to your preference as necessary.

  3. Test and validate the incident received in PagerDuty.

    PagerDuty Validation

  4. Set up alerts and receive real-time incident reporting in your PagerDuty service.

    PagerDuty Alert

Managing an integration

You can manage your integrations by going to Settings > Integrations 2.0 from your Secure State dashboard and clicking View Details below your desired integration service. This displays all the integrations currently in Secure State for a given service. From this screen you can decide whether to enable, disable, or delete individual integrations. When you disable an integration, it stops sending or receiving data until you enable it again. Note that inbound integrations for Amazon GuardDuty and Azure Security Center can't be deleted, only disabled. Depending on the integration service you can also view any alerts you've created, or edit configuration options for a specific integration.