# IAM Policy Lint
A comprehensive tool for linting and validating AWS IAM (Identity and Access Management) policies in JSON, YAML, and embedded formats. Built around the powerful [Parliament](https://github.com/duo-labs/parliament) library, this tool helps you identify security issues, policy problems, and structural errors in your IAM policies.
## Features
- 🔍 **Deep Policy Analysis**: Uses Parliament to detect security issues and policy problems
- 📝 **Structure Validation**: Validates basic IAM policy structure and syntax
- 🔧 **Multiple Formats**: Supports JSON and YAML IAM policies, plus embedded policies in YAML
- 🎯 **Embedded Policy Support**: Extract and lint IAM policies embedded in Kubernetes manifests, Terraform, CloudFormation, etc.
- 📁 **Directory Scanning**: Lint all policies in a directory at once
- 🎯 **Severity Filtering**: Filter findings by severity level (CRITICAL, HIGH, MEDIUM, LOW)
- 📊 **Multiple Output Formats**: Human-readable text or machine-readable JSON output
- 🖥️ **CLI Interface**: Easy-to-use command-line interface
- 🔗 **Pre-commit Integration**: Automated policy checking in Git workflows
## Installation
### Prerequisites
- Python 3.12+
- pyenv (recommended for Python version management)
- uv (for package management)
### Setup
1. **Clone the repository**:
```bash
git clone https://github.com/yourusername/iam-policy-lint.git
cd iam-policy-lint
```
2. **Set Python version** (if using pyenv):
```bash
pyenv local 3.12
```
3. **Install dependencies**:
```bash
uv sync
```
4. **Install the package** (for development):
```bash
uv pip install -e .
```
## Usage
### Command Line Interface
#### Lint a single policy file
```bash
iam-policy-lint lint examples/policy.json
# Lint a YAML policy
iam-policy-lint lint examples/policy.yaml
# With severity filtering and JSON output
iam-policy-lint lint examples/policy.json --severity HIGH --format json
```
#### Validate policy structure
```bash
# Basic structure validation
iam-policy-lint validate examples/policy.json
# Validation with JSON output
iam-policy-lint validate examples/policy.json --format json
```
#### Lint directory of policies
```bash
# Lint all policies in a directory
iam-policy-lint lint-dir examples/
# With file pattern and severity filtering
iam-policy-lint lint-dir examples/ --pattern "*.yaml" --severity MEDIUM
# Directory linting with JSON output
iam-policy-lint lint-dir examples/ --format json
```
#### Lint embedded policies in YAML files
```bash
# Lint policies embedded in Kubernetes manifests, Terraform, CloudFormation, etc.
iam-policy-lint lint-embedded examples/kubernetes-manifest.yaml
# Lint with custom key path
iam-policy-lint lint-embedded examples/terraform.yaml --key-path "data.policy_document"
# Lint with multiple key paths
iam-policy-lint lint-embedded examples/config.yaml \
--key-path "spec.policies[].document" \
--key-path "metadata.annotations.\"iam.policy\""
# Only show critical issues
iam-policy-lint lint-embedded examples/manifest.yaml --severity CRITICAL
```
**Example YAML with embedded IAM policy:**
```yaml
# Kubernetes ServiceAccount with IAM policy annotation
apiVersion: v1
kind: ServiceAccount
metadata:
name: my-service-account
annotations:
"iam.policy": |
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject"],
"Resource": "arn:aws:s3:::my-bucket/*"
}
]
}
```
### Python API
```python
from iam_policy_lint import IAMLinter, IAMValidator
# Initialize linter and validator
linter = IAMLinter()
validator = IAMValidator()
# Lint a policy file
findings = linter.lint_file("path/to/policy.json")
for finding in findings:
print(f"{finding['severity']}: {finding['title']}")
# Validate policy structure
errors = validator.validate_file("path/to/policy.json")
for error in errors:
print(f"{error['severity']}: {error['message']}")
# Lint a policy dictionary directly
policy = {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "*",
"Resource": "*"
}]
}
findings = linter.lint_policy(policy)
validation_errors = validator.validate_policy(policy)
# Lint embedded policies from YAML
embedded_findings = linter.lint_embedded_policies("path/to/manifest.yaml")
for finding in embedded_findings:
print(f"Embedded policy issue: {finding['title']}")
```
## Example Output
### Text Output (Default)
```
🔍 Linting results for: examples/overly-permissive.json
============================================================
🔴 Issue #1 - HIGH
Title: Wildcard action
Issue: WILDCARD_ACTION
Description: Action contains a wildcard that allows all actions
Location: Statement[0].Action
🔴 Issue #2 - HIGH
Title: Wildcard resource
Issue: WILDCARD_RESOURCE
Description: Resource contains a wildcard that allows access to all resources
Location: Statement[0].Resource
```
### JSON Output
```json
[
{
"issue": "WILDCARD_ACTION",
"title": "Wildcard action",
"description": "Action contains a wildcard that allows all actions",
"severity": "HIGH",
"location": "Statement[0].Action",
"detail": null
}
]
```
## Policy Examples
The `examples/` directory contains sample IAM policies:
- `valid-policy.json` - A well-structured policy with specific permissions
- `overly-permissive.json` - A policy with security issues (wildcards)
- `policy.yaml` - A YAML-formatted policy
- `invalid-policy.json` - A structurally invalid policy
## Development
### Running Tests
```bash
# Run all tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src/iam_policy_lint
# Run specific test file
uv run pytest tests/test_validator.py
```
### Code Quality
```bash
# Format code
uv run black src/ tests/
# Lint code
uv run flake8 src/ tests/
# Type checking
uv run mypy src/
```
## Dependencies
### Core Dependencies
- **[Parliament](https://github.com/duo-labs/parliament)** - AWS IAM linting library
- **[PyYAML](https://github.com/yaml/pyyaml)** - YAML parser
- **[Click](https://github.com/pallets/click)** - CLI framework
### Development Dependencies
- **pytest** - Testing framework
- **pytest-cov** - Coverage reporting
- **black** - Code formatter
- **flake8** - Linter
- **mypy** - Type checker
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite and ensure all tests pass
6. Submit a pull request
## License
This project is licensed under the MIT License. See the LICENSE file for details.
## Acknowledgments
- [Parliament](https://github.com/duo-labs/parliament) by Duo Labs for the core IAM policy analysis engine
- [AWS IAM Policy Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) for policy structure guidelines
Raw data
{
"_id": null,
"home_page": null,
"name": "iam-policy-lint",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "aws, embedded, governance, iam, json, lint, parliament, policy, security, validation, yaml",
"author": null,
"author_email": "Richard Gilmore <richard.gilmore@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/62/6e/13838ef179f9478587ce12ab5b1e177c4f2f03dde9305ded16b5d61101e0/iam_policy_lint-0.3.2.tar.gz",
"platform": null,
"description": "# IAM Policy Lint\n\nA comprehensive tool for linting and validating AWS IAM (Identity and Access Management) policies in JSON, YAML, and embedded formats. Built around the powerful [Parliament](https://github.com/duo-labs/parliament) library, this tool helps you identify security issues, policy problems, and structural errors in your IAM policies.\n\n## Features\n\n- \ud83d\udd0d **Deep Policy Analysis**: Uses Parliament to detect security issues and policy problems\n- \ud83d\udcdd **Structure Validation**: Validates basic IAM policy structure and syntax\n- \ud83d\udd27 **Multiple Formats**: Supports JSON and YAML IAM policies, plus embedded policies in YAML\n- \ud83c\udfaf **Embedded Policy Support**: Extract and lint IAM policies embedded in Kubernetes manifests, Terraform, CloudFormation, etc.\n- \ud83d\udcc1 **Directory Scanning**: Lint all policies in a directory at once\n- \ud83c\udfaf **Severity Filtering**: Filter findings by severity level (CRITICAL, HIGH, MEDIUM, LOW)\n- \ud83d\udcca **Multiple Output Formats**: Human-readable text or machine-readable JSON output\n- \ud83d\udda5\ufe0f **CLI Interface**: Easy-to-use command-line interface\n- \ud83d\udd17 **Pre-commit Integration**: Automated policy checking in Git workflows\n\n## Installation\n\n### Prerequisites\n\n- Python 3.12+\n- pyenv (recommended for Python version management)\n- uv (for package management)\n\n### Setup\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/yourusername/iam-policy-lint.git\n cd iam-policy-lint\n ```\n\n2. **Set Python version** (if using pyenv):\n ```bash\n pyenv local 3.12\n ```\n\n3. **Install dependencies**:\n ```bash\n uv sync\n ```\n\n4. **Install the package** (for development):\n ```bash\n uv pip install -e .\n ```\n\n## Usage\n\n### Command Line Interface\n\n#### Lint a single policy file\n\n```bash\niam-policy-lint lint examples/policy.json\n\n# Lint a YAML policy\niam-policy-lint lint examples/policy.yaml\n\n# With severity filtering and JSON output\niam-policy-lint lint examples/policy.json --severity HIGH --format json\n```\n\n#### Validate policy structure\n\n```bash\n# Basic structure validation\niam-policy-lint validate examples/policy.json\n\n# Validation with JSON output\niam-policy-lint validate examples/policy.json --format json\n```\n\n#### Lint directory of policies\n\n```bash\n# Lint all policies in a directory\niam-policy-lint lint-dir examples/\n\n# With file pattern and severity filtering\niam-policy-lint lint-dir examples/ --pattern \"*.yaml\" --severity MEDIUM\n\n# Directory linting with JSON output\niam-policy-lint lint-dir examples/ --format json\n```\n\n#### Lint embedded policies in YAML files\n\n```bash\n# Lint policies embedded in Kubernetes manifests, Terraform, CloudFormation, etc.\niam-policy-lint lint-embedded examples/kubernetes-manifest.yaml\n\n# Lint with custom key path\niam-policy-lint lint-embedded examples/terraform.yaml --key-path \"data.policy_document\"\n\n# Lint with multiple key paths\niam-policy-lint lint-embedded examples/config.yaml \\\n --key-path \"spec.policies[].document\" \\\n --key-path \"metadata.annotations.\\\"iam.policy\\\"\"\n\n# Only show critical issues\niam-policy-lint lint-embedded examples/manifest.yaml --severity CRITICAL\n```\n\n**Example YAML with embedded IAM policy:**\n```yaml\n# Kubernetes ServiceAccount with IAM policy annotation\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n name: my-service-account\n annotations:\n \"iam.policy\": |\n {\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\"s3:GetObject\"],\n \"Resource\": \"arn:aws:s3:::my-bucket/*\"\n }\n ]\n }\n```\n\n### Python API\n\n```python\nfrom iam_policy_lint import IAMLinter, IAMValidator\n\n# Initialize linter and validator\nlinter = IAMLinter()\nvalidator = IAMValidator()\n\n# Lint a policy file\nfindings = linter.lint_file(\"path/to/policy.json\")\nfor finding in findings:\n print(f\"{finding['severity']}: {finding['title']}\")\n\n# Validate policy structure\nerrors = validator.validate_file(\"path/to/policy.json\")\nfor error in errors:\n print(f\"{error['severity']}: {error['message']}\")\n\n# Lint a policy dictionary directly\npolicy = {\n \"Version\": \"2012-10-17\",\n \"Statement\": [{\n \"Effect\": \"Allow\",\n \"Action\": \"*\",\n \"Resource\": \"*\"\n }]\n}\n\nfindings = linter.lint_policy(policy)\nvalidation_errors = validator.validate_policy(policy)\n\n# Lint embedded policies from YAML\nembedded_findings = linter.lint_embedded_policies(\"path/to/manifest.yaml\")\nfor finding in embedded_findings:\n print(f\"Embedded policy issue: {finding['title']}\")\n```\n\n## Example Output\n\n### Text Output (Default)\n\n```\n\ud83d\udd0d Linting results for: examples/overly-permissive.json\n============================================================\n\n\ud83d\udd34 Issue #1 - HIGH\nTitle: Wildcard action\nIssue: WILDCARD_ACTION\nDescription: Action contains a wildcard that allows all actions\nLocation: Statement[0].Action\n\n\ud83d\udd34 Issue #2 - HIGH\nTitle: Wildcard resource\nIssue: WILDCARD_RESOURCE\nDescription: Resource contains a wildcard that allows access to all resources\nLocation: Statement[0].Resource\n```\n\n### JSON Output\n\n```json\n[\n {\n \"issue\": \"WILDCARD_ACTION\",\n \"title\": \"Wildcard action\",\n \"description\": \"Action contains a wildcard that allows all actions\",\n \"severity\": \"HIGH\",\n \"location\": \"Statement[0].Action\",\n \"detail\": null\n }\n]\n```\n\n## Policy Examples\n\nThe `examples/` directory contains sample IAM policies:\n\n- `valid-policy.json` - A well-structured policy with specific permissions\n- `overly-permissive.json` - A policy with security issues (wildcards)\n- `policy.yaml` - A YAML-formatted policy\n- `invalid-policy.json` - A structurally invalid policy\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=src/iam_policy_lint\n\n# Run specific test file\nuv run pytest tests/test_validator.py\n```\n\n### Code Quality\n\n```bash\n# Format code\nuv run black src/ tests/\n\n# Lint code\nuv run flake8 src/ tests/\n\n# Type checking\nuv run mypy src/\n```\n\n## Dependencies\n\n### Core Dependencies\n- **[Parliament](https://github.com/duo-labs/parliament)** - AWS IAM linting library\n- **[PyYAML](https://github.com/yaml/pyyaml)** - YAML parser\n- **[Click](https://github.com/pallets/click)** - CLI framework\n\n### Development Dependencies\n- **pytest** - Testing framework\n- **pytest-cov** - Coverage reporting\n- **black** - Code formatter\n- **flake8** - Linter\n- **mypy** - Type checker\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite and ensure all tests pass\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## Acknowledgments\n\n- [Parliament](https://github.com/duo-labs/parliament) by Duo Labs for the core IAM policy analysis engine\n- [AWS IAM Policy Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) for policy structure guidelines\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive tool for linting and validating AWS IAM policies in JSON and YAML formats using Parliament",
"version": "0.3.2",
"project_urls": {
"Changelog": "https://github.com/gilandose/iam-policy-lint/releases",
"Documentation": "https://github.com/gilandose/iam-policy-lint#readme",
"Homepage": "https://github.com/gilandose/iam-policy-lint",
"Issues": "https://github.com/gilandose/iam-policy-lint/issues",
"Repository": "https://github.com/gilandose/iam-policy-lint"
},
"split_keywords": [
"aws",
" embedded",
" governance",
" iam",
" json",
" lint",
" parliament",
" policy",
" security",
" validation",
" yaml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "06c9f5a23004aac526c9cb694ae896fbd40b7fcc270bced4c2a56d48623f1d7f",
"md5": "840618f7975871c0ca03649d4ff9bc55",
"sha256": "d46361ec81db19b6630290056d12ef1cc993429373531f2e8b238e53d455febf"
},
"downloads": -1,
"filename": "iam_policy_lint-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "840618f7975871c0ca03649d4ff9bc55",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14943,
"upload_time": "2025-08-07T13:25:59",
"upload_time_iso_8601": "2025-08-07T13:25:59.438377Z",
"url": "https://files.pythonhosted.org/packages/06/c9/f5a23004aac526c9cb694ae896fbd40b7fcc270bced4c2a56d48623f1d7f/iam_policy_lint-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "626e13838ef179f9478587ce12ab5b1e177c4f2f03dde9305ded16b5d61101e0",
"md5": "f48736ed0513e13f0aa8ead79d99f3f7",
"sha256": "65f15a4a4c2f10d8dea626ac9ff04531eaee7327b49c3af6264d91ff4d6fe0ec"
},
"downloads": -1,
"filename": "iam_policy_lint-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "f48736ed0513e13f0aa8ead79d99f3f7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17295,
"upload_time": "2025-08-07T13:26:00",
"upload_time_iso_8601": "2025-08-07T13:26:00.701414Z",
"url": "https://files.pythonhosted.org/packages/62/6e/13838ef179f9478587ce12ab5b1e177c4f2f03dde9305ded16b5d61101e0/iam_policy_lint-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 13:26:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gilandose",
"github_project": "iam-policy-lint",
"github_not_found": true,
"lcname": "iam-policy-lint"
}
JSON
