https://github.com/jemo19/infra-plan-scanner
Terraform/OpenTofu plan scanner for security, tagging, deletion, and cost-risk checks.
https://github.com/jemo19/infra-plan-scanner
devops github-actions iac opentofu policy-as-code security terraform
Last synced: 10 days ago
JSON representation
Terraform/OpenTofu plan scanner for security, tagging, deletion, and cost-risk checks.
- Host: GitHub
- URL: https://github.com/jemo19/infra-plan-scanner
- Owner: jemo19
- License: mit
- Created: 2026-06-15T22:09:21.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2026-06-15T23:53:49.000Z (10 days ago)
- Last Synced: 2026-06-16T00:09:07.726Z (10 days ago)
- Topics: devops, github-actions, iac, opentofu, policy-as-code, security, terraform
- Language: Python
- Size: 64.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# InfraGuard Plan Scanner
[](https://github.com/jemo19/infra-plan-scanner/actions/workflows/ci.yml)
[](https://github.com/jemo19/infra-plan-scanner/actions/workflows/codeql.yml)
[](LICENSE)
[](pyproject.toml)
Catch risky AWS and Azure infrastructure changes before `terraform apply`.
InfraGuard is a local Terraform/OpenTofu plan scanner for engineers who want a
fast review gate for tagging, public exposure, encryption, IAM, deletion,
resilience, and cost-risk checks. It reads `terraform show -json` output,
normalizes resource changes, runs built-in policies, supports reviewed
suppressions/baselines, and emits Markdown, JSON, or SARIF.
## Install
From a release package:
```bash
python -m pip install infraguard-plan-scanner
infraguard --help
```
From this checkout:
```bash
python -m pip install -e ".[dev]"
infraguard --help
```
## 5-Minute Demo
```bash
infraguard scan fixtures/risky-plan.json --format markdown || true
infraguard scan fixtures/azure-risky-plan.json --format markdown || true
infraguard scan fixtures/safe-plan.json --format json
infraguard scan fixtures/azure-safe-plan.json --format json
infraguard rules --format markdown
infraguard explain IG016
```
The risky fixtures fail the default `high` severity gate with actionable
findings. The safe fixtures exit zero.
## Terraform Plan Workflow
Use fake or non-production data while evaluating the tool.
```bash
terraform init
terraform plan -out plan.out
terraform show -json plan.out > plan.json
infraguard scan plan.json --format markdown
```
To generate a starter config:
```bash
infraguard init --profile aws-azure --output infraguard.json
infraguard validate infraguard.json --kind config
infraguard scan plan.json --config infraguard.json
```
Checked-in starter packs live in [`examples/packs/`](examples/packs/).
## Output Formats
```bash
infraguard scan fixtures/risky-plan.json --format markdown
infraguard scan fixtures/risky-plan.json --format json --output report.json
infraguard scan fixtures/risky-plan.json --format sarif --output report.sarif
```
JSON results include `schema_version`, active findings, suppressed findings,
unused suppressions, and the effective rule catalog for the scan. SARIF includes
stable `partialFingerprints` based on InfraGuard finding IDs.
Checked-in examples live in [`examples/outputs/`](examples/outputs/).
## Suppressions And Baselines
Use a suppression file for findings that have been reviewed and accepted. A
suppression requires a stable `finding_id`, or a `rule_id` plus
`resource_address`, and a non-empty `reason`.
```bash
infraguard baseline fixtures/risky-plan.json --output examples/outputs/risky-baseline.json --min-severity high
infraguard scan fixtures/risky-plan.json --suppressions examples/outputs/risky-baseline.json --min-severity high
infraguard scan fixtures/risky-plan.json --suppressions examples/suppressions.json --include-suppressed
```
Suppressed findings are excluded from the severity gate. JSON output always
includes `suppressed_findings`; Markdown and SARIF include suppressed findings
only when `--include-suppressed` is set.
## Severity Gate
`--min-severity` controls the exit status.
```bash
infraguard scan fixtures/risky-plan.json --min-severity high
infraguard scan fixtures/risky-plan.json --min-severity medium
infraguard scan fixtures/risky-plan.json --min-severity low
```
Exit codes:
| Code | Meaning |
|---:|---|
| 0 | Scan completed and no findings met the severity gate |
| 1 | Scan completed and at least one finding met the severity gate |
| 2 | Input, parser, or configuration error |
Use `--report-only` to render findings while exiting zero after a successful
parse and config validation.
## Built-In Policies
InfraGuard v1 ships 20 built-in rules across AWS, Azure, and multi-provider
governance checks. Use the CLI or generated docs as the source of truth:
```bash
infraguard rules
infraguard rules --format json
infraguard explain IG005
```
See [`docs/RULES.md`](docs/RULES.md) and
[`docs/POLICY_AUTHORING.md`](docs/POLICY_AUTHORING.md).
## GitHub Actions
Use [`examples/github-action.yml`](examples/github-action.yml) as the copy/paste
starting point. The v1 Action is report-only by default, writes a GitHub Step
Summary, and uploads SARIF when paired with `github/codeql-action/upload-sarif`.
Set `fail-on-findings: "true"` after reviewing and baselining existing findings.
```yaml
- name: Scan plan with InfraGuard
uses: jemo19/infra-plan-scanner@v1
with:
plan-path: plan.json
output: infraguard.sarif
fail-on-findings: "false"
```
## Schemas
Machine-readable schemas are checked in under [`schemas/`](schemas/):
- `config.schema.json`
- `result.schema.json`
- `suppressions.schema.json`
Regenerate them after model changes:
```bash
python scripts/generate_schemas.py
```
## Local Checks
```bash
python -m pytest
python -m ruff check .
python -m ruff format --check .
python scripts/generate_schemas.py
python scripts/generate_policy_docs.py
python -m build
```
## Limitations
- The scanner does not run Terraform state-changing commands.
- Fixture plans are fake and intentionally small.
- Policy configuration and suppressions are JSON-only in v1.
- OPA/Rego plugins, Docker images, GCP coverage, and a PR comment bot are
post-v1 backlog items.
## Security
Do not scan or commit production secrets, private Terraform state, customer data,
or proprietary infrastructure details. See [`SECURITY.md`](SECURITY.md).
## License
MIT. See [`LICENSE`](LICENSE).