GitHub - AA-KH/Trace

████████╗██████╗  █████╗  ██████╗███████╗██████╗ ██╗      █████╗ ███████╗████████╗
╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║     ██╔══██╗██╔════╝╚══██╔══╝
   ██║   ██████╔╝███████║██║     █████╗  ██████╔╝██║     ███████║███████╗   ██║
   ██║   ██╔══██╗██╔══██║██║     ██╔══╝  ██╔══██╗██║     ██╔══██║╚════██║   ██║
   ██║   ██║  ██║██║  ██║╚██████╗███████╗██████╔╝███████╗██║  ██║███████║   ██║
   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝╚═════╝ ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝

Don't just scan. Understand.

The Reachability-Aware Vulnerability Intelligence Engine

Built by QuadCore — Saksham Sood · Aaradhya Khanna · Sameer Garg · Sourabh Bansal
Hack Helix Hackathon 2026

🚨 Problem Statement

Existing vulnerability scanners are loud, not smart. They flood developers with alerts without answering the only question that actually matters:

"Does this CVE affect my running application — and can an attacker actually reach it?"

Pain Point	The Reality
Alert fatigue	Tools scream about every CVE in `node_modules`, whether or not the vulnerable code is ever called
No reachability context	"lodash is vulnerable" tells you nothing about whether `lodash.template()` is reachable from your login route
Phantom dependency noise	Packages declared in `package.json` but never imported inflate finding counts by 30–60%
No negative detection	Tools only alert — they never tell you a CVE is safe because the path doesn't exist
Missing call-graph depth	Package-level reachability is not function-level reachability. The difference is the difference between a false alarm and an actual RCE

💡 Solution Overview

TraceBlast is a reachability-aware vulnerability intelligence engine. It does not just report which packages have CVEs — it traces every CVE from the package back through your dependency graph to your HTTP entry points, scores how exploitable it truly is, and tells you when something is not reachable.

It operates across three analysis tiers, automatically selecting the deepest tier available in your environment:

Tier 1 — Manifest Analysis: BFS graph traversal + CVE scoring. Always available, runs in milliseconds.
Tier 2 — Dependency Intelligence: Phantom detection, fix-commit diff analysis, OSV/npm ecosystem enrichment.
Tier 3 — Full Signal Analysis: Semgrep taint/sink confirmation, js-callgraph / Jelly function-level reachability, combined six-signal exploitability model.

🧬 Core Features

🔍 Six-Signal Exploitability Model

TraceBlast replaces simple CVSS scoring with a multi-signal formula:

E = S_cve · Φ(E) · semgrep_boost · callgraph_multiplier · ecosystem_multiplier · (1 + α · log P)

Each signal either confirms or suppresses a finding. A CVE with CVSS 9.8 scores zero if the call graph proves the vulnerable function is unreachable.

🚫 Negative Detection — The Feature No One Else Has

If TraceBlast cannot find a path from any entry point to the vulnerable package, it says so explicitly with "reachable": false and "risk_label": "safe". Most scanners only scream. TraceBlast also knows when to stay quiet.

👻 Phantom Dependency Pruning

Packages declared in package.json but never imported or required anywhere in source are flagged as phantom dependencies. Their CVEs are suppressed entirely — no score, no alert, no noise.

🔬 Fix-Commit Diff Analysis

TraceBlast fetches the actual commit that patched each CVE from the OSV database, parses the diff, and extracts the exact vulnerable function name. This upgrades call-graph and Semgrep queries from package-level to function-level precision.

🗺️ Subway-Map Visualizer

A React/Vite frontend renders every dependency path as an interactive subway map. Each node is coloured by risk label. Click any stop to open the signal breakdown panel for that finding.

🧩 VS Code Extension

A native VS Code extension surfaces TraceBlast findings inline while you code — no terminal required.

⌨️ CLI

A Node.js CLI (trace-cli) lets you pipe TraceBlast results into CI pipelines, scripts, or other tooling.

🧠 System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Client Layer                             │
│   React/Vite Subway UI  ·  VS Code Extension  ·  trace-cli     │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTP  POST /analyze
┌──────────────────────────▼──────────────────────────────────────┐
│                    Flask API Gateway                            │
│                app.py  ·  ingestion.py                         │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│               Analysis Orchestrator (orchestrator.py)           │
│                                                                 │
│  ┌─── Tier 1 ──────────────────────────────────────────────┐   │
│  │  traversal.py (NetworkX BFS)  ·  heuristic.py (Φ calc)  │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─── Tier 2 ──────────────────────────────────────────────┐   │
│  │  phantom_signal.py  ·  fixcommit_signal.py              │   │
│  │  ecosystem_signal.py (OSV API + npm downloads)          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─── Tier 3 ──────────────────────────────────────────────┐   │
│  │  semgrep_signal.py (taint/sink)                         │   │
│  │  callgraph_signal.py (Jelly / js-callgraph)             │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  exploitability_model.py — six-signal combiner + hard gates    │
└─────────────────────────────────────────────────────────────────┘

Signal Registry

Signal	Module	Tier	What It Contributes
BFS Traversal	`traversal.py`	1	Shortest path from entry point to vulnerable package
Heuristic Φ(E)	`heuristic.py`	1	Import-chain confidence score
OSV + npm	`ecosystem_signal.py`	2	CVSS enrichment, PoC detection, popularity multiplier
Phantom Detector	`phantom_signal.py`	2	Suppresses packages that are declared but never imported
Fix-Commit Diff	`fixcommit_signal.py`	2	Resolves exact vulnerable function from the patch commit
Semgrep	`semgrep_signal.py`	3	Confirms user-controlled data reaches the vulnerable sink
Call Graph	`callgraph_signal.py`	3	Function-level reachability via Jelly or js-callgraph

📐 The Scoring Model

Formula

E = S_cve · Φ(E) · semgrep_boost · callgraph_multiplier · ecosystem_multiplier · (1 + α · log P)

Term	Range	Meaning
`S_cve`	0 – 10	Raw CVSS base score
`Φ(E)`	0.1 – 1.0	Import-chain confidence (lower for barrel exports / dynamic imports)
`semgrep_boost`	0.8 – 1.0	Taint/sink confirmation from Semgrep
`callgraph_multiplier`	0.0 – 1.0	0.0 = hard gate if function is provably unreachable
`ecosystem_multiplier`	1.0 – 2.0	Network exploitability + PoC availability + package popularity
`P` (proximity)	1 – N	Number of hops from entry point
`α`	0.0 – 5.0	Tunable weight (default 0.5)

Hard Gates

Two conditions force the score to zero before the formula runs:

Phantom gate — package declared but never imported → score = 0, label = "phantom"
Call-graph gate — Jelly/js-callgraph finds no path to the vulnerable function → score = 0, label = "safe"

Risk Labels

Score	Label
≥ 9.0	`critical`
≥ 7.0	`high`
≥ 4.0	`medium`
≥ 1.0	`low`
= 0.0	`safe`
Φ < 0.4	`uncertain` (manual review advised)
Phantom	`phantom`

🔌 API Reference

All endpoints are documented via Flask's interactive spec at /docs.

`POST /analyze`

Run a full multi-tier analysis.

Request body:

{
  "cves": [
    {
      "id": "CVE-2021-23337",
      "package": "lodash",
      "cvss": 7.2,
      "description": "Command injection"
    }
  ],
  "entry_points": [{ "id": "POST /login", "type": "http" }],
  "dependency_graph": {
    "POST /login": ["app.js"],
    "app.js": ["auth.js"],
    "auth.js": ["lodash"]
  },
  "project_root": "/path/to/project",
  "max_tier": 3,
  "alpha": 0.5,
  "github_token": "ghp_...",
  "semgrep_rules": ["p/javascript.express"]
}

Response:

{
  "findings": [
    {
      "cve_id":      "CVE-2021-23337",
      "package":     "lodash",
      "cvss":        7.2,
      "entry_point": "POST /login",
      "reachable":   true,
      "risk_label":  "high",
      "score":       6.19,
      "path":        ["POST /login", "app.js", "auth.js", "lodash"],
      "exploitability": {
        "score": 6.19,
        "breakdown": { "s_cve": 7.2, "phi": 0.333, "p_term": 1.693 }
      },
      "signals":     { "ecosystem": {...}, "callgraph": {...} },
      "investigative_prompts": ["..."],
      "tier": 3
    }
  ],
  "nodes": [
    { "id": "POST /login", "type": "ingress" },
    { "id": "lodash",      "type": "dependency" },
    { "id": "app.js",      "type": "app" }
  ],
  "edges": [
    { "from": "POST /login", "to": "app.js" },
    { "from": "app.js",      "to": "auth.js" },
    { "from": "auth.js",     "to": "lodash" }
  ],
  "paths": [
    { "id": "path_0", "nodes": ["POST /login", "app.js", "auth.js", "lodash"] }
  ],
  "tier_used":         3,
  "signals_available": ["bfs_traversal", "heuristic_phi", "ecosystem_osv", "semgrep", "jelly"]
}

`GET /health`

Returns tier detection, available signals, and engine version.

{
  "status": "ok",
  "tier_available": 2,
  "signals_available": [
    "bfs_traversal",
    "heuristic_phi",
    "ecosystem_osv",
    "phantom_detector",
    "fix_commit_diff"
  ],
  "engine_version": "2.0.0"
}

📂 Project Structure

Trace/
│
├── Task12/                        # Python Analysis Engine (Flask API)
│   ├── app.py                     # Flask entrypoint — POST /analyze, GET /health
│   ├── orchestrator.py            # Three-tier orchestrator — selects tier, runs signals
│   ├── traversal.py               # NetworkX BFS path finder
│   ├── heuristic.py               # Φ(E) confidence calculator
│   ├── exploitability_model.py    # Six-signal scoring formula + hard gates
│   ├── phantom_signal.py          # Phantom dependency detector
│   ├── ecosystem_signal.py        # OSV API + npm download enrichment
│   ├── fixcommit_signal.py        # Fix-commit diff → vulnerable function resolver
│   ├── semgrep_signal.py          # Semgrep taint/sink analyser
│   ├── callgraph_signal.py        # Jelly / js-callgraph reachability
│   ├── ingestion.py               # Payload validation
│   └── output.py                  # Output generator
│
├── kdbdfvh/                       # React / Vite Subway Visualizer
│   ├── src/
│   │   ├── App.tsx
│   │   ├── trace/
│   │   │   ├── TraceMapView.tsx   # Root map component
│   │   │   ├── SubwayPathCanvas.tsx
│   │   │   ├── MergedSubwayCanvas.tsx
│   │   │   ├── NodeDetailPanel.tsx
│   │   │   ├── FilterToolbar.tsx
│   │   │   ├── RiskLegend.tsx
│   │   │   ├── ApiUrlInput.tsx
│   │   │   ├── PathJsonInput.tsx
│   │   │   └── core/
│   │   │       ├── buildDirectedGraph.ts
│   │   │       ├── computeSubwayScene.ts
│   │   │       ├── parsePayload.ts
│   │   │       └── filterPaths.ts
│   │   └── ...
│   ├── package.json
│   └── vite.config.ts
│
├── traceblast/                    # VS Code Extension
│   ├── src/
│   │   └── extension.ts           # Extension entry point
│   ├── dist/
│   │   └── extension.js           # Compiled output
│   ├── package.json
│   └── esbuild.js
│
├── trace-cli/                     # Node.js CLI
│   ├── index.js                   # CLI entry (commander + axios + chalk)
│   └── package.json
│
└── traceblast.py                  # Root Python helper script

💻 Local Setup Guide

Follow all four phases in order.

Phase 0 — Install Prerequisites

🍎 macOS

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js and Python
brew install node python@3.11 git

🪟 Windows

Install Git, Node.js LTS, and Python 3.11+ — check "Add Python to PATH" during the Python installer.

🐧 Linux (Ubuntu / Debian)

sudo apt update
sudo apt install nodejs npm python3 python3-venv python3-pip git

Phase 1 — Clone the Repository

git clone https://github.com/AA-KH/Trace.git
cd Trace

Phase 2 — Analysis Engine (Python / Flask)

cd Task12

1. Create and activate a virtual environment

# macOS / Linux
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate

2. Install Python dependencies

pip install flask networkx requests

3. (Optional) Install Tier 3 signal tools

Semgrep enables taint/sink analysis. Jelly or js-callgraph enables function-level call graph reachability. Both are optional — the engine degrades gracefully to Tier 1 without them.

# Semgrep
pip install semgrep

# js-callgraph (fallback call-graph backend)
npm install -g js-callgraph

4. (Optional) Set your GitHub token

The fix-commit signal fetches patch diffs from GitHub. Without a token, requests are rate-limited to 60/hour.

export GITHUB_TOKEN=ghp_your_token_here

5. Start the engine

python app.py

✅ The engine is live at http://localhost:5050. Visit http://localhost:5050/health to confirm tier detection and available signals.

Phase 3 — Subway Visualizer (React / Vite)

Open a new terminal:

cd kdbdfvh
npm install
npm run dev

✅ The visualizer is live at http://localhost:5173. Point it at http://localhost:5050 using the API URL input in the UI.

Phase 4 — CLI

Open another terminal:

cd trace-cli
npm install

# Run an analysis against the local engine
node index.js --url http://localhost:5050/analyze --payload payload.json

Phase 5 — VS Code Extension (Development Mode)

Open a new terminal:

cd traceblast
npm install
npm run compile    # or: npm run watch

Then press F5 in VS Code to launch the Extension Development Host.

Running on a Physical Device / Remote Server

If your frontend is running on a device that cannot reach localhost, update the API URL in the visualizer's URL input to your machine's local IP address, and start the Flask server with:

python app.py --host 0.0.0.0 --port 5050

Find your local IP with ipconfig getifaddr en0 (macOS), ipconfig (Windows), or hostname -I (Linux).

🛠 Troubleshooting

Error	Fix
`ModuleNotFoundError: flask`	Activate your virtual environment (`source venv/bin/activate`) and run `pip install flask networkx`
`Command not found: python` (Windows)	Re-run the Python installer → Modify → enable "Add Python to PATH"
Tier stays at 1 even with Semgrep installed	Confirm `semgrep` is on your PATH inside the virtual environment: `which semgrep`
Call-graph signal returns `backend_used: "none"`	Install `js-callgraph` globally: `npm install -g js-callgraph`
GitHub rate-limit errors in fix-commit signal	Set `GITHUB_TOKEN` environment variable
Vite dev server CORS error	Ensure the Flask engine is running with `--host 0.0.0.0` and the API URL in the UI matches exactly
`npm install` fails in `kdbdfvh`	Try `npm install --legacy-peer-deps`

🗺️ Roadmap

👥 Team

Name	Role
Saksham Sood	Backend Engine, Orchestration & Integration
Aaradhya Khanna	Signal Architecture & OSV / GitHub API Integration
Sameer Garg	Frontend Visualizer & VS Code Extension
Sourabh Bansal	CLI, Testing & DevOps

📄 License

This project was built for the Hack Helix Hackathon 2026 and is shared for educational and demonstration purposes only.

Made with 🔍 and way too many CVEs by QuadCore

TraceBlast — Don't just scan. Understand.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
__pycache__		__pycache__
analytical_engine		analytical_engine
dependencies_extractor		dependencies_extractor
traceblast		traceblast
visualizer		visualizer
.DS_Store		.DS_Store
README.md		README.md
requirements.txt		requirements.txt
traceblast.py		traceblast.py
verify-traceblast-setup.js		verify-traceblast-setup.js

Folders and files

Latest commit

History

Repository files navigation

Table of Contents

🚨 Problem Statement

💡 Solution Overview

🧬 Core Features

🔍 Six-Signal Exploitability Model

🚫 Negative Detection — The Feature No One Else Has

👻 Phantom Dependency Pruning

🔬 Fix-Commit Diff Analysis

🗺️ Subway-Map Visualizer

🧩 VS Code Extension

⌨️ CLI

🧠 System Architecture

Signal Registry

📐 The Scoring Model

Formula

Hard Gates

Risk Labels

🔌 API Reference

POST /analyze

GET /health

📂 Project Structure

💻 Local Setup Guide

Phase 0 — Install Prerequisites

Phase 1 — Clone the Repository

Phase 2 — Analysis Engine (Python / Flask)

Phase 3 — Subway Visualizer (React / Vite)

Phase 4 — CLI

Phase 5 — VS Code Extension (Development Mode)

Running on a Physical Device / Remote Server

🛠 Troubleshooting

🗺️ Roadmap

👥 Team

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /analyze`

`GET /health`

Packages