Control Assurance Agent

Reference implementation / Python 3.10+ / offline / v0.1

Controls should be evaluated against evidence, not presumed from documentation.

Security policies declare how systems ought to behave. Configuration, identity state, logs, and operational telemetry reveal how they actually behave. The distance between the two is an assurance problem.

This reference prototype turns the existing control-state checking idea into a bounded agent workflow. It can inspect an input snapshot, choose a permitted evidence lookup when information is missing, reevaluate the result, compare two structured standards snapshots, and produce a review queue. Every tool action is recorded.

Scope matters: the demonstration runs entirely on fictional JSON fixtures. It does not connect to cloud accounts, poll NIST, use an LLM, edit security configurations, or declare an organization compliant.

Architecture

control definitions          system-state snapshot
         |                            |
         +--------------+-------------+
                        |
                        v
                evaluate controls
                        |
                  missing data?
                        |
                bounded tool lookup
                        |
                        v
                 reevaluate state
                        |
standards v1 + v2 --------+---- compare & map changes
                        |
                        v
              findings + tool trace
                        |
                        v
                  human review

The agent is a deterministic, bounded orchestrator. It uses a tool-use loop for targeted evidence retrieval; the test outcomes remain deterministic and cannot be overridden by agent interpretation.

Reproducible example

The sample checks five controls against a fictional finance application. Two fail. One initially lacks evidence; the agent retrieves a permitted local backup-test record and reevaluates it. The catalog comparison identifies one modified and one added illustrative requirement.

Read the generated HTML report · Raw JSON output

The sample report is produced by running the included Python application. Seven unit tests cover core comparisons, unknown evidence, invalid types, bounded investigation, and catalog changes.

Source and execution

Explore the complete Python source and tests on GitHub. No API key or third-party package is required for the demonstration.

python -m assurance_agent --out out
python -m unittest discover -s tests -v

Run these commands from the cloned control-assurance-agent/ repository directory. Local files are read; reports are written only to the selected output directory.

Engineering decisions

Deterministic evaluations. Boolean and numeric control tests produce PASS, FAIL, UNKNOWN, or ERROR; an agent cannot simply declare a control healthy.
Bounded tool access. Evidence lookups are read-only, use an explicit local source, and are limited by a configurable budget.
Traceable results. The output identifies evidence sources and records tool input/output digests. These are integrity aids, not signatures.
Standards diffing without false certainty. Structural edits are review candidates; a textual change is not necessarily a changed obligation.
Human authority. Suggested remediation and mapping changes never execute automatically.

Limitations and next steps

The current agent demonstrates orchestration, not enterprise deployment. It uses synthetic local fixtures, not authoritative NIST content or live security telemetry. The next engineering milestones are scoped read-only connectors, evidence freshness controls, verified NIST OSCAL ingestion, scheduling, and an evaluation set measuring false positives and missed control drift.

An LLM-powered investigator could eventually summarize conflicting evidence or propose mapping changes, but source-grounded explanation must remain separate from the deterministic control decision.

Related reading: The GRC Engineer is Already Here.