vpcatlas iam-policy

vpcatlas [GLOBAL OPTIONS] iam-policy [OPTIONS]

What it does

Prints the minimal read-only IAM policy for the auditor role: the smallest set of Describe*, Get*, List* and Search* actions that the collectors call. It is the same document as deploy/iam/auditor-policy.json in the repository, packaged with the tool so it is available in the binary, the Python package and the Docker image.

The command never calls AWS and needs no credentials. The policy has Core* statements (what the diagrams need) and Optional* statements (the extra services of the inventory), plus one Deny statement, DenyApiGatewaySecrets, that keeps the auditor away from API key values and client certificates. With --core-only only the statements whose Sid starts with Core are printed, so the Deny statement is left out too. Which actions each statement allows and why: iam.

The policy goes to standard output as indented JSON. With --output it is written to the file and the path is printed.

Options

Flag	Environment variable	Default	Description
--core-only	none	off	Only the statements the diagrams need; skip the optional ones.
--output, -o	none	standard output	Write to this file, not to stdout. Missing parent directories are created.

Files it writes

Only the file named by --output. Without it nothing is written to disk.

Examples

A local run, saving the policy to a file and attaching it as an inline policy to the auditor role in the account to audit:

vpcatlas iam-policy --output auditor-policy.json
aws iam put-role-policy --role-name AtlasAuditor --policy-name VpcAtlasAuditor --policy-document file://auditor-policy.json

For a role that other accounts assume with an external id, save the core statements, attach them to the role and require the external id in its trust policy. vpcatlas then assumes the role with --role-arn and --external-id:

vpcatlas iam-policy --core-only --output core-policy.json
vpcatlas discover \
  --role-arn arn:aws:iam::111122223333:role/VpcAtlasAuditor --external-id my-external-id

The trust policy of that role carries a condition on sts:ExternalId:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::999988887777:root" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "my-external-id" } }
  }]
}

Docker:

docker run --rm vpcatlas/vpcatlas iam-policy > auditor-policy.json

Exit codes

Code	When
0	The policy was printed or written.
1	The policy file inside the installation was not found, or the --output file cannot be written.
2	Bad usage: an unknown option, or --output pointing at a directory.

Details and typical causes: exit codes.