TrustPartners
🛡AWS Cloud Governance|Documentation

Architecture

AWS Cloud Governance 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 four logical layers:

  1. Inventory — a collector builds a queryable graph of your AWS resources across accounts and regions.
  2. Ingestion — CloudTrail activity arrives via EventBridge → SQS; optional GuardDuty findings arrive via EventBridge.
  3. Processing — the EventsProcessor Lambda evaluates detection rules against the event stream and runs the matching runbook (contain a principal, remediate a resource, notify), recording every action and execution.
  4. Presentation — a Svelte SPA served from S3 via CloudFront talks to API Gateway to browse inventory, events, automation and the reversible action log.

AWS Services Used

Amazon EventBridge + SQS

Event backbone. CloudTrail activity is routed to an SQS queue that the EventsProcessor Lambda polls in batches; optional GuardDuty findings are routed via an EventBridge rule. Batching lets threshold/sequence detectors aggregate efficiently.

AWS Lambda (5 functions)

EventsProcessor — evaluate detection rules, run runbooks, execute containment and remediation, write actions/executions. InventoryApi — serves /inventory, /events, /automation and /actions, and runs the inventory collector. Findings — findings/license/notifications API and the public one-click /incident-action endpoint. DeployAndSeed — one-time custom resource that seeds the catalog and templates. Plus a collector worker.

AWS Step Functions

Orchestrates inventory collection across accounts, regions and services, producing the resource-graph snapshots the app and automation query.

Amazon DynamoDB

Configuration, detection templates/rules/runbooks, the unified Actions#History log, automation execution index, single-use action-link tokens, and per-account settings. TTL is set on transient records to control storage costs.

Amazon S3

The compiled SPA (served via CloudFront), the inventory/events Parquet snapshots the query engine reads, and automation investigation reports. Buckets are private; access is via CloudFront OAC and least-privilege roles.

Amazon API Gateway (HTTP API v2)

Front door for the SPA, protected by a Cognito JWT authorizer — except the single-use /incident-action link, which is intentionally public. Routes fan out to the Findings and InventoryApi Lambdas.

Amazon Cognito

Identity provider for the console. Users are admin-created (no self-signup); TOTP MFA is configurable at deployment time. The SPA performs OIDC code exchange with Cognito from the browser.

Amazon CloudFront

CDN serving the SPA with Origin Access Control. Injects runtime configuration (config.json) so one build works across all deployments.

Amazon SNS

Outbound notification bus. The notify action publishes an alert — optionally with a single-use, 24-hour one-click containment link — to a topic you can subscribe email, Lambda, or HTTP endpoints to.

AWS IAM / Organizations

Containment attaches a customer-managed deny policy to the offending principal. Cross-account containment and remediation run through a scoped ContainmentAutomationRole assumed in the member account.

AWS CloudFormation

A single template (customer_template.yaml) provisions all of the above. For multi-account estates, an organization StackSet wires cross-account roles and CloudTrail forwarding.

Data Flow: Automation & Containment

When a CloudTrail event (or optional GuardDuty finding) arrives:

  1. EventBridge routes it to the SQS queue; the EventsProcessor Lambda is invoked in batches.
  2. Enabled rules are evaluated (field match, threshold window, sequence/absence), scoped and optionally gated on the triggering resource's inventory state.
  3. On a match, the bound runbook runs its actions — notify, contain the principal, or remediate a resource (stop/start an instance, revoke/re-authorize an ingress rule).
  4. Each action writes one row to the unified Actions#History log with the inverse needed to undo it; an execution record and investigation report are written for the run.
  5. The action appears on the Actions page with a Rollback button (when reversible); the run appears under Automation → Executions.

Data Flow: One-Click Containment from an Email

A notify action can embed a single-use, 24-hour containment link:

  1. The notify action generates a random token (stored in DynamoDB with a 24h TTL) and includes a link in the SNS email.
  2. An operator clicks it; the public /incident-action endpoint validates the token, atomically claims it (single-use), and invokes containment for the principal.
  3. The principal is contained exactly as an automated rule would — recorded in the same Actions log and reversible from the console.

How Deployments Work

Initial deployment: run the CloudFormation template with an admin email. It provisions all resources, then the DeployAndSeed Lambda seeds the service catalog and detection templates and creates the admin Cognito user.

Updates: new builds are published to the source bucket; a CloudFormation stack update swaps the Lambdas and frontend and invalidates the CloudFront cache. DynamoDB changes are additive to avoid data loss.

Multi-account: an organization StackSet deploys cross-account containment roles and CloudTrail forwarding so one application account can inventory, investigate and contain across the org.

Security Design

  • All console API calls require a valid Cognito JWT (TOTP MFA configurable); the only public route is the single-use action link.
  • The S3 SPA bucket is private; CloudFront OAC is the only allowed origin.
  • Lambda execution roles follow least-privilege; cross-account containment uses a scoped assumed role.
  • 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

CloudTrail activity is forwarded to the application account by the organization StackSet. For a single-account deployment, the stack consumes the account's own CloudTrail events directly.

💡 Tip

Keep inventory fresh: a rule's resource gate (for example, only act if an instance is in a given subnet) matches precisely when the inventory graph has collected the resource, and fails open otherwise.