{"id":49774428,"url":"https://github.com/vinsoc-cyber/vulnhunterx","last_synced_at":"2026-06-12T14:00:32.691Z","repository":{"id":354001693,"uuid":"1148534151","full_name":"vinsoc-cyber/VulnHunterX","owner":"vinsoc-cyber","description":"A Python framework for combining static analysis with LLM-based bug verification","archived":false,"fork":false,"pushed_at":"2026-06-06T15:07:05.000Z","size":1502,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T15:22:49.662Z","etag":null,"topics":["codeql","fuzzing","llm","semgrep","static-analysis","vulnerability","vulnerability-verification"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vinsoc-cyber.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-03T04:25:23.000Z","updated_at":"2026-06-06T15:07:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vinsoc-cyber/VulnHunterX","commit_stats":null,"previous_names":["vinsoc-cyber/vulnhunterx"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vinsoc-cyber/VulnHunterX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinsoc-cyber%2FVulnHunterX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinsoc-cyber%2FVulnHunterX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinsoc-cyber%2FVulnHunterX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinsoc-cyber%2FVulnHunterX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vinsoc-cyber","download_url":"https://codeload.github.com/vinsoc-cyber/VulnHunterX/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinsoc-cyber%2FVulnHunterX/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34247461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codeql","fuzzing","llm","semgrep","static-analysis","vulnerability","vulnerability-verification"],"created_at":"2026-05-11T14:26:30.610Z","updated_at":"2026-06-12T14:00:32.677Z","avatar_url":"https://github.com/vinsoc-cyber.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VulnHunterX\n\n**SAST (CodeQL, Semgrep, OpenGrep) + fuzzing + LLM vulnerability hunting and verification**\n\nA Python framework that pairs static analysis with multi-turn LLM verification to suppress false positives in SAST findings, implementing the *Vulnhalla* methodology of guided-question, evidence-anchored triage.\n\n![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)\n![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)\n![SAST](https://img.shields.io/badge/SAST-CodeQL%20%7C%20Semgrep%20%7C%20OpenGrep-orange.svg)\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Quick Start](#quick-start)\n- [Pipeline Stages](#pipeline-stages)\n- [CLI Reference](#cli-reference)\n- [Python API](#python-api)\n- [Rules \u0026 Coverage](#rules--coverage)\n- [Configuration](#configuration)\n- [Project Structure](#project-structure)\n- [Development](#development)\n- [Benchmark](#benchmark)\n- [References](#references)\n\n---\n\n## Overview\n\nSAST engines deliberately over-approximate — they flag every program point that *might* be vulnerable. The dominant cost of running them in production is not analysis time but human triage. VulnHunterX automates triage by feeding each SARIF finding to an LLM that must answer a rule-specific checklist of evidence-anchored questions, request additional code context when needed (multi-turn), and emit a structured verdict with a confidence score.\n\n```\nSource  ──\u003e  Static Analysis  ──\u003e  SARIF Findings  ──\u003e  LLM Verification  ──\u003e  Verdicts\n(prepare)    (CodeQL/Semgrep/      (rule, file,          (guided questions,      (TP/FP/NMD +\n              OpenGrep)             line, severity)       multi-turn context)     confidence)\n```\n\nThe **Vulnhalla** methodology forces the LLM to:\n\n- answer rule-specific guided questions *before* committing to a verdict,\n- request callers, structs, globals, free-sites, etc. as needed via a fixed context vocabulary,\n- reason across multiple turns rather than pattern-match a single snippet.\n\n### Key features\n\n| Feature | Description |\n|---|---|\n| **Languages** | C, C++, Python, JavaScript, PHP, Java, Go |\n| **SAST engines** | CodeQL, Semgrep, OpenGrep (`--tool codeql\\|semgrep\\|opengrep\\|both\\|all`) |\n| **Security rule profiles** | `standard` → `extended` → `maximum` → `extended-registry` → `full` (see [config/RULES.md](config/RULES.md)) |\n| **Guided questions** | 316 rule-specific templates across 6 per-language banks plus a fallback |\n| **LLM providers** | OpenAI, Anthropic, Ollama (local or [Ollama Cloud](https://ollama.com)) — via [LiteLLM](https://github.com/BerriAI/litellm) |\n| **Multi-turn verification** | Dynamic context expansion (callers, structs, globals, macros, free-sites) |\n| **Inputs** | Git URL, local directory, or batch list (`repos.yaml`) |\n| **Reports** | Markdown, EN/VI, executive summary + per-finding detail |\n| **Fuzz confirmation** | libFuzzer / Atheris / Jazzer / Jazzer.js / php-fuzzer harness generation + crash triage |\n| **Benchmarking** | Precision/recall across 6 ground-truth datasets (see [benchmarks/README.md](benchmarks/README.md)) |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.12+\n- [CodeQL CLI 2.15+](https://codeql.github.com/docs/codeql-cli/getting-started-with-the-codeql-cli/)\n- [Semgrep](https://semgrep.dev/docs/getting-started/) and/or [OpenGrep](https://github.com/opengrep/opengrep#installation) — optional\n- An LLM provider: OpenAI, Anthropic, or local Ollama\n\n### Install\n\n```bash\ngit clone https://github.com/vinsoc-cyber/VulnHunterX.git \u0026\u0026 cd VulnHunterX\nuv venv --python python3.12 .venv \u0026\u0026 source .venv/bin/activate\nuv pip install -e \".[dev]\"\n\ncp env.example .env       # add OPENAI_API_KEY / ANTHROPIC_API_KEY / OLLAMA_API_BASE\nvuln-hunter-x check-env   # verify toolchain\n```\n\n\u003e Requires [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).\n\u003e Plain `python3.12 -m venv .venv` + `pip install -e \".[dev]\"` also works if you'd rather not install `uv`.\n\n### First run\n\nThe fastest path is one of the per-language example scripts under [examples/](examples/), which clone a real-world target, a vulnerable target, and run the full pipeline against both so the FP-vs-TP contrast is visible:\n\n```bash\npython examples/pipeline_python.py\n# Common flags: --dry-run, --skip-clone, --api ; C/C++ scripts also support --fuzz\n```\n\n| Script | Language | Real-world | Vulnerable |\n|---|---|---|---|\n| `pipeline_python.py` | Python | pyyaml | dvpwa |\n| `pipeline_javascript.py` | JavaScript | minimist | nodegoat |\n| `pipeline_c.py` | C | c-ares | dvcp |\n| `pipeline_cpp.py` | C++ | re2 | insecure-coding-examples |\n| `pipeline_java.py` | Java | commons-collections | webgoat |\n| `pipeline_php.py` | PHP | monolog | dvwa |\n| `pipeline_go.py` | Go | gin | govwa |\n\n### Or run stages directly\n\n```bash\nvuln-hunter-x prepare --repo pyyaml\nvuln-hunter-x analyze --repo pyyaml --profile extended\nvuln-hunter-x verify  --repo pyyaml --limit 5\nvuln-hunter-x report  --repo pyyaml --lang python\n```\n\n### Add your own repository\n\n```bash\n# Single-shot from URL\nvuln-hunter-x prepare --url https://github.com/org/app.git --lang python\n\n# Existing checkout\nvuln-hunter-x prepare --local-path /path/to/app --lang python --name app\n\n# Compiled languages need a build command\nvuln-hunter-x prepare --url https://github.com/org/lib.git --lang c --build-command \"make\"\n```\n\nOr list it under `repos:` in [config/repos.yaml](config/repos.yaml) and run `vuln-hunter-x prepare --repo \u003cname\u003e`.\n\n### Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `CodeQL CLI not found` | Add to `PATH` or set `CODEQL_PATH` in `.env` |\n| `Semgrep CLI not found` | Set `SEMGREP_PATH` in `.env` |\n| `OpenAI API key not configured` | Add `OPENAI_API_KEY=sk-...` to `.env` |\n| `could not resolve module cpp` | `codeql pack install config/queries/tools/cpp` |\n| `Database is already finalized` | Normal — analysis proceeds automatically |\n\n---\n\n## Pipeline Stages\n\n| # | Command | Input | Output |\n|---|---|---|---|\n| 1 | `prepare` (alias `clone`) | URL / local path / `repos.yaml` | Source + CodeQL DB + context CSVs |\n| 2 | `analyze` | CodeQL DB and/or source tree | SARIF findings |\n| 3 | `verify` | SARIF + context CSVs | JSON verdicts + reasoning |\n| 4 | `report` | Verification results | Markdown report (EN/VI) |\n| 5 | `build-sanitized` | Verified C/C++ findings | ASan/UBSan build manifest |\n| 6 | `extract-fuzz-context` | C/C++ source | Function signatures for harness generation |\n| 7 | `generate-fuzz-drivers` | Fuzz context + sanitized build | libFuzzer / Atheris / Jazzer harnesses |\n| 8 | `fuzz-run` | Compiled harnesses | Crash files + triage results |\n\n| Goal | Required stages | Optional |\n|---|---|---|\n| Static analysis only | 1, 2 | — |\n| LLM verification | 1, 2, 3 | 4 (`report`) |\n| Fuzz confirmation | 1, 2, 3, 5, 6, 7, 8 | 4 (`report`) |\n\nStages 2–3 accept `--local-path` to operate directly on an arbitrary directory.\n\n---\n\n## CLI Reference\n\n### `check-env`\n\n```bash\nvuln-hunter-x check-env\n```\n\nVerifies CodeQL CLI, Semgrep/OpenGrep, and LLM provider keys.\n\n### `prepare` *(alias: `clone`)*\n\nClone a repository, create a CodeQL database, and extract context CSVs (functions, callers, structs, globals, macros, classes).\n\n```bash\nvuln-hunter-x prepare                                                 # batch from repos.yaml\nvuln-hunter-x prepare --url https://github.com/org/repo.git --lang go\nvuln-hunter-x prepare --local-path /path/to/repo --lang python\nvuln-hunter-x prepare --skip-clone --skip-db --force --repo libucl    # re-extract context only\n```\n\n| Option | Description | Default |\n|---|---|---|\n| `--config PATH` | Path to `repos.yaml` | — |\n| `--url URL` | Git URL to clone | — |\n| `--local-path PATH` | Existing local directory | — |\n| `--name NAME` | Repository name (auto-derived if omitted) | — |\n| `--lang LANG` | Language — required with `--url` or `--local-path` | — |\n| `--build-command CMD` | Build command for compiled languages | — |\n| `--repo NAME` | Filter to one repository (config mode) | All |\n| `--skip-clone` / `--skip-db` / `--skip-context` | Skip stages | false |\n| `--backend {auto,codeql,treesitter}` | Context extraction backend | `auto` |\n| `--ask-llm` | Ask the LLM for help if the build fails | false |\n| `-f, --force` | Force re-extraction of context CSVs | false |\n| `--dry-run` | Preview actions | false |\n\n#### Context extraction backends (`--backend`)\n\nContext CSVs (functions, callers, structs/classes, globals, macros) feed multi-turn LLM verification. Two backends produce them:\n\n| Backend | When to use | Notes |\n|---|---|---|\n| `auto` *(default)* | Most workflows | CodeQL where a database was built; tree-sitter as fallback for repos where the DB build failed |\n| `codeql` | Highest precision | Requires a valid CodeQL DB. Semantic-level extraction; adds C/C++-specific context (`free_sites`, `destructors`, `field_writes`) used by memory-safety guided questions |\n| `treesitter` | No CodeQL DB, quick iteration | Syntactic extraction — fast, no DB build. Covers C, C++, Python, JavaScript, Java, PHP, Go; skips the C/C++-specific context types listed above |\n\nTree-sitter grammars (`tree-sitter-c/cpp/python/javascript/java/php/go`, pinned to `\u003e=0.23,\u003c1.0`) ship with the standard `pip install -e .` — no extra setup. Both backends emit the same CSV layout, so downstream stages (`analyze`, `verify`, `report`) work identically regardless of backend. `vuln-hunter-x check-env` verifies tree-sitter availability alongside CodeQL.\n\n### `analyze`\n\nRun CodeQL, Semgrep, and/or OpenGrep against a prepared repo or a local path.\n\n```bash\nvuln-hunter-x analyze --repo libucl\nvuln-hunter-x analyze --tool all --repo c-ares --profile full\nvuln-hunter-x analyze --tool semgrep --local-path /path/to/project --lang python --profile extended\n```\n\n| Option | Description | Default |\n|---|---|---|\n| `--tool {codeql,semgrep,opengrep,both,all}` | Analyzer(s) | `codeql` |\n| `--profile {standard,extended,maximum,extended-registry,full}` | Rule profile (see [config/RULES.md](config/RULES.md)) | `standard` |\n| `--category CAT` | Filter by security category (repeatable) | All |\n| `--local-path PATH` | Analyze a local directory | — |\n| `--name NAME` | Repository name | auto-derived |\n| `--semgrep-config CFG` / `--opengrep-config CFG` | Override rule pack(s) | from profile |\n| `--codeql-suite SUITE` | Override CodeQL suite | from profile |\n| `--repo NAME` / `--lang LANG` | Filters | All |\n| `-j, --jobs N` | Parallel CodeQL analyses | 2 |\n| `--json` | Also output findings JSON | false |\n| `-f, --force` | Re-run even if SARIF exists | false |\n| `--dry-run` / `-v` | Preview / verbose | false |\n\n### `verify`\n\nVerify SARIF findings using multi-turn LLM reasoning.\n\n```bash\nvuln-hunter-x verify --repo libucl\nvuln-hunter-x verify --repo c-ares --lang c --category memory-safety\nvuln-hunter-x verify --provider ollama --model ollama/llama3.2 --repo libucl\nvuln-hunter-x verify --local-path /path/to/project --lang python --limit 20\n```\n\n| Option | Description | Default |\n|---|---|---|\n| `--config PATH` | Configuration file | `config/confirm_findings.yaml` |\n| `--local-path PATH` | Verify findings for a local directory | — |\n| `--name NAME` | Repository name | auto-derived |\n| `--repo NAME` / `--lang LANG` | Filters | All |\n| `--sarif PATH` | Process a specific SARIF file | — |\n| `--provider {openai,anthropic,ollama}` | LLM provider | from config |\n| `--model NAME` | Model name | from config |\n| `--temperature F` / `--max-tokens N` | LLM tuning | from config |\n| `--max-iterations N` | Max conversation rounds per finding | 3 |\n| `-j, --jobs N` | Concurrent findings to verify (1 = sequential) | 4 |\n| `--limit N` | Maximum findings to process | Unlimited |\n| `--category CAT` | Filter by category (repeatable, same vocabulary as `analyze`) | All |\n| `--include-tests` | Include findings under `test/`, `tests/` | false |\n| `-v` / `-q` | Verbose / quiet | normal |\n| `--log-file PATH` | Persist LLM conversations | — |\n| `--dry-run` | Preview findings | false |\n\n### `report`\n\nGenerate a markdown report from verification results. `verify` already writes `report.md` and `report_vi.md`; use this to regenerate or change the output path.\n\n```bash\nvuln-hunter-x report --repo c-ares --lang c\nvuln-hunter-x report --results-dir output/c/c-ares/verification_results\nvuln-hunter-x report --repo libucl -o my-report.md --lang-report en\n```\n\n| Option | Description | Default |\n|---|---|---|\n| `--results-dir PATH` | Path to a `verification_results/` directory | auto-discover |\n| `--repo NAME` / `--lang LANG` | Auto-discover by repo and language | — |\n| `-o, --output PATH` | Output path | `report.md` in results dir |\n| `--lang-report {en,vi,all}` | Report language(s) | `all` |\n\nReport sections: executive summary · findings overview (before/after verdicting) · severity breakdown · CWE distribution · per-finding detail (verdict, confidence, reasoning, dataflow).\n\n### Fuzz stages (C/C++ only)\n\n```bash\nvuln-hunter-x build-sanitized       --repo libucl\nvuln-hunter-x extract-fuzz-context  --repo libucl\nvuln-hunter-x generate-fuzz-drivers --repo libucl --build --llm-fix\nvuln-hunter-x fuzz-run              --repo libucl --triage\n```\n\nRun any subcommand with `--help` for full options.\n\n### `info`\n\n```bash\nvuln-hunter-x info\n```\n\nPrints the resolved configuration — provider, model, paths.\n\n---\n\n## Python API\n\n```python\nfrom pathlib import Path\nfrom vuln_hunter_x import VerificationEngine\nfrom vuln_hunter_x.reporting.markdown import MarkdownReportGenerator\n\nengine = VerificationEngine.from_config(\"config/confirm_findings.yaml\")\nresult = engine.verify_sarif(\"output/c/libucl/libucl.sarif\", lang=\"c\", repo_name=\"libucl\")\n\nfor verdict in result.verdicts:\n    print(f\"{verdict.finding.rule_id}: {verdict.verdict} ({verdict.confidence})\")\n\nengine.save_results(result)\nMarkdownReportGenerator().generate(\n    result, Path(\"output/c/libucl/verification_results/report.md\")\n)\n```\n\n---\n\n## Rules \u0026 Coverage\n\n[config/RULES.md](config/RULES.md) is the authoritative inventory — every profile, every custom CodeQL query, every custom Semgrep rule, with CWE tags and severities. Quick summary:\n\n| Metric | Count |\n|---|---|\n| Rule profiles | 5 (`standard` → `full`) |\n| Security categories | 12 |\n| CWE entries in routing map | 123 |\n| Custom CodeQL queries | 73 (C/C++ 21, Java 14, JavaScript 15, Python 12, Go 11) |\n| Custom Semgrep rules | 47 (Python 12, JavaScript 9, Java 7, Go 8, PHP 7, C/C++ 4) |\n| Built-in CodeQL suites | `security-extended` (~200), `security-and-quality` (~400) |\n| Built-in Semgrep universal packs | 8 |\n| Built-in Semgrep per-language packs | 10 (django, flask, nodejs, gosec, …) |\n| Guided-question templates | 342 across 6 per-language banks + 1 fallback |\n\nCoverage growth from `--profile standard` to `--profile full` is roughly **5×–10×** more rules per scan. Per-language registry packs (`p/django`, `p/gosec`, …) are only applied to matching repos so cross-language scans aren't polluted.\n\nTo add a custom rule:\n\n- **CodeQL** — drop `\u003cname\u003e.ql` into `config/codeql-custom/\u003clang\u003e/src/` with `@id \u003clang\u003e/\u003cname\u003e` matching a guided-question key.\n- **Semgrep** — append a rule to `config/semgrep-custom/\u003clang\u003e.yaml` with `metadata.cwe: [\"CWE-NNN\"]` so CWE-based routing works.\n\nBoth are activated by `--profile full`. Run `python scripts/audit_rule_coverage.py --fail-on-gaps` to verify the wiring.\n\n---\n\n## Configuration\n\nPriority: **CLI args \u003e environment variables \u003e config file \u003e defaults**.\n\n### Environment variables (`.env`)\n\n| Variable | Description |\n|---|---|\n| `OPENAI_API_KEY` | OpenAI API key |\n| `ANTHROPIC_API_KEY` | Anthropic API key |\n| `OLLAMA_API_BASE` | Ollama server URL (`http://localhost:11434` for local, `https://ollama.com` for cloud) |\n| `OLLAMA_API_KEYS` | Ollama Cloud bearer token(s). Comma-separated for a pool (`k1,k2,k3`); 2+ keys enable round-robin rotation with per-key 429 cooldown. Required when `OLLAMA_API_BASE` points at `ollama.com` or the model carries a `:cloud` / `-cloud` tag. |\n| `LLM_PROVIDER` / `LLM_MODEL` | Override default provider / model |\n| `CODEQL_PATH` / `SEMGREP_PATH` / `OPENGREP_PATH` | Tool paths if not on `PATH` |\n\n### LLM / verification settings (`config/confirm_findings.yaml`)\n\n```yaml\nprovider: openai          # openai | anthropic | ollama\nmodel: gpt-4o\ntemperature: 0.2\nmax_tokens: 1500\nmax_iterations: 3         # conversation rounds per finding\n```\n\n### Repository list (`config/repos.yaml`)\n\n```yaml\nrepos:\n  - name: pyyaml\n    url: https://github.com/yaml/pyyaml.git\n    language: python\n\n  - name: libucl\n    url: https://github.com/vstakhov/libucl.git\n    language: c\n    build_command: \"mkdir -p build \u0026\u0026 cd build \u0026\u0026 cmake .. \u0026\u0026 make\"\n```\n\n| Field | Description |\n|---|---|\n| `name` | Short identifier used in output paths |\n| `url` | Git clone URL |\n| `language` | `c` · `cpp` · `python` · `javascript` · `php` · `java` · `go` |\n| `build_command` | Required for C/C++; omit for interpreted languages |\n\n### Guided questions (`config/prompts/`)\n\nRule-specific question banks that force the LLM to reason step-by-step.\n\n| File | Language | Rule sets |\n|---|---|---|\n| `cpp_questions.yaml` | C/C++ | 59 |\n| `python_questions.yaml` | Python | 56 |\n| `javascript_questions.yaml` | JavaScript / TypeScript | 51 |\n| `go_questions.yaml` | Go | 50 |\n| `java_questions.yaml` | Java | 50 |\n| `php_questions.yaml` | PHP | 50 |\n| `default_questions.yaml` | Fallback | 1 |\n\nThe verifier matches each SARIF `ruleId` in three tiers — exact match → prefix/normalized → CWE map — falling back to `default_questions.yaml` only when none hits. See [config/RULES.md § 7](config/RULES.md#7-guided-question-routing).\n\n---\n\n## Project Structure\n\n```\nVulnHunterX/\n├── src/vuln_hunter_x/\n│   ├── cli/           # CLI commands\n│   ├── codeql/        # Database creation, analysis, context extraction\n│   ├── context/       # Heuristic + tree-sitter context extraction\n│   ├── core/          # Types, config, constants\n│   ├── dyntest/       # Language backends for fuzz stages 5–8\n│   ├── fuzz/          # C/C++ fuzz shims\n│   ├── llm/           # LLM client (LiteLLM) and prompt construction\n│   ├── opengrep/      # OpenGrep integration\n│   ├── questions/     # Guided-question loader\n│   ├── reporting/     # Markdown report generation\n│   ├── sarif/         # SARIF parsing\n│   ├── semgrep/       # Semgrep integration\n│   └── verification/  # Multi-turn verification engine\n├── config/\n│   ├── RULES.md                # Authoritative rule inventory\n│   ├── rule_categories.yaml    # Profiles, categories, CWE map\n│   ├── codeql-custom/          # Custom CodeQL queries (full profile)\n│   ├── semgrep-custom/         # Custom Semgrep rules (full profile)\n│   ├── prompts/                # Guided questions + system prompt\n│   ├── queries/                # CodeQL context queries (per language)\n│   ├── confirm_findings.yaml   # LLM and verification settings\n│   └── repos.yaml              # Repository definitions\n├── benchmarks/        # Evaluation framework — see benchmarks/README.md\n├── examples/          # Per-language pipeline scripts\n├── scripts/           # audit_rule_coverage.py, etc.\n├── tests/\n└── output/\n    └── \u003clang\u003e/\u003crepo\u003e/\n        ├── database/              # CodeQL database\n        ├── *.sarif                # SARIF results\n        ├── context/               # Extracted CSVs\n        ├── verification_results/  # Verdict JSON + report.md\n        ├── sanitized_build/       # (C/C++) sanitizer build\n        ├── fuzz_targets/          # (C/C++) harnesses\n        └── fuzz_results/          # (C/C++) crashes\n```\n\n---\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest tests/\nruff check src/\nruff format src/\nmypy src/\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## Benchmark\n\nVulnHunterX ships a standalone benchmark framework comparing the full pipeline against `raw-sast` and ablation baselines on six ground-truth datasets (SecLLMHolmes, Juliet C/C++, DiverseVul, OWASP BenchmarkJava, OWASP BenchmarkPython, RealVuln).\n\n```bash\npython benchmarks/scripts/run_benchmark.py \\\n    --dataset secllmholmes --approach all \\\n    --model gpt-4o-mini --limit 50\n```\n\nFull documentation — datasets, per-dataset playbooks, metrics, resume semantics — lives in [benchmarks/README.md](benchmarks/README.md). The literature review and design-decision rationale are in [benchmarks/RESEARCH.md](benchmarks/RESEARCH.md).\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## References\n\n- [Vulnhalla — CyberArk](https://www.cyberark.com/resources/threat-research-blog/vulnhalla-picking-the-true-vulnerabilities-from-the-codeql-haystack) — original methodology\n- [CodeQL Documentation](https://codeql.github.com/docs/)\n- [Semgrep Documentation](https://semgrep.dev/docs/)\n- [SARIF Specification](https://sarifweb.azurewebsites.net/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinsoc-cyber%2Fvulnhunterx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvinsoc-cyber%2Fvulnhunterx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinsoc-cyber%2Fvulnhunterx/lists"}