Security overview

This document is for security reviewers. It covers what Cloud Certainty TraceHound 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.

#Threat model

TraceHound reads your CloudWatch Logs for many people, across accounts. What it must prevent:

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

#Controls

#Identity and authorization

The API trusts the Cognito ID token's signature, issuer and audience (checked by API Gateway, and by the live tail function itself), and then decides who the caller is from its claims. Roles, grants, history 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 two independent layers.

1. The connection's IAM role sets the ceiling for everyone: the local role is limited by the stack parameters LocalAccessLevel (Read or Manage) and LogGroupPrefixes; a spoke role by AccessLevel and LogGroupPrefixes of its own stack. TraceHound can never do more in an account than its role allows, and the account owner controls that role.
2. TraceHound grants decide what each user may do within that ceiling: a subject (user or group), a connection, Regions, log group name patterns and permissions (browse, read, export, manage). See the admin guide.

Grants are not only checked in code. For every request, 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 CloudWatch Logs call in the target account;
• a role session name th-<email>, also visible in CloudTrail;
• a session policy (for non-admins) scoped to the call:

If a user's grants are too many to fit the session policy size limit, the request is refused rather than widened. Grant patterns use the same matching as IAM (* any run of characters, ? one, case-sensitive), so what TraceHound shows and what AWS allows agree.

Your SCPs, permissions boundaries and resource policies still apply on top: TraceHound adds restrictions and never removes yours.

#Streaming live tail

Browsers can't carry CloudWatch Logs Live Tail's event stream through API Gateway, so a separate Lambda function serves it through a Lambda function URL with response streaming (stack output LiveTailUrl).

• The function URL has auth type NONE because browsers can't sign requests with IAM. The function itself validates the Cognito ID token on every request (signature against the user pool's keys, issuer, audience, token use and expiry), then applies the same checks as the API: trusted email, licence, IP allowlist, and read on every log group requested (names only, at most 10). A request that fails any check gets no data.
• CORS allows only the portal's origin. Each stream ends after about 14 minutes and the browser reconnects, which repeats every check.
• AWS calls use the same per-user credentials and session policy as the API, limited to the log groups the user may read.
• Sharing between viewers. To limit Live Tail cost, people who tail the same log groups with the same filter share one Live Tail session: one stream runs it and writes the events to the shared cache, and the others read them from there. Each viewer's permissions are checked before they can join. The events are kept in the cache for about two minutes; DynamoDB removes expired items in the background, and expired items are never served.

#IAM summary

#Data flows

#The shared cache

The log group list is slow and rate-limited to read, so TraceHound keeps it in a second DynamoDB table shared by every user: each Region's log groups (names, sizes and settings, no events), field names per log group, Lambda function names, the live tail session events (about two minutes) and the daily usage counters. Every read is filtered by the caller's grants exactly as a live call would be: field names only for callers with read on that log group. It never holds query results. It is reachable only by the hub role, encrypted like the main table, and can be rebuilt at any time.

#What stays in your account

Everything: identities, connections and external IDs, grants, the query history with query text, storage history, saved queries, dashboards, snapshots (which contain result rows), usage figures and the audit log, as well as your logs and the query results, which stay in CloudWatch Logs. Cloud Certainty operates no service in the data path, and the stack never contacts the vendor at runtime. 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.

#Encryption

• In transit. TLS for every AWS API, the portal and the live tail stream (HTTPS only, with HSTS). The artifacts bucket denies non-TLS requests.
• At rest. With KmsKeyArn, your customer managed key encrypts the DynamoDB tables, TraceHound's own CloudWatch log groups, the update topic and the artifacts bucket. Without it, AWS owned keys and SSE-S3 are used. Your log groups keep their 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, the API and the live tail function URL in the stack's Region.
• 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. CSV and TSV exports defuse spreadsheet formulas.

#Audit

Every administrative change (roles, connections, grants, settings), every retention change (with the old and new values), every full result export, every collector run started by hand, every snapshot created or deleted, every saved query and dashboard change, and refused requests 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, and are also written to TraceHound's CloudWatch log groups. The query history keeps who ran every query, and what it scanned and cost, for 30 to 730 days by plan. In each account, CloudTrail shows the assumed-role session behind each call with sourceIdentity set to the user's email. Forward CloudTrail and the log groups to your SIEM.

#Licensing

TraceHound 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), TraceHound 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 people should change retention through TraceHound, and set LogGroupPrefixes where TraceHound should read only some log groups of an account.
• Grant groups rather than single users, with log group prefixes per team (/aws/lambda/payments-*).
• Use data protection policies for sensitive fields in your logs; TraceHound never unmasks them.
• Set a daily live tail minute limit and, on Business, daily scan budgets, and review Administration › Usage.
• Treat snapshots and exports like copies of your logs: share only data everyone signed in may see, with short expiries.
• On Business and above, set the IP allowlist to your corporate egress ranges if users should only connect from managed networks.
• Forward CloudTrail and TraceHound's log groups to your SIEM.