CLI Reference¶
Complete documentation for the iam-validator command-line interface.
Commands¶
| Command | Description |
|---|---|
validate |
Validate IAM policies |
analyze |
AWS Access Analyzer integration |
post-to-pr |
Post results to GitHub PR |
query |
Query AWS service definitions |
cache |
Manage AWS service cache |
sync-services |
Sync AWS definitions for offline use |
completion |
Generate shell completion scripts |
mcp |
Start MCP server for AI assistant integration |
<command> -h lists options only. Every command prints its usage examples with
--examples, e.g. iam-validator validate --examples; required arguments are not needed.
validate¶
Validate IAM policies for correctness and security issues.
Usage¶
iam-validator validate [OPTIONS]
Options¶
Input:
| Option | Description | Default |
|---|---|---|
--path, -p |
Path to policy file or directory (can be specified multiple times) | Required |
--stdin |
Read policy from stdin (JSON format) |
Output:
| Option | Description | Default |
|---|---|---|
--format, -f |
Output format (console, enhanced, json, markdown, html, csv, sarif) | console |
--output, -o |
Output file path (for json/markdown/html/csv/sarif) | |
--summary |
Show Executive Summary section in enhanced output | false |
--severity-breakdown |
Show Issue Severity Breakdown in enhanced output | false |
--verbose, -v |
Enable verbose logging | false |
Validation:
| Option | Description | Default |
|---|---|---|
--config, -c |
Path to configuration file | Auto-detect |
--policy-type, -t |
Policy type (IDENTITY_POLICY, RESOURCE_POLICY, TRUST_POLICY, SERVICE_CONTROL_POLICY, RESOURCE_CONTROL_POLICY). When omitted, each policy's type is auto-resolved per file (config policy_types: glob → content detection → IDENTITY_POLICY). See Policy Type Resolution. |
auto-detect |
--fail-on-warnings |
Fail validation if warnings are found | false |
--no-recursive |
Don't recursively search directories | false |
--custom-checks-dir |
Path to directory containing custom checks | |
--aws-services-dir |
Path to pre-downloaded AWS service definitions (offline mode) |
Performance:
| Option | Description | Default |
|---|---|---|
--stream |
Process files one-by-one (memory efficient) | false |
--batch-size |
Number of policies per batch (only with --stream) | 10 |
GitHub Integration:
| Option | Description | Default |
|---|---|---|
--github-comment |
Post summary comment to PR conversation | false |
--github-review |
Create line-specific review comments on PR files | false |
--github-summary |
Write summary to GitHub Actions job summary | false |
--allow-owner-ignore |
Allow CODEOWNERS to ignore findings by replying 'ignore' | true |
--no-owner-ignore |
Disable CODEOWNERS ignore feature | false |
--comment-tag |
Run scope tag (1-32 chars, [A-Za-z0-9._-]) for parallel runs on same PR |
unset |
CI Mode:
| Option | Description | Default |
|---|---|---|
--ci |
CI mode: enhanced console output + JSON report to file | |
--ci-output |
Output file for JSON report in CI mode | validation-report.json |
Examples¶
# Validate a single file
iam-validator validate --path policy.json
# Validate a directory
iam-validator validate --path ./policies/
# With custom config
iam-validator validate --path ./policies/ --config iam-validator.yaml
# JSON output
iam-validator validate --path policy.json --format json
# Trust policy validation
iam-validator validate --path trust-policy.json --policy-type TRUST_POLICY
Output Formats¶
| Format | Description |
|---|---|
console |
Rich terminal output (default) |
enhanced |
Colorful detailed output |
json |
Machine-readable JSON |
sarif |
SARIF for security tools |
markdown |
Markdown report |
html |
HTML report |
csv |
CSV export |
query¶
Query AWS service definitions for actions, ARNs, condition keys, and global condition keys.
Usage¶
iam-validator query <subcommand> [OPTIONS]
Options¶
The --service option is optional when --name includes the service prefix (e.g., s3:GetObject).
| Option | Description |
|---|---|
--service |
AWS service prefix (optional if --name has prefix) |
--name |
Name(s) to query; supports multiple values, wildcards, and service prefix (s3:GetObject) |
--output |
Output format: json, yaml, or text |
--show-condition-keys |
Show only condition keys for each action |
--show-resource-types |
Show only resource types for each action |
--show-access-level |
Show only access level for each action |
--show-data-plane |
Show only the data-plane classification for each action |
--data-plane |
query action: only data-plane actions (AWS IsDataPlane: true) |
--control-plane |
query action: only control-plane actions (IsDataPlane: false); unclassified excluded |
--show-service-name |
query action: show only the AWS service name for each action |
--show-types |
query condition / global-condition: show only each key's value types |
--show-description |
query global-condition: show only each key's description |
--show-doc-url |
query global-condition: show only each key's documentation URL |
--access-level, --resource-type, --has-condition-key, --data-plane and --control-plane
apply to every query action mode: listing a service, exact names and wildcards.
Examples¶
query -h lists options only. Print grouped usage examples with:
iam-validator query --examples # all topics
iam-validator query examples # all topics
iam-validator query examples action # action, arn, condition, global-condition, output
Subcommands¶
query action¶
.action is always the full service:action name. description appears only when the AWS
Service Reference provides one.
# List all S3 actions
iam-validator query action --service s3
# Filter by access level
iam-validator query action --service iam --access-level permissions-management
# Get specific action (two equivalent forms)
iam-validator query action --service s3 --name GetObject
iam-validator query action --name s3:GetObject
# Query with service prefix in --name (--service not required)
iam-validator query action --name iam:CreateRole
iam-validator query action --name ec2:DescribeInstances --output yaml
# Filter write-level actions
iam-validator query action --service s3 --access-level write --output text
# Expand wildcard patterns to matching actions
iam-validator query action --name "iam:Get*" --output text
iam-validator query action --name "s3:*Object*" --output json
iam-validator query action --service ec2 --name "Describe*" --output text
# Count matching actions
iam-validator query action --name "ec2:Describe*" --output text | wc -l
# Query MULTIPLE actions at once (space-separated)
iam-validator query action --name dynamodb:Query dynamodb:Scan --output yaml
iam-validator query action --name s3:GetObject s3:PutObject ec2:DescribeInstances
# Mix exact names and wildcards
iam-validator query action --name dynamodb:Query dynamodb:BatchGet* --output json
iam-validator query action --name iam:CreateRole iam:Delete* --output text
Multiple Action Queries¶
The --name option accepts multiple space-separated action names, allowing you to query several actions in a single command:
# Query multiple specific actions
iam-validator query action --name dynamodb:Query dynamodb:Scan --output yaml
# Query actions across different services
iam-validator query action --name s3:GetObject ec2:DescribeInstances iam:GetRole
# Mix exact names with wildcards for powerful queries
iam-validator query action --name dynamodb:Query dynamodb:BatchGet* --output json
iam-validator query action --name iam:CreateRole iam:Delete* --output text
This feature is optimized for performance:
- Actions are grouped by service to minimize API calls
- Service definitions are fetched in parallel when querying multiple services
- Wildcards and exact matches are processed efficiently in a single pass
Wildcard Pattern Expansion¶
The --name option supports wildcard patterns (* and ?) to find all matching actions:
*matches zero or more characters?matches exactly one character
This is useful for:
- Exploring available actions for a permission prefix
- Finding all actions related to a specific operation
- Generating action lists for least-privilege policies
# Find all IAM Get actions
iam-validator query action --name "iam:Get*" --output text
# Output: iam:GetAccessKeyLastUsed, iam:GetAccountAuthorizationDetails, ...
# Find all S3 Object-related actions
iam-validator query action --name "s3:*Object*" --output text
# Output: s3:DeleteObject, s3:GetObject, s3:PutObject, ...
# Get detailed JSON output for wildcard results
iam-validator query action --name "iam:Create*" --output json
Output Field Filters¶
Use --show-condition-keys, --show-resource-types, or --show-access-level to filter output to only specific fields:
# Show only condition keys for DynamoDB actions
iam-validator query action --name dynamodb:Query dynamodb:Scan --show-condition-keys --output yaml
# Show only resource types for S3 wildcard actions
iam-validator query action --name "s3:Get*" --show-resource-types --output text
# Show only access level for multiple actions
iam-validator query action --name iam:CreateRole iam:DeleteRole --show-access-level
# Combine multiple filters
iam-validator query action --name s3:GetObject --show-condition-keys --show-resource-types --output yaml
These filters work with all query modes (single action, multiple actions, wildcards) and all output formats.
Data-plane filters¶
# Data-plane actions (e.g. s3:GetObject)
iam-validator query action --service s3 --data-plane --output text
# Control-plane write actions
iam-validator query action --service s3 --control-plane --access-level write
AWS annotates actions with IsDataPlane. Actions without the annotation match neither
flag; some services (e.g. kms, iam) currently have no data-plane actions.
query arn¶
# List ARN formats
iam-validator query arn --service s3
# Specific resource type (two equivalent forms)
iam-validator query arn --service s3 --name bucket
iam-validator query arn --name s3:bucket
# Get ARN format for IAM role
iam-validator query arn --name iam:role
query condition¶
# List condition keys
iam-validator query condition --service s3
# Query specific condition key (two equivalent forms)
iam-validator query condition --service s3 --name prefix
iam-validator query condition --name s3:prefix
# Only key names and value types
iam-validator query condition --service s3 --show-types --output text
query global-condition¶
Global condition keys come from the AWS Service Reference
(global-condition-keys.json), with a bundled fallback when offline.
# List all global condition keys
iam-validator query global-condition --output text
# Filter by value type (case-insensitive)
iam-validator query global-condition --type IPAddress
# One key; tag keys resolve to their ${TagKey} template
iam-validator query global-condition --name aws:SourceIp
iam-validator query global-condition --name aws:ResourceTag
# Keys matching a wildcard (case-insensitive)
iam-validator query global-condition --name 'aws:Re*' --output text
# Only selected fields
iam-validator query global-condition --type Bool --show-description --show-doc-url --output text
cache¶
Manage the AWS service definition cache.
Usage¶
iam-validator cache <subcommand> [OPTIONS]
Subcommands¶
| Subcommand | Description |
|---|---|
info |
Show cache information and statistics |
list |
List all cached AWS services |
clear |
Clear all cached AWS service definitions |
refresh |
Refresh all cached services with fresh data |
prefetch |
Pre-fetch common AWS services (without clearing) |
location |
Show cache directory location |
Examples¶
# Show cache info
iam-validator cache info
# List all cached services
iam-validator cache list
iam-validator cache list --format table
# Clear cache completely
iam-validator cache clear
# Refresh all cached services with fresh data from AWS
iam-validator cache refresh
# Pre-fetch common AWS services
iam-validator cache prefetch
# Show cache directory location
iam-validator cache location
Options¶
| Option | Subcommand | Description |
|---|---|---|
--config |
all | Path to configuration file |
--format |
list |
Output format: table, columns, simple |
sync-services¶
Download AWS service definitions for offline validation.
Usage¶
# Sync all services to the default directory (aws_services/)
iam-validator sync-services
# Sync to a custom directory
iam-validator sync-services --output-dir /path/to/backup
# Limit concurrent downloads
iam-validator sync-services --max-concurrent 5
Options¶
| Option | Description | Default |
|---|---|---|
--output-dir |
Output directory for downloads | aws_services |
--max-concurrent |
Maximum concurrent downloads | 10 |
completion¶
Generate shell completion scripts for bash and zsh.
Usage¶
iam-validator completion {bash|zsh} [--install]
Options¶
| Option | Description | Default |
|---|---|---|
--install |
Write the script to the user completion directory instead of stdout |
Install¶
--install writes the completion script for you and prints the single line to
add to your shell rc file:
$ iam-validator completion zsh --install
installed to /Users/you/.local/share/zsh/site-functions/_iam-validator
add this to ${ZDOTDIR:-$HOME}/.zshrc, once:
fpath+=('/Users/you/.local/share/zsh/site-functions')
autoload -Uz compinit && compinit
Install locations:
| Shell | Path |
|---|---|
zsh |
~/.local/share/zsh/site-functions/_iam-validator |
bash |
~/.local/share/bash-completion/completions/iam-validator |
XDG_DATA_HOME is honoured when set, replacing ~/.local/share. The script is
rewritten every time, so re-running --install after an upgrade always leaves
the completions current.
Print to stdout¶
Without --install the script is written to stdout, for evaluating directly or
redirecting somewhere else:
# Evaluate in the current shell
eval "$(iam-validator completion bash)"
eval "$(iam-validator completion zsh)"
# Or write it wherever you keep completions
iam-validator completion bash > ~/.bash_completion.d/iam-validator
mcp¶
Start an MCP (Model Context Protocol) server for AI assistant integration.
iam-validator-mcp (a standalone entry point) and iam-validator mcp (this
subcommand) share one argparse layer, so both accept identical flags and resolve
them to an identical ServerSettings. Every flag also has an IAM_VALIDATOR_MCP_*
environment variable equivalent; flags win over env vars, env vars win over
defaults. This table is checked against the parser by
tests/mcp/test_cli_reference_doc.py — a flag added to iam_validator/mcp/cli.py
without a matching row here fails that test.
Usage¶
iam-validator mcp [OPTIONS]
Options¶
| Option | Description | Default |
|---|---|---|
--mode |
Server mode: local or hosted |
local |
--transport |
Transport: stdio or http (sse was removed, not deprecated) |
stdio |
--host |
Bind host, used only with --transport http |
127.0.0.1 |
--port |
Bind port, used only with --transport http |
8000 |
--config |
Path to configuration YAML file, loaded at startup | None |
--auth |
Auth provider: none, token, jwt, or an IdP name (azure/google/github/keycloak/auth0/workos); token/JWT/IdP material is env-var- or file-only, never a flag |
none |
--profile |
Limit exposed tools: full, validate-only, validate-and-query, read-only |
full |
--list-profiles |
Print the profile → tool taxonomy and exit | — |
--custom-checks-dir |
Directory of custom PolicyCheck modules to auto-discover |
None |
--aws-services-dir |
Directory of pre-downloaded AWS service definitions (offline mode) | None |
--cache-directory |
Directory for the AWS service-data disk cache | None |
--instructions |
Inline custom instructions appended to the default LLM instructions | None |
--instructions-file |
Path to a file with custom instructions (mutually exclusive with --instructions) |
None |
--allowed-regions |
Comma-separated AWS regions analyze_policy may target |
server's own region |
--analyze-rate-limit |
Max analyze_policy calls per minute per worker process; 0 disables |
10 |
--max-policies |
Max policies accepted in one validate_policies call |
50 |
--max-policy-bytes |
Max size of a single policy, in bytes | 1 MiB |
--max-request-bytes |
Max total request size, in bytes | 8 MiB |
--request-timeout-s |
Per-request timeout, in seconds | 60 |
--max-response-bytes |
Max response size before detail is degraded and the response marked truncated |
4 MiB |
Examples¶
# Start with stdio transport (for Claude Desktop)
iam-validator mcp
# Start with Streamable HTTP transport
iam-validator mcp --transport http --host 127.0.0.1 --port 8000
# Start with config preloaded
iam-validator mcp --config ./config.yaml
# List the tool taxonomy for each --profile value
iam-validator mcp --list-profiles
See the MCP Server Integration guide for the tool
reference, and MCP Hosting for --mode hosted
deployments.
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | Success - all policies valid |
| 1 | Validation errors found |
| 2 | Configuration or input error |
Environment Variables¶
| Variable | Description |
|---|---|
IAM_VALIDATOR_CONFIG |
Default config file path |
IAM_VALIDATOR_CACHE_DIR |
Cache directory location |
NO_COLOR |
Disable colored output |