Connect AWS | ShellOrbit

These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.

AWS sends its account activity as CloudTrail events. An EventBridge rule picks the ones that matter for security and sends them to your source through an API destination. ShellOrbit gets no credentials for your account and can never act in it.

You need CloudTrail recording management events (an organization or account trail), and permission to create EventBridge rules, connections, and API destinations, in each region you want watched. Console sign ins and IAM events are recorded in us-east-1, so start there.

1. Create the source

In ShellOrbit, Settings, Integrations, Add source, choose AWS, and name it after the account. Copy the URL, and the header name and value shown on the source page.

2. Create the connection and API destination

In the AWS console, Amazon EventBridge, Integration, API destinations, Create API destination:

Connect AWS: Field, Value
Field	Value
API destination endpoint	The source URL, `https://hooks.shellorbit.com/e/...`
HTTP method	`POST`
Invocation rate limit	10 per second is plenty
Connection	Create a new connection, authorization type API Key, with the header name and value from the source page

3. Create the rule

EventBridge, Rules, Create rule, on the default event bus, with an event pattern. This pattern sends only the events the ready-made rules read, which keeps your source events low:

json
{
  "detail-type": [
    "AWS Console Sign In via CloudTrail",
    "AWS API Call via CloudTrail"
  ],
  "detail": {
    "eventName": [
      "ConsoleLogin", "StopLogging", "DeleteTrail", "UpdateTrail",
      "CreateAccessKey", "CreateUser", "AttachUserPolicy", "AttachRolePolicy",
      "AttachGroupPolicy", "AuthorizeSecurityGroupIngress",
      "DeleteBucketPublicAccessBlock", "DeleteDetector",
      "DisableSecurityHub", "ScheduleKeyDeletion"
    ]
  }
}

Add a second rule to the same API destination for anything the root user does:

json
{
  "detail": {
    "userIdentity": { "type": ["Root"] }
  }
}

For each rule choose the API destination as the target, and let EventBridge create its execution role. Repeat in each other region you use; console sign ins and IAM only need us-east-1.

What the ready-made rules detect

Connect AWS: Finding, Severity, CloudTrail evidence
Finding	Severity	CloudTrail evidence
Root user activity	Critical	`userIdentity.type` is `Root`
CloudTrail stopped, deleted, or changed	Critical	`StopLogging`, `DeleteTrail`, `UpdateTrail`
Console sign in without MFA	High	`ConsoleLogin` succeeded with `MFAUsed` set to `No`
Repeated failed console sign ins	High	5 failed `ConsoleLogin` events in 10 minutes
Administrator policy attached	High	`AdministratorAccess` attached to a user, role, or group
Security group opened to the internet	High	`AuthorizeSecurityGroupIngress` with `0.0.0.0/0` or `::/0`
S3 public access block removed	High	`DeleteBucketPublicAccessBlock`
GuardDuty or Security Hub disabled	High	`DeleteDetector`, `DisableSecurityHub`
KMS key scheduled for deletion	High	`ScheduleKeyDeletion`
Access key created	Medium	`CreateAccessKey`
IAM user created	Medium	`CreateUser`

Set silent hours on this source: if CloudTrail or the rule is switched off, the events stop, and silence is the only signal left.

Checking it works

Sign in to the AWS console. Within a minute or two the ConsoleLogin event shows in the source’s events. EventBridge shows failed invocations on the rule’s monitoring tab if the connection’s header is wrong.