choom
4b7e9fcbc0
Add project overview, architecture, installation instructions, CLI usage, cost controls, and background on the motivation behind VulscanNervePinch.
13 KiB
▄▄▄ ▄▄
▄▄▄▀████ ▄▄████▄
██████████ ▄████ ████
████▄████▄ ████▀█████
▀████▀████▄ █████▄████
▀████▀████ ▄████▄█████
██████████ ▄████▀██████
████▄█████ ████▀███████
▄▄▄ ▀████ ████▄▄▄█████▄██████ ▄▄▄▄▄ ▄▄▄▄ ████ ▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄
▀█████▄ ████████████████▄████▀ █████ ████ ████▀ █████████████ ████████████ █████████████▄ ██████████████
▀█████ ▀████████████████████ █████ ████ ████ █████▀▀▀▀▀▀▀▀ █████▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀██████ █████▀▀▀▀█████
▀██████ ███████████████████▀ █████ ████ ████ ████ █████ █████ █████ █████
███████▄███▀██████████████ █████ ████ ████ ███████████▄▄ █████ ▄████████████ █████ █████
▀██████████▄▀███████████ █████ ████ ████▄ ▀████████████ █████ ██████████████ █████ █████
███████████▄█████████▀ █████ ████ ████▄ ▀▀▀▀▀▀█████ █████ █████ █████ █████ █████
▀███████████████████ █████▄▄▄▄█████ ████ ▄▄▄▄▄▄▄▄▄████▀ █████▄▄▄▄▄▄▄ █████▄▄▄▄█████ █████ █████
▀███████████████▀ ▀█████████████ ████ █████████████ ████████████ ▀█████████████ █████ █████
██████████████
▀▀▀▀▀▀▀▀▀▀▀▀
██████ █████ ███████████ ███ █████
░░██████ ░░███ ░░███░░░░░███ ░░░ ░░███
░███░███ ░███ ██████ ████████ █████ █████ ██████ ░███ ░███ ████ ████████ ██████ ░███████
░███░░███░███ ███░░███░░███░░███░░███ ░░███ ███░░███ ░██████████ ░░███ ░░███░░███ ███░░███ ░███░░███
░███ ░░██████ ░███████ ░███ ░░░ ░███ ░███ ░███████ ░███░░░░░░ ░███ ░███ ░███ ░███ ░░░ ░███ ░███
░███ ░░█████ ░███░░░ ░███ ░░███ ███ ░███░░░ ░███ ░███ ░███ ░███ ░███ ███ ░███ ░███
█████ ░░█████░░██████ █████ ░░█████ ░░██████ █████ █████ ████ █████░░██████ ████ █████
░░░░░ ░░░░░ ░░░░░░ ░░░░░ ░░░░░ ░░░░░░ ░░░░░ ░░░░░ ░░░░ ░░░░░ ░░░░░░ ░░░░ ░░░░░
Resumable, cost-controlled vulnerability triage. Prioritize first. Analyze second. Validate with purpose.
Overview
VulscanNervePinch is a resumable, cost-controlled vulnerability triage engine.
It isn't a one-shot scanner. It ranks, reviews, and routes: cheaply prioritizing code most likely to contain vulnerabilities, sending only the highest-value files to Claude for focused analysis, and compiling actionable findings into a report that identifies exactly which downstream tool to point where.
The goal is simple: spend less time and money analyzing everything, and more effort investigating what actually matters.
Why Triage Instead of Scanning Everything?
Running a large language model over every file in a repository is slow and expensive. Running dynamic security tools indiscriminately wastes effort on low-value targets.
VulscanNervePinch introduces a prioritization layer between your source code and your security tooling.
A fast, deterministic ranking pass identifies code deserving deeper analysis, allowing more expensive LLM-assisted review to focus on the most promising targets.
How It Works
The engine operates in three stages:
| Stage | Description | API Cost |
|---|---|---|
| 1. RANK | Scores code files against vulnerability classes using language-aware patterns and input-reachability heuristics. | Free |
| 2. RUN | Submits the highest-ranked files to Claude for focused vulnerability review. | Token-based |
| 3. REPORT | Compiles prioritized findings and generates downstream-tool validation guidance. | No additional LLM review |
1. RANK — Find What Matters
The ranking engine evaluates code files using language-specific signals and an input-reachability heuristic.
Each file receives vulnerability-class-specific scores to help prioritize review.
No API calls are required.
2. RUN — Focused LLM Analysis
The highest-ranked files are submitted to Claude individually for analysis.
Findings include:
- Vulnerability classification — Relevant OWASP category and CWE.
- Validation pointer — The endpoint, parameter, or function requiring investigation.
- Recommended tools — Downstream security tools appropriate to the vulnerability class.
- Supporting analysis — Context for assessing and validating the potential vulnerability.
Analysis is resumable, allowing interrupted sessions to continue without repeating completed work.
3. REPORT — Turn Findings Into Action
The reporting engine organizes findings according to severity × effort-to-fix.
Each finding includes a validation playbook identifying the appropriate downstream security tool and where to direct further investigation.
AI-generated findings are leads requiring independent validation, not confirmed vulnerabilities.
Architecture & Configuration
The engine is driven by three reusable registries and one application-specific configuration block.
| Component | Purpose |
|---|---|
LANGUAGE_PROFILES |
Language-aware analysis patterns |
VULN_CLASSES |
Vulnerability classes and detection criteria |
TOOLS |
Downstream security tool registry |
TARGET_PROFILE |
Application-specific settings |
To analyze another project, update TARGET_PROFILE. The core engine and reusable registries remain unchanged.
Quick Start
Prerequisites
- Python 3
- An Anthropic API key
- A repository you are authorized to analyze
Installation
pip install requests
Set your Anthropic API key:
Linux / macOS:
export ANTHROPIC_API_KEY="your-api-key"
PowerShell:
$env:ANTHROPIC_API_KEY = "your-api-key"
Never commit API keys or other credentials to the repository.
Commands
1. View available vulnerability classes and tools
python VulscanNervePinch.py catalog
2. Rank repository files (free, no API calls)
python VulscanNervePinch.py rank --repo /path/to/repo
3. Check the analysis queue and API spend
python VulscanNervePinch.py status
4. Preview an analysis and estimate its cost
python VulscanNervePinch.py run --top 10 --dry-run
5. Analyze the ten highest-ranked files
python VulscanNervePinch.py run --top 10
Interrupted analysis automatically resumes from saved progress.
6. Generate the final report
python VulscanNervePinch.py report
Cost Control
VulscanNervePinch provides controls to manage LLM usage and avoid unnecessary API expenditure.
| Feature | Usage | Description |
|---|---|---|
| Dry Run | run --dry-run |
Estimates tokens and cost before analysis |
| Spending Cap | run --max-cost 5.00 |
Stops before exceeding the configured dollar cap |
| Model Selection | run --model <model> |
Selects the Claude model used for analysis |
| Top-N Selection | run --top 10 |
Restricts analysis to the highest-ranked files |
| Automatic Resume | run |
Continues from saved progress rather than repeating completed files |
Supported Model Options
python VulscanNervePinch.py run --model haiku-4-5
python VulscanNervePinch.py run --model sonnet-4-6
python VulscanNervePinch.py run --model opus-4-8
Available model identifiers and pricing are subject to Anthropic API support.
Resumable Analysis
Progress is persisted to a manifest after each analyzed file.
If the process is interrupted, subsequent runs continue from the saved state.
This allows large reviews to be performed across multiple sessions while avoiding unnecessary repeat analysis.
Responsible Use
VulscanNervePinch performs static review and security-tool routing only. It does not exploit vulnerabilities.
Its reports recommend downstream validation tools, such as sqlmap, dalfox, and commix, and identify potential targets for further investigation.
Only conduct testing against systems you own or are explicitly authorized to assess.
Important Limitations
- Findings are AI-assisted and may contain false positives or false negatives.
- LLM reviews are performed on individual files, potentially limiting cross-file context.
- Vulnerability classifications and severity assessments require human verification.
- Recommended validation steps are not proof that a vulnerability exists.
- Findings should be independently confirmed before remediation decisions or disclosure.
This tool is intended to support authorized security assessment workflows, not replace professional judgment.
Why I Built It
VulscanNervePinch was inspired by a talk from Nicholas Carlini, a security researcher at Anthropic known for his work in adversarial machine learning and vulnerability research. He demonstrated how LLMs are already finding and exploiting serious vulnerabilities in software like Ghost CMS and the Linux kernel.
I've been using LLMs to help solve CTF challenges for a while now, so their potential for offensive security wasn't exactly news to me. What caught my attention was the scale of what Carlini was demonstrating, and just how quickly these capabilities are improving.
His talk got me thinking about what that means for defenders. We already know attackers are going to take advantage of this technology, and the models are only getting better. But why wait for the next generation? The tools we have today are already capable of doing meaningful vulnerability research.
That was the push I needed to actually build something.
I wanted a practical way to put LLMs to work finding vulnerabilities in open-source software. The biggest constraint was cost. I couldn't afford to have Claude exhaustively review every file in every repository, so I built VulscanNervePinch to prioritize the most promising code and spend my API budget where it would have the most impact.
Now I regularly use it to investigate potential vulnerabilities in open-source projects, validate findings, and work toward getting them fixed.
My thinking is pretty simple: if AI is making it cheaper and easier to find vulnerabilities, I want to use that same advantage to help close as many security gaps as I can afford to close.
License
See LICENSE for licensing information.