feat: add GitGalaxy composite action and modernize Spoke CI/CD docume…

README.md

@@ -85,6 +85,33 @@ Point the GalaxyScope at any local repository or ZIP archive. The engine runs en
 galaxyscope /path/to/your/local/repo
 ```
 
+### 3. GitHub Actions CI/CD Integration
+
+GitGalaxy can be integrated directly into your GitHub Actions pipeline for automated DevSecOps auditing, Zero-Trust SBOM generation, or Pre-Commit firewalls. 
+
+Create a file in your repository at `.github/workflows/gitgalaxy-scan.yml`:
+
+```yaml
+name: GitGalaxy Security Audit
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  gitgalaxy-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Run GitGalaxy Supply Chain Firewall
+        uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'supply-chain-firewall' # Options: galaxyscope, zero-trust-sbom, pii-leak-hunter, etc.
+          target: '.'
+```
+
 ---
 
 ### [GitGalaxy Core Analysis Engine](docs/wiki/01-project-overview.md)

action.yml

@@ -0,0 +1,61 @@
+name: 'GitGalaxy Scanner'
+description: 'High-velocity, AST-free DevSecOps scanner for zero-trust CI/CD, SBOMs, secret detection, and supply chain security.'
+branding:
+  icon: 'shield'
+  color: 'purple'
+
+inputs:
+  tool:
+    description: >
+      The GitGalaxy command to execute. 
+      Options: galaxyscope, blast, vault-sentinel, supply-chain-firewall, xray-inspector, zero-trust-sbom, pii-leak-hunter, terabyte-log-scanner, api-network-map.
+    required: true
+    default: 'galaxyscope'
+  target:
+    description: 'The directory or file path to scan.'
+    required: true
+    default: '.'
+  args:
+    description: 'Any additional CLI arguments to pass to the tool (e.g., --output json, --paranoid).'
+    required: false
+    default: ''
+  version:
+    description: 'The version of GitGalaxy to install from PyPI. Defaults to latest.'
+    required: false
+    default: 'latest'
+  full_precision:
+    description: 'Opt-in to install heavy physics engines (networkx, tiktoken, xgboost) for Blast Radius and ML Threat Inference.'
+    required: false
+    default: 'false'
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install GitGalaxy
+      shell: bash
+      run: |
+        if [ "${{ inputs.version }}" = "latest" ]; then
+          echo "Installing latest GitGalaxy from PyPI..."
+          pip install gitgalaxy
+        else
+          echo "Installing GitGalaxy version ${{ inputs.version }}..."
+          pip install gitgalaxy==${{ inputs.version }}
+        fi
+
+        if [ "${{ inputs.full_precision }}" = "true" ]; then
+          echo "Unlocking Full Precision Mode..."
+          pip install networkx tiktoken xgboost pandas numpy
+        else
+          echo "Running in ultra-fast Zero-Dependency Mode."
+        fi
+
+    - name: Execute GitGalaxy Tool
+      shell: bash
+      run: |
+        echo "Running: ${{ inputs.tool }} ${{ inputs.target }} ${{ inputs.args }}"
+        ${{ inputs.tool }} ${{ inputs.target }} ${{ inputs.args }}

gitgalaxy/README.md

@@ -5,11 +5,11 @@ Welcome to the internal source code for the **GitGalaxy blAST Engine**.
 This directory contains the core physics, routing, and mathematical heuristics that power the system. If you are a developer looking to contribute or understand the pipeline, here is the architectural map:
 
 ### 🗺️ The Developer Map
-* **`/core/`**: The optical routing layer. Contains the `aperture.py` and `prism.py` which break down source code into structural signals.
-* **`/physics/`**: The heuristics engine. Contains the `signal_processor.py` and `neural_auditor.py` which apply the GitGalaxy mathematics to score O(N) complexity, blast radius, and state flux.
-* **`/recorders/`**: The export layer. Translates the internal state maps into SQLite databases, AI-agent JSON tickets, and the WebGPU data payloads.
-* **`/security/`**: The zero-trust validation layer. 
-* **`/tools/`**: The enterprise "Spokes". Contains the specific scripts for Legacy Refraction, Supply Chain Firewalls, and AI Guardrails.
+* **`/core/`**: The optical routing layer. Contains `aperture.py` and `prism.py`, which break down source code into structural signals and separate executable logic from ghost mass (comments).
+* **`/physics/`**: The heuristics engine. Contains `signal_processor.py` and `neural_auditor.py`, which apply GitGalaxy mathematics to score O(N) complexity, blast radius, and state flux.
+* **`/recorders/`**: The export layer. Translates the internal state maps into SQLite databases, AI-agent JSON tickets, and WebGPU data payloads.
+* **`/security/`**: The zero-trust validation layer for detecting embedded malware and logic bombs.
+* **`/tools/`**: The enterprise "Spokes". Contains specific automation controllers for CI/CD pipelines, including Supply Chain Firewalls, PII Leak Hunters, and GitHub Actions integrations.
 
 ---
 
@@ -19,7 +19,9 @@ To demonstrate the engine's capability on complex, cross-language system archite
 
 Because NVDA relies heavily on bridging Python application logic with low-level C++ system hooks, it requires advanced dependency mapping. The blAST engine successfully parsed the mixed-language architecture, analyzing **236,754 lines of code** in just **5.59 seconds** (a velocity of 42,357 LOC/sec). 
 
-Crucially, during the import resolution phase, the Air-Gapped Dependency Radar successfully intercepted a structural naming collision (`fstream` vs `sstream`), proving the real-time typosquatting defenses are fully operational, this is likely a false positive, which could be prevented by adding these approved imports to the approve import list, so the system doesn't keep flagging them as unknown. 
+Crucially, during the import resolution phase, the Air-Gapped Dependency Radar successfully intercepted a structural naming collision (`fstream` vs `sstream`), proving the real-time typosquatting defenses are fully operational. 
+
+> **Note on False Positives:** Because `fstream` and `sstream` are both standard C++ libraries, this specific flag is a false positive. To prevent the engine from halting on trusted internal libraries, contributors can whitelist them by adding them to the `approved_imports.json` registry.
 
 ![NVDA Processing Demo](../docs/wiki/assets/nvda_processing.gif)
 
@@ -34,10 +36,23 @@ Crucially, during the import resolution phase, the Air-Gapped Dependency Radar s
 
 ---
 
-### Using the blAST Engine
-You do not need to run these internal files directly. To scan a repository, use the main entry point:
+### 🛠️ Local Development & Testing
+
+If you are modifying the internal physics or optical routing, it is highly recommended to install the package in editable mode so your CLI commands instantly reflect your local code changes.
+
+From the **root directory** of the repository, run:
+```bash
+pip install -e .
+```
+
+Once installed, you can trigger the main orchestrator (`galaxyscope.py`) globally from your terminal:
+```bash
+galaxyscope /path/to/test/repo --debug
+```
+
+Before submitting a Pull Request, ensure your changes do not skew the baseline risk equations by running the test suite:
 ```bash
-python3 galaxyscope.py /path/to/your/repo
+python3 -m unittest discover tests/
 ```
 
 ---

gitgalaxy/tools/README.md

@@ -1,74 +1,63 @@
-# GitGalaxy: Software Supply Chain Security & DevSecOps Automation
+# 🛠️ GitGalaxy Tools (The Spokes)
 
-[![Integration](https://img.shields.io/badge/Integration-CI%2FCD_Ready-00C957.svg)](#)
-[![Accuracy](https://img.shields.io/badge/Accuracy-Internal_File_Scanning-00BFFF.svg)](#)
-[![Defense](https://img.shields.io/badge/Defense-Zero__Trust-FF4500.svg)](#)
+Welcome to the GitGalaxy Tools directory. 
 
-Welcome to the **GitGalaxy Supply Chain Security Suite**.
+If `galaxyscope.py` is the core physics engine (the Hub), the tools in this directory are the "Spokes." These are specialized, standalone execution controllers that leverage GitGalaxy's AST-free, high-speed parsing capabilities to solve specific engineering and security challenges.
 
-Standard security scanners have a massive blind spot: they read your `package.json` or `requirements.txt` manifests and simply check those names against CVE databases. They never look inside the actual downloaded files. 
+Each sub-module is designed to be executed directly from the CLI or wired into CI/CD pipelines.
 
-Modern attackers (like the **XZ-Utils** or **Glassworm** campaigns) exploit this exact gap. They don't announce themselves in a manifest.
+## 📂 Tool Suites Directory
 
-GitGalaxy operates differently. We shift security entirely left by scanning the physical internals of every dependency file at extreme velocities (100k+ LOC/sec) before it enters your system. 
+### 🛡️ [Supply Chain Security](./supply_chain_security/README.md)
+Zero-trust DevSecOps tools designed for pre-commit hooks and CI/CD pipeline blocking.
+* **Supply Chain Firewall:** Scans `node_modules` and vendor directories for malicious typosquatting and unauthorized network I/O.
+* **Vault Sentinel:** Hyper-speed secrets and credential detection.
+* **Binary Anomaly Detector:** Triage engine for finding encrypted payloads and parasitic logic hidden in binary artifacts.
 
-### 🛡️ What We Block
-We provide highly effective, zero-trust defense against structural supply chain threats:
-* **Hidden Executables:** Steganography and XZ-Utils attack patterns.
-* **Malicious Typosquatting:** Unicode homoglyphs tricking developer imports.
-* **Encrypted Payloads:** Obfuscated XOR decryption loops.
-* **Hostile I/O:** Shadow imports establishing covert outbound connections.
-* **Anomalous Logic:** Network sockets hidden inside declarative CSS or JSON files.
+### 📜 [Compliance & Auditing](./compliance/README.md)
+Tools for generating forensic and legal records of software architecture.
+* **Zero-Trust SBOM Generator:** Builds CycloneDX/SPDX manifests verified by structural code analysis, not just package manifests.
 
----
-
-### 🛠️ Shift-Left Security Automation
+### 🕵️ [Terabyte Log Scanning](./terabyte_log_scanning/README.md)
+High-throughput engines for processing massive data outputs.
+* **PII Leak Hunter:** Scans terabytes of raw logs for accidentally exposed PII without choking system memory.
+* **Terabyte Log Scanner:** Maps static architecture to dynamic runtime execution logs.
 
-Wired directly into your Git Pre-Commit hooks or CI/CD pipelines, these automation tools act as a physical firewall to fail poisoned builds instantly.
+### 🕸️ [Network Auditing](./network_auditing/README.md)
+* **API Network Mapper:** Automatically maps the physical outbound and inbound API surface area and compares it against Swagger/OpenAPI docs to find Shadow APIs.
 
-#### 1. The Supply Chain Firewall (`supply_chain_firewall.py`)
-Scans massive `node_modules` or `venv` directories in seconds.
-* **Zero-Trust Verification:** Checks every physical `import` against strict allowlists.
-* **Behavioral Heuristics:** Scans for tainted data injection routines and runtime modifications.
+### 🦕 [Legacy Modernization: COBOL to Java](./cobol_to_java/README.md) & [COBOL to COBOL](./cobol_to_cobol/README.md)
+A complete suite of architectural controllers for modernizing legacy mainframe systems.
+* **COBOL Refractor:** Slices massive monolithic COBOL programs into isolated microservices.
+* **Java Spring Forge:** Translates legacy business logic into compiling Java Spring architectures.
 
-#### 2. Binary Anomaly Inspector (`binary_anomaly_detector.py`)
-Designed to triage binary files and detect encrypted malware hidden in plain sight.
-* **Magic Byte Validation:** Catches executable scripts disguised as harmless images.
-* **Entropy Math:** Flags high-entropy encrypted text payloads.
-* **Parasitic Headers:** Detects executable logic nested inside static data blobs.
-
-#### 3. Secrets Detection Hook (`vault_sentinel.py`)
-A hyper-speed pre-commit hook strictly for credential and secret detection.
-* **Critical Path Blocking:** Instantly blocks sensitive file path commits (e.g., `.env`, `.pem`).
-* **Deep Content Scanning:** Hunts for hardcoded cloud cryptographic keys and AWS tokens.
-* **Dead Code Secrets:** Finds abandoned passwords hidden deep in commented code.
+### 🤖 [AI Guardrails](./ai_guardrails/README.md)
+* **AppSec Sensor & Dev Agent Firewall:** Middleware sensors that prevent LLMs from being wired to RCE vulnerabilities, and block autonomous AI coding agents from mutating highly complex legacy code.
 
 ---
 
-### 🚀 Quickstart: CI/CD & Pre-Commit Integration
+## 🚀 Execution & CI/CD Integration
 
-Because GitGalaxy bypasses slow ASTs, these scripts execute in seconds, making them perfect for synchronous pipeline blockers.
+The GitGalaxy Spoke architecture allows you to run these specialized tools using three distinct methods:
 
-**Run the Supply Chain Firewall against your local dependencies:**
-```bash
-python3 supply_chain_firewall.py ./node_modules/
-```
+### 1. GitHub Actions (The Universal Pipeline)
+You can trigger any of the standalone CLI tools in your CI/CD pipeline using our universal composite action. Simply change the `tool` parameter to the spoke you want to execute:
 
-**Run the Binary Anomaly Inspector against an incoming Pull Request:**
-```bash
-python3 binary_anomaly_detector.py ./src/
+```yaml
+      - name: Run GitGalaxy Tool
+        uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'supply-chain-firewall' # Options: xray-inspector, zero-trust-sbom, api-network-map, etc.
+          target: '.'
 ```
 
-**Run the Secrets Detection script as a Git pre-commit hook:**
+### 2. Global CLI Execution
+If you have GitGalaxy installed via PyPI (`pip install gitgalaxy`), all the standalone tools are registered as global console scripts. You can run them instantly from your terminal:
 ```bash
-python3 vault_sentinel.py .
+vault-sentinel .
+api-network-map ./src
+pii-leak-hunter ./logs/dump.sql
 ```
 
----
-### 🌌 Powered by the blAST Engine (Bypassing LLMs and ASTs)
-This tool is a specialized integration in the larger GitGalaxy ecosystem. It is driven by our custom mathematical heuristics engine, capable of mapping multi-dimensional relationships at extreme velocity. Explore the official documentation to see the structural heuristics used to catch obfuscated malware:
-
-* 📖 **[Supply Chain Firewall Architecture](../../../docs/wiki/04-03-supply-chain-firewall.md)**
-* 📖 **[Binary Anomaly & Entropy Mathematics](../../../docs/wiki/04-05-binary-anomaly-detector.md)**
-* 📖 **[Hardcoded Secrets Exposure Equations](../../../docs/wiki/08-23-hardcoded-secrets-exposure.md)**
-* 🪐 **[Return to the Main GitGalaxy Hub](https://github.com/squid-protocol/gitgalaxy)**
+### 3. Engine Middleware (AI Guardrails)
+Note that the **AI Guardrails** do not operate as standalone CLI tools. They act as deep-inspection middleware. To utilize them, run the primary `galaxyscope` engine, and the sensors will automatically inject their AppSec findings into the final project telemetry.

gitgalaxy/tools/ai_guardrails/README.md

@@ -14,7 +14,7 @@ GitGalaxy maps the architectural reality of your code in seconds. We use AST-fre
 
 ---
 
-### 🛡️ Side 1: The AI AppSec Sensor (`ai_appsec_sensor.py`)
+### 🛡️ Side 1: The AI AppSec Sensor (`AIAppSecSensor`)
 *Protects your application from the AI features you build.*
 
 Standard AST scanners frequently miss "Weaponized AI Architectures." This sensor maps the physical call-path distance between an LLM API execution and your critical system functions.
@@ -25,7 +25,7 @@ Standard AST scanners frequently miss "Weaponized AI Architectures." This sensor
 
 ---
 
-### 🤖 Side 2: The Dev Agent Firewall (`dev_agent_firewall.py`)
+### 🤖 Side 2: The Dev Agent Firewall (`DevAgentFirewall`)
 *Protects your codebase from the autonomous AI tools you use.*
 
 Not all legacy code is safe for an AI coding assistant (like Cursor, Copilot, or Claude) to modify. This firewall evaluates the structural complexity, cognitive load, and entropy of a file to determine if an AI agent will succeed, hallucinate, or silently destroy your system logic.
@@ -37,13 +37,39 @@ Not all legacy code is safe for an AI coding assistant (like Cursor, Copilot, or
 
 ---
 
-### 🚀 The GitGalaxy Advantage
+### 🚀 Quickstart: CI/CD & Pipeline Integration
 
-This is a fundamentally novel approach to AI Attack Surface Management, built for extreme velocity.
+Currently, the AI Guardrails operate as deep-inspection middleware. Instead of running as standalone standalone commands, these sensors inject themselves into the primary `galaxyscope` analysis pipeline to evaluate project telemetry in real-time.
 
-* **Zero Compilation:** Scans raw text instantly. No build environment or cloud API required.
-* **Contextual Reporting:** Explains the exact architectural danger. No useless "Yes/No" alerts.
-* **CI/CD Ready:** Scans at 100k+ LOC/sec. Blocks dangerous AI-generated PRs synchronously in your pipeline.
+#### 1. Local CLI Execution
+Run a standard scan using the global PyPI package. The guardrails will automatically evaluate the ecosystem and report critical Agentic vulnerabilities.
+```bash
+galaxyscope /path/to/source/code
+```
+
+#### 2. GitHub Actions CI/CD Integration
+To block dangerous AI architectures or prevent AI agents from modifying complex code, run the main GalaxyScope engine on your pull requests. Create `.github/workflows/ai-guardrails.yml`:
+
+```yaml
+name: GitGalaxy AI Guardrails
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  gitgalaxy-ai-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Run GalaxyScope Engine
+        uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'galaxyscope'
+          target: '.'
+```
 
 ---
 ### 🌌 Powered by the blAST Engine (Bypassing LLMs and ASTs)

gitgalaxy/tools/compliance/README.md

@@ -69,10 +69,42 @@ The tool instantly parsed the Go modules, located 170 physical third-party depen
 
 ### 🚀 Quickstart: Generate a Zero-Trust SBOM
 
-Run the Universal SBOM Generator against the root of your project. It will automatically find your manifests, locate the physical dependencies, scan their internals, and output an industry-standard CycloneDX JSON file.
+#### 1. Local CLI Execution
+If you have installed GitGalaxy globally via PyPI (`pip install gitgalaxy`), you can generate a CycloneDX JSON file instantly from your terminal:
 
 ```bash
-python3 sbom_generator.py /path/to/your/project
+zero-trust-sbom /path/to/your/project
+```
+
+#### 2. GitHub Actions CI/CD Integration
+Automate your compliance by generating and saving a mathematically verified SBOM on every release. Create `.github/workflows/generate-sbom.yml`:
+
+```yaml
+name: Generate Zero-Trust SBOM
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-sbom:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Build SBOM via GitGalaxy
+        uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'zero-trust-sbom'
+          target: '.'
+          args: '--out bom.json'
+
+      - name: Upload SBOM Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cyclonedx-sbom
+          path: ./*_bom.json
 ```
 
 ---