juanmaalt/dep_shield

# dep_shield 一个 Python 依赖漏洞扫描器，使用 OSV 数据库检测项目依赖中的已知 CVE，并提供 AI 驱动的影响分析，以评估每个漏洞对您特定代码库的影响。 ## 工作原理 ``` requirements.txt ↘ dependency list → OSV API → vulnerabilities pyproject.toml ↗ ↓ Python files → import scanner → code usage ↓ (--analyze only, skipped if not imported) ↓ LLM impact analysis ↓ ChromaDB (RAG vector store) ``` 1. 发现并解析 `requirements.txt` 和/或 `pyproject.toml`（PEP 621 和 Poetry 格式）以提取包名和版本；跨文件的重复项会被去重 2. 针对每个依赖查询 OSV API 以查找已知 CVE 3. 对于每个存在漏洞的依赖，扫描所有 `.py` 文件以检测 import 语句和使用位置 4. 如果设置了 `--analyze` 且包已被导入，则从 ChromaDB 检索相似的过往 CVE，并使用 CVE 详情 + import 上下文调用 GPT-4o-mini；如果包未在任何地方导入，则跳过 LLM 调用并将风险报告为 `NONE` 5. 显示带有严重性颜色编码的结果和可选的 LLM 建议 6. 将分析过的 CVE 持久化到 ChromaDB 以用于未来的相似性查找 7. 如果发现任何漏洞则返回退出码 `1`，如果项目干净则返回 `0` ### 忽略的目录 import 扫描器会跳过 `.venv`、`venv`、`__pycache__`、`.git`、`node_modules`、`.eggs`、`build` 和 `dist`。 ### 风险等级 | Level | Meaning | |---|---| | `HIGH` | import 语句直接引用了 CVE 中指名的易受攻击函数或功能 | | `MEDIUM` | 包已被导入，但没有明确证据表明使用了易受攻击的功能 | | `LOW` | 包仅在测试、开发工具或可选依赖中被导入 | | `NONE` | 包未被导入，或者 CVE 的条件在当前代码库中不成立 | | `UNKNOWN` | API 错误或速率限制导致分析无法进行 | ## 安装要求 - Python 3.12 或更高版本 - `uv` 包管理器 - OpenAI API 密钥（`--analyze` 模式必需） ``` git clone cd dep_shield uv sync ``` ## 配置 在项目根目录的 `.env` 文件中设置以下环境变量： ``` OPENAI_API_KEY=sk-... ``` | Setting | Default | Description | |---|---|---| | `OPENAI_API_KEY` | *（`--analyze` 必需）* | OpenAI API 密钥 | | Embedding model | `text-embedding-3-small` | 用于 CVE embeddings 的 OpenAI 模型 | | Analysis model | `gpt-4o-mini` | 用于影响分析的 OpenAI 模型 | | Vector store path | `~/.dep_shield/chroma/` | 本地 ChromaDB 持久化存储路径 | | Similarity threshold | `0.35` | 检索相似过往 CVE 的最小余弦距离 | | Top-k similar CVEs | `3` | 用作上下文的过往分析数量 | ## 用法 ``` # 扫描项目目录（自动检测 requirements.txt 和/或 pyproject.toml） uv run dep_shield # 通过 AI 驱动的影响分析进行扫描 uv run dep_shield --analyze ``` **示例：** ``` uv run dep_shield . uv run dep_shield ./requirements.txt --analyze uv run dep_shield ./pyproject.toml --analyze uv run dep_shield /path/to/project -a ``` ## 项目结构 ``` src/ ├── cli.py # Typer CLI entry point ├── parsers/ │ ├── requirements.py # requirements.txt parser │ └── pyproject.py # pyproject.toml parser (PEP 621 + Poetry) ├── scanners/ │ ├── models.py # Vulnerability and CodeUsage dataclasses │ ├── osv.py # OSV API client (async httpx) │ └── code_scanner.py # Python import scanner └── rag/ ├── analyzer.py # LLM-based impact analysis ├── client.py # OpenAI client initialization ├── embeddings.py # Embedding generation ├── models.py # Pydantic models (ImpactAnalysis, SimilarCVE) └── store.py # ChromaDB store management tests/ ├── parsers/ │ ├── test_requirements.py │ └── test_pyproject.py └── scanners/ ├── test_osv.py └── test_code_scanner.py ``` ## 运行测试 ``` uv sync --group dev uv run pytest ``` ## 安全说明 * `.env` 文件已通过 `.gitignore` 从版本控制中排除。切勿将您的 `OPENAI_API_KEY` 直接提交到源文件中。 * 只有 import 语句会与 LLM 共享，而不会共享您的业务逻辑。模型看到的是类似 `import requests` 或 `from flask import Flask` 的内容，永远不会看到函数体。

标签：AI代码分析, ChromaDB, CVE, DevSecOps, DNS 解析, GPT-4o-mini, Import扫描, LLM, OSV, Petitpotam, pyproject.toml, Python, RAG, requirements.txt, Unmanaged PE, Vercel, 上游代理, 云安全监控, 代码安全, 依赖扫描, 依赖管理, 向量数据库, 对称加密, 数字签名, 文档安全, 无后门, 模型提供商, 漏洞枚举, 自动化审计, 软件开发工具包, 运行时操纵, 逆向工具, 静态分析