Design & Architecture¶

G.U.A.R.D. operates as a verification gate that acts on a version control repository. By linking abstract norms to concrete file paths and code symbols (anchors), it ensures that compliance requirements remain traceable and actively monitored.

System Architecture¶

The core verification workflow consists of three primary stages:

flowchart TD
    Registry[Compliance Registry YAML] --> Parser[Registry Parser]
    Parser --> Validator[Anchor Symbol Validator]
    Git[Git Diff Engine] --> HunkFilter[Hunk Anchor Filter]

    Source[Source Code Repository] --> Validator
    Source --> Git

    Validator --> Evaluator[Audit Gate Evaluator]
    HunkFilter --> Evaluator

    Evaluator --> Report[JSON/JUNIT Compliance Report]

Registry Parser: Loads the configuration YAML, validating the defined categories, norms, and code references.
Anchor Symbol Validator: Inspects the current state of files in the workspace to verify that each referenced symbol (anchor) actually exists. If a symbol is missing, the gate triggers a failure.
Hunk Anchor Filter (Git Engine): Compares the repository's HEAD against a base commit (baseSha). If a registered file was modified, it extracts the raw git diff hunks and checks if the modification overlaps with the specific lines containing the anchor symbol.

Registry Schema Reference¶

The compliance registry is defined in a YAML file (usually compliance-registry.yaml). It uses the following structure:

categories:
  - id: ISO-27001-A.5
    name: Information security policies
    norms:
      - id: ISM-001
        title: Protect clinical data rendering fixtures from accidental drift.
        # Single reference configuration
        code_ref:
          file: mock-epr/src/main.ts
          anchor: patientRecord
          kind: variable

      - id: ISM-002
        title: Keep the patient summary generated from a typed source of truth.
        # Multiple references configuration
        code_refs:
          - file: mock-epr-python/main.py
            anchor: renderRecordCard
            kind: function
          - file: mock-epr-python/extra_components.py
            anchor: renderRecordCardV2
            kind: function

Schema Parameters¶

Property	Type	Description
`categories`	Array	A top-level group representing a regulatory standard (e.g. ISO 27001 or NEN 7510).
`categories[].id`	String	Unique identifier of the regulatory standard section.
`categories[].name`	String	Human-readable name of the regulatory section.
`categories[].norms`	Array	List of specific norms within the category.
`norms[].id`	String	Unique identifier of the norm.
`norms[].title`	String	Statement of the compliance requirement.
`norms[].code_ref`	Object	(Optional) A single code reference object matching the norm.
`norms[].code_refs`	Array	(Optional) An array of code reference objects matching the norm.

Code Reference Object¶

Each code reference defines exactly where the compliance control is implemented:

file: The repository-relative path to the source file (e.g. src/auth.ts).
anchor: The name of the code symbol representing the control (e.g. hashPassword).
kind: The type of the symbol. Valid types include function, variable, class, method, etc. (used by the parser to search for boundaries).

Audit Memory & Cryptographic Receipt Schema¶

G.U.A.R.D. generates a structured, tamper-evident audit receipt JSON (guard-audit-receipt.json) that establishes an immutable record of regulatory evaluations, code changes, and stakeholder approvals.

Receipt JSON Structure¶

{
  "schemaVersion": "1.0.0",
  "auditId": "guard-1788858764637-a1b2c3d",
  "timestamp": "2026-09-08T10:00:00.000Z",
  "project": "Mock EPR Python",
  "repositoryRoot": "/repo",
  "headSha": "a1b2c3d4e5f6...",
  "baseSha": "HEAD~1",
  "branch": "main",
  "actor": {
    "name": "Jane Doe",
    "email": "jane@healthcare.org"
  },
  "approver": {
    "name": "Dr. Noor El-Amin",
    "environment": "compliance-approval",
    "approvedAt": "2026-09-08T10:15:00.000Z"
  },
  "summary": {
    "totalControls": 6,
    "unchanged": 5,
    "driftDetected": 1,
    "configErrors": 0,
    "complianceStatus": "DRIFT_PENDING_APPROVAL",
    "complianceRatePercent": 83
  },
  "frameworks": [
    {
      "id": "NEN-7510-8.2",
      "name": "Information security awareness and classification",
      "totalNorms": 2,
      "unchanged": 2,
      "drifted": 0,
      "errors": 0,
      "status": "COMPLIANT"
    }
  ],
  "findings": [ ... ],
  "integrity": {
    "algorithm": "SHA-256",
    "receiptHash": "55599cc5e71ca8a56d6eab41d167614bf8e128b27b011fa2da6a14ffa9dd1beb"
  }
}

Cryptographic Tamper-Evidence¶

The integrity.receiptHash is a deterministic SHA-256 checksum calculated over the canonical findings, metadata, commit identifiers, and timestamps. Any retroactive tampering with the audit receipt alters the hash and invalidates the record.

Standalone Interactive HTML Dashboard & History Ledger¶

For management and compliance officers, G.U.A.R.D. compiles audits into a self-contained, interactive HTML dashboard (guard-audit-dashboard.html):

Executive Posture Banner: Immediate visual indicator of compliance integrity (Compliant / Drift Pending Review / Config Error).
KPI Metrics: Overall compliance score percentage, total controls scanned, clean controls, and pending drift items.
Framework Breakdown Matrix: Per-standard (ISO 27001, NEN 7510) compliance progress bars and breakdown.
Diff & Evidence Explorer: Searchable and filterable table with filtered hunk diffs highlighting exact lines modified in anchored symbols.
Audit History & Governance Ledger: When a history directory (--history-dir) is configured, the dashboard includes a dedicated Audit History Ledger tab displaying past audits, lifetime drift occurrences, stakeholder sign-offs, and historical snapshot inspection.
Offline & Air-Gapped Ready: Generated as a single file with embedded styles, client-side filtering, and embedded JSON data—no external CDN dependencies required. Includes one-click "Download JSON Receipt" and print/PDF export.

Directory-Based Audit Ledger (`--history-dir`)¶

To maintain a continuous audit trail without depending on specific CI/CD platform artifact stores:

G.U.A.R.D. saves each execution as a uniquely named receipt file: <history-dir>/receipt-<timestamp>-<shortSha>.json.
On subsequent runs, G.U.A.R.D. loads and validates all receipts in <history-dir>, sorting them chronologically.
The dashboard aggregates the entire timeline, displaying trends, historical compliance rates, and past approver records.

.guard/receipts/
├── receipt-2026-09-01T09-00-00-000Z-f9b8c7d.json  # Initial release (100% Compliant)
├── receipt-2026-09-07T14-30-00-000Z-a4f91b2.json  # PR Drift (Approved by Dr. Noor)
└── receipt-2026-09-08T09-33-35-717Z-UNKNOWN.json  # Current Audit (100% Compliant)

Engine Optimization Features¶

G.U.A.R.D. includes performance optimizations to support execution on large codebases inside containerized environments:

1. Batch Diffing¶

Instead of invoking git diff sequentially for every changed file in the registry, G.U.A.R.D. maps out all modified files that match the registry, then queries Git in a single batch command:

git diff <base-sha> -- <file1> <file2> <file3> ...

This reduces external process invocation overhead from \(O(N)\) (where \(N\) is the number of references) to \(O(1)\).

2. Line Anchor Verification and Caching (`FileCache`)¶

To verify if an anchor exists in a file, G.U.A.R.D. parses/scans the file content. When multiple norms reference the same file, the content is stored in a lightweight in-memory cache (FileCache). This avoids repeated filesystem disk read operations.

3. Anchor Hunk Extraction¶

When a file is modified, the compiler maps the changed line numbers in the git diff hunk against the location of the anchor symbol in the target file. If a change occurs outside the scope of the anchor's definition, the status is reported as unchanged, ensuring developers are not flagged for unrelated changes.