feat: create initial bot implementation

.editorconfig

@@ -0,0 +1,26 @@
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[{Dockerfile,Dockerfile.*}]
+indent_size = 4
+tab_width = 4
+
+[{Makefile,makefile,GNUmakefile}]
+indent_style = tab
+indent_size = 4
+
+[Makefile.*]
+indent_style = tab
+indent_size = 4
+
+[**/*.{go,mod,sum}]
+indent_style = tab
+indent_size = unset
+
+[**/*.py]
+indent_size = 4

.env.example

@@ -0,0 +1,16 @@
+APP_DEBUG_ENABLED=true
+APP_AWS_CONSOLE_URL=https://console.aws.amazon.com
+APP_AWS_ACCESS_PORTAL_URL=
+APP_AWS_ACCESS_ROLE_NAME=
+APP_AWS_SECURITYHUBV2_REGION=
+
+# Auto-close rules (JSON array) - optional
+# APP_AUTO_CLOSE_RULES='[{"name":"auto-close-runs-on-container-mounts","enabled":true,"filters":{"finding_types":["PrivilegeEscalation:Runtime/ContainerMountsHostDirectory"],"resource_tags":[{"name":"provider","value":"runs-on.com"}]},"action":{"status_id":5,"comment":"Auto-closed: Expected behavior for runs-on.com ephemeral runners"},"skip_notification":true}]'
+
+# Auto-close rules from S3 (recommended for large rule sets) - optional
+# APP_AUTO_CLOSE_RULES_S3_BUCKET=my-securityhub-rules-bucket
+# APP_AUTO_CLOSE_RULES_S3_PREFIX=rules/
+
+# Slack integration (optional - both required to enable Slack notifications)
+APP_SLACK_TOKEN=
+APP_SLACK_CHANNEL=

.github/.dependabot.yaml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/ci.yaml

@@ -0,0 +1,67 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - name: Setup Go
+        uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0
+        with:
+          go-version: '1.24'
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Check formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "following files are not formatted:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - name: Setup Go
+        uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0
+        with:
+          go-version: '1.24'
+
+      - name: Run Tests
+        run: make test
+
+      - name: Run Verify Tests
+        run: make test-verify-verbose
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - name: Setup Go
+        uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0
+        with:
+          go-version: '1.24'
+
+      - name: Build Lambda
+        run: GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -C cmd/lambda -o ../../dist/bootstrap

.github/workflows/release.yaml

@@ -0,0 +1,29 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      - name: Bump Version
+        id: tag_version
+        uses: mathieudutour/github-tag-action@a22cf08638b34d5badda920f9daf6e72c477b07b # v6.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          default_bump: minor
+          custom_release_rules: bug:patch:Fixes,chore:patch:Chores,docs:patch:Documentation,feat:minor:Features,refactor:minor:Refactors,test:patch:Tests,ci:patch:Development,dev:patch:Development
+      - name: Create Release
+        uses: ncipollo/release-action@b7eabc95ff50cbeeedec83973935c8f306dfcd0b # v1.20.0
+        with:
+          tag: ${{ steps.tag_version.outputs.new_tag }}
+          name: ${{ steps.tag_version.outputs.new_tag }}
+          body: ${{ steps.tag_version.outputs.changelog }}

.github/workflows/semantic-check.yaml

@@ -0,0 +1,26 @@
+name: semantic-check
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  main:
+    name: Semantic Commit Message Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        name: Check PR for Semantic Commit Message
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          requireScope: false
+          validateSingleCommit: true

.gitignore

@@ -0,0 +1,8 @@
+!**/.gitkeep
+
+tmp/
+dist/
+.DS_Store
+
+.local/
+.env

AGENTS.md

@@ -0,0 +1,39 @@
+# Agent Guidelines
+
+## Build & Test
+- **Build Lambda**: `GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -C cmd/lambda -o ../../dist/bootstrap`
+- **Test all**: `make test` (runs with `-race -count=1`)
+- **Test single package**: `go test -race -count=1 ./internal/filters`
+- **Test single function**: `go test -race -count=1 ./internal/filters -run TestFilterEngine_FindMatchingRule_RunsOnExample`
+- **Run sample locally**: `go run -C cmd/sample .` (requires `.env` file and AWS credentials for auto-close testing)
+- **Lint**: `go vet ./...` and `gofmt -l .`
+
+## Code Style
+- **Imports**: stdlib, then blank line, then third-party, then local (e.g., `internal/`)
+- **Naming**: Go standard - `PascalCase` exports, `camelCase` private, `ALL_CAPS` for env vars prefixed with `APP_`
+- **Error handling**: return errors up the stack; use `fmt.Errorf` for wrapping
+- **Structs**: define types in package, constructors as `New()` or `NewTypeName()`; all methods must be public (PascalCase)
+- **Interfaces**: keep minimal (e.g., `SecurityHubEvent` has 2 methods)
+- **Formatting**: use `gofmt` (tabs for indentation)
+- **Comments**: rare, lowercase, short, concise; code should be self-documenting
+- **Code smells**: keep to minimum; prefer clear naming over comments
+
+## Architecture
+- `cmd/lambda/main.go` - Lambda handler entry point
+- `cmd/sample/main.go` - Local development runner using fixtures
+- `internal/app/` - Core application logic and configuration
+- `internal/events/` - OCSF event parsing and Slack message formatting
+- `internal/filters/` - Auto-close rule engine and filter matching logic
+- `internal/actions/` - Finding update actions (auto-close via BatchUpdateFindingsV2)
+- `internal/notifiers/` - Optional notification integrations (Slack)
+- `fixtures/samples.json` - Sample Security Hub v2 OCSF findings for testing
+
+## Important Notes
+- This project is specifically for **AWS Security Hub v2** which uses OCSF (Open Cybersecurity Schema Framework) format
+- It is NOT compatible with the original AWS Security Hub (now called Security Hub CSPM) ASFF format
+- Security Hub v2 centralizes findings from GuardDuty, Inspector, Macie, IAM Access Analyzer, and Security Hub CSPM
+- Events use OCSF fields like `finding_info`, `metadata`, `severity`, `class_name`, etc.
+- Auto-close rules use **BatchUpdateFindingsV2** API (not BatchUpdateFindings)
+- Slack integration is **optional** - bot works without Slack if only auto-close is needed
+- Rules are evaluated in order; first match wins
+- Filter matching uses AND logic - all specified filters must match

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Crux Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,32 @@
+# set mac-only linker flags only for go test (not global)
+UNAME_S := $(shell uname -s)
+TEST_ENV :=
+ifeq ($(UNAME_S),Darwin)
+  TEST_ENV = CGO_LDFLAGS=-w
+endif
+
+TEST_FLAGS := -race -count=1
+.PHONY: build-debug
+build-debug:
+	GOOS=$(GOOS) GOARCH=$(GOARCH) go build -trimpath -ldflags "-s -w" -o dist/sample ./cmd/sample
+
+.PHONY: debug
+debug:
+	go run ./cmd/sample
+
+.PHONY: test
+test:
+	$(TEST_ENV) go test $(TEST_FLAGS) $$(go list ./... | grep -v tmp/)
+
+.PHONY: test-unit
+test-unit:
+	$(TEST_ENV) go test $(TEST_FLAGS) ./internal/...
+
+.PHONY: test-verify
+test-verify:
+	go run ./cmd/verify
+
+.PHONY: test-verify-verbose
+test-verify-verbose:
+	go run ./cmd/verify -verbose
+