AWS¶
Cloud platforms. CloudTrail management events, plus GuardDuty, Security Hub, and Amazon Inspector findings.
Status: available now - you connect this yourself
This source is live in the console. Create the read-only credential below, connect it on its card in Integrate -> Sources, and your dedicated instance starts collecting.
What SheerSight reads¶
SheerSight reads security-relevant AWS activity straight from the AWS APIs, using a read-only role in your account. Four feeds:
- CloudTrail management events (root usage, logging stopped, and other control-plane changes),
- GuardDuty findings,
- Security Hub findings and control results, and
- Amazon Inspector findings.
That feed powers detections such as root account usage, CloudTrail logging stopped, high-severity GuardDuty, an access-denied burst, critical Inspector vulnerabilities, and Security Hub control failures and high-severity findings.
All four are separate AWS services that you switch on yourself, so read Enable the services you want collected before you connect.
Everything is read-only, and it is exactly six API operations - no more (listed under what SheerSight can and cannot do).
Check the scope you are granting
The role reads whatever the account you create it in can see. If that account is your Security
Hub, GuardDuty, or Inspector delegated administrator, those findings APIs return findings for
every member account in your organization - and, with cross-region aggregation on, from every
linked region. cloudtrail:LookupEvents returns that one account's full 90-day control-plane
history. Create the stack in the account whose scope you actually mean to share.
Enable the services you want collected¶
Quick Connect reads four separate AWS services, and they are switched on separately. The role you create gives SheerSight permission to read them. It does not turn any of them on. A service that is off in your account stays off, and SheerSight collects nothing from it.
- CloudTrail management events are on by default in every AWS account. Nothing for you to do.
- GuardDuty, Security Hub and Amazon Inspector are opt-in and off by default. Each one you want has to be enabled by you, in the account and region you connect, and AWS bills you for it.
| Service | What it covers | On by default? | Where you enable it |
|---|---|---|---|
| CloudTrail | Management (control-plane) activity: root account use, logging being turned off, permission changes, and the like | Yes | Already on - it is the Event history view in the CloudTrail console |
| GuardDuty | AWS's own threat-detection findings for the account | No | GuardDuty console, Enable GuardDuty |
| Security Hub | Findings collected from other AWS security services, plus pass/fail results for security-standard controls | No | Security Hub console, then enable Security Hub |
| Amazon Inspector | Vulnerability findings for EC2 instances, container images and Lambda functions | No | Amazon Inspector console, then turn Inspector on for the account |
You do not have to enable all three of the opt-in services. Connect with just CloudTrail if that is what you want: the console will say plainly which services are off rather than leaving you to assume they are covered.
One connection covers one AWS account and one region
This is the expectation most often wrong, so it is worth being blunt. A connection signs in to one AWS account - the one you created the stack in - and collects from one region, the one you chose on the card. SheerSight does not reach into your other accounts or your other regions, and does not combine them for you.
If you need more than one account or more than one region watched, get in touch at security@sheersafe.com before you rely on a single connection.
One thing does cross accounts, and it is AWS's doing rather than ours: if the account you connect is a delegated administrator for GuardDuty, Security Hub or Inspector, AWS hands it findings from its member accounts too, as the warning above says. CloudTrail is never like that. It is always that one account's activity, in that one region.
What you'll need¶
- An AWS account admin who can create a CloudFormation stack and an IAM role in the account you want monitored.
- The region you want collected. One connection covers one account and one region.
- The services you want collected switched on in that account and region (above).
- Your dedicated instance enrolled.
Create the read-only credential¶
There is no access key anywhere in this design. SheerSight never asks for an AWS access key ID or secret. Instead you run a small CloudFormation stack that creates one read-only cross-account IAM role which only SheerSight's collector account can assume, and only when it presents the external ID issued for your tenant. You paste back the role's ARN.
Work through the AWS card in the console (Integrate -> Sources -> AWS) - it carries your external ID and builds the Launch-Stack link for you. About two minutes.
- Copy your External ID. The card shows it. It is unique to your tenant and is what stops anyone else using the role even if they learn its ARN. The Launch-Stack link fills it in for you, and the CloudFormation form keeps it masked - leave it exactly as it arrives, do not retype or edit it.
-
Choose the region you want collected - do this first. The card's region selector starts empty on purpose and there is no default. Your choice does two things at once: it is where SheerSight collects from, and it is the region the Launch-Stack link opens CloudFormation in. Until you pick one, there is no link to click.
Pick the region before you launch
This ordering is the whole point. A stack created in a region SheerSight is not polling connects successfully, shows a healthy card, and collects nothing - there is no signal anywhere that tells you. Choose the region on the card, then launch, and leave the AWS console's own region picker alone.
Regions that AWS requires you to enable per account are grouped separately in the selector. If the Launch link lands on a "region is not enabled" page, that is why: enable it (AWS console -> your account menu -> Account -> Regions), then launch again. If the region you need is not in the list, tell us rather than picking the nearest one.
-
Create the stack in AWS. Sign in to the AWS account you want monitored, then use the card's Launch AWS setup link. CloudFormation opens pre-filled, in the region you chose. Before it will let you continue you must tick the acknowledgement:
I acknowledge that AWS CloudFormation might create IAM resources with custom names.
That box is required and is not boilerplate you can skip - the stack creates one named read-only role, so CloudFormation needs the
CAPABILITY_NAMED_IAMacknowledgement. Then choose Create stack. -
Copy the RoleArn output. When the stack reaches
CREATE_COMPLETE, open its Outputs tab and copy theRoleArnvalue. The stack'sRegionoutput is only a record of where you ran it; the role itself works from any region and SheerSight collects from the region you chose in step 2 either way.
Re-running the stack creates a new role
The role name carries the stack's own identifier, so if you ever delete and recreate the stack, or run it again, AWS creates a different role with a new ARN. Paste the new Role ARN back on the card, or collection stops.
Revoking takes one click
Delete the stack and the role goes with it. Access is revoked immediately, with nothing left behind in your account and no key to rotate.
Disconnecting in SheerSight is not the same thing. Disconnect stops collection: it shuts down the collectors on your instance and forgets your role ARN. It does not touch your AWS account, and it cannot - the role we create grants six read-only actions and nothing that could delete a stack. The role stays in your account and still trusts us until you delete the stack. Disconnect to pause collection; delete the stack to end our access.
Connect it in SheerSight¶
In the console, open Integrate -> Sources -> AWS and fill in:
| Field | Value |
|---|---|
| Region to collect from | The region you chose in step 2. Set this before launching the stack. |
| Role ARN | The stack's RoleArn output from step 4. |
Press Connect.
AWS is the one source with nothing encrypted
Every other source relays a secret, encrypted in your browser. AWS relays none, because there is no secret to relay: a role ARN is not sensitive, and the external ID is already shown to you and lives in your own CloudFormation stack. So AWS has no relayed credentials entry - the console sends only a signed instruction to start collection.
What the console shows for each service¶
Because the four services are enabled separately, the console reports them separately. The AWS card in Integrate -> Sources shows one badge for the source overall, and expanding the card lists each service with its own state underneath.
The badge on the card:
| Badge | What it means |
|---|---|
| not connected | Nothing has been connected yet, or this source was disconnected |
| activating | Connected, waiting for the first results |
| live | Everything we check is collecting |
| partial | Some of it is collecting, and at least one service is not enabled |
| not enabled | None of them are on yet |
| error | Something is genuinely wrong, such as a call that keeps failing |
| stalled | It was collecting and has stopped |
Reading partial¶
partial is the one to read carefully. It means: we are collecting, but not everything you might assume. That is not a fault and nothing is broken - it is us telling you that a service you may believe is being watched was never switched on, so no amount of waiting will produce anything from it.
Expand the card to see which service. Each one that is off gets its own line naming it and the region it was checked in, for example "GuardDuty is not enabled in us-east-1." Enable it in your AWS console and the badge goes to live on its own, usually within a few minutes. There is nothing to reconnect and no credential to redo.
We cannot tell whether Inspector is enabled
GuardDuty and Security Hub both say plainly when they are switched off, so the console can report those two accurately. Amazon Inspector does not. When we ask Inspector for findings, an account with Inspector switched off answers with an empty list - which is exactly the answer we get from an account with Inspector on that happens to have no vulnerabilities. We cannot tell the two apart.
So Inspector normally shows as live whether or not it is enabled, with no findings either way. Please do not read that badge as confirmation that Inspector is on. If you are counting on Inspector, check it yourself in the Amazon Inspector console, for the account and region you connected. The other three services are reported accurately.
Verify¶
- The AWS source badge moves from not connected to live once the role is assumed and polling starts - or to partial, if one of the four services is not enabled.
- Expand the card and read the per-service rows. Anything marked not enabled is waiting on you to turn it on in AWS.
- CloudTrail events and findings begin appearing, and matching detections start firing.
- Confirm events are arriving from the region you expected. A healthy badge on its own does not prove the region is right.
Troubleshooting¶
- Connect is refused. The Role ARN has to be the stack's
RoleArnoutput as written, and a region has to be selected. Both are checked before anything is sent. - Access denied when assuming the role. Usually the External ID was edited rather than left as the Launch link filled it in, or the stack was created in a different AWS account than the one you meant. Re-run the stack from the card's link and paste the new Role ARN.
- Connected but no events. Most often the stack landed in a region you are not actually using, or the account has no GuardDuty/Security Hub/Inspector findings in the window you are looking at. Check the region first.
- The badge says partial. One or more of the four services is not enabled in the account and region you connected. Expand the card to see which, then turn it on in AWS. Nothing is broken and there is nothing to reconnect.
- The badge says not enabled. None of the four reported anything collectable. Check that you connected the account and region you meant to, and that at least one service is on there.
- GuardDuty findings are missing in another region. A connection covers one region only. Regions you did not connect are not collected, and the console will not claim otherwise.
- It worked and then stopped. Check whether the stack was deleted or re-run. A re-run means a new Role ARN to paste back.
What SheerSight can and cannot do¶
The role grants exactly six read-only operations and nothing else:
cloudtrail:LookupEvents
guardduty:ListDetectors
guardduty:ListFindings
guardduty:GetFindings
securityhub:GetFindings
inspector2:ListFindings
Every one of them returns data; none creates, changes, or deletes anything. SheerSight cannot modify AWS resources, security settings, or IAM, cannot write to or delete your logs, and cannot act in your account. It only reads events and findings. The role trusts SheerSight's collector account alone, and only with your external ID.