policy-scout

README

policy-scout

Explore AWS Organizations service control policies (SCPs) from a terminal. Policy Scout shows where an account sits in the organization and which SCPs it inherits, without requiring several AWS CLI calls or manual console navigation.

Table of Contents

• Features
• Prerequisites
• Usage
• Automation and agent usage
• Output
• Version and JSON compatibility
• Tooling
• License
• Feedback

Features

• Display one account's path from the organization root, or the complete tree with --account-id all.
• Display directly attached and inherited SCPs for every returned member account.
• Identify the management account, where SCPs are not enforced.
• Produce structured json (default) or a human-readable text tree.

Prerequisites

Policy Scout uses the AWS SDK default configuration and credential chain. Configure credentials before running it. Pass --profile <name> to select an AWS shared-config profile explicitly; this selection takes precedence over AWS_PROFILE. When --profile is omitted, the SDK's normal profile selection and default credential chain are unchanged. Policy Scout itself never prompts, but an external credential provider may require you to authenticate before a non-interactive run.

The selected AWS identity must be able to inspect the organization. Depending on the requested scope, Policy Scout calls:

• organizations:ListRoots
• organizations:DescribeOrganization
• organizations:DescribeAccount
• organizations:DescribeOrganizationalUnit
• organizations:ListParents
• organizations:ListPoliciesForTarget
• organizations:ListChildren when using --account-id all

Usage

Check which AWS identity the default credential chain resolves and whether it can access AWS Organizations:

policy-scout aws auth status
policy-scout aws auth status --output-format text

The status command calls AWS STS GetCallerIdentity and Organizations DescribeOrganization. It reports the credential source and expiration when available, but never displays secret credential values. A successful identity check with denied Organizations access is reported in the output and returns a nonzero exit status.

Inspect one account (JSON is the default):

policy-scout aws --account-id 339712974046

Select a named AWS shared-config profile explicitly:

policy-scout aws --profile security-audit --account-id 339712974046

Inspect the entire organization and save structured output:

policy-scout aws --account-id all --output-format json > organization.json

Request a terminal-friendly tree:

policy-scout aws --account-id 339712974046 --output-format text
policy-scout aws --account-id all --output-format text

Bound AWS work for a CI job or coding agent:

policy-scout aws --account-id all --output-format json --timeout 30s --max-retries 3

• --timeout <duration> sets one overall deadline for AWS configuration and credential loading plus all Organizations API traversal. Durations use Go syntax such as 500ms, 30s, or 2m. The value must be greater than zero.
• --max-retries <count> limits each AWS API request to that many retries after its initial attempt. 0 disables retries; accepted values are 0 through 10. Retryability and backoff remain managed by the AWS SDK.
• When either flag is omitted, Policy Scout does not override that setting. In particular, omitting --max-retries preserves the AWS SDK default or settings from the AWS environment and shared configuration files.

Run policy-scout aws --help for complete, copyable command examples and input requirements.

Discover the installed binary version:

policy-scout version
policy-scout version --output-format json

Automation and agent usage

Policy Scout is non-interactive and is designed to be safe to invoke from scripts and coding agents such as Amp, Claude Code, and Codex:

1. Run policy-scout aws --help to discover the supported operation and flags.
2. Ensure AWS credentials are already available through the default credential chain.
3. Use --output-format json explicitly in automation, even though JSON is the default.
4. Set --timeout and, when needed, --max-retries so a degraded AWS endpoint cannot leave the caller waiting indefinitely.
5. Check the exit status before parsing stdout. Exit status 0 means stdout contains one JSON document; a nonzero status means the operation failed and stderr contains a diagnostic.
6. Add --error-format json to receive one machine-readable JSON error on stderr. This flag is independent of --output-format and may appear before or after the subcommand.

The CLI does not use confirmation prompts, interactive input, a pager, or colored output. Successful data is written to stdout and errors are written to stderr, so redirection and JSON processors work predictably:

if policy-scout aws --account-id all --output-format json > organization.json; then
  jq '.. | objects | select(.type? == "account")' organization.json
fi

For example, an agent can capture successful data and structured errors separately:

policy-scout --error-format json aws --account-id all \
  > organization.json 2> policy-scout-error.json

JSON errors have this stable shape. operation and request_id are omitted when unavailable. Messages and remediation are curated and never include credentials or raw credential-provider errors.

{
  "code": "aws_access_denied",
  "message": "AWS denied the Organizations request.",
  "operation": "ListRoots",
  "retryable": false,
  "request_id": "example-request-id",
  "remediation": "Grant the selected identity the required AWS Organizations read permissions, then retry."
}

Exit statuses and stable error codes are:

Exit	Error code	Meaning
0	—	Success.
1	unexpected	An unexpected local or AWS response failure.
2	invalid_invocation	Invalid command, flag, argument, or input value.
3	aws_credentials	Missing, invalid, or expired AWS credentials.
4	aws_access_denied	AWS authorization denied the operation.
5	aws_transient	Retryable network, throttling, or AWS service failure.

Human-readable stderr remains the default. Retry transient failures with backoff; correct the invocation or credentials/permissions before retrying other classified failures.

Output

JSON output is a tree rooted at the AWS organization root. Nodes use these fields:

• schema_version: the organization JSON compatibility version; present on the root node.
• type: root, organizational_unit, or account.
• id: the AWS entity ID.
• name: the entity name, when applicable.
• management_account: true for the management account.
• scps: sorted, de-duplicated effective SCP names for a member account.
• children: nested organization nodes.

Fields that do not apply or contain no values may be omitted. The successful JSON document is not wrapped in a status envelope.

{
  "schema_version": "1",
  "type": "root",
  "id": "r-cww9",
  "children": [
    {
      "type": "organizational_unit",
      "id": "ou-cww9-x2atbcle",
      "name": "Finance",
      "children": [
        {
          "type": "account",
          "id": "339712974046",
          "name": "aws-child1",
          "scps": ["DenyAccessS3", "FullAWSAccess"]
        }
      ]
    }
  ]
}

Text output renders the same hierarchy as a tree:

|-- Root: [r-cww9]
    |-- OU: Prod [ou-cww9-36h7ub42]
        |-- OU: Finance [ou-cww9-x2atbcle]
            |-- Account: aws-child1 [339712974046] (SCPs: DenyAccessS3, FullAWSAccess)

Version and JSON compatibility

policy-scout version --output-format json provides machine-readable binary and schema discovery without AWS credentials:

{
  "version": "1.2.3",
  "organization_schema_version": "1"
}

Release binaries report their release version; binaries built directly with go build report dev. The organization output's root-level schema_version matches organization_schema_version above.

Within one schema version, consumers must tolerate additive object fields and should use the type field rather than assume every node has identical fields. Removing or renaming fields, changing their types or meanings, or restructuring the document is a breaking change and requires a new schema_version. The successful organization document remains an unwrapped root node.

Tooling

• Mise pins the development tools used locally and in CI. Run mise install after cloning the repository, then use the Make targets for local workflows.
• Cobra CLI
• GolangCI-Lint
• Goreleaser
• go-semantic-release
• GitHub Workflows
• Pre-Commit
• EditorConfig

License

Policy Scout is released under the Apache 2.0 license. See LICENSE.

Feedback

Feel free to open an issue to report a bug or submit a feature request. PRs are also welcome!

Documentation

Overview

Copyright © 2024 Aristides Gonzalez aristides@glezpol.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.