Administrator guide

Administrators manage Cloud Certainty TraceHound from Administration in the portal (PortalUrl): connections, grants, roles, settings and prices, usage, the collector, the audit log and the licence. Everything is stored in the stack's DynamoDB table in your account, and every change is written to the audit log.

Administration has the pages Connections, Grants, Roles, Settings, Usage, Collector, Audit log and Licence and about. Without a valid licence only Licence and about opens.

#Connections

A connection is one IAM role TraceHound assumes in one AWS account, with the Regions it shows (Administration › Connections).

Screenshot

#Access levels

The access level of a connection's role is the ceiling for everyone, administrators included. Grants can narrow it per user or group but never widen it.

Whatever the level, a role whose stack sets LogGroupPrefixes reads events from, and changes, only the log groups under those prefixes; it still lists every log group with its size and metrics. The roles never have logs:Unmask, so masked data stays masked (log group access).

Use Read unless you want people to change retention through TraceHound.

#Add a connection

1. Deploy the spoke role in the account (installation guide). How to connect another AWS account at the bottom of the page shows the steps, the template URL and an AWS CLI command. Set TrustedPrincipal to the hub stack's SpokeTrustedPrincipal output and choose an ExternalId secret of 16 to 128 characters.
2. Choose Add connection and enter:
   • Id: a short name used in links, for example production. It can't be changed later, and local is reserved.
   • Name and AWS account id.
   • Access level: the same as the spoke stack's AccessLevel. The role in the account is what really enforces it.
   • Role ARN: the spoke stack's RoleArn output, arn:aws:iam::<account>:role/tracehound/<RoleName>. It must be in that account and under the /tracehound/ path.
   • External ID: the same secret you gave the spoke stack (Generate makes one you can then give the stack). It is stored and never shown again; when you edit the connection, leave it empty to keep it.
   • Regions to show: as many as you like; one role covers every Region of the account.
3. Save connection, then choose Test. The test assumes the role and, for each Region, reports the number of log groups and their stored bytes, or the AWS error.

Screenshot

Each distinct AWS account counts against your plan's account limit, the hub account included (3 on Starter, 10 on Team, 50 on Business, unlimited on Enterprise). When the limit is reached, Add connection is disabled. Deleting a connection makes TraceHound stop using the role, and grants on it stop applying; the role stays in the account until you delete its stack. The collector adds a new connection's Regions on its next hourly run.

#Grants

A grant gives a user or a group permissions on the log groups whose names match some patterns, on a connection (or all) in some Regions (or all) (Administration › Grants). A new grant, or a change, applies on the user's next request.

Screenshot

The Pattern tester next to the patterns shows, for a connection and Region you choose, how many log groups match and what they store, which pattern matches each, and which patterns match nothing. Try a name checks a single name. Log groups created later that match the patterns are covered automatically.

Screenshot

#How grants combine

• A user's permissions are the union of every grant that matches them, through their email or any of their groups, capped by the connection's access level and the plan.
• A log group no grant covers doesn't exist for the user ("not found"): TraceHound doesn't reveal it. A log group they can see but not use in that way answers "forbidden".
• Administrators have every permission on every log group, still bounded by each connection's access level and the plan.
• Saved queries and dashboards never grant anything: they run with the viewer's own permissions.

Check access, under the grants, answers "what may this person do with this log group?": enter an email and groups, a connection, a Region and a log group name, and it shows the effective permissions, what the connection's access level removes, and the grants that matched. It works from the grants on the page; the API checks every request again.

Screenshot

#How grants are enforced

Grants are enforced twice. TraceHound checks them on every request, and every AWS call runs with temporary credentials (15 minutes) that a per-request session policy limits to the user's grants: Logs Insights queries, event searches, field lists and Live Tail only on the ARNs of the log groups the user may read, and retention changes only on the one log group being changed. Even if TraceHound's own check had a bug, AWS would refuse anything outside the grants.

Every session carries the user's email as its source identity, so CloudTrail in each account names the person behind every CloudWatch Logs call.

If someone's grants would make a session policy larger than AWS allows, TraceHound refuses the request ("too many grants") rather than widening it. Combine grants: use groups, and patterns such as /aws/lambda/payments-* instead of many single names.

#Examples

#Roles

Screenshot

• Everyone who signs in without a role entry is a User, and sees no log groups until a grant applies to them.
• Roles and grants match the user's email or groups. The email must be trusted: asserted by your SAML IdP, verified by your OIDC IdP (email_verified), or marked verified in the Cognito user pool (Identity providers).
• In Administration › Roles, under Grant a role, choose User or Group, enter the email or the group name exactly as your IdP sends it (group names are case-sensitive), choose Administrator or User, and Save role. A role for a user wins over a role for one of their groups, so you can make a group administrators and keep one member a User. A change applies on the user's next request.
• You can't remove your own Administrator role. Grant it to at least one more person or group.

#The bootstrap admin

BootstrapAdminEmail (a stack parameter) is the bootstrap admin. The first person who signs in with that email is bound to it by their immutable user ID (the Cognito sub) and is always an Administrator, which prevents lock-out. The Roles page shows the entry as set by the stack. The binding is recorded in the audit log (bootstrap.bind). Someone else who later signs in with the same email address but a different user ID is not the bootstrap admin.

#Recovering the bootstrap admin

Reset the binding when the bootstrap admin's user ID changes (the user was recreated, the IdP issues a new subject, or you switched IdentityProvider). Either:

• Use a different person: update the stack and change BootstrapAdminEmail. The first sign-in with the new email takes over the binding.
• Keep the same email: update the stack with BootstrapAdminEmail set to another address you can sign in with, and sign in with it once. Then set it back and sign in with the original email, which takes the binding over again.

If another Administrator can still sign in, they can simply grant the Administrator role to the person by email under Administration › Roles.

#Settings

Administration › Settings:

Screenshot

The prices are CloudWatch's us-east-1 list prices by default; Reset to defaults restores them. Set your Region's prices, or your negotiated ones. Every estimate in TraceHound uses them; your AWS bill is the record.

#Usage

Administration › Usage shows what your teams ran through TraceHound over the last 7, 30 or 90 days, per UTC day:

Screenshot

• Insights queries, Failed and cancelled, Reused, Bytes scanned, Live tail minutes and the Estimated cost, with queries per day and bytes scanned, live tail minutes or cost per day.
• Top users and Top Regions (Business and above): the 50 users and the 50 connections and Regions that cost the most over the period, with their queries, bytes scanned and live tail minutes.

Each query is counted once, when it reaches its final state (succeeded, failed or cancelled), however many people or panels were watching it. A result TraceHound showed again from someone's own earlier run starts no query and costs nothing. Live tail minutes are counted per session minute of each shared session, once, however many people watched it. Estimated costs use the prices in Settings; your AWS bill is the record. Usage covers only what runs through TraceHound, and is kept for 400 days.

#Collector

Administration › Collector shows the storage history collector in every connection and Region: when it last ran, the last day it recorded, whether its 90-day ingestion backfill is done, how many log groups it tracked and any error.

Screenshot

Every hour the collector records each log group's stored bytes and yesterday's ingestion from CloudWatch metrics. The first run in a Region backfills 90 days of ingestion; stored bytes history starts the day TraceHound is installed. GetMetricData costs about $0.01 per 1,000 metrics, so a Region with 2,000 log groups costs about $0.04 a day. Storage history is kept for 90 days on Starter, 365 on Team, 730 on Business and 1,825 on Enterprise.

Collect now starts a run at once (recorded in the audit log as collector.run); new numbers appear within a few minutes. An error in one Region, such as an access error from a spoke role, is shown there and doesn't stop the others; the next run tries again. A Region with more than 20,000 log groups is recorded for its first 20,000 and says so.

#Audit log

Administration › Audit log lists events by UTC day, newest first, with the time, the actor, the action, the target and the source IP. Open an event for its details. Filter this page searches the events shown.

Screenshot

Events are kept for your plan's audit days: 30 on Starter, 90 on Team, 365 on Business and 3,650 on Enterprise. Each event is also written as a JSON line (with "kind":"audit") to the API's CloudWatch log group, /aws/lambda/<NamePrefix>-api (live tail refusals to /aws/lambda/<NamePrefix>-livetail), kept for the stack's LogRetentionDays, so you can forward it to your SIEM.

Every query, with who ran it, is in the query history, which administrators can see for everyone, day by day, under History › Everyone.

For a full trail, CloudTrail in each account records the CloudWatch Logs calls TraceHound makes, as it records them for any client, with sourceIdentity set to the user's email and the role session name th-<email>.

#Licence and about

Administration › Licence and about shows your licence, your plan and the installed version.

Screenshot

#Licence

TraceHound reads your AWS Marketplace licence from AWS License Manager in the hub account. The page shows the status, the plan, the entitlements, when the licence is valid until and when it was last checked. Check licence now reads it again (TraceHound otherwise rechecks every 10 minutes).

Without a valid licence every page except this one says a licence is required. Nothing is deleted; subscribing again unlocks TraceHound.

#Plan

What your plan includes lists the limits and features of your plan, and Compare plans shows all four:

Features your plan doesn't include show a plan badge, and TraceHound refuses them. To change plan, see Changing plan.

#Version and updates

The version card shows the installed version and, when update checks are on (UpdateChecks), the latest release, its summary and release notes, whether it is a security release, the oldest supported version, and How to upgrade with the template URL and an AWS CLI command. A banner on the Administration pages announces a newer release. See Upgrading.