Inspiration
Most software teams treat security and compliance as an afterthought — a checklist item at the end of a sprint or a blocker discovered at code review. By then, governance debt has already been baked into the design.
NIST CSF 2.0 introduced a GOVERN function precisely to solve this: governance should be a pre-condition that informs all other security functions, not a follow-up activity. We wanted to bring that same concept into the GitLab software development lifecycle (SDLC) — so that before a developer writes a single line of code, the project's governance posture is already defined, checked, and documented.
Governance Guardian was built to answer one question: what if your governance layer ran before planning, not after?
What It Does
Governance Guardian is an agentic tool that reads a plain-English project description and automatically:
Checks the project against company governance policy — using a configurable base.json policy file that private-sector organizations can customize to their own rules.
Detects pre-planning violations — surfacing errors (🔴), warnings (🟡), and informational flags (🔵) before a repository is even scaffolded.
Generates four governance artifacts in one command:
output/checklist.md — a pre-planning checklist mapped to NIST CSF 2.0, OWASP SAMM, OpenSSF Baseline Level 1, SLSA, and ISO 27001 A.5.8
output/risk_summary.md — a risk summary with a framework control matrix
output/.gitlab-ci.template.yml — a CI/CD pipeline template with SAST, SCA, secret detection, IaC scanning, provenance, and a conventional commit linter pre-wired
output/policy_violations.md — a human-readable violation report referencing GitLab's own engineering handbook rules
Trigger model: The agent runs on-demand (CLI) or can be integrated as a CI/CD pre-planning gate, blocking pipeline progression until governance outputs are reviewed and committed.
Example scenario: A developer starts a new SaaS service that handles PII. They run:
bash python3 run_agent.py --input input.json Within seconds, the agent flags that high-criticality projects require MFA enforcement and a documented RPO/RTO — violations caught before planning begins, not during an audit.
How We Built It
Agent Architecture
The core engine (run_agent.py) is a Python-based governance agent with three stages:
Profile resolution — reads input.json (project metadata: sector, criticality, data types, integrations) and selects the appropriate governance profile from profiles/base.json
Policy evaluation — runs the project description against the policy file, scoring it against controls derived from NIST CSF 2.0's GOVERN function, OWASP SAMM's Governance stream, OpenSSF OSPS Baseline Level 1, SLSA L1/L2, and ISO 27001 A.5.8
Artifact generation — writes all four output files, including the CI template with jobs pre-configured for: gitleaks (secret detection), semgrep (SAST), pip-audit (SCA), checkov (IaC), and SLSA provenance
Governance Framework Mapping
Framework What Governance Guardian enforces NIST CSF 2.0 — GOVERN — Pre-planning policy gate; context for all downstream SDLC phases NIST SSDF SP 800-218 PO.1 — Security requirements defined before coding starts OWASP SAMM — Governance Strategy, policy, and compliance evaluated at project initiation OpenSSF OSPS Baseline L1 MFA enforcement, least-privilege default, branch protection rules SLSA L1/L2 Commit signing + provenance job in generated CI template ISO 27001 A.5.8 Security required across all project phases from initiation GitLab Engineering Handbook Commit message conventions, MR description requirements, approval policies Policy-as-Code Design
The profiles/base.json is intentionally designed as a company policy file — any private-sector organization can swap in their own controls without touching the agent logic. This mirrors how real enterprise governance tools (Cycode, Blue Flag, etc.) operate: configurable policy, portable engine.
Challenges We Faced
Defining "pre-planning" governance in code — most governance frameworks describe controls at a conceptual level. Translating NIST CSF 2.0 GOVERN and OWASP SAMM into discrete, checkable policy rules required careful mapping and several iterations.
Making violations actionable, not just flagged — it's easy to output a list of failures. Making each violation link back to a specific framework control, explain why it matters, and suggest a concrete fix required building a structured violation schema.
CI template generation that's actually usable — generating a GitLab CI template that developers would genuinely adopt (not just demo) meant choosing real, open-source tools (gitleaks, semgrep, pip-audit, checkov) and writing the jobs with plain-English comments so developers understand the rule, not just the checkbox.
What We Learned
NIST CSF 2.0's GOVERN function is the architectural precedent that validates this entire approach — pre-planning governance is not a novel idea, it's the direction the field is moving.
GitLab's own engineering handbook is a rich, publicly citable source of real company rules that can be machine-checked — making it an ideal "reference policy" for a governance tool targeting GitLab-native teams.
The most important feature of a governance tool is not the output — it's the timing. Running governance checks at day zero, before any code exists, is what prevents security debt from compounding across the SDLC.
What's Next
Real-time GitLab Flow integration — trigger the governance check automatically on issue creation or MR open events via GitLab Duo Agent Platform, posting violations as MR comments before review begins
Governance drift detection — continuously re-evaluate projects as they evolve, flagging when branch protections are weakened or excess privileges are granted
Jurisdiction-aware profiles — extend base.json profiles to encode sector-specific requirements (NIS2, CMMC, SOC 2) so the agent adapts its controls based on regulatory context
LLM-powered violation explanations — use Claude to generate plain-language explanations of each violation and auto-suggest remediation steps, making the tool accessible to non-security engineers