Nexus-KDG

A local-first AI egress gateway for source code.

Made by Kasukabe Defense Group: Srijeet, Ayushman, and Priyanshu.

Nexus sits between a developer workflow and AI coding models. It inspects each request locally, removes secrets, pseudonymizes proprietary Python identifiers, chooses a local, sanitized-cloud, or blocked route, and records a tamper-evident audit event.

Current scope: a Python/FastAPI daemon, CLI, privacy pipeline, Ollama adapter, Groq/Anthropic cloud adapters, automated tests, and a VS Code/Cursor Command Center extension.

Core flow

flowchart LR
    %% Define Styles
    classDef user fill:#6366f1,stroke:#fff,stroke-width:2px,color:#fff,rx:8px
    classDef process fill:#1e293b,stroke:#cbd5e1,stroke-width:2px,color:#fff,rx:8px
    classDef decision fill:#f59e0b,stroke:#fff,stroke-width:2px,color:#fff,rx:8px
    classDef cloud fill:#0ea5e9,stroke:#fff,stroke-width:2px,color:#fff,rx:8px
    classDef local fill:#10b981,stroke:#fff,stroke-width:2px,color:#fff,rx:8px
    classDef block fill:#ef4444,stroke:#fff,stroke-width:2px,color:#fff,rx:8px
    classDef audit fill:#8b5cf6,stroke:#fff,stroke-width:2px,color:#fff,rx:8px

    %% Flow
    User([👨‍💻 Developer Request]):::user --> Scan[🔍 Secret Scan]:::process
    Scan --> AST[🌳 AST Symbol Extraction]:::process
    AST --> Pseudo[🎭 Semantic Pseudonymization]:::process
    Pseudo --> Policy[📜 YAML Policy Eval]:::process
    
    Policy --> Route{Route Decision}:::decision
    
    %% Routes
    Route -- "sanitized_cloud" --> Egress[🛡️ Egress Verification]:::process
    Egress --> Cloud([☁️ Groq / Anthropic]):::cloud
    
    Route -- "local_only" --> Local([💻 Ollama Local Model]):::local
    
    Route -- "blocked" --> Blocked([🚫 Blocked Request]):::block
    
    %% Return Path
    Cloud --> Detoken[🧩 Local De-tokenization]:::process
    Local --> Detoken
    
    Detoken --> Audit[(🔗 Hash-chained Audit)]:::audit
    Blocked --> Audit

Loading

Why it exists

Developers in regulated or IP-sensitive environments often face a bad trade-off:

• use a strong cloud model and expose sensitive context;
• use a small local model and lose capability;
• manually scrub every prompt and slow down the workflow.

Nexus treats privacy as a routing and verification problem instead of forcing one model choice for every request.

Current capabilities

• Regex and entropy-based secret detection
• Python AST symbol extraction
• Semantic identifier pseudonymization
• YAML policy engine
• Local-only, sanitized-cloud, and blocked routes
• Ollama local inference
• Groq / Anthropic sanitized-cloud adapters with exact egress verification
• Local response de-tokenization
• SQLite hash-chained audit ledger with Phase 3 truthful egress receipts (intended vs actual provider/route, call attempts, payload hash - never raw code/secrets/maps)
• Request-scoped exact outbound payload inspection (token-gated short-lived lookup)
• VS Code/Cursor Command Center extension with live secure assist, Nexus Chat, and fixture modes
• Nexus Chat approval gate with Review Suggestion, Approve & Apply, Deny Suggestion, and + New Session
• Session-scoped temporary secret vault for placeholder restoration, deleted on approve, deny, cancel, new session, expiry, or daemon restart stale cleanup
• Chat-to-Command Center synchronization for live request evidence, receipts, protected context, and exact outbound payload review
• Local hybrid repository indexing, secure scan, human approval plan, and redacted patch preview workflow
• Repository API protected by X-Nexus-Token
• Dependency/generated artifact filtering for repo scans (node_modules, lockfiles, build output, caches)
• nexus audit verify and nexus audit list
• FastAPI endpoints for assist, redact, route, health, audit verification, and repository indexing/search/remediation
• Local hybrid repository indexing (SQLite + FTS5) with CLI nexus repo ... commands

Important limitations

This is a hackathon prototype, not a production security boundary.

• It is a local daemon, not an operating-system kernel.
• Python is the only AST-aware language currently supported.
• Secret detection is heuristic and cannot guarantee detection of every sensitive value.
• The current hash chain is tamper-evident, not independently signed.
• OS-wide or network-wide enforcement is future work.
• The extension is an MVP demo surface, not a production policy enforcement layer.

Setup

Requires Python 3.11+.

Install from PyPI:

pip install kdg-nexus
nexus --version
nexus --help

For local development from this repository:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

For local inference:

ollama serve
ollama pull llama3.2:3b

Set the model in .env when needed:

NEXUS_OLLAMA_MODEL=llama3.2:3b

Start the daemon:

uvicorn nexus.main:app --host 127.0.0.1 --port 7420

Health check:

curl http://127.0.0.1:7420/v1/health

VS Code / Cursor extension demo

The extension has two modes:

• Live (default): calls the local Nexus daemon, keeps the local Nexus token in the extension host, and shows real request evidence.
• Fixture: uses built-in UI fixtures for offline Command Center review.

The extension now exposes two synchronized surfaces:

• Nexus Chat: sidebar chat for file-scoped assist, streamed responses, safe diff preview, human approval, denial, and new chat sessions.
• Nexus Command Center: evidence dashboard for the latest live request, including route, provider, protected context, exact cloud payload, events, receipt, and audit verification.

For the judge-ready live path, run:

powershell -ExecutionPolicy Bypass -File scripts\run_judge_demo.ps1

Then follow docs/JUDGE_DEMO.md.

Build the extension:

cd extension
npm install
cd webview-ui
npm install
cd ..
npm run build

Start the real daemon before the live demo:

python -m uvicorn nexus.main:app --host 127.0.0.1 --port 7420

Launch the Extension Development Host:

code --extensionDevelopmentPath=C:\Users\mukhe\KDG\extension C:\Users\mukhe\KDG

In the Extension Development Host:

1. Open a Python file containing synthetic sensitive code.
2. Select the code, or leave the selection empty to use a bounded current-file excerpt.
3. Run Nexus: Ask Privately.
4. Enter a question, for example: The intended multiplier is 1.25. Return corrected Python code containing the class and function names.
5. Confirm the restored answer appears in Command Center.
6. Verify the Live badge plus request evidence: route, provider, real event timeline, exact sanitized outbound payload, receipt, and audit verification.

Nexus Chat approval workflow

1. Open a Python file or select a span of code.
2. Ask Nexus Chat for a fix.
3. Nexus masks credentials and proprietary identifiers locally before any cloud request.
4. The cloud model receives only the protected payload; Command Center shows the exact sanitized payload for audit.
5. After the model responds, Nexus restores local placeholders for the developer-facing answer and patch preview.
6. Use Review Suggestion to inspect the generated diff.
7. Use Approve & Apply to apply the patch and end the session, or Deny Suggestion to stop without editing files.
8. When the session ends, temporary raw secret material for that session is deleted.
9. Click + to start a clean chat session with a new session id.

Provider requirements:

• sanitized_cloud needs a working Groq or Anthropic credential.
• Local fallback needs Ollama running and the configured model pulled.
• If Command Center shows provider: none, the cloud call failed and local fallback did not produce a response. Check provider credentials, rate limits, network access, and ollama_available in /v1/health.

To use fixtures instead, set nexus.mode to fixture in VS Code settings and open Nexus: Open Command Center.

For larger codebases, run Nexus: Scan Codebase Privately from the Command Palette. Nexus registers and indexes the open workspace locally, ranks candidate files from indexed secret fingerprints, diagnostics, test-output hints, the focus query, and the active editor path as ranking context. It then asks you to approve exact indexed files from a picker before patch preview. The preview report uses redacted diffs and never writes source files automatically.

For a richer masking demo, open demo-repo/customer_support/secure_ticket_service.py. It contains only synthetic fake credentials, fake personal data, normal code, and small logic bugs. Use the prompt in demo-repo/README.md to verify that secrets and personal data are removed before sanitized cloud assist.

Run tests:

pytest -q

API example

curl -X POST http://127.0.0.1:7420/v1/assist \
  -H "Content-Type: application/json" \
  -d '{
    "code": "def calculate_internal_risk_score_for_loan_default(x):\n    return x * 2",
    "file_path": "payments/risk_engine.py",
    "diagnostics": [],
    "test_output": null,
    "question": "Why is this calculation failing?"
  }'

Recommended Demo Flow

1. Show a normal AI request that would expose a fake credential and proprietary identifiers.
2. Send the same request through Nexus and open the exact outbound payload.
3. Receive a cloud-generated fix, restore the real names locally, and pass the failing test.
4. Attempt prompt injection and show that no cloud request is made.
5. Run nexus audit verify, then demonstrate detection on a deliberately tampered copy.

CLI

nexus audit list
nexus audit verify

# Repository indexing (Phase 2.5)
nexus repo register /path/to/your/repo
nexus repo index <repo_id>
nexus repo search <repo_id> "symbol_or_query" --json
nexus repo list
nexus repo status <repo_id>

Repository indexing (Phase 2.5)

Nexus can index local repositories into isolated SQLite + FTS5 databases under ~/.nexus/indexes/ (override with NEXUS_INDEX_DB_ROOT). Search and context retrieval run entirely on your machine - no model or network calls.

Endpoint	Purpose
POST /v1/repos	Register a local path
GET /v1/repos	List repositories
GET /v1/repos/{repo_id}	Index status
POST /v1/repos/{repo_id}/index	Build or update ({"full": true} for full rebuild)
POST /v1/repos/{repo_id}/search	Hybrid search (no model)
POST /v1/repos/{repo_id}/scan	Safe repo-wide remediation candidate scan (no model)
POST /v1/repos/{repo_id}/fix-plan	Human approval plan for candidate files (no model)
POST /v1/repos/{repo_id}/patch-preview	Redacted, non-writing patch previews for approved files
POST /v1/repos/{repo_id}/assist	Context pack -> recovery guard -> privacy pipeline

Privacy notes:

• Secrets are never stored raw in the index - only redacted chunks and HMAC-SHA256 fingerprints (key at ~/.nexus/fingerprint_key).
• /v1/repos* requires a local API token via X-Nexus-Token (stored at ~/.nexus/api_token). CORS is explicit loopback origins only (no *).
• Git discovery includes tracked and untracked non-ignored files (git ls-files -co --exclude-standard).
• Dependency/generated artifacts are excluded from remediation candidates by default, including common package lockfiles, build output, caches, and node_modules.
• full=true reprocesses every file; config drift requires a full rebuild.
• Oversized files are partially indexed with bounded streaming and coverage stats.
• /v1/repos/{id}/search never calls a provider.
• /v1/repos/{id}/assist re-reads selected spans from disk, runs the recovery guard, then applies the sanitize/egress pipeline.
• Index builds run as background jobs (per-repo lock); poll GET /v1/repos/{id} for readiness.

Architecture: docs/architecture/REPOSITORY_INDEXING_ARCHITECTURE.md.
Measured local benchmarks: benchmarks/README.md.

Limitations (indexing v1)

Python gets AST-aware chunking; other languages use line windows. Retrieval uses import-graph one-hop expansion (no call-graph). Semantic/vector search is optional and off by default. This is a local hybrid indexer - not a claim of parity with proprietary code-search products.

Security

Never commit .env, API keys, generated databases, or real proprietary code. The committed demo fixtures contain fake values only.

Phase 4/5 additions

• Typed provider errors and fallback state machine (docs/architecture/PROVIDER_FAILURE_STATE_MACHINE.md)
• Execution event stream (docs/architecture/EXECUTION_EVENT_STREAM.md)
• Report: docs/reports/PHASE_4_5_PROVIDER_LIFECYCLE_REPORT.md