Skip to content

Connect AWS read-only

One CloudFormation stack in your own account adds a role MarshalCloud can assume only with your External ID, and an hourly billing export into a bucket you own. The role reads; it changes nothing.

How do I install it?

  1. Start the connection

    On the connect page, choose Amazon Web Services, give the account a label if you like, and press Start. MarshalCloud makes a unique External ID for this account.

  2. Create the stack

    Press Connect AWS in one click, tick the box that allows creating the role, and press Create stack; the page finishes by itself, usually in about a minute. Or open Connect by hand and run:

    Shell (AWS CLI)
    curl -fsSLo aws-connect.yaml <template address>/aws-connect.yaml
aws cloudformation deploy --region us-east-1 --stack-name MarshalConnect \
  --template-file aws-connect.yaml --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides MarshalRoleArn=<MarshalCloud's role ARN> \
    ExternalId=<your External ID> ExportBucketName=<your bucket name>
# Paste RoleArn and BucketName from here into the connect page.
aws cloudformation describe-stacks --stack-name MarshalConnect --region us-east-1 \
  --query 'Stacks[0].Outputs' --output table

How you know it worked. The account shows as connected. Cost Explorer figures come first; the billing export follows within about 24 hours.

Signed in? Open this guide with your own valuesNot signed in: sign in, then open Settings, Setup guides.

What do I need first?

  • Every plan, Free included, connects AWS this way. Each plan allows a set number of cloud accounts.
  • An admin role in MarshalCloud: connecting is admin only.
  • In AWS, permission to create a CloudFormation stack with an IAM role (the stack asks for CAPABILITY_NAMED_IAM).
  • The stack must run in US East (N. Virginia), us-east-1: AWS serves the billing export service only there. The role itself works in every region.
  • Nothing to open on your side: no traffic comes into your network.

What access does it grant?

What it installs

  • An IAM role named MarshalReadRole. Only MarshalCloud's own service role can assume it, and only with your External ID.
  • An S3 bucket in your account for the cost export, with every public access setting blocked. Only AWS's billing service writes to it.
  • An hourly FOCUS 1.2 billing export (AWS Data Exports) delivered into that bucket as Parquet files.

What it can do

  • Read your bill: Cost Explorer, Savings Plans and reservations, budgets, and the hourly billing export the stack writes to your bucket.
  • List what is running and how it is set up (servers, databases, storage, networks, containers, functions and more) with Describe, List and Get calls only.
  • Read security settings: IAM users and policies, encryption, public access, CloudTrail, GuardDuty, Security Hub, Inspector and Access Analyzer findings.
  • Ask IAM to generate the credential report, the one call in the role that makes AWS produce something new.

What it never does

  • Change, stop or delete anything: the role has no write permission outside its own export bucket, which AWS writes to, not MarshalCloud.
  • Read secret values: GetSecretValue is not granted.
  • Read log contents, or the prompts and responses of AI models.
  • Keep a password or long-lived key when you use the secure link: it signs in with the role and your External ID each time.

How do I check or remove it?

  1. Disconnect the account

    In MarshalCloud, open Settings, Accounts and press Disconnect on this account (owners only). Reading stops at once.

  2. Delete the stack

    This removes the role and the billing export, so access ends even if the account were still connected. The export bucket is kept on purpose, so your billing history is not lost; the last line removes it too.

    Shell (AWS CLI)
    # If you named the stack differently, use that name.
aws cloudformation delete-stack --stack-name MarshalConnect --region us-east-1
aws cloudformation wait stack-delete-complete --stack-name MarshalConnect --region us-east-1
# To remove the bucket too (this deletes every export in it):
# aws s3 rb s3://<the BucketName output> --force

  3. Connected with an access key instead?

    Delete that access key in AWS (IAM, the user's Security credentials) as well: disconnecting only stops MarshalCloud using it.

What about the separate fix role?

It is optional, and never installing it is a supported way to use MarshalCloud. A second stack creates MarshalRemediateRole, separate from the read-only role, which can carry out only the fixes in MarshalCloud's action catalog, and only after a person approves each one. Each permission is scoped to its fix. To resize a container service, tag its task role and execution role marshal:passable = true in IAM first. Fixes are on Growth and Scaled.

  1. Create the fix role

    Run it in the connected account; it reuses that connection's External ID. There is no screen yet to record the role's RemediateRoleArn output in the product: today it is set through the API, so write to us before you rely on it.

    Shell (AWS CLI)
    curl -fsSLo aws-remediate.yaml <template address>/aws-remediate.yaml
aws cloudformation deploy --stack-name MarshalRemediate \
  --template-file aws-remediate.yaml --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides MarshalRoleArn=<MarshalCloud's role ARN> ExternalId=<your External ID>

  2. Remove the fix role

    Delete the stack. Fixes stop working at once; the read-only connection is not touched.

    Shell (AWS CLI)
    aws cloudformation delete-stack --stack-name MarshalRemediate
aws cloudformation wait stack-delete-complete --stack-name MarshalRemediate