Viper678/CodeScanAI
GitHub: Viper678/CodeScanAI
基于 Gemma 4 31B 大语言模型的代码扫描 Web 应用，提供安全漏洞检测、Bug 分析和关键字搜索功能，帮助开发者和安全团队在代码审计中自动化发现问题。
Stars: 0 | Forks: 0
# CodeScan
CodeScan 是一个 Web 应用程序，允许开发者上传代码库（zip 压缩包或单个文件），选择他们关心的文件，并对其运行一项或多项基于 LLM 的扫描：**安全**、**Bug 报告**和**关键字**扫描。扫描结果经过标准化处理，支持过滤和导出。
用于分析的模型是 **Gemma 4 31B**（Google AI Studio API，256K 上下文）。
## 功能特性 (v1)
- 邮箱 + 密码身份验证（bcrypt + JWT，刷新令牌轮换）
- 上传 `.zip` 压缩包或一个或多个源文件（zip 文件 ≤ 100 MB / 单个文件 ≤ 50 MB）
- 服务器端解压，内置 zip 炸弹 / 路径遍历防护
- UI 中显示动态加载的目录树，包含合理的默认排除项和三态复选框选择功能
- 每次运行支持三种独立的扫描类型：
1. **安全扫描**（OWASP 风格：注入、硬编码密钥、弱加密等）
2. **Bug 报告扫描**（空指针解引用、差一错误、竞态条件、资源泄漏、逻辑错误）
3. **关键字扫描**（用户自定义关键字/短语 — 支持大小写敏感与正则表达式切换）
- 通过 Celery 执行异步扫描；基于轮询流式传输单文件进度（后续版本可能支持 SSE）
- 扫描结果表格，包含严重程度、文件/行号、代码片段和修复建议
- 导出扫描结果为 JSON / CSV / SARIF（SARIF 可在 v1.1 版本中发布）
## 技术栈
| 层级 | 选择 | 原因 |
| ----------- | ------------------------------------------------ | -------------------------------------------------- |
| 前端 | Next.js 14 (App Router), TS, Tailwind, shadcn/ui | 快速迭代，强类型，整洁的基础组件 |
| 状态管理 | TanStack Query + Zustand | 服务端缓存 + 小型客户端状态库 |
| 后端 | FastAPI + Pydantic v2 + SQLAlchemy 2 + Alembic | 现代 Python，异步，类型化，支持迁移 |
| 异步任务 | Celery 5 + Redis broker | 成熟，可观测，支持重试与并行处理 |
| 数据库 | Postgres 16 | 关系型数据库，支持 JSONB 存储扫描结果元数据 |
| 缓存/队列 | Redis 7 | 消息代理 + 缓存 + 临时状态存储 |
| LLM | Gemma 4 31B via `google-genai` SDK | 256K 上下文，JSON 结构化输出，擅长代码分析 |
| 容器 | Docker + docker-compose | 本地与生产环境运行时一致 |
## 仓库结构
```
codescan/
├── README.md # this file
├── docker-compose.yml # local + prod
├── .env.example
├── apps/
│ ├── api/ # FastAPI service
│ │ ├── pyproject.toml
│ │ ├── alembic/
│ │ └── app/
│ │ ├── main.py
│ │ ├── core/ # config, security, db, deps
│ │ ├── models/ # SQLAlchemy
│ │ ├── schemas/ # Pydantic
│ │ ├── routers/ # FastAPI routers
│ │ ├── services/ # business logic
│ │ └── tests/
│ ├── worker/ # Celery app
│ │ ├── pyproject.toml
│ │ └── worker/
│ │ ├── celery_app.py
│ │ ├── tasks/ # scan tasks
│ │ ├── llm/ # Gemma client + prompts
│ │ ├── scanners/ # security, bug, keyword
│ │ └── tests/
│ └── web/ # Next.js
│ ├── package.json
│ ├── app/
│ ├── components/
│ ├── lib/
│ └── tests/
└── docs/
├── ARCHITECTURE.md
├── SCHEMA.md
├── API.md
├── FLOW.md
├── UI_DESIGN.md
├── FILE_HANDLING.md
├── SCAN_RULES.md
├── TASKS.md
├── WORKFLOW.md
├── SECURITY.md
├── DEPLOYMENT.md
├── TESTING.md
└── CONTRIBUTING.md
```
## 快速开始 (本地)
```
cp .env.example .env
# 至少填写 GOOGLE_AI_API_KEY
docker compose up --build
```
然后：
- Web 界面 → http://localhost:3000
- API 接口 → http://localhost:8000 (文档位于 `/docs`)
- Postgres 数据库 → `localhost:5432`
- Redis 服务 → `localhost:6379`
## 从哪里开始阅读
如果您是接手该项目的 AI 代理，请按以下顺序阅读：
1. `docs/ARCHITECTURE.md` — 系统架构
2. `docs/FLOW.md` — 端到端流程
3. `docs/SCHEMA.md` + `docs/API.md` — 数据结构与接口契约
4. `docs/TASKS.md` — 选取任务
5. `docs/WORKFLOW.md` — 分支、构建、测试与 PR 流程
6. `docs/CONTRIBUTING.md` — 代码规范
## 当前状态
🟡 规划中 / 预实现阶段。尚未提交任何代码。
标签：AI代码分析, AV绕过, bcrypt, Bug检测, Celery, CISA项目, DevSecOps, FastAPI, Gemma 4, JSON导出, JWT, Pydantic, Python, React, Redis, SARIF, SQLAlchemy, Syscalls, Tailwind CSS, TanStack Query, TLS抓取, TypeScript, ZIP炸弹防护, ZIP解压, Zustand, 上游代理, 人工智能, 代码安全, 代码静态检查, 关键词扫描, 关键词检索, 大模型, 威胁情报, 安全扫描, 安全插件, 开发者工具, 异步任务, 搜索引擎查询, 数据管道, 文件上传, 文档安全, 无后门, 时序注入, 测试用例, 漏洞枚举, 状态管理, 用户模式Hook绕过, 请求拦截, 路径遍历防护, 软件安全, 软件工程, 逆向工具, 错误基检测, 静态代码分析