Installation guide

This guide is for the platform team installing Cloud Certainty TraceHound in their AWS account. The install is one CloudFormation stack (the hub). Every other account whose CloudWatch Logs TraceHound should reach gets a small role stack (the spoke). With IAM Identity Center or another SAML IdP, the hub takes two steps: deploy the stack, configure the SAML application, then update the stack. For the short version, see Getting started.

#Before you start

• Region. Any Region with Amazon CloudWatch Logs, AWS Lambda (with function URLs and response streaming), Amazon API Gateway (HTTP APIs), Amazon DynamoDB, Amplify Hosting, Amazon Cognito, AWS License Manager, Amazon EventBridge and Amazon ECS on Fargate. The templates are always loaded from the vendor's public bucket in us-east-1 (CloudFormation accepts a template URL from any Region), and all product code comes from the container image. The hub's Region doesn't limit which Regions you can read: list them in LocalRegions and in each connection.
• Account. Deploy the hub in the account that subscribed on AWS Marketplace: the licence is delivered to that account through AWS License Manager. To run the hub in another account of your organisation, distribute the licence to it with a License Manager grant first.
• Permissions. You need permission to create the resources in the stack: IAM roles (two have fixed names), Lambda functions and a Lambda function URL, ECS, EC2 security groups, Cognito, API Gateway, Amplify, DynamoDB, S3, SNS, EventBridge, KMS and CloudWatch Logs.
• Service control policies. The live tail function is reached through a Lambda function URL with auth type NONE (the function checks every request itself, see What the stack runs). If an SCP or permissions boundary denies such URLs, ask for an exception for the <NamePrefix>-livetail function first.
• Network. A VPC with at least one subnet with outbound HTTPS access, for the one-off installer task (see Networking). Nothing else runs in your VPC.
• Identity. Decide how users will sign in: IAM Identity Center, another SAML 2.0 IdP (Entra ID, Okta and others), an OIDC IdP, or Cognito-managed users. SAML IdPs other than IAM Identity Center, and OIDC, need the Team plan or above.
• Scope. Decide whether TraceHound should read every log group of an account (the default) or only those under some name prefixes, and whether it may change retention (see Log group access).

#1. Subscribe

1. Open TraceHound in AWS Marketplace and choose Continue to Subscribe. Choose the plan and the contract length (Team is the base plan; Business and Enterprise are add-ons to it) and accept the offer. AWS License Manager now holds your licence.
2. Choose Continue to Configuration, select the fulfilment option and the Region, then open the CloudFormation launch link from the usage instructions.

#2. Launch the hub stack

In the CloudFormation console, fill in the parameters (see the reference). Acknowledge "AWS CloudFormation might create IAM resources with custom names" and create the stack. Creation takes about 10 minutes.

The quick-create link, with the release version filled in:

https://console.aws.amazon.com/cloudformation/home#/stacks/quickcreate?templateURL=https://cloudcertainty-tracehound-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/main.yaml&stackName=tracehound

From the AWS CLI (--region is the Region you deploy to):

aws cloudformation create-stack --region <your-region> --stack-name tracehound \
  --template-url https://cloudcertainty-tracehound-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/main.yaml \
  --parameters file://params.json \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

params.json lists the parameters as [{"ParameterKey": "VpcId", "ParameterValue": "vpc-..."}, ...].

#What happens during creation

The product's code (the Lambda functions and the web app) ships inside the subscription-protected container image, not as public downloads. Early in stack creation:

1. CloudFormation creates a private S3 bucket in your account (output ArtifactsBucketName; all public access blocked, encrypted, TLS only).
2. The ArtifactInstall custom resource starts one Fargate task from the product image in your InstallerSubnetIds. The task checks your AWS Marketplace licence in AWS License Manager, verifies every file of the code bundle against the SHA-256 checksums in the image, and copies it into the bucket under the release's version. It runs for about a minute at 0.25 vCPU and 512 MB, with a read-only root filesystem and a security group without inbound rules.
3. The Lambda functions and the web app are then created from that bucket.

If the installer task fails, stack creation fails and rolls back. The error message gives the task's exit code and its log stream (log group /<NamePrefix>/installer); see Troubleshooting.

#What the stack runs

All of it is serverless and runs only when used, apart from two schedules:

The API, live tail and collector functions share one role, the hub role (<NamePrefix>-api-<Region>, output SpokeTrustedPrincipal), which reaches CloudWatch Logs only by assuming the connection roles. The live tail function URL has no IAM authorisation, because browsers can't sign requests to it; instead the function checks the user's TraceHound sign-in token itself (signature, issuer, audience, token use and expiry), and applies the same licence, IP allowlist and permission checks as the API. Cross-origin requests are answered only for the portal's own address. See the security overview.

#3. Connect your identity provider

Until SamlMetadataUrl is set, the portal falls back to Cognito sign-in, which has no users. Nobody can sign in at that point, so the stack is safe in that state.

#4. First sign-in

Open the PortalUrl output and sign in as BootstrapAdminEmail. The first account that signs in with that (verified) email becomes the bootstrap administrator and stays bound to it (see the admin guide).

The local connection to the hub's own account exists from the start. It uses the stack's local role, which may do what LocalAccessLevel and LogGroupPrefixes allow, in the Regions of LocalRegions. Administrators see every log group there. Other users see nothing until an administrator grants them access (admin guide).

Choose Collect now on the Overview (or under Administration › Collector) to record the first storage and ingestion history straight away instead of within the hour.

#Log group access

The local role and every spoke role are the upper limit of what TraceHound can do in an account. Every call runs with the credentials of the person who asked, narrowed to their grants, so the role must allow it and the grants decide who may use it.

The roles never have logs:Unmask, so data masked by a data protection policy stays masked in TraceHound. They have no IAM, CloudFormation, DynamoDB or S3 permissions, and their log group permissions are limited to the role's own account. The local role is also explicitly denied TraceHound's own artifacts bucket and retention changes of TraceHound's own log groups (/aws/lambda/<NamePrefix>-* and /<NamePrefix>/* in the stack's Region), so TraceHound can't change its own stack or shorten its own audit trail. That deny also covers your own Lambda functions whose names start with <NamePrefix>-; choose another NamePrefix if you have such functions and want to manage their retention from TraceHound.

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

#The collector

CloudWatch reports a log group's stored bytes only as a value for now, so TraceHound keeps its own history. Every hour the collector looks at every connection and Region; for each one without a record for the current UTC day it:

1. lists every log group (up to 20,000 per Region);
2. reads yesterday's IncomingBytes and IncomingLogEvents for each log group from CloudWatch metrics (GetMetricData, 500 metrics a call). The first run in a Region reads the last 90 days instead, so ingestion history is there on day one;
3. writes one record for the day with each log group's stored bytes, bytes ingested and events.

Stored bytes history starts the day TraceHound is installed; backfilled days have ingestion only. History is kept for your plan's storage history days: 90 on Starter, 365 on Team, 730 on Business and 1,825 on Enterprise.

The collector runs as the hub role with the source identity tracehound-collector, with a session that can only list log groups, read metrics and list Lambda functions. GetMetricData is billed per metric requested ($0.01 per 1,000), so a Region with 2,000 log groups costs about $0.04 a day; the 90-day backfill costs about 90 times that, once. A failure in one Region is shown under Administration › Collector and never stops the others; the next hourly run tries again.

#5. Deploy the spoke role in other accounts

spoke-role.yaml creates one role, /tracehound/<RoleName>, that only the hub role (stack output SpokeTrustedPrincipal) can assume, only with your external ID, and only with a source identity (a user's email, or tracehound-collector). Its template URL is the stack output SpokeTemplateUrl:

https://cloudcertainty-tracehound-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml

The role is the upper limit of what TraceHound can do in that account; grants narrow it per user or group but never widen it. IAM is global and the role covers every Region of the account, so create it once per account, in any Region. The stack's outputs are RoleArn (enter it in the connection) and AccessLevel (choose the same level for the connection).

#A single account

cat > spoke-params.json <<'EOF'
[
  {"ParameterKey": "TrustedPrincipal", "ParameterValue": "<SpokeTrustedPrincipal output>"},
  {"ParameterKey": "ExternalId", "ParameterValue": "<a secret of 16 to 128 characters>"},
  {"ParameterKey": "AccessLevel", "ParameterValue": "Read"}
]
EOF
aws cloudformation create-stack --region eu-west-1 --stack-name tracehound-spoke \
  --template-url https://cloudcertainty-tracehound-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml \
  --parameters file://spoke-params.json --capabilities CAPABILITY_NAMED_IAM

#Every account of an AWS Organization (StackSets)

With service-managed StackSets, new accounts in the target OUs get the role automatically. Use one external ID for the whole StackSet, and enter that same external ID for every connection you create for those accounts.

# From the management account or a delegated StackSets administrator.
aws cloudformation create-stack-set --region us-east-1 --stack-set-name tracehound-spoke \
  --template-url https://cloudcertainty-tracehound-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml \
  --parameters file://spoke-params.json \
  --capabilities CAPABILITY_NAMED_IAM \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false

# One Region is enough: IAM is global and the role covers every Region.
aws cloudformation create-stack-instances --region us-east-1 --stack-set-name tracehound-spoke \
  --deployment-targets OrganizationalUnitIds=ou-abcd-11111111 --regions us-east-1

Service-managed StackSets don't deploy to the management account; use a normal stack there if TraceHound should reach it. To change AccessLevel later, update the StackSet, then the access level of the connections.

#Add the connection

In Administration › Connections › Add connection, enter an id (used in links, it can't be changed later), a name, the account ID, the access level, the spoke stack's RoleArn, the external ID and the Regions. Choose Test: TraceHound assumes the role and lists the log groups in each Region. See the admin guide.

#Parameter reference

#Hub (main.yaml)

#Spoke (spoke-role.yaml)

TrustedPrincipal, ExternalId, RoleName, AccessLevel and LogGroupPrefixes; see Deploy the spoke role.

#Networking

Only the installer task runs in your VPC, for about a minute at install and at each upgrade. It needs outbound HTTPS (443) to:

• Amazon ECR in us-east-1, to pull the image from the AWS Marketplace registry (cross-Region, so this needs internet egress: a NAT gateway or public subnets);
• AWS License Manager in your Region, for the licence check;
• Amazon S3 in your Region, to write the code into the artifacts bucket (a gateway endpoint works);
• CloudWatch Logs in your Region, for its log stream.

Its security group has no inbound rules and one outbound rule, TCP 443. The Lambda functions don't run in your VPC; they reach STS, CloudWatch Logs, CloudWatch and Lambda in your accounts over AWS's public endpoints.

People's browsers reach the portal (Amplify Hosting), Cognito, the HTTP API and, for live tail, the live tail function URL (https://<id>.lambda-url.<region>.on.aws, output LiveTailUrl). If a proxy or firewall limits which sites people can open, allow that address too; the stream is a long-lived HTTPS response (Server-Sent Events), so a proxy must not buffer it.

#Encryption and KMS

Without KmsKeyArn, the DynamoDB tables, the log groups, the update SNS topic and the artifacts bucket use AWS owned keys and SSE-S3.

With KmsKeyArn, your key encrypts all of them. The key must be a symmetric customer managed key in the stack's Region (give its ARN, not an alias), and its key policy must:

• let the account's IAM policies grant its use (the default key policy statement for the account root does this). The hub role uses it only through DynamoDB, the update notifier only through DynamoDB and SNS, and the installer and the portal deployer only through S3;
• allow logs.<region>.amazonaws.com to use it for the stack's log groups;
• allow sns.amazonaws.com to use it for the update topic.

The identity that creates or updates the stack also needs kms:Decrypt on the key, because Lambda reads the function code from the encrypted artifacts bucket with the deploying identity's permissions.

The key protects TraceHound's own data. Your log groups keep their own encryption: a log group encrypted with a customer managed key needs that key's policy to let CloudWatch Logs use it, as it does today; TraceHound reads through CloudWatch Logs and needs no KMS permission of its own.

#Stack outputs

#Updating

Each release is a new template; there is no version parameter. To upgrade, update the stack with the new release's template (Update stack › Replace current template) and keep every other parameter value. See the upgrading guide.

To change a setting such as LocalAccessLevel, LocalRegions, LogGroupPrefixes or SamlMetadataUrl, update the stack with the current template and change only that parameter.

#Deleting

1. Delete the hub stack. The DynamoDB table (<NamePrefix>-table) is retained on purpose, with its settings, grants, saved queries, dashboards, history, storage history and audit log. Everything else is deleted: the cache table (with the usage counters), the Cognito user pool (Cognito-only users are lost), the artifacts bucket and TraceHound's own log groups. A new stack with the same NamePrefix can't be created while the retained table exists.

   To delete the table when you no longer need it, turn off its deletion protection, then delete it.

2. Delete the spoke stacks or the StackSets in the other accounts.

3. Delete the SAML or OIDC application in your identity provider.

Your log groups are never touched by deleting TraceHound; retention you changed through TraceHound stays as you set it.

#Troubleshooting