Skip to content

The Audit Recorder

The SHBOM (Structural Health Bill of Materials)

The Audit Recorder (audit_recorder.py) is the final compliance stage of the GitGalaxy pipeline. It extracts the raw telemetry from live RAM and compiles it into a verbose, human-readable forensic JSON manifest. Designed for strict enterprise compliance, advanced supply chain tracking, and deep-dive debugging, it guarantees absolute traceability for every file evaluated.

Note: While the SHBOM is not yet an industry standard, it serves as a technically more detailed version of a traditional Software Bill of Materials (SBOM). Rather than merely listing that a file exists, the SHBOM provides granular, mathematical proof about the actual quality, security, and structural health of the code inside those promised files.

Key Architectural Features

  • The Traceability Anchor: Imprints the exact Git footprint (Branch, SHA-1 Hash, Remote URL, Last Commit Date) and engine timestamp into the header. This ensures the audit is permanently and cryptographically tied to the state of the repository at the exact moment of the scan.
  • Hierarchical Constellation Mapping: Rather than dumping a flat list of files, the Auditor intelligently sorts the "Visible Matter" by Constellation (folder) and ranks them descending by total structural mass. It also generates a folder-level Architectural Fingerprint, showing the exact breakdown of ML Archetypes per directory.
  • Advanced Security Triage: To prevent alert fatigue, the engine explicitly decouples active malicious threats from general structural risks. It evaluates raw threat signatures, incorporates the XGBoost AI Threat Confidence scores, and assigns a strict repository status: AI_CONFIRMED_MALWARE_DETECTED, CRITICAL_THREATS_DETECTED (Rule-Based), ELEVATED_SURFACE_RISK, or SECURE_NO_MALWARE_DETECTED.
  • Network & AppSec Posture: In the modern protocol, the Audit Recorder injects the full N-dimensional network graph topology (PageRank, Blast Radius) alongside any detected Autonomous AI AppSec Vulnerabilities (like Agentic RCE funnels) directly into the file's forensic profile.
  • The Faction Interceptor: Translates raw numerical data into human context. For example, it intercepts the "Civil War Exposure" (Tabs vs. Spaces) and translates the 0-100 score into readable cultural tags like "Team Tabs," "Team Spaces," or "Neutral / Deadlocked."
  • Dark Matter Preservation: Files rejected during the pipeline are never silently deleted. They are logged in the Dark Matter archive with explicit diagnostic reasons (e.g., "Structural Saturation," "Ecosystem Orphan," "Unsupported Extension") and their exact physical size, so engineers can audit the pipeline's blind spots.

The Blank Audit Skeleton (galaxy_audit.json)

Here is the structural blueprint of the final output. This template exactly matches the data hierarchy GitGalaxy produces in its V6.3+ protocol:

```json { "Audit Protocol": "GitGalaxy v6.3.2-Audit", "1. Forensic Trail (Traceability)": { "Analysis Context": { "Engine Identity": "", "Target Root Name": "", "Absolute Project Path": "", "Analysis ISO Timestamp": "", "Total Scan Duration": "" }, "Source Control Footprint (Immutable Anchor)": { "Active Branch": "", "Commit Hash (SHA-1)": "", "Remote Origin URL": "", "Last Code Integration Date": "" } }, "2. Global Synthesis Summary": { "summary": {}, "Repository Macro-Architecture Patterns": {}, "singularity": {}, "health": {}, "composition": {}, "Global Architectural Fingerprint": {}, "ai_topology": {}, "constellations": {} }, "3. Forensic Security & Vulnerability Audit": { "Audit Status": "[AI_CONFIRMED_MALWARE_DETECTED | CRITICAL_THREATS_DETECTED | ELEVATED_SURFACE_RISK | SECURE]", "AI Threat Intelligence (XGBoost)": { "Infected Files Detected": 0, "Critical Targets": [] }, "Scope": {}, "Exposed Secrets & Credentials (Quarantined Files)": [], "Vulnerability Exposures (Rule-Based Threshold Breaches)": {}, "Raw Threat Signature Hits (Total Repository Occurrences)": {} }, "4. High-Value Forensic Report": { "exposures": { "cognitive_load": { "highest": [], "lowest": [] }, "safety_score": { "highest": [], "lowest": [] }, "tech_debt": { "highest": [], "lowest": [] } // ... iterates through all active risk exposures }, "file_impact": { "highest": [], "lowest": [] }, "function_impact": { "highest": [], "lowest": [] }, "systemic_bottlenecks": { "highest": [], "lowest": [] }, "cumulative_risk": { "highest": [], "lowest": [] } }, "5. Dark Matter (Excluded Artifacts)": [ { "Path": "", "Forensic Category": "Dark Matter (Excluded Artifact)", "Diagnostic Reason": "", "Size": "", "Identity Confidence": "", "Discovery Proof": "" } ], "6. Visible Matter (Scanned Artifacts)": { "[Constellation/Folder Name]": { "Constellation Mass": 0.0, "File Count": 0, "Architectural Fingerprint (Archetypes)": {}, "Average Risk Exposures": {}, "Stars / Files": { "[File Path]": { "1. Identity": {}, "2. Spatial Coordinates": {}, "3. Architectural Profile": {}, "4. Risk Exposures": {}, "5. Function Analysis (Satellites)": [], "6. Contextual Mitigations & Amplifications": {}, "7. Structural DNA (Net Mitigated Signals)": {}, // Evaluated structurally as heuristic signatures "8. Dependency Network": { "Direct Upstream (Fragility)": 0, "Direct Downstream (Blast Radius)": 0, "Total Upstream (Absolute Fragility)": 0, "Total Downstream (Absolute Blast Radius)": 0 }, "9. Extracted Dependencies": [] } } } } }



🌌 Powered by the blAST Engine

This documentation is part of the GitGalaxy Ecosystem, an AST-free, LLM-free heuristic knowledge graph engine.