aws-securityhub-findings-to-msteams

Demonstrates sending AWS Security Hub findings to your Microsoft Teams channel.

The template Installs a Lambda function and an EventBridge Rule that sends events to a Microsoft Teams incoming web hook. This relies on you creating an Incoming WebHook in your Microsoft Teams account and simply passing the URL as a parameter to this template. By default, the EventBridge Rule is configured to look for Custom Actions in Security Hub:

{
  "resources": ["arn:aws:securityhub:REGION:ACCOUNTNO:action/custom/SendToMSTeams"],
  "source": ["aws.securityhub"]
}

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

Implementation

Manual notifications

Follow Section 1 and Section 2 to set up the manual method of send findings to MS Teams

Automatic notifications

Alternatively, complete Section 1 and Section 3 to AUTOMATICALLY send all NEW CRITICAL and HIGH findings to MS Teams. You can limit this to only send events with a certain label type e.g. CRITICAL and HIGH.

Section 1 - Prerequisites and deployment

1. Prerequisites

   • AWS Security Hub is enabled
   • Sufficient permissions in an MS Teams channel to create incoming WebHooks.

2. Create an incoming Webhook in the Microsoft Teams API

   • Follow Microsoft's instructions on how to create a Webhook (https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook)
   • Note down the URL e.g. https://CUSTOMER.webhook.office.com/webhookb2/12341234-abcd-1234-abcd-1234123412341234/IncomingWebhook/CODE/UUID for use later.

3. Launch Cloud Formation Template
   This CloudFormation template will create a Lambda Function that utilizes MS Teams' Webhook API feature, as well as a EventBridge Rule to send findings from Security Hub’s custom actions to MS Teams.

   • Download CloudFormation template by right clicking on “SecurityHubFindingsToMSTeams.yaml” and “Save Link As..” on your local machine
   • Navigate to https://console.aws.amazon.com/cloudformation/
   • Select Create stack
   • Select Upload a template file
   • Select Choose file and locate “SecurityHubFindingsToMSTeams.json” on your local machine
   • Select Next
   • Use the following values to fill out Create Stack parameters

       StackName: EnableSecurityHubFindingsToMSTeams  
       IncomingWebHookURL: Paste URL that you just copied from MS Teams API pages  
   

   • Select Next, fill out any Tags and select Next again
   • Accept IAM Resource creation
   • Select Create Stack, CloudFormation will then begin creating the stack
   • Wait for the CloudFormation console to report stack creation complete

Continue to Section 2 or Section 3

Section 2 - Manual notification - Send to MS Teams Custom Action

1. Create Security Hub Custom Actions .
   • In the Security Hub navigation pane (https://console.aws.amazon.com/securityhub/) select Settings then choose the Custom Actions tab.
   • Select Create custom action.
   • Then in the Create custom action pop up, specify the action name, description and ID then choose OK to create the action.

        Name: Send to MS Teams  
        Description: This custom action sends selected findings to a channel in Microsoft Teams
        Custom action ID: SendToMSTeams
   

2. Testing the Send to MS Teams Custom Action
   • Navigate to AWS Security Hub Console (https://console.aws.amazon.com/securityhub/)
   • Navigate to Findings
   • Select the check box next to one or more findings
   • Click the drop-down Actions menu and choose the Send To MS Teams Custom Action

The Security Hub Console will then send the finding to your MS Teams channel, you should then receive a notification in your MS Teams channel

Section 3 - Automatic notification - All NEW CRITICAL and HIGH findings to Teams Channel

1. Go to EventBridge --> Rules
2. Search for the Rule called SecurityHubFindingsToMSTeams and click on it.
3. Click EDIT
4. Leave Event source as Other and skip the Sample event section.
5. Go to Event pattern and click the button labelled 'Custom patterns (JSON editor)
6. Paste in the following JSON (NOTE: This only notifies for NEW CRITICAL and HIGH events - you can add labels for "MEDIUM" and "LOW" as needed):

{
  "source": ["aws.securityhub"],
  "detail-type": ["Security Hub Findings - Imported"],
  "detail": {
    "findings": {
      "RecordState": ["ACTIVE"],
      "Severity": {
        "Label": ["CRITICAL", "HIGH"]
      },
      "Workflow": {
        "Status": ["NEW"]
      }
    }
  }
}

7. Click Next.
8. Leave the target as the existing Lambda function and click Next.
9. Add any relevant tags and click Next.
10. Click 'Update Rule'
11. The next time Security Hub identifies a non-compliant resource with a CRITICAL / HIGH severity it should now be sent to Microsoft Teams.
12. You can trigger a test by going into Security Hub and switching the workflow status to be different from "NEW" (e.g. "NOTIFIED" and then back to "NEW'.

Security Findings

This repository has been scanned by the following Static Application Security Testing (SAST) tools

npm-audit

NodeJS code has been copied to SecurityHubToTeams.js and scanned using npm-audit

main* $ npm audit fix

up to date, audited 1 package in 209ms

found 0 vulnerabilities

Checkov

Cloudformation has been scanned using Checkov.
The following four LOW severity findings have been supressed in the code:

Check: CKV_AWS_117: "Ensure that AWS Lambda function is configured inside a VPC"
Reason: Example code - ReservedConcurrentExecutions may be considered in a Production environment to guarantee Lambda is launched

FAILED for resource: AWS::Lambda::Function.lambdafindingsToMSTeams
Severity: LOW
File: /SecurityHubFindingsToMSTeams.yaml:74-224
Guide: https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-inside-a-vpc-1

---

Check: CKV_AWS_116: "Ensure that AWS Lambda function is configured for a Dead Letter Queue(DLQ)"
Reason: Example code - a Dead Letter Queue may be considered in a Production environment

FAILED for resource: AWS::Lambda::Function.lambdafindingsToMSTeams
Severity: LOW
File: /SecurityHubFindingsToMSTeams.yaml:74-224
Guide: https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-for-a-dead-letter-queue-dlq

---

Check: CKV_AWS_173: "Check encryption settings for Lambda environmental variable"
Reason: Example code - Encrypting Lambda environment variables using KMS should be considered in Production environment

FAILED for resource: AWS::Lambda::Function.lambdafindingsToMSTeams
Severity: LOW
File: /SecurityHubFindingsToMSTeams.yaml:74-224
Guide: https://docs.bridgecrew.io/docs/bc_aws_serverless_5

---

Check: CKV_AWS_115: "Ensure that AWS Lambda function is configured for function-level concurrent execution limit"
Reason: Example code - ReservedConcurrentExecutions may be considered in a Production environment to guarantee Lambda is launched

FAILED for resource: AWS::Lambda::Function.lambdafindingsToMSTeams
Severity: LOW
File: /SecurityHubFindingsToMSTeams.yaml:74-224
Guide: https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-for-function-level-concurrent-execution-limit

CFN_Nag

This has been scanned with CFN_Nag The following two WARNINGs severity findings have been supressed in the code:

Check: W89: "Lambda functions should be deployed inside a VPC"
Reason: Example code - Running a Lambda inside a VPC should be considered for a Production environment

| WARN W89
|
| Resource: ["lambdafindingsToMSTeams"]
| Line Numbers: [93]
|
| Lambda functions should be deployed inside a VPC

---

Check: W92: "Lambda functions should define ReservedConcurrentExecutions to reserve simultaneous executions" Reason: Example code - ReservedConcurrentExecutions may be considered in a Production environment to guarantee Lambda is launched

| WARN W92
|
| Resource: ["lambdafindingsToMSTeams"]
| Line Numbers: [93]
|
| Lambda functions should define ReservedConcurrentExecutions to reserve simultaneous executions