Last updated on February 10, 2022
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.
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.
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.
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.
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.
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.
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.
After you've set up the integration, you must create an alert to begin creating issues from rules violations.
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.
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.
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.
From your Secure State dashboard, Navigate to Settings > Integrations 2.0.
Under Splunk, select Add New.
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.
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).
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.
Click Test to verify a successful connection between the integration and your Splunk instance.
After receiving a successful response, click Save.
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.
From your Secure State dashboard, navigate to Settings > Integrations 2.0.
Under SQS, select Add New.
Enter the name of your integration and the SQS URL from your AWS portal.
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).
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.
Click Test to verify a successful connection between the integration and your SQS queue.
After receiving a successful response, click Save.
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.
From your Secure State dashboard, navigate to Settings > Integrations.
Under Webhook, select Add New.
Enter the following information:
Click Enable if you want this integration to be active immediately upon saving.
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.
Click Next.
If you're an organization admin, you'll be prompted to select integration's context (Organization or Project).
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.
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.
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.
Create an auth token in PagerDuty.
Create a new webhook integration in Secure State:
Headers
URL: https://api.pagerduty.com/incidents
Template: Select the PagerDuty template and customize to your preference as necessary.
Test and validate the incident received in PagerDuty.
Set up alerts and receive real-time incident reporting in your PagerDuty service.
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.