GRC Control Engineering Lab

A Python-first portfolio lab that turns written controls into preventive policy, detective automation, tamper-evident evidence, findings, remediation, and verified closure.

This is not a compliance dashboard. It is an executable reference implementation showing how a GRC engineer can work with cloud and platform teams to make controls testable.

What this proves

• Prevent bad infrastructure in pull requests with Open Policy Agent (Rego).
• Implement secure and intentionally insecure examples with Terraform.
• Detect runtime drift through AWS and GitHub API collectors.
• Evaluate evidence with explicit PASS, FAIL, UNKNOWN, and ERROR semantics.
• Preserve evidence integrity with canonical JSON and SHA-256 digests.
• Manage findings with owners, severity, SLA, and evidence-gated closure.
• Translate technical results into an OSCAL 1.2.2 assessment-results artifact.
• Validate Python, Rego, and Terraform in GitHub Actions.

Control catalog

ID	Objective	Preventive layer	Detective source
AWS-S3-001	Encrypted, private, versioned, owned production storage	Rego + Terraform	AWS S3 APIs
AWS-IAM-002	Least-privilege human identities without stale keys	Rego + Terraform	AWS IAM APIs
AWS-LOG-003	Multi-region, validated, encrypted activity logging	Rego + Terraform	AWS CloudTrail APIs
SDLC-CHANGE-001	Reviewed infrastructure changes with passing checks	Rego + Terraform	GitHub REST API

Framework mappings in each control.yaml are illustrative crosswalks, not claims of compliance. Applicability still depends on scope, system design, and audit criteria.

Architecture

flowchart LR
    A["Terraform change"] --> B["Rego preventive test"]
    B -->|deny| C["PR blocked"]
    B -->|allow| D["Deploy"]
    D --> E["AWS / GitHub API collector"]
    E --> F["Python evaluator"]
    F --> G["Hashed JSON evidence"]
    G --> H["Finding + owner + SLA"]
    H --> I["Terraform remediation"]
    I --> E
    G --> J["OSCAL assessment-results bridge"]

Loading

The key control-engineering decision is that remediation does not close a finding. Only fresh, post-remediation PASS evidence for the same control and resource can close it.

Rebuild in five minutes

Prerequisites: Git, Python 3.11 or newer, and optionally OPA and Terraform for the full suite.

Windows PowerShell

git clone https://github.com/envokeME/grc-control-engineering-lab.git
Set-Location grc-control-engineering-lab
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pytest
python -m grc_lab demo --out artifacts/local-run

macOS or Linux

git clone https://github.com/envokeME/grc-control-engineering-lab.git
cd grc-control-engineering-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
python -m pytest
python -m grc_lab demo --out artifacts/local-run

The demo uses committed fixtures and no cloud credentials. It produces ten artifacts showing the full S3 lifecycle:

baseline PASS -> preventive block -> runtime FAIL -> finding OPEN
-> issue adapters -> OSCAL export -> risk handoff
-> remediation applied -> recovery PASS -> CLOSED_VERIFIED

Inspect artifacts/local-run/03-drift-evidence.json and artifacts/local-run/10-finding-closed.json first. A reviewed synthetic run is committed at artifacts/example-run/ for readers who do not execute the code.

Run an individual control

# A passing fixture should return exit code 0.
python -m grc_lab evaluate --control AWS-S3-001 --state passing --expect PASS

# A known failing fixture also returns 0 when FAIL is the expected result.
python -m grc_lab evaluate --control AWS-S3-001 --state failing --expect FAIL

# List the catalog.
python -m grc_lab list

The --expect argument makes the CLI useful in CI: a status mismatch returns exit code 2.

Collect live evidence

Install the optional dependencies:

python -m pip install -e '.[live]'

Then use your existing AWS credential chain or a short-lived role:

python -m grc_lab collect \
  --control AWS-S3-001 \
  --resource customer-data-prod \
  --region us-east-1 \
  --out artifacts/live/s3.json

python -m grc_lab collect \
  --control AWS-IAM-002 \
  --resource alice \
  --out artifacts/live/iam.json

python -m grc_lab collect \
  --control AWS-LOG-003 \
  --resource org-primary \
  --region us-east-1 \
  --out artifacts/live/cloudtrail.json

For GitHub, use a fine-grained read token in the process environment:

export GITHUB_TOKEN='...'
python -m grc_lab collect \
  --control SDLC-CHANGE-001 \
  --resource owner/repository \
  --branch main \
  --pull-request 42 \
  --out artifacts/live/change-control.json

Do not commit live evidence without reviewing it for account identifiers, repository metadata, or other sensitive information. The committed examples use synthetic names.

grc_lab.evidence_store.S3EvidenceStore is an injected-client adapter for writing the same JSON to encrypted S3 while preserving its SHA-256 digest as object metadata. Production use should add Object Lock, scoped write roles, trusted timestamps, signing, lifecycle policy, and access logging.

Failure semantics

Status	Meaning	Finding behavior
PASS	Fresh evidence and every assertion satisfied	May close a matching finding after remediation
FAIL	Fresh evidence proves one or more assertions failed	Opens or updates a finding
UNKNOWN	Evidence is stale or a required value is missing	Investigate collection; do not claim effectiveness
ERROR	Collector or API operation failed	Fix collection; do not convert an outage into a control failure

This distinction avoids a common GRC automation error: treating missing telemetry as proof that a control passed or failed.

Repository map

controls/<CONTROL-ID>/
  control.yaml              control objective, risk, ownership, evidence, mapping
  examples/                 passing and failing API-shaped snapshots
  prevent/                  Rego policy and tests
  implement/                compliant and noncompliant Terraform
  remediate/                reviewed remediation and operator notes
src/grc_lab/
  collectors/               read-only AWS and GitHub API adapters
  evaluators/               deterministic control assertions
  evidence.py               status precedence and SHA-256 integrity
  findings.py               open and evidence-gated close transitions
  adapters.py               GitHub Issue and ServiceNow-compatible payloads
  evidence_store.py         encrypted S3 evidence writer
  oscal.py                  assessment-results translation
  risk.py                   technical-to-business risk handoff
tests/                      unit, integration-style, lifecycle, and CLI tests
docs/                       rebuild, hardening, and validation documentation

Full validation

ruff check src tests
pytest --cov=grc_lab --cov-report=term-missing --cov-fail-under=85
find controls -type d -name prevent -exec opa test {} -v \;
terraform fmt -check -recursive controls

GitHub Actions also initializes and validates every compliant, noncompliant, and remediation Terraform directory.

The exact local validation evidence is recorded in docs/validation-report.md.

Deliberate limitations

This is a portfolio lab, not a production control platform. The default demo uses local JSON artifacts, evaluates one resource at a time, and does not provision live cloud resources. Production adoption would add federated identity, scoped collection roles, centralized scheduling, immutable signed evidence, durable finding state, schema validation, alerting, pagination beyond the first 100 GitHub records, and organization-specific control mappings.

Primary references

• AWS S3 API reference
• AWS IAM security best practices
• AWS CloudTrail API reference
• GitHub REST API for protected branches
• OPA Terraform policy tutorial
• NIST OSCAL assessment results model

License

MIT