InfraGuard

A read-only-first Kubernetes and Terraform policy scanner with deterministic reports, a constrained MCP surface, and human-approved remediation.

InfraGuard checks source manifests, rendered Helm charts, live Kubernetes objects, and Terraform plan JSON. It combines strict Kubernetes schemas, Rego policies, and Python checks for inventory-wide relationships and destructive changes. Findings have stable identities and can gate CI or be exported as JSON, Markdown, terminal tables, and Prometheus metrics.

The project deliberately treats AI as an untrusted proposer. MCP operations are read-only, secrets are removed at collection boundaries, and a remediation cannot mutate Kubernetes until it passes technical gates and a person approves the exact resource in an interactive terminal.

Capabilities

Related MCP server: Claude Ops Investigator

Real output

These captures are regenerated from the committed fixtures and runtime tool registry with make screenshots; they are not hand-edited mockups.

Offline Kubernetes + Terraform scan

Markdown evidence report

Architecture

flowchart LR
  subgraph Inputs[Read-only inputs]
    K[Kubernetes API] --> KC[KubernetesLiveCollector]
    Y[YAML / Helm] --> MC[ManifestCollector]
    T[Terraform plan JSON] --> TC[TerraformPlanCollector]
  end

  KC --> N[Immutable normalized resources]
  MC --> N
  TC --> N

  N --> S[kubeconform schema]
  N --> P[Native + Rego policy]
  N --> X[Cross-resource / plan-risk checks]

  S --> E[Engine: dedupe · sort · summarize]
  P --> E
  X --> E

  E --> R[JSON · Markdown · terminal]
  E --> M[Prometheus metrics]
  E --> G[CI policy gate]
  E --> API[Read-only MCP]

  API --> AI[AI client]
  AI --> RP[Remediation proposal]
  RP --> V[Schema → policy delta → server dry-run]
  V --> H{Interactive human approval}
  H -->|exact resource name| A[Server-side apply]
  V --> L[(Append-only audit log)]
  H --> L
  A --> L

More detail: architecture, MCP threat model, and remediation guardrails.

Five-minute offline demo

The offline path needs Python 3.11/3.12 and Make; it does not need Docker, a cluster, cloud credentials, or Terraform execution.

git clone https://github.com/hfmohammed/infraguard.git
cd infraguard

python3.12 -m venv .venv
.venv/bin/pip install -e '.[dev]'

.venv/bin/infraguard validate \
  samples/manifests/noncompliant \
  --offline \
  --plan-json samples/terraform/plan-fixtures/noncompliant.plan.fixture.json \
  --fail-on NONE \
  --format table \
  --format json \
  --format markdown \
  --metrics-file reports/metrics.prom

Expected result: six normalized resources, 20 deliberately seeded findings, and reports under reports/. Both world-open security groups expose SSH, so TF-AWS-NET-001 appears twice. --fail-on NONE keeps the demonstration command successful while still reporting every violation.

Compare the clean target:

.venv/bin/infraguard validate samples/manifests/compliant --offline --fail-on LOW

Full local platform demo

Prerequisites: Docker, Python 3.11/3.12, Make, curl, tar, and unzip.

make setup          # virtualenv + pinned tools in ./bin; no sudo
make cluster-up     # one control-plane and one worker
make deploy-samples # compliant and intentionally vulnerable namespaces
make scan           # terminal + JSON + Markdown + Prometheus
make test           # Python and Rego suites
make cluster-down

scripts/install-tools.sh detects Darwin/Linux and amd64/arm64, then installs the exact versions in tools.env locally. Nothing is written system-wide.

Policy catalog

Every catalog entry has severity, category, remediation guidance, engine ownership, and a seeded fixture. See the generated policy reference.

Normal scans run kubeconform, Conftest/Rego, the network inventory check, and the Terraform action analyzer. Missing binaries and tool failures stop the scan. --offline explicitly selects the native evaluator and omits external schema checks; it is useful for demonstrations and quick local feedback. --skip-schema on scan, or --policy-only on validate, retains Rego validation without kubeconform.

CLI

infraguard scan       # live cluster and/or Terraform plan
infraguard validate   # YAML, directories, Helm, and plan JSON
infraguard report     # re-render a saved JSON report
infraguard policies   # inspect or generate the policy catalog
infraguard mcp serve  # start the read-only MCP server
infraguard remediate  # propose, check, or interactively apply

Policy thresholds are CRITICAL, HIGH, MEDIUM, LOW, and NONE.

Run .venv/bin/infraguard --help for the complete command tree.

Read-only MCP server

The server registers exactly these six tools:

1. list_cluster_resources

2. get_resource

3. get_policy_findings

4. analyze_terraform_plan

5. validate_manifest

6. validate_patch

validate_patch performs validation only and always returns applied: false. Filesystem arguments must resolve under --allowed-root; YAML is capped at 256 KB and 50 documents; results are redacted. The Kubernetes capability wrapper exposes read/list operations and a dry-run-only patch path.

validate_manifest runs actual schema and policy checks. validate_patch also checks target identity, compares live and proposed findings, and requests a server-side dry-run. Every call writes a content hash and outcome to audit/mcp-calls.jsonl; arguments and returned manifests are not logged.

{
  "mcpServers": {
    "infraguard": {
      "command": "infraguard",
      "args": ["mcp", "serve", "--context", "kind-infraguard"]
    }
  }
}

Human-gated remediation

infraguard remediate propose \
  --report reports/scan-abc12345.json \
  --finding a91c03e7f2b4d611 \
  --out proposal.yaml \
  --context kind-infraguard

infraguard remediate check proposal.yaml --context kind-infraguard
infraguard remediate apply proposal.yaml --context kind-infraguard

check stops after server-side dry-run. apply reruns the gates, refuses noninteractive input, requires the exact resource name, and only then performs server-side apply. Each executed step is appended to audit/remediation.jsonl; the manifest itself is never logged, only its SHA-256.

The approval screen shows the target, context, rationale, gate outcomes, and checked diff before asking for input. Proposals containing redaction placeholders are rejected to avoid overwriting secret values. For the Helm-managed sample, run infraguard remediate check samples/remediation/good-patch.yaml --context kind-infraguard --take-ownership. The flag explicitly permits transferring conflicting field ownership; without it, a Helm conflict fails the dry-run. Real apply still requires interactive approval. The five files under bad-patches/ exercise identity, kind, schema, policy, and admission failures.

Metrics endpoint

infraguard scan --context kind-infraguard -n ig-compliant \
  --serve-metrics 9108 --metrics-file reports/metrics.prom
curl http://127.0.0.1:9108/metrics

The endpoint serves the completed scan until Ctrl-C; it does not rescan periodically. It binds to localhost unless --metrics-host is specified. Metrics include severity counts, source/kind inventory, scan phase durations, policy counts, completion time, and process-local MCP/remediation counters.

CI and verification

The GitHub Actions workflow separates concerns:

• lint: Ruff, formatting, strict mypy, forbidden-plan detection, and gitleaks;

• unit: Python 3.11/3.12 matrix with the 85% coverage gate;

• policy/IaC validation: Rego, Helm, kubeconform, Terraform formatting/validation, clean-target checks, and an asserted negative gate;

• integration: an ephemeral kind cluster, both Helm releases, live collection, and a compliant namespace gate.

Useful local commands:

make lint
make test
make validate
make screenshots
./scripts/check_no_plans.sh

Measured results are recorded in docs/METRICS.md. The verification guide maps requirements to executable checks and describes the manual approval exercise.

Security model

• Terraform samples are plan-only, use mock credentials, disable provider account checks, and contain no data sources.

• Plans, state, kubeconfigs, credentials, reports, audit logs, caches, and downloaded binaries are gitignored.

• A repository hook and CI check reject tracked Terraform plans/state.

• Kubernetes Secrets lose data and stringData; sensitive environment values are replaced before models, reports, or MCP output are built.

• The recommended Kubernetes role grants get, list, and watch but cannot read Secrets.

• No subprocess uses a shell; YAML uses safe loaders; MCP paths are canonicalized before access.

• Remediation is the only mutation path, and it cannot bypass interactive approval.

See security and guardrail details.

Repository map

src/infraguard/       collectors, validators, engine, reports, MCP, remediation
policies/             metadata plus Kubernetes and Terraform Rego
samples/              Helm, raw YAML, sanitized plans, Terraform, remediation
tests/                unit, integration, policy matrix, golden expectations
cluster/              kind topology and least-privilege Kubernetes RBAC
dashboards/           optional Prometheus/Grafana development stack
docs/                 architecture, policy, MCP, guardrail, and metric evidence

Roadmap

• SARIF output and GitHub code-scanning upload

• Kustomize rendering

• Optional AWS/GCP read-only inventory collectors with mocked test suites

• Fully provisioned Grafana dashboards

• Optional local Ollama proposer while preserving the same guardrail pipeline

License

MIT