trace-sec 0.0.0-stage → 2.1.0

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# TRACE — Threat Reconnaissance & Attack-path Correlation Engine (v2.1)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Security Gate](https://github.com/VK-Amogh/TRACE/actions/workflows/trace-gate.yml/badge.svg)](https://github.com/VK-Amogh/TRACE/actions/workflows/trace-gate.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python](https://img.shields.io/badge/Python-3.11+-green.svg)](https://www.python.org/)
+[![Node.js](https://img.shields.io/badge/NPX-Zero--Install-mint.svg)](https://nodejs.org/)
+[![AI Models](https://img.shields.io/badge/AI_Models-SecureBERT_2.0_%2B_Laya_System_1-emerald.svg)](https://huggingface.co/ehsanaghaei/SecureBERT)
+
+> **Threat Reconnaissance & Attack-path Correlation Engine** — A local-first, zero-telemetry neuro-symbolic security intelligence engine, autonomous agent harness, and deterministic verification layer for AI coding agents (Claude Code, Antigravity, Cursor, Codex, OpenHands).
+
+---
+
+## 🚀 Instant Zero-Install Quickstart (NPX)
+
+Run TRACE immediately on any machine with Node.js installed without cloning or manual configuration:
+
+```bash
+# Launch interactive step-by-step security wizard (via NPM)
+npx @vk.amogh/trace
+
+# Or run directly from GitHub
+npx github:VK-Amogh/TRACE
+
+# Run comprehensive vulnerability audit across all source files and AI models
+npx @vk.amogh/trace audit .
+
+# Interactive Architecture & "How It Works" Guide
+npx @vk.amogh/trace how-it-works
+```
+
+Or install globally via npm:
+```bash
+npm install -g @vk.amogh/trace
+trace welcome
+```
+
+---
+
+## 🤖 AI Coding Agent Integration (Claude Code, Antigravity, Cursor)
+
+TRACE was purpose-built to act as the **ground-truth verification oracle** for autonomous AI coding agents.
+
+### 1-Click Skill & MCP Installation
+Run this single command inside any repository you want your coding agent to audit and repair:
+
+```bash
+npx @vk.amogh/trace install-skill
+```
+
+This immediately registers:
+- **Claude Code Integration:** Configures `.mcp.json` and installs `.claude/skills/trace-security/`
+- **Antigravity / Agentic IDEs:** Installs `.agents/plugins/trace-security/` with rules and skill runbooks
+- **Cursor IDE Integration:** Generates `.cursor/mcp.json`
+
+### Connect Directly to Claude Code CLI
+```bash
+claude mcp add trace -- npx -y @vk.amogh/trace mcp
+```
+
+### Registered Agent MCP Tools:
+| Tool Name | Description |
+|---|---|
+| `trace_scan` | Full static AST + Attack-Path Model (APM) + live exploit correlation |
+| `trace_findings` | Query correlated findings with AST code evidence and reproduction steps |
+| `trace_explain` | Deep-dive root-cause analysis with zero-dummy-bypass remediation guidance |
+| `trace_verify` | Live deterministic verification oracle proving whether an agent's patch fixed the flaw |
+| `trace_harness_task` | Generate standardized benchmark tasks for the current unmitigated vulnerability |
+| `trace_eval_patch` | Score patches produced by external agents with rollback protection |
+
+---
+
+## 🧠 Bundled Neural Intelligence Stack (SecureBERT 2.0 & Laya System 1)
+
+TRACE does **not** rely solely on static heuristics. It incorporates a fine-tuned dual-engine neural stack bundled directly with the repository via **Git LFS**:
+
+1. **SecureBERT 2.0 Semantic Vulnerability Classifier (`ehsanaghaei/SecureBERT` fine-tuned):**
+   - 125M parameter transformer specialized in cybersecurity AST token semantics.
+   - Accurately classifies vulnerability classes: **BOLA/IDOR, BFLA, SSRF, Injection (SQLi/Command), Broken Authentication, Mass Assignment, Path Traversal, CORS**.
+   - Offline cached token representations for instant classification.
+
+2. **Laya System 1 Decision Engine (`convaiinnovations/laya` fine-tuned):**
+   - Dual-head priority router with ONNX Runtime sub-millisecond execution (<0.5ms per endpoint).
+   - Dynamically triages high-risk routes into `P0 (Critical Exploit Path)` down to `P3 (Informational)`.
+
+### Zero-Setup Model Verification
+When cloned or installed, TRACE automatically loads the bundled fine-tuned checkpoints from `.trace/models/`:
+```bash
+trace intelligence
+```
+Output:
+```text
+TRACE Intelligence Stack Status
+  • Laya System 1 Decision Engine: ONLINE (convaiinnovations/laya loaded on CPU)
+  • SecureBERT 2.0 Semantic Classifier: ONLINE (.trace/models/securebert-finetuned)
+  • Model Hierarchy: Deterministic -> SecureBERT -> Laya System 1 -> Local LLM
+```
+
+---
+
+## 🛡️ Core Architecture & Operational Guarantees
+
+TRACE operates on three strict architectural invariants:
+
+```
+  ┌─────────────────────────┐
+  │ Multi-Language AST Code │ (Python, TypeScript, JavaScript, Go, Java, Kotlin, PHP)
+  └────────────┬────────────┘
+               ▼
+  ┌─────────────────────────┐
+  │ Attack-Path Model (APM) │ Directed graph: Endpoints ➔ Handlers ➔ Auth Gates ➔ Sinks
+  └────────────┬────────────┘
+               ▼
+  ┌─────────────────────────┐
+  │ Neural Intelligence     │ SecureBERT 2.0 + Laya System 1 Dual-Engine Scoring
+  └────────────┬────────────┘
+               ▼
+  ┌─────────────────────────┐
+  │ ScopeGuard Runtime DAST │ RFC-1918 / Localhost Sandboxed Active Probing
+  └────────────┬────────────┘
+               ▼
+  ┌─────────────────────────┐
+  │ Ground-Truth Findings   │ 100% Correlated Evidence (Zero False Positives)
+  └────────────┬────────────┘
+               ▼
+  ┌─────────────────────────┐
+  │ Agent Remediation Loop  │ Auto-patching + Verification Oracle + SWE-bench Export
+  └─────────────────────────┘
+```
+
+1. **100% Local-First & Offline:**
+   - Operates completely on your local workstation. Zero external cloud telemetry or proprietary API dependencies.
+2. **ScopeGuard Boundary Enforcement:**
+   - Dynamic probing is hard-isolated to localhost and authorized development containers. Cloud destinations and third-party APIs are rejected at the socket layer.
+3. **Zero-False-Positive Guarantee:**
+   - Flaws are only promoted to `CONFIRMED` when both static AST attack paths and live runtime oracles prove exploitability.
+
+---
+
+## 💻 CLI Command Reference
+
+### Comprehensive Audits & Testing
+```bash
+# Interactive guided terminal audit wizard
+trace
+
+# Full repository audit across all languages, test packs, and AI models
+trace audit [PATH]
+
+# End-to-end scan with target URL and SARIF report export
+trace scan [PATH] --target http://127.0.0.1:18080 --format sarif -o results.sarif
+
+# Explain a specific finding with reproduction curl commands
+trace explain TR-BOLA-001
+
+# Replay exact HTTP reproduction steps
+trace replay TR-BOLA-001
+```
+
+### Autonomous Remediation & Benchmarking
+```bash
+# Run self-healing remediation loop (synthesize fix, apply patch, verify oracle)
+trace heal [PATH]
+
+# Verify if a developer or coding agent's code change resolved a finding
+trace verify TR-BOLA-001
+
+# Benchmark coding agent performance against TRACE-Bench v1.0 scorecard
+trace bench [PATH] --model "Claude-3.7-Sonnet"
+
+# Export benchmark instances to SWE-bench JSONL format
+trace plugin export -o swebench_tasks.jsonl
+```
+
+### System Inspection & Labs
+```bash
+# Environment diagnostic check (Tree-sitter, SQLite, PyTorch, Tool Adapters)
+trace doctor
+
+# Start reference vulnerable Vending API lab
+trace lab start --port 18080
+```
+
+---
+
+## 🛠️ Python Local Installation (Alternative)
+
+If developing directly inside Python:
+
+```bash
+git clone https://github.com/VK-Amogh/TRACE.git
+cd TRACE
+
+# Ensure Git LFS pulls the model checkpoints
+git lfs pull
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Or on Windows: .venv\Scripts\activate
+
+# Install editable package
+pip install -e .
+
+# Run test suite (63 unit tests)
+pytest
+```
+
+---
+
+## 📄 License
+
+Apache License 2.0. See [LICENSE](LICENSE) for details.

package/bin/trace.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * TRACE — Threat Reconnaissance & Attack-path Correlation Engine
+ * Node.js & NPX launcher for TRACE Python engine.
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, cpSync, writeFileSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = resolve(__dirname, '..');
+const args = process.argv.slice(2);
+
+// Handle install-skill directly in Node.js for instant zero-dependency agent skill setup
+if (args[0] === 'install-skill' || args[0] === 'setup-agent' || args[0] === 'install-agent') {
+  const targetDir = process.cwd();
+  const bundleDir = join(projectRoot, 'src', 'trace_engine', 'plugin', 'bundle');
+
+  console.log('\n\x1b[32m\x1b[1mInstalling TRACE Autonomous Security Agent Skill & MCP Tools...\x1b[0m');
+
+  if (existsSync(bundleDir)) {
+    // 1. Antigravity plugin (.agents/plugins/trace-security)
+    const agentPluginDir = join(targetDir, '.agents', 'plugins', 'trace-security');
+    mkdirSync(agentPluginDir, { recursive: true });
+    cpSync(bundleDir, agentPluginDir, { recursive: true });
+    console.log(`  \x1b[32m✓\x1b[0m Antigravity Plugin : ${agentPluginDir}`);
+
+    // 2. Direct agent skill (.agents/skills/trace-security-harness)
+    const skillSrc = join(bundleDir, 'skills', 'trace-security-harness');
+    if (existsSync(skillSrc)) {
+      const agentSkillDir = join(targetDir, '.agents', 'skills', 'trace-security-harness');
+      mkdirSync(agentSkillDir, { recursive: true });
+      cpSync(skillSrc, agentSkillDir, { recursive: true });
+      console.log(`  \x1b[32m✓\x1b[0m Agent Skill        : ${agentSkillDir}`);
+
+      // 3. Claude Code skill (.claude/skills/trace-security)
+      const claudeSkillDir = join(targetDir, '.claude', 'skills', 'trace-security');
+      mkdirSync(claudeSkillDir, { recursive: true });
+      cpSync(skillSrc, claudeSkillDir, { recursive: true });
+      console.log(`  \x1b[32m✓\x1b[0m Claude Code Skill  : ${claudeSkillDir}`);
+    }
+
+    // 4. MCP Configuration (.mcp.json and .cursor/mcp.json)
+    const isWin = process.platform === 'win32';
+    const mcpConfig = {
+      mcpServers: {
+        trace: {
+          command: isWin ? 'cmd.exe' : 'npx',
+          args: isWin
+            ? ['/c', 'npx', '-y', 'github:VK-Amogh/TRACE', 'mcp']
+            : ['-y', 'github:VK-Amogh/TRACE', 'mcp'],
+          env: {
+            PYTHONUNBUFFERED: '1',
+          },
+        },
+      },
+    };
+    const mcpJsonPath = join(targetDir, '.mcp.json');
+    writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2), 'utf-8');
+    console.log(`  \x1b[32m✓\x1b[0m Claude Code MCP    : ${mcpJsonPath}`);
+
+    const cursorMcpDir = join(targetDir, '.cursor');
+    mkdirSync(cursorMcpDir, { recursive: true });
+    writeFileSync(join(cursorMcpDir, 'mcp.json'), JSON.stringify(mcpConfig, null, 2), 'utf-8');
+    console.log(`  \x1b[32m✓\x1b[0m Cursor IDE MCP     : ${join(cursorMcpDir, 'mcp.json')}`);
+
+    console.log('\n\x1b[1mCapabilities Enabled for AI Coding Agents:\x1b[0m');
+    console.log('  • \x1b[32mClaude Code Integration:\x1b[0m Skills + MCP server ready');
+    console.log('  • \x1b[32mAntigravity & Agentic IDEs:\x1b[0m .agents/plugins/trace-security active');
+    console.log('  • \x1b[32mVerification Tools:\x1b[0m trace_scan, trace_findings, trace_verify, trace_harness_task');
+    console.log('\n\x1b[90mTo register in Claude Code CLI directly:\x1b[0m');
+    console.log('  \x1b[37mclaude mcp add trace -- npx github:VK-Amogh/TRACE mcp\x1b[0m\n');
+    process.exit(0);
+  } else {
+    console.error(`[TRACE] Bundle directory not found at ${bundleDir}`);
+    process.exit(1);
+  }
+}
+
+// Find virtual environment python or system python
+const isWin = process.platform === 'win32';
+const venvPython = isWin
+  ? join(projectRoot, '.venv', 'Scripts', 'python.exe')
+  : join(projectRoot, '.venv', 'bin', 'python');
+
+const pythonBin = existsSync(venvPython) ? venvPython : (isWin ? 'python' : 'python3');
+
+const cliArgs = ['-m', 'trace_engine.cli', ...args];
+
+const proc = spawn(pythonBin, cliArgs, {
+  cwd: process.cwd(),
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    PYTHONPATH: join(projectRoot, 'src') + (process.env.PYTHONPATH ? (isWin ? ';' : ':') + process.env.PYTHONPATH : ''),
+    PYTHONIOENCODING: 'utf-8',
+  },
+});
+
+proc.on('exit', (code) => {
+  process.exit(code || 0);
+});
+
+proc.on('error', (err) => {
+  console.error(`[TRACE] Failed to spawn Python process (${pythonBin}):`, err.message);
+  console.error(`Please ensure Python 3.10+ is installed and on your PATH, or run: pip install -e .`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "trace-sec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.1.0",
+  "description": "Threat Reconnaissance & Attack-path Correlation Engine — Security Verification Layer for Coding Agents with Fine-Tuned SecureBERT 2.0 & Laya AI",
+  "type": "module",
+  "main": "bin/trace.js",
+  "bin": {
+    "trace": "./bin/trace.js",
+    "trace-sec": "./bin/trace.js",
+    "trace-security": "./bin/trace.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "pyproject.toml"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VK-Amogh/TRACE.git"
+  },
+  "bugs": {
+    "url": "https://github.com/VK-Amogh/TRACE/issues"
+  },
+  "homepage": "https://github.com/VK-Amogh/TRACE#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "security",
+    "dast",
+    "sast",
+    "attack-path",
+    "mcp",
+    "claude-code",
+    "cursor",
+    "codex",
+    "antigravity",
+    "vulnerability",
+    "securebert",
+    "laya",
+    "agent-harness"
+  ],
+  "author": "Amogh (VK-Amogh)",
+  "license": "Apache-2.0"
+}

package/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trace-sec"
+version = "1.0.0"
+description = "Threat Reconnaissance & Attack-path Correlation Engine"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "TRACE Core Team" }
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+    "pydantic>=2.7.0",
+    "pydantic-settings>=2.2.0",
+    "networkx>=3.2.0",
+    "httpx>=0.27.0",
+    "orjson>=3.9.0",
+    "tomli-w>=1.0.0",
+    "tree-sitter>=0.21.0",
+    "tree-sitter-language-pack>=0.2.0",
+]
+
+[project.scripts]
+trace = "trace_engine.cli:app"
+Trace = "trace_engine.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trace_engine"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+filterwarnings = [
+    "ignore::RuntimeWarning:laya.*",
+]

package/src/trace_engine/__init__.py

@@ -0,0 +1,8 @@
+"""TRACE — Threat Reconnaissance & Attack-path Correlation Engine.
+
+Local-first application security analysis and runtime validation engine.
+"""
+
+__version__ = "1.0.0"
+__app_name__ = "TRACE"
+__description__ = "Threat Reconnaissance & Attack-path Correlation Engine"

package/src/trace_engine/ai/__init__.py

@@ -0,0 +1,7 @@
+"""Local AI orchestration module."""
+
+from trace_engine.ai.base import AIProvider
+from trace_engine.ai.ollama import OllamaProvider
+from trace_engine.ai.planner import TestPlanner
+
+__all__ = ["AIProvider", "OllamaProvider", "TestPlanner"]

package/src/trace_engine/ai/base.py

@@ -0,0 +1,23 @@
+"""Base interfaces for local AI providers."""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any
+
+
+class AIProvider(ABC):
+    """Abstract interface for local LLM engines."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if local inference engine is reachable."""
+        pass
+
+    @abstractmethod
+    def generate(self, prompt: str, system_prompt: Optional[str] = None) -> Optional[str]:
+        """Generate a response using the local model."""
+        pass

package/src/trace_engine/ai/ollama.py

@@ -0,0 +1,50 @@
+"""Ollama local AI provider."""
+
+import httpx
+from typing import Optional
+from trace_engine.ai.base import AIProvider
+
+
+class OllamaProvider(AIProvider):
+    """Integrates with local Ollama runtime for offline model execution."""
+
+    def __init__(
+        self,
+        endpoint: str = "http://127.0.0.1:11434",
+        model: str = "qwen2.5-coder:latest",
+        temperature: float = 0.1,
+    ):
+        self.endpoint = endpoint.rstrip("/")
+        self.model = model
+        self.temperature = temperature
+
+    @property
+    def name(self) -> str:
+        return f"Ollama ({self.model})"
+
+    def is_available(self) -> bool:
+        try:
+            with httpx.Client(timeout=2.0) as client:
+                res = client.get(f"{self.endpoint}/api/tags")
+                return res.status_code == 200
+        except Exception:
+            return False
+
+    def generate(self, prompt: str, system_prompt: Optional[str] = None) -> Optional[str]:
+        try:
+            payload = {
+                "model": self.model,
+                "prompt": prompt,
+                "stream": False,
+                "options": {"temperature": self.temperature},
+            }
+            if system_prompt:
+                payload["system"] = system_prompt
+
+            with httpx.Client(timeout=30.0) as client:
+                res = client.post(f"{self.endpoint}/api/generate", json=payload)
+                if res.status_code == 200:
+                    return res.json().get("response")
+        except Exception:
+            pass
+        return None

package/src/trace_engine/ai/planner.py

@@ -0,0 +1,40 @@
+"""AI and deterministic test planner for orchestrating security validation."""
+
+from typing import List, Optional
+from trace_engine.security.hypotheses import SecurityHypothesis
+from trace_engine.ai.base import AIProvider
+from trace_engine.ai.ollama import OllamaProvider
+
+
+class TestPlanner:
+    """Orchestrates test selection using deterministic signals and optional local AI reasoning."""
+
+    def __init__(self, ai_provider: Optional[AIProvider] = None):
+        self.ai_provider = ai_provider or OllamaProvider()
+
+    def prioritize_hypotheses(
+        self, hypotheses: List[SecurityHypothesis]
+    ) -> List[SecurityHypothesis]:
+        """Orders hypotheses by severity prior and attack surface criticality."""
+        return sorted(hypotheses, key=lambda h: h.confidence_prior, reverse=True)
+
+    def explain_finding_with_ai(
+        self, title: str, category: str, attack_path: List[str], evidence: List[str]
+    ) -> str:
+        """Uses local AI if available to explain root cause and exploitability in plain language."""
+        if self.ai_provider and self.ai_provider.is_available():
+            prompt = (
+                f"Explain the security vulnerability '{title}' in category {category}.\n"
+                f"Attack path hops: {' -> '.join(attack_path)}\n"
+                f"Evidence: {'; '.join(evidence)}\n"
+                f"Provide a concise, 2-3 sentence technical explanation of the exploit risk and fix."
+            )
+            response = self.ai_provider.generate(prompt)
+            if response:
+                return response.strip()
+
+        # Fallback explanation
+        return (
+            f"The attack path violates security invariant {category}. "
+            f"Static code flow reaches sensitive sink without boundary enforcement."
+        )

package/src/trace_engine/apm/__init__.py

@@ -0,0 +1,18 @@
+"""Attack-Path Model (APM) module."""
+
+from trace_engine.apm.nodes import APMNode, NodeType
+from trace_engine.apm.edges import APMEdge, EdgeType
+from trace_engine.apm.model import AttackPathModel
+from trace_engine.apm.builder import APMBuilder
+from trace_engine.apm.serialization import save_apm_sqlite, export_apm_json
+
+__all__ = [
+    "APMNode",
+    "NodeType",
+    "APMEdge",
+    "EdgeType",
+    "AttackPathModel",
+    "APMBuilder",
+    "save_apm_sqlite",
+    "export_apm_json",
+]