aws-securityhubv2-bot

AWS Lambda bot that processes AWS Security Hub v2 findings with configurable auto-close rules and optional Slack notifications.

Important: Security Hub v2 only (OCSF format). Not directly compatible with original Security Hub CSPM (ASFF format).

Features

• auto-close rules - suppress/resolve findings via JSON filters (type, severity, tags, accounts, regions)
• optional slack - rich notifications with context and remediation links
• flexible config - environment variables or S3 for rule storage
• multi-service - GuardDuty, Inspector, Macie, IAM Access Analyzer, Security Hub CSPM

---

Quick Start

Build

mkdir -p dist
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -C cmd/lambda -o ../../dist/bootstrap
cd dist && zip deployment.zip bootstrap && cd ..

Deploy Lambda

1. IAM role with AWSLambdaBasicExecutionRole + securityhub:BatchUpdateFindingsV2
2. Create function using deployment.zip (runtime: provided.al2023, handler: bootstrap)
3. EventBridge rule targeting the Lambda:

   {
     "source": ["aws.securityhub"],
     "detail-type": ["Findings Imported V2"]
   }

4. Configure using environment variables below

---

Configuration

Auto-Close Rules

Name	Description
APP_AUTO_CLOSE_RULES	JSON array of auto-close rules (see examples)
APP_AUTO_CLOSE_RULES_S3_BUCKET	S3 bucket for rules (for large rule sets)
APP_AUTO_CLOSE_RULES_S3_PREFIX	S3 prefix for rules (default: rules/)

Use environment variables, S3, or both. Environment rules evaluated first.

Slack (Optional)

Name	Description
APP_SLACK_TOKEN	Bot token with chat:write scope
APP_SLACK_CHANNEL	Channel ID (e.g., C000XXXXXXX)

Additional

Name	Description
APP_DEBUG_ENABLED	Verbose logging (default: false)
APP_AWS_CONSOLE_URL	Base console URL
APP_AWS_ACCESS_PORTAL_URL	Federated access portal URL
APP_AWS_ACCESS_ROLE_NAME	IAM role for portal
APP_AWS_SECURITYHUBV2_REGION	Centralized SecurityHub region

---

Examples

Basic Rule: Suppress GitHub Runner Findings

[
  {
    "name": "auto-close-github-runners",
    "enabled": true,
    "filters": {
      "finding_types": ["Execution:Runtime/NewBinaryExecuted"],
      "resource_tags": [{"name": "component-type", "value": "github-action-runners"}]
    },
    "action": {
      "status_id": 5,
      "comment": "Auto-archived: Expected CI/CD behavior"
    },
    "skip_notification": true
  }
]

See examples/github-actions-runner-example.md for detailed walkthrough.

Multiple Rules

[
  {
    "name": "suppress-inspector-low-dev",
    "filters": {
      "product_name": ["Inspector"],
      "severity": ["Low"],
      "accounts": ["123456789012"]
    },
    "action": {"status_id": 3, "comment": "Auto-suppressed: Low severity in dev"},
    "skip_notification": false
  },
  {
    "name": "resolve-approved-scans",
    "filters": {
      "finding_types": ["Recon:EC2/PortProbeUnprotectedPort"],
      "resource_tags": [{"name": "ScannerApproved", "value": "true"}]
    },
    "action": {"status_id": 4, "comment": "Auto-resolved: Approved scanner"},
    "skip_notification": true
  }
]

Filter Reference

All filters use AND logic. First matching rule wins.

Field	Type	Example
finding_types	[]string	["Execution:Runtime/NewBinaryExecuted"]
severity	[]string	["Critical", "High"]
product_name	[]string	["GuardDuty", "Inspector"]
resource_types	[]string	["AWS::EC2::Instance"]
resource_tags	[]object	[{"name": "Environment", "value": "dev"}]
accounts	[]string	["123456789012"]
regions	[]string	["us-east-1"]

Status IDs

Based on OCSF 1.6.0 specification:

ID	Status	Description
0	Unknown	The status is unknown
1	New	The finding is new and yet to be reviewed
2	In Progress	The finding is under review
3	Suppressed	The finding was reviewed, determined to be benign or false positive, suppressed
4	Resolved	The finding was reviewed, remediated and is now considered resolved
5	Archived	The finding was archived
6	Deleted	The finding was deleted (e.g., created in error)
99	Other	The status is not mapped (see status attribute for source-specific value)

Common usage: status_id: 5 (Archived) for accepted behavior, status_id: 4 (Resolved) for remediated issues, status_id: 3 (Suppressed) for false positives.

S3 Rule Storage

For large rule sets (>4KB), store rules in S3. Supports single rule per file, arrays of rules, or mixed approach:

s3://my-rules-bucket/rules/
├── guardduty/
│   └── suppress-dev.json
├── inspector/
│   └── all-rules.json
└── auto-close-runners.json

Requirements: Lambda needs s3:GetObject and s3:ListBucket on the bucket. Only .json files processed.

---

EventBridge Filters (Optional)

Filter by severity for high-volume environments:

{
  "source": ["aws.securityhub"],
  "detail-type": ["Findings Imported V2"],
  "detail": {
    "findings": {
      "severity": ["Critical", "High"]
    }
  }
}

Or by source service:

{
  "detail": {
    "findings": {
      "metadata": {
        "product": {
          "name": ["GuardDuty", "Inspector"]
        }
      }
    }
  }
}

---

IAM Permissions

Lambda role needs AWSLambdaBasicExecutionRole plus:

{
  "Effect": "Allow",
  "Action": ["securityhub:BatchUpdateFindingsV2"],
  "Resource": "*"
}

If using S3 rules, add:

{
  "Effect": "Allow",
  "Action": ["s3:GetObject", "s3:ListBucket"],
  "Resource": [
    "arn:aws:s3:::my-rules-bucket",
    "arn:aws:s3:::my-rules-bucket/*"
  ]
}

---

How It Works

1. EventBridge triggers Lambda on "Findings Imported V2"
2. Parse OCSF finding from event
3. Evaluate auto-close rules in order (first match wins)
4. If matched: call BatchUpdateFindingsV2 with status + comment
5. Send Slack notification (unless skip_notification: true)
6. If no match: send to Slack if finding is alertable

---

Local Development

cp .env.example .env  # edit values
go run -C cmd/sample .

Uses OCSF findings from fixtures/samples.json. Requires AWS credentials for auto-close testing.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.