Security overview

This document is for security reviewers. It covers what Cloud Certainty Watchtower protects against, how users are identified, how access is limited, where data goes and how it is encrypted. Everything described here runs in your own AWS account.

Watchtower reads AWS Security Hub findings across your organisation, writes workflow changes back when you allow it, and, when you configure it, reads your GitHub repositories and opens pull requests in them. Its controls make sure that each person sees and changes exactly the findings an administrator granted them, that AWS itself bounds what each session can do, that tokens for code hosts never leak, that changes to code always go through a pull request a person reviews, and that every action can be traced to a person.

#Threat model

Out of scope: a malicious administrator of the AWS account (they can change any IAM policy), the security of your GitHub organisation and its branch protection, and the security of the identity provider and of users' devices.

#Zero-trust controls

#Identity and authorisation

The API trusts the Cognito ID token's signature, issuer and audience (checked by API Gateway), and then decides who the caller is from its claims. Roles, grants, tasks and the bootstrap admin are keyed on the email claim, so a user who could pick their own email could take over someone else's access. The API therefore accepts the email only when it is one the user can't choose; otherwise it refuses the caller with 403 forbidden on every route.

The provider is read from the signed token, never from anything the client sends.

Bootstrap admin. BootstrapAdminEmail is always an admin, so it is bound to an immutable identity: the first trusted sign-in with that email records the caller's Cognito user ID, and from then on only that user is the bootstrap admin. Sign in as the bootstrap admin straight after deployment. Resetting the binding is described in the admin guide.

#Permissions, grants and session policies

What a user can do is the intersection of:

1. The connection's IAM role, set by the account owner: LocalAccessLevel on the hub stack, AccessLevel on each spoke stack. Read allows Security Hub reads; Triage adds securityhub:BatchUpdateFindings. Watchtower can never do more in an account than its role allows.
2. Watchtower grants: a subject (user or group), a connection (or all), AWS account patterns (*, ?), Regions (or all), and the permissions view, triage (implies view) and fix (implies view). Administrators hold every permission, still bounded by the role. See the admin guide.

For every request that reaches Security Hub, the API calls sts:AssumeRole on the connection's role with:

• SourceIdentity = the user's email. It can't be changed for the rest of the session, also in role chains, and it appears in CloudTrail for every Security Hub call in the target account (the sync worker uses watchtower-sync);
• a role session name wt-<email>, also visible in CloudTrail;
• the external ID for spoke roles;
• a session policy (for non-admins) for the scope of the call:

#Account grants and Security Hub

AWS Security Hub has no IAM permissions per member account. GetFindings and BatchUpdateFindings act on the hub (arn:aws:securityhub:<region>:<account>:hub/default) of the account they are called in: in the delegated administrator, they read or change the findings of every member account. No IAM policy or session policy can say "only the findings of account 111122223333".

So the two layers do different jobs:

• Watchtower enforces which findings each person may see and change. The index holds every finding of a source and is filtered to the caller's grants on every read; every finding in a change request is checked against the caller's triage grants before anything is sent; findings outside the grants answer "not found". This is covered by tests on every route.
• AWS enforces which actions each session may take. A user without triage gets a session that AWS refuses to let change any finding; a Read connection's role can't change findings at all; and no role can do anything outside Security Hub reads, BatchUpdateFindings and the Organizations account list.

If you need AWS itself to separate accounts, connect separate Security Hub administrators (for example per business unit) as separate connections with their own roles.

#IAM summary

* resources appear only where AWS has no resource-level permissions (Security Hub reads, AWS Organizations, License Manager).

#Data flows

#What stays in your account

Everything: identities, connections and external IDs, grants, the findings index, posture and trends, tasks and comments, exceptions, saved views, code indexes (resource names, types, tags and line numbers, not whole files), scan results, integration secrets, usage figures and the audit log. File contents are read from GitHub when someone opens a file or previews a fix, and are not stored.

Cloud Certainty operates no service in the data path, and Watchtower sends no telemetry. The AWS Marketplace container registry and the vendor's public bucket in us-east-1 (templates and the release manifest) are read-only distribution points used at install and upgrade, and, with UpdateChecks = Enabled, for a daily read of the public release manifest that sends nothing about you. Links to cloudcertainty.com in the portal are plain links, followed only when someone clicks them.

#Code hosts

The only places Watchtower sends data outside AWS are the code hosts you configure:

• GitHub or GitHub Enterprise Server. Watchtower reads repository trees, files and archives. When a person opens a fix pull request or creates a GitHub issue, Watchtower writes a branch, commits and a pull request, or an issue, whose text includes the finding titles, AWS account ids and resource ids concerned (never notes). Choose repositories whose visibility suits that information.
• SonarCloud or SonarQube. Watchtower only reads issues and hotspots of the projects you map.

Use a GitHub App or fine-grained tokens limited to the repositories Watchtower indexes, with write permissions only for the features you use (Code integrations).

#Encryption

• In transit. TLS for every AWS API, every code host and the portal (HTTPS only, with HSTS). The artifacts and data buckets deny non-TLS requests.
• At rest. With KmsKeyArn, your customer managed key encrypts the DynamoDB tables, CloudWatch Logs, the update topic, the artifacts and data buckets and the integration secrets. Without it, AWS owned or AWS managed keys and SSE-S3 are used. Security Hub keeps its own encryption.

#Portal hardening

Amplify Hosting serves the portal with these headers:

• A strict Content-Security-Policy: no inline or third-party script, frame-ancestors 'none', and AWS endpoints allowed only for sign-in and the API.
• Strict-Transport-Security, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, X-Frame-Options: DENY, and a Permissions-Policy that turns off camera, microphone, geolocation, payment and USB.

Charts are drawn in the browser; nothing is loaded from third parties. Tokens are kept in session storage, never in cookies; refresh tokens last 8 hours and can be revoked.

#Audit

Every administrative change (roles, connections, grants, settings, integrations, repositories, ingest tokens), every change to findings in Security Hub, every task created or deleted, every exception created, changed, revoked or applied, saved views, fix pull requests, GitHub issues, scans, SARIF uploads and manual syncs are written to the audit log with the actor, source IP and target. Admins read it in Administration › Audit log. Events are kept for the plan's audit days: 30 on Starter, 90 on Team, 365 on Business and 3,650 on Enterprise. For each AWS call, CloudTrail in the connected account shows the assumed-role session with sourceIdentity set to the user's email. Forward CloudTrail and Watchtower's log groups to your SIEM.

#Licensing

Watchtower reads its AWS Marketplace licence from AWS License Manager in your account: at install and in the API. Nothing about your usage or data is sent anywhere. Without a valid licence the installer stops and the API answers 402 licence_required. If License Manager is unreachable, or a licence that was active disappears (which bridges a move between plans), Watchtower keeps working for up to 72 hours from the last successful check. Your data stays in place either way.

#Shared responsibility

• Keep BootstrapAdminEmail on a protected identity and enforce MFA at your IdP. Grant Admin to a second person or group.
• Keep connection roles at Read unless your team triages in Watchtower, and grant triage to the people who own each account.
• Grant groups rather than single users, with account patterns per team.
• Prefer a GitHub App installed on the infrastructure repositories only, or fine-grained tokens limited to them. Protect default branches so that Watchtower's pull requests need review.
• Review exceptions when they expire, and keep their maximum length short.
• Scope each ingest token to one repository, give it an expiry, and rotate it.
• On Business and above, set the IP allowlist to your corporate egress ranges if users should only connect from managed networks.
• Forward CloudTrail and Watchtower's log groups to your SIEM.