boogy/iam-policy-validator

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.