ThreatReaction
🛡Threat Reaction|Documentation

Architecture

Threat Reaction is a serverless application deployed entirely within your AWS account using a single CloudFormation template. No external dependencies, no data exfiltration — every byte stays in your infrastructure.

High-Level Overview

The platform has three logical layers:

  1. Ingestion — GuardDuty findings enter via EventBridge; S3 data events arrive via CloudTrail → SQS.
  2. Processing — The EventsProcessor Lambda evaluates findings against your threat policies stored in DynamoDB and executes the configured response action.
  3. Presentation — A Svelte SPA served from S3 via CloudFront communicates with API Gateway to read findings and update policies.

AWS Services Used

Amazon GuardDuty

Threat intelligence engine. Analyzes VPC flow logs, DNS logs, and CloudTrail events to produce structured security findings. Threat Reaction does not replace GuardDuty — it sits on top of it.

Amazon EventBridge

Routes GuardDuty findings to the EventsProcessor Lambda in real time. A default EventBridge rule is provisioned by the CloudFormation template to capture all GuardDuty finding events.

AWS Lambda (5 functions)

EventsProcessor — core logic: evaluate findings, look up policy in DynamoDB, execute response action. FindingsAPI — CRUD API for the frontend. DeployAndSeed — runs once at stack creation to populate sample data. LicenseValidator — validates license keys on each API call. ActionsProcessor — handles block/unblock/revoke operations.

Amazon DynamoDB

Single-table design. Stores threat policies (per finding type + severity), processed events, and entity inventory. All reads and writes from the Lambda functions go through DynamoDB. TTL is set on event records to control storage costs.

Amazon API Gateway (HTTP API v2)

Front-door for the Svelte SPA. Two endpoints: GET /findings (read threats or events) and PUT /findings (update policy). Protected by a JWT authorizer backed by Cognito.

Amazon Cognito

Identity provider for the management UI. Users must be admin-created (no self-signup). MFA (TOTP) is mandatory. The Svelte app performs OIDC code exchange with Cognito directly from the browser.

Amazon S3

Two buckets: one for the compiled Svelte SPA (served via CloudFront), one for exported findings (when SAVE action is used). The SPA bucket is private; access is enforced via CloudFront OAC.

Amazon CloudFront

CDN serving the Svelte SPA. OAC (Origin Access Control) restricts direct S3 access. Injects runtime configuration (config.json) so one build works across all customer deployments. Optional country-level access policy.

Amazon SQS

Decouples S3 data event ingestion from processing. CloudTrail delivers S3 object-level events to SQS; the EventsProcessor Lambda polls the queue in batches, enabling the sliding-window anomaly detector to aggregate events efficiently.

Amazon SNS

Outbound notification bus. When a threat is detected or a containment action fires, Threat Reaction publishes a JSON payload to an SNS topic. You can subscribe email addresses, Lambda functions, or HTTP endpoints.

AWS WAF

Used by the BLOCK response action to add attacker IPs to a managed IP set, dropping subsequent requests at the CloudFront edge before they reach your application.

AWS CloudFormation

Single template (customer_template.yaml) provisions all of the above. Stack creation takes 3–5 minutes. Updates are applied via the CloudFormation console and the in-app update flow.

Data Flow: GuardDuty Finding

When GuardDuty generates a finding the following sequence occurs:

  1. GuardDuty publishes the finding to EventBridge (usually within 5 minutes of detection).
  2. The EventBridge rule matches the event and synchronously invokes the EventsProcessor Lambda.
  3. EventsProcessor reads the threat policy for that finding type + severity from DynamoDB.
  4. If the policy is BLOCK: the actor IP is added to the WAF IP set. If REVOKE: the IAM access key is invalidated via the IAM API. If REPORT or SAVE: the finding is written to DynamoDB (and optionally S3).
  5. An SNS notification is published if a matching notification rule exists.
  6. The finding appears in the Events log the next time the frontend polls the API.

Data Flow: S3 Anomaly Detection

S3 object-level events (GetObject, PutObject, DeleteObject, ListObjects) are tracked for each registered bucket:

  1. CloudTrail captures S3 data events and delivers them to the SQS queue.
  2. EventsProcessor Lambda is triggered by SQS in batches.
  3. For each batch, the Lambda aggregates operations per entity (IP or IAM principal) using a sliding time window stored in DynamoDB.
  4. If the operation rate or byte volume exceeds the configured threshold, an anomaly event is written to DynamoDB with type S3DataExfiltration, RansomwareWrite, RansomwareDelete, or RansomwareEnumeration.
  5. If the corresponding ThreatReaction detector is set to BLOCK, the entity is blocked immediately.

How Deployments Work

Initial deployment: Run the CloudFormation template with two parameters: an admin email address and the URL of the pre-built frontend ZIP hosted in the Threat Reaction publisher S3 bucket. CloudFormation provisions all resources, then the DeployAndSeed Lambda runs automatically as a custom resource to populate sample data and create the admin Cognito user.

Frontend updates: New frontend builds are uploaded to the publisher S3 bucket. A CloudFormation stack update with the new ZIP URL triggers a CloudFront cache invalidation and deploys the new SPA. The in-app update banner automates this flow for end users.

Backend updates: Lambda code changes are included in the same CloudFormation template update. DynamoDB schema changes are backward-compatible (additive-only) to avoid data loss during updates.

Multi-region: GuardDuty findings only flow in the same region as the deployed stack. To cover multiple regions, deploy a separate stack per region.

Security Design

  • All API calls require a valid JWT from Cognito (TOTP MFA enforced).
  • The S3 SPA bucket is private; CloudFront OAC is the only allowed origin.
  • Lambda execution roles follow least-privilege — each function has only the IAM permissions it needs.
  • License keys are RSA-signed and validated locally on every API call — no outbound call to a license server.
  • No customer data leaves your AWS account at any point.

ℹ️ Note

GuardDuty must be enabled in the same AWS region as your Threat Reaction stack. Cross-region finding forwarding is not supported by default — deploy one stack per region you want to monitor.

💡 Tip

Use AWS Organizations to delegate GuardDuty administration to a central security account. Deploy Threat Reaction in that account to get a consolidated view of findings across all member accounts.