How salesforce/policy_sentry works
Core Project Type and Purpose
• This is a Python-based command line tool (with library usage, Docker support, and even integrations for Terraform) that automates the generation of AWS IAM policies based on resource ARNs and access levels.
• The tool abstracts the complexity of crafting least-privilege IAM policies by reading IAM documentation data (stored in YAML files under “shared/data”) and providing functionality via various command modules.
Main Components
A. CLI & User Interface:
• Entry point(s) found in policy_sentry/bin (e.g., cli.py) where user commands such as “create-template”, “write-policy”, “query”, and “initialize” are parsed.
• Integration points for different interfaces such as the native Python CLI, Docker entrypoints (in “utils/entrypoint.sh” and Dockerfile), and even Homebrew commands.
B. Command & Control Layer:
• Mapping from CLI to these command modules.
C. Core Business Logic & Processing Engine:
• “analysis”, “querying”, and “writing” modules within policy_sentry. These form the core engine for processing user inputs:
– The Analysis component is responsible for interpreting input ARNs and expanding them into actionable sets.
– The Querying component provides methods to retrieve details from the IAM database (using data files provided under “shared/data”).
– The Writing component uses policy templates and logic to generate the final IAM policy JSON output.
• Incorporate the “util” modules that facilitate text processing, file handling, and access level management.
D. Data Management & Configuration:
• Configuration files (like pyproject.toml, .readthedocs.yml, and various GitHub workflows) that support building, testing, and documentation.
E. Testing and Documentation:
• “test” directory as an ancillary component that validates all functionality using unit and integration tests.
• That documentation is built via MkDocs (mkdocs.yml and docs/) and ReadTheDocs integration.
F. External Integration / Distribution Layers:
• Docker: Show the Dockerfile that builds the container image and related utilities in the “utils” directory.
• Homebrew & PyPI: Indicate that distribution mechanisms (e.g., Homebrew formula and pip installation) wrap around the core functionality.
• Terraform Module: Include the separate “terraform_module” directory, which demonstrates how Policy Sentry’s output is integrated into infrastructure as code use cases.
Relationships and Data Flow
• From the CLI, the command layer directs requests to the core engine. The engine consults the IAM data configuration (and any overrides) to compute relevant IAM actions.
• Finally, the engine outputs a JSON-formatted IAM policy for consumption.
• Also, illustrate the feedback loop for queries (e.g., where the “query” command reads from the IAM database) and note the modular design that separates these concerns.
Architectural Patterns and Design Principles
• A layered architecture where:
– The CLI/Interface layer manages I/O and user commands.
– The Command module maps these inputs to core business logic.
– The Core Engine handles the complex processing – applying a domain-specific abstraction (i.e., the logic for IAM policy generation).
– The Data layer segregates static resources, configuration, and external integrations.
• Separation of concerns, where each module such as analysis, querying, and writing is self-contained, improving testability.