FaultLine

Open-source dependency vulnerability scanner. GitHub URL in, prioritised CVE report out. Built on the GBrain thin-harness / fat-skills pattern. Zero config. No database. Ships as a CLI and a web UI from the same package.

Credit and Context

This project was forked from and directly inspired by GBrain by Garry Tan — a personal knowledge base spec that introduced the thin CLI harness + fat skill files architecture pattern. That pattern proved so clean and composable that we applied it wholesale to a different domain: dependency security scanning.

If you haven't read GBrain, read it first. The architectural reasoning there is the foundation of everything here.

What FaultLine Does

Paste a GitHub repository URL. FaultLine returns a structured vulnerability report — packages ranked by exploitability, not just CVSS score.

The pipeline:

GitHub URL
  → manifest discovery (package-lock.json, requirements.txt, go.sum, Cargo.lock, pom.xml, ...)
  → dependency parser (per-ecosystem, lockfile-preferred)
  → OSV batch query (open-source vulnerability database)
  → EPSS enrichment (exploit probability score, FIRST.org)
  → KEV cross-reference (CISA Known Exploited Vulnerabilities catalogue)
  → triage engine (P0 / P1 / P2 / P3 priority assignment)
  → report (markdown or JSON)

No API keys required. All enrichment sources (OSV, EPSS, KEV) are public and unauthenticated.

Architecture: Thin Harness, Fat Skills

Directly borrowed from GBrain (which borrowed it from GStack).

Thin harness: The CLI and server are pure plumbing — argument parsing, HTTP routing, and command dispatch. They contain no logic about what a vulnerability means or how to triage it.

Fat skills: The intelligence lives in SKILL.md files that an AI coding agent reads at session start. Skills encode the triage heuristics, enrichment workflows, report quality rules, and edge case handling. Editing a skill is editing a markdown file — no recompile, no redeploy.

This separation means:

The harness is stable. It rarely changes.
The skills are the living knowledge. They evolve as threat models evolve.
AI agents (Claude Code, Cursor, Windsurf) can follow skills without custom tooling.
Humans get a fast, Unix-friendly CLI regardless.

Ecosystems Supported

Ecosystem	Preferred manifest	Fallback
npm	`package-lock.json`	`package.json`
PyPI	`Pipfile.lock`	`requirements.txt`
Go	`go.sum`	`go.mod`
Rust	`Cargo.lock`	`Cargo.toml`
Maven	`pom.xml`	`build.gradle`

Lockfiles are always preferred over bare manifests — they capture the full resolved dependency tree, not just direct dependencies.

Priority Triage Model

FaultLine assigns each finding a priority label rather than surfacing raw CVSS scores. The model combines three signals:

Signal	Source	Weight
CVSS base score	OSV / NVD	Moderate
EPSS score	FIRST.org	High
KEV membership	CISA	Critical — always P0

P0 — Actively exploited (KEV-listed) or very high EPSS + critical CVSS. Fix immediately.
P1 — High CVSS + meaningful EPSS. Fix this sprint.
P2 — Moderate severity, low exploit probability. Fix in next cycle.
P3 — Low severity or theoretical only. Awareness only.

The specific weighting formula is private. The principle is: a vulnerability being exploited in the wild today beats a 9.8 CVSS that nobody has ever weaponised.

CLI

# Scan a public GitHub repo
faultline scan https://github.com/owner/repo

# Scan a local manifest file
faultline scan ./package-lock.json

# Output as JSON
faultline scan https://github.com/owner/repo --format json

# Write to file
faultline scan https://github.com/owner/repo --output report.md

# Version
faultline --version

Progress is written to stderr; report output goes to stdout. Pipe-safe.

Web UI

npm start
# → http://localhost:3000

Single-page interface. Paste a GitHub URL, click Scan, get a rendered report in ~10 seconds. Summary bar shows P0/P1/P2/P3 counts with coloured badges. No framework, no build step — a single HTML file rendered server-side via marked.

Stack

Runtime: Node.js 20+ / TypeScript
Server: Express (web UI + /scan API endpoint)
CLI: Commander.js
Manifest fetch: GitHub raw tree API (no auth for public repos)
Vuln data: OSV batch query API
Enrichment: EPSS API (FIRST.org) + CISA KEV JSON feed
No database — all lookups are live API calls. Zero setup, zero migration.

Skills (Fat Markdown)

The skills/ directory contains the operational knowledge of the tool. Each skill is a standalone markdown document that an AI agent reads before acting.

skills/
├── scan/SKILL.md       # Full scan workflow: fetch → parse → query → enrich → triage → report
├── triage/SKILL.md     # Priority assignment heuristics and edge cases
├── report/SKILL.md     # Report quality rules, formatting standards
└── maintain/SKILL.md   # Keeping the tool healthy: API changes, new ecosystems, stale data

Skill files are not included in the public release. They represent the accumulated operational knowledge of the system and are kept private. The architecture pattern — thin harness reads fat skills — is the open contribution.

Repository Structure

faultline/
├── README.md
├── CLAUDE.md               # AI agent instructions (skill locations, build commands, test commands)
├── package.json
├── tsconfig.json
│
├── src/
│   ├── cli.ts              # CLI entrypoint — argument parsing + command dispatch
│   ├── server.ts           # Express web server
│   ├── types.ts            # Shared TypeScript interfaces
│   └── lib/
│       ├── github.ts       # Manifest discovery from GitHub
│       ├── parsers.ts      # Per-ecosystem manifest parsers
│       ├── osv.ts          # OSV batch query + normalisation
│       ├── enrich.ts       # EPSS + KEV enrichment
│       ├── triage.ts       # Priority assignment engine
│       ├── report.ts       # Markdown + JSON report generation
│       └── scan.ts         # Orchestrator — wires the pipeline together
│
├── public/
│   └── index.html          # Single-file web UI
│
├── scripts/
│   └── verify.ts           # Integration verification script
│
├── skills/                 # Fat skill files (private — not in public release)
│   └── ...
│
└── test/
    └── ...                 # Unit tests per module

CLAUDE.md (Pattern, Not Content)

Every repo built on this pattern ships a CLAUDE.md at root. It tells the AI coding agent:

What the project does and its architecture
Where the skill files live and when to read them
Key files and their responsibilities
Build and test commands
What "done" looks like for each workflow

The CLAUDE.md is the contract between the codebase and the agent. Without it, the agent works from inference. With it, the agent works from specification.

Build and Test

# Build
npm run build

# Run tests
npm test

# Integration verification (requires network)
npx ts-node scripts/verify.ts

# Start web server
npm start

# Global install
npm install -g faultline
faultline scan https://github.com/owner/repo

Why This Architecture Works for Security Tooling

The thin harness / fat skills pattern is particularly well-suited to vulnerability scanning because:

The threat landscape changes faster than the pipeline. The OSV → EPSS → KEV pipeline is stable. What changes is how you interpret the results — new exploit types, new CVSS version weightings, new KEV categories. That interpretation lives in skills, not code.
AI agents are better at triage than rule engines. A fixed rule (if cvss > 9.0 then P0) misses context. A skill file can encode nuance: "if EPSS is below 0.01 and there's no KEV entry, deprioritise regardless of CVSS." An agent reading a skill understands that instruction without it being compiled into a decision tree.
Zero-config matters for adoption. No database, no API keys, no Docker. npm install -g faultline and you're scanning in 30 seconds. The GBrain premise — SQLite as a single file you can scp anywhere — maps here to: no persistence at all. The scan is stateless. The report is the artifact.

What's Next

FaultLine's repo is currently private while we stabilise the skill files and triage model. The architectural pattern above — and the build approach that produced it — is the community contribution.

If you build on this pattern, credit GBrain. Garry's spec is the source of the architecture; this is just one application of it.

Timeline

2026-04-05 | GBrain spec published by Garry Tan. Architecture pattern identified as applicable to security scanning.
2026-04-05 | FaultLine spec written, forking GBrain's thin-harness / fat-skills pattern for the dependency vulnerability domain.
2026-04-07 | MVP built task-by-task via Claude Code (T-01 through T-11). All tasks passing.
2026-04-08 | CLI and web UI verified end-to-end. Repo made private. This Gist published as community courtesy.

GenerationUX/FaultLine.md

Select an option

No results found