Amazon Web Services

Connect a client's AWS account so the agent can see what is really running: its servers (EC2), containers (ECS and EKS), functions (Lambda), databases (RDS), load balancers and their health, and CloudTrail's record of who changed what.

What the agent may do is up to you: it is set in AWS, by the policies of the role or user you give it. Nothing is off limits, access included, but every change waits for a person to approve it. See Changes below.

Three ways to sign in#

A role we take on#

1. 1

   Here, go to Settings › Accounts and cloud. Click Connect an account (or Connect another), and choose Amazon Web Services.

2. 2

   Under Sign-in, choose A role we take on. Choose the regions to look in under Where to look, and click Save. The External ID and Our AWS account now show: you need both for the role.

3. 3

   In the AWS console (console.aws.amazon.com), go to IAM › Roles and click Create role. Choose AWS account, then Another AWS account, and paste Our AWS account. Tick Require external ID and paste the External ID.

4. 4

   Add the permissions. To let the agent look, add Amazon's ReadOnlyAccess. To let it propose changes too, add the permissions those changes need, for example AmazonECS_FullAccess to change container services. See Which permissions.

5. 5

   Name the role, for example CerberiusAgent, and create it. On its page, copy its ARN.

6. 6

   Here, paste it under Role ARN, click Save, then Check connection.

The trust policy the console makes looks like this (with your values):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::<our AWS account>:root" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "<External ID>" } }
  }]
}

The External ID stops anyone else using your role through us: only your platform's requests carry it.

An access key#

1. 1

   In the AWS console, go to IAM › Users, create a user (for example cerberius-agent), and add its permissions: ReadOnlyAccess, plus whatever changes you want it to propose.

2. 2

   Add this statement to its permissions as well. The agent's pass is made from the key with it:

3. 3

   { "Effect": "Allow", "Action": "sts:GetFederationToken", "Resource": "*" }
   

   Copy
4. 4

   On the user's Security credentials tab, click Create access key, choose Application running outside AWS, and copy the Access key ID and the Secret access key. AWS shows the secret only once.

5. 5

   Here, under Sign-in, choose An access key, type both, choose the regions, click Save, then Check connection.

With an access key, the agent's pass can't read IAM itself (users, roles and policies): AWS doesn't allow that for a pass made from a key. Use a role if the agent should look at IAM.

Your runner's own role#

When the agent runs on your own runner inside AWS (EKS with a service account role, or a server with an instance role), choose Your runner's own role. Make the role as above, but in its trust policy name your runner's own role instead of our account. The External ID shown here is sent too; you may require it. Your runner needs version 0.13.0 or later.

Which permissions#

To look, ReadOnlyAccess is enough. Whatever the role allows, the agent's pass for an investigation is narrowed to ReadOnlyAccess by AWS itself, so it can never change anything.

To let it propose changes, add what those changes need. Some examples:

Give only what your team is happy for the agent to propose. A person approves each change.

The settings#

How the agent uses it#

• At the start of each investigation, Cerberius Agents takes on the role (or uses the key) and gives the agent a pass that lasts about an hour, narrowed to reading. The agent never sees the key.
• Its tools only read: describe, list and get. They never read a secret's value (Secrets Manager, Parameter Store).
• It looks only in the platform's regions.
• What it reads can appear in its findings as evidence. Secrets and keys are removed first.
• Fix runs (a change to code) never get AWS.

Changes#

To let the agent propose AWS changes, switch on Changes in Amazon Web Services on this page, or under Settings › Approved changes. See Allowing changes.

The agent then puts the exact calls in a change: the service, the operation, the region and its parameters. When it's approved (by two people, if you asked for that):

1. Cerberius Agents checks every call against Amazon's own description of it. EC2 calls are tried first without changing anything. If one fails, nothing runs.
2. It makes the calls in order, with the role's own permissions, and stops at the first one AWS refuses. The ticket says what was done.
3. The agent checks the result and drafts the reply to the requester.

A few calls are never made, whatever the role allows: any that hands out a key, a password or a token (it would land in the ticket), and any that sets a password the agent wrote. A person does those in the AWS console.

With your own runner#

When the agent runs on your own runner, choose Your runner's own role (no key anywhere) or An access key kept by you: Scrambled for your runner, or In your store (named aws-key, holding the access key ID and the secret access key joined by a colon). Your runner then signs in for each investigation, checks the connection and makes the approved changes. It makes none until its own rules allow them: add an aws section naming the services changes may call, for example services: [ecs, ec2].