# https://github.com/AliAmmar15/Velonus 项目说明书
生成时间：2026-05-15 02:07:26 UTC
## 目录
- [项目概述](#page-overview)
- [系统架构](#page-architecture)
- [CLI 命令行工具](#page-cli)
- [API 服务系统](#page-api)
- [安全扫描器管道](#page-scanner)
- [数据标准化模块](#page-normalizer)
- [AI 引擎](#page-ai-engine)
- [GitHub 集成](#page-github-integration)
- [部署与基础设施](#page-deployment)
- [使用指南与最佳实践](#page-usage)
## 项目概述
### 相关页面
相关主题：[系统架构](#page-architecture), [使用指南与最佳实践](#page-usage)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)
- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)
- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)
- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)
- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)
# 项目概述
## 简介
Velonus 是一个本地优先的 Python 安全扫描工具（SAST），专注于在软件开发周期中自动检测安全漏洞和敏感信息泄露。该项目当前处于 Alpha 阶段，已实现核心功能并可在生产环境中使用。资料来源：[README.md:1]()
Velonus 的核心设计理念是将多个业界领先的开源安全工具整合到一个统一的命令行界面中，通过标准化输出格式和可配置的严重级别过滤，帮助开发团队在本地环境和 CI/CD 流水线中快速识别和修复安全问题。
## 核心价值主张
| 特性 | 说明 |
|------|------|
| **本地优先** | 所有扫描均在本地执行，无需将代码上传到第三方服务 |
| **多工具整合** | 统一调用 TruffleHog、Bandit、Semgrep、pip-audit、Safety 等工具 |
| **标准化输出** | 支持 Terminal、JSON、SARIF 三种输出格式 |
| **CI 友好** | CRITICAL/HIGH 级别发现时以退出码 1 退出，可作为合并门禁 |
| **即插即用** | 支持 GitHub Actions 和 Pre-commit hook 集成 |
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph CLI层["CLI 层 (apps/cli)"]
A["velonus scan"]
B["velonus auth"]
C["velonus config"]
end
subgraph 核心层["核心扫描层"]
D["扫描管道 Pipeline"]
E["结果归一化 NormalizedFinding"]
F["格式化器 Formatters"]
end
subgraph 检测器层["检测器层 (packages/scanner)"]
G["secrets - 密钥扫描"]
H["bandit - 代码审计"]
I["semgrep - 静态分析"]
J["pip-audit - 依赖审计"]
K["safety - 安全检查"]
end
subgraph 输出层["输出层"]
L["Terminal 格式化器"]
M["JSON 格式化器"]
N["SARIF 格式化器"]
end
A --> D
D --> G
D --> H
D --> I
D --> J
D --> K
G --> E
H --> E
I --> E
J --> E
K --> E
E --> F
F --> L
F --> M
F --> N
```
### 项目目录结构
```
Velonus/
├── apps/
│ └── cli/
│ ├── shield/ # CLI 主程序
│ │ ├── __main__.py
│ │ ├── cli.py # 命令行入口
│ │ ├── commands/ # 子命令实现
│ │ └── formatters/ # 输出格式化器
│ │ ├── terminal.py
│ │ ├── json.py
│ │ └── sarif.py
├── packages/
│ ├── scanner/
│ │ └── scanner/
│ │ ├── detectors/ # 安全检测器
│ │ │ ├── secrets.py # TruffleHog + 熵值检测
│ │ │ ├── bandit.py # Bandit 集成
│ │ │ ├── semgrep.py # Semgrep 集成
│ │ │ ├── pip_audit.py # pip-audit 集成
│ │ │ └── safety.py # Safety 集成
│ │ ├── models/ # 数据模型
│ │ │ ├── raw_finding.py
│ │ │ └── normalized_finding.py
│ │ └── pipeline.py # 扫描管道编排
│ └── normalizer/ # 结果标准化模块
└── pyproject.toml # 项目配置
```
## 扫描能力矩阵
### 已集成的安全工具
| 工具 | 用途 | 配置文件 |
|------|------|----------|
| **TruffleHog** | 硬编码密钥和凭证检测 | `secrets.py` |
| **Bandit** | Python 代码安全分析 | `bandit.py` |
| **Semgrep** | 高级静态分析与自定义规则 | `semgrep.py` |
| **pip-audit** | Python 依赖漏洞扫描 | `pip_audit.py` |
| **Safety** | Safety DB 依赖安全检查 | `safety.py` |
### 严重级别定义
| 级别 | 颜色标识 | 典型场景 |
|------|----------|----------|
| 🔴 CRITICAL | 粗体红色 | 硬编码密钥、RCE、认证绕过 |
| 🟠 HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |
| 🟡 MEDIUM | 黄色 | XSS、弱加密、路径遍历 |
| 🔵 LOW | 蓝色 | 不安全默认值、次要配置问题 |
| ⚪ INFO | 灰色 | 代码风格问题、信息性注释 |
资料来源：[apps/cli/README.md:1]()
## 命令行接口
### 核心命令
```bash
# 扫描当前目录
velonus scan ./
# 扫描指定项目
velonus scan ./my-python-project
# 仅显示 HIGH 和 CRITICAL 级别
velonus scan ./ --severity high
# 输出为 JSON 格式
velonus scan ./ --format json
# 输出为 SARIF 格式
velonus scan ./ --format sarif
# 详细输出模式
velonus scan ./ --verbose
```
### 命令行参数表
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `PATH` | `.` | 要扫描的项目或文件路径 |
| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |
| `--severity`, `-s` | `info` | 最低显示级别 |
| `--verbose`, `-v` | off | 显示解析后的目标路径和额外详情 |
| `--help` | - | 显示帮助信息并退出 |
资料来源：[apps/cli/README.md:1]()
### 退出码约定
| 退出码 | 含义 |
|--------|------|
| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |
| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |
退出码 1 的设计是**有意为之**，用于将扫描结果作为 CI/CD 流水线的合并门禁条件。资料来源：[apps/cli/README.md:1]()
## 输出格式详解
### Terminal 格式（默认）
使用 Rich 库渲染彩色表格，包含严重级别徽章、文件路径、行号、规则 ID 和详细信息。
### JSON 格式
适用于管道集成和结果存储：
```bash
velonus scan ./ --format json | python -m json.tool
velonus scan ./ --format json > scan-results.json
```
### SARIF 格式
SARIF（Static Analysis Results Interchange Format）是一种标准化格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具。资料来源：[apps/cli/README.md:1]()
```bash
velonus scan ./ --format sarif
```
## 数据模型
### RawFinding
各检测器输出的原始发现对象，包含以下核心字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| `tool` | str | 来源工具名称（如 `secrets`、`bandit`） |
| `rule_id` | str | 规则标识符 |
| `file` | str | 发现漏洞的文件路径 |
| `line` | int | 代码行号 |
| `severity` | str | 严重级别 |
| `message` | str | 人类可读的消息 |
| `code_snippet` | str | 相关代码片段 |
| `metadata` | dict | 工具特定的元数据 |
### NormalizedFinding
经过标准化处理的统一发现对象，格式统一后由格式化器渲染。
## 开发规范
### 代码质量要求
项目采用严格的代码质量标准：
| 检查项 | 工具 | 命令 |
|--------|------|------|
| 代码风格检查 | Ruff | `ruff check .` |
| 代码格式化 | Ruff | `ruff format --check .` |
| 静态类型检查 | mypy | `mypy --strict --ignore-missing-imports` |
资料来源：[CONTRIBUTING.md:1]()
### 严格模式要求
所有新代码必须通过 mypy strict 模式检查，零错误。引入 `type: ignore` 注释需要在代码注释中提供说明。资料来源：[CONTRIBUTING.md:1]()
### Pull Request 规范
| 规范 | 说明 |
|------|------|
| 单一职责 | 每个 PR 只包含一个功能或修复 |
| 测试要求 | 所有新功能必须包含匹配的单元测试 |
| 代码清理 | PR 前本地运行 ruff 和 mypy 检查 |
| 代码行数 | 建议 PR 差异控制在 400 行以内 |
| 无占位符 | 禁止 AI 生成的占位代码 |
## CI/CD 集成
### GitHub Actions 集成
```yaml
name: Velonus Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install velonus-cli
run: pip install -e apps/cli
- name: Run security scan
run: velonus scan ./ --severity high
```
资料来源：[apps/cli/README.md:1]()
### Pre-commit Hook 配置
```yaml
repos:
- repo: local
hooks:
- id: velonus-scan
name: Velonus Security Scan
entry: velonus scan
args: ["./", "--severity", "high"]
language: system
pass_filenames: false
```
## 开发路线图
| 阶段 | 状态 | 交付内容 |
|------|------|----------|
| **Phase 0** — 基础框架 | ✅ 已完成 | CLI 骨架、Rich 输出、`NormalizedFinding` 模型 |
| **Phase 1** — 扫描管道 | ✅ 已完成 | 真正的密钥检测、Bandit、Semgrep、pip-audit、SARIF |
| **Phase 2** — AI 层 | 🔨 进行中 | AI 优先级排序、可利用性评分、修复建议生成 |
| **Phase 3** — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |
| **Phase 4** — Web 控制台 | 🔴 未开始 | Web UI、扫描历史、问题趋势 |
资料来源：[README.md:1]()
## 技术栈
| 组件 | 技术选型 | 用途 |
|------|----------|------|
| CLI 框架 | Click | 命令行界面构建 |
| 表格渲染 | Rich | 终端彩色输出 |
| 类型系统 | Python 3.12+ | 静态类型检查 |
| 代码检查 | Ruff | 格式化与 linting |
| 静态分析 | Semgrep、Bandit | 代码安全分析 |
| 依赖扫描 | pip-audit、Safety | 依赖漏洞检测 |
| 密钥检测 | TruffleHog | 凭证扫描 |
## 总结
Velonus 是一个功能完整的 Python 安全扫描工具，通过统一界面整合多个业界领先的安全检测工具，为开发团队提供从本地开发到 CI/CD 流水线的全流程安全保障。项目采用严格的代码质量标准，确保长期可维护性，同时保持开放的贡献文化，欢迎社区参与改进。
---
## 系统架构
### 相关页面
相关主题：[项目概述](#page-overview), [CLI 命令行工具](#page-cli), [API 服务系统](#page-api), [安全扫描器管道](#page-scanner)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/cli/shield/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/main.py)
- [apps/api/shield_api/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/main.py)
- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)
- [infra/docker/docker-compose.yml](https://github.com/AliAmmar15/Velonus/blob/main/infra/docker/docker-compose.yml)
# 系统架构
## 概述
Velonus 是一个模块化的安全扫描平台，采用分层架构设计。系统由 CLI 前端、扫描管道、多个检测器后端和输出格式化器组成。核心设计理念是将扫描逻辑与用户界面分离，使每个检测工具（Bandit、Semgrep、pip-audit、Safety、TruffleHog）能够独立工作，同时通过统一的 `RawFinding` 数据模型汇聚结果。
## 整体架构
```mermaid
graph TD
subgraph CLI层["CLI 层 (apps/cli/shield)"]
CLI[命令行入口]
Formatters[格式化器]
Main[main.py]
end
subgraph Scanner层["扫描器层 (packages/scanner)"]
Pipeline[扫描管道]
Secrets[Secrets 检测器]
Bandit[Bandit 检测器]
Semgrep[Semgrep 检测器]
PipAudit[pip-audit 检测器]
Safety[Safety 检测器]
end
subgraph 数据模型["数据模型层"]
RawFinding[RawFinding 模型]
NormalizedFinding[NormalizedFinding 模型]
end
subgraph API层["API 层 (apps/api)"]
API[Shield API]
end
CLI --> Main
Main --> Formatters
Main --> Pipeline
Pipeline --> Secrets
Pipeline --> Bandit
Pipeline --> Semgrep
Pipeline --> PipAudit
Pipeline --> Safety
Secrets --> RawFinding
Bandit --> RawFinding
Semgrep --> RawFinding
PipAudit --> RawFinding
Safety --> RawFinding
Formatters --> NormalizedFinding
Formatters --> RawFinding
```
## 核心组件
### CLI 层
CLI 层位于 `apps/cli/shield` 目录，负责用户交互和结果展示。
| 组件 | 路径 | 职责 |
|------|------|------|
| main.py | apps/cli/shield/main.py | 命令行入口，参数解析，扫描协调 |
| formatters/ | apps/cli/shield/formatters/ | 输出格式化（terminal、json、sarif） |
| detectors/ | packages/scanner/scanner/detectors/ | 安全检测器实现 |
CLI 支持的输出格式：
| 格式 | 用途 | 状态 |
|------|------|------|
| terminal | 交互式彩色输出 | ✅ 已实现 |
| json | 管道友好输出 | ✅ 已实现 |
| sarif | GitHub Code Scanning 兼容 | ✅ 已实现 |
资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
### 扫描管道
扫描管道 (`packages/scanner/scanner/pipeline.py`) 是核心编排组件，负责：
1. 依次调用各个检测器
2. 收集并归一化扫描结果
3. 处理检测器的执行超时和错误
```mermaid
graph LR
A[扫描目标] --> B[Secrets 检测器]
B --> C[Bandit 检测器]
C --> D[Semgrep 检测器]
D --> E[pip-audit 检测器]
E --> F[Safety 检测器]
F --> G[结果聚合]
```
每个检测器返回 `RawFinding` 列表，管道统一收集后传递给格式化器。
### 检测器架构
检测器采用统一的接口设计，每个检测器继承基础类并实现 `scan()` 方法。
#### Secrets 检测器
位于 `packages/scanner/scanner/detectors/secrets.py` 和 `packages/scanner/detectors/secrets.py`，实现两层检测：
| 检测模式 | 描述 |
|----------|------|
| TruffleHog | 使用 TruffleHog 进行已知格式密钥检测 |
| 熵值分析 | Shannon 熵阈值检测高随机性字符串 |
```python
# 熵值阈值常量
_ENTROPY_THRESHOLD = 4.5
```
当 TruffleHog 未安装时，自动降级到熵值分析模式。检测结果包含：
- `detector`: 检测器类型名称
- `verified`: 是否经过 TruffleHog 验证
- `decoder`: 使用的解码器名称
资料来源：[packages/scanner/scanner/detectors/secrets.py:1-150](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)
#### Semgrep 检测器
位于 `packages/scanner/scanner/detectors/semgrep.py`，使用 `p/python` 规则集。
| 参数 | 默认值 | 说明 |
|------|--------|------|
| --config | p/python | Semgrep 规则集 |
| --json | - | JSON 输出格式 |
| --quiet | - | 静默模式 |
| --metrics | off | 禁用遥测 |
Semgrep 返回 1 表示发现漏洞（正常行为），返回 2+ 才表示错误。
资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-50](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
#### 依赖漏洞检测器
##### pip-audit 检测器
位于 `packages/scanner/scanner/detectors/pip_audit.py`，检测 Python 依赖中的已知漏洞。
关键元数据字段：
| 字段 | 说明 |
|------|------|
| package_name | 包名称 |
| package_version | 安装版本 |
| cvss_score | CVSS v3 评分 |
| fix_versions | 可修复版本列表 |
| fix_available | 是否有修复版本 |
##### Safety 检测器
位于 `packages/scanner/scanner/detectors/safety.py`，支持两种输出格式：
| Safety 版本 | 数据格式 |
|-------------|----------|
| v2 (>=2.0) | `{"vulnerabilities": [...]}` |
| v1 (<2.0) | 5 元素列表数组 |
CVSS 评分提取逻辑处理嵌套的 severity 字典结构。
资料来源：[packages/scanner/scanner/detectors/safety.py:1-100](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)
## 数据模型
### RawFinding
所有检测器返回统一的 `RawFinding` 对象：
| 字段 | 类型 | 说明 |
|------|------|------|
| tool | str | 来源工具名称 |
| rule_id | str | 规则标识符 |
| file | str | 文件路径 |
| line | int | 行号 |
| severity | str | 严重级别 |
| message | str | 人类可读消息 |
| code_snippet | str | 相关代码片段 |
| metadata | dict | 工具特定元数据 |
### 严重级别
| 级别 | 颜色 | 典型场景 |
|------|------|----------|
| CRITICAL | 红色 | 硬编码密钥、RCE、认证绕过 |
| HIGH | 橙色 | SQL 注入、命令注入 |
| MEDIUM | 黄色 | XSS、弱加密、路径遍历 |
| LOW | 蓝色 | 不安全默认值 |
| INFO | 灰色 | 样式问题 |
资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
## 格式化输出
### SARIF 格式化器
位于 `apps/cli/shield/formatters/sarif.py`，实现 SARIF 2.1.0 规范。
关键转换函数：
```python
def _rule_id_to_name(rule_id: str) -> str:
"""将 rule_id 转换为 PascalCase 显示名称"""
base = rule_id.split("/")[-1]
return "".join(word.capitalize() for word in base.replace("-", "_").split("_"))
```
目录 URI 处理遵循 SARIF 规范 §3.14.14，强制添加尾部斜杠。
### 输出格式映射
| 内部级别 | SARIF 级别 |
|----------|-----------|
| CRITICAL | error |
| HIGH | error |
| MEDIUM | warning |
| LOW | note |
| INFO | note |
## API 层
位于 `apps/api/shield_api/main.py`，为 Phase 2 及后续功能预留。
当前阶段：
| 阶段 | 功能 | 状态 |
|------|------|------|
| Phase 0 | CLI 框架 | ✅ 完成 |
| Phase 1 | 扫描管道 | ✅ 完成 |
| Phase 2 | AI 上下文引擎 | 🔨 开发中 |
| Phase 3 | GitHub PR 集成 | 📋 计划中 |
| Phase 4 | Web 仪表板 | 📋 计划中 |
资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
## 部署架构
### Docker 部署
项目提供 Docker Compose 配置用于容器化部署：
```yaml
# infra/docker/docker-compose.yml 结构
services:
shield-api: # API 服务
scanner: # 扫描引擎
dashboard: # Web UI (Phase 4)
```
### CI/CD 集成
系统设计支持多种 CI 场景：
| 集成方式 | 配置示例 |
|----------|----------|
| GitHub Actions | .github/workflows/security.yml |
| Pre-commit hook | .pre-commit-config.yaml |
Velonus 在发现 HIGH 或 CRITICAL 漏洞时返回退出码 1，可作为 CI 门禁。
## 贡献与质量保障
项目要求严格的代码质量标准：
| 检查项 | 工具 | 命令 |
|--------|------|------|
| 代码格式 | ruff | `ruff format --check .` |
| 代码检查 | ruff | `ruff check .` |
| 类型检查 | mypy | `mypy --strict` |
PR 规范：
- 每个 PR 只做一个改动
- 必须包含测试
- Diff 行数建议小于 400
- 禁止 AI 生成的占位代码
资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)
## 工作流程图
```mermaid
sequenceDiagram
participant User as 用户
participant CLI as CLI
participant Pipeline as 扫描管道
participant Detectors as 检测器
participant Formatter as 格式化器
User->>CLI: velonus scan ./ --severity high
CLI->>Pipeline: 初始化扫描任务
Pipeline->>Detectors: 并行/顺序执行检测
Detectors-->>Pipeline: RawFinding[]
Pipeline->>Formatter: 聚合结果
Formatter->>User: 格式化输出
```
## 总结
Velonus 采用插件化的检测器架构，每个安全工具（Bandit、Semgrep、pip-audit、Safety、TruffleHog）作为独立模块接入管道。这种设计使得系统易于扩展，新增检测器只需实现统一的 `scan()` 接口并返回 `RawFinding` 对象即可。CLI 与扫描逻辑的分离确保了核心功能可以在多种场景下复用，包括本地 CLI、CI/CD 管道和 Web 仪表板。
---
## CLI 命令行工具
### 相关页面
相关主题：[系统架构](#page-architecture), [API 服务系统](#page-api), [使用指南与最佳实践](#page-usage)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/cli/shield/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/main.py)
- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)
- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)
- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)
- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)
- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)
# CLI 命令行工具
## 概述
Velonus CLI 是一个基于 Python 的命令行安全扫描工具，采用 Typer 框架构建，为开发者提供本地化的应用安全测试能力。CLI 工具支持多种安全扫描器集成，包括密钥检测、代码漏洞扫描、依赖漏洞审计等，并能输出多种格式的结果用于不同场景。
CLI 的核心定位是**本地优先**，即所有核心扫描功能在不依赖后端 API 的情况下完全可用。身份验证和云端功能（如 AI 优先级排序、修复建议生成）则在后续阶段（Phase 2+）逐步实现。 资料来源：[apps/cli/shield/main.py:1-17]()
## 架构设计
### 整体架构
```mermaid
graph TD
A["velonus CLI 入口
(main.py)"] --> B["Typer 应用层"]
B --> C["命令模块
(commands/)"]
C --> D["scan 命令"]
C --> E["auth 命令"]
C --> F["config 命令"]
D --> G["scanner 包
(packages/scanner)"]
G --> H["检测器引擎"]
H --> I["secrets.py
密钥检测"]
H --> J["semgrep.py
代码模式扫描"]
H --> K["pip_audit.py
依赖漏洞审计"]
H --> L["safety.py
安全依赖检查"]
D --> M["格式化器
(formatters/)"]
M --> N["terminal.py
终端输出"]
M --> O["sarif.py
SARIF 格式"]
```
### 模块职责
| 模块路径 | 职责 | 状态 |
|---|---|---|
| `main.py` | CLI 根应用定义、Typer 实例初始化、命令组注册 | 稳定 |
| `commands/scan.py` | `velonus scan` 命令实现、参数解析、扫描执行 | 稳定 |
| `commands/auth.py` | `velonus auth` 认证命令（登录/登出/状态） | Phase 2 |
| `commands/config.py` | `velonus config` 配置管理命令 | Phase 2 |
| `core/api_client.py` | 与 Velonus 后端 API 通信 | Phase 2 |
| `core/config.py` | 本地配置加载与存储 | Phase 2 |
| `formatters/terminal.py` | 终端 Rich 表格输出 | 稳定 |
| `formatters/sarif.py` | SARIF 格式生成 | Phase 1 |
## 命令详解
### velonus scan
`velonus scan` 是核心命令，用于在本地路径上运行安全扫描管道。
#### 命令语法
```
velonus scan [PATH] [OPTIONS]
```
#### 参数与选项
| 参数/选项 | 默认值 | 描述 |
|---|---|---|
| `PATH` | `.` | 要扫描的项目路径或文件 |
| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |
| `--severity`, `-s` | `info` | 最低显示严重级别：`critical`、`high`、`medium`、`low`、`info` |
| `--verbose`, `-v` | 关闭 | 显示解析后的目标路径及额外详情 |
| `--help` | - | 显示帮助信息并退出 |
#### 使用示例
```bash
# 扫描当前目录
velonus scan ./
# 扫描子目录
velonus scan ./apps/api
# 仅显示高危和严重漏洞
velonus scan ./ --severity high
# 显示详细路径信息
velonus scan ./ --verbose
# 导出为 JSON
velonus scan ./ --format json
# 导出为 SARIF 格式
velonus scan ./ --format sarif
# 高危以上结果重定向到文件
velonus scan ./ --format json --severity high > findings.json
```
#### 退出码
| 退出码 | 含义 |
|---|---|
| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |
| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |
退出码 `1` 是有意设计的，可作为 CI/CD 门禁阻止合并。 资料来源：[apps/cli/README.md:1-80]()
### velonus auth
认证命令用于与 Velonus API 建立连接，目前处于 **Phase 2** 阶段（桩代码状态）。
| 子命令 | 描述 |
|---|---|
| `velonus auth login` | 通过 Clerk（浏览器 OAuth 流程）进行身份验证 |
| `velonus auth logout` | 清除存储的凭证 |
| `velonus auth status` | 显示当前认证状态 |
```bash
velonus auth login
velonus auth logout
velonus auth status
```
> Phase 0 阶段这些命令为桩代码，将在 Phase 2 后端 API 上线后完整实现。
### velonus config
本地 CLI 配置管理命令，目前处于 **Phase 2** 阶段（桩代码状态）。
| 子命令 | 描述 |
|---|---|
| `velonus config show` | 打印当前配置 |
| `velonus config set ` | 设置配置值 |
```bash
velonus config show
velonus config set api_url https://api.velonus.dev
```
## 输出格式
### terminal（默认）
使用 Rich 库渲染彩色表格，包含严重级别徽章、文件路径、行号、规则 ID 和消息。适合交互式使用。 资料来源：[apps/cli/README.md:100-130]()
```
┏━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃
┡━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ 🔴 CRITICAL│ secrets│ config.yml │ 5 │ aws-key │ AWS key detected │
│ 🟠 HIGH │ bandit │ app.py │ 42 │ B301 │ Pickle deserial... │
└────────────┴────────┴────────────┴───────┴──────────┴────────────────────┘
```
### JSON
适合管道传递或存储结果。
```bash
velonus scan ./ --format json | python -m json.tool
velonus scan ./ --format json > scan-results.json
```
### SARIF
静态分析结果交换格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具。**Phase 1** 可用。
SARIF 格式化器负责将扫描结果转换为符合规范的 SARIF 2.1.0 输出：
```python
def _rule_id_to_name(rule_id: str) -> str:
"""Convert a rule_id to a PascalCase display name for SARIF.
Strips any tool-prefix segment (e.g. ``"secrets/generic-api-key"``
becomes ``"GenericApiKey"``)."""
```
目录 URI 处理遵循 SARIF 规范 §3.14.14，确保目录 URI 以 `/` 结尾：
```python
def _dir_uri(path: Path) -> str:
"""Return a file:// URI for a directory, ensuring a trailing slash."""
uri = path.as_uri()
return uri if uri.endswith("/") else uri + "/"
```
资料来源：[apps/cli/shield/formatters/sarif.py:1-50]()
## 严重级别
| 徽章 | 级别 | 颜色 | 适用场景 |
|---|---|---|---|
| 🔴 | `CRITICAL` | 粗体红色 | 硬编码密钥、RCE、认证绕过 |
| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |
| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |
| 🔵 | `LOW` | 蓝色 | 不安全默认值、次要配置错误 |
| ⚪ | `INFO` | 灰色 | 样式问题、信息性备注 |
建议使用 `--severity high` 仅显示需要立即处理的问题；使用 `--severity info`（默认）查看所有发现。
## 扫描管道
扫描管道由多个检测器组成，每个检测器负责特定类型的安全问题扫描。
### secrets — 密钥检测
支持两种检测模式：
1. **TruffleHog 集成**：调用 TruffleHog3 二进制进行已知密钥模式检测
2. **熵值检测回退**：基于 Shannon 熵阈值检测高熵字符串
```python
def _entropy_scan(self, target: Path) -> list[RawFinding]:
"""Entropy-based regex secret scanner — trufflehog fallback.
Walks the target path recursively, skipping non-code directories and
binary file extensions."""
```
跳过目录包括：`.git`、`node_modules`、`__pycache__`、`.venv`、`venv`、`.env`、`dist`、`build` 等。 资料来源：[packages/scanner/scanner/detectors/secrets.py:1-80]()
### semgrep — 代码模式扫描
调用 Semgrep 进行基于规则的代码静态分析，默认使用 `p/python` 规则集。
```python
def scan(self, target: Path) -> list[RawFinding]:
"""Run semgrep on target and return findings as RawFinding instances.
Invokes ``semgrep scan --config p/python --json --quiet --metrics=off ``."""
```
Semgrep 以退出码 1 返回发现时，**不**视为错误——JSON 输出仍然完全有效并正常解析。退出码 2+ 才表示真正的错误。 资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-50]()
### pip-audit — 依赖漏洞审计
解析 pip-audit 的 JSON 输出，提取漏洞信息、CWE 分类和修复版本建议。
```python
def _extract_cvss_score(cvss_list: Any) -> float | None:
"""Extract the highest CVSS v3 base score from pip-audit's cvss array.
pip-audit embeds CVSS data as a list of score objects::
[{"type": "CVSS_V3", "score": "CVSS:3.1/...", "base_score": 7.5}]"""
```
漏洞元数据包含：包名、包版本、别名、修复版本、CVSS 评分、CWE、OWASP 分类，以及 `fix_available` 标志驱动终端格式化器的 UI 徽章。 资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1-60]()
### safety — 安全依赖检查
支持 Safety CLI 的 v1 和 v2 两种 JSON 输出格式：
- **v2 格式**：字典结构，包含 `"vulnerabilities"` 键
- **v1 格式**：列表结构，每个元素为 5 元素列表
```python
def _parse_entry_v2(self, entry: dict, attribution_path: str) -> RawFinding | None:
"""Parse a v2-format vulnerability entry.
Required fields: ``vulnerability_id``, ``package_name``,
``analyzed_version``."""
```
资料来源：[packages/scanner/scanner/detectors/safety.py:1-100]()
## CI/CD 集成
### GitHub Actions
```yaml
name: Velonus Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install velonus-cli
run: pip install -e apps/cli
- name: Run security scan
run: velonus scan ./ --severity high
# exits 1 if HIGH or CRITICAL findings are found — blocks the merge
```
### Pre-commit Hook
添加到 `.pre-commit-config.yaml`：
```yaml
repos:
- repo: local
hooks:
- id: velonus-scan
name: Velonus Security Scan
entry: velonus scan
args: ["./", "--severity", "high"]
language: system
pass_filenames: false
```
## 发展阶段路线图
| 阶段 | 状态 | 功能范围 |
|---|---|---|
| Phase 0 — 基础 | ✅ 完成 | CLI 骨架、Rich 输出、`NormalizedFinding` 模型 |
| Phase 1 — 扫描管道 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、SARIF |
| Phase 2 — AI 层 | 🔨 进行中 | AI 优先级排序、可利用性评分、修复生成 |
| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |
| Phase 4 — 仪表盘 | 🔴 未开始 | Web UI、扫描历史、问题趋势 |
## 代码质量要求
项目对 CLI 代码有严格的代码质量标准：
### Ruff 格式化
```bash
# 检查格式化
ruff format --check .
# 自动格式化
ruff format .
```
### Mypy 严格模式
```bash
mypy apps/cli/shield --strict --ignore-missing-imports
mypy packages/scanner --strict --ignore-missing-imports
```
所有新代码必须通过 mypy 严格检查且零错误。引入 `type: ignore` 注释的 PR 需要在代码注释中附带说明。 资料来源：[CONTRIBUTING.md:1-50]()
### PR 指南
1. **每次 PR 一个功能或修复**：不要捆绑不相关的更改
2. **必须包含测试**：每个新的扫描器包装器、格式化器或工具函数需要匹配的单元测试
3. **Ruff 必须通过**：本地推送前运行 `ruff check . && ruff format --check .`
4. **mypy 必须通过**：本地运行 `mypy apps/cli/shield --strict --ignore-missing-imports`
5. **目标 main 分支**：所有 PR 合并到 main，无长期特性分支
6. **描述变更**：填写 PR 模板，清晰的描述和完整的检查清单
7. **保持小规模**：400 行以下 diff 的 PR 审核更快，必要时拆分大型更改
8. **禁止 AI 占位代码**：每个函数必须功能完整且经过测试
---
## API 服务系统
### 相关页面
相关主题：[系统架构](#page-architecture), [AI 引擎](#page-ai-engine), [部署与基础设施](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
**注意：以下API相关文件未在当前检索上下文中找到实际源码内容，页面内容基于项目文档和已知架构信息整理。**
- [apps/api/shield_api/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/main.py)
- [apps/api/shield_api/routers/scans.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/scans.py)
- [apps/api/shield_api/routers/findings.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/findings.py)
- [apps/api/shield_api/routers/remediation.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/remediation.py)
- [apps/api/shield_api/routers/github.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/github.py)
- [apps/api/shield_api/services/scan_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/scan_service.py)
- [apps/api/shield_api/services/ai_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/ai_service.py)
- [apps/api/shield_api/middleware/auth.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/middleware/auth.py)
- [apps/api/shield_api/middleware/rate_limit.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/middleware/rate_limit.py)
- [apps/api/shield_api/background/ai_worker.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/background/ai_worker.py)
- [apps/api/shield_api/background/scan_worker.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/background/scan_worker.py)
# API 服务系统
## 概述
Velonus 的 API 服务系统（`apps/api/shield_api/`）是整个安全扫描平台的核心后端服务，负责接收扫描请求、协调安全工具执行、管理扫描结果，并提供 AI 驱动的漏洞修复建议。该系统基于 FastAPI 构建，采用模块化架构设计，将功能划分为路由（routers）、服务（services）、中间件（middleware）和后台任务（background workers）四个层次。
根据项目路线图，API 服务系统属于 **Phase 2 — AI Layer** 阶段的核心组件，目前处于 `Building`（构建中）状态。资料来源：[README.md]()
## 系统架构
### 整体架构图
```mermaid
graph TD
A[客户端 / CLI] -->|HTTP REST API| B[API Gateway]
B --> C[认证中间件
auth.py]
B --> D[限流中间件
rate_limit.py]
C --> E[路由层]
E --> F1[scans.py]
E --> F2[findings.py]
E --> F3[remediation.py]
E --> F4[github.py]
F1 --> G1[scan_service.py]
F2 --> G1
F3 --> G2[ai_service.py]
G1 --> H1[scan_worker.py
后台扫描任务]
G2 --> H2[ai_worker.py
AI 任务队列]
H1 --> I[安全扫描器]
I --> J1[Bandit]
I --> J2[Semgrep]
I --> J3[pip-audit]
I --> J4[Safety]
I --> J5[Trufflehog]
H2 --> K[AI 修复建议引擎]
G1 --> L[(结果存储)]
H2 --> L
```
### 核心组件说明
| 组件 | 文件路径 | 职责描述 |
|------|----------|----------|
| **main.py** | `apps/api/shield_api/main.py` | FastAPI 应用入口，配置路由、中间件和生命周期事件 |
| **scans.py** | `apps/api/shield_api/routers/scans.py` | 扫描任务的创建、查询和状态管理 API |
| **findings.py** | `apps/api/shield_api/routers/findings.py` | 漏洞发现结果的分页查询和过滤 API |
| **remediation.py** | `apps/api/shield_api/routers/remediation.py` | AI 驱动的漏洞修复建议 API |
| **github.py** | `apps/api/shield_api/routers/github.py` | GitHub 集成相关 API（Webhooks、PR 评论） |
| **scan_service.py** | `apps/api/shield_api/services/scan_service.py` | 扫描编排服务，协调各安全工具执行 |
| **ai_service.py** | `apps/api/shield_api/services/ai_service.py` | AI 修复建议生成服务 |
| **auth.py** | `apps/api/shield_api/middleware/auth.py` | Clerk OAuth 认证中间件 |
| **rate_limit.py** | `apps/api/shield_api/middleware/rate_limit.py` | API 请求限流中间件 |
| **scan_worker.py** | `apps/api/shield_api/background/scan_worker.py` | 异步扫描任务执行器 |
| **ai_worker.py** | `apps/api/shield_api/background/ai_worker.py` | 异步 AI 任务处理器 |
## 认证与授权
### 认证机制
Velonus API 使用 **Clerk** 进行身份认证，支持浏览器 OAuth 流程。资料来源：[apps/cli/README.md]()
认证中间件 `auth.py` 负责：
- 验证用户访问令牌的有效性
- 提取用户身份信息并注入请求上下文
- 保护需要认证的 API 端点
```mermaid
sequenceDiagram
participant Client
participant API
participant Clerk
Client->>API: 请求 + Bearer Token
API->>Clerk: 验证 Token
Clerk-->>API: Token 有效 / 无效
API->>Client: 200 OK / 401 Unauthorized
```
### CLI 认证命令
| 命令 | 功能 |
|------|------|
| `velonus auth login` | 通过 Clerk 浏览器 OAuth 流程认证 |
| `velonus auth logout` | 清除存储的凭证 |
| `velonus auth status` | 显示当前认证状态 |
> 注意：认证功能在 Phase 2 阶段完全可用，Phase 0 阶段仅为存根实现。资料来源：[apps/cli/README.md]()
## 限流策略
`rate_limit.py` 中间件实现了 API 请求限流机制，用于：
- 防止 API 滥用和资源耗尽
- 确保多租户环境下的公平使用
- 保护后端扫描任务不被过度触发
限流策略的具体参数和阈值需参考实际配置文件或环境变量设置。
## 扫描服务
### 扫描流程
```mermaid
graph LR
A[创建扫描任务] --> B[scan_worker 接收]
B --> C[调用 scan_service]
C --> D[并行执行安全工具]
D --> E1[Bandit]
D --> E2[Semgrep]
D --> E3[pip-audit]
D --> E4[Safety]
D --> E5[Trufflehog]
E1 --> F[结果标准化]
E2 --> F
E3 --> F
E4 --> F
E5 --> F
F --> G[存储 NormalizedFinding]
G --> H[返回扫描结果]
```
### 支持的安全扫描器
| 扫描器 | 类型 | 用途 |
|--------|------|------|
| **Bandit** | SAST | Python 代码安全分析 |
| **Semgrep** | SAST | 多语言代码规则扫描（使用 `p/python` 规则集） |
| **pip-audit** | 依赖审计 | Python 依赖漏洞扫描 |
| **Safety** | 依赖审计 | Python 依赖安全检查（支持 v1/v2 两种输出格式） |
| **Trufflehog** | 密钥扫描 | 高熵值密钥和敏感信息检测 |
### 扫描退出码语义
| 退出码 | 含义 |
|--------|------|
| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别漏洞 |
| `1` | 扫描完成，发现一个或多个 HIGH/CRITICAL 级别漏洞 |
退出码 1 是有意设计的，用于 CI/CD 流程中的门禁检查。资料来源：[apps/cli/README.md]()
## AI 修复服务
### AI 层架构
Phase 2 的核心功能是 AI 驱动的漏洞优先级排序和修复建议生成。资料来源：[README.md]()
```mermaid
graph TD
A[发现结果] --> B[ai_service.py]
B --> C[可利用性评分]
B --> D[优先级计算]
B --> E[修复建议生成]
C --> F[AI 评分模型]
D --> F
E --> G[ai_worker.py]
G --> H[修复方案输出]
```
### ai_worker.py 职责
`ai_worker.py` 是后台 AI 任务处理器，负责：
- 接收来自 AI 服务的异步任务
- 调用 AI 模型进行漏洞分析和修复建议生成
- 管理任务队列和重试逻辑
- 返回结构化的修复方案
## GitHub 集成
`github.py` 路由提供与 GitHub 平台的集成能力：
- 接收 GitHub Webhook 事件（push、pull_request）
- 在 PR 中内联显示安全扫描结果
- 提供一键修复建议的接受功能
此功能属于 **Phase 3 — GitHub PR Integration** 阶段，规划中。资料来源：[README.md]()
## 数据模型
### NormalizedFinding
核心数据结构，用于统一不同安全工具的输出格式：
```python
@dataclass
class NormalizedFinding:
tool: str # 来源工具名称
rule_id: str # 规则标识符
file: str # 文件路径
line: int # 代码行号
severity: str # 严重级别
message: str # 人类可读消息
code_snippet: str # 代码片段
metadata: dict # 额外元数据
```
### 严重级别定义
| 级别 | 颜色 | 场景 |
|------|------|------|
| 🔴 CRITICAL | 粗体红色 | 硬编码密钥、RCE、认证绕过 |
| 🟠 HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |
| 🟡 MEDIUM | 黄色 | XSS、弱加密、路径遍历 |
| 🔵 LOW | 蓝色 | 不安全默认值、轻微配置问题 |
| ⚪ INFO | 灰色 | 样式问题、信息性提示 |
资料来源：[apps/cli/README.md]()
## API 端点概览
### 扫描相关
| 端点 | 方法 | 功能 |
|------|------|------|
| `/scans` | POST | 创建新扫描任务 |
| `/scans/{id}` | GET | 获取扫描详情 |
| `/scans/{id}/status` | GET | 获取扫描状态 |
### 发现结果
| 端点 | 方法 | 功能 |
|------|------|------|
| `/findings` | GET | 分页查询漏洞发现 |
| `/findings/{id}` | GET | 获取单个发现详情 |
| `/findings/{id}/metadata` | GET | 获取发现元数据 |
### 修复建议
| 端点 | 方法 | 功能 |
|------|------|------|
| `/remediation/{finding_id}` | GET | 获取 AI 修复建议 |
| `/remediation/{finding_id}/apply` | POST | 尝试应用修复 |
### GitHub 集成
| 端点 | 方法 | 功能 |
|------|------|------|
| `/github/webhook` | POST | 接收 GitHub Webhook 事件 |
| `/github/pr-comment` | POST | 在 PR 中添加评论 |
## 输出格式
### 支持的格式
| 格式 | 用途 | 适用场景 |
|------|------|----------|
| `terminal` | 彩色 Rich 表格（默认） | 交互式使用 |
| `json` | 结构化 JSON | 管道处理、工具集成 |
| `sarif` | SARIF 标准格式 | GitHub Code Scanning、VS Code |
### SARIF 输出
SARIF（Static Analysis Results Interchange Format）输出与 GitHub Security 标签兼容，可直接上传至 GitHub 进行漏洞展示。资料来源：[apps/cli/shield/formatters/sarif.py]()
## 部署配置
### 环境变量
| 变量 | 说明 |
|------|------|
| `CLERK_PUBLISHABLE_KEY` | Clerk 认证公钥 |
| `CLERK_SECRET_KEY` | Clerk 认证密钥 |
| `DATABASE_URL` | 数据库连接字符串 |
| `REDIS_URL` | Redis 连接（任务队列） |
### 配置管理
```bash
# 查看当前配置
velonus config show
# 设置配置项
velonus config set api_url https://api.velonus.dev
```
## 开发与贡献
### 代码质量要求
| 检查工具 | 模式 | 说明 |
|----------|------|------|
| **ruff** | 格式检查 | `ruff format --check .` |
| **ruff** | 代码检查 | `ruff check .` |
| **mypy** | 严格类型检查 | `mypy apps/cli/shield --strict --ignore-missing-imports` |
### PR 指南
1. **单功能原则**：每个 PR 只包含一个功能或修复
2. **测试要求**：新增功能必须附带对应的单元测试
3. **代码规范**：必须通过 ruff 和 mypy 检查
4. **PR 描述**：清晰说明变更内容和动机
5. **代码行数**：建议 PR 变更行数小于 400 行
资料来源：[CONTRIBUTING.md]()
## 路线图
| 阶段 | 状态 | 功能 |
|------|------|------|
| Phase 0 — Foundation | ✅ 完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |
| Phase 1 — Scanner Pipeline | ✅ 完成 | 密钥检测、Bandit、Semgrep、pip-audit、SARIF |
| **Phase 2 — AI Layer** | 🔨 构建中 | AI 优先级排序、可利用性评分、修复生成 |
| Phase 3 — GitHub Integration | 🔜 规划中 | PR 内联评论、一键修复建议 |
| Phase 4 — Dashboard | 🔜 规划中 | Web UI、扫描历史、漏洞趋势 |
资料来源：[README.md]()
## 状态说明
| 符号 | 含义 |
|------|------|
| ✅ | 已完成 |
| 🔨 | 正在构建 |
| 🔜 | 规划中 |
> **Alpha 提示**：Velonus 当前处于 Alpha 阶段，API 服务系统仍在积极开发中，可能存在不稳定性和 API 变更。请关注 [GitHub Issues](https://github.com/AliAmmar15/Velonus/issues) 获取最新动态并报告问题。
---
## 安全扫描器管道
### 相关页面
相关主题：[数据标准化模块](#page-normalizer), [系统架构](#page-architecture), [使用指南与最佳实践](#page-usage)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)
- [packages/scanner/scanner/detectors/bandit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/bandit.py)
- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)
- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)
- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)
- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)
# 安全扫描器管道
## 概述
安全扫描器管道（Scanner Pipeline）是 Velonus 安全扫描工具的核心组件，负责协调和执行多种安全扫描工具，对代码仓库进行全面的安全漏洞检测。管道设计遵循模块化架构，将不同的安全检测工具（检测器）作为独立的插件集成到统一的工作流中。
管道的主要职责包括：
- **并行执行**：协调多个安全扫描工具的并发执行
- **结果收集**：统一收集各检测器的原始发现（RawFinding）
- **数据规范化**：将不同工具的输出格式转换为统一的 NormalizedFinding 数据结构
- **格式输出**：支持多种输出格式（终端、JSON、SARIF）
资料来源：[packages/scanner/scanner/pipeline.py]()
## 架构设计
### 整体架构
Velonus 的安全扫描器采用插件化架构，核心管道负责调度，各检测器负责具体的扫描逻辑。这种设计使得添加新的扫描工具变得简单，只需实现对应的检测器接口即可。
```mermaid
graph TD
A[用户输入
velonus scan ./] --> B[ScannerPipeline]
B --> C[SecretDetector]
B --> D[BanditDetector]
B --> E[SemgrepDetector]
B --> F[PipAuditDetector]
B --> G[SafetyDetector]
C --> H[RawFinding List]
D --> I[RawFinding List]
E --> J[RawFinding List]
F --> K[RawFinding List]
G --> L[RawFinding List]
H --> M[FindingNormalizer]
I --> M
J --> M
K --> M
L --> M
M --> N[NormalizedFinding List]
N --> O[Output Formatters]
O --> P[Terminal
JSON
SARIF]
```
### 组件层次
| 层级 | 组件 | 职责 |
|------|------|------|
| 入口层 | CLI (`velonus scan`) | 解析命令行参数，调用管道 |
| 管道层 | `ScannerPipeline` | 协调检测器执行，收集结果 |
| 检测层 | 各 Detector 实现 | 执行具体的扫描工具 |
| 规范化层 | `FindingNormalizer` | 转换为统一数据模型 |
| 输出层 | Formatters | 将结果渲染为不同格式 |
## 扫描管道核心
### ScannerPipeline 类
`ScannerPipeline` 是管道的中央调度器，负责管理检测器的生命周期和执行顺序。
```mermaid
graph LR
A[初始化] --> B[执行扫描]
B --> C[并行运行所有检测器]
C --> D[收集RawFinding]
D --> E[规范化处理]
E --> F[返回NormalizedFinding列表]
```
管道支持以下配置参数：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `target` | `Path` | 必需 | 扫描目标路径（文件或目录） |
| `severity` | `str` | `"info"` | 最小严重级别过滤 |
| `tools` | `list[str]` | `None` | 指定运行的检测器，None表示全部 |
| `verbose` | `bool` | `False` | 是否显示详细输出 |
### 执行流程
1. **初始化阶段**：加载所有启用的检测器实例
2. **扫描阶段**：各检测器独立扫描目标路径，管道等待所有检测完成
3. **规范化阶段**：将 RawFinding 转换为 NormalizedFinding 统一格式
4. **输出阶段**：根据用户指定的格式输出结果
## 检测器模块
### 密钥检测器（SecretsDetector）
**文件位置**：`packages/scanner/scanner/detectors/secrets.py`
密钥检测器是 Velonus 的核心检测功能，负责发现代码库中的敏感信息泄露，包括 API 密钥、密码、证书等。
#### 检测策略
密钥检测器采用双重检测机制：
```mermaid
graph TD
A[扫描目标] --> B{Trufflehog可用?}
B -->|是| C[使用Trufflehog检测]
B -->|否| D[使用熵值检测]
C --> E[返回验证/未验证的密钥发现]
D --> F[正则匹配已知模式]
D --> G[Shannon熵阈值分析]
F --> H[高熵值判断]
G --> H
H --> I[返回高熵密钥发现]
```
#### Trufflehog 集成
当 Trufflehog 可用时，检测器调用 Trufflehog 的解码器对文件进行深度扫描：
```python
_raw_findings.append(
RawFinding(
tool="secrets",
rule_id=f"trufflehog-{detector_name.lower().replace(' ', '-')}",
file=file_path,
line=line_num,
severity="CRITICAL",
message=(
f"{'Verified' if verified else 'Potential'} secret detected "
f"[{detector_name}] — value starts: {redacted}"
),
code_snippet=redacted,
metadata={
"detector": detector_name,
"verified": verified,
"decoder": str(obj.get("DecoderName", "")),
},
)
)
```
资料来源：[packages/scanner/scanner/detectors/secrets.py:20-35]()
#### 熵值检测（后备方案）
当 Trufflehog 不可用时，使用基于 Shannon 熵的启发式检测方法：
- **跳过目录**：`.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build` 等
- **跳过文件扩展名**：二进制文件（图片、压缩包等）被排除
- **熵值阈值**：当字符串的 Shannon 熵超过阈值时，判定为可能的密钥
```python
if entropy >= _ENTROPY_THRESHOLD:
findings.append(
RawFinding(
tool="secrets",
rule_id="high-entropy-secret",
file=str(path),
line=line_num,
severity="CRITICAL",
message=(
f"High-entropy string in secret assignment "
f"(Shannon entropy={entropy:.2f}) — likely a hardcoded credential"
),
code_snippet=_redact_line(line_text, candidate),
metadata={"entropy": round(entropy, 3)},
)
)
```
资料来源：[packages/scanner/scanner/detectors/secrets.py:60-80]()
### Bandit 检测器
**文件位置**：`packages/scanner/scanner/detectors/bandit.py`
Bandit 是一个专门用于检测 Python 代码安全问题的静态分析工具，Velonus 通过 subprocess 调用 Bandit 并解析其 JSON 输出。
| 特性 | 说明 |
|------|------|
| 工具类型 | 本地 Python 安全扫描器 |
| 依赖 | Bandit 必须安装（`pip install bandit`） |
| 输出格式 | JSON → RawFinding |
### Semgrep 检测器
**文件位置**：`packages/scanner/scanner/detectors/semgrep.py`
Semgrep 是一个支持多语言的静态分析工具，Velonus 使用其 Python 规则集进行扫描。
#### 可用性检查
检测器首先检查 Semgrep 是否在 PATH 中可用：
```python
def _semgrep_available(self) -> bool:
try:
subprocess.run(
["semgrep", "--version"],
capture_output=True,
check=False,
timeout=10,
)
return True
except FileNotFoundError:
return False
```
资料来源：[packages/scanner/scanner/detectors/semgrep.py:50-60]()
#### 执行命令
```bash
semgrep scan --config p/python --json --quiet --metrics=off
```
| 参数 | 说明 |
|------|------|
| `--config p/python` | 使用 Python 规则集 |
| `--json` | 输出 JSON 格式 |
| `--quiet` | 抑制非必要输出 |
| `--metrics=off` | 禁用遥测数据收集 |
### pip-audit 检测器
**文件位置**：`packages/scanner/scanner/detectors/pip_audit.py`
pip-audit 是 Python 生态系统的依赖漏洞扫描工具，用于检测项目依赖中已知的 CVE 漏洞。
#### 严重级别映射
| CVSS 分数范围 | 严重级别 |
|--------------|---------|
| 9.0 - 10.0 | CRITICAL |
| 7.0 - 8.9 | HIGH |
| 4.0 - 6.9 | MEDIUM |
| 0.1 - 3.9 | LOW |
| 0 | INFO |
#### CVSS 分数提取
```python
def _extract_cvss_score(cvss_list: Any) -> float | None:
"""Extract the highest CVSS v3 base score from pip-audit's cvss array.
pip-audit embeds CVSS data as a list of score objects::
[{"type": "CVSS_V3", "score": "CVSS:3.1/...", "base_score": 7.5}]
"""
```
资料来源：[packages/scanner/scanner/detectors/pip_audit.py:80-95]()
### Safety 检测器
**文件位置**：`packages/scanner/scanner/detectors/safety.py`
Safety 是另一个 Python 依赖安全扫描工具，与 pip-audit 互补使用以获得更全面的覆盖。
#### 必需字段
解析 Safety 输出时，以下字段为必需：
| 字段 | 类型 | 说明 |
|------|------|------|
| `vulnerability_id` | `str` | 漏洞唯一标识 |
| `package_name` | `str` | 受影响包名 |
| `analyzed_version` | `str` | 当前安装版本 |
缺少必需字段的条目将被跳过并记录警告：
```python
try:
vuln_id: str = str(entry["vulnerability_id"])
package_name: str = str(entry["package_name"])
installed_version: str = str(entry["analyzed_version"])
except (KeyError, TypeError) as exc:
logger.warning("safety v2: skipping malformed entry: %s", exc)
return None
```
资料来源：[packages/scanner/scanner/detectors/safety.py:45-60]()
## 数据模型
### RawFinding
各检测器输出的原始发现对象，包含工具特定的数据结构。
| 字段 | 类型 | 说明 |
|------|------|------|
| `tool` | `str` | 来源工具名称 |
| `rule_id` | `str` | 规则标识符 |
| `file` | `str` | 关联文件路径 |
| `line` | `int` | 代码行号 |
| `severity` | `str` | 严重级别 |
| `message` | `str` | 人类可读的消息 |
| `code_snippet` | `str` | 相关代码片段 |
| `metadata` | `dict` | 额外元数据 |
### NormalizedFinding
规范化的统一发现格式，支持跨扫描去重和一致输出。
**文件位置**：`packages/normalizer/models.py`
```mermaid
classDiagram
class NormalizedFinding {
+str id
+str tool
+str rule_id
+list~str~ cwe
+list~str~ owasp
+Severity severity
+Confidence confidence
+str file
+int line_start
+int line_end
+str code_snippet
+str message
+bool fix_available
+bool suppressed
+datetime first_seen
}
class Severity {
<>
CRITICAL
HIGH
MEDIUM
LOW
INFO
}
class Confidence {
<>
HIGH
MEDIUM
LOW
}
```
#### 字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `str` | 确定性 SHA-256 指纹（tool+file+line+rule_id 前16位） |
| `cwe` | `list[str]` | CWE 列表，如 `["CWE-89"]` |
| `owasp` | `list[str]` | OWASP 分类，如 `["A03:2021"]` |
| `fix_available` | `bool` | 是否有可用修复版本 |
| `suppressed` | `bool` | 是否被规则抑制 |
资料来源：[packages/normalizer/models.py:35-60]()
## 使用方式
### 命令行接口
```bash
# 扫描当前目录
velonus scan ./
# 指定路径扫描
velonus scan ./my-project
# 仅显示高危和严重问题
velonus scan ./ --severity high
# JSON 格式输出
velonus scan ./ --format json
# SARIF 格式（用于 GitHub Security）
velonus scan ./ --format sarif -o results.sarif
# 详细输出模式
velonus scan ./ --verbose
```
### 退出码
| 退出码 | 含义 |
|--------|------|
| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 问题 |
| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 问题 |
退出码 `1` 用于 CI/CD 流程中阻断合并。
### CI/CD 集成
#### GitHub Actions
```yaml
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install velonus-cli
run: pip install -e apps/cli
- name: Run security scan
run: velonus scan ./ --severity high
```
#### Pre-commit Hook
```yaml
repos:
- repo: local
hooks:
- id: velonus-scan
name: Velonus Security Scan
entry: velonus scan
args: ["./", "--severity", "high"]
language: system
pass_filenames: false
```
## 扩展开发
### 添加新检测器
要添加新的安全检测工具，需要创建新的检测器类并实现标准接口：
1. **创建检测器类**，继承基础 Detector 接口
2. **实现 `scan()` 方法**，返回 `list[RawFinding]`
3. **处理工具不存在**的情况，返回空列表
4. **在管道中注册**检测器
```python
class NewToolDetector:
def scan(self, target: Path) -> list[RawFinding]:
"""执行新工具扫描并返回标准化发现"""
if not self._tool_available():
logger.warning("new-tool not found — skipping")
return []
return self._run_scan(target)
```
### 严重级别过滤
管道支持按严重级别过滤结果：
| 级别 | 颜色 | 用途 |
|------|------|------|
| CRITICAL | 红色 | 硬编码密钥、RCE、认证绕过 |
| HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |
| MEDIUM | 黄色 | XSS、弱加密、路径遍历 |
| LOW | 蓝色 | 不安全默认值、次要配置错误 |
| INFO | 灰色 | 样式问题、信息性说明 |
## 相关资源
- 源码仓库：[Velonus GitHub](https://github.com/AliAmmar15/Velonus)
- 问题反馈：[GitHub Issues](https://github.com/AliAmmar15/Velonus/issues)
- 安全漏洞：请参阅 [SECURITY.md](SECURITY.md)（不要公开提交）
---
## 数据标准化模块
### 相关页面
相关主题：[安全扫描器管道](#page-scanner), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/normalizer/normalizer.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/normalizer.py)
- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)
- [packages/normalizer/deduplicator.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/deduplicator.py)
- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)
- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
# 数据标准化模块
## 模块概述
数据标准化模块（Normalizer Package）是 Velonus 安全扫描系统的核心组件之一，负责将来自不同安全工具的扫描结果统一转换为标准的发现数据格式。该模块位于 `packages/normalizer/` 目录下，是连接扫描检测器与输出格式化器的桥梁。
数据标准化模块的主要职责包括：
1. **格式统一**：将 Bandit、Semgrep、pip-audit、Safety、Secrets 等多种扫描工具的原始输出转换为统一的 `NormalizedFinding` 数据结构
2. **数据去重**：基于确定性哈希算法消除跨扫描的重复发现
3. **元数据丰富**：提取 CWE、OWASP 等安全分类标准，增强发现数据的可分析性
## 架构概览
```mermaid
graph TD
subgraph 扫描检测器层
B[Bandit]
SG[Semgrep]
PA[pip-audit]
SA[Safety]
ST[Secrets]
end
subgraph 数据标准化模块
RF[RawFinding 原始发现]
FN[FindingNormalizer 标准化器]
DF[DeduplicationFilter 去重过滤器]
NF[NormalizedFinding 标准发现]
end
subgraph 输出格式化层
TF[Terminal 终端]
JF[JSON]
SF[SARIF]
end
B --> RF
SG --> RF
PA --> RF
SA --> RF
ST --> RF
RF --> FN
FN --> DF
DF --> NF
NF --> TF
NF --> JF
NF --> SF
```
## 核心数据模型
### RawFinding（原始发现）
`RawFinding` 是各扫描检测器产生的原始数据结构，包含扫描工具返回的原始字段信息。
| 字段 | 类型 | 说明 |
|------|------|------|
| `tool` | `str` | 工具名称（bandit/semgrep/pip-audit/safety/secrets） |
| `rule_id` | `str` | 规则标识符 |
| `file` | `str` | 发现的文件路径 |
| `line` | `int` | 代码行号 |
| `severity` | `str` | 严重程度（CRITICAL/HIGH/MEDIUM/LOW/INFO） |
| `message` | `str` | 发现描述信息 |
| `code_snippet` | `str` | 相关代码片段 |
| `metadata` | `dict` | 工具特定的元数据 |
资料来源：[packages/scanner/scanner/detectors/semgrep.py:90-110]()
### NormalizedFinding（标准发现）
`NormalizedFinding` 是整个系统的规范发现格式，所有扫描工具的输出最终都会转换为这种格式。
```python
@dataclass
class NormalizedFinding:
id: str # deterministic: sha256(tool+file+line+rule_id)[:16]
tool: str # "bandit"|"semgrep"|"secrets"|"pip-audit"|"safety"
rule_id: str
cwe: list[str] # e.g. ["CWE-89"]
owasp: list[str] # e.g. ["A03:2021"]
severity: Severity # CRITICAL | HIGH | MEDIUM | LOW | INFO
confidence: Confidence # HIGH | MEDIUM | LOW
file: str
line_start: int
line_end: int
code_snippet: str
message: str
fix_available: bool = False
suppressed: bool = False
first_seen: datetime = field(default_factory=datetime.utcnow)
```
**关键设计特点**：
- **确定性 ID**：通过 SHA-256 哈希算法 `sha256(tool + file + line + rule_id)` 生成前 16 位十六进制字符作为唯一标识符，确保相同漏洞在不同扫描中具有相同 ID
- **安全分类**：标准化提取 CWE 和 OWASP 分类标识符
- **时间追踪**：记录首次发现时间 `first_seen`
资料来源：[packages/normalizer/models.py:46-70]()
### Severity 枚举
严重程度等级定义：
| 枚举值 | 说明 | 使用场景 |
|--------|------|----------|
| `CRITICAL` | 严重 | 硬编码密钥、RCE、认证绕过 |
| `HIGH` | 高危 | SQL 注入、命令注入、不安全反序列化 |
| `MEDIUM` | 中危 | XSS、弱加密、路径遍历 |
| `LOW` | 低危 | 不安全默认值、轻微配置错误 |
| `INFO` | 信息 | 代码风格问题、信息性备注 |
### Confidence 枚举
置信度等级反映工具的检测确定性（非严重程度）：
| 枚举值 | 说明 |
|--------|------|
| `HIGH` | 高置信度，检测结果可靠 |
| `MEDIUM` | 中置信度，需人工复核 |
| `LOW` | 低置信度，建议验证 |
## 标准化流程
### 完整处理流水线
```mermaid
sequenceDiagram
participant 检测器 as 扫描检测器
participant 标准化器 as FindingNormalizer
participant 去重器 as DeduplicationFilter
participant 格式化器 as 输出格式化器
检测器->>检测器: 执行安全扫描
检测器->>标准化器: 产出 RawFinding 列表
标准化器->>标准化器: 验证必填字段
标准化器->>标准化器: 映射严重程度
标准化器->>标准化器: 提取 CWE/OWASP
标准化器->>标准化器: 生成确定性 ID
标准化器->>去重器: 产出 NormalizedFinding
去重器->>去重器: 计算哈希指纹
去重器->>去重器: 过滤重复发现
去重器->>格式化器: 返回去重后列表
```
### FindingNormalizer 标准化器
`FindingNormalizer` 负责将 `RawFinding` 转换为 `NormalizedFinding`，主要处理逻辑包括：
1. **字段验证**：检查必填字段（tool、rule_id、file）是否存在
2. **严重程度映射**：将各工具的原始严重程度值映射到规范枚举值
3. **分类提取**：从元数据中提取 CWE 和 OWASP 分类代码
4. **ID 生成**：计算确定性哈希作为唯一标识符
```python
# 严重程度映射示例（Semgrep → 规范值）
_SEVERITY_MAP = {
"ERROR": "HIGH",
"WARNING": "MEDIUM",
"INFO": "INFO",
}
```
资料来源：[packages/scanner/scanner/detectors/semgrep.py:40-50]()
### CWE 提取逻辑
CWE（Common Weakness Enumeration）分类通过正则表达式从工具元数据中提取：
```python
_CWE_EXTRACT_RE = re.compile(r"CWE-\d+", re.IGNORECASE)
def _extract_cwe(raw: Any) -> list[str]:
"""从 semgrep 元数据提取规范化 CWE 标识符"""
if not raw:
return []
items: list[Any] = raw if isinstance(raw, list) else [raw]
# 正则匹配并去重
...
return result # e.g. ["CWE-78", "CWE-89"]
```
**提取规则**：
- 支持字符串或列表格式的输入
- 正则表达式匹配：`CWE-\d+`（不区分大小写）
- 自动规范化为首字母大写格式（如 `cwe-78` → `CWE-78`）
- 自动去重，保持插入顺序
资料来源：[packages/scanner/scanner/detectors/semgrep.py:25-45]()
### OWASP 提取逻辑
OWASP（Open Web Application Security Project）分类的提取方式与 CWE 类似：
```python
_OWASP_EXTRACT_RE = re.compile(r"A\d{2}(?::\d{4})?", re.IGNORECASE)
def _extract_owasp(raw: Any) -> list[str]:
"""从 semgrep 元数据提取规范化 OWASP 代码"""
# 支持多种格式：["A03:2021 - Injection"] | "A03:2021" | []
...
return result # e.g. ["A03:2021"]
```
**支持的格式**：
- 完整描述：`["A03:2021 - Injection"]`
- 纯代码格式：`"A03:2021"`
- 空值：`[]` 或 `None`
资料来源：[packages/scanner/scanner/detectors/semgrep.py:55-80]()
## 去重机制
### DeduplicationFilter
`DeduplicationFilter` 组件负责跨扫描会话的发现去重，基于 `NormalizedFinding.id` 字段进行哈希比对。
```mermaid
graph LR
A[发现 A: ID=abc123] --> B{已见过?}
C[发现 C: ID=abc123] --> B
D[发现 B: ID=def456] --> B
B -->|是| E[跳过]
B -->|否| F[保留并记录]
```
**去重策略**：
| 策略 | 说明 |
|------|------|
| 基于 ID 去重 | 同一工具、文件、行号、规则的发现视为同一漏洞 |
| 跨工具去重 | 不同工具检测到同一漏洞时合并 |
| 时间窗口 | 保留首次发现时间 `first_seen` |
**确定性 ID 算法**：
```
ID = SHA-256(tool + file + line + rule_id)[:16]
```
这种设计确保：
- 相同漏洞在不同扫描中产生相同 ID
- 便于历史数据比对和趋势分析
- 支持增量扫描和变更检测
资料来源：[packages/normalizer/models.py:50-55]()
## 与扫描管道的集成
### ScanPipeline 集成架构
`ScanPipeline` 是扫描流水线的主协调器，集成数据标准化模块的处理流程：
```python
from normalizer.deduplicator import DeduplicationFilter
from normalizer.normalizer import FindingNormalizer
from normalizer.models import NormalizedFinding, Severity
class ScanPipeline:
async def run(self, target: Path, verbose: bool = False) -> list[NormalizedFinding]:
# 1. 并行运行所有检测器
raw_findings = await self._run_all_detectors(target)
# 2. 标准化处理
normalizer = FindingNormalizer()
normalized = normalizer.normalize(raw_findings)
# 3. 去重过滤
deduplicator = DeduplicationFilter()
deduplicated = deduplicator.filter(normalized)
return deduplicated
```
**并行检测器支持**：
| 检测器 | 工具类型 | 输出格式 |
|--------|----------|----------|
| `BanditRunner` | 静态分析 | JSON |
| `SemgrepRunner` | 静态分析 | JSON |
| `PipAuditRunner` | 依赖审计 | JSON |
| `SafetyRunner` | 依赖审计 | JSON |
| `SecretsDetector` | 密钥扫描 | 自定义 |
资料来源：[packages/scanner/scanner/pipeline.py:1-50]()
### 执行时序
```mermaid
sequenceDiagram
participant CLI as CLI 命令行
participant Pipeline as ScanPipeline
participant Detector as 检测器集合
participant Normalizer as FindingNormalizer
participant Deduplicator as DeduplicationFilter
CLI->>Pipeline: scan(path, options)
Pipeline->>Detector: 并行执行 5 个检测器
Detector-->>Pipeline: RawFinding[]
Pipeline->>Normalizer: normalize(raw_findings)
Normalizer-->>Pipeline: NormalizedFinding[]
Pipeline->>Deduplicator: filter(findings)
Deduplicator-->>Pipeline: 去重后列表
Pipeline-->>CLI: 最终结果
```
## 输出格式支持
标准化后的 `NormalizedFinding` 支持多种输出格式：
| 格式 | 用途 | 文件 |
|------|------|------|
| `terminal` | 交互式彩色输出（默认） | Rich 表格 + 严重程度徽章 |
| `json` | 机器可读格式 | 管道集成 |
| `sarif` | GitHub Code Scanning | SARIF 规范 |
### SARIF 格式化
SARIF（Static Analysis Results Interchange Format）格式化器将标准发现转换为符合 OASIS SARIF 规范的输出：
```python
def _rule_id_to_name(rule_id: str) -> str:
"""将 rule_id 转换为 PascalCase 显示名称"""
base = rule_id.split("/")[-1]
return "".join(word.capitalize() for word in base.replace("-", "_").split("_"))
```
**转换示例**：
- `generic-api-key` → `GenericApiKey`
- `secrets/aws-access-key-id` → `AwsAccessKeyId`
资料来源：[apps/cli/shield/formatters/sarif.py:40-60]()
## 错误处理与容错
### 字段缺失处理
标准化器对缺失字段采用宽松策略：
| 场景 | 处理方式 | 日志级别 |
|------|----------|----------|
| 必填字段缺失 | 跳过该发现 | WARNING |
| 可选字段缺失 | 使用默认值 | DEBUG |
| JSON 解析失败 | 返回空列表 | ERROR |
```python
try:
check_id: str = str(entry["check_id"])
path: str = str(entry["path"])
start_line: int = int(entry["start"]["line"])
except (KeyError, ValueError, TypeError) as exc:
logger.warning("Skipping malformed semgrep result: %s", exc)
return None # 不中断整个扫描
```
### 日志记录
模块使用 Python 标准 `logging` 模块，遵循以下日志级别约定：
| 级别 | 使用场景 |
|------|----------|
| DEBUG | 详细流程信息、解析计数 |
| INFO | 扫描完成摘要、处理统计 |
| WARNING | 单个发现跳过（不影响整体） |
| ERROR | 致命错误（如 JSON 解析失败） |
## 配置与扩展
### 严重程度阈值
用户可通过 CLI 参数控制最低显示严重程度：
```bash
velonus scan ./ --severity high # 仅显示 HIGH 和 CRITICAL
velonus scan ./ --severity medium # 显示 MEDIUM 及以上
```
### 新增检测器集成
集成新的扫描工具需要：
1. 实现检测器类，返回 `RawFinding` 列表
2. 在 `ScanPipeline` 中注册检测器
3. 配置严重程度映射（如需要）
4. 添加 CWE/OWASP 元数据提取（如适用）
```python
# packages/scanner/scanner/detectors/custom.py
from .secrets import RawFinding
class CustomRunner:
def run(self, target: Path) -> list[RawFinding]:
# 实现扫描逻辑
...
```
## 模块依赖关系
```mermaid
graph TD
normalizer -->|无外部依赖| stdlib
scanner_pipeline --> normalizer
scanner_pipeline --> detectors
scanners --> scanner_pipeline
cli --> scanners
cli --> formatters
formatters --> normalizer
```
**依赖约束**：
- `normalizer` 包不依赖其他业务包，仅依赖 Python 标准库
- `scanner` 包依赖 `normalizer` 包
- `apps/cli` 依赖 `scanner` 和 `normalizer`
## 总结
数据标准化模块是 Velonus 安全扫描系统的基础设施层，承担着格式统一、数据丰富和去重过滤的关键职责。通过 `RawFinding` → `NormalizedFinding` → 去重过滤的处理流程，系统实现了：
- **多工具统一**：不同扫描工具的输出具有一致的内部表示
- **跨扫描去重**：基于确定性哈希避免重复报告
- **分类标准化**：CWE/OWASP 分类的自动提取和规范化
- **格式灵活**：支持多种输出格式适应不同使用场景
该模块的解耦设计确保了系统的可扩展性，便于后续集成新的安全检测工具。
---
## AI 引擎
### 相关页面
相关主题：[API 服务系统](#page-api), [GitHub 集成](#page-github-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)
- [packages/ai-engine/remediation_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/remediation_engine.py)
- [packages/ai-engine/prompts.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/prompts.py)
- [packages/ai-engine/cache.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/cache.py)
- [apps/api/shield_api/services/ai_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/ai_service.py)
**注意**：上述文件在本次检索的上下文（START_OF_CONTEXT 至 END_OF_CONTEXT）中未找到相关内容。本页说明基于项目文档（README.md、apps/cli/README.md、CONTRIBUTING.md）中的 AI 引擎相关描述以及项目路线图生成。如需获取完整的 AI 引擎实现细节，请确保在检索上下文中包含 `packages/ai-engine/` 目录下的所有源码文件。
# AI 引擎
## 概述
AI 引擎（AI Engine）是 Velonus 安全扫描平台的核心智能组件，属于项目的 **Phase 2 — AI Layer** 阶段。根据项目路线图，AI 引擎的主要职责包括：
- **漏洞优先级排序**（AI prioritization）
- **可利用性评分**（Exploitability scoring）
- **修复建议生成**（Fix generation）
资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
AI 引擎作为 Phase 2 的核心功能，目前处于 **Building（开发中）** 状态，尚未完成实现。
资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
## 架构组件
根据源码文件结构，AI 引擎由以下核心模块组成：
| 模块 | 文件路径 | 功能描述 |
|------|----------|----------|
| **Context Engine** | `packages/ai-engine/context_engine.py` | 上下文分析引擎，处理安全发现的上下文信息 |
| **Remediation Engine** | `packages/ai-engine/remediation_engine.py` | 修复引擎，生成漏洞修复建议 |
| **Prompts** | `packages/ai-engine/prompts.py` | LLM 提示词管理，定义与 AI 交互的模板 |
| **Cache** | `packages/ai-engine/cache.py` | 缓存模块，存储 AI 响应以减少 API 调用 |
| **AI Service** | `apps/api/shield_api/services/ai_service.py` | API 服务层，暴露 AI 引擎能力给前端 |
## 工作流程
AI 引擎的整体工作流程如下：
```mermaid
graph TD
A[安全扫描结果] --> B[Context Engine
上下文分析]
B --> C{缓存命中?}
C -->|是| D[返回缓存结果]
C -->|否| E[Remediation Engine
修复建议生成]
E --> F[LLM API 调用]
F --> G[Cache 存储结果]
G --> D
D --> H[AI Service API]
H --> I[前端展示/用户交互]
style A fill:#f9f,stroke:#333,stroke-width:2px
style I fill:#ccf,stroke:#333,stroke-width:2px
style F fill:#ffc,stroke:#333,stroke-width:2px
```
## 核心功能模块
### 1. Context Engine（上下文引擎）
`context_engine.py` 负责处理安全发现的上下文信息。该模块分析扫描结果中的漏洞详情，包括：
- 漏洞类型与严重程度
- 受影响文件的代码上下文
- 相关依赖信息
- 历史修复记录
### 2. Remediation Engine（修复引擎）
`remediation_engine.py` 是 AI 引擎的核心组件，负责生成针对具体漏洞的修复建议。其主要功能包括：
- 分析漏洞根因
- 生成代码级别的修复方案
- 提供多种修复策略选项
- 评估修复方案的安全性与兼容性
### 3. Prompts（提示词管理）
`prompts.py` 集中管理所有与 LLM 交互的提示词模板，包括：
- 漏洞分析提示词
- 修复建议生成提示词
- 可利用性评估提示词
- 优先级排序提示词
### 4. Cache（缓存模块）
`cache.py` 实现响应缓存机制，用于：
- 减少重复的 LLM API 调用
- 加速相同漏洞的响应时间
- 降低 API 使用成本
### 5. AI Service（API 服务）
`apps/api/shield_api/services/ai_service.py` 是 AI 引擎对外暴露的 REST API 服务，提供：
- 漏洞分析接口
- 修复建议获取接口
- 批量处理接口
## 可利用性评分
AI 引擎通过对漏洞的多个维度进行分析来计算可利用性评分：
| 维度 | 说明 |
|------|------|
| **CVSS 基础分数** | 来自漏洞数据库的标准评分 |
| **代码上下文** | 漏洞代码在实际项目中的使用方式 |
| **攻击面** | 漏洞是否暴露在外部可访问的范围 |
| **现有利用条件** | 是否存在已知的利用工具或脚本 |
| **修复难度** | 应用修复方案的复杂程度 |
资料来源：[apps/cli/README.md - Severity Levels](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
## 修复建议生成
AI 引擎生成的修复建议包含以下层次：
### 代码级修复
- 直接的代码修改建议
- 安全的 API 替换方案
- 参数化/规范化建议
### 依赖级修复
- 需要升级的包版本
- 替代库建议
- 配置修改指导
### 架构级建议
- 安全设计模式推荐
- 架构重构方向
- 防御纵深建议
## 与 Phase 1 的关系
AI 引擎建立在 Phase 1 扫描管道的基础之上：
```mermaid
graph LR
A[Phase 1
扫描管道] -->|RawFinding| B[AI Engine
上下文分析]
B --> C[可利用性评分]
C --> D[优先级排序]
D --> E[修复建议生成]
A -->|Bandit| A1[代码安全]
A -->|Semgrep| A2[代码模式]
A -->|pip-audit| A3[依赖漏洞]
A -->|Safety| A4[包安全]
A -->|Secrets| A5[密钥泄露]
style A fill:#9f9,stroke:#333,stroke-width:2px
style B fill:#f96,stroke:#333,stroke-width:2px
```
Phase 1 已实现的扫描工具包括：
| 工具 | 用途 | 状态 |
|------|------|------|
| Bandit | Python 代码安全分析 | ✅ 完成 |
| Semgrep | 多语言代码模式扫描 | ✅ 完成 |
| pip-audit | pip 依赖漏洞审计 | ✅ 完成 |
| Safety | Python 包安全扫描 | ✅ 完成 |
| Secrets | 密钥/凭证检测 | ✅ 完成 |
资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
## Phase 3 与 Phase 4 的集成
AI 引擎的能力将在后续阶段被进一步利用：
### Phase 3 — GitHub PR 集成
AI 引擎生成的修复建议将通过 PR 内联评论直接展示给开发者，实现一键接受修复的功能。
资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
### Phase 4 — Web 仪表盘
AI 引擎的分析结果将集成到 Web 仪表盘中，提供：
- 扫描历史趋势
- 发现趋势分析
- 团队安全态势概览
## 认证与配置
AI 引擎的功能需要通过 Velonus API 访问，认证方式采用 Clerk 浏览器 OAuth 流程：
```bash
velonus auth login # 认证登录
velonus auth logout # 清除存储的凭证
velonus auth status # 查看当前认证状态
```
配置管理通过以下命令实现：
```bash
velonus config show # 显示当前配置
velonus config set api_url https://api.velonus.dev # 设置 API 地址
```
资料来源：[apps/cli/README.md - velonus auth](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
> ⚠️ **注意**：认证和配置功能目前处于 Phase 0 的存根（stubbed）状态，将在 Phase 2 API 后端上线后完全可用。
## 开发指南
根据 CONTRIBUTING.md 的要求，AI 引擎代码开发需遵循以下规范：
| 要求 | 说明 |
|------|------|
| **类型检查** | 必须通过 mypy strict 模式检查 |
| **代码格式** | 必须通过 ruff format 检查 |
| **代码检查** | 必须通过 ruff check 检查 |
| **测试覆盖** | 所有新功能必须有对应的单元测试 |
| **PR 规范** | 每个 PR 不超过 400 行 diff |
资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)
## 当前状态
| 项目 | 状态 | 说明 |
|------|------|------|
| CLI 基础框架 | ✅ 完成 | Phase 0 |
| 扫描管道 | ✅ 完成 | Phase 1 |
| AI 上下文引擎 | 🔨 开发中 | Phase 2 |
| 可利用性评分 | 🔨 开发中 | Phase 2 |
| 修复建议生成 | 🔨 开发中 | Phase 2 |
| GitHub PR 集成 | 🔜 计划中 | Phase 3 |
| Web 仪表盘 | 🔜 计划中 | Phase 4 |
资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
## 相关文档
- [README 主页](../README.md) — 项目概览与快速开始
- [CLI 使用指南](../apps/cli/README.md) — 命令行工具详细文档
- [贡献指南](../CONTRIBUTING.md) — 开发者贡献规范
- [安全策略](../SECURITY.md) — 安全漏洞报告流程
---
## GitHub 集成
### 相关页面
相关主题：[AI 引擎](#page-ai-engine), [部署与基础设施](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)
- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)
- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)
# GitHub 集成
## 概述
Velonus 的 GitHub 集成功能旨在将安全扫描能力深度嵌入到 GitHub 的开发工作流中。根据项目路线图，GitHub 集成属于 **Phase 3** 阶段，规划功能包括 PR 内联评论（inline review comments）和一键修复建议（one-click fix suggestions）。资料来源：[README.md:70-73]()
当前版本（Phase 0-1）已实现与 GitHub 的基础集成能力，主要通过以下方式：
- **GitHub Actions 工作流** 集成
- **SARIF 格式输出** 与 GitHub Security tab 兼容
- **Pre-commit hook** 支持
## 架构概览
```mermaid
graph TD
A[开发者提交代码] --> B[GitHub Actions 触发]
B --> C[velonus scan 命令执行]
C --> D{SARIF 输出}
D --> E[github/codeql-action/upload-sarif]
E --> F[GitHub Security tab]
D --> G{Exit Code}
G --> H[exit 0: 无高危漏洞]
G --> I[exit 1: 发现 HIGH/CRITICAL]
I --> J[PR 合并被阻断]
subgraph "Phase 3 规划功能"
K[PR 内联评论]
L[一键修复建议]
K --> M[velonus auth 认证]
L --> M
end
```
## 当前支持的集成方式
### GitHub Actions 工作流集成
Velonus 可作为 GitHub Actions 工作流中的安全扫描步骤运行。通过 `github/codeql-action/upload-sarif@v4` 将扫描结果上传至 GitHub Security tab。
#### 基础工作流配置
```yaml
name: Velonus Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install velonus-cli
run: pip install -e apps/cli
- name: Run security scan
run: velonus scan ./ --severity high
# exits 1 if HIGH or CRITICAL findings are found — blocks the merge
```
资料来源：[apps/cli/README.md:89-111]()
#### 带 SARIF 输出的工作流配置
```yaml
- name: Velonus security scan
run: velonus scan . --sarif -o velonus-results.sarif
- name: Upload to GitHub Security tab
uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: velonus-results.sarif
```
资料来源：[README.md:50-60]()
### Pre-commit Hook 集成
Velonus 可配置为 pre-commit hook，在每次提交前自动执行安全扫描。
#### 配置示例
在项目根目录的 `.pre-commit-config.yaml` 中添加：
```yaml
repos:
- repo: local
hooks:
- id: velonus-scan
name: Velonus Security Scan
entry: velonus scan
args: ["./", "--severity", "high"]
language: system
pass_filenames: false
```
资料来源：[apps/cli/README.md:113-122]()
### Pre-commit Hook 配置参数
| 参数 | 说明 |
|------|------|
| `entry` | 执行命令 `velonus scan` |
| `args` | 扫描参数，`["/", "--severity", "high"]` 表示扫描当前目录且仅显示 HIGH 及以上级别 |
| `language` | `system` 表示使用系统环境中的 Python |
| `pass_filenames` | `false` 表示不传递文件名给扫描器 |
## SARIF 输出格式
### 概述
SARIF（Static Analysis Results Interchange Format）是与 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具兼容的标准输出格式。Velonus 通过 `--sarif` 参数生成 SARIF 文件。
资料来源：[README.md:45-47]()
### SARIF 文件生成命令
| 命令 | 说明 |
|------|------|
| `velonus scan ./ --sarif` | 生成默认路径 `results/velonus.sarif` |
| `velonus scan ./ -o results/velonus.sarif` | 指定自定义输出路径 |
资料来源：[README.md:48-52]()
### SARIF 规则 ID 转换
Velonus 在生成 SARIF 输出时，会将内部规则 ID 转换为 PascalCase 格式的显示名称，便于在 GitHub 界面中阅读。
```python
def _rule_id_to_name(rule_id: str) -> str:
"""Convert a rule_id to a PascalCase display name for SARIF.
Strips any tool-prefix segment (e.g. ``"secrets/generic-api-key"``
becomes ``"GenericApiKey"``).
"""
base = rule_id.split("/")[-1]
return "".join(word.capitalize() for word in base.replace("-", "_").split("_"))
```
资料来源：[apps/cli/shield/formatters/sarif.py:51-62]()
### 目录 URI 规范
SARIF 规范要求目录 URI 必须以斜杠结尾，Velonus 在生成输出时遵循此规范：
```python
def _dir_uri(path: Path) -> str:
"""Return a file:// URI for a directory, ensuring a trailing slash.
SARIF spec §3.14.14 requires directory URIs to end with ``/``.
"""
uri = path.as_uri()
return uri if uri.endswith("/") else uri + "/"
```
资料来源：[apps/cli/shield/formatters/sarif.py:28-37]()
## CI/CD 阻断机制
### 退出码机制
Velonus 使用退出码（exit code）作为 CI/CD 管道中的安全门禁：
| 退出码 | 含义 | CI 行为 |
|--------|------|---------|
| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别漏洞 | 允许合并 |
| `1` | 扫描完成，发现一个或多个 HIGH/CRITICAL 级别漏洞 | 阻断合并 |
资料来源：[apps/cli/README.md:73-76]()
### 严重级别定义
| 徽章 | 级别 | 颜色 | 典型场景 |
|------|------|------|---------|
| 🔴 | `CRITICAL` | 粗体红色 | 硬编码密钥、RCE、认证绕过 |
| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |
| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |
| 🔵 | `LOW` | 蓝色 | 不安全默认值、次要配置问题 |
| ⚪ | `INFO` | 灰色 | 样式问题、信息性备注 |
资料来源：[apps/cli/README.md:61-69]()
### 推荐配置策略
```bash
# 仅显示 HIGH 和 CRITICAL 级别
velonus scan ./ --severity high
# 导出 JSON 格式（高危过滤）
velonus scan ./ --format json --severity high > findings.json
```
## Phase 3 规划功能
根据项目路线图，Phase 3 将实现更深入的 GitHub 集成：
| 功能 | 说明 | 状态 |
|------|------|------|
| **PR 内联评论** | 在代码行级别展示漏洞信息 | 🔜 规划中 |
| **一键修复建议** | 提供自动化修复建议并支持一键接受 | 🔜 规划中 |
### Phase 3 依赖的前置条件
Phase 3 功能需要以下基础设施支持：
1. **认证系统**：`velonus auth` 命令（Phase 2 实现）
```bash
velonus auth login # 通过 Clerk 浏览器 OAuth 流程认证
velonus auth logout # 清除存储的凭证
velonus auth status # 显示当前认证状态
```
资料来源：[apps/cli/README.md:77-92]()
2. **配置文件管理**：`velonus config` 命令（Phase 2 实现）
```bash
velonus config show # 显示当前配置
velonus config set api_url https://api.velonus.dev # 设置配置值
```
资料来源：[apps/cli/README.md:93-104]()
## 输出格式对比
| 格式 | 用途 | GitHub 兼容 |
|------|------|------------|
| `terminal`（默认） | 交互式终端输出，彩色 Rich 表格 | ❌ |
| `json` | 管道传输或程序化处理 | ❌ |
| `sarif` | GitHub Code Scanning 集成 | ✅ |
资料来源：[README.md:40-60]()
## 相关扫描器与 GitHub 集成的漏洞数据
Velonus 的各个扫描器均支持提取与 GitHub 漏洞数据库兼容的元数据：
### Semgrep CWE/OWASP 提取
```python
def _extract_cwe(raw: Any) -> list[str]:
"""Extract canonical CWE identifiers from semgrep rule metadata."""
# 规范化格式：cwe-78 → CWE-78
for match in _CWE_EXTRACT_RE.findall(str(item)):
normalised = match.upper()
```
资料来源：[packages/scanner/scanner/detectors/semgrep.py:45-58]()
### Safety CVSS 评分
```python
def _cvss_to_severity(score: float | None) -> str:
"""Convert CVSS v3 base score to severity level."""
if score is None:
return "MEDIUM"
if score >= _CVSS_CRITICAL:
return "CRITICAL"
# ...
```
资料来源：[packages/scanner/scanner/detectors/safety.py:80-90]()
## 项目阶段概览
| 阶段 | 状态 | 交付内容 |
|------|------|---------|
| Phase 0 — 基础 | ✅ 完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |
| Phase 1 — 扫描管道 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、Safety |
| Phase 2 — AI 层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复生成 |
| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |
| Phase 4 — Web 仪表盘 | 🔴 未开始 | Web UI、扫描历史、漏洞趋势 |
资料来源：[README.md:65-73]()
## 常见问题
### Q: 如何仅扫描并显示高危漏洞？
```bash
velonus scan ./ --severity high
```
### Q: 如何将扫描结果上传到 GitHub Security tab？
1. 生成 SARIF 文件：`velonus scan ./ --sarif -o velonus.sarif`
2. 在 workflow 中使用 `github/codeql-action/upload-sarif@v4`
### Q: Velonus 如何在 CI 中实现阻断？
当发现 HIGH 或 CRITICAL 级别漏洞时，Velonus 返回退出码 `1`，GitHub Actions 将该步骤标记为失败，从而阻断 PR 合并。
---
## 部署与基础设施
### 相关页面
相关主题：[系统架构](#page-architecture), [API 服务系统](#page-api)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)
- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)
- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)
- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
> **注意**：查询中提到的 `infra/docker/` 目录下的 Docker 相关文件（Dockerfile.api、Dockerfile.worker、docker-compose.yml）以及 `apps/api/pyproject.toml` 未包含在当前上下文检索结果中，以下内容基于可检索的源码文件进行分析。
# 部署与基础设施
## 概述
Velonus 是一个 Python 编写的安全扫描工具，采用单体仓库（monorepo）结构管理多个包和应用。项目当前处于 Alpha 阶段，CLI 工具已完成并可直接使用，但完整的 API 后端服务仍在开发中。资料来源：[README.md]()
当前项目分为以下主要组件：
| 组件 | 路径 | 用途 | 状态 |
|------|------|------|------|
| CLI 应用 | `apps/cli/` | 命令行入口，提供 `velonus scan` 等命令 | ✅ 已完成 |
| Scanner 包 | `packages/scanner/` | 安全扫描引擎，包含多个检测器 | ✅ 已完成 |
| Normalizer 包 | `packages/normalizer/` | 发现标准化与去重 | ✅ 已完成 |
| API 服务 | `apps/api/` | AI 层与认证后端 | 🔨 Phase 2 开发中 |
| Worker 服务 | - | 异步任务处理 | 规划中 |
## 项目架构
Velonus 采用分层架构设计，CLI 作为前端入口调用 Scanner 包中的各个检测器。
```mermaid
graph TD
A[用户终端] --> B[velonus CLI]
B --> C[ScanPipeline]
C --> D1[SecretsDetector]
C --> D2[BanditRunner]
C --> D3[SemgrepRunner]
C --> D4[PipAuditRunner]
C --> D5[SafetyRunner]
D1 --> E[FindingNormalizer]
D2 --> E
D3 --> E
D4 --> E
D5 --> E
E --> F[DeduplicationFilter]
F --> G[NormalizedFinding]
G --> H[Formatter]
H --> I[终端输出 / JSON / SARIF]
```
## Scanner 包架构
`packages/scanner/scanner/pipeline.py` 定义了核心扫描管道，所有检测器并行执行：
```python
from .detectors.bandit import BanditRunner
from .detectors.pip_audit import PipAuditRunner
from .detectors.safety import SafetyRunner
from .detectors.secrets import SecretsDetector
from .detectors.semgrep import SemgrepRunner
```
检测器执行顺序（对应索引 0-4）：
```mermaid
graph LR
subgraph 检测器层
S[SecretsDetector
索引 0]
B[BanditRunner
索引 1]
SG[SemgrepRunner
索引 2]
PA[PipAuditRunner
索引 3]
SF[SafetyRunner
索引 4]
end
```
### 检测器类型定义
```python
_ParallelRunner = BanditRunner | SemgrepRunner | PipAuditRunner | SafetyRunner
```
资料来源：[packages/scanner/scanner/pipeline.py:33]()
## 开发环境部署
### 环境要求
| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| Python | 3.10+ | 最低支持版本 |
| uv | 最新版 | 包管理工具 |
资料来源：[CONTRIBUTING.md]()
### 安装步骤
```bash
# 1. 克隆仓库
git clone https://github.com/AliAmmar15/Velonus
cd Velonus
# 2. 安装所有工作区包和开发依赖
uv sync --all-extras --dev
# 3. 激活虚拟环境
source .venv/bin/activate # macOS / Linux
.venv\Scripts\Activate.ps1 # Windows PowerShell
# 4. 以可编辑模式安装 CLI 和 Scanner
pip install -e apps/cli
pip install -e packages/scanner
pip install -e packages/normalizer
```
资料来源：[CONTRIBUTING.md]()
### 验证安装
```bash
velonus --help
velonus scan ./apps/cli/shield
```
## 本地运行
### CLI 扫描命令
```bash
# 扫描当前目录
velonus scan ./
# 指定扫描路径
velonus scan ./my-project
# 仅显示高危及以上级别
velonus scan ./ --severity high
# 详细输出
velonus scan ./ --verbose
# JSON 格式输出
velonus scan ./ --format json
# SARIF 格式输出（用于 GitHub Security）
velonus scan ./ --format sarif
```
### 输出格式
| 格式 | 用途 | 说明 |
|------|------|------|
| `terminal` | 交互式使用 | 带颜色的 Rich 表格，含徽章、路径、行号 |
| `json` | 管道集成 | 适合传递给其他工具或存储结果 |
| `sarif` | CI/CD 集成 | 兼容 GitHub Code Scanning，Phase 1 可用 |
资料来源：[apps/cli/README.md]()
### 退出码
| 退出码 | 含义 |
|--------|------|
| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |
| `1` | 发现 HIGH 或 CRITICAL 级别问题（用作 CI 门禁） |
资料来源：[apps/cli/README.md]()
## CI/CD 集成
### GitHub Actions 集成
```yaml
name: Velonus Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install velonus-cli
run: pip install -e apps/cli
- name: Run security scan
run: velonus scan ./ --severity high
```
资料来源：[apps/cli/README.md]()
### Pre-commit Hook
```yaml
repos:
- repo: local
hooks:
- id: velonus-scan
name: Velonus Security Scan
entry: velonus scan
args: ["./", "--severity", "high"]
language: system
pass_filenames: false
```
## 扫描管道技术细节
### PipAuditRunner
`packages/scanner/scanner/detectors/pip_audit.py` 负责检测依赖漏洞：
- 执行 `pip-audit --format json --progress-spinner off` 子命令
- 超时设置：120 秒（考虑 PyPI advisory DB 网络延迟）
- 返回码处理：退出码 2+ 表示真实错误，退出码 1 表示发现漏洞（正常处理）
```python
cmd: list[str] = [
"pip-audit",
"--format",
"json",
"--progress-spinner",
"off",
]
if req_file is not None:
cmd.extend(["-r", str(req_file)])
else:
cmd.append("--local")
```
资料来源：[packages/scanner/scanner/detectors/pip_audit.py]()
### SafetyRunner
`packages/scanner/scanner/detectors/safety.py` 支持两种格式：
| Safety 版本 | 输出格式 | 数据结构 |
|-------------|----------|----------|
| v2 (>=2.0) | JSON 对象 | `{"vulnerabilities": [...]}` |
| v1 (<2.0) | JSON 列表 | `[vuln_id, pkg, version, ...]` |
CVSS 评分提取逻辑：
```python
cvss_score: float | None = _extract_cvss_v2(entry.get("severity"))
severity: str = _cvss_to_severity(cvss_score)
```
资料来源：[packages/scanner/scanner/detectors/safety.py]()
### SemgrepRunner
`packages/scanner/scanner/detectors/semgrep.py` 使用 Semgrep 公共 Python 规则集：
- 配置：`p/python`
- 命令：`semgrep scan --config p/python --json --quiet --metrics=off `
- 退出码 1 = 正常发现（JSON 仍有效），退出码 2+ = 错误
```python
RULESET: str = "p/python"
def _semgrep_available(self) -> bool:
try:
subprocess.run(
["semgrep", "--version"],
capture_output=True,
check=False,
timeout=10,
)
return True
except FileNotFoundError:
return False
```
资料来源：[packages/scanner/scanner/detectors/semgrep.py]()
## 阶段性规划
| 阶段 | 状态 | 内容 |
|------|------|------|
| Phase 0 — 基础 | ✅ 已完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |
| Phase 1 — 扫描管道 | ✅ 已完成 | Secret 检测、Bandit、Semgrep、pip-audit、SARIF |
| Phase 2 — AI 层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复建议生成 |
| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |
| Phase 4 — Web 仪表板 | 🔴 未开始 | Web UI、扫描历史、趋势分析 |
资料来源：[README.md]()
## 本地开发命令
### 运行测试
```bash
# 运行全部测试（当前 367 个测试，覆盖 6 个文件）
pytest apps/cli/tests/
# 详细输出
pytest apps/cli/tests/ -v
```
### 代码检查
```bash
# Ruff 检查和格式化检查
ruff check . && ruff format --check .
# 自动格式化
ruff format .
# 类型检查（严格模式）
mypy apps/cli/shield --strict --ignore-missing-imports
mypy packages/normalizer --strict --ignore-missing-imports
mypy packages/scanner --strict --ignore-missing-imports
```
> 所有新代码必须通过 mypy 严格模式检查，PR 中引入 `type: ignore` 注释需在代码注释中提供说明。
资料来源：[CONTRIBUTING.md]()
## 未来部署架构（规划中）
当 Phase 2 API 后端上线后，系统架构预计如下：
```mermaid
graph TD
subgraph 前端层
CLI[velonus CLI]
Web[Web Dashboard
Phase 4]
end
subgraph 后端服务
API[API Server
Phase 2]
Worker[Async Worker
Phase 3+]
end
subgraph 数据层
DB[(Database)]
Cache[(Cache)]
end
CLI -->|REST API| API
Web -->|REST API| API
API --> DB
API --> Cache
Worker --> DB
Worker --> Cache
subgraph 认证
Clerk[Clerk OAuth]
end
API --> Clerk
```
### 认证命令（Phase 2 规划）
```bash
velonus auth login # 通过 Clerk 浏览器 OAuth 流程认证
velonus auth logout # 清除存储的凭证
velonus auth status # 显示当前认证状态
```
### 配置管理（Phase 2 规划）
```bash
velonus config show # 打印当前配置
velonus config set api_url # 设置配置值
```
> Phase 0/1 中这些命令为存根实现，将在 Phase 2 API 上线后完整实现。
## 项目结构总览
```
Velonus/
├── apps/
│ ├── cli/ # CLI 应用入口
│ │ ├── shield/ # CLI 核心模块
│ │ ├── formatters/ # 输出格式化器（terminal/json/sarif）
│ │ └── tests/ # 测试套件（367 个测试）
│ └── api/ # API 后端（Phase 2）
│ └── pyproject.toml # API 依赖配置
├── packages/
│ ├── scanner/ # 扫描引擎
│ │ └── scanner/
│ │ ├── detectors/ # 检测器实现
│ │ │ ├── bandit.py
│ │ │ ├── semgrep.py
│ │ │ ├── pip_audit.py
│ │ │ ├── safety.py
│ │ │ └── secrets.py
│ │ └── pipeline.py # 扫描管道编排
│ └── normalizer/ # 发现标准化与去重
├── infra/
│ └── docker/ # Docker 部署配置（待实现）
│ ├── Dockerfile.api
│ ├── Dockerfile.worker
│ └── docker-compose.yml
└── pyproject.toml # 根工作区配置
```
## 依赖管理
项目使用 `uv` 作为包管理工具，所有包的依赖定义在各自目录的 `pyproject.toml` 中：
- 根目录 `pyproject.toml`：定义 uv 工作区
- `apps/cli/pyproject.toml`：CLI 应用依赖
- `packages/scanner/pyproject.toml`：扫描器依赖（包含 bandit、semgrep 等）
- `packages/normalizer/pyproject.toml`：标准化器依赖
安装所有 extras 和 dev 依赖：
```bash
uv sync --all-extras --dev
```
## 安全门禁配置
Velonus 设计为可作为安全 CI 门禁使用：
```bash
# 硬性门禁：发现 HIGH 或 CRITICAL 时退出码为 1
velonus scan ./ --severity high
```
建议在 CI 中配置：
1. 使用 `--severity high` 过滤，仅阻断高危及以上问题
2. 定期使用 `--severity info` 全量扫描
3. 导出 SARIF 格式上传至 GitHub Security 标签页
---
> 本页基于 Velonus 项目当前阶段的源码文件编写。API 和 Worker 的 Docker 容器化部署配置将在 Phase 2/3 实现后补充。
---
## 使用指南与最佳实践
### 相关页面
相关主题：[项目概述](#page-overview), [CLI 命令行工具](#page-cli), [安全扫描器管道](#page-scanner)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)
- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)
- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)
- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)
- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)
# 使用指南与最佳实践
Velonus 是一款针对 Python 项目开发的自动化安全扫描工具，专注于代码中的敏感信息检测、依赖漏洞发现以及静态代码分析。本页面将详细介绍 Velonus 的安装配置、基本使用、输出格式、CI/CD 集成以及开发最佳实践，帮助用户和贡献者高效地使用该工具。
---
## 1. 快速入门
### 1.1 安装方式
Velonus 支持多种安装方式，用户可根据实际需求选择合适的方案。
```bash
# 从源码安装 CLI（开发模式）
pip install -e apps/cli
# 验证安装
velonus --version
```
资料来源：[apps/cli/README.md:1]()
### 1.2 首次扫描
安装完成后，即可对本地项目执行安全扫描。以下是最基础的扫描命令：
```bash
# 扫描当前目录
velonus scan ./
# 扫描指定项目路径
velonus scan ./my-python-project
```
Velonus 默认会递归扫描目标路径下的所有 Python 源文件，并调用多个安全检测工具协同工作。
资料来源：[README.md:1]()
---
## 2. 核心命令详解
### 2.1 `velonus scan` 命令
`scan` 命令是 Velonus 的核心功能，用于执行完整的安全扫描流水线。
```
velonus scan [PATH] [OPTIONS]
```
#### 参数与选项说明
| 参数/选项 | 默认值 | 说明 |
|---|---|---|
| `PATH` | `.` | 要扫描的项目或文件路径 |
| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |
| `--severity`, `-s` | `info` | 最低显示严重级别：`critical`、`high`、`medium`、`low`、`info` |
| `--verbose`, `-v` | off | 显示解析后的目标路径及额外详情 |
| `--help` | - | 显示帮助信息并退出 |
资料来源：[apps/cli/README.md:1]()
#### 常用扫描示例
```bash
# 显示所有级别（默认行为）
velonus scan ./
# 仅显示高危和严重问题
velonus scan ./ --severity high
# 显示详细输出
velonus scan ./ --verbose
# 导出 JSON 格式
velonus scan ./ --format json
# 高危以上问题导出 JSON 到文件
velonus scan ./ --format json --severity high > findings.json
```
资料来源：[apps/cli/README.md:1]()
### 2.2 `velonus auth` 命令（Phase 2）
身份认证命令用于与 Velonus API 进行交互，目前在 Phase 0 阶段为存根实现，将在 Phase 2 阶段完整实现。
```
velonus auth [COMMAND]
```
| 子命令 | 说明 |
|---|---|
| `velonus auth login` | 通过 Clerk 浏览器 OAuth 流程认证 |
| `velonus auth logout` | 清除存储的凭据 |
| `velonus auth status` | 显示当前认证状态 |
资料来源：[apps/cli/README.md:1]()
### 2.3 `velonus config` 命令（Phase 2）
本地配置管理命令用于设置和查看 CLI 配置参数，同样在 Phase 2 阶段完整实现。
```
velonus config [COMMAND]
```
| 子命令 | 说明 |
|---|---|
| `show` | 打印当前配置 |
| `set ` | 设置配置值 |
资料来源：[apps/cli/README.md:1]()
---
## 3. 输出格式详解
Velonus 支持三种输出格式，适用于不同场景的需求。
### 3.1 Terminal 格式（默认）
终端格式使用 Rich 库渲染带有颜色和严重级别徽章的表格，包含文件路径、行号、规则 ID 和消息描述，是交互式使用场景的最佳选择。
```
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃
```
资料来源：[apps/cli/README.md:1]()
### 3.2 JSON 格式
适用于管道传输或结果存储的纯 JSON 格式：
```bash
# 格式化输出
velonus scan ./ --format json | python -m json.tool
# 写入文件
velonus scan ./ --format json > scan-results.json
```
资料来源：[apps/cli/README.md:1]()
### 3.3 SARIF 格式
SARIF（Static Analysis Results Interchange Format）是一种标准化的静态分析结果交换格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等主流 SAST 工具。该格式将在 Phase 1 阶段完整支持。
```bash
# 输出 SARIF 到默认路径
velonus scan ./ --sarif
# 输出到自定义路径
velonus scan ./ -o results/velonus.sarif
```
资料来源：[README.md:1]()
---
## 4. 严重级别体系
Velonus 定义了五个严重级别，帮助用户快速识别和优先处理安全问题。
| 徽章 | 级别 | 颜色 | 适用场景 |
|---|---|---|---|
| 🔴 | `CRITICAL` | 粗体红色 | 硬编码凭据、RCE、认证绕过 |
| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |
| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |
| 🔵 | `LOW` | 蓝色 | 不安全默认值、轻微配置错误 |
| ⚪ | `INFO` | 灰色 | 代码风格问题、信息性备注 |
资料来源：[apps/cli/README.md:1]()
### 退出码规则
| 退出码 | 含义 |
|---|---|
| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |
| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |
当检测到 HIGH 或 CRITICAL 问题时返回退出码 1，这是设计上的意图，可用于 CI 环境作为合并门禁。
资料来源：[apps/cli/README.md:1]()
---
## 5. 扫描流水线架构
Velonus 的扫描功能由多个检测器协同工作完成，形成完整的静态分析流水线。
```mermaid
graph TD
A[velonus scan] --> B[目标路径解析]
B --> C[Secret 检测 TruffleHog]
B --> D[Bandit 静态分析]
B --> E[Semgrep 代码模式扫描]
B --> F[pip-audit 依赖审计]
B --> G[Safety 依赖检查]
C --> H[NormalizedFinding 聚合]
D --> H
E --> H
F --> H
G --> H
H --> I[格式化输出]
I --> J[Terminal]
I --> K[JSON]
I --> L[SARIF]
```
### 5.1 Secret 检测（secrets.py）
Secret 检测器负责发现代码中硬编码的敏感凭据，包括：
- **TruffleHog 检测器**：使用正则模式匹配已知类型的密钥（如 AWS 访问密钥、API 令牌等）
- **熵值检测器**：当 TruffleHog 无法识别时，使用香农熵算法检测高熵字符串，识别潜在凭据
```python
if entropy >= _ENTROPY_THRESHOLD:
findings.append(
RawFinding(
tool="secrets",
rule_id="high-entropy-secret",
severity="CRITICAL",
message=f"High-entropy string in secret assignment (Shannon entropy={entropy:.2f})"
)
)
```
资料来源：[packages/scanner/detectors/secrets.py:1]()
### 5.2 Semgrep 静态分析
Semgrep 检测器运行 Semgrep 规则集 `p/python`，执行代码模式匹配和自定义规则扫描。
```python
def scan(self, target: Path) -> list[RawFinding]:
"""Run semgrep on target and return findings as RawFinding instances."""
if not self._semgrep_available():
logger.warning("semgrep not found on PATH")
return []
return self._run_semgrep(target)
```
Semgrep 以 JSON 格式输出结果，Velonus 提取关键字段并映射到标准化格式：
- CWE（Common Weakness Enumeration）标识符
- OWASP 分类代码
- 规则级别和置信度
资料来源：[packages/scanner/scanner/detectors/semgrep.py:1]()
### 5.3 pip-audit 依赖审计
pip-audit 检测器扫描 Python 项目的依赖包，识别已知漏洞。
```python
cvss_score: float | None = _extract_cvss_score(cvss_list)
severity: str = _cvss_to_severity(cvss_score)
```
输出包含：
- CVE 或漏洞 ID
- 受影响包名及版本
- 修复版本建议
- CVSS v3 评分
```python
message = (
f"[{display_id}] {package_name}=={package_version} has a known vulnerability.{fix_hint}"
)
```
资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1]()
### 5.4 Safety 依赖检查
Safety 检测器提供额外的依赖漏洞检测能力，支持两种输出格式：
- **v2 格式**：字典结构，包含 `vulnerabilities` 列表
- **v1 格式**：列表结构，每个元素为 5 元组
```python
# Format A: safety >= 2.0
if isinstance(data, dict):
vulns = data.get("vulnerabilities", [])
findings = [_parse_entry_v2(entry, ...) for entry in vulns]
# Format B: safety < 2.0
if isinstance(data, list):
findings = [_parse_entry_v1(entry, ...) for entry in data]
```
资料来源：[packages/scanner/scanner/detectors/safety.py:1]()
---
## 6. CI/CD 集成指南
### 6.1 GitHub Actions 集成
在项目中添加 `.github/workflows/security.yml` 以自动执行安全扫描：
```yaml
name: Velonus Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install velonus-cli
run: pip install -e apps/cli
- name: Run security scan
run: velonus scan ./ --severity high
# exits 1 if HIGH or CRITICAL findings are found
```
资料来源：[apps/cli/README.md:1]()
### 6.2 SARIF 上传到 GitHub Security
将扫描结果上传到 GitHub Security tab：
```yaml
- name: Velonus security scan
run: |
pip install velonus
velonus scan . --sarif -o velonus.sarif
- name: Upload to GitHub Security tab
uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: velonus.sarif
```
资料来源：[README.md:1]()
### 6.3 Pre-commit 钩子配置
在 `.pre-commit-config.yaml` 中配置本地钩子：
```yaml
repos:
- repo: local
hooks:
- id: velonus-scan
name: Velonus Security Scan
entry: velonus scan
args: ["./", "--severity", "high"]
language: system
pass_filenames: false
```
资料来源：[README.md:1]()
---
## 7. 开发贡献指南
### 7.1 开发环境配置
克隆仓库后，安装开发依赖：
```bash
git clone https://github.com/AliAmmar15/Velonus
cd Velonus
pip install -e apps/cli
```
资料来源：[CONTRIBUTING.md:1]()
### 7.2 代码格式化
项目使用 `ruff` 进行代码格式化和检查：
```bash
# 检查格式问题
ruff format --check .
# 自动格式化所有文件
ruff format .
```
建议在提交前同时运行检查和格式化：
```bash
ruff check . && ruff format .
```
资料来源：[CONTRIBUTING.md:1]()
### 7.3 类型检查
项目使用 mypy 严格模式进行类型检查：
```bash
mypy apps/cli/shield --strict --ignore-missing-imports
mypy packages/normalizer --strict --ignore-missing-imports
mypy packages/scanner --strict --ignore-missing-imports
```
所有新代码必须通过 mypy 严格检查，PR 中引入 `type: ignore` 注释时需要在代码注释中提供说明。
资料来源：[CONTRIBUTING.md:1]()
### 7.4 PR 提交规范
#### 提交信息格式
```
: <简短祈使句描述>
Types: feat | fix | refactor | test | docs | infra | chore
```
#### 示例
```
feat: add semgrep CWE extraction from rule metadata
fix: handle bandit exit code 2 on bad target path
test: cover pip-audit CVSS v3 threshold edge cases
docs: add CONTRIBUTING.md and issue templates
```
资料来源：[CONTRIBUTING.md:1]()
#### PR 审核准则
| 准则 | 说明 |
|---|---|
| **单一职责** | 每个 PR 只做一个功能或修复 |
| **测试要求** | 所有新功能必须有对应的单元测试 |
| **代码规范** | 必须通过 ruff 和 mypy 检查 |
| **目标分支** | 所有 PR 合并到 `main` 分支 |
| **规模控制** | 建议 PR 少于 400 行 diff |
| **代码质量** | 不接受 AI 生成的占位符代码 |
资料来源：[CONTRIBUTING.md:1]()
---
## 8. 项目路线图
| 阶段 | 状态 | 内容 |
|---|---|---|
| **Phase 0** — 基础框架 | ✅ 完成 | CLI 框架、Rich 输出、NormalizedFinding 模型 |
| **Phase 1** — 扫描流水线 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、Safety、SARIF |
| **Phase 2** — AI 增强层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复建议生成 |
| **Phase 3** — GitHub 集成 | 🔴 未开始 | PR 行内评论、一键修复建议 |
| **Phase 4** — Web 控制台 | 🔴 未开始 | Web UI、扫描历史、问题趋势分析 |
资料来源：[README.md:1]()
---
## 9. 最佳实践总结
### 9.1 扫描策略建议
| 场景 | 推荐配置 |
|---|---|
| 交互式开发 | `velonus scan ./ --severity info`（显示所有问题） |
| CI/CD 门禁 | `velonus scan ./ --severity high`（仅阻断高危） |
| 报告生成 | `velonus scan ./ --format json --severity high > findings.json` |
| 详细调试 | `velonus scan ./ --verbose` |
### 9.2 性能优化
- 定期运行扫描，避免累积大量问题
- 使用 `--severity` 参数过滤低优先级问题以减少噪音
- 在 CI 中仅扫描变更文件路径（需配合 pre-commit 钩子）
### 9.3 安全配置
- 敏感项目建议集成 pre-commit 钩子，在提交前强制扫描
- 使用 GitHub Actions 自动扫描主分支和 PR
- 定期更新本地依赖以获取最新的漏洞数据库
---
## 10. 常见问题
**Q: 为什么扫描结果中没有 Semgrep 输出？**
A: 请确认 Semgrep 已正确安装：`semgrep --version`。Velonus 会自动跳过未安装的工具并输出警告。
**Q: 如何处理误报？**
A: 当前版本建议使用 `--severity` 参数过滤低置信度问题。Phase 2 将提供基于 AI 的可利用性评分来辅助判断。
**Q: SARIF 格式有什么用途？**
A: SARIF 是静态分析结果的标准格式，可导入 GitHub Security tab、VS Code SARIF Viewer 等工具，实现可视化展示和趋势追踪。
---
---
## Doramagic 踩坑日志
项目：aliammar15/velonus
摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)。
## 1. 安装坑 · 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_62cdd9b76ac447b8b11064afda81fb9a | https://github.com/AliAmmar15/Velonus/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium
## 6. 安全/权限坑 · 来源证据：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3a9b7a6193ee4ea289f4dc4a12f6a0c1 | https://github.com/AliAmmar15/Velonus/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | issue_or_pr_quality=unknown
## 8. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | release_recency=unknown