简介

Velonus 是一个本地优先的 Python 安全扫描工具（SAST），专注于在软件开发周期中自动检测安全漏洞和敏感信息泄露。该项目当前处于 Alpha 阶段，已实现核心功能并可在生产环境中使用。资料来源：README.md:1

Velonus 的核心设计理念是将多个业界领先的开源安全工具整合到一个统一的命令行界面中，通过标准化输出格式和可配置的严重级别过滤，帮助开发团队在本地环境和 CI/CD 流水线中快速识别和修复安全问题。

核心价值主张

系统架构

整体架构图

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                     # 项目配置

扫描能力矩阵

已集成的安全工具

严重级别定义

资料来源：apps/cli/README.md:1

命令行接口

核心命令

# 扫描当前目录
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

命令行参数表

资料来源：apps/cli/README.md:1

退出码约定

退出码 1 的设计是有意为之，用于将扫描结果作为 CI/CD 流水线的合并门禁条件。资料来源：apps/cli/README.md:1

输出格式详解

Terminal 格式（默认）

使用 Rich 库渲染彩色表格，包含严重级别徽章、文件路径、行号、规则 ID 和详细信息。

JSON 格式

适用于管道集成和结果存储：

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

velonus scan ./ --format sarif

数据模型

RawFinding

各检测器输出的原始发现对象，包含以下核心字段：

NormalizedFinding

经过标准化处理的统一发现对象，格式统一后由格式化器渲染。

开发规范

代码质量要求

项目采用严格的代码质量标准：

资料来源：CONTRIBUTING.md:1

严格模式要求

所有新代码必须通过 mypy strict 模式检查，零错误。引入 type: ignore 注释需要在代码注释中提供说明。资料来源：CONTRIBUTING.md:1

Pull Request 规范

CI/CD 集成

GitHub Actions 集成

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 配置

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

技术栈

总结

Velonus 是一个功能完整的 Python 安全扫描工具，通过统一界面整合多个业界领先的安全检测工具，为开发团队提供从本地开发到 CI/CD 流水线的全流程安全保障。项目采用严格的代码质量标准，确保长期可维护性，同时保持开放的贡献文化，欢迎社区参与改进。

概述

Velonus 是一个模块化的安全扫描平台，采用分层架构设计。系统由 CLI 前端、扫描管道、多个检测器后端和输出格式化器组成。核心设计理念是将扫描逻辑与用户界面分离，使每个检测工具（Bandit、Semgrep、pip-audit、Safety、TruffleHog）能够独立工作，同时通过统一的 RawFinding 数据模型汇聚结果。

整体架构

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 目录，负责用户交互和结果展示。

CLI 支持的输出格式：

资料来源：apps/cli/README.md

扫描管道

扫描管道 (packages/scanner/scanner/pipeline.py) 是核心编排组件，负责：

1. 依次调用各个检测器
2. 收集并归一化扫描结果
3. 处理检测器的执行超时和错误

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，实现两层检测：

# 熵值阈值常量
_ENTROPY_THRESHOLD = 4.5

当 TruffleHog 未安装时，自动降级到熵值分析模式。检测结果包含：

• detector: 检测器类型名称
• verified: 是否经过 TruffleHog 验证
• decoder: 使用的解码器名称

资料来源：packages/scanner/scanner/detectors/secrets.py:1-150

#### Semgrep 检测器

位于 packages/scanner/scanner/detectors/semgrep.py，使用 p/python 规则集。

Semgrep 返回 1 表示发现漏洞（正常行为），返回 2+ 才表示错误。

资料来源：packages/scanner/scanner/detectors/semgrep.py:1-50

#### 依赖漏洞检测器

##### pip-audit 检测器

位于 packages/scanner/scanner/detectors/pip_audit.py，检测 Python 依赖中的已知漏洞。

关键元数据字段：

##### Safety 检测器

位于 packages/scanner/scanner/detectors/safety.py，支持两种输出格式：

CVSS 评分提取逻辑处理嵌套的 severity 字典结构。

资料来源：packages/scanner/scanner/detectors/safety.py:1-100

数据模型

RawFinding

所有检测器返回统一的 RawFinding 对象：

严重级别

资料来源：apps/cli/README.md

格式化输出

SARIF 格式化器

位于 apps/cli/shield/formatters/sarif.py，实现 SARIF 2.1.0 规范。

关键转换函数：

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，强制添加尾部斜杠。

输出格式映射

API 层

位于 apps/api/shield_api/main.py，为 Phase 2 及后续功能预留。

当前阶段：

资料来源：README.md

部署架构

Docker 部署

项目提供 Docker Compose 配置用于容器化部署：

# infra/docker/docker-compose.yml 结构
services:
  shield-api:     # API 服务
  scanner:        # 扫描引擎
  dashboard:      # Web UI (Phase 4)

CI/CD 集成

系统设计支持多种 CI 场景：

Velonus 在发现 HIGH 或 CRITICAL 漏洞时返回退出码 1，可作为 CI 门禁。

贡献与质量保障

项目要求严格的代码质量标准：

PR 规范：

• 每个 PR 只做一个改动
• 必须包含测试
• Diff 行数建议小于 400
• 禁止 AI 生成的占位代码

资料来源：CONTRIBUTING.md

工作流程图

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 仪表板。

概述

Velonus CLI 是一个基于 Python 的命令行安全扫描工具，采用 Typer 框架构建，为开发者提供本地化的应用安全测试能力。CLI 工具支持多种安全扫描器集成，包括密钥检测、代码漏洞扫描、依赖漏洞审计等，并能输出多种格式的结果用于不同场景。

CLI 的核心定位是本地优先，即所有核心扫描功能在不依赖后端 API 的情况下完全可用。身份验证和云端功能（如 AI 优先级排序、修复建议生成）则在后续阶段（Phase 2+）逐步实现。 资料来源：apps/cli/shield/main.py:1-17

架构设计

整体架构

graph TD
    A["velonus CLI 入口<br/>(main.py)"] --> B["Typer 应用层"]
    B --> C["命令模块<br/>(commands/)"]
    
    C --> D["scan 命令"]
    C --> E["auth 命令"]
    C --> F["config 命令"]
    
    D --> G["scanner 包<br/>(packages/scanner)"]
    G --> H["检测器引擎"]
    
    H --> I["secrets.py<br/>密钥检测"]
    H --> J["semgrep.py<br/>代码模式扫描"]
    H --> K["pip_audit.py<br/>依赖漏洞审计"]
    H --> L["safety.py<br/>安全依赖检查"]
    
    D --> M["格式化器<br/>(formatters/)"]
    M --> N["terminal.py<br/>终端输出"]
    M --> O["sarif.py<br/>SARIF 格式"]

模块职责

命令详解

velonus scan

velonus scan 是核心命令，用于在本地路径上运行安全扫描管道。

#### 命令语法

velonus scan [PATH] [OPTIONS]

#### 参数与选项

#### 使用示例

# 扫描当前目录
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

#### 退出码

退出码 1 是有意设计的，可作为 CI/CD 门禁阻止合并。 资料来源：apps/cli/README.md:1-80

velonus auth

认证命令用于与 Velonus API 建立连接，目前处于 Phase 2 阶段（桩代码状态）。

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 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

适合管道传递或存储结果。

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 输出：

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 以 / 结尾：

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

严重级别

建议使用 --severity high 仅显示需要立即处理的问题；使用 --severity info（默认）查看所有发现。

扫描管道

扫描管道由多个检测器组成，每个检测器负责特定类型的安全问题扫描。

secrets — 密钥检测

支持两种检测模式：

1. TruffleHog 集成：调用 TruffleHog3 二进制进行已知密钥模式检测
2. 熵值检测回退：基于 Shannon 熵阈值检测高熵字符串

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 规则集。

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 <target>``."""

Semgrep 以退出码 1 返回发现时，不视为错误——JSON 输出仍然完全有效并正常解析。退出码 2+ 才表示真正的错误。 资料来源：packages/scanner/scanner/detectors/semgrep.py:1-50

pip-audit — 依赖漏洞审计

解析 pip-audit 的 JSON 输出，提取漏洞信息、CWE 分类和修复版本建议。

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 元素列表

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

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：

repos:
  - repo: local
    hooks:
      - id: velonus-scan
        name: Velonus Security Scan
        entry: velonus scan
        args: ["./", "--severity", "high"]
        language: system
        pass_filenames: false

发展阶段路线图

代码质量要求

项目对 CLI 代码有严格的代码质量标准：

Ruff 格式化

# 检查格式化
ruff format --check .

# 自动格式化
ruff format .

Mypy 严格模式

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 占位代码：每个函数必须功能完整且经过测试

概述

Velonus 的 API 服务系统（apps/api/shield_api/）是整个安全扫描平台的核心后端服务，负责接收扫描请求、协调安全工具执行、管理扫描结果，并提供 AI 驱动的漏洞修复建议。该系统基于 FastAPI 构建，采用模块化架构设计，将功能划分为路由（routers）、服务（services）、中间件（middleware）和后台任务（background workers）四个层次。

根据项目路线图，API 服务系统属于 Phase 2 — AI Layer 阶段的核心组件，目前处于 Building（构建中）状态。资料来源：README.md

系统架构

整体架构图

graph TD
    A[客户端 / CLI] -->|HTTP REST API| B[API Gateway]
    B --> C[认证中间件<br/>auth.py]
    B --> D[限流中间件<br/>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<br/>后台扫描任务]
    G2 --> H2[ai_worker.py<br/>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

核心组件说明

认证与授权

认证机制

Velonus API 使用 Clerk 进行身份认证，支持浏览器 OAuth 流程。资料来源：apps/cli/README.md

认证中间件 auth.py 负责：

• 验证用户访问令牌的有效性
• 提取用户身份信息并注入请求上下文
• 保护需要认证的 API 端点

sequenceDiagram
    participant Client
    participant API
    participant Clerk
    
    Client->>API: 请求 + Bearer Token
    API->>Clerk: 验证 Token
    Clerk-->>API: Token 有效 / 无效
    API->>Client: 200 OK / 401 Unauthorized

CLI 认证命令

注意：认证功能在 Phase 2 阶段完全可用，Phase 0 阶段仅为存根实现。资料来源：apps/cli/README.md

限流策略

rate_limit.py 中间件实现了 API 请求限流机制，用于：

• 防止 API 滥用和资源耗尽
• 确保多租户环境下的公平使用
• 保护后端扫描任务不被过度触发

限流策略的具体参数和阈值需参考实际配置文件或环境变量设置。

扫描服务

扫描流程

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[返回扫描结果]

支持的安全扫描器

扫描退出码语义

退出码 1 是有意设计的，用于 CI/CD 流程中的门禁检查。资料来源：apps/cli/README.md

AI 修复服务

AI 层架构

Phase 2 的核心功能是 AI 驱动的漏洞优先级排序和修复建议生成。资料来源：README.md

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

核心数据结构，用于统一不同安全工具的输出格式：

@dataclass
class NormalizedFinding:
    tool: str                    # 来源工具名称
    rule_id: str                 # 规则标识符
    file: str                    # 文件路径
    line: int                    # 代码行号
    severity: str                # 严重级别
    message: str                 # 人类可读消息
    code_snippet: str            # 代码片段
    metadata: dict               # 额外元数据

严重级别定义

资料来源：apps/cli/README.md

API 端点概览

扫描相关

发现结果

修复建议

GitHub 集成

输出格式

支持的格式

SARIF 输出

SARIF（Static Analysis Results Interchange Format）输出与 GitHub Security 标签兼容，可直接上传至 GitHub 进行漏洞展示。资料来源：apps/cli/shield/formatters/sarif.py

部署配置

环境变量

配置管理

# 查看当前配置
velonus config show

# 设置配置项
velonus config set api_url https://api.velonus.dev

开发与贡献

代码质量要求

PR 指南

1. 单功能原则：每个 PR 只包含一个功能或修复
2. 测试要求：新增功能必须附带对应的单元测试
3. 代码规范：必须通过 ruff 和 mypy 检查
4. PR 描述：清晰说明变更内容和动机
5. 代码行数：建议 PR 变更行数小于 400 行

资料来源：CONTRIBUTING.md

路线图

资料来源：README.md

状态说明

Alpha 提示：Velonus 当前处于 Alpha 阶段，API 服务系统仍在积极开发中，可能存在不稳定性和 API 变更。请关注 GitHub Issues 获取最新动态并报告问题。

概述

安全扫描器管道（Scanner Pipeline）是 Velonus 安全扫描工具的核心组件，负责协调和执行多种安全扫描工具，对代码仓库进行全面的安全漏洞检测。管道设计遵循模块化架构，将不同的安全检测工具（检测器）作为独立的插件集成到统一的工作流中。

管道的主要职责包括：

• 并行执行：协调多个安全扫描工具的并发执行
• 结果收集：统一收集各检测器的原始发现（RawFinding）
• 数据规范化：将不同工具的输出格式转换为统一的 NormalizedFinding 数据结构
• 格式输出：支持多种输出格式（终端、JSON、SARIF）

资料来源：packages/scanner/scanner/pipeline.py

架构设计

整体架构

Velonus 的安全扫描器采用插件化架构，核心管道负责调度，各检测器负责具体的扫描逻辑。这种设计使得添加新的扫描工具变得简单，只需实现对应的检测器接口即可。

graph TD
    A[用户输入<br/>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<br/>JSON<br/>SARIF]

组件层次

扫描管道核心

ScannerPipeline 类

ScannerPipeline 是管道的中央调度器，负责管理检测器的生命周期和执行顺序。

graph LR
    A[初始化] --> B[执行扫描]
    B --> C[并行运行所有检测器]
    C --> D[收集RawFinding]
    D --> E[规范化处理]
    E --> F[返回NormalizedFinding列表]

管道支持以下配置参数：

执行流程

1. 初始化阶段：加载所有启用的检测器实例
2. 扫描阶段：各检测器独立扫描目标路径，管道等待所有检测完成
3. 规范化阶段：将 RawFinding 转换为 NormalizedFinding 统一格式
4. 输出阶段：根据用户指定的格式输出结果

检测器模块

密钥检测器（SecretsDetector）

文件位置：packages/scanner/scanner/detectors/secrets.py

密钥检测器是 Velonus 的核心检测功能，负责发现代码库中的敏感信息泄露，包括 API 密钥、密码、证书等。

#### 检测策略

密钥检测器采用双重检测机制：

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 的解码器对文件进行深度扫描：

_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 熵超过阈值时，判定为可能的密钥

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 输出。

Semgrep 检测器

文件位置：packages/scanner/scanner/detectors/semgrep.py

Semgrep 是一个支持多语言的静态分析工具，Velonus 使用其 Python 规则集进行扫描。

#### 可用性检查

检测器首先检查 Semgrep 是否在 PATH 中可用：

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

#### 执行命令

semgrep scan --config p/python --json --quiet --metrics=off <target>

pip-audit 检测器

文件位置：packages/scanner/scanner/detectors/pip_audit.py

pip-audit 是 Python 生态系统的依赖漏洞扫描工具，用于检测项目依赖中已知的 CVE 漏洞。

#### 严重级别映射

#### CVSS 分数提取

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 输出时，以下字段为必需：

缺少必需字段的条目将被跳过并记录警告：

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

各检测器输出的原始发现对象，包含工具特定的数据结构。

NormalizedFinding

规范化的统一发现格式，支持跨扫描去重和一致输出。

文件位置：packages/normalizer/models.py

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 {
        <<enumeration>>
        CRITICAL
        HIGH
        MEDIUM
        LOW
        INFO
    }
    
    class Confidence {
        <<enumeration>>
        HIGH
        MEDIUM
        LOW
    }

#### 字段说明

资料来源：packages/normalizer/models.py:35-60

使用方式

命令行接口

# 扫描当前目录
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

退出码

退出码 1 用于 CI/CD 流程中阻断合并。

CI/CD 集成

#### GitHub Actions

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

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. 在管道中注册检测器

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)

严重级别过滤

管道支持按严重级别过滤结果：

相关资源

• 源码仓库：Velonus GitHub
• 问题反馈：GitHub Issues
• 安全漏洞：请参阅 SECURITY.md（不要公开提交）

模块概述

数据标准化模块（Normalizer Package）是 Velonus 安全扫描系统的核心组件之一，负责将来自不同安全工具的扫描结果统一转换为标准的发现数据格式。该模块位于 packages/normalizer/ 目录下，是连接扫描检测器与输出格式化器的桥梁。

数据标准化模块的主要职责包括：

1. 格式统一：将 Bandit、Semgrep、pip-audit、Safety、Secrets 等多种扫描工具的原始输出转换为统一的 NormalizedFinding 数据结构
2. 数据去重：基于确定性哈希算法消除跨扫描的重复发现
3. 元数据丰富：提取 CWE、OWASP 等安全分类标准，增强发现数据的可分析性

架构概览

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 是各扫描检测器产生的原始数据结构，包含扫描工具返回的原始字段信息。

资料来源：packages/scanner/scanner/detectors/semgrep.py:90-110

NormalizedFinding（标准发现）

NormalizedFinding 是整个系统的规范发现格式，所有扫描工具的输出最终都会转换为这种格式。

@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 枚举

严重程度等级定义：

Confidence 枚举

置信度等级反映工具的检测确定性（非严重程度）：

标准化流程

完整处理流水线

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 生成：计算确定性哈希作为唯一标识符

# 严重程度映射示例（Semgrep → 规范值）
_SEVERITY_MAP = {
    "ERROR": "HIGH",
    "WARNING": "MEDIUM",
    "INFO": "INFO",
}

资料来源：packages/scanner/scanner/detectors/semgrep.py:40-50

CWE 提取逻辑

CWE（Common Weakness Enumeration）分类通过正则表达式从工具元数据中提取：

_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 类似：

_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 字段进行哈希比对。

graph LR
    A[发现 A: ID=abc123] --> B{已见过?}
    C[发现 C: ID=abc123] --> B
    D[发现 B: ID=def456] --> B
    B -->|是| E[跳过]
    B -->|否| F[保留并记录]

去重策略：

确定性 ID 算法：

ID = SHA-256(tool + file + line + rule_id)[:16]

这种设计确保：

• 相同漏洞在不同扫描中产生相同 ID
• 便于历史数据比对和趋势分析
• 支持增量扫描和变更检测

资料来源：packages/normalizer/models.py:50-55

与扫描管道的集成

ScanPipeline 集成架构

ScanPipeline 是扫描流水线的主协调器，集成数据标准化模块的处理流程：

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

并行检测器支持：

资料来源：packages/scanner/scanner/pipeline.py:1-50

执行时序

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 支持多种输出格式：

SARIF 格式化

SARIF（Static Analysis Results Interchange Format）格式化器将标准发现转换为符合 OASIS SARIF 规范的输出：

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

错误处理与容错

字段缺失处理

标准化器对缺失字段采用宽松策略：

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 模块，遵循以下日志级别约定：

配置与扩展

严重程度阈值

用户可通过 CLI 参数控制最低显示严重程度：

velonus scan ./ --severity high    # 仅显示 HIGH 和 CRITICAL
velonus scan ./ --severity medium  # 显示 MEDIUM 及以上

新增检测器集成

集成新的扫描工具需要：

1. 实现检测器类，返回 RawFinding 列表
2. 在 ScanPipeline 中注册检测器
3. 配置严重程度映射（如需要）
4. 添加 CWE/OWASP 元数据提取（如适用）

# packages/scanner/scanner/detectors/custom.py
from .secrets import RawFinding

class CustomRunner:
    def run(self, target: Path) -> list[RawFinding]:
        # 实现扫描逻辑
        ...

模块依赖关系

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 引擎（AI Engine）是 Velonus 安全扫描平台的核心智能组件，属于项目的 Phase 2 — AI Layer 阶段。根据项目路线图，AI 引擎的主要职责包括：

• 漏洞优先级排序（AI prioritization）
• 可利用性评分（Exploitability scoring）
• 修复建议生成（Fix generation）

资料来源：README.md

AI 引擎作为 Phase 2 的核心功能，目前处于 Building（开发中） 状态，尚未完成实现。

资料来源：README.md - Roadmap

架构组件

根据源码文件结构，AI 引擎由以下核心模块组成：

工作流程

AI 引擎的整体工作流程如下：

graph TD
    A[安全扫描结果] --> B[Context Engine<br/>上下文分析]
    B --> C{缓存命中?}
    C -->|是| D[返回缓存结果]
    C -->|否| E[Remediation Engine<br/>修复建议生成]
    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 引擎通过对漏洞的多个维度进行分析来计算可利用性评分：

资料来源：apps/cli/README.md - Severity Levels

修复建议生成

AI 引擎生成的修复建议包含以下层次：

代码级修复

• 直接的代码修改建议
• 安全的 API 替换方案
• 参数化/规范化建议

依赖级修复

• 需要升级的包版本
• 替代库建议
• 配置修改指导

架构级建议

• 安全设计模式推荐
• 架构重构方向
• 防御纵深建议

与 Phase 1 的关系

AI 引擎建立在 Phase 1 扫描管道的基础之上：

graph LR
    A[Phase 1<br/>扫描管道] -->|RawFinding| B[AI Engine<br/>上下文分析]
    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 已实现的扫描工具包括：

资料来源：README.md - Roadmap

Phase 3 与 Phase 4 的集成

AI 引擎的能力将在后续阶段被进一步利用：

Phase 3 — GitHub PR 集成

AI 引擎生成的修复建议将通过 PR 内联评论直接展示给开发者，实现一键接受修复的功能。

资料来源：README.md - Roadmap

Phase 4 — Web 仪表盘

AI 引擎的分析结果将集成到 Web 仪表盘中，提供：

• 扫描历史趋势
• 发现趋势分析
• 团队安全态势概览

认证与配置

AI 引擎的功能需要通过 Velonus API 访问，认证方式采用 Clerk 浏览器 OAuth 流程：

velonus auth login    # 认证登录
velonus auth logout   # 清除存储的凭证
velonus auth status   # 查看当前认证状态

配置管理通过以下命令实现：

velonus config show                          # 显示当前配置
velonus config set api_url https://api.velonus.dev  # 设置 API 地址

资料来源：apps/cli/README.md - velonus auth

⚠️ 注意：认证和配置功能目前处于 Phase 0 的存根（stubbed）状态，将在 Phase 2 API 后端上线后完全可用。

开发指南

根据 CONTRIBUTING.md 的要求，AI 引擎代码开发需遵循以下规范：

资料来源：CONTRIBUTING.md

当前状态

资料来源：README.md - Roadmap

相关文档

• README 主页 — 项目概览与快速开始
• CLI 使用指南 — 命令行工具详细文档
• 贡献指南 — 开发者贡献规范
• 安全策略 — 安全漏洞报告流程

概述

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 支持

架构概览

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。

#### 基础工作流配置

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 输出的工作流配置

- 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 中添加：

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 配置参数

SARIF 输出格式

概述

SARIF（Static Analysis Results Interchange Format）是与 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具兼容的标准输出格式。Velonus 通过 --sarif 参数生成 SARIF 文件。

资料来源：README.md:45-47

SARIF 文件生成命令

资料来源：README.md:48-52

SARIF 规则 ID 转换

Velonus 在生成 SARIF 输出时，会将内部规则 ID 转换为 PascalCase 格式的显示名称，便于在 GitHub 界面中阅读。

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 在生成输出时遵循此规范：

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 管道中的安全门禁：

资料来源：apps/cli/README.md:73-76

严重级别定义

资料来源：apps/cli/README.md:61-69

推荐配置策略

# 仅显示 HIGH 和 CRITICAL 级别
velonus scan ./ --severity high

# 导出 JSON 格式（高危过滤）
velonus scan ./ --format json --severity high > findings.json

Phase 3 规划功能

根据项目路线图，Phase 3 将实现更深入的 GitHub 集成：

Phase 3 依赖的前置条件

Phase 3 功能需要以下基础设施支持：

``bash velonus auth login # 通过 Clerk 浏览器 OAuth 流程认证 velonus auth logout # 清除存储的凭证 velonus auth status # 显示当前认证状态 `` 资料来源：apps/cli/README.md:77-92

1. 认证系统：velonus auth 命令（Phase 2 实现）

``bash velonus config show # 显示当前配置 velonus config set api_url https://api.velonus.dev # 设置配置值 `` 资料来源：apps/cli/README.md:93-104

1. 配置文件管理：velonus config 命令（Phase 2 实现）

输出格式对比

资料来源：README.md:40-60

相关扫描器与 GitHub 集成的漏洞数据

Velonus 的各个扫描器均支持提取与 GitHub 漏洞数据库兼容的元数据：

Semgrep CWE/OWASP 提取

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 评分

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

项目阶段概览

资料来源：README.md:65-73

常见问题

Q: 如何仅扫描并显示高危漏洞？

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 合并。

概述

Velonus 是一个 Python 编写的安全扫描工具，采用单体仓库（monorepo）结构管理多个包和应用。项目当前处于 Alpha 阶段，CLI 工具已完成并可直接使用，但完整的 API 后端服务仍在开发中。资料来源：README.md

当前项目分为以下主要组件：

项目架构

Velonus 采用分层架构设计，CLI 作为前端入口调用 Scanner 包中的各个检测器。

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 定义了核心扫描管道，所有检测器并行执行：

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）：

graph LR
    subgraph 检测器层
        S[SecretsDetector<br/>索引 0]
        B[BanditRunner<br/>索引 1]
        SG[SemgrepRunner<br/>索引 2]
        PA[PipAuditRunner<br/>索引 3]
        SF[SafetyRunner<br/>索引 4]
    end

检测器类型定义

_ParallelRunner = BanditRunner | SemgrepRunner | PipAuditRunner | SafetyRunner

资料来源：packages/scanner/scanner/pipeline.py:33

开发环境部署

环境要求

资料来源：CONTRIBUTING.md

安装步骤

# 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

验证安装

velonus --help
velonus scan ./apps/cli/shield

本地运行

CLI 扫描命令

# 扫描当前目录
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

输出格式

资料来源：apps/cli/README.md

退出码

资料来源：apps/cli/README.md

CI/CD 集成

GitHub Actions 集成

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

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 表示发现漏洞（正常处理）

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 支持两种格式：

CVSS 评分提取逻辑：

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 <target>
• 退出码 1 = 正常发现（JSON 仍有效），退出码 2+ = 错误

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

阶段性规划

资料来源：README.md

本地开发命令

运行测试

# 运行全部测试（当前 367 个测试，覆盖 6 个文件）
pytest apps/cli/tests/

# 详细输出
pytest apps/cli/tests/ -v

代码检查

# 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 后端上线后，系统架构预计如下：

graph TD
    subgraph 前端层
        CLI[velonus CLI]
        Web[Web Dashboard<br/>Phase 4]
    end
    
    subgraph 后端服务
        API[API Server<br/>Phase 2]
        Worker[Async Worker<br/>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 规划）

velonus auth login    # 通过 Clerk 浏览器 OAuth 流程认证
velonus auth logout   # 清除存储的凭证
velonus auth status   # 显示当前认证状态

配置管理（Phase 2 规划）

velonus config show                    # 打印当前配置
velonus config set api_url <value>     # 设置配置值

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 依赖：

uv sync --all-extras --dev

安全门禁配置

Velonus 设计为可作为安全 CI 门禁使用：

# 硬性门禁：发现 HIGH 或 CRITICAL 时退出码为 1
velonus scan ./ --severity high

建议在 CI 中配置：

1. 使用 --severity high 过滤，仅阻断高危及以上问题
2. 定期使用 --severity info 全量扫描
3. 导出 SARIF 格式上传至 GitHub Security 标签页

Pitfall Log / 踩坑日志

项目：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