# boogy/iam-policy-validator architecture

> Architecture diagram of the GitHub repository boogy/iam-policy-validator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boogy/iam-policy-validator
- Repository: https://github.com/boogy/iam-policy-validator

## Overview

1. **Repository purpose and shape**
   - This is a Python 3.10+ package that ships as both a CLI (`iam-validator`) and a reusable library (`iam_validator.sdk`).
   - The same validation engine powers multiple entrypoints: local CLI, GitHub Action, MCP server, and Python API.

2. **Primary execution path**
   - Input is one policy file or a directory of IAM policy documents in JSON/YAML.
   - The CLI loads configuration, detects policy type when needed, parses policies into internal models, runs checks, and emits a report in the chosen format.
   - Core flow is: load policy -> normalize/model -> run checks -> collect findings -> format output -> optionally post to PR or other integrations.

3. **Core validation engine**
   - `iam_validator/core` is the central subsystem.
   - It contains policy loading, type resolution, diff parsing, ignore handling, finding fingerprinting, rule registry, and report assembly.
   - `core/policy_checks.py` and `core/check_registry.py` connect policy documents to the individual check modules under `iam_validator/checks`.

4. **Check subsystem**
   - `iam_validator/checks` is organized as a catalog of focused validators: action validation, resource validation, principal validation, trust policy validation, wildcard detection, policy size, SID uniqueness, condition validation, and others.
   - These checks are split between:
     - AWS correctness checks, which verify policy syntax and semantic compatibility
     - security checks, which detect overbroad or risky permissions
   - Several checks depend on shared utilities in `checks/utils` for action parsing, wildcard expansion, formatting, and sensitive-action matching.

5. **Policy-type awareness**
   - The engine distinguishes identity policies, resource policies, trust policies, service control policies, and related variants.
   - Policy-type logic affects which checks run and how fields like `Principal`, `NotPrincipal`, and condition rules are interpreted.
   - This is why the same policy file can produce different validation behavior depending on context.

6. **AWS service metadata as a data source**
   - A major dependency is AWS IAM service-definition data: actions, resource types, and condition keys.
   - `iam_validator/core/aws_service` handles fetching, parsing, caching, storage, and validation of these service definitions.
   - The repository supports both online fetching from AWS and offline validation using a synced local service-definition directory.

7. **Configuration and organization-specific rules**
   - `iam_validator/core/config` loads the validator’s YAML configuration and merges defaults with user-defined rules.
   - This is where custom condition enforcement, sensitive-action rules, wildcard policies, principal requirements, and documentation metadata are modeled.
   - The architecture supports organization-specific policy gates, not just generic linting.

8. **Reporting and output layer**
   - Findings are rendered through `iam_validator/core/formatters`, with multiple output channels: console, enhanced terminal, JSON, CSV, Markdown, HTML, and SARIF.
   - `core/report.py`, `core/pr_commenter.py`, and related modules adapt the same findings into human-readable summaries and GitHub PR comments.
   - This separation lets the engine stay format-agnostic while downstream consumers choose the presentation.

9. **GitHub and CI/CD integration**
   - The GitHub Action entrypoint is defined in `action.yaml`, and the repository has workflows for CI, release, docs, prerelease, cleanup, and code quality.
   - `iam_validator/integrations/github_integration.py` and `core/pr_commenter.py` support diff-aware PR review comments, comment deduplication, and summary reporting.
   - The design is CI-first: validation can fail builds, annotate changed lines, and produce SARIF for code scanning.

10. **Optional AWS Access Analyzer integration**
   - `iam_validator/core/access_analyzer.py` and related report code add a second validation layer that requires AWS credentials.
   - This is separate from the offline built-in checks: the tool can first use Access Analyzer for AWS-backed analysis, then apply its own security and policy-specific rules on top.

11. **SDK and query layer**
   - `iam_validator/sdk` exposes programmatic helpers for validation, ARN matching, policy utilities, context, and query shortcuts.
   - `iam_validator/commands/query.py`, `download_services.py`, and `validate.py` provide operational commands for interacting with AWS service data and policy analysis from the CLI.
   - This makes the same engine usable in scripts and automation without invoking the full CLI workflow.

12. **MCP server and assistant tooling**
   - `iam_validator/mcp` exposes the validator as an MCP server with tools for validation, analysis, generation, and AWS service querying.
   - The Claude Code skill and plugin metadata in `.claude*` and `skills/iam-policy-validator` are packaging layers around the same CLI-oriented workflow.
   - These integrations do not introduce a new validation engine; they wrap the existing one for AI-assisted usage.

13. **Examples, docs, and tests as architecture signals**
   - `examples/` documents the supported policy types, checks, configs, CI patterns, custom checks, and offline AWS service data flow.
   - `docs/` is organized around getting started, user guide, developer guide, integrations, API reference, and custom check authoring.
   - `tests/` mirrors the production layout, which shows the intended boundaries: core logic, checks, CLI commands, integrations, SDK, and MCP each have their own test coverage.

14. **Overall architectural boundary**
   - The key boundary is between **policy analysis logic** and **consumers of analysis results**.
   - Core modules own parsing, rule execution, AWS metadata lookup, and finding generation.
   - CLI, GitHub Action, MCP server, SDK, and report/comment formatters are delivery surfaces built on top of that shared engine.

Main entry points: [`iam_validator/core/policy_checks.py`](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/policy_checks.py) (Policy checks), [`iam_validator/core/report.py`](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/report.py) (Reporting), [`iam_validator/core/cli.py`](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/cli.py) (CLI), [`iam_validator/checks`](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/checks) (Checks catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery surfaces"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_commands["Commands"]
  node_github["GitHub<br/>integration<br/>[action.yaml]"]
  node_github_integration["GitHub integration<br/>ci integration"]
end

subgraph group_core["Core engine"]
  node_policy_loader["Policy loader<br/>ingest<br/>[policy_loader.py]"]
  node_policy_checks["Policy checks<br/>orchestration<br/>[policy_checks.py]"]
  node_check_registry["Check registry<br/>[check_registry.py]"]
  node_config["Config<br/>[config_loader.py]"]
  node_aws_service["AWS service data<br/>metadata"]
  node_access_analyzer["Access Analyzer<br/>aws-backed analysis<br/>[access_analyzer.py]"]
  node_report["Reporting<br/>output assembly<br/>[report.py]"]
  node_formatters["Formatters<br/>renderers"]
  node_pr_commenter["PR commenter<br/>review output<br/>[pr_commenter.py]"]
  node_models(("Models<br/>[models.py]"))
end

subgraph group_checks["Checks"]
  node_checks_catalog["Checks catalog<br/>validators"]
  node_checks_utils["Check utils<br/>shared helpers"]
end

subgraph group_sdk["SDK"]
  node_sdk["SDK"]
end

subgraph group_mcp["MCP server"]
  node_mcp_server["MCP server<br/>tool server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>tooling"]
end

node_cli -->|"loads"| node_policy_loader
node_cli -->|"configures"| node_config
node_cli -->|"runs"| node_policy_checks
node_commands -->|"invokes"| node_policy_checks
node_commands -->|"manages"| node_aws_service
node_policy_loader -->|"creates"| node_models
node_config -->|"shapes"| node_policy_checks
node_policy_checks -->|"resolves"| node_check_registry
node_check_registry -->|"dispatches"| node_checks_catalog
node_checks_catalog -->|"shares"| node_checks_utils
node_checks_catalog -->|"queries"| node_aws_service
node_policy_checks -->|"reads"| node_models
node_policy_checks -->|"collects"| node_report
node_access_analyzer -->|"augments"| node_report
node_report -->|"renders"| node_formatters
node_report -->|"adapts"| node_pr_commenter
node_pr_commenter -->|"posts"| node_github_integration
node_github -->|"uses"| node_github_integration
node_mcp_server -->|"exposes"| node_mcp_tools
node_mcp_tools -->|"calls"| node_policy_checks
node_mcp_tools -->|"wraps"| node_sdk
node_sdk -->|"shares"| node_models
node_sdk -->|"assists"| node_policy_loader

click node_cli "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/cli.py"
click node_commands "https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/commands"
click node_github "https://github.com/boogy/iam-policy-validator/blob/main/action.yaml"
click node_mcp_server "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/mcp/server.py"
click node_mcp_tools "https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/mcp/tools"
click node_sdk "https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/sdk"
click node_policy_loader "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/policy_loader.py"
click node_policy_checks "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/policy_checks.py"
click node_check_registry "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/check_registry.py"
click node_config "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/config/config_loader.py"
click node_aws_service "https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/core/aws_service"
click node_access_analyzer "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/access_analyzer.py"
click node_report "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/report.py"
click node_formatters "https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/core/formatters"
click node_pr_commenter "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/pr_commenter.py"
click node_github_integration "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/integrations/github_integration.py"
click node_checks_catalog "https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/checks"
click node_checks_utils "https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/checks/utils"
click node_models "https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_commands,node_github,node_github_integration toneBlue
class node_policy_loader,node_policy_checks,node_check_registry,node_config,node_aws_service,node_access_analyzer,node_report,node_formatters,node_pr_commenter,node_models toneAmber
class node_checks_catalog,node_checks_utils toneMint
class node_sdk toneRose
class node_mcp_server,node_mcp_tools toneIndigo
```

## Components

### Delivery surfaces

CLI, action, MCP, and integrations that expose the shared engine

- [CLI](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/cli.py): entrypoint · Main command-line entrypoint and subcommand wiring · `iam_validator/core/cli.py`
- [Commands](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/commands): cli commands · Operational commands for validate, query, download, analyze, and PR posting · `iam_validator/commands`
- [GitHub](https://github.com/boogy/iam-policy-validator/blob/main/action.yaml): integration · GitHub Action and PR review integration surface · `action.yaml`
- [GitHub integration](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/integrations/github_integration.py): ci integration · GitHub-specific comment handling, deduplication, and review flow · `iam_validator/integrations/github_integration.py`

### Core engine

Policy loading, rule execution, AWS metadata, configuration, and reporting

- [Policy loader](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/policy_loader.py): ingest · Loads policy documents from files or directories into internal models · `iam_validator/core/policy_loader.py`
- [Policy checks](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/policy_checks.py): orchestration · Selects and runs checks for a given policy context · `iam_validator/core/policy_checks.py`
- [Check registry](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/check_registry.py): registry · Maps policy documents to the available validator modules · `iam_validator/core/check_registry.py`
- [Config](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/config/config_loader.py): configuration · Loads defaults and organization-specific validation rules · `iam_validator/core/config/config_loader.py`
- [AWS service data](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/core/aws_service): metadata · Fetches, parses, caches, and validates IAM service definitions · `iam_validator/core/aws_service`
- [Access Analyzer](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/access_analyzer.py): aws-backed analysis · Optional AWS-backed validation layer requiring credentials · `iam_validator/core/access_analyzer.py`
- [Reporting](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/report.py): output assembly · Builds findings, summaries, and review artifacts · `iam_validator/core/report.py`
- [Formatters](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/core/formatters): renderers · Console, JSON, CSV, Markdown, HTML, enhanced terminal, and SARIF output · `iam_validator/core/formatters`
- [PR commenter](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/pr_commenter.py): review output · Shapes findings into GitHub review comments and summaries · `iam_validator/core/pr_commenter.py`
- [Models](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/core/models.py): domain models · Shared policy and finding data structures · `iam_validator/core/models.py`

### Checks

Catalog of policy validators and shared check utilities

- [Checks catalog](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/checks): validators · Action, resource, principal, trust, wildcard, size, SID, and condition checks · `iam_validator/checks`
- [Check utils](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/checks/utils): shared helpers · Action parsing, wildcard expansion, formatting, and sensitive-action matching · `iam_validator/checks/utils`

### SDK

Programmatic helpers for validation and policy analysis

- [SDK](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/sdk): library · Reusable Python API for validation and policy utilities · `iam_validator/sdk`

### MCP server

Assistant-facing tools and server wrappers

- [MCP server](https://github.com/boogy/iam-policy-validator/blob/main/iam_validator/mcp/server.py): tool server · Model Context Protocol server and tool dispatch · `iam_validator/mcp/server.py`
- [MCP tools](https://github.com/boogy/iam-policy-validator/tree/main/iam_validator/mcp/tools): tooling · Validation, analysis, query, and generation tools exposed over MCP · `iam_validator/mcp/tools`

## Connections

- CLI → Policy loader: loads · CLI reads policy input and normalizes it
- CLI → Config: configures · CLI merges defaults and user rules
- CLI → Policy checks: runs · CLI invokes the validation pipeline
- Commands → Policy checks: invokes · Subcommands reuse the same engine
- Commands → AWS service data: manages · Download and cache commands maintain service data
- Policy loader → Models: creates · Parsed documents become internal policy models
- Config → Policy checks: shapes · Config determines enabled rules and thresholds
- Policy checks → Check registry: resolves · The engine selects applicable validators
- Check registry → Checks catalog: dispatches · Registry connects policy context to check modules
- Checks catalog → Check utils: shares · Validators depend on common parsing and matching helpers
- Checks catalog → AWS service data: queries · Checks use service definitions for action/resource/condition validation
- Policy checks → Models: reads · Validation runs over normalized policy models
- Policy checks → Reporting: collects · Findings are assembled into a report object
- Access Analyzer → Reporting: augments · AWS-backed findings are merged into reporting
- Reporting → Formatters: renders · Same findings are emitted in multiple output formats
- Reporting → PR commenter: adapts · Report data is adapted for PR summaries and comments
- PR commenter → GitHub integration: posts · GitHub-specific delivery uses integration helpers
- GitHub → GitHub integration: uses · Action workflow routes through GitHub integration code
- MCP server → MCP tools: exposes · Server publishes validation and query tools
- MCP tools → Policy checks: calls · MCP validation tools reuse the core engine
- MCP tools → SDK: wraps · MCP tooling leans on reusable SDK helpers
- SDK → Models: shares · SDK helpers work with the same domain objects
- SDK → Policy loader: assists · Programmatic APIs help load and analyze policy inputs