DevGreick/VulnHunter

你的依赖中隐藏着秘密。VulnHunter 能帮你找出它们。
由 AI 驱动进行分类的离线漏洞扫描器。无需云服务，无 API 调用，数据绝不会离开你的本机。

English · Português

文档 · 快速开始 · AI 分类

## 🇺🇸 English ### VulnHunter 的独特之处 大多数漏洞扫描器会将你的依赖树发送到云服务。而 VulnHunter 完全在本地执行所有操作： - **扫描 7 个生态系统：** Python、Node.js、Go、Rust、Java、PHP、Ruby - **通过 Ollama 进行 AI 分类：** 本地 LLM 会读取你的代码，并告诉你哪些 CVE 在你的上下文中是真正可被利用的 - **初始设置后零网络需求：** 适用于隔离网络、政府和银行环境 - **保障机密安全：** API 密钥存储在你的操作系统密钥环中，从不保存在配置文件里 ### 快速开始 ``` # Install (global, recommended) uv tool install vulnhunter # Or via pip pip install vulnhunter # Interactive setup (detects Ollama, configures AI, sets language) vulnhunter init # Scan your project vulnhunter scan . # Scan with AI triage vulnhunter scan . --ai-triage ``` 就是这样。可在任何目录下运行，无需虚拟环境。 ### AI 分类 常规扫描器会直接吐出一堆 CVE 列表，让你自己去猜。VulnHunter 的 AI 分类功能会读取你的实际源代码，将其与每个 CVE 进行关联，并回答那个最关键的问题：**这个漏洞在我的代码中可达吗？** ``` vulnhunter scan . --ai-triage ``` ``` ╭──────────────── AI Triage Results ────────────────╮ │ CVE │ Package │ Risk │ Action │ ├────────────────┼──────────┼──────────┼─────────────┤ │ CVE-2023-XXXX │ flask │ HIGH │ Upgrade now │ │ CVE-2023-YYYY │ requests │ LOW │ Not exposed │ ╰────────────────┴──────────┴──────────┴─────────────╯ ``` 完全通过 [Ollama](https://ollama.com) 在你的本机上运行。推荐的模型： | 模型 | 使用场景 | |---|---| | `phi3:3.8b` | 快速分类，资源消耗低 | | `mistral` | 速度与准确性的最佳平衡 | | `llama3:8b` | 深度分析，效果最好 | ### 设置向导 `vulnhunter init` 会启动一个带有可交互选择菜单的向导（防误输）： - 检测你的系统语言（EN/PT-BR） - 查找运行中的 Ollama 及可用模型 - 允许你从包含大小和层级信息的列表中选择模型 - 将你的 NVD API 密钥安全地存储在操作系统密钥环中 ### 支持的生态系统 | 生态系统 | 文件 | 传递依赖 (Transitive Deps) | |---|---|---| | **Python** | `requirements.txt` · `Pipfile.lock` · `poetry.lock` · `uv.lock` | `pipdeptree` | | **Node.js** | `package-lock.json` · `yarn.lock` · `pnpm-lock.yaml` | `npm ls` | | **Go** | `go.sum` · `go.mod` | `go mod graph` | | **Rust** | `Cargo.lock` | 内置 | | **Java** | `pom.xml` · `build.gradle` | `mvn dependency:tree` | | **PHP** | `composer.lock` | `composer show` | | **Ruby** | `Gemfile.lock` | `bundle list` | ### 数据来源 | 来源 | 角色 | 覆盖范围 | |---|---|---| | **OSV.dev** (Google) | 主要 | PyPI、npm、Maven、Packagist、RubyGems、Go | | **NVD** (NIST) | 备用 | 基于所有生态系统中的 CPE 进行匹配 | 数据库通过 GitHub Actions 每周更新。一次下载，永久扫描： ``` vulnhunter db download # Pre-built database (fastest) vulnhunter db update # Build from OSV/NVD sources vulnhunter db info # Check database stats ``` ### 输出格式 **表格：** 带有按严重性分组功能的彩色终端输出（默认） **JSON：** 机器可读报告 ``` vulnhunter scan . -f json -o report.json ``` **SARIF 2.1.0：** GitHub Code Scanning、VS Code SARIF Viewer ``` vulnhunter scan . -f sarif -o results.sarif ``` ### 命令行参考 ``` vulnhunter init Setup wizard vulnhunter scan [PATHS] [OPTIONS] Scan for vulnerabilities --ai-triage Enable AI analysis --model MODEL Override AI model -f, --format [table|json|sarif] Output format -o, --output FILE Save report to file -s, --severity [critical|high|...] Minimum severity filter --ignore-file FILE Path to .vulnignore -v, --verbose Debug logging vulnhunter db update [OPTIONS] Update vulnerability database --ecosystem ECOSYSTEMS Select specific ecosystems --all Download all ecosystems --source [osv|nvd|both] Data source vulnhunter db download Download pre-built database vulnhunter db info Show database stats vulnhunter config View current settings vulnhunter config set-nvd-key Save NVD API key to keyring vulnhunter config remove-nvd-key Remove NVD API key from keyring ``` ### CI/CD 集成 ``` # .github/workflows/vulnhunter.yml name: Security Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install vulnhunter - run: vulnhunter db download - run: vulnhunter scan . -f sarif -o results.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` ### 忽略漏洞 创建一个 `.vulnignore` 文件： ``` # Ignore globally CVE-2023-0001 # Ignore for a specific package CVE-2023-0002 requests # Ignore namespaced packages CVE-2023-0003 guzzlehttp/guzzle ``` ### 安全性 - API 密钥通过 `keyring` 存储在操作系统密钥环中，绝不使用明文 - 无数据泄密。所有的扫描和 AI 分析均在本地进行 - 每个模块均遵循 OWASP 最佳实践 - 输入验证、参数化查询，不使用 `eval`/`exec` - 发现漏洞时退出代码为 `1`。可用作 CI 闸门 ### 已知局限性 - 准确性取决于 OSV/NVD 数据的更新程度。请定期运行 `db update` - CPE 匹配（NVD）可能会对不常见的包名产生误报 - AI 分类仅为建议。请务必手动验证关键发现 - 仅限静态分析。不执行代码或分析运行时行为 ## 🇧🇷 Português

Suas dependências têm segredos. O VulnHunter encontra.
Scanner offline de vulnerabilidades com triagem por IA. Sem cloud, sem chamadas de API, nenhum dado sai da sua máquina.

### O que torna o VulnHunter diferente A maioria dos scanners de vulnerabilidade envia sua árvore de dependências para um serviço na nuvem. O VulnHunter faz tudo localmente: - **Escaneia 7 ecossistemas:** Python, Node.js, Go, Rust, Java, PHP, Ruby - **Triagem com IA via Ollama:** uma LLM local lê seu código e diz quais CVEs são realmente exploráveis no seu contexto - **Zero rede após o setup:** funciona em ambientes air-gapped, governo e bancos - **Segredos protegidos:** chaves de API armazenadas no keyring do sistema, nunca em arquivos de config ### Início Rápido ``` # Instalar (global, recomendado) uv tool install vulnhunter # Ou via pip pip install vulnhunter # Setup interativo (detecta Ollama, configura IA, define idioma) vulnhunter init # Escanear seu projeto vulnhunter scan . # Escanear com triagem por IA vulnhunter scan . --ai-triage ``` Funciona de qualquer diretório, sem virtual environment. ### Triagem com IA Scanners comuns despejam uma lista de CVEs e te deixam adivinhando. A triagem do VulnHunter lê seu código-fonte real, correlaciona com cada CVE e responde a pergunta que importa: **essa vulnerabilidade é alcançável no meu código?** ``` vulnhunter scan . --ai-triage ``` Roda inteiramente na sua máquina via [Ollama](https://ollama.com). Modelos recomendados: | Modelo | Uso | |---|---| | `phi3:3.8b` | Triagem rápida, poucos recursos | | `mistral` | Melhor equilíbrio velocidade/precisão | | `llama3:8b` | Análise profunda, melhores resultados | ### Wizard de Setup `vulnhunter init` abre um wizard interativo com menus selecionáveis (sem erros de digitação): - Detecta o idioma do sistema (EN/PT-BR) - Encontra Ollama rodando e modelos disponíveis - Permite escolher modelo de uma lista com tamanho e tier - Armazena sua API key do NVD com segurança no keyring do sistema ### Ecossistemas Suportados | Ecossistema | Arquivos | Deps Transitivas | |---|---|---| | **Python** | `requirements.txt` · `Pipfile.lock` · `poetry.lock` · `uv.lock` | `pipdeptree` | | **Node.js** | `package-lock.json` · `yarn.lock` · `pnpm-lock.yaml` | `npm ls` | | **Go** | `go.sum` · `go.mod` | `go mod graph` | | **Rust** | `Cargo.lock` | Nativo | | **Java** | `pom.xml` · `build.gradle` | `mvn dependency:tree` | | **PHP** | `composer.lock` | `composer show` | | **Ruby** | `Gemfile.lock` | `bundle list` | ### Fontes de Dados | Fonte | Papel | Cobertura | |---|---|---| | **OSV.dev** (Google) | Primária | PyPI, npm, Maven, Packagist, RubyGems, Go | | **NVD** (NIST) | Fallback | Matching via CPE em todos os ecossistemas | Banco atualizado semanalmente via GitHub Actions. Baixe uma vez, escaneie sempre: ``` vulnhunter db download # Banco pré-construído (mais rápido) vulnhunter db update # Construir a partir das fontes OSV/NVD vulnhunter db info # Ver estatísticas do banco ``` ### Formatos de Saída **Table:** saída colorida no terminal com agrupamento por severidade (padrão) **JSON:** relatório legível por máquina ``` vulnhunter scan . -f json -o report.json ``` **SARIF 2.1.0:** GitHub Code Scanning, VS Code SARIF Viewer ``` vulnhunter scan . -f sarif -o results.sarif ``` ### Referência CLI ``` vulnhunter init Wizard de configuração vulnhunter scan [CAMINHOS] [OPÇÕES] Escanear vulnerabilidades --ai-triage Ativar análise com IA --model MODELO Sobrescrever modelo de IA -f, --format [table|json|sarif] Formato de saída -o, --output ARQUIVO Salvar relatório em arquivo -s, --severity [critical|high|...] Filtro de severidade mínima --ignore-file ARQUIVO Caminho para .vulnignore -v, --verbose Log de debug vulnhunter db update [OPÇÕES] Atualizar banco de vulnerabilidades --ecosystem ECOSSISTEMAS Selecionar ecossistemas específicos --all Baixar todos os ecossistemas --source [osv|nvd|both] Fonte de dados vulnhunter db download Baixar banco pré-construído vulnhunter db info Ver estatísticas do banco vulnhunter config Ver configurações atuais vulnhunter config set-nvd-key Salvar API key do NVD no keyring vulnhunter config remove-nvd-key Remover API key do NVD do keyring ``` ### Integração CI/CD ``` # .github/workflows/vulnhunter.yml name: Security Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install vulnhunter - run: vulnhunter db download - run: vulnhunter scan . -f sarif -o results.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` ### Ignorando Vulnerabilidades Crie um arquivo `.vulnignore`: ``` # Ignorar globalmente CVE-2023-0001 # Ignorar para um pacote específico CVE-2023-0002 requests # Ignorar pacotes com namespace CVE-2023-0003 guzzlehttp/guzzle ``` ### Segurança - Chaves de API no keyring do sistema via `keyring`, nunca em texto puro - Zero exfiltração de dados. Todo scan e análise de IA acontece localmente - Boas práticas OWASP em todos os módulos - Validação de input, queries parametrizadas, sem `eval`/`exec` - Exit code `1` quando vulnerabilidades são encontradas. Use como gate de CI ### Limitações Conhecidas - Precisão depende da atualização dos dados OSV/NVD. Execute `db update` regularmente - Matching por CPE (NVD) pode gerar falsos positivos para pacotes incomuns - Triagem com IA é sugestiva. Sempre valide findings críticos manualmente - Análise estática apenas. Não executa código nem analisa comportamento em runtime ## 许可证 MIT 许可证。详情请见 [LICENSE](LICENSE)。 ## 作者 由 [DevGreick](https://github.com/DevGreick) 构建

标签：AES-256, AI风险缓解, GNU通用公共许可证, Go, LLM评估, MIT许可, Node.js, Ollama, OpenVAS, PHP, Python, Ruby, Ruby工具, Rust, SARIF, StruQ, 人工智能分类, 依赖漏洞扫描, 图数据库, 敏感信息保护, 无后门, 本地大语言模型, 漏洞评估, 知识库, 离线安全扫描, 离线工具, 网络安全, 网络流量审计, 逆向工具, 隐私保护, 隐私安全, 零网络通信