HeJiguang/codescan
GitHub: HeJiguang/codescan
结合确定性规则与 LLM 分析的代码安全扫描工具，通过结构化流水线和 MCP 协议为编程智能体提供原生的代码审查能力。
Stars: 18 | Forks: 4
# CodeScan
English | [简体中文](README.zh-CN.md)
针对文件、代码库、Git diffs 和编程智能体的 AI 辅助代码安全扫描。
从确定性规则开始，利用 LLM 分析深化上下文，并通过 MCP 和 Codex skill 暴露扫描器。
[](https://github.com/HeJiguang/codescan/actions/workflows/ci.yml)
## 快速链接
- [为什么选择 CodeScan](#why-codescan)
- [适用人群](#who-this-is-for)
- [5 分钟体验](#try-it-in-5-minutes)
- [快速开始](#quick-start)
- [配合 Codex 使用](#use-with-codex)
- [示例输出](#example-output)
- [参与贡献](#get-involved)
- [路线图](#roadmap)
## 为什么选择 CodeScan
许多 AI 代码扫描器仅仅是粘贴源文件之上的聊天包装器。它们听起来很智能，但输出结果不稳定，难以集成，且在实际工作流中难以信赖。
CodeScan 走了一条更严格的路线：
- 从确定性的基于规则的信号开始
- 使用 LLM 分析来深化上下文和解释
- 强制结构化输出，而不是自由形式的 blob 解析
- 通过 CLI、报告、MCP 工具和 Codex 工作流交付相同的结果模型
CodeScan 专注于审查工作流，在这里确定性检查、结构化发现和智能体集成至关重要。
## 适用人群
目前 CodeScan 对以下人群最有用：
- 希望在合并代码前进行第二轮安全检查的开发者
- 使用 Codex、Cursor 或 Claude 并希望获得结构化安全工具的团队
- 希望拥有轻量级代码库分类工具，而又不想搭建大型平台的维护者
- 对安全规则、AI 辅助分析或原生 MCP 开发者工具感兴趣的贡献者
目前，它最适合作为审查助手和原生智能体扫描层，而不是一个完整的 SAST 平台。
## 5 分钟体验
从以下三项开始：
1. 浏览 [`examples/demo-vulnerable-app`](examples/demo-vulnerable-app) 中的示例固件
2. 打开 [`examples/sample-mcp-result.json`](examples/sample-mcp-result.json) 中的代表性结果
3. 阅读 [示例输出](docs/example-output.md) 中的图文说明
本地运行：
```
pip install -e .
python -m codescan config --provider deepseek --api-key YOUR_API_KEY --model deepseek-chat
python -m codescan dir examples/demo-vulnerable-app --output demo-result.json
```
## 与众不同之处
| 领域 | 当前功能 | 为什么重要 |
| --- | --- | --- |
| `LangChain` 提供商 | 统一 DeepSeek、OpenAI、Anthropic 和兼容 OpenAI 的端点 | 无需重写扫描器即可切换模型 |
| `LangGraph` 工作流 | 将文件分析建模为 `rule_scan -> llm_scan -> merge_and_finalize` | 为 AI 运行时提供真正的流水线，而不是杂乱的提示词 |
| `MCP Server` | 为编程智能体暴露结构化扫描工具 | 让 Codex 和其他 MCP 客户端直接调用 CodeScan |
| `Skill layer` | 提供可安装的 `codescan-review` skill | 指导 Codex 何时扫描以及如何呈现结果 |
| 报告系统 | 生成 HTML / JSON / 文本输出 | 同时适用于人工和自动化 |
| 测试 + CI | 验证运行时、打包、文档和入口点 | 防止代码库退化为原型质量 |
## 架构
```
flowchart LR
A["CLI / GUI"] --> B["CodeScanner"]
A2["MCP Server"] --> B
A3["Codex Skill"] --> A2
B --> C["AIAnalysisService"]
C --> D["providers.py"]
C --> E["chains.py"]
C --> F["workflow.py"]
B --> G["VulnerabilityDB"]
B --> H["report.py"]
F --> I["rule_scan"]
F --> J["llm_scan"]
F --> K["merge_and_finalize"]
```
核心布局：
```
codescan/
├── ai/
│ ├── providers.py
│ ├── prompts.py
│ ├── chains.py
│ ├── workflow.py
│ ├── schemas.py
│ └── service.py
├── scanner.py
├── report.py
├── vulndb.py
├── mcp_server.py
└── __main__.py
skills/
└── codescan-review/
```
## 快速开始
### 1. 克隆
```
git clone https://github.com/HeJiguang/codescan.git
cd codescan
```
### 2. 安装
```
python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
pip install -e .
```
### 3. 配置模型
```
python -m codescan config --show
python -m codescan config --provider deepseek --api-key YOUR_DEEPSEEK_API_KEY --model deepseek-chat
```
### 4. 试用 CLI
```
python -m codescan file /path/to/file.py
python -m codescan dir /path/to/project
python -m codescan git-merge main
```
### 5. 试用 MCP server
```
codescan-mcp --transport stdio
```
## 配合 Codex 使用
标签：Agent, AI辅助分析, CISA项目, Codex, DevSecOps, DLL 劫持, Git Diff扫描, LangChain, LangGraph, LLM, MCP, Python, Unmanaged PE, 上游代理, 代码安全, 大语言模型, 威胁情报, 安全审查, 安全工作流, 开发者工具, 无后门, 模型上下文协议, 源码审计, 漏洞枚举, 编程助手, 轻量级, 逆向工具, 错误基检测, 静态代码分析, 预合并扫描