Skip to content

v1.4.0 — Governance Provenance Chain

Choose a tag to compare

View all tags
@greenarmor greenarmor released this 18 Jun 09:45
· 32 commits to master since this release
v1.4.0
5087aae

Release v1.4.0 (Minor)

This is a minor release. It adds a complete Governance Provenance Chain system — a linked approval record connecting System → Risk Assessment → Policy → Approval → Evidence → Review Cycle → Data Inventory → Compliance Links. The system is system-type-agnostic (works for AI systems, applications, APIs, infrastructure, and more). No breaking changes. Existing projects continue to work unchanged.

Previous release: v1.3.0
Release date: 2026-06-11

Highlights

Governance Provenance Chain

A new framework-wide system that solves traceability fragmentation. Rather than building a GRC platform, GESF creates a linked provenance record that references evidence wherever it lives (Jira, Confluence, ServiceNow, SharePoint, GRC platforms). The dashboard serves as a one-stop shop where auditors, examiners, and developers can see the full approval chain and download reports.

The core question it answers: "Who approved this system? Under which authority? When? Is it still valid? What evidence supports the decision?"

System Identity → Risk Assessment → Policy Basis → Approval Decision
                                                       ↓
    Review Cycle ← Evidence Chain ← Committee ← Data Inventory
                                                       ↓
                                            Compliance Links

Key Metrics

Metric Before (v1.3.0) After (v1.4.0)
MCP tools 31 43 (+12 governance)
Policy packs 26 27 (+governance)
CLI subcommands — +13 (governance)
Dashboard tabs 6 7 (+Governance)
Tests passing 432 438
GOVP controls 0 12 (GOVP-001–012)

What's New

1. Governance Provenance Records

Every governed system gets a single record that connects all dimensions of the approval chain:

  • System Identity — Name, type, version, description, risk level
  • Risk Assessment — Assessor, methodology, risk score, residual risk, identified risks, mitigations
  • Policy Basis — Policy ID, name, version, standard reference, applicable clauses
  • Approval Decision — Approver name/role/email, authority, decision (approved/rejected/conditional), validity period, conditions, rationale
  • Committee Approval — Committee name, meeting reference/date, attendees, decision summary
  • Evidence Chain — References to external systems (Jira, Confluence, ServiceNow, etc.) — referenced, not duplicated
  • Review Cycle — Frequency (quarterly/semi-annual/annual/biennial), next review date, review history
  • Data Inventory — Personal data categories, processing purposes, data subjects, cross-border transfers, retention period
  • Compliance Links — Frameworks, controls satisfied, control pack IDs

Records are stored in .ges/governance-records.json.

2. Verification Engine

verifyGovernanceRecord() checks 8 dimensions and returns a single defensible answer:

Overall: ✓ VALID
Approval Status: VALID
Expiry: 197 days remaining
Evidence Count: 1

Completeness Checklist:
  ✓ Approval Decision
  ✓ Risk Assessment
  ✓ Policy Basis
  ✓ Evidence Chain
  ✓ Review Cycle
  ✓ Data Inventory
  ✓ Compliance Links
  ✓ Currently Valid
  • Blocking issues — Missing approval, risk assessment, policy basis, or evidence
  • Warnings — Missing review cycle, data inventory, compliance links, or approval expiring within 30 days
  • Expiry monitoring — Tracks days until approval expires, flags expired approvals as blocking

3. CLI Commands (13 subcommands)

# Create and manage records
ges governance add --name "API Gateway" --type api --risk high
ges governance list
ges governance show <id>
ges governance delete <id>

# Enrich the provenance chain
ges governance risk-assessment <id> --assessor "John" --methodology "NIST RMF" --score "7/10" --residual "medium"
ges governance policy-basis <id> --policy-name "InfoSec Policy" --standard "ISO 27001" --pv "2.0"
ges governance approve <id> --approver "Jane" --role "CISO" --decision approved --valid-until "2027-01-01"
ges governance evidence <id> --title "DPIA Report" --source jira --reference "DPIA-001"
ges governance review-cycle <id> --frequency annual --next-review 2027-01-01
ges governance data-inventory <id> --categories "emails,IPs" --purposes "analytics"
ges governance committee <id> --committee "Ethics Board" --meeting-ref "MIN-2026-001"
ges governance compliance-links <id> --frameworks GDPR,OWASP

# Verify
ges governance verify <id>

All subcommands support interactive prompts and CLI flags. --actor and --actor-role flags on all commands provide attribution in the activity log.

4. MCP Tools (12 new, 31 → 43 total)

Original governance tools (6):

Tool Description
create_governance_record Create a new governance provenance record
approve_governance_record Record an approval decision
add_governance_evidence Add an evidence reference
list_governance_records List all records with summary
get_governance_record Get full provenance chain
verify_governance_record Verify provenance completeness

Enrichment tools (6):

Tool Description
set_governance_risk_assessment Link a risk assessment
set_governance_policy_basis Document the policy basis
set_governance_review_cycle Set up periodic review
set_governance_data_inventory Document data inventory
set_governance_committee Record committee approval
set_governance_compliance_links Map compliance frameworks

All action tools accept optional actor_name / actor_role for activity log attribution.

5. Audit Engine GOVP Detection

New GovernanceScanner activates automatically when the governance policy pack is installed (controls/governance/ directory exists). It validates 10 GOVP controls per record:

Rule Severity Trigger
GOVP-001 High Pack installed but no governance records
GOVP-002 Medium Missing risk assessment
GOVP-003 Medium Missing policy basis
GOVP-004 High Missing approval decision
GOVP-005 High No evidence references
GOVP-007 Low Missing review cycle
GOVP-008 Critical/Medium Expired or soon-expiring approval
GOVP-009 Low Missing data inventory
GOVP-010 Low Missing compliance links
GOVP-011 High Verification failed (blocking issues)

Zero findings are produced when the provenance chain is complete and valid.

6. Doctor Governance Health Checks

ges doctor now reports governance health:

[!] Governance records - 1 record(s), 0 approved, 1 with blocking issues
[!] Governance review cycles - 1 record(s) without review cycle

Checks: record count, approved count, blocking issues, expired approvals, missing review cycles.

7. Dashboard Governance Tab (7th tab)

  • Summary cards: total records, approved, pending, blocked
  • High-risk system alerts
  • Expandable provenance chain cards with full verification checklist
  • /api/governance and /api/governance/:id API routes
  • Report download endpoints: /api/report/compliance, /api/report/governance
  • Actor column in activity log table
  • Actor field in fix history detail cards
  • GOVP- prefix matching across all pack-matching logic

8. Actor Attribution

Optional actor_name and actor_role fields added to:

  • ActivityLogEntry type — displayed in dashboard Activity Log table
  • FixHistoryEntry type — displayed in dashboard Fix History detail cards
  • All governance CLI subcommands via --actor / --actor-role flags
  • All governance MCP action tools via actor_name / actor_role params

Fully backward compatible — existing data without actor fields works unchanged.

Governance Policy Pack (12 Controls)

New pack governance with control IDs GOVP-001 through GOVP-012:

Control Title
GOVP-001 System Identity & Registration
GOVP-002 Risk Assessment Documentation
GOVP-003 Policy Basis & Regulatory Reference
GOVP-004 Approval Decision Recording
GOVP-005 Evidence Chain References
GOVP-006 Committee Approval (when required)
GOVP-007 Review Cycle Definition
GOVP-008 Approval Validity & Expiry Monitoring
GOVP-009 Data Inventory Documentation
GOVP-010 Compliance Framework Mapping
GOVP-011 Provenance Verification
GOVP-012 Dashboard Auditability

Applicable to all 13 project types. Control ID prefix GOVP- avoids collision with the existing government pack's GOV- prefix.

Install with:

ges policy install governance

Full Provenance Chain Workflow

# 1. Initialize project
ges init --name "MyApp" --type saas --frameworks GDPR,OWASP
ges policy install governance

# 2. Create governance record
ges governance add --name "Payment API" --type api --risk high

# 3. Enrich all dimensions
ges governance risk-assessment <id> --assessor "John Doe" --methodology "NIST RMF" --score "7/10" --residual "medium"
ges governance policy-basis <id> --policy-name "InfoSec Policy" --standard "ISO 27001" --pv "2.0"
ges governance approve <id> --approver "Jane Smith" --role "CISO" --decision approved --authority "Board" --valid-until "2027-01-01"
ges governance evidence <id> --title "DPIA Report" --source jira --reference "DPIA-2026-001"
ges governance review-cycle <id> --frequency annual --next-review 2027-01-01
ges governance data-inventory <id> --categories "emails,IPs,payment-data" --purposes "analytics,processing" --retention "2 years"
ges governance compliance-links <id> --frameworks GDPR,OWASP --controls GDPR-ART32-001

# 4. Verify
ges governance verify <id>
# → ✓ VALID — all 8 dimensions green

# 5. Audit
ges audit
# → 0 governance findings (chain complete)

# 6. Health check
ges doctor
# → [✓] Governance records - 1 record(s), 1 approved, 0 with blocking issues

Architecture

Evidence Referenced, Not Duplicated

EvidenceRef stores a reference to the source system (Jira ticket ID, Confluence URL, ServiceNow ticket) — never the content itself. This maintains a single source of truth while providing a unified governance view.

interface EvidenceRef {
  id: string;
  type: "document" | "ticket" | "meeting-record" | "report" | ...;
  title: string;
  source_system: "jira" | "confluence" | "servicenow" | "sharepoint" | "grc-platform" | ...;
  reference: string;        // ticket ID, URL, document name
  location_description: string;
  added_by: string;
  added_at: string;
}

Single Record, All Dimensions

One GovernanceRecord connects system identity, risk assessment, policy basis, approval, committee, evidence chain, review cycle, data inventory, and compliance links. Stored as a single JSON file (.ges/governance-records.json).

System-Type-Agnostic

The governance pack applies to all 13 project types. System types include: ai-system, application, data-process, api, model, infrastructure, third-party-service.

Files Changed

File Change
packages/core/src/types/index.ts 16 governance interfaces + actor fields on ActivityLogEntry/FixHistoryEntry
packages/core/src/governance/index.ts New — Storage module: create/add/update/find/delete/verify + 6 enrichment functions
packages/core/src/activity-log/index.ts Actor params on createActivityLogEntry/recordActivity
packages/core/src/fix-history/index.ts Actor params on createFixHistoryEntry
packages/core/src/index.ts Export governance module
packages/policy-engine/src/packs/governance.ts New — 12 GOVP controls, all 13 project types
packages/policy-engine/src/index.ts Register governance pack
packages/policy-engine/src/index.test.ts Pack count assertion (26 → 27)
packages/cli/src/commands/governance.ts New — 13 subcommands with actor flags
packages/cli/src/cli.ts Register governance command
packages/cli/src/commands/doctor.ts Governance health checks
packages/mcp-server/src/server.ts 12 governance tools + actor params (43 total)
packages/mcp-server/src/server.test.ts Tool count assertion (31 → 43)
packages/audit-engine/src/scanners/governance-scanner.ts New — GOVP control validation
packages/audit-engine/src/scanners/governance-scanner.test.ts New — 5 test cases
packages/audit-engine/src/index.ts Register GovernanceScanner
packages/web-dashboard/src/index.ts Governance data collection, API routes, report endpoints
packages/web-dashboard/src/template.ts 7th tab, provenance chain UI, actor columns, GOVP matching
packages/web-dashboard/package.json Added report-generator dependency
docs/governance/architecture.md New — Full architecture documentation

Bug Fixes

  • --version flag conflict — ges governance policy-basis had a --version option that conflicted with commander.js's built-in global --version flag. Renamed to --pv.
  • Missing CLI options — ges governance approve was missing --email, --valid-from, --rationale options. All added.

Test Results

Packages:    16 buildable, all clean
Tests:        438 passing (was 432)
New tests:    5 governance scanner tests + 6 MCP governance tool tests
GOVP controls: 12 (GOVP-001–012)

Documentation

  • docs/governance/architecture.md — Full architecture: data model, verification logic, auditor workflow, API endpoints

Upgrade Guide

This release is fully backward compatible. No migration steps required.

To start using governance provenance chains:

# Install the governance pack
ges policy install governance

# Create your first governance record
ges governance add --name "My System" --type application --risk medium
Assets 2
Loading