User guide

Cloud Certainty Watchtower is a console for AWS Security Hub that runs in your organisation's own AWS account. You search and triage the findings of every AWS account and Region your administrator connected, work through a fix list ranked by risk, track remediation as tasks with due dates, record accepted risks as exceptions that expire, and see where each finding's resource is defined in your Terraform and CloudFormation code.

Open the portal URL your administrator gave you and sign in with your company account. You see the findings of the AWS accounts and Regions an administrator granted you; what you may do with them depends on your permissions:

Permissions are granted per AWS account (with patterns such as 1111*) and Region, so you may be able to triage findings in one account and only view them in another. Each connection's role also has an access level set by the account owner: on a Read connection nobody can change findings, whatever their grants. Buttons for actions you can't take are greyed out, and their tooltip says why.

Some features depend on your organisation's plan (Starter, Team, Business or Enterprise). A feature the plan doesn't include shows a plan badge, for example Team or Business. This guide notes the plan next to each such feature.

The navigation has Overview, Findings, Fix list, Tasks, Compliance, Code, Exceptions and, for administrators, Administration. Ctrl+K (Cmd+K on a Mac) opens a command palette to go to a page, a finding, a control or a task by typing part of its name.

#Signing in

Watchtower uses your organisation's sign-in: AWS IAM Identity Center, another SAML or OIDC identity provider, or Watchtower's own user pool with multi-factor authentication. Your administrator chose one when installing Watchtower (Identity providers).

The first time you sign in you may see no findings at all: nobody sees anything until an administrator gives them a grant. Ask your Watchtower administrator for access, naming the AWS accounts and Regions you work on.

#How fresh the data is

Watchtower keeps its own index of your Security Hub findings, which is why search, counts and the fix list are instant. A sync worker updates it every few minutes (15 by default) with what changed in Security Hub, and reads everything again once a day. The findings page shows how old its data is, and warns when a source fails to sync.

Some things are always live: opening a finding reads its full record and history straight from Security Hub, with your own identity. Changes you make (workflow status, notes, severity) are written to Security Hub at once and show in Watchtower immediately.

#Overview

Overview is the home page. For the findings you may view, it shows:

• Open findings by severity, suppressed findings, findings new and closed in the last 7 days, and overdue findings (open past their SLA due date).
• Mean time to remediate per severity: the median number of days between first seeing and closing the findings closed in the last 30 days.
• Trend: open findings per severity per day, with new and closed findings, over your plan's history (30 days on Starter, 90 on Team, 365 on Business, 730 on Enterprise).
• Ageing: open findings by age (0 to 7 days, 8 to 30, 31 to 90, 91 to 180, more than 180).
• Accounts by risk: the 50 accounts with the highest risk, with their open and overdue findings.
• Top issues: the 10 issues of the fix list with the highest risk.
• Security score: the share of passed control checks across your accounts and Regions, and the pass rate of each enabled standard.
• Products that report findings, and tasks open, overdue and done this week.

The Overview takes the same search as the findings page, so you can narrow it, for example to account:prod-*. The trend can only be narrowed by account, Region and connection; other filters don't apply to it, and the page says so.

#Findings

Findings is a fast explorer of every finding you may view. It shows open and suppressed findings by default; add state:closed to see closed ones (Watchtower keeps closed findings for 30 days by default).

A finding's state is Watchtower's summary of it:

#Search

Type in the search box. Words match anywhere in a finding's title, description, id, resource id and name, account id and name, control id, generator, product, finding types, CVEs, packages, resource tag values and note; every word must match. The box also understands filters, so a search is easy to type, read and share:

severity:critical,high account:prod-* -workflow:suppressed "public access" age>30

Filter fields:

Range fields: age (days since first observed), score (Security Hub's normalised severity, 0 to 100), updated, first (first observed, also firstSeen or observed) and created.

Examples:

While you type, the box suggests field names and values, with their counts.

#Filters with counts

The Filters panel lists each field's values with how many findings have them, among the findings that match everything else you searched for (so choosing high still shows how many critical findings there are). Choose a value to include it, or exclude it to add -field:value. The search box updates as you click, so the panel and the box always say the same thing.

#Sorting, columns and grouping

Sort by any column; the default is severity, then the most recently updated. Choose the columns to show. Group findings by control, account, resource type, product, Region, severity or workflow status: each group shows its count and severities, and opens to its findings. Grouping by control is a quick way to see what one fix would close.

#Saved views

A view saves the search, the filters, the sort, the grouping and the columns under a name. Views are private by default; on Team and above you can share a view with everyone (they can use it, only you and administrators can change it). The link of the page always holds the current search, so you can also share a search by copying the address. Each person can keep up to 10 views on Starter, 100 on Team, 500 on Business, and any number on Enterprise.

#Keyboard shortcuts

You can also click a row to open it, and Ctrl+click or Shift+click rows to select them.

#Bulk actions

Select findings to act on them together: set their workflow status, add a note, create a task, or create an exception from them. When every finding on screen is selected, you can select all the findings that match the search; changes to Security Hub go 500 findings at a time. Every finding in a change must be one you may triage, or nothing is changed and Watchtower names the first one you can't.

#Export

Export CSV downloads the findings that match the search, up to 50,000 rows, in the current sort order. For more, narrow the search and export in parts.

#Finding detail

Open a finding to see it in a side panel. The header shows its severity, title, state, and whether it is overdue or public, and lets you change its workflow status. A link opens the finding in the Security Hub console of its hub Region (you sign in to AWS there separately). The tabs:

The detail and history are read from Security Hub with your own identity, so CloudTrail records that you looked.

#Triage

With the triage permission on a Triage connection you can change, for one finding or up to 500 at once:

Changes are written to Security Hub with BatchUpdateFindings under your own identity, so they also show in the Security Hub console, and CloudTrail names you. Every change is in Watchtower's audit log.

#Fix list

Fix list groups findings by what fixes them, so 400 rows of "block public access on S3 buckets" become one line. An issue is the set of findings of one Security Hub control (c-S3.8) across every account and Region; findings without a control (Amazon GuardDuty, Amazon Inspector, partner products) are grouped by product and generator.

Each issue shows its title, its highest open severity, its risk, and how many findings are open, suppressed and closed in the last 30 days, how many resources and accounts it covers, its Regions and resource types, how many findings are overdue or exposed, whether a guide and an automatic fix exist, its tasks, and how many findings are mapped to code or flagged by code scanners. Sort by risk (the default), severity, open findings, resources, accounts, oldest or title.

The fix list takes the same search as the findings page, and the search applies to the findings: for example account:prod-* gives the fix list of production, and -task:with the issues nobody is working on yet.

#Risk

An issue's risk adds up its open findings. Each open finding counts:

• by severity: 40 points if critical, 20 if high, 6 if medium, 2 if low and 0 if informational;
• more as it ages: the points grow steadily from one times when the finding is new to three times at 180 days and older (twice at 90 days);
• double when the resource is exposed to the internet.

So ten critical findings that are six months old and public outweigh a hundred new medium ones. The same score ranks accounts on the Overview.

#Issue page

Open an issue to see its remediation guide, its findings (open and suppressed first, up to 1,000), code scanner findings for the same control in every repository, and its tasks. From there you can create a task for all its open findings, and, on the Business plan with the fix permission, preview and open a fix pull request (Code integrations).

#Remediation guides

Watchtower has built-in remediation guides for about 60 of the most common Security Hub controls (Amazon S3, IAM, Amazon EC2, Amazon RDS, AWS Lambda, Amazon DynamoDB, AWS KMS, AWS CloudTrail and others). Each guide is written for engineers:

• Why it matters: the risk in a paragraph;
• Steps: what to change, in the console or in general terms;
• AWS CLI: the command to fix one resource;
• Terraform and CloudFormation snippets, marked Automatic fix when Watchtower can patch your code for you;
• References to the AWS documentation;
• the code scanner rules (Trivy, Checkov) that check the same thing.

For controls without a guide, the finding's own remediation text and AWS documentation link are shown.

#Tasks

A task is work to fix a set of findings, with an owner and a due date. Tasks are numbered WT-1, WT-2 and so on. Create one from selected findings, from an issue (all its open findings you may view), from code scanner findings, or from scratch on Tasks.

SLA due dates. Each severity has a number of days to fix a finding, set by your administrator: by default 7 for critical, 30 for high, 90 for medium, 180 for low and none for informational. A finding is due that many days after it was first observed, and overdue while it is open after that.

Progress is counted from the findings: "12 of 38 closed" means 12 of the task's findings are now closed in Security Hub. It updates with every sync. With close automatically (on by default), the task is done when the last finding is closed.

Notify. When you create a task with the triage permission, you can mark its findings NOTIFIED in Security Hub with the note Tracked in Watchtower WT-<n>: <title>, so people in the Security Hub console see that someone is on it.

Comments and history. Add comments for discussion; status changes are recorded in the same thread. If someone else saved the task since you opened it, your save is refused so their change isn't lost: reload and apply yours again.

GitHub issues (Team and above). Create a GitHub issue from a task in one of the indexed repositories: it gets the task's title, description and a table of its findings, and is linked to the task.

Who sees a task. Administrators, its creator, its assignee, and everyone who may view at least one of its findings. Anyone who can see a task can edit it; only its creator or an administrator can delete it. Filter Tasks by status, by assignee (your own tasks, or someone else's) or by text.

#Exceptions

Team and above. An exception records an accepted risk: a reason, a scope and an expiry date. Unlike a permanent suppression in Security Hub, it ends on its own and the findings come back.

Before you save, Watchtower previews how many findings the exception matches, with a sample. Creating an exception needs the triage permission over its whole scope: every account pattern and Region in it.

While an exception is active, its findings read suppressed in Watchtower and drop out of the fix list, the risk and the overdue counts. With write back, the sync worker also sets them to SUPPRESSED in Security Hub with the note Watchtower exception "<title>" until <date>: <reason>, and applies the exception to new matching findings as they arrive. When it expires or is revoked, the findings it suppressed are set back to NEW with the note Watchtower exception "<title>" ended.

Everyone signed in can read the list of exceptions, so accepted risks are visible. The creator or an administrator can change or revoke one. Every change is in the audit log.

#Compliance

Compliance shows, for one connection and hub Region, the standards enabled in Security Hub and their controls, over the accounts and Regions you may view:

• Standards: each with its number of controls, how many passed and failed, and the percentage passed.
• Controls: each with its title, severity, standards, status (passed, failed or no data), passed and failed checks, how many accounts fail it, its open findings, and whether a guide and an automatic fix exist.

A control fails when any account you may view has an active failed finding for it. The pass counts come from the daily full sync, updated with the open findings of every sync.

#Code

Team and above. Code shows the GitHub repositories your administrator connected and what Watchtower found in them:

• Repositories: each with its branch, the commit last indexed, how many Terraform and CloudFormation files and resources it has, and how many of your findings are mapped to it.
• Resources and files: every Terraform resource and CloudFormation resource with its file and line. Open a file to read it at the indexed commit, with the resource highlighted.
• Scanner findings (Business and above): the results of built-in Trivy scans, SonarCloud and SARIF uploads from CI, searchable by repository, source, tool, category (misconfiguration, vulnerability, secret, code, security hotspot), severity, control and path. Rules that check the same thing as a Security Hub control are linked to it, so you see the cloud findings a code problem causes, and the reverse.
• Scans: the recent scans of each repository, and a way to start a Trivy scan.
• Pull requests that Watchtower opened, with their state.

On a finding, the Code tab shows where its resource is defined ("defined in infra/s3.tf:12"), with a confidence:

Scanner findings and repositories are visible to everyone signed in, since they come from your organisation's own code; code matches are shown only on findings you may view. How mapping, fixes and scanners work is in Code integrations.

#When something is refused