Use cbx audit aws

cbx audit aws reads a live AWS account directly via the AWS SDK, grounds what it discovers in CloudBooster's curated AWS knowledge and rule pack, runs a local LLM CLI to produce cited findings, and writes a markdown report alongside terminal output. It's the live-account audit surface of the CLI.

It's designed for single-account, ad-hoc audits from a developer's laptop. Multi-account, continuous, or org-wide scanning is the hosted product's job — see Connect an AWS account.

Before you begin

• cbx-cli v1 or later installed — see the install guide.
• A CloudBooster account (cbx login) — the audit fetches curated knowledge and the rule pack from the CloudBooster API.
• A local LLM CLI on your PATH — claude (Claude Code) by default, or codex. The CLI owns its own auth.
• An AWS profile in ~/.aws/credentials (or AWS_PROFILE set, or --credentials-file <path> pointing at a credentials file).
• IAM permissions for the actions listed under Minimum IAM policy below.

Step 1 — Pick the profile

cbx audit aws resolves the profile with this precedence (highest wins):

1. --credentials-file <path> — explicit credentials file (overrides everything else).
2. Positional [profile] argument — cbx audit aws prod.
3. AWS_PROFILE environment variable.
4. The default profile.

# default profile
cbx audit aws
 
# named profile
cbx audit aws prod
 
# explicit credentials file
cbx audit aws --credentials-file ~/work/customer-x.credentials

Step 2 — Pick the region(s)

The --region flag is repeatable.

If the profile has no configured region and you're on an interactive terminal, you'll be prompted to pick. In non-interactive mode (--json/-o json, --quiet, or no TTY) you must pass --region explicitly — the command errors otherwise so a CI run can't silently scan the wrong place.

Step 3 — Run the audit

cbx audit aws prod --region us-east-1

Before any AWS call, a pre-discovery LLM preflight probes the chosen executor with a one-shot prompt. If the executor isn't on your PATH or isn't authenticated, the run aborts with E_LLM_PREFLIGHT before touching AWS.

Output goes in three places:

A typical header looks like:

✓ AWS preflight ok
  audited account:  123456789012
  identity:         arn:aws:iam::123456789012:user/alice
  audited regions:  us-east-1
  resources found:  42
  note:             this run generated ~120 CloudTrail Read events
  components (tag         ): 3
  components (cb-primitive): 7

The CloudTrail line is intentional — security-conscious teams ask about read-event volume before letting tools loose on a production account. For a small account expect ~50–200 events per run.

Minimum IAM policy

The CLI ships a curated least-privilege policy at docs/cbx-audit-aws-iam.json in the cbx-cli repository. The high-level groupings are:

The AWS-managed AWSReadOnlyAccess policy is a strict superset and is fine to use if you don't need least privilege.

AWS API calls are free

Every AWS API call cbx audit aws makes — Describe*, List*, Get* — is free. There's no per-call AWS charge to surface, so the report doesn't carry an AWS-cost line. The LLM analysis step does have a cost — see Choosing the executor below.

Choosing the executor

cbx audit aws always grounds its findings by running a local LLM CLI over discovered resources plus CloudBooster's curated knowledge. Pick which CLI drives it with --llm-executor:

The default follows cbx llm default when that names one of these executors; otherwise it's claude-code. So either pass the flag or set a default once:

# explicit, per-run
cbx audit aws prod --llm-executor codex
 
# make codex the default for all audits
cbx llm default codex
cbx audit aws prod            # now uses codex

The chosen CLI (claude or codex) must be on your PATH and is responsible for its own authentication. Pin the model it uses with --llm-model:

cbx audit aws prod --llm-executor codex --llm-model gpt-5-codex

The rule pack

The grounding rules come from a curated rule pack distributed over the CloudBooster API (/v1/knowledge/aws/rulepack) and cached locally at ~/.cache/cbx/rulepack/.

cbx audit aws prod --rulepack-version 2026.06.1

What if?

cbx llm cli test claude-code   # or: cbx llm cli test codex

cbx audit aws prod --diagnose

Permission errors during discovery:
  ✗ s3:ListAllMyBuckets    → AccessDenied (in global)
  ✗ iam:GetRole            → AccessDenied (in global)
  ✗ lambda:ListFunctions   → AccessDenied (in us-east-1)

Recommended IAM policy patch to fix the above:
  { "Effect": "Allow",
    "Action": ["s3:ListAllMyBuckets", "iam:GetRole", "lambda:ListFunctions"],
    "Resource": "*" }

Caller: arn:aws:iam::123456789012:user/alice

cbx audit aws prod --region all --aws-concurrency 2

Other useful flags

Where else can I audit?

Next steps

• Connect an AWS account for continuous, multi-account scanning in the hosted product.
• Run cbx audit in GitHub Actions.
• Use cbx audit — how the CLI surface relates to the library state-file path.
• cbx audit failures — troubleshooting common errors.