{
"canonical_name": "aliammar15/velonus",
"compilation_id": "pack_bd166e8a2bd4406ca413847db1388f54",
"created_at": "2026-05-15T06:25:51.029086+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install velonus` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install velonus",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_49ba810ee768462588ae29119eab08f8"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_74e5f41285b519eb7bf25d7c1d8469dd",
"canonical_name": "aliammar15/velonus",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/AliAmmar15/Velonus",
"slug": "velonus",
"source_packet_id": "phit_6665dda9b967460bb3356f04a17cad82",
"source_validation_id": "dval_910361ca834d4aa6b030e19a6074b3fc"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 chatgpt的用户",
"github_forks": null,
"github_stars": null,
"one_liner_en": "[](https://github.com/AliAmmar15/Velonus/actions)",
"one_liner_zh": "[](https://github.com/AliAmmar15/Velonus/actions)",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, ci"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "velonus",
"title_zh": "velonus 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Open Source Capability Building",
"label_zh": "开源能力构建",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-open-source-capability-building",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_6665dda9b967460bb3356f04a17cad82",
"page_model": {
"artifacts": {
"artifact_slug": "velonus",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install velonus",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/AliAmmar15/Velonus#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"开源能力构建",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "[](https://github.com/AliAmmar15/Velonus/actions)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_62cdd9b76ac447b8b11064afda81fb9a | https://github.com/AliAmmar15/Velonus/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_3a9b7a6193ee4ea289f4dc4a12f6a0c1 | https://github.com/AliAmmar15/Velonus/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": null,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": null
},
"source_url": "https://github.com/AliAmmar15/Velonus",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "[](https://github.com/AliAmmar15/Velonus/actions)",
"title": "velonus 能力包",
"trial_prompt": "# velonus - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 velonus 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: [](https://github.com/AliAmmar15/Velonus/actions) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-cli：CLI 命令行工具。围绕“CLI 命令行工具”模拟一次用户任务，不展示安装或运行结果。\n4. page-api：API 服务系统。围绕“API 服务系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-scanner：安全扫描器管道。围绕“安全扫描器管道”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-cli\n输入：用户提供的“CLI 命令行工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-api\n输入：用户提供的“API 服务系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-scanner\n输入：用户提供的“安全扫描器管道”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-cli：Step 3 必须围绕“CLI 命令行工具”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-api：Step 4 必须围绕“API 服务系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-scanner：Step 5 必须围绕“安全扫描器管道”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://news.ycombinator.com/item?id=48143235\n- https://github.com/AliAmmar15/Velonus#readme\n- README.md\n- pyproject.toml\n- CONTRIBUTING.md\n- apps/cli/shield/main.py\n- apps/api/shield_api/main.py\n- packages/scanner/scanner/pipeline.py\n- infra/docker/docker-compose.yml\n- apps/cli/shield/commands/scan.py\n- apps/cli/shield/commands/auth.py\n- apps/cli/shield/commands/pr.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 velonus 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [bug] Same vulnerability reported twice when detected by both Bandit and（https://github.com/AliAmmar15/Velonus/issues/2）；github/github_issue: [bug] Scanner reports test-file findings as production vulnerabilities (（https://github.com/AliAmmar15/Velonus/issues/1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[bug] Same vulnerability reported twice when detected by both Bandit and",
"url": "https://github.com/AliAmmar15/Velonus/issues/2"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] Scanner reports test-file findings as production vulnerabilities (",
"url": "https://github.com/AliAmmar15/Velonus/issues/1"
}
],
"status": "已收录 2 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "[](https://github.com/AliAmmar15/Velonus/actions)",
"effort": "安装已验证",
"forks": null,
"icon": "code",
"name": "velonus 能力包",
"risk": "需复核",
"slug": "velonus",
"stars": null,
"tags": [
"安全审查与权限治理",
"开源能力构建",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/AliAmmar15/Velonus 项目说明书\n\n生成时间：2026-05-15 02:07:26 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [CLI 命令行工具](#page-cli)\n- [API 服务系统](#page-api)\n- [安全扫描器管道](#page-scanner)\n- [数据标准化模块](#page-normalizer)\n- [AI 引擎](#page-ai-engine)\n- [GitHub 集成](#page-github-integration)\n- [部署与基础设施](#page-deployment)\n- [使用指南与最佳实践](#page-usage)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [使用指南与最佳实践](#page-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n \n\n# 项目概述\n\n## 简介\n\nVelonus 是一个本地优先的 Python 安全扫描工具（SAST），专注于在软件开发周期中自动检测安全漏洞和敏感信息泄露。该项目当前处于 Alpha 阶段，已实现核心功能并可在生产环境中使用。资料来源：[README.md:1]()\n\nVelonus 的核心设计理念是将多个业界领先的开源安全工具整合到一个统一的命令行界面中，通过标准化输出格式和可配置的严重级别过滤，帮助开发团队在本地环境和 CI/CD 流水线中快速识别和修复安全问题。\n\n## 核心价值主张\n\n| 特性 | 说明 |\n|------|------|\n| **本地优先** | 所有扫描均在本地执行，无需将代码上传到第三方服务 |\n| **多工具整合** | 统一调用 TruffleHog、Bandit、Semgrep、pip-audit、Safety 等工具 |\n| **标准化输出** | 支持 Terminal、JSON、SARIF 三种输出格式 |\n| **CI 友好** | CRITICAL/HIGH 级别发现时以退出码 1 退出，可作为合并门禁 |\n| **即插即用** | 支持 GitHub Actions 和 Pre-commit hook 集成 |\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph CLI层[\"CLI 层 (apps/cli)\"]\n A[\"velonus scan\"]\n B[\"velonus auth\"]\n C[\"velonus config\"]\n end\n \n subgraph 核心层[\"核心扫描层\"]\n D[\"扫描管道 Pipeline\"]\n E[\"结果归一化 NormalizedFinding\"]\n F[\"格式化器 Formatters\"]\n end\n \n subgraph 检测器层[\"检测器层 (packages/scanner)\"]\n G[\"secrets - 密钥扫描\"]\n H[\"bandit - 代码审计\"]\n I[\"semgrep - 静态分析\"]\n J[\"pip-audit - 依赖审计\"]\n K[\"safety - 安全检查\"]\n end\n \n subgraph 输出层[\"输出层\"]\n L[\"Terminal 格式化器\"]\n M[\"JSON 格式化器\"]\n N[\"SARIF 格式化器\"]\n end\n \n A --> D\n D --> G\n D --> H\n D --> I\n D --> J\n D --> K\n \n G --> E\n H --> E\n I --> E\n J --> E\n K --> E\n \n E --> F\n F --> L\n F --> M\n F --> N\n```\n\n### 项目目录结构\n\n```\nVelonus/\n├── apps/\n│ └── cli/\n│ ├── shield/ # CLI 主程序\n│ │ ├── __main__.py\n│ │ ├── cli.py # 命令行入口\n│ │ ├── commands/ # 子命令实现\n│ │ └── formatters/ # 输出格式化器\n│ │ ├── terminal.py\n│ │ ├── json.py\n│ │ └── sarif.py\n├── packages/\n│ ├── scanner/\n│ │ └── scanner/\n│ │ ├── detectors/ # 安全检测器\n│ │ │ ├── secrets.py # TruffleHog + 熵值检测\n│ │ │ ├── bandit.py # Bandit 集成\n│ │ │ ├── semgrep.py # Semgrep 集成\n│ │ │ ├── pip_audit.py # pip-audit 集成\n│ │ │ └── safety.py # Safety 集成\n│ │ ├── models/ # 数据模型\n│ │ │ ├── raw_finding.py\n│ │ │ └── normalized_finding.py\n│ │ └── pipeline.py # 扫描管道编排\n│ └── normalizer/ # 结果标准化模块\n└── pyproject.toml # 项目配置\n```\n\n## 扫描能力矩阵\n\n### 已集成的安全工具\n\n| 工具 | 用途 | 配置文件 |\n|------|------|----------|\n| **TruffleHog** | 硬编码密钥和凭证检测 | `secrets.py` |\n| **Bandit** | Python 代码安全分析 | `bandit.py` |\n| **Semgrep** | 高级静态分析与自定义规则 | `semgrep.py` |\n| **pip-audit** | Python 依赖漏洞扫描 | `pip_audit.py` |\n| **Safety** | Safety DB 依赖安全检查 | `safety.py` |\n\n### 严重级别定义\n\n| 级别 | 颜色标识 | 典型场景 |\n|------|----------|----------|\n| 🔴 CRITICAL | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 LOW | 蓝色 | 不安全默认值、次要配置问题 |\n| ⚪ INFO | 灰色 | 代码风格问题、信息性注释 |\n\n资料来源：[apps/cli/README.md:1]()\n\n## 命令行接口\n\n### 核心命令\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 扫描指定项目\nvelonus scan ./my-python-project\n\n# 仅显示 HIGH 和 CRITICAL 级别\nvelonus scan ./ --severity high\n\n# 输出为 JSON 格式\nvelonus scan ./ --format json\n\n# 输出为 SARIF 格式\nvelonus scan ./ --format sarif\n\n# 详细输出模式\nvelonus scan ./ --verbose\n```\n\n### 命令行参数表\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `PATH` | `.` | 要扫描的项目或文件路径 |\n| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |\n| `--severity`, `-s` | `info` | 最低显示级别 |\n| `--verbose`, `-v` | off | 显示解析后的目标路径和额外详情 |\n| `--help` | - | 显示帮助信息并退出 |\n\n资料来源：[apps/cli/README.md:1]()\n\n### 退出码约定\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |\n\n退出码 1 的设计是**有意为之**，用于将扫描结果作为 CI/CD 流水线的合并门禁条件。资料来源：[apps/cli/README.md:1]()\n\n## 输出格式详解\n\n### Terminal 格式（默认）\n\n使用 Rich 库渲染彩色表格，包含严重级别徽章、文件路径、行号、规则 ID 和详细信息。\n\n### JSON 格式\n\n适用于管道集成和结果存储：\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n### SARIF 格式\n\nSARIF（Static Analysis Results Interchange Format）是一种标准化格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具。资料来源：[apps/cli/README.md:1]()\n\n```bash\nvelonus scan ./ --format sarif\n```\n\n## 数据模型\n\n### RawFinding\n\n各检测器输出的原始发现对象，包含以下核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tool` | str | 来源工具名称（如 `secrets`、`bandit`） |\n| `rule_id` | str | 规则标识符 |\n| `file` | str | 发现漏洞的文件路径 |\n| `line` | int | 代码行号 |\n| `severity` | str | 严重级别 |\n| `message` | str | 人类可读的消息 |\n| `code_snippet` | str | 相关代码片段 |\n| `metadata` | dict | 工具特定的元数据 |\n\n### NormalizedFinding\n\n经过标准化处理的统一发现对象，格式统一后由格式化器渲染。\n\n## 开发规范\n\n### 代码质量要求\n\n项目采用严格的代码质量标准：\n\n| 检查项 | 工具 | 命令 |\n|--------|------|------|\n| 代码风格检查 | Ruff | `ruff check .` |\n| 代码格式化 | Ruff | `ruff format --check .` |\n| 静态类型检查 | mypy | `mypy --strict --ignore-missing-imports` |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 严格模式要求\n\n所有新代码必须通过 mypy strict 模式检查，零错误。引入 `type: ignore` 注释需要在代码注释中提供说明。资料来源：[CONTRIBUTING.md:1]()\n\n### Pull Request 规范\n\n| 规范 | 说明 |\n|------|------|\n| 单一职责 | 每个 PR 只包含一个功能或修复 |\n| 测试要求 | 所有新功能必须包含匹配的单元测试 |\n| 代码清理 | PR 前本地运行 ruff 和 mypy 检查 |\n| 代码行数 | 建议 PR 差异控制在 400 行以内 |\n| 无占位符 | 禁止 AI 生成的占位代码 |\n\n## CI/CD 集成\n\n### GitHub Actions 集成\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### Pre-commit Hook 配置\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 开发路线图\n\n| 阶段 | 状态 | 交付内容 |\n|------|------|----------|\n| **Phase 0** — 基础框架 | ✅ 已完成 | CLI 骨架、Rich 输出、`NormalizedFinding` 模型 |\n| **Phase 1** — 扫描管道 | ✅ 已完成 | 真正的密钥检测、Bandit、Semgrep、pip-audit、SARIF |\n| **Phase 2** — AI 层 | 🔨 进行中 | AI 优先级排序、可利用性评分、修复建议生成 |\n| **Phase 3** — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| **Phase 4** — Web 控制台 | 🔴 未开始 | Web UI、扫描历史、问题趋势 |\n\n资料来源：[README.md:1]()\n\n## 技术栈\n\n| 组件 | 技术选型 | 用途 |\n|------|----------|------|\n| CLI 框架 | Click | 命令行界面构建 |\n| 表格渲染 | Rich | 终端彩色输出 |\n| 类型系统 | Python 3.12+ | 静态类型检查 |\n| 代码检查 | Ruff | 格式化与 linting |\n| 静态分析 | Semgrep、Bandit | 代码安全分析 |\n| 依赖扫描 | pip-audit、Safety | 依赖漏洞检测 |\n| 密钥检测 | TruffleHog | 凭证扫描 |\n\n## 总结\n\nVelonus 是一个功能完整的 Python 安全扫描工具，通过统一界面整合多个业界领先的安全检测工具，为开发团队提供从本地开发到 CI/CD 流水线的全流程安全保障。项目采用严格的代码质量标准，确保长期可维护性，同时保持开放的贡献文化，欢迎社区参与改进。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI 命令行工具](#page-cli), [API 服务系统](#page-api), [安全扫描器管道](#page-scanner)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/shield/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/main.py)\n- [apps/api/shield_api/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/main.py)\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [infra/docker/docker-compose.yml](https://github.com/AliAmmar15/Velonus/blob/main/infra/docker/docker-compose.yml)\n \n\n# 系统架构\n\n## 概述\n\nVelonus 是一个模块化的安全扫描平台，采用分层架构设计。系统由 CLI 前端、扫描管道、多个检测器后端和输出格式化器组成。核心设计理念是将扫描逻辑与用户界面分离，使每个检测工具（Bandit、Semgrep、pip-audit、Safety、TruffleHog）能够独立工作，同时通过统一的 `RawFinding` 数据模型汇聚结果。\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph CLI层[\"CLI 层 (apps/cli/shield)\"]\n CLI[命令行入口]\n Formatters[格式化器]\n Main[main.py]\n end\n\n subgraph Scanner层[\"扫描器层 (packages/scanner)\"]\n Pipeline[扫描管道]\n Secrets[Secrets 检测器]\n Bandit[Bandit 检测器]\n Semgrep[Semgrep 检测器]\n PipAudit[pip-audit 检测器]\n Safety[Safety 检测器]\n end\n\n subgraph 数据模型[\"数据模型层\"]\n RawFinding[RawFinding 模型]\n NormalizedFinding[NormalizedFinding 模型]\n end\n\n subgraph API层[\"API 层 (apps/api)\"]\n API[Shield API]\n end\n\n CLI --> Main\n Main --> Formatters\n Main --> Pipeline\n Pipeline --> Secrets\n Pipeline --> Bandit\n Pipeline --> Semgrep\n Pipeline --> PipAudit\n Pipeline --> Safety\n Secrets --> RawFinding\n Bandit --> RawFinding\n Semgrep --> RawFinding\n PipAudit --> RawFinding\n Safety --> RawFinding\n Formatters --> NormalizedFinding\n Formatters --> RawFinding\n```\n\n## 核心组件\n\n### CLI 层\n\nCLI 层位于 `apps/cli/shield` 目录，负责用户交互和结果展示。\n\n| 组件 | 路径 | 职责 |\n|------|------|------|\n| main.py | apps/cli/shield/main.py | 命令行入口，参数解析，扫描协调 |\n| formatters/ | apps/cli/shield/formatters/ | 输出格式化（terminal、json、sarif） |\n| detectors/ | packages/scanner/scanner/detectors/ | 安全检测器实现 |\n\nCLI 支持的输出格式：\n\n| 格式 | 用途 | 状态 |\n|------|------|------|\n| terminal | 交互式彩色输出 | ✅ 已实现 |\n| json | 管道友好输出 | ✅ 已实现 |\n| sarif | GitHub Code Scanning 兼容 | ✅ 已实现 |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n### 扫描管道\n\n扫描管道 (`packages/scanner/scanner/pipeline.py`) 是核心编排组件，负责：\n\n1. 依次调用各个检测器\n2. 收集并归一化扫描结果\n3. 处理检测器的执行超时和错误\n\n```mermaid\ngraph LR\n A[扫描目标] --> B[Secrets 检测器]\n B --> C[Bandit 检测器]\n C --> D[Semgrep 检测器]\n D --> E[pip-audit 检测器]\n E --> F[Safety 检测器]\n F --> G[结果聚合]\n```\n\n每个检测器返回 `RawFinding` 列表，管道统一收集后传递给格式化器。\n\n### 检测器架构\n\n检测器采用统一的接口设计，每个检测器继承基础类并实现 `scan()` 方法。\n\n#### Secrets 检测器\n\n位于 `packages/scanner/scanner/detectors/secrets.py` 和 `packages/scanner/detectors/secrets.py`，实现两层检测：\n\n| 检测模式 | 描述 |\n|----------|------|\n| TruffleHog | 使用 TruffleHog 进行已知格式密钥检测 |\n| 熵值分析 | Shannon 熵阈值检测高随机性字符串 |\n\n```python\n# 熵值阈值常量\n_ENTROPY_THRESHOLD = 4.5\n```\n\n当 TruffleHog 未安装时，自动降级到熵值分析模式。检测结果包含：\n\n- `detector`: 检测器类型名称\n- `verified`: 是否经过 TruffleHog 验证\n- `decoder`: 使用的解码器名称\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:1-150](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n\n#### Semgrep 检测器\n\n位于 `packages/scanner/scanner/detectors/semgrep.py`，使用 `p/python` 规则集。\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| --config | p/python | Semgrep 规则集 |\n| --json | - | JSON 输出格式 |\n| --quiet | - | 静默模式 |\n| --metrics | off | 禁用遥测 |\n\nSemgrep 返回 1 表示发现漏洞（正常行为），返回 2+ 才表示错误。\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-50](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n\n#### 依赖漏洞检测器\n\n##### pip-audit 检测器\n\n位于 `packages/scanner/scanner/detectors/pip_audit.py`，检测 Python 依赖中的已知漏洞。\n\n关键元数据字段：\n\n| 字段 | 说明 |\n|------|------|\n| package_name | 包名称 |\n| package_version | 安装版本 |\n| cvss_score | CVSS v3 评分 |\n| fix_versions | 可修复版本列表 |\n| fix_available | 是否有修复版本 |\n\n##### Safety 检测器\n\n位于 `packages/scanner/scanner/detectors/safety.py`，支持两种输出格式：\n\n| Safety 版本 | 数据格式 |\n|-------------|----------|\n| v2 (>=2.0) | `{\"vulnerabilities\": [...]}` |\n| v1 (<2.0) | 5 元素列表数组 |\n\nCVSS 评分提取逻辑处理嵌套的 severity 字典结构。\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:1-100](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n\n## 数据模型\n\n### RawFinding\n\n所有检测器返回统一的 `RawFinding` 对象：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| tool | str | 来源工具名称 |\n| rule_id | str | 规则标识符 |\n| file | str | 文件路径 |\n| line | int | 行号 |\n| severity | str | 严重级别 |\n| message | str | 人类可读消息 |\n| code_snippet | str | 相关代码片段 |\n| metadata | dict | 工具特定元数据 |\n\n### 严重级别\n\n| 级别 | 颜色 | 典型场景 |\n|------|------|----------|\n| CRITICAL | 红色 | 硬编码密钥、RCE、认证绕过 |\n| HIGH | 橙色 | SQL 注入、命令注入 |\n| MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| LOW | 蓝色 | 不安全默认值 |\n| INFO | 灰色 | 样式问题 |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## 格式化输出\n\n### SARIF 格式化器\n\n位于 `apps/cli/shield/formatters/sarif.py`，实现 SARIF 2.1.0 规范。\n\n关键转换函数：\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"将 rule_id 转换为 PascalCase 显示名称\"\"\"\n base = rule_id.split(\"/\")[-1]\n return \"\".join(word.capitalize() for word in base.replace(\"-\", \"_\").split(\"_\"))\n```\n\n目录 URI 处理遵循 SARIF 规范 §3.14.14，强制添加尾部斜杠。\n\n### 输出格式映射\n\n| 内部级别 | SARIF 级别 |\n|----------|-----------|\n| CRITICAL | error |\n| HIGH | error |\n| MEDIUM | warning |\n| LOW | note |\n| INFO | note |\n\n## API 层\n\n位于 `apps/api/shield_api/main.py`，为 Phase 2 及后续功能预留。\n\n当前阶段：\n\n| 阶段 | 功能 | 状态 |\n|------|------|------|\n| Phase 0 | CLI 框架 | ✅ 完成 |\n| Phase 1 | 扫描管道 | ✅ 完成 |\n| Phase 2 | AI 上下文引擎 | 🔨 开发中 |\n| Phase 3 | GitHub PR 集成 | 📋 计划中 |\n| Phase 4 | Web 仪表板 | 📋 计划中 |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## 部署架构\n\n### Docker 部署\n\n项目提供 Docker Compose 配置用于容器化部署：\n\n```yaml\n# infra/docker/docker-compose.yml 结构\nservices:\n shield-api: # API 服务\n scanner: # 扫描引擎\n dashboard: # Web UI (Phase 4)\n```\n\n### CI/CD 集成\n\n系统设计支持多种 CI 场景：\n\n| 集成方式 | 配置示例 |\n|----------|----------|\n| GitHub Actions | .github/workflows/security.yml |\n| Pre-commit hook | .pre-commit-config.yaml |\n\nVelonus 在发现 HIGH 或 CRITICAL 漏洞时返回退出码 1，可作为 CI 门禁。\n\n## 贡献与质量保障\n\n项目要求严格的代码质量标准：\n\n| 检查项 | 工具 | 命令 |\n|--------|------|------|\n| 代码格式 | ruff | `ruff format --check .` |\n| 代码检查 | ruff | `ruff check .` |\n| 类型检查 | mypy | `mypy --strict` |\n\nPR 规范：\n\n- 每个 PR 只做一个改动\n- 必须包含测试\n- Diff 行数建议小于 400\n- 禁止 AI 生成的占位代码\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n## 工作流程图\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as CLI\n participant Pipeline as 扫描管道\n participant Detectors as 检测器\n participant Formatter as 格式化器\n\n User->>CLI: velonus scan ./ --severity high\n CLI->>Pipeline: 初始化扫描任务\n Pipeline->>Detectors: 并行/顺序执行检测\n Detectors-->>Pipeline: RawFinding[]\n Pipeline->>Formatter: 聚合结果\n Formatter->>User: 格式化输出\n```\n\n## 总结\n\nVelonus 采用插件化的检测器架构，每个安全工具（Bandit、Semgrep、pip-audit、Safety、TruffleHog）作为独立模块接入管道。这种设计使得系统易于扩展，新增检测器只需实现统一的 `scan()` 接口并返回 `RawFinding` 对象即可。CLI 与扫描逻辑的分离确保了核心功能可以在多种场景下复用，包括本地 CLI、CI/CD 管道和 Web 仪表板。\n\n---\n\n\n\n## CLI 命令行工具\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [API 服务系统](#page-api), [使用指南与最佳实践](#page-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/shield/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/main.py)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n \n\n# CLI 命令行工具\n\n## 概述\n\nVelonus CLI 是一个基于 Python 的命令行安全扫描工具，采用 Typer 框架构建，为开发者提供本地化的应用安全测试能力。CLI 工具支持多种安全扫描器集成，包括密钥检测、代码漏洞扫描、依赖漏洞审计等，并能输出多种格式的结果用于不同场景。\n\nCLI 的核心定位是**本地优先**，即所有核心扫描功能在不依赖后端 API 的情况下完全可用。身份验证和云端功能（如 AI 优先级排序、修复建议生成）则在后续阶段（Phase 2+）逐步实现。 资料来源：[apps/cli/shield/main.py:1-17]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[\"velonus CLI 入口
(main.py)\"] --> B[\"Typer 应用层\"]\n B --> C[\"命令模块
(commands/)\"]\n \n C --> D[\"scan 命令\"]\n C --> E[\"auth 命令\"]\n C --> F[\"config 命令\"]\n \n D --> G[\"scanner 包
(packages/scanner)\"]\n G --> H[\"检测器引擎\"]\n \n H --> I[\"secrets.py
密钥检测\"]\n H --> J[\"semgrep.py
代码模式扫描\"]\n H --> K[\"pip_audit.py
依赖漏洞审计\"]\n H --> L[\"safety.py
安全依赖检查\"]\n \n D --> M[\"格式化器
(formatters/)\"]\n M --> N[\"terminal.py
终端输出\"]\n M --> O[\"sarif.py
SARIF 格式\"]\n```\n\n### 模块职责\n\n| 模块路径 | 职责 | 状态 |\n|---|---|---|\n| `main.py` | CLI 根应用定义、Typer 实例初始化、命令组注册 | 稳定 |\n| `commands/scan.py` | `velonus scan` 命令实现、参数解析、扫描执行 | 稳定 |\n| `commands/auth.py` | `velonus auth` 认证命令（登录/登出/状态） | Phase 2 |\n| `commands/config.py` | `velonus config` 配置管理命令 | Phase 2 |\n| `core/api_client.py` | 与 Velonus 后端 API 通信 | Phase 2 |\n| `core/config.py` | 本地配置加载与存储 | Phase 2 |\n| `formatters/terminal.py` | 终端 Rich 表格输出 | 稳定 |\n| `formatters/sarif.py` | SARIF 格式生成 | Phase 1 |\n\n## 命令详解\n\n### velonus scan\n\n`velonus scan` 是核心命令，用于在本地路径上运行安全扫描管道。\n\n#### 命令语法\n\n```\nvelonus scan [PATH] [OPTIONS]\n```\n\n#### 参数与选项\n\n| 参数/选项 | 默认值 | 描述 |\n|---|---|---|\n| `PATH` | `.` | 要扫描的项目路径或文件 |\n| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |\n| `--severity`, `-s` | `info` | 最低显示严重级别：`critical`、`high`、`medium`、`low`、`info` |\n| `--verbose`, `-v` | 关闭 | 显示解析后的目标路径及额外详情 |\n| `--help` | - | 显示帮助信息并退出 |\n\n#### 使用示例\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 扫描子目录\nvelonus scan ./apps/api\n\n# 仅显示高危和严重漏洞\nvelonus scan ./ --severity high\n\n# 显示详细路径信息\nvelonus scan ./ --verbose\n\n# 导出为 JSON\nvelonus scan ./ --format json\n\n# 导出为 SARIF 格式\nvelonus scan ./ --format sarif\n\n# 高危以上结果重定向到文件\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n#### 退出码\n\n| 退出码 | 含义 |\n|---|---|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |\n\n退出码 `1` 是有意设计的，可作为 CI/CD 门禁阻止合并。 资料来源：[apps/cli/README.md:1-80]()\n\n### velonus auth\n\n认证命令用于与 Velonus API 建立连接，目前处于 **Phase 2** 阶段（桩代码状态）。\n\n| 子命令 | 描述 |\n|---|---|\n| `velonus auth login` | 通过 Clerk（浏览器 OAuth 流程）进行身份验证 |\n| `velonus auth logout` | 清除存储的凭证 |\n| `velonus auth status` | 显示当前认证状态 |\n\n```bash\nvelonus auth login\nvelonus auth logout\nvelonus auth status\n```\n\n> Phase 0 阶段这些命令为桩代码，将在 Phase 2 后端 API 上线后完整实现。\n\n### velonus config\n\n本地 CLI 配置管理命令，目前处于 **Phase 2** 阶段（桩代码状态）。\n\n| 子命令 | 描述 |\n|---|---|\n| `velonus config show` | 打印当前配置 |\n| `velonus config set ` | 设置配置值 |\n\n```bash\nvelonus config show\nvelonus config set api_url https://api.velonus.dev\n```\n\n## 输出格式\n\n### terminal（默认）\n\n使用 Rich 库渲染彩色表格，包含严重级别徽章、文件路径、行号、规则 ID 和消息。适合交互式使用。 资料来源：[apps/cli/README.md:100-130]()\n\n```\n┏━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃\n┡━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩\n│ 🔴 CRITICAL│ secrets│ config.yml │ 5 │ aws-key │ AWS key detected │\n│ 🟠 HIGH │ bandit │ app.py │ 42 │ B301 │ Pickle deserial... │\n└────────────┴────────┴────────────┴───────┴──────────┴────────────────────┘\n```\n\n### JSON\n\n适合管道传递或存储结果。\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n### SARIF\n\n静态分析结果交换格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具。**Phase 1** 可用。\n\nSARIF 格式化器负责将扫描结果转换为符合规范的 SARIF 2.1.0 输出：\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"Convert a rule_id to a PascalCase display name for SARIF.\n\n Strips any tool-prefix segment (e.g. ``\"secrets/generic-api-key\"``\n becomes ``\"GenericApiKey\"``).\"\"\"\n```\n\n目录 URI 处理遵循 SARIF 规范 §3.14.14，确保目录 URI 以 `/` 结尾：\n\n```python\ndef _dir_uri(path: Path) -> str:\n \"\"\"Return a file:// URI for a directory, ensuring a trailing slash.\"\"\"\n uri = path.as_uri()\n return uri if uri.endswith(\"/\") else uri + \"/\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:1-50]()\n\n## 严重级别\n\n| 徽章 | 级别 | 颜色 | 适用场景 |\n|---|---|---|---|\n| 🔴 | `CRITICAL` | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 | `LOW` | 蓝色 | 不安全默认值、次要配置错误 |\n| ⚪ | `INFO` | 灰色 | 样式问题、信息性备注 |\n\n建议使用 `--severity high` 仅显示需要立即处理的问题；使用 `--severity info`（默认）查看所有发现。\n\n## 扫描管道\n\n扫描管道由多个检测器组成，每个检测器负责特定类型的安全问题扫描。\n\n### secrets — 密钥检测\n\n支持两种检测模式：\n\n1. **TruffleHog 集成**：调用 TruffleHog3 二进制进行已知密钥模式检测\n2. **熵值检测回退**：基于 Shannon 熵阈值检测高熵字符串\n\n```python\ndef _entropy_scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Entropy-based regex secret scanner — trufflehog fallback.\n\n Walks the target path recursively, skipping non-code directories and\n binary file extensions.\"\"\"\n```\n\n跳过目录包括：`.git`、`node_modules`、`__pycache__`、`.venv`、`venv`、`.env`、`dist`、`build` 等。 资料来源：[packages/scanner/scanner/detectors/secrets.py:1-80]()\n\n### semgrep — 代码模式扫描\n\n调用 Semgrep 进行基于规则的代码静态分析，默认使用 `p/python` 规则集。\n\n```python\ndef scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Run semgrep on target and return findings as RawFinding instances.\n\n Invokes ``semgrep scan --config p/python --json --quiet --metrics=off ``.\"\"\"\n```\n\nSemgrep 以退出码 1 返回发现时，**不**视为错误——JSON 输出仍然完全有效并正常解析。退出码 2+ 才表示真正的错误。 资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-50]()\n\n### pip-audit — 依赖漏洞审计\n\n解析 pip-audit 的 JSON 输出，提取漏洞信息、CWE 分类和修复版本建议。\n\n```python\ndef _extract_cvss_score(cvss_list: Any) -> float | None:\n \"\"\"Extract the highest CVSS v3 base score from pip-audit's cvss array.\n\n pip-audit embeds CVSS data as a list of score objects::\n\n [{\"type\": \"CVSS_V3\", \"score\": \"CVSS:3.1/...\", \"base_score\": 7.5}]\"\"\"\n```\n\n漏洞元数据包含：包名、包版本、别名、修复版本、CVSS 评分、CWE、OWASP 分类，以及 `fix_available` 标志驱动终端格式化器的 UI 徽章。 资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1-60]()\n\n### safety — 安全依赖检查\n\n支持 Safety CLI 的 v1 和 v2 两种 JSON 输出格式：\n\n- **v2 格式**：字典结构，包含 `\"vulnerabilities\"` 键\n- **v1 格式**：列表结构，每个元素为 5 元素列表\n\n```python\ndef _parse_entry_v2(self, entry: dict, attribution_path: str) -> RawFinding | None:\n \"\"\"Parse a v2-format vulnerability entry.\n\n Required fields: ``vulnerability_id``, ``package_name``,\n ``analyzed_version``.\"\"\"\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:1-100]()\n\n## CI/CD 集成\n\n### GitHub Actions\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n # exits 1 if HIGH or CRITICAL findings are found — blocks the merge\n```\n\n### Pre-commit Hook\n\n添加到 `.pre-commit-config.yaml`：\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 发展阶段路线图\n\n| 阶段 | 状态 | 功能范围 |\n|---|---|---|\n| Phase 0 — 基础 | ✅ 完成 | CLI 骨架、Rich 输出、`NormalizedFinding` 模型 |\n| Phase 1 — 扫描管道 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、SARIF |\n| Phase 2 — AI 层 | 🔨 进行中 | AI 优先级排序、可利用性评分、修复生成 |\n| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| Phase 4 — 仪表盘 | 🔴 未开始 | Web UI、扫描历史、问题趋势 |\n\n## 代码质量要求\n\n项目对 CLI 代码有严格的代码质量标准：\n\n### Ruff 格式化\n\n```bash\n# 检查格式化\nruff format --check .\n\n# 自动格式化\nruff format .\n```\n\n### Mypy 严格模式\n\n```bash\nmypy apps/cli/shield --strict --ignore-missing-imports\nmypy packages/scanner --strict --ignore-missing-imports\n```\n\n所有新代码必须通过 mypy 严格检查且零错误。引入 `type: ignore` 注释的 PR 需要在代码注释中附带说明。 资料来源：[CONTRIBUTING.md:1-50]()\n\n### PR 指南\n\n1. **每次 PR 一个功能或修复**：不要捆绑不相关的更改\n2. **必须包含测试**：每个新的扫描器包装器、格式化器或工具函数需要匹配的单元测试\n3. **Ruff 必须通过**：本地推送前运行 `ruff check . && ruff format --check .`\n4. **mypy 必须通过**：本地运行 `mypy apps/cli/shield --strict --ignore-missing-imports`\n5. **目标 main 分支**：所有 PR 合并到 main，无长期特性分支\n6. **描述变更**：填写 PR 模板，清晰的描述和完整的检查清单\n7. **保持小规模**：400 行以下 diff 的 PR 审核更快，必要时拆分大型更改\n8. **禁止 AI 占位代码**：每个函数必须功能完整且经过测试\n\n---\n\n\n\n## API 服务系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [AI 引擎](#page-ai-engine), [部署与基础设施](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n**注意：以下API相关文件未在当前检索上下文中找到实际源码内容，页面内容基于项目文档和已知架构信息整理。**\n\n- [apps/api/shield_api/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/main.py)\n- [apps/api/shield_api/routers/scans.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/scans.py)\n- [apps/api/shield_api/routers/findings.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/findings.py)\n- [apps/api/shield_api/routers/remediation.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/remediation.py)\n- [apps/api/shield_api/routers/github.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/github.py)\n- [apps/api/shield_api/services/scan_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/scan_service.py)\n- [apps/api/shield_api/services/ai_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/ai_service.py)\n- [apps/api/shield_api/middleware/auth.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/middleware/auth.py)\n- [apps/api/shield_api/middleware/rate_limit.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/middleware/rate_limit.py)\n- [apps/api/shield_api/background/ai_worker.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/background/ai_worker.py)\n- [apps/api/shield_api/background/scan_worker.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/background/scan_worker.py)\n \n\n# API 服务系统\n\n## 概述\n\nVelonus 的 API 服务系统（`apps/api/shield_api/`）是整个安全扫描平台的核心后端服务，负责接收扫描请求、协调安全工具执行、管理扫描结果，并提供 AI 驱动的漏洞修复建议。该系统基于 FastAPI 构建，采用模块化架构设计，将功能划分为路由（routers）、服务（services）、中间件（middleware）和后台任务（background workers）四个层次。\n\n根据项目路线图，API 服务系统属于 **Phase 2 — AI Layer** 阶段的核心组件，目前处于 `Building`（构建中）状态。资料来源：[README.md]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[客户端 / CLI] -->|HTTP REST API| B[API Gateway]\n B --> C[认证中间件
auth.py]\n B --> D[限流中间件
rate_limit.py]\n C --> E[路由层]\n \n E --> F1[scans.py]\n E --> F2[findings.py]\n E --> F3[remediation.py]\n E --> F4[github.py]\n \n F1 --> G1[scan_service.py]\n F2 --> G1\n F3 --> G2[ai_service.py]\n \n G1 --> H1[scan_worker.py
后台扫描任务]\n G2 --> H2[ai_worker.py
AI 任务队列]\n \n H1 --> I[安全扫描器]\n I --> J1[Bandit]\n I --> J2[Semgrep]\n I --> J3[pip-audit]\n I --> J4[Safety]\n I --> J5[Trufflehog]\n \n H2 --> K[AI 修复建议引擎]\n \n G1 --> L[(结果存储)]\n H2 --> L\n```\n\n### 核心组件说明\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| **main.py** | `apps/api/shield_api/main.py` | FastAPI 应用入口，配置路由、中间件和生命周期事件 |\n| **scans.py** | `apps/api/shield_api/routers/scans.py` | 扫描任务的创建、查询和状态管理 API |\n| **findings.py** | `apps/api/shield_api/routers/findings.py` | 漏洞发现结果的分页查询和过滤 API |\n| **remediation.py** | `apps/api/shield_api/routers/remediation.py` | AI 驱动的漏洞修复建议 API |\n| **github.py** | `apps/api/shield_api/routers/github.py` | GitHub 集成相关 API（Webhooks、PR 评论） |\n| **scan_service.py** | `apps/api/shield_api/services/scan_service.py` | 扫描编排服务，协调各安全工具执行 |\n| **ai_service.py** | `apps/api/shield_api/services/ai_service.py` | AI 修复建议生成服务 |\n| **auth.py** | `apps/api/shield_api/middleware/auth.py` | Clerk OAuth 认证中间件 |\n| **rate_limit.py** | `apps/api/shield_api/middleware/rate_limit.py` | API 请求限流中间件 |\n| **scan_worker.py** | `apps/api/shield_api/background/scan_worker.py` | 异步扫描任务执行器 |\n| **ai_worker.py** | `apps/api/shield_api/background/ai_worker.py` | 异步 AI 任务处理器 |\n\n## 认证与授权\n\n### 认证机制\n\nVelonus API 使用 **Clerk** 进行身份认证，支持浏览器 OAuth 流程。资料来源：[apps/cli/README.md]()\n\n认证中间件 `auth.py` 负责：\n\n- 验证用户访问令牌的有效性\n- 提取用户身份信息并注入请求上下文\n- 保护需要认证的 API 端点\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API\n participant Clerk\n \n Client->>API: 请求 + Bearer Token\n API->>Clerk: 验证 Token\n Clerk-->>API: Token 有效 / 无效\n API->>Client: 200 OK / 401 Unauthorized\n```\n\n### CLI 认证命令\n\n| 命令 | 功能 |\n|------|------|\n| `velonus auth login` | 通过 Clerk 浏览器 OAuth 流程认证 |\n| `velonus auth logout` | 清除存储的凭证 |\n| `velonus auth status` | 显示当前认证状态 |\n\n> 注意：认证功能在 Phase 2 阶段完全可用，Phase 0 阶段仅为存根实现。资料来源：[apps/cli/README.md]()\n\n## 限流策略\n\n`rate_limit.py` 中间件实现了 API 请求限流机制，用于：\n\n- 防止 API 滥用和资源耗尽\n- 确保多租户环境下的公平使用\n- 保护后端扫描任务不被过度触发\n\n限流策略的具体参数和阈值需参考实际配置文件或环境变量设置。\n\n## 扫描服务\n\n### 扫描流程\n\n```mermaid\ngraph LR\n A[创建扫描任务] --> B[scan_worker 接收]\n B --> C[调用 scan_service]\n C --> D[并行执行安全工具]\n D --> E1[Bandit]\n D --> E2[Semgrep]\n D --> E3[pip-audit]\n D --> E4[Safety]\n D --> E5[Trufflehog]\n E1 --> F[结果标准化]\n E2 --> F\n E3 --> F\n E4 --> F\n E5 --> F\n F --> G[存储 NormalizedFinding]\n G --> H[返回扫描结果]\n```\n\n### 支持的安全扫描器\n\n| 扫描器 | 类型 | 用途 |\n|--------|------|------|\n| **Bandit** | SAST | Python 代码安全分析 |\n| **Semgrep** | SAST | 多语言代码规则扫描（使用 `p/python` 规则集） |\n| **pip-audit** | 依赖审计 | Python 依赖漏洞扫描 |\n| **Safety** | 依赖审计 | Python 依赖安全检查（支持 v1/v2 两种输出格式） |\n| **Trufflehog** | 密钥扫描 | 高熵值密钥和敏感信息检测 |\n\n### 扫描退出码语义\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别漏洞 |\n| `1` | 扫描完成，发现一个或多个 HIGH/CRITICAL 级别漏洞 |\n\n退出码 1 是有意设计的，用于 CI/CD 流程中的门禁检查。资料来源：[apps/cli/README.md]()\n\n## AI 修复服务\n\n### AI 层架构\n\nPhase 2 的核心功能是 AI 驱动的漏洞优先级排序和修复建议生成。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n A[发现结果] --> B[ai_service.py]\n B --> C[可利用性评分]\n B --> D[优先级计算]\n B --> E[修复建议生成]\n \n C --> F[AI 评分模型]\n D --> F\n E --> G[ai_worker.py]\n G --> H[修复方案输出]\n```\n\n### ai_worker.py 职责\n\n`ai_worker.py` 是后台 AI 任务处理器，负责：\n\n- 接收来自 AI 服务的异步任务\n- 调用 AI 模型进行漏洞分析和修复建议生成\n- 管理任务队列和重试逻辑\n- 返回结构化的修复方案\n\n## GitHub 集成\n\n`github.py` 路由提供与 GitHub 平台的集成能力：\n\n- 接收 GitHub Webhook 事件（push、pull_request）\n- 在 PR 中内联显示安全扫描结果\n- 提供一键修复建议的接受功能\n\n此功能属于 **Phase 3 — GitHub PR Integration** 阶段，规划中。资料来源：[README.md]()\n\n## 数据模型\n\n### NormalizedFinding\n\n核心数据结构，用于统一不同安全工具的输出格式：\n\n```python\n@dataclass\nclass NormalizedFinding:\n tool: str # 来源工具名称\n rule_id: str # 规则标识符\n file: str # 文件路径\n line: int # 代码行号\n severity: str # 严重级别\n message: str # 人类可读消息\n code_snippet: str # 代码片段\n metadata: dict # 额外元数据\n```\n\n### 严重级别定义\n\n| 级别 | 颜色 | 场景 |\n|------|------|------|\n| 🔴 CRITICAL | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 LOW | 蓝色 | 不安全默认值、轻微配置问题 |\n| ⚪ INFO | 灰色 | 样式问题、信息性提示 |\n\n资料来源：[apps/cli/README.md]()\n\n## API 端点概览\n\n### 扫描相关\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/scans` | POST | 创建新扫描任务 |\n| `/scans/{id}` | GET | 获取扫描详情 |\n| `/scans/{id}/status` | GET | 获取扫描状态 |\n\n### 发现结果\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/findings` | GET | 分页查询漏洞发现 |\n| `/findings/{id}` | GET | 获取单个发现详情 |\n| `/findings/{id}/metadata` | GET | 获取发现元数据 |\n\n### 修复建议\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/remediation/{finding_id}` | GET | 获取 AI 修复建议 |\n| `/remediation/{finding_id}/apply` | POST | 尝试应用修复 |\n\n### GitHub 集成\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/github/webhook` | POST | 接收 GitHub Webhook 事件 |\n| `/github/pr-comment` | POST | 在 PR 中添加评论 |\n\n## 输出格式\n\n### 支持的格式\n\n| 格式 | 用途 | 适用场景 |\n|------|------|----------|\n| `terminal` | 彩色 Rich 表格（默认） | 交互式使用 |\n| `json` | 结构化 JSON | 管道处理、工具集成 |\n| `sarif` | SARIF 标准格式 | GitHub Code Scanning、VS Code |\n\n### SARIF 输出\n\nSARIF（Static Analysis Results Interchange Format）输出与 GitHub Security 标签兼容，可直接上传至 GitHub 进行漏洞展示。资料来源：[apps/cli/shield/formatters/sarif.py]()\n\n## 部署配置\n\n### 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `CLERK_PUBLISHABLE_KEY` | Clerk 认证公钥 |\n| `CLERK_SECRET_KEY` | Clerk 认证密钥 |\n| `DATABASE_URL` | 数据库连接字符串 |\n| `REDIS_URL` | Redis 连接（任务队列） |\n\n### 配置管理\n\n```bash\n# 查看当前配置\nvelonus config show\n\n# 设置配置项\nvelonus config set api_url https://api.velonus.dev\n```\n\n## 开发与贡献\n\n### 代码质量要求\n\n| 检查工具 | 模式 | 说明 |\n|----------|------|------|\n| **ruff** | 格式检查 | `ruff format --check .` |\n| **ruff** | 代码检查 | `ruff check .` |\n| **mypy** | 严格类型检查 | `mypy apps/cli/shield --strict --ignore-missing-imports` |\n\n### PR 指南\n\n1. **单功能原则**：每个 PR 只包含一个功能或修复\n2. **测试要求**：新增功能必须附带对应的单元测试\n3. **代码规范**：必须通过 ruff 和 mypy 检查\n4. **PR 描述**：清晰说明变更内容和动机\n5. **代码行数**：建议 PR 变更行数小于 400 行\n\n资料来源：[CONTRIBUTING.md]()\n\n## 路线图\n\n| 阶段 | 状态 | 功能 |\n|------|------|------|\n| Phase 0 — Foundation | ✅ 完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |\n| Phase 1 — Scanner Pipeline | ✅ 完成 | 密钥检测、Bandit、Semgrep、pip-audit、SARIF |\n| **Phase 2 — AI Layer** | 🔨 构建中 | AI 优先级排序、可利用性评分、修复生成 |\n| Phase 3 — GitHub Integration | 🔜 规划中 | PR 内联评论、一键修复建议 |\n| Phase 4 — Dashboard | 🔜 规划中 | Web UI、扫描历史、漏洞趋势 |\n\n资料来源：[README.md]()\n\n## 状态说明\n\n| 符号 | 含义 |\n|------|------|\n| ✅ | 已完成 |\n| 🔨 | 正在构建 |\n| 🔜 | 规划中 |\n\n> **Alpha 提示**：Velonus 当前处于 Alpha 阶段，API 服务系统仍在积极开发中，可能存在不稳定性和 API 变更。请关注 [GitHub Issues](https://github.com/AliAmmar15/Velonus/issues) 获取最新动态并报告问题。\n\n---\n\n\n\n## 安全扫描器管道\n\n### 相关页面\n\n相关主题：[数据标准化模块](#page-normalizer), [系统架构](#page-architecture), [使用指南与最佳实践](#page-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [packages/scanner/scanner/detectors/bandit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/bandit.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n \n\n# 安全扫描器管道\n\n## 概述\n\n安全扫描器管道（Scanner Pipeline）是 Velonus 安全扫描工具的核心组件，负责协调和执行多种安全扫描工具，对代码仓库进行全面的安全漏洞检测。管道设计遵循模块化架构，将不同的安全检测工具（检测器）作为独立的插件集成到统一的工作流中。\n\n管道的主要职责包括：\n\n- **并行执行**：协调多个安全扫描工具的并发执行\n- **结果收集**：统一收集各检测器的原始发现（RawFinding）\n- **数据规范化**：将不同工具的输出格式转换为统一的 NormalizedFinding 数据结构\n- **格式输出**：支持多种输出格式（终端、JSON、SARIF）\n\n资料来源：[packages/scanner/scanner/pipeline.py]()\n\n## 架构设计\n\n### 整体架构\n\nVelonus 的安全扫描器采用插件化架构，核心管道负责调度，各检测器负责具体的扫描逻辑。这种设计使得添加新的扫描工具变得简单，只需实现对应的检测器接口即可。\n\n```mermaid\ngraph TD\n A[用户输入
velonus scan ./] --> B[ScannerPipeline]\n B --> C[SecretDetector]\n B --> D[BanditDetector]\n B --> E[SemgrepDetector]\n B --> F[PipAuditDetector]\n B --> G[SafetyDetector]\n C --> H[RawFinding List]\n D --> I[RawFinding List]\n E --> J[RawFinding List]\n F --> K[RawFinding List]\n G --> L[RawFinding List]\n H --> M[FindingNormalizer]\n I --> M\n J --> M\n K --> M\n L --> M\n M --> N[NormalizedFinding List]\n N --> O[Output Formatters]\n O --> P[Terminal
JSON
SARIF]\n```\n\n### 组件层次\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 入口层 | CLI (`velonus scan`) | 解析命令行参数，调用管道 |\n| 管道层 | `ScannerPipeline` | 协调检测器执行，收集结果 |\n| 检测层 | 各 Detector 实现 | 执行具体的扫描工具 |\n| 规范化层 | `FindingNormalizer` | 转换为统一数据模型 |\n| 输出层 | Formatters | 将结果渲染为不同格式 |\n\n## 扫描管道核心\n\n### ScannerPipeline 类\n\n`ScannerPipeline` 是管道的中央调度器，负责管理检测器的生命周期和执行顺序。\n\n```mermaid\ngraph LR\n A[初始化] --> B[执行扫描]\n B --> C[并行运行所有检测器]\n C --> D[收集RawFinding]\n D --> E[规范化处理]\n E --> F[返回NormalizedFinding列表]\n```\n\n管道支持以下配置参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `target` | `Path` | 必需 | 扫描目标路径（文件或目录） |\n| `severity` | `str` | `\"info\"` | 最小严重级别过滤 |\n| `tools` | `list[str]` | `None` | 指定运行的检测器，None表示全部 |\n| `verbose` | `bool` | `False` | 是否显示详细输出 |\n\n### 执行流程\n\n1. **初始化阶段**：加载所有启用的检测器实例\n2. **扫描阶段**：各检测器独立扫描目标路径，管道等待所有检测完成\n3. **规范化阶段**：将 RawFinding 转换为 NormalizedFinding 统一格式\n4. **输出阶段**：根据用户指定的格式输出结果\n\n## 检测器模块\n\n### 密钥检测器（SecretsDetector）\n\n**文件位置**：`packages/scanner/scanner/detectors/secrets.py`\n\n密钥检测器是 Velonus 的核心检测功能，负责发现代码库中的敏感信息泄露，包括 API 密钥、密码、证书等。\n\n#### 检测策略\n\n密钥检测器采用双重检测机制：\n\n```mermaid\ngraph TD\n A[扫描目标] --> B{Trufflehog可用?}\n B -->|是| C[使用Trufflehog检测]\n B -->|否| D[使用熵值检测]\n C --> E[返回验证/未验证的密钥发现]\n D --> F[正则匹配已知模式]\n D --> G[Shannon熵阈值分析]\n F --> H[高熵值判断]\n G --> H\n H --> I[返回高熵密钥发现]\n```\n\n#### Trufflehog 集成\n\n当 Trufflehog 可用时，检测器调用 Trufflehog 的解码器对文件进行深度扫描：\n\n```python\n_raw_findings.append(\n RawFinding(\n tool=\"secrets\",\n rule_id=f\"trufflehog-{detector_name.lower().replace(' ', '-')}\",\n file=file_path,\n line=line_num,\n severity=\"CRITICAL\",\n message=(\n f\"{'Verified' if verified else 'Potential'} secret detected \"\n f\"[{detector_name}] — value starts: {redacted}\"\n ),\n code_snippet=redacted,\n metadata={\n \"detector\": detector_name,\n \"verified\": verified,\n \"decoder\": str(obj.get(\"DecoderName\", \"\")),\n },\n )\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:20-35]()\n\n#### 熵值检测（后备方案）\n\n当 Trufflehog 不可用时，使用基于 Shannon 熵的启发式检测方法：\n\n- **跳过目录**：`.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build` 等\n- **跳过文件扩展名**：二进制文件（图片、压缩包等）被排除\n- **熵值阈值**：当字符串的 Shannon 熵超过阈值时，判定为可能的密钥\n\n```python\nif entropy >= _ENTROPY_THRESHOLD:\n findings.append(\n RawFinding(\n tool=\"secrets\",\n rule_id=\"high-entropy-secret\",\n file=str(path),\n line=line_num,\n severity=\"CRITICAL\",\n message=(\n f\"High-entropy string in secret assignment \"\n f\"(Shannon entropy={entropy:.2f}) — likely a hardcoded credential\"\n ),\n code_snippet=_redact_line(line_text, candidate),\n metadata={\"entropy\": round(entropy, 3)},\n )\n )\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:60-80]()\n\n### Bandit 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/bandit.py`\n\nBandit 是一个专门用于检测 Python 代码安全问题的静态分析工具，Velonus 通过 subprocess 调用 Bandit 并解析其 JSON 输出。\n\n| 特性 | 说明 |\n|------|------|\n| 工具类型 | 本地 Python 安全扫描器 |\n| 依赖 | Bandit 必须安装（`pip install bandit`） |\n| 输出格式 | JSON → RawFinding |\n\n### Semgrep 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/semgrep.py`\n\nSemgrep 是一个支持多语言的静态分析工具，Velonus 使用其 Python 规则集进行扫描。\n\n#### 可用性检查\n\n检测器首先检查 Semgrep 是否在 PATH 中可用：\n\n```python\ndef _semgrep_available(self) -> bool:\n try:\n subprocess.run(\n [\"semgrep\", \"--version\"],\n capture_output=True,\n check=False,\n timeout=10,\n )\n return True\n except FileNotFoundError:\n return False\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:50-60]()\n\n#### 执行命令\n\n```bash\nsemgrep scan --config p/python --json --quiet --metrics=off \n```\n\n| 参数 | 说明 |\n|------|------|\n| `--config p/python` | 使用 Python 规则集 |\n| `--json` | 输出 JSON 格式 |\n| `--quiet` | 抑制非必要输出 |\n| `--metrics=off` | 禁用遥测数据收集 |\n\n### pip-audit 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/pip_audit.py`\n\npip-audit 是 Python 生态系统的依赖漏洞扫描工具，用于检测项目依赖中已知的 CVE 漏洞。\n\n#### 严重级别映射\n\n| CVSS 分数范围 | 严重级别 |\n|--------------|---------|\n| 9.0 - 10.0 | CRITICAL |\n| 7.0 - 8.9 | HIGH |\n| 4.0 - 6.9 | MEDIUM |\n| 0.1 - 3.9 | LOW |\n| 0 | INFO |\n\n#### CVSS 分数提取\n\n```python\ndef _extract_cvss_score(cvss_list: Any) -> float | None:\n \"\"\"Extract the highest CVSS v3 base score from pip-audit's cvss array.\n\n pip-audit embeds CVSS data as a list of score objects::\n\n [{\"type\": \"CVSS_V3\", \"score\": \"CVSS:3.1/...\", \"base_score\": 7.5}]\n \"\"\"\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:80-95]()\n\n### Safety 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/safety.py`\n\nSafety 是另一个 Python 依赖安全扫描工具，与 pip-audit 互补使用以获得更全面的覆盖。\n\n#### 必需字段\n\n解析 Safety 输出时，以下字段为必需：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `vulnerability_id` | `str` | 漏洞唯一标识 |\n| `package_name` | `str` | 受影响包名 |\n| `analyzed_version` | `str` | 当前安装版本 |\n\n缺少必需字段的条目将被跳过并记录警告：\n\n```python\ntry:\n vuln_id: str = str(entry[\"vulnerability_id\"])\n package_name: str = str(entry[\"package_name\"])\n installed_version: str = str(entry[\"analyzed_version\"])\nexcept (KeyError, TypeError) as exc:\n logger.warning(\"safety v2: skipping malformed entry: %s\", exc)\n return None\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:45-60]()\n\n## 数据模型\n\n### RawFinding\n\n各检测器输出的原始发现对象，包含工具特定的数据结构。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tool` | `str` | 来源工具名称 |\n| `rule_id` | `str` | 规则标识符 |\n| `file` | `str` | 关联文件路径 |\n| `line` | `int` | 代码行号 |\n| `severity` | `str` | 严重级别 |\n| `message` | `str` | 人类可读的消息 |\n| `code_snippet` | `str` | 相关代码片段 |\n| `metadata` | `dict` | 额外元数据 |\n\n### NormalizedFinding\n\n规范化的统一发现格式，支持跨扫描去重和一致输出。\n\n**文件位置**：`packages/normalizer/models.py`\n\n```mermaid\nclassDiagram\n class NormalizedFinding {\n +str id\n +str tool\n +str rule_id\n +list~str~ cwe\n +list~str~ owasp\n +Severity severity\n +Confidence confidence\n +str file\n +int line_start\n +int line_end\n +str code_snippet\n +str message\n +bool fix_available\n +bool suppressed\n +datetime first_seen\n }\n \n class Severity {\n <>\n CRITICAL\n HIGH\n MEDIUM\n LOW\n INFO\n }\n \n class Confidence {\n <>\n HIGH\n MEDIUM\n LOW\n }\n```\n\n#### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `str` | 确定性 SHA-256 指纹（tool+file+line+rule_id 前16位） |\n| `cwe` | `list[str]` | CWE 列表，如 `[\"CWE-89\"]` |\n| `owasp` | `list[str]` | OWASP 分类，如 `[\"A03:2021\"]` |\n| `fix_available` | `bool` | 是否有可用修复版本 |\n| `suppressed` | `bool` | 是否被规则抑制 |\n\n资料来源：[packages/normalizer/models.py:35-60]()\n\n## 使用方式\n\n### 命令行接口\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 指定路径扫描\nvelonus scan ./my-project\n\n# 仅显示高危和严重问题\nvelonus scan ./ --severity high\n\n# JSON 格式输出\nvelonus scan ./ --format json\n\n# SARIF 格式（用于 GitHub Security）\nvelonus scan ./ --format sarif -o results.sarif\n\n# 详细输出模式\nvelonus scan ./ --verbose\n```\n\n### 退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 问题 |\n\n退出码 `1` 用于 CI/CD 流程中阻断合并。\n\n### CI/CD 集成\n\n#### GitHub Actions\n\n```yaml\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n - name: Install velonus-cli\n run: pip install -e apps/cli\n - name: Run security scan\n run: velonus scan ./ --severity high\n```\n\n#### Pre-commit Hook\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 扩展开发\n\n### 添加新检测器\n\n要添加新的安全检测工具，需要创建新的检测器类并实现标准接口：\n\n1. **创建检测器类**，继承基础 Detector 接口\n2. **实现 `scan()` 方法**，返回 `list[RawFinding]`\n3. **处理工具不存在**的情况，返回空列表\n4. **在管道中注册**检测器\n\n```python\nclass NewToolDetector:\n def scan(self, target: Path) -> list[RawFinding]:\n \"\"\"执行新工具扫描并返回标准化发现\"\"\"\n if not self._tool_available():\n logger.warning(\"new-tool not found — skipping\")\n return []\n return self._run_scan(target)\n```\n\n### 严重级别过滤\n\n管道支持按严重级别过滤结果：\n\n| 级别 | 颜色 | 用途 |\n|------|------|------|\n| CRITICAL | 红色 | 硬编码密钥、RCE、认证绕过 |\n| HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| LOW | 蓝色 | 不安全默认值、次要配置错误 |\n| INFO | 灰色 | 样式问题、信息性说明 |\n\n## 相关资源\n\n- 源码仓库：[Velonus GitHub](https://github.com/AliAmmar15/Velonus)\n- 问题反馈：[GitHub Issues](https://github.com/AliAmmar15/Velonus/issues)\n- 安全漏洞：请参阅 [SECURITY.md](SECURITY.md)（不要公开提交）\n\n---\n\n\n\n## 数据标准化模块\n\n### 相关页面\n\n相关主题：[安全扫描器管道](#page-scanner), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/normalizer/normalizer.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/normalizer.py)\n- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n- [packages/normalizer/deduplicator.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/deduplicator.py)\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n \n\n# 数据标准化模块\n\n## 模块概述\n\n数据标准化模块（Normalizer Package）是 Velonus 安全扫描系统的核心组件之一，负责将来自不同安全工具的扫描结果统一转换为标准的发现数据格式。该模块位于 `packages/normalizer/` 目录下，是连接扫描检测器与输出格式化器的桥梁。\n\n数据标准化模块的主要职责包括：\n\n1. **格式统一**：将 Bandit、Semgrep、pip-audit、Safety、Secrets 等多种扫描工具的原始输出转换为统一的 `NormalizedFinding` 数据结构\n2. **数据去重**：基于确定性哈希算法消除跨扫描的重复发现\n3. **元数据丰富**：提取 CWE、OWASP 等安全分类标准，增强发现数据的可分析性\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph 扫描检测器层\n B[Bandit]\n SG[Semgrep]\n PA[pip-audit]\n SA[Safety]\n ST[Secrets]\n end\n \n subgraph 数据标准化模块\n RF[RawFinding 原始发现]\n FN[FindingNormalizer 标准化器]\n DF[DeduplicationFilter 去重过滤器]\n NF[NormalizedFinding 标准发现]\n end\n \n subgraph 输出格式化层\n TF[Terminal 终端]\n JF[JSON]\n SF[SARIF]\n end\n \n B --> RF\n SG --> RF\n PA --> RF\n SA --> RF\n ST --> RF\n RF --> FN\n FN --> DF\n DF --> NF\n NF --> TF\n NF --> JF\n NF --> SF\n```\n\n## 核心数据模型\n\n### RawFinding（原始发现）\n\n`RawFinding` 是各扫描检测器产生的原始数据结构，包含扫描工具返回的原始字段信息。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tool` | `str` | 工具名称（bandit/semgrep/pip-audit/safety/secrets） |\n| `rule_id` | `str` | 规则标识符 |\n| `file` | `str` | 发现的文件路径 |\n| `line` | `int` | 代码行号 |\n| `severity` | `str` | 严重程度（CRITICAL/HIGH/MEDIUM/LOW/INFO） |\n| `message` | `str` | 发现描述信息 |\n| `code_snippet` | `str` | 相关代码片段 |\n| `metadata` | `dict` | 工具特定的元数据 |\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:90-110]()\n\n### NormalizedFinding（标准发现）\n\n`NormalizedFinding` 是整个系统的规范发现格式，所有扫描工具的输出最终都会转换为这种格式。\n\n```python\n@dataclass\nclass NormalizedFinding:\n id: str # deterministic: sha256(tool+file+line+rule_id)[:16]\n tool: str # \"bandit\"|\"semgrep\"|\"secrets\"|\"pip-audit\"|\"safety\"\n rule_id: str\n cwe: list[str] # e.g. [\"CWE-89\"]\n owasp: list[str] # e.g. [\"A03:2021\"]\n severity: Severity # CRITICAL | HIGH | MEDIUM | LOW | INFO\n confidence: Confidence # HIGH | MEDIUM | LOW\n file: str\n line_start: int\n line_end: int\n code_snippet: str\n message: str\n fix_available: bool = False\n suppressed: bool = False\n first_seen: datetime = field(default_factory=datetime.utcnow)\n```\n\n**关键设计特点**：\n\n- **确定性 ID**：通过 SHA-256 哈希算法 `sha256(tool + file + line + rule_id)` 生成前 16 位十六进制字符作为唯一标识符，确保相同漏洞在不同扫描中具有相同 ID\n- **安全分类**：标准化提取 CWE 和 OWASP 分类标识符\n- **时间追踪**：记录首次发现时间 `first_seen`\n\n资料来源：[packages/normalizer/models.py:46-70]()\n\n### Severity 枚举\n\n严重程度等级定义：\n\n| 枚举值 | 说明 | 使用场景 |\n|--------|------|----------|\n| `CRITICAL` | 严重 | 硬编码密钥、RCE、认证绕过 |\n| `HIGH` | 高危 | SQL 注入、命令注入、不安全反序列化 |\n| `MEDIUM` | 中危 | XSS、弱加密、路径遍历 |\n| `LOW` | 低危 | 不安全默认值、轻微配置错误 |\n| `INFO` | 信息 | 代码风格问题、信息性备注 |\n\n### Confidence 枚举\n\n置信度等级反映工具的检测确定性（非严重程度）：\n\n| 枚举值 | 说明 |\n|--------|------|\n| `HIGH` | 高置信度，检测结果可靠 |\n| `MEDIUM` | 中置信度，需人工复核 |\n| `LOW` | 低置信度，建议验证 |\n\n## 标准化流程\n\n### 完整处理流水线\n\n```mermaid\nsequenceDiagram\n participant 检测器 as 扫描检测器\n participant 标准化器 as FindingNormalizer\n participant 去重器 as DeduplicationFilter\n participant 格式化器 as 输出格式化器\n \n 检测器->>检测器: 执行安全扫描\n 检测器->>标准化器: 产出 RawFinding 列表\n 标准化器->>标准化器: 验证必填字段\n 标准化器->>标准化器: 映射严重程度\n 标准化器->>标准化器: 提取 CWE/OWASP\n 标准化器->>标准化器: 生成确定性 ID\n 标准化器->>去重器: 产出 NormalizedFinding\n 去重器->>去重器: 计算哈希指纹\n 去重器->>去重器: 过滤重复发现\n 去重器->>格式化器: 返回去重后列表\n```\n\n### FindingNormalizer 标准化器\n\n`FindingNormalizer` 负责将 `RawFinding` 转换为 `NormalizedFinding`，主要处理逻辑包括：\n\n1. **字段验证**：检查必填字段（tool、rule_id、file）是否存在\n2. **严重程度映射**：将各工具的原始严重程度值映射到规范枚举值\n3. **分类提取**：从元数据中提取 CWE 和 OWASP 分类代码\n4. **ID 生成**：计算确定性哈希作为唯一标识符\n\n```python\n# 严重程度映射示例（Semgrep → 规范值）\n_SEVERITY_MAP = {\n \"ERROR\": \"HIGH\",\n \"WARNING\": \"MEDIUM\",\n \"INFO\": \"INFO\",\n}\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:40-50]()\n\n### CWE 提取逻辑\n\nCWE（Common Weakness Enumeration）分类通过正则表达式从工具元数据中提取：\n\n```python\n_CWE_EXTRACT_RE = re.compile(r\"CWE-\\d+\", re.IGNORECASE)\n\ndef _extract_cwe(raw: Any) -> list[str]:\n \"\"\"从 semgrep 元数据提取规范化 CWE 标识符\"\"\"\n if not raw:\n return []\n items: list[Any] = raw if isinstance(raw, list) else [raw]\n # 正则匹配并去重\n ...\n return result # e.g. [\"CWE-78\", \"CWE-89\"]\n```\n\n**提取规则**：\n- 支持字符串或列表格式的输入\n- 正则表达式匹配：`CWE-\\d+`（不区分大小写）\n- 自动规范化为首字母大写格式（如 `cwe-78` → `CWE-78`）\n- 自动去重，保持插入顺序\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:25-45]()\n\n### OWASP 提取逻辑\n\nOWASP（Open Web Application Security Project）分类的提取方式与 CWE 类似：\n\n```python\n_OWASP_EXTRACT_RE = re.compile(r\"A\\d{2}(?::\\d{4})?\", re.IGNORECASE)\n\ndef _extract_owasp(raw: Any) -> list[str]:\n \"\"\"从 semgrep 元数据提取规范化 OWASP 代码\"\"\"\n # 支持多种格式：[\"A03:2021 - Injection\"] | \"A03:2021\" | []\n ...\n return result # e.g. [\"A03:2021\"]\n```\n\n**支持的格式**：\n- 完整描述：`[\"A03:2021 - Injection\"]`\n- 纯代码格式：`\"A03:2021\"`\n- 空值：`[]` 或 `None`\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:55-80]()\n\n## 去重机制\n\n### DeduplicationFilter\n\n`DeduplicationFilter` 组件负责跨扫描会话的发现去重，基于 `NormalizedFinding.id` 字段进行哈希比对。\n\n```mermaid\ngraph LR\n A[发现 A: ID=abc123] --> B{已见过?}\n C[发现 C: ID=abc123] --> B\n D[发现 B: ID=def456] --> B\n B -->|是| E[跳过]\n B -->|否| F[保留并记录]\n```\n\n**去重策略**：\n\n| 策略 | 说明 |\n|------|------|\n| 基于 ID 去重 | 同一工具、文件、行号、规则的发现视为同一漏洞 |\n| 跨工具去重 | 不同工具检测到同一漏洞时合并 |\n| 时间窗口 | 保留首次发现时间 `first_seen` |\n\n**确定性 ID 算法**：\n\n```\nID = SHA-256(tool + file + line + rule_id)[:16]\n```\n\n这种设计确保：\n- 相同漏洞在不同扫描中产生相同 ID\n- 便于历史数据比对和趋势分析\n- 支持增量扫描和变更检测\n\n资料来源：[packages/normalizer/models.py:50-55]()\n\n## 与扫描管道的集成\n\n### ScanPipeline 集成架构\n\n`ScanPipeline` 是扫描流水线的主协调器，集成数据标准化模块的处理流程：\n\n```python\nfrom normalizer.deduplicator import DeduplicationFilter\nfrom normalizer.normalizer import FindingNormalizer\nfrom normalizer.models import NormalizedFinding, Severity\n\nclass ScanPipeline:\n async def run(self, target: Path, verbose: bool = False) -> list[NormalizedFinding]:\n # 1. 并行运行所有检测器\n raw_findings = await self._run_all_detectors(target)\n \n # 2. 标准化处理\n normalizer = FindingNormalizer()\n normalized = normalizer.normalize(raw_findings)\n \n # 3. 去重过滤\n deduplicator = DeduplicationFilter()\n deduplicated = deduplicator.filter(normalized)\n \n return deduplicated\n```\n\n**并行检测器支持**：\n\n| 检测器 | 工具类型 | 输出格式 |\n|--------|----------|----------|\n| `BanditRunner` | 静态分析 | JSON |\n| `SemgrepRunner` | 静态分析 | JSON |\n| `PipAuditRunner` | 依赖审计 | JSON |\n| `SafetyRunner` | 依赖审计 | JSON |\n| `SecretsDetector` | 密钥扫描 | 自定义 |\n\n资料来源：[packages/scanner/scanner/pipeline.py:1-50]()\n\n### 执行时序\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 命令行\n participant Pipeline as ScanPipeline\n participant Detector as 检测器集合\n participant Normalizer as FindingNormalizer\n participant Deduplicator as DeduplicationFilter\n \n CLI->>Pipeline: scan(path, options)\n Pipeline->>Detector: 并行执行 5 个检测器\n Detector-->>Pipeline: RawFinding[]\n Pipeline->>Normalizer: normalize(raw_findings)\n Normalizer-->>Pipeline: NormalizedFinding[]\n Pipeline->>Deduplicator: filter(findings)\n Deduplicator-->>Pipeline: 去重后列表\n Pipeline-->>CLI: 最终结果\n```\n\n## 输出格式支持\n\n标准化后的 `NormalizedFinding` 支持多种输出格式：\n\n| 格式 | 用途 | 文件 |\n|------|------|------|\n| `terminal` | 交互式彩色输出（默认） | Rich 表格 + 严重程度徽章 |\n| `json` | 机器可读格式 | 管道集成 |\n| `sarif` | GitHub Code Scanning | SARIF 规范 |\n\n### SARIF 格式化\n\nSARIF（Static Analysis Results Interchange Format）格式化器将标准发现转换为符合 OASIS SARIF 规范的输出：\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"将 rule_id 转换为 PascalCase 显示名称\"\"\"\n base = rule_id.split(\"/\")[-1]\n return \"\".join(word.capitalize() for word in base.replace(\"-\", \"_\").split(\"_\"))\n```\n\n**转换示例**：\n- `generic-api-key` → `GenericApiKey`\n- `secrets/aws-access-key-id` → `AwsAccessKeyId`\n\n资料来源：[apps/cli/shield/formatters/sarif.py:40-60]()\n\n## 错误处理与容错\n\n### 字段缺失处理\n\n标准化器对缺失字段采用宽松策略：\n\n| 场景 | 处理方式 | 日志级别 |\n|------|----------|----------|\n| 必填字段缺失 | 跳过该发现 | WARNING |\n| 可选字段缺失 | 使用默认值 | DEBUG |\n| JSON 解析失败 | 返回空列表 | ERROR |\n\n```python\ntry:\n check_id: str = str(entry[\"check_id\"])\n path: str = str(entry[\"path\"])\n start_line: int = int(entry[\"start\"][\"line\"])\nexcept (KeyError, ValueError, TypeError) as exc:\n logger.warning(\"Skipping malformed semgrep result: %s\", exc)\n return None # 不中断整个扫描\n```\n\n### 日志记录\n\n模块使用 Python 标准 `logging` 模块，遵循以下日志级别约定：\n\n| 级别 | 使用场景 |\n|------|----------|\n| DEBUG | 详细流程信息、解析计数 |\n| INFO | 扫描完成摘要、处理统计 |\n| WARNING | 单个发现跳过（不影响整体） |\n| ERROR | 致命错误（如 JSON 解析失败） |\n\n## 配置与扩展\n\n### 严重程度阈值\n\n用户可通过 CLI 参数控制最低显示严重程度：\n\n```bash\nvelonus scan ./ --severity high # 仅显示 HIGH 和 CRITICAL\nvelonus scan ./ --severity medium # 显示 MEDIUM 及以上\n```\n\n### 新增检测器集成\n\n集成新的扫描工具需要：\n\n1. 实现检测器类，返回 `RawFinding` 列表\n2. 在 `ScanPipeline` 中注册检测器\n3. 配置严重程度映射（如需要）\n4. 添加 CWE/OWASP 元数据提取（如适用）\n\n```python\n# packages/scanner/scanner/detectors/custom.py\nfrom .secrets import RawFinding\n\nclass CustomRunner:\n def run(self, target: Path) -> list[RawFinding]:\n # 实现扫描逻辑\n ...\n```\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n normalizer -->|无外部依赖| stdlib\n \n scanner_pipeline --> normalizer\n scanner_pipeline --> detectors\n \n scanners --> scanner_pipeline\n \n cli --> scanners\n cli --> formatters\n \n formatters --> normalizer\n```\n\n**依赖约束**：\n- `normalizer` 包不依赖其他业务包，仅依赖 Python 标准库\n- `scanner` 包依赖 `normalizer` 包\n- `apps/cli` 依赖 `scanner` 和 `normalizer`\n\n## 总结\n\n数据标准化模块是 Velonus 安全扫描系统的基础设施层，承担着格式统一、数据丰富和去重过滤的关键职责。通过 `RawFinding` → `NormalizedFinding` → 去重过滤的处理流程，系统实现了：\n\n- **多工具统一**：不同扫描工具的输出具有一致的内部表示\n- **跨扫描去重**：基于确定性哈希避免重复报告\n- **分类标准化**：CWE/OWASP 分类的自动提取和规范化\n- **格式灵活**：支持多种输出格式适应不同使用场景\n\n该模块的解耦设计确保了系统的可扩展性，便于后续集成新的安全检测工具。\n\n---\n\n\n\n## AI 引擎\n\n### 相关页面\n\n相关主题：[API 服务系统](#page-api), [GitHub 集成](#page-github-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n- [packages/ai-engine/remediation_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/remediation_engine.py)\n- [packages/ai-engine/prompts.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/prompts.py)\n- [packages/ai-engine/cache.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/cache.py)\n- [apps/api/shield_api/services/ai_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/ai_service.py)\n\n**注意**：上述文件在本次检索的上下文（START_OF_CONTEXT 至 END_OF_CONTEXT）中未找到相关内容。本页说明基于项目文档（README.md、apps/cli/README.md、CONTRIBUTING.md）中的 AI 引擎相关描述以及项目路线图生成。如需获取完整的 AI 引擎实现细节，请确保在检索上下文中包含 `packages/ai-engine/` 目录下的所有源码文件。\n\n \n\n# AI 引擎\n\n## 概述\n\nAI 引擎（AI Engine）是 Velonus 安全扫描平台的核心智能组件，属于项目的 **Phase 2 — AI Layer** 阶段。根据项目路线图，AI 引擎的主要职责包括：\n\n- **漏洞优先级排序**（AI prioritization）\n- **可利用性评分**（Exploitability scoring）\n- **修复建议生成**（Fix generation）\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\nAI 引擎作为 Phase 2 的核心功能，目前处于 **Building（开发中）** 状态，尚未完成实现。\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## 架构组件\n\n根据源码文件结构，AI 引擎由以下核心模块组成：\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| **Context Engine** | `packages/ai-engine/context_engine.py` | 上下文分析引擎，处理安全发现的上下文信息 |\n| **Remediation Engine** | `packages/ai-engine/remediation_engine.py` | 修复引擎，生成漏洞修复建议 |\n| **Prompts** | `packages/ai-engine/prompts.py` | LLM 提示词管理，定义与 AI 交互的模板 |\n| **Cache** | `packages/ai-engine/cache.py` | 缓存模块，存储 AI 响应以减少 API 调用 |\n| **AI Service** | `apps/api/shield_api/services/ai_service.py` | API 服务层，暴露 AI 引擎能力给前端 |\n\n## 工作流程\n\nAI 引擎的整体工作流程如下：\n\n```mermaid\ngraph TD\n A[安全扫描结果] --> B[Context Engine
上下文分析]\n B --> C{缓存命中?}\n C -->|是| D[返回缓存结果]\n C -->|否| E[Remediation Engine
修复建议生成]\n E --> F[LLM API 调用]\n F --> G[Cache 存储结果]\n G --> D\n D --> H[AI Service API]\n H --> I[前端展示/用户交互]\n \n style A fill:#f9f,stroke:#333,stroke-width:2px\n style I fill:#ccf,stroke:#333,stroke-width:2px\n style F fill:#ffc,stroke:#333,stroke-width:2px\n```\n\n## 核心功能模块\n\n### 1. Context Engine（上下文引擎）\n\n`context_engine.py` 负责处理安全发现的上下文信息。该模块分析扫描结果中的漏洞详情，包括：\n\n- 漏洞类型与严重程度\n- 受影响文件的代码上下文\n- 相关依赖信息\n- 历史修复记录\n\n### 2. Remediation Engine（修复引擎）\n\n`remediation_engine.py` 是 AI 引擎的核心组件，负责生成针对具体漏洞的修复建议。其主要功能包括：\n\n- 分析漏洞根因\n- 生成代码级别的修复方案\n- 提供多种修复策略选项\n- 评估修复方案的安全性与兼容性\n\n### 3. Prompts（提示词管理）\n\n`prompts.py` 集中管理所有与 LLM 交互的提示词模板，包括：\n\n- 漏洞分析提示词\n- 修复建议生成提示词\n- 可利用性评估提示词\n- 优先级排序提示词\n\n### 4. Cache（缓存模块）\n\n`cache.py` 实现响应缓存机制，用于：\n\n- 减少重复的 LLM API 调用\n- 加速相同漏洞的响应时间\n- 降低 API 使用成本\n\n### 5. AI Service（API 服务）\n\n`apps/api/shield_api/services/ai_service.py` 是 AI 引擎对外暴露的 REST API 服务，提供：\n\n- 漏洞分析接口\n- 修复建议获取接口\n- 批量处理接口\n\n## 可利用性评分\n\nAI 引擎通过对漏洞的多个维度进行分析来计算可利用性评分：\n\n| 维度 | 说明 |\n|------|------|\n| **CVSS 基础分数** | 来自漏洞数据库的标准评分 |\n| **代码上下文** | 漏洞代码在实际项目中的使用方式 |\n| **攻击面** | 漏洞是否暴露在外部可访问的范围 |\n| **现有利用条件** | 是否存在已知的利用工具或脚本 |\n| **修复难度** | 应用修复方案的复杂程度 |\n\n资料来源：[apps/cli/README.md - Severity Levels](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## 修复建议生成\n\nAI 引擎生成的修复建议包含以下层次：\n\n### 代码级修复\n\n- 直接的代码修改建议\n- 安全的 API 替换方案\n- 参数化/规范化建议\n\n### 依赖级修复\n\n- 需要升级的包版本\n- 替代库建议\n- 配置修改指导\n\n### 架构级建议\n\n- 安全设计模式推荐\n- 架构重构方向\n- 防御纵深建议\n\n## 与 Phase 1 的关系\n\nAI 引擎建立在 Phase 1 扫描管道的基础之上：\n\n```mermaid\ngraph LR\n A[Phase 1
扫描管道] -->|RawFinding| B[AI Engine
上下文分析]\n B --> C[可利用性评分]\n C --> D[优先级排序]\n D --> E[修复建议生成]\n \n A -->|Bandit| A1[代码安全]\n A -->|Semgrep| A2[代码模式]\n A -->|pip-audit| A3[依赖漏洞]\n A -->|Safety| A4[包安全]\n A -->|Secrets| A5[密钥泄露]\n \n style A fill:#9f9,stroke:#333,stroke-width:2px\n style B fill:#f96,stroke:#333,stroke-width:2px\n```\n\nPhase 1 已实现的扫描工具包括：\n\n| 工具 | 用途 | 状态 |\n|------|------|------|\n| Bandit | Python 代码安全分析 | ✅ 完成 |\n| Semgrep | 多语言代码模式扫描 | ✅ 完成 |\n| pip-audit | pip 依赖漏洞审计 | ✅ 完成 |\n| Safety | Python 包安全扫描 | ✅ 完成 |\n| Secrets | 密钥/凭证检测 | ✅ 完成 |\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Phase 3 与 Phase 4 的集成\n\nAI 引擎的能力将在后续阶段被进一步利用：\n\n### Phase 3 — GitHub PR 集成\n\nAI 引擎生成的修复建议将通过 PR 内联评论直接展示给开发者，实现一键接受修复的功能。\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n### Phase 4 — Web 仪表盘\n\nAI 引擎的分析结果将集成到 Web 仪表盘中，提供：\n\n- 扫描历史趋势\n- 发现趋势分析\n- 团队安全态势概览\n\n## 认证与配置\n\nAI 引擎的功能需要通过 Velonus API 访问，认证方式采用 Clerk 浏览器 OAuth 流程：\n\n```bash\nvelonus auth login # 认证登录\nvelonus auth logout # 清除存储的凭证\nvelonus auth status # 查看当前认证状态\n```\n\n配置管理通过以下命令实现：\n\n```bash\nvelonus config show # 显示当前配置\nvelonus config set api_url https://api.velonus.dev # 设置 API 地址\n```\n\n资料来源：[apps/cli/README.md - velonus auth](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n> ⚠️ **注意**：认证和配置功能目前处于 Phase 0 的存根（stubbed）状态，将在 Phase 2 API 后端上线后完全可用。\n\n## 开发指南\n\n根据 CONTRIBUTING.md 的要求，AI 引擎代码开发需遵循以下规范：\n\n| 要求 | 说明 |\n|------|------|\n| **类型检查** | 必须通过 mypy strict 模式检查 |\n| **代码格式** | 必须通过 ruff format 检查 |\n| **代码检查** | 必须通过 ruff check 检查 |\n| **测试覆盖** | 所有新功能必须有对应的单元测试 |\n| **PR 规范** | 每个 PR 不超过 400 行 diff |\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n## 当前状态\n\n| 项目 | 状态 | 说明 |\n|------|------|------|\n| CLI 基础框架 | ✅ 完成 | Phase 0 |\n| 扫描管道 | ✅ 完成 | Phase 1 |\n| AI 上下文引擎 | 🔨 开发中 | Phase 2 |\n| 可利用性评分 | 🔨 开发中 | Phase 2 |\n| 修复建议生成 | 🔨 开发中 | Phase 2 |\n| GitHub PR 集成 | 🔜 计划中 | Phase 3 |\n| Web 仪表盘 | 🔜 计划中 | Phase 4 |\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## 相关文档\n\n- [README 主页](../README.md) — 项目概览与快速开始\n- [CLI 使用指南](../apps/cli/README.md) — 命令行工具详细文档\n- [贡献指南](../CONTRIBUTING.md) — 开发者贡献规范\n- [安全策略](../SECURITY.md) — 安全漏洞报告流程\n\n---\n\n\n\n## GitHub 集成\n\n### 相关页面\n\n相关主题：[AI 引擎](#page-ai-engine), [部署与基础设施](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n \n\n# GitHub 集成\n\n## 概述\n\nVelonus 的 GitHub 集成功能旨在将安全扫描能力深度嵌入到 GitHub 的开发工作流中。根据项目路线图，GitHub 集成属于 **Phase 3** 阶段，规划功能包括 PR 内联评论（inline review comments）和一键修复建议（one-click fix suggestions）。资料来源：[README.md:70-73]()\n\n当前版本（Phase 0-1）已实现与 GitHub 的基础集成能力，主要通过以下方式：\n\n- **GitHub Actions 工作流** 集成\n- **SARIF 格式输出** 与 GitHub Security tab 兼容\n- **Pre-commit hook** 支持\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[开发者提交代码] --> B[GitHub Actions 触发]\n B --> C[velonus scan 命令执行]\n C --> D{SARIF 输出}\n D --> E[github/codeql-action/upload-sarif]\n E --> F[GitHub Security tab]\n D --> G{Exit Code}\n G --> H[exit 0: 无高危漏洞]\n G --> I[exit 1: 发现 HIGH/CRITICAL]\n I --> J[PR 合并被阻断]\n \n subgraph \"Phase 3 规划功能\"\n K[PR 内联评论] \n L[一键修复建议]\n K --> M[velonus auth 认证]\n L --> M\n end\n```\n\n## 当前支持的集成方式\n\n### GitHub Actions 工作流集成\n\nVelonus 可作为 GitHub Actions 工作流中的安全扫描步骤运行。通过 `github/codeql-action/upload-sarif@v4` 将扫描结果上传至 GitHub Security tab。\n\n#### 基础工作流配置\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n # exits 1 if HIGH or CRITICAL findings are found — blocks the merge\n```\n\n资料来源：[apps/cli/README.md:89-111]()\n\n#### 带 SARIF 输出的工作流配置\n\n```yaml\n- name: Velonus security scan\n run: velonus scan . --sarif -o velonus-results.sarif\n\n- name: Upload to GitHub Security tab\n uses: github/codeql-action/upload-sarif@v4\n with:\n sarif_file: velonus-results.sarif\n```\n\n资料来源：[README.md:50-60]()\n\n### Pre-commit Hook 集成\n\nVelonus 可配置为 pre-commit hook，在每次提交前自动执行安全扫描。\n\n#### 配置示例\n\n在项目根目录的 `.pre-commit-config.yaml` 中添加：\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n资料来源：[apps/cli/README.md:113-122]()\n\n### Pre-commit Hook 配置参数\n\n| 参数 | 说明 |\n|------|------|\n| `entry` | 执行命令 `velonus scan` |\n| `args` | 扫描参数，`[\"/\", \"--severity\", \"high\"]` 表示扫描当前目录且仅显示 HIGH 及以上级别 |\n| `language` | `system` 表示使用系统环境中的 Python |\n| `pass_filenames` | `false` 表示不传递文件名给扫描器 |\n\n## SARIF 输出格式\n\n### 概述\n\nSARIF（Static Analysis Results Interchange Format）是与 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具兼容的标准输出格式。Velonus 通过 `--sarif` 参数生成 SARIF 文件。\n\n资料来源：[README.md:45-47]()\n\n### SARIF 文件生成命令\n\n| 命令 | 说明 |\n|------|------|\n| `velonus scan ./ --sarif` | 生成默认路径 `results/velonus.sarif` |\n| `velonus scan ./ -o results/velonus.sarif` | 指定自定义输出路径 |\n\n资料来源：[README.md:48-52]()\n\n### SARIF 规则 ID 转换\n\nVelonus 在生成 SARIF 输出时，会将内部规则 ID 转换为 PascalCase 格式的显示名称，便于在 GitHub 界面中阅读。\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"Convert a rule_id to a PascalCase display name for SARIF.\n\n Strips any tool-prefix segment (e.g. ``\"secrets/generic-api-key\"``\n becomes ``\"GenericApiKey\"``).\n \"\"\"\n base = rule_id.split(\"/\")[-1]\n return \"\".join(word.capitalize() for word in base.replace(\"-\", \"_\").split(\"_\"))\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:51-62]()\n\n### 目录 URI 规范\n\nSARIF 规范要求目录 URI 必须以斜杠结尾，Velonus 在生成输出时遵循此规范：\n\n```python\ndef _dir_uri(path: Path) -> str:\n \"\"\"Return a file:// URI for a directory, ensuring a trailing slash.\n\n SARIF spec §3.14.14 requires directory URIs to end with ``/``.\n \"\"\"\n uri = path.as_uri()\n return uri if uri.endswith(\"/\") else uri + \"/\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:28-37]()\n\n## CI/CD 阻断机制\n\n### 退出码机制\n\nVelonus 使用退出码（exit code）作为 CI/CD 管道中的安全门禁：\n\n| 退出码 | 含义 | CI 行为 |\n|--------|------|---------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别漏洞 | 允许合并 |\n| `1` | 扫描完成，发现一个或多个 HIGH/CRITICAL 级别漏洞 | 阻断合并 |\n\n资料来源：[apps/cli/README.md:73-76]()\n\n### 严重级别定义\n\n| 徽章 | 级别 | 颜色 | 典型场景 |\n|------|------|------|---------|\n| 🔴 | `CRITICAL` | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 | `LOW` | 蓝色 | 不安全默认值、次要配置问题 |\n| ⚪ | `INFO` | 灰色 | 样式问题、信息性备注 |\n\n资料来源：[apps/cli/README.md:61-69]()\n\n### 推荐配置策略\n\n```bash\n# 仅显示 HIGH 和 CRITICAL 级别\nvelonus scan ./ --severity high\n\n# 导出 JSON 格式（高危过滤）\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n## Phase 3 规划功能\n\n根据项目路线图，Phase 3 将实现更深入的 GitHub 集成：\n\n| 功能 | 说明 | 状态 |\n|------|------|------|\n| **PR 内联评论** | 在代码行级别展示漏洞信息 | 🔜 规划中 |\n| **一键修复建议** | 提供自动化修复建议并支持一键接受 | 🔜 规划中 |\n\n### Phase 3 依赖的前置条件\n\nPhase 3 功能需要以下基础设施支持：\n\n1. **认证系统**：`velonus auth` 命令（Phase 2 实现）\n ```bash\n velonus auth login # 通过 Clerk 浏览器 OAuth 流程认证\n velonus auth logout # 清除存储的凭证\n velonus auth status # 显示当前认证状态\n ```\n 资料来源：[apps/cli/README.md:77-92]()\n\n2. **配置文件管理**：`velonus config` 命令（Phase 2 实现）\n ```bash\n velonus config show # 显示当前配置\n velonus config set api_url https://api.velonus.dev # 设置配置值\n ```\n 资料来源：[apps/cli/README.md:93-104]()\n\n## 输出格式对比\n\n| 格式 | 用途 | GitHub 兼容 |\n|------|------|------------|\n| `terminal`（默认） | 交互式终端输出，彩色 Rich 表格 | ❌ |\n| `json` | 管道传输或程序化处理 | ❌ |\n| `sarif` | GitHub Code Scanning 集成 | ✅ |\n\n资料来源：[README.md:40-60]()\n\n## 相关扫描器与 GitHub 集成的漏洞数据\n\nVelonus 的各个扫描器均支持提取与 GitHub 漏洞数据库兼容的元数据：\n\n### Semgrep CWE/OWASP 提取\n\n```python\ndef _extract_cwe(raw: Any) -> list[str]:\n \"\"\"Extract canonical CWE identifiers from semgrep rule metadata.\"\"\"\n # 规范化格式：cwe-78 → CWE-78\n for match in _CWE_EXTRACT_RE.findall(str(item)):\n normalised = match.upper()\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:45-58]()\n\n### Safety CVSS 评分\n\n```python\ndef _cvss_to_severity(score: float | None) -> str:\n \"\"\"Convert CVSS v3 base score to severity level.\"\"\"\n if score is None:\n return \"MEDIUM\"\n if score >= _CVSS_CRITICAL:\n return \"CRITICAL\"\n # ...\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:80-90]()\n\n## 项目阶段概览\n\n| 阶段 | 状态 | 交付内容 |\n|------|------|---------|\n| Phase 0 — 基础 | ✅ 完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |\n| Phase 1 — 扫描管道 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、Safety |\n| Phase 2 — AI 层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复生成 |\n| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| Phase 4 — Web 仪表盘 | 🔴 未开始 | Web UI、扫描历史、漏洞趋势 |\n\n资料来源：[README.md:65-73]()\n\n## 常见问题\n\n### Q: 如何仅扫描并显示高危漏洞？\n\n```bash\nvelonus scan ./ --severity high\n```\n\n### Q: 如何将扫描结果上传到 GitHub Security tab？\n\n1. 生成 SARIF 文件：`velonus scan ./ --sarif -o velonus.sarif`\n2. 在 workflow 中使用 `github/codeql-action/upload-sarif@v4`\n\n### Q: Velonus 如何在 CI 中实现阻断？\n\n当发现 HIGH 或 CRITICAL 级别漏洞时，Velonus 返回退出码 `1`，GitHub Actions 将该步骤标记为失败，从而阻断 PR 合并。\n\n---\n\n\n\n## 部署与基础设施\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [API 服务系统](#page-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n> **注意**：查询中提到的 `infra/docker/` 目录下的 Docker 相关文件（Dockerfile.api、Dockerfile.worker、docker-compose.yml）以及 `apps/api/pyproject.toml` 未包含在当前上下文检索结果中，以下内容基于可检索的源码文件进行分析。\n\n \n\n# 部署与基础设施\n\n## 概述\n\nVelonus 是一个 Python 编写的安全扫描工具，采用单体仓库（monorepo）结构管理多个包和应用。项目当前处于 Alpha 阶段，CLI 工具已完成并可直接使用，但完整的 API 后端服务仍在开发中。资料来源：[README.md]()\n\n当前项目分为以下主要组件：\n\n| 组件 | 路径 | 用途 | 状态 |\n|------|------|------|------|\n| CLI 应用 | `apps/cli/` | 命令行入口，提供 `velonus scan` 等命令 | ✅ 已完成 |\n| Scanner 包 | `packages/scanner/` | 安全扫描引擎，包含多个检测器 | ✅ 已完成 |\n| Normalizer 包 | `packages/normalizer/` | 发现标准化与去重 | ✅ 已完成 |\n| API 服务 | `apps/api/` | AI 层与认证后端 | 🔨 Phase 2 开发中 |\n| Worker 服务 | - | 异步任务处理 | 规划中 |\n\n## 项目架构\n\nVelonus 采用分层架构设计，CLI 作为前端入口调用 Scanner 包中的各个检测器。\n\n```mermaid\ngraph TD\n A[用户终端] --> B[velonus CLI]\n B --> C[ScanPipeline]\n C --> D1[SecretsDetector]\n C --> D2[BanditRunner]\n C --> D3[SemgrepRunner]\n C --> D4[PipAuditRunner]\n C --> D5[SafetyRunner]\n D1 --> E[FindingNormalizer]\n D2 --> E\n D3 --> E\n D4 --> E\n D5 --> E\n E --> F[DeduplicationFilter]\n F --> G[NormalizedFinding]\n G --> H[Formatter]\n H --> I[终端输出 / JSON / SARIF]\n```\n\n## Scanner 包架构\n\n`packages/scanner/scanner/pipeline.py` 定义了核心扫描管道，所有检测器并行执行：\n\n```python\nfrom .detectors.bandit import BanditRunner\nfrom .detectors.pip_audit import PipAuditRunner\nfrom .detectors.safety import SafetyRunner\nfrom .detectors.secrets import SecretsDetector\nfrom .detectors.semgrep import SemgrepRunner\n```\n\n检测器执行顺序（对应索引 0-4）：\n\n```mermaid\ngraph LR\n subgraph 检测器层\n S[SecretsDetector
索引 0]\n B[BanditRunner
索引 1]\n SG[SemgrepRunner
索引 2]\n PA[PipAuditRunner
索引 3]\n SF[SafetyRunner
索引 4]\n end\n```\n\n### 检测器类型定义\n\n```python\n_ParallelRunner = BanditRunner | SemgrepRunner | PipAuditRunner | SafetyRunner\n```\n\n资料来源：[packages/scanner/scanner/pipeline.py:33]()\n\n## 开发环境部署\n\n### 环境要求\n\n| 依赖 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 最低支持版本 |\n| uv | 最新版 | 包管理工具 |\n\n资料来源：[CONTRIBUTING.md]()\n\n### 安装步骤\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/AliAmmar15/Velonus\ncd Velonus\n\n# 2. 安装所有工作区包和开发依赖\nuv sync --all-extras --dev\n\n# 3. 激活虚拟环境\nsource .venv/bin/activate # macOS / Linux\n.venv\\Scripts\\Activate.ps1 # Windows PowerShell\n\n# 4. 以可编辑模式安装 CLI 和 Scanner\npip install -e apps/cli\npip install -e packages/scanner\npip install -e packages/normalizer\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 验证安装\n\n```bash\nvelonus --help\nvelonus scan ./apps/cli/shield\n```\n\n## 本地运行\n\n### CLI 扫描命令\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 指定扫描路径\nvelonus scan ./my-project\n\n# 仅显示高危及以上级别\nvelonus scan ./ --severity high\n\n# 详细输出\nvelonus scan ./ --verbose\n\n# JSON 格式输出\nvelonus scan ./ --format json\n\n# SARIF 格式输出（用于 GitHub Security）\nvelonus scan ./ --format sarif\n```\n\n### 输出格式\n\n| 格式 | 用途 | 说明 |\n|------|------|------|\n| `terminal` | 交互式使用 | 带颜色的 Rich 表格，含徽章、路径、行号 |\n| `json` | 管道集成 | 适合传递给其他工具或存储结果 |\n| `sarif` | CI/CD 集成 | 兼容 GitHub Code Scanning，Phase 1 可用 |\n\n资料来源：[apps/cli/README.md]()\n\n### 退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 发现 HIGH 或 CRITICAL 级别问题（用作 CI 门禁） |\n\n资料来源：[apps/cli/README.md]()\n\n## CI/CD 集成\n\n### GitHub Actions 集成\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n```\n\n资料来源：[apps/cli/README.md]()\n\n### Pre-commit Hook\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 扫描管道技术细节\n\n### PipAuditRunner\n\n`packages/scanner/scanner/detectors/pip_audit.py` 负责检测依赖漏洞：\n\n- 执行 `pip-audit --format json --progress-spinner off` 子命令\n- 超时设置：120 秒（考虑 PyPI advisory DB 网络延迟）\n- 返回码处理：退出码 2+ 表示真实错误，退出码 1 表示发现漏洞（正常处理）\n\n```python\ncmd: list[str] = [\n \"pip-audit\",\n \"--format\",\n \"json\",\n \"--progress-spinner\",\n \"off\",\n]\nif req_file is not None:\n cmd.extend([\"-r\", str(req_file)])\nelse:\n cmd.append(\"--local\")\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py]()\n\n### SafetyRunner\n\n`packages/scanner/scanner/detectors/safety.py` 支持两种格式：\n\n| Safety 版本 | 输出格式 | 数据结构 |\n|-------------|----------|----------|\n| v2 (>=2.0) | JSON 对象 | `{\"vulnerabilities\": [...]}` |\n| v1 (<2.0) | JSON 列表 | `[vuln_id, pkg, version, ...]` |\n\nCVSS 评分提取逻辑：\n\n```python\ncvss_score: float | None = _extract_cvss_v2(entry.get(\"severity\"))\nseverity: str = _cvss_to_severity(cvss_score)\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py]()\n\n### SemgrepRunner\n\n`packages/scanner/scanner/detectors/semgrep.py` 使用 Semgrep 公共 Python 规则集：\n\n- 配置：`p/python`\n- 命令：`semgrep scan --config p/python --json --quiet --metrics=off `\n- 退出码 1 = 正常发现（JSON 仍有效），退出码 2+ = 错误\n\n```python\nRULESET: str = \"p/python\"\n\ndef _semgrep_available(self) -> bool:\n try:\n subprocess.run(\n [\"semgrep\", \"--version\"],\n capture_output=True,\n check=False,\n timeout=10,\n )\n return True\n except FileNotFoundError:\n return False\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py]()\n\n## 阶段性规划\n\n| 阶段 | 状态 | 内容 |\n|------|------|------|\n| Phase 0 — 基础 | ✅ 已完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |\n| Phase 1 — 扫描管道 | ✅ 已完成 | Secret 检测、Bandit、Semgrep、pip-audit、SARIF |\n| Phase 2 — AI 层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复建议生成 |\n| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| Phase 4 — Web 仪表板 | 🔴 未开始 | Web UI、扫描历史、趋势分析 |\n\n资料来源：[README.md]()\n\n## 本地开发命令\n\n### 运行测试\n\n```bash\n# 运行全部测试（当前 367 个测试，覆盖 6 个文件）\npytest apps/cli/tests/\n\n# 详细输出\npytest apps/cli/tests/ -v\n```\n\n### 代码检查\n\n```bash\n# Ruff 检查和格式化检查\nruff check . && ruff format --check .\n\n# 自动格式化\nruff format .\n\n# 类型检查（严格模式）\nmypy apps/cli/shield --strict --ignore-missing-imports\nmypy packages/normalizer --strict --ignore-missing-imports\nmypy packages/scanner --strict --ignore-missing-imports\n```\n\n> 所有新代码必须通过 mypy 严格模式检查，PR 中引入 `type: ignore` 注释需在代码注释中提供说明。\n\n资料来源：[CONTRIBUTING.md]()\n\n## 未来部署架构（规划中）\n\n当 Phase 2 API 后端上线后，系统架构预计如下：\n\n```mermaid\ngraph TD\n subgraph 前端层\n CLI[velonus CLI]\n Web[Web Dashboard
Phase 4]\n end\n \n subgraph 后端服务\n API[API Server
Phase 2]\n Worker[Async Worker
Phase 3+]\n end\n \n subgraph 数据层\n DB[(Database)]\n Cache[(Cache)]\n end\n \n CLI -->|REST API| API\n Web -->|REST API| API\n API --> DB\n API --> Cache\n Worker --> DB\n Worker --> Cache\n \n subgraph 认证\n Clerk[Clerk OAuth]\n end\n \n API --> Clerk\n```\n\n### 认证命令（Phase 2 规划）\n\n```bash\nvelonus auth login # 通过 Clerk 浏览器 OAuth 流程认证\nvelonus auth logout # 清除存储的凭证\nvelonus auth status # 显示当前认证状态\n```\n\n### 配置管理（Phase 2 规划）\n\n```bash\nvelonus config show # 打印当前配置\nvelonus config set api_url # 设置配置值\n```\n\n> Phase 0/1 中这些命令为存根实现，将在 Phase 2 API 上线后完整实现。\n\n## 项目结构总览\n\n```\nVelonus/\n├── apps/\n│ ├── cli/ # CLI 应用入口\n│ │ ├── shield/ # CLI 核心模块\n│ │ ├── formatters/ # 输出格式化器（terminal/json/sarif）\n│ │ └── tests/ # 测试套件（367 个测试）\n│ └── api/ # API 后端（Phase 2）\n│ └── pyproject.toml # API 依赖配置\n├── packages/\n│ ├── scanner/ # 扫描引擎\n│ │ └── scanner/\n│ │ ├── detectors/ # 检测器实现\n│ │ │ ├── bandit.py\n│ │ │ ├── semgrep.py\n│ │ │ ├── pip_audit.py\n│ │ │ ├── safety.py\n│ │ │ └── secrets.py\n│ │ └── pipeline.py # 扫描管道编排\n│ └── normalizer/ # 发现标准化与去重\n├── infra/\n│ └── docker/ # Docker 部署配置（待实现）\n│ ├── Dockerfile.api\n│ ├── Dockerfile.worker\n│ └── docker-compose.yml\n└── pyproject.toml # 根工作区配置\n```\n\n## 依赖管理\n\n项目使用 `uv` 作为包管理工具，所有包的依赖定义在各自目录的 `pyproject.toml` 中：\n\n- 根目录 `pyproject.toml`：定义 uv 工作区\n- `apps/cli/pyproject.toml`：CLI 应用依赖\n- `packages/scanner/pyproject.toml`：扫描器依赖（包含 bandit、semgrep 等）\n- `packages/normalizer/pyproject.toml`：标准化器依赖\n\n安装所有 extras 和 dev 依赖：\n\n```bash\nuv sync --all-extras --dev\n```\n\n## 安全门禁配置\n\nVelonus 设计为可作为安全 CI 门禁使用：\n\n```bash\n# 硬性门禁：发现 HIGH 或 CRITICAL 时退出码为 1\nvelonus scan ./ --severity high\n```\n\n建议在 CI 中配置：\n\n1. 使用 `--severity high` 过滤，仅阻断高危及以上问题\n2. 定期使用 `--severity info` 全量扫描\n3. 导出 SARIF 格式上传至 GitHub Security 标签页\n\n---\n\n> 本页基于 Velonus 项目当前阶段的源码文件编写。API 和 Worker 的 Docker 容器化部署配置将在 Phase 2/3 实现后补充。\n\n---\n\n\n\n## 使用指南与最佳实践\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI 命令行工具](#page-cli), [安全扫描器管道](#page-scanner)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n \n\n# 使用指南与最佳实践\n\nVelonus 是一款针对 Python 项目开发的自动化安全扫描工具，专注于代码中的敏感信息检测、依赖漏洞发现以及静态代码分析。本页面将详细介绍 Velonus 的安装配置、基本使用、输出格式、CI/CD 集成以及开发最佳实践，帮助用户和贡献者高效地使用该工具。\n\n---\n\n## 1. 快速入门\n\n### 1.1 安装方式\n\nVelonus 支持多种安装方式，用户可根据实际需求选择合适的方案。\n\n```bash\n# 从源码安装 CLI（开发模式）\npip install -e apps/cli\n\n# 验证安装\nvelonus --version\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 1.2 首次扫描\n\n安装完成后，即可对本地项目执行安全扫描。以下是最基础的扫描命令：\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 扫描指定项目路径\nvelonus scan ./my-python-project\n```\n\nVelonus 默认会递归扫描目标路径下的所有 Python 源文件，并调用多个安全检测工具协同工作。\n\n资料来源：[README.md:1]()\n\n---\n\n## 2. 核心命令详解\n\n### 2.1 `velonus scan` 命令\n\n`scan` 命令是 Velonus 的核心功能，用于执行完整的安全扫描流水线。\n\n```\nvelonus scan [PATH] [OPTIONS]\n```\n\n#### 参数与选项说明\n\n| 参数/选项 | 默认值 | 说明 |\n|---|---|---|\n| `PATH` | `.` | 要扫描的项目或文件路径 |\n| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |\n| `--severity`, `-s` | `info` | 最低显示严重级别：`critical`、`high`、`medium`、`low`、`info` |\n| `--verbose`, `-v` | off | 显示解析后的目标路径及额外详情 |\n| `--help` | - | 显示帮助信息并退出 |\n\n资料来源：[apps/cli/README.md:1]()\n\n#### 常用扫描示例\n\n```bash\n# 显示所有级别（默认行为）\nvelonus scan ./\n\n# 仅显示高危和严重问题\nvelonus scan ./ --severity high\n\n# 显示详细输出\nvelonus scan ./ --verbose\n\n# 导出 JSON 格式\nvelonus scan ./ --format json\n\n# 高危以上问题导出 JSON 到文件\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 2.2 `velonus auth` 命令（Phase 2）\n\n身份认证命令用于与 Velonus API 进行交互，目前在 Phase 0 阶段为存根实现，将在 Phase 2 阶段完整实现。\n\n```\nvelonus auth [COMMAND]\n```\n\n| 子命令 | 说明 |\n|---|---|\n| `velonus auth login` | 通过 Clerk 浏览器 OAuth 流程认证 |\n| `velonus auth logout` | 清除存储的凭据 |\n| `velonus auth status` | 显示当前认证状态 |\n\n资料来源：[apps/cli/README.md:1]()\n\n### 2.3 `velonus config` 命令（Phase 2）\n\n本地配置管理命令用于设置和查看 CLI 配置参数，同样在 Phase 2 阶段完整实现。\n\n```\nvelonus config [COMMAND]\n```\n\n| 子命令 | 说明 |\n|---|---|\n| `show` | 打印当前配置 |\n| `set ` | 设置配置值 |\n\n资料来源：[apps/cli/README.md:1]()\n\n---\n\n## 3. 输出格式详解\n\nVelonus 支持三种输出格式，适用于不同场景的需求。\n\n### 3.1 Terminal 格式（默认）\n\n终端格式使用 Rich 库渲染带有颜色和严重级别徽章的表格，包含文件路径、行号、规则 ID 和消息描述，是交互式使用场景的最佳选择。\n\n```\n┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 3.2 JSON 格式\n\n适用于管道传输或结果存储的纯 JSON 格式：\n\n```bash\n# 格式化输出\nvelonus scan ./ --format json | python -m json.tool\n\n# 写入文件\nvelonus scan ./ --format json > scan-results.json\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 3.3 SARIF 格式\n\nSARIF（Static Analysis Results Interchange Format）是一种标准化的静态分析结果交换格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等主流 SAST 工具。该格式将在 Phase 1 阶段完整支持。\n\n```bash\n# 输出 SARIF 到默认路径\nvelonus scan ./ --sarif\n\n# 输出到自定义路径\nvelonus scan ./ -o results/velonus.sarif\n```\n\n资料来源：[README.md:1]()\n\n---\n\n## 4. 严重级别体系\n\nVelonus 定义了五个严重级别，帮助用户快速识别和优先处理安全问题。\n\n| 徽章 | 级别 | 颜色 | 适用场景 |\n|---|---|---|---|\n| 🔴 | `CRITICAL` | 粗体红色 | 硬编码凭据、RCE、认证绕过 |\n| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 | `LOW` | 蓝色 | 不安全默认值、轻微配置错误 |\n| ⚪ | `INFO` | 灰色 | 代码风格问题、信息性备注 |\n\n资料来源：[apps/cli/README.md:1]()\n\n### 退出码规则\n\n| 退出码 | 含义 |\n|---|---|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |\n\n当检测到 HIGH 或 CRITICAL 问题时返回退出码 1，这是设计上的意图，可用于 CI 环境作为合并门禁。\n\n资料来源：[apps/cli/README.md:1]()\n\n---\n\n## 5. 扫描流水线架构\n\nVelonus 的扫描功能由多个检测器协同工作完成，形成完整的静态分析流水线。\n\n```mermaid\ngraph TD\n A[velonus scan] --> B[目标路径解析]\n B --> C[Secret 检测 TruffleHog]\n B --> D[Bandit 静态分析]\n B --> E[Semgrep 代码模式扫描]\n B --> F[pip-audit 依赖审计]\n B --> G[Safety 依赖检查]\n \n C --> H[NormalizedFinding 聚合]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[格式化输出]\n I --> J[Terminal]\n I --> K[JSON]\n I --> L[SARIF]\n```\n\n### 5.1 Secret 检测（secrets.py）\n\nSecret 检测器负责发现代码中硬编码的敏感凭据，包括：\n\n- **TruffleHog 检测器**：使用正则模式匹配已知类型的密钥（如 AWS 访问密钥、API 令牌等）\n- **熵值检测器**：当 TruffleHog 无法识别时，使用香农熵算法检测高熵字符串，识别潜在凭据\n\n```python\nif entropy >= _ENTROPY_THRESHOLD:\n findings.append(\n RawFinding(\n tool=\"secrets\",\n rule_id=\"high-entropy-secret\",\n severity=\"CRITICAL\",\n message=f\"High-entropy string in secret assignment (Shannon entropy={entropy:.2f})\"\n )\n )\n```\n\n资料来源：[packages/scanner/detectors/secrets.py:1]()\n\n### 5.2 Semgrep 静态分析\n\nSemgrep 检测器运行 Semgrep 规则集 `p/python`，执行代码模式匹配和自定义规则扫描。\n\n```python\ndef scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Run semgrep on target and return findings as RawFinding instances.\"\"\"\n if not self._semgrep_available():\n logger.warning(\"semgrep not found on PATH\")\n return []\n return self._run_semgrep(target)\n```\n\nSemgrep 以 JSON 格式输出结果，Velonus 提取关键字段并映射到标准化格式：\n\n- CWE（Common Weakness Enumeration）标识符\n- OWASP 分类代码\n- 规则级别和置信度\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:1]()\n\n### 5.3 pip-audit 依赖审计\n\npip-audit 检测器扫描 Python 项目的依赖包，识别已知漏洞。\n\n```python\ncvss_score: float | None = _extract_cvss_score(cvss_list)\nseverity: str = _cvss_to_severity(cvss_score)\n```\n\n输出包含：\n\n- CVE 或漏洞 ID\n- 受影响包名及版本\n- 修复版本建议\n- CVSS v3 评分\n\n```python\nmessage = (\n f\"[{display_id}] {package_name}=={package_version} has a known vulnerability.{fix_hint}\"\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1]()\n\n### 5.4 Safety 依赖检查\n\nSafety 检测器提供额外的依赖漏洞检测能力，支持两种输出格式：\n\n- **v2 格式**：字典结构，包含 `vulnerabilities` 列表\n- **v1 格式**：列表结构，每个元素为 5 元组\n\n```python\n# Format A: safety >= 2.0\nif isinstance(data, dict):\n vulns = data.get(\"vulnerabilities\", [])\n findings = [_parse_entry_v2(entry, ...) for entry in vulns]\n\n# Format B: safety < 2.0\nif isinstance(data, list):\n findings = [_parse_entry_v1(entry, ...) for entry in data]\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:1]()\n\n---\n\n## 6. CI/CD 集成指南\n\n### 6.1 GitHub Actions 集成\n\n在项目中添加 `.github/workflows/security.yml` 以自动执行安全扫描：\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n # exits 1 if HIGH or CRITICAL findings are found\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 6.2 SARIF 上传到 GitHub Security\n\n将扫描结果上传到 GitHub Security tab：\n\n```yaml\n- name: Velonus security scan\n run: |\n pip install velonus\n velonus scan . --sarif -o velonus.sarif\n\n- name: Upload to GitHub Security tab\n uses: github/codeql-action/upload-sarif@v4\n with:\n sarif_file: velonus.sarif\n```\n\n资料来源：[README.md:1]()\n\n### 6.3 Pre-commit 钩子配置\n\n在 `.pre-commit-config.yaml` 中配置本地钩子：\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n资料来源：[README.md:1]()\n\n---\n\n## 7. 开发贡献指南\n\n### 7.1 开发环境配置\n\n克隆仓库后，安装开发依赖：\n\n```bash\ngit clone https://github.com/AliAmmar15/Velonus\ncd Velonus\npip install -e apps/cli\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 7.2 代码格式化\n\n项目使用 `ruff` 进行代码格式化和检查：\n\n```bash\n# 检查格式问题\nruff format --check .\n\n# 自动格式化所有文件\nruff format .\n```\n\n建议在提交前同时运行检查和格式化：\n\n```bash\nruff check . && ruff format .\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 7.3 类型检查\n\n项目使用 mypy 严格模式进行类型检查：\n\n```bash\nmypy apps/cli/shield --strict --ignore-missing-imports\nmypy packages/normalizer --strict --ignore-missing-imports\nmypy packages/scanner --strict --ignore-missing-imports\n```\n\n所有新代码必须通过 mypy 严格检查，PR 中引入 `type: ignore` 注释时需要在代码注释中提供说明。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 7.4 PR 提交规范\n\n#### 提交信息格式\n\n```\n: <简短祈使句描述>\n\nTypes: feat | fix | refactor | test | docs | infra | chore\n```\n\n#### 示例\n\n```\nfeat: add semgrep CWE extraction from rule metadata\nfix: handle bandit exit code 2 on bad target path\ntest: cover pip-audit CVSS v3 threshold edge cases\ndocs: add CONTRIBUTING.md and issue templates\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n#### PR 审核准则\n\n| 准则 | 说明 |\n|---|---|\n| **单一职责** | 每个 PR 只做一个功能或修复 |\n| **测试要求** | 所有新功能必须有对应的单元测试 |\n| **代码规范** | 必须通过 ruff 和 mypy 检查 |\n| **目标分支** | 所有 PR 合并到 `main` 分支 |\n| **规模控制** | 建议 PR 少于 400 行 diff |\n| **代码质量** | 不接受 AI 生成的占位符代码 |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n## 8. 项目路线图\n\n| 阶段 | 状态 | 内容 |\n|---|---|---|\n| **Phase 0** — 基础框架 | ✅ 完成 | CLI 框架、Rich 输出、NormalizedFinding 模型 |\n| **Phase 1** — 扫描流水线 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、Safety、SARIF |\n| **Phase 2** — AI 增强层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复建议生成 |\n| **Phase 3** — GitHub 集成 | 🔴 未开始 | PR 行内评论、一键修复建议 |\n| **Phase 4** — Web 控制台 | 🔴 未开始 | Web UI、扫描历史、问题趋势分析 |\n\n资料来源：[README.md:1]()\n\n---\n\n## 9. 最佳实践总结\n\n### 9.1 扫描策略建议\n\n| 场景 | 推荐配置 |\n|---|---|\n| 交互式开发 | `velonus scan ./ --severity info`（显示所有问题） |\n| CI/CD 门禁 | `velonus scan ./ --severity high`（仅阻断高危） |\n| 报告生成 | `velonus scan ./ --format json --severity high > findings.json` |\n| 详细调试 | `velonus scan ./ --verbose` |\n\n### 9.2 性能优化\n\n- 定期运行扫描，避免累积大量问题\n- 使用 `--severity` 参数过滤低优先级问题以减少噪音\n- 在 CI 中仅扫描变更文件路径（需配合 pre-commit 钩子）\n\n### 9.3 安全配置\n\n- 敏感项目建议集成 pre-commit 钩子，在提交前强制扫描\n- 使用 GitHub Actions 自动扫描主分支和 PR\n- 定期更新本地依赖以获取最新的漏洞数据库\n\n---\n\n## 10. 常见问题\n\n**Q: 为什么扫描结果中没有 Semgrep 输出？**\n\nA: 请确认 Semgrep 已正确安装：`semgrep --version`。Velonus 会自动跳过未安装的工具并输出警告。\n\n**Q: 如何处理误报？**\n\nA: 当前版本建议使用 `--severity` 参数过滤低置信度问题。Phase 2 将提供基于 AI 的可利用性评分来辅助判断。\n\n**Q: SARIF 格式有什么用途？**\n\nA: SARIF 是静态分析结果的标准格式，可导入 GitHub Security tab、VS Code SARIF Viewer 等工具，实现可视化展示和趋势追踪。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：aliammar15/velonus\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)。\n\n## 1. 安装坑 · 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_62cdd9b76ac447b8b11064afda81fb9a | https://github.com/AliAmmar15/Velonus/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a9b7a6193ee4ea289f4dc4a12f6a0c1 | https://github.com/AliAmmar15/Velonus/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | release_recency=unknown\n\n\n",
"markdown_key": "velonus",
"pages": "draft",
"source_refs": [
{
"evidence_id": "hn_item:48143235",
"kind": "hn",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://news.ycombinator.com/item?id=48143235"
},
{
"evidence_id": "art_baab9f5d783b4b2a8ba5bad93080c056",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/AliAmmar15/Velonus#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "velonus 说明书",
"toc": [
"https://github.com/AliAmmar15/Velonus 项目说明书",
"目录",
"项目概述",
"简介",
"核心价值主张",
"系统架构",
"扫描能力矩阵",
"命令行接口",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "13e0beb4481ddee25fc7596233532b6f8726a140",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"packages/scanner/pyproject.toml",
"packages/scanner/pipeline.py",
"packages/scanner/__init__.py",
"packages/normalizer/pyproject.toml",
"packages/normalizer/normalizer.py",
"packages/normalizer/deduplicator.py",
"packages/normalizer/models.py",
"packages/normalizer/__init__.py",
"packages/ai-engine/pyproject.toml",
"packages/ai-engine/context_engine.py",
"packages/ai-engine/prompts.py",
"packages/ai-engine/remediation_engine.py",
"packages/ai-engine/__init__.py",
"packages/ai-engine/cache.py",
"packages/github/pyproject.toml",
"packages/github/comments.py",
"packages/github/app.py",
"packages/github/pr_reviewer.py",
"packages/github/__init__.py",
"packages/scanner/scanner/pipeline.py",
"packages/scanner/scanner/__init__.py",
"packages/scanner/detectors/semgrep.py",
"packages/scanner/detectors/bandit.py",
"packages/scanner/detectors/pip_audit.py",
"packages/scanner/detectors/secrets.py",
"packages/scanner/detectors/__init__.py",
"packages/scanner/scanner/detectors/safety.py",
"packages/scanner/scanner/detectors/semgrep.py",
"packages/scanner/scanner/detectors/bandit.py",
"packages/scanner/scanner/detectors/pip_audit.py",
"packages/scanner/scanner/detectors/secrets.py",
"packages/scanner/scanner/detectors/__init__.py",
"packages/ai-engine/ai_engine/__init__.py",
"packages/github/shield_github/__init__.py"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# velonus - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 velonus 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install velonus` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install uv` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install -e apps/cli` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `pip install -e packages/scanner` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pip install -e packages/normalizer` 证据：`README.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：92\n- 重要文件覆盖：9/92\n- 证据索引条目：9\n- 角色 / Skill 条目：7\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 velonus 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 velonus 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 velonus 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 7 个角色 / Skill / 项目文档条目。\n\n- **Velonus**（project_doc）：! CI https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg https://github.com/AliAmmar15/Velonus/actions ! PyPI https://img.shields.io/pypi/v/velonus https://pypi.org/project/velonus ! Python https://img.shields.io/pypi/pyversions/velonus https://pypi.org/project/velonus ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg LICENSE ! Alpha https://img.shields.io/badge/status-alpha-ora… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **velonus-cli**（project_doc）：AI-native application security scanner for developers. Finds real issues. Explains why they matter. Generates fixes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/cli/README.md`\n- **Contributing to Velonus**（project_doc）：Thank you for your interest in contributing. This guide covers everything you need to get the dev environment running and a PR merged. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Description**（project_doc）：- Bug fix - New feature - Refactor no behaviour change - Documentation update - Infrastructure / CI change 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Security Policy**（project_doc）：Do not open a public GitHub issue for security vulnerabilities. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **Bug report**（project_doc）：Field Value --- --- OS e.g. Ubuntu 22.04 / macOS 14.4 / Windows 11 Python version e.g. 3.12.3 velonus-cli version Output of velonus --version or pip show velonus-cli 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature request**（project_doc）：What frustration, gap, or limitation are you trying to address? Be specific — describe the scenario where this is painful today. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n\n## 证据索引\n\n- 共索引 9 条证据。\n\n- **Velonus**（documentation）：! CI https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg https://github.com/AliAmmar15/Velonus/actions ! PyPI https://img.shields.io/pypi/v/velonus https://pypi.org/project/velonus ! Python https://img.shields.io/pypi/pyversions/velonus https://pypi.org/project/velonus ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg LICENSE ! Alpha https://img.shields.io/badge/status-alpha-orange 证据：`README.md`\n- **velonus-cli**（documentation）：AI-native application security scanner for developers. Finds real issues. Explains why they matter. Generates fixes. 证据：`apps/cli/README.md`\n- **Contributing to Velonus**（documentation）：Thank you for your interest in contributing. This guide covers everything you need to get the dev environment running and a PR merged. 证据：`CONTRIBUTING.md`\n- **Description**（documentation）：- Bug fix - New feature - Refactor no behaviour change - Documentation update - Infrastructure / CI change 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Security Policy**（documentation）：Do not open a public GitHub issue for security vulnerabilities. 证据：`SECURITY.md`\n- **Environment**（documentation）：Field Value --- --- OS e.g. Ubuntu 22.04 / macOS 14.4 / Windows 11 Python version e.g. 3.12.3 velonus-cli version Output of velonus --version or pip show velonus-cli 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Problem this solves**（documentation）：What frustration, gap, or limitation are you trying to address? Be specific — describe the scenario where this is painful today. 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **── Python ────────────────────────────────────────────────────────────────────**（source_file）：── Python ──────────────────────────────────────────────────────────────────── pycache / .py cod $py.class .pyo .pyd .Python 证据：`.gitignore`\n- **Root uv workspace configuration for Velonus monorepo.**（source_file）：Root uv workspace configuration for Velonus monorepo. Covers all Python apps and packages in the monorepo. Using uv workspaces — do NOT use pip or poetry to manage dependencies. 证据：`pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `apps/cli/README.md`, `CONTRIBUTING.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `apps/cli/README.md`, `CONTRIBUTING.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, pyproject.toml, CONTRIBUTING.md\n- **系统架构**：importance `high`\n - source_paths: apps/cli/shield/main.py, apps/api/shield_api/main.py, packages/scanner/scanner/pipeline.py, infra/docker/docker-compose.yml\n- **CLI 命令行工具**：importance `high`\n - source_paths: apps/cli/shield/main.py, apps/cli/shield/commands/scan.py, apps/cli/shield/commands/auth.py, apps/cli/shield/commands/pr.py, apps/cli/shield/core/api_client.py\n- **API 服务系统**：importance `high`\n - source_paths: apps/api/shield_api/main.py, apps/api/shield_api/routers/scans.py, apps/api/shield_api/routers/findings.py, apps/api/shield_api/routers/remediation.py, apps/api/shield_api/routers/github.py\n- **安全扫描器管道**：importance `high`\n - source_paths: packages/scanner/scanner/pipeline.py, packages/scanner/scanner/detectors/bandit.py, packages/scanner/scanner/detectors/semgrep.py, packages/scanner/scanner/detectors/secrets.py, packages/scanner/scanner/detectors/pip_audit.py\n- **数据标准化模块**：importance `medium`\n - source_paths: packages/normalizer/normalizer.py, packages/normalizer/models.py, packages/normalizer/deduplicator.py\n- **AI 引擎**：importance `high`\n - source_paths: packages/ai-engine/context_engine.py, packages/ai-engine/remediation_engine.py, packages/ai-engine/prompts.py, packages/ai-engine/cache.py, apps/api/shield_api/services/ai_service.py\n- **GitHub 集成**：importance `medium`\n - source_paths: packages/github/app.py, packages/github/comments.py, packages/github/pr_reviewer.py, apps/cli/shield/commands/pr.py, apps/api/shield_api/routers/github.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `13e0beb4481ddee25fc7596233532b6f8726a140`\n- inspected_files: `pyproject.toml`, `README.md`, `packages/scanner/pyproject.toml`, `packages/scanner/pipeline.py`, `packages/scanner/__init__.py`, `packages/normalizer/pyproject.toml`, `packages/normalizer/normalizer.py`, `packages/normalizer/deduplicator.py`, `packages/normalizer/models.py`, `packages/normalizer/__init__.py`, `packages/ai-engine/pyproject.toml`, `packages/ai-engine/context_engine.py`, `packages/ai-engine/prompts.py`, `packages/ai-engine/remediation_engine.py`, `packages/ai-engine/__init__.py`, `packages/ai-engine/cache.py`, `packages/github/pyproject.toml`, `packages/github/comments.py`, `packages/github/app.py`, `packages/github/pr_reviewer.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_62cdd9b76ac447b8b11064afda81fb9a | https://github.com/AliAmmar15/Velonus/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3a9b7a6193ee4ea289f4dc4a12f6a0c1 | https://github.com/AliAmmar15/Velonus/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：aliammar15/velonus\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/AliAmmar15/Velonus 项目说明书\n\n生成时间：2026-05-15 02:07:26 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [CLI 命令行工具](#page-cli)\n- [API 服务系统](#page-api)\n- [安全扫描器管道](#page-scanner)\n- [数据标准化模块](#page-normalizer)\n- [AI 引擎](#page-ai-engine)\n- [GitHub 集成](#page-github-integration)\n- [部署与基础设施](#page-deployment)\n- [使用指南与最佳实践](#page-usage)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [使用指南与最佳实践](#page-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n \n\n# 项目概述\n\n## 简介\n\nVelonus 是一个本地优先的 Python 安全扫描工具（SAST），专注于在软件开发周期中自动检测安全漏洞和敏感信息泄露。该项目当前处于 Alpha 阶段，已实现核心功能并可在生产环境中使用。资料来源：[README.md:1]()\n\nVelonus 的核心设计理念是将多个业界领先的开源安全工具整合到一个统一的命令行界面中，通过标准化输出格式和可配置的严重级别过滤，帮助开发团队在本地环境和 CI/CD 流水线中快速识别和修复安全问题。\n\n## 核心价值主张\n\n| 特性 | 说明 |\n|------|------|\n| **本地优先** | 所有扫描均在本地执行，无需将代码上传到第三方服务 |\n| **多工具整合** | 统一调用 TruffleHog、Bandit、Semgrep、pip-audit、Safety 等工具 |\n| **标准化输出** | 支持 Terminal、JSON、SARIF 三种输出格式 |\n| **CI 友好** | CRITICAL/HIGH 级别发现时以退出码 1 退出，可作为合并门禁 |\n| **即插即用** | 支持 GitHub Actions 和 Pre-commit hook 集成 |\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph CLI层[\"CLI 层 (apps/cli)\"]\n A[\"velonus scan\"]\n B[\"velonus auth\"]\n C[\"velonus config\"]\n end\n \n subgraph 核心层[\"核心扫描层\"]\n D[\"扫描管道 Pipeline\"]\n E[\"结果归一化 NormalizedFinding\"]\n F[\"格式化器 Formatters\"]\n end\n \n subgraph 检测器层[\"检测器层 (packages/scanner)\"]\n G[\"secrets - 密钥扫描\"]\n H[\"bandit - 代码审计\"]\n I[\"semgrep - 静态分析\"]\n J[\"pip-audit - 依赖审计\"]\n K[\"safety - 安全检查\"]\n end\n \n subgraph 输出层[\"输出层\"]\n L[\"Terminal 格式化器\"]\n M[\"JSON 格式化器\"]\n N[\"SARIF 格式化器\"]\n end\n \n A --> D\n D --> G\n D --> H\n D --> I\n D --> J\n D --> K\n \n G --> E\n H --> E\n I --> E\n J --> E\n K --> E\n \n E --> F\n F --> L\n F --> M\n F --> N\n```\n\n### 项目目录结构\n\n```\nVelonus/\n├── apps/\n│ └── cli/\n│ ├── shield/ # CLI 主程序\n│ │ ├── __main__.py\n│ │ ├── cli.py # 命令行入口\n│ │ ├── commands/ # 子命令实现\n│ │ └── formatters/ # 输出格式化器\n│ │ ├── terminal.py\n│ │ ├── json.py\n│ │ └── sarif.py\n├── packages/\n│ ├── scanner/\n│ │ └── scanner/\n│ │ ├── detectors/ # 安全检测器\n│ │ │ ├── secrets.py # TruffleHog + 熵值检测\n│ │ │ ├── bandit.py # Bandit 集成\n│ │ │ ├── semgrep.py # Semgrep 集成\n│ │ │ ├── pip_audit.py # pip-audit 集成\n│ │ │ └── safety.py # Safety 集成\n│ │ ├── models/ # 数据模型\n│ │ │ ├── raw_finding.py\n│ │ │ └── normalized_finding.py\n│ │ └── pipeline.py # 扫描管道编排\n│ └── normalizer/ # 结果标准化模块\n└── pyproject.toml # 项目配置\n```\n\n## 扫描能力矩阵\n\n### 已集成的安全工具\n\n| 工具 | 用途 | 配置文件 |\n|------|------|----------|\n| **TruffleHog** | 硬编码密钥和凭证检测 | `secrets.py` |\n| **Bandit** | Python 代码安全分析 | `bandit.py` |\n| **Semgrep** | 高级静态分析与自定义规则 | `semgrep.py` |\n| **pip-audit** | Python 依赖漏洞扫描 | `pip_audit.py` |\n| **Safety** | Safety DB 依赖安全检查 | `safety.py` |\n\n### 严重级别定义\n\n| 级别 | 颜色标识 | 典型场景 |\n|------|----------|----------|\n| 🔴 CRITICAL | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 LOW | 蓝色 | 不安全默认值、次要配置问题 |\n| ⚪ INFO | 灰色 | 代码风格问题、信息性注释 |\n\n资料来源：[apps/cli/README.md:1]()\n\n## 命令行接口\n\n### 核心命令\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 扫描指定项目\nvelonus scan ./my-python-project\n\n# 仅显示 HIGH 和 CRITICAL 级别\nvelonus scan ./ --severity high\n\n# 输出为 JSON 格式\nvelonus scan ./ --format json\n\n# 输出为 SARIF 格式\nvelonus scan ./ --format sarif\n\n# 详细输出模式\nvelonus scan ./ --verbose\n```\n\n### 命令行参数表\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `PATH` | `.` | 要扫描的项目或文件路径 |\n| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |\n| `--severity`, `-s` | `info` | 最低显示级别 |\n| `--verbose`, `-v` | off | 显示解析后的目标路径和额外详情 |\n| `--help` | - | 显示帮助信息并退出 |\n\n资料来源：[apps/cli/README.md:1]()\n\n### 退出码约定\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |\n\n退出码 1 的设计是**有意为之**，用于将扫描结果作为 CI/CD 流水线的合并门禁条件。资料来源：[apps/cli/README.md:1]()\n\n## 输出格式详解\n\n### Terminal 格式（默认）\n\n使用 Rich 库渲染彩色表格，包含严重级别徽章、文件路径、行号、规则 ID 和详细信息。\n\n### JSON 格式\n\n适用于管道集成和结果存储：\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n### SARIF 格式\n\nSARIF（Static Analysis Results Interchange Format）是一种标准化格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具。资料来源：[apps/cli/README.md:1]()\n\n```bash\nvelonus scan ./ --format sarif\n```\n\n## 数据模型\n\n### RawFinding\n\n各检测器输出的原始发现对象，包含以下核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tool` | str | 来源工具名称（如 `secrets`、`bandit`） |\n| `rule_id` | str | 规则标识符 |\n| `file` | str | 发现漏洞的文件路径 |\n| `line` | int | 代码行号 |\n| `severity` | str | 严重级别 |\n| `message` | str | 人类可读的消息 |\n| `code_snippet` | str | 相关代码片段 |\n| `metadata` | dict | 工具特定的元数据 |\n\n### NormalizedFinding\n\n经过标准化处理的统一发现对象，格式统一后由格式化器渲染。\n\n## 开发规范\n\n### 代码质量要求\n\n项目采用严格的代码质量标准：\n\n| 检查项 | 工具 | 命令 |\n|--------|------|------|\n| 代码风格检查 | Ruff | `ruff check .` |\n| 代码格式化 | Ruff | `ruff format --check .` |\n| 静态类型检查 | mypy | `mypy --strict --ignore-missing-imports` |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 严格模式要求\n\n所有新代码必须通过 mypy strict 模式检查，零错误。引入 `type: ignore` 注释需要在代码注释中提供说明。资料来源：[CONTRIBUTING.md:1]()\n\n### Pull Request 规范\n\n| 规范 | 说明 |\n|------|------|\n| 单一职责 | 每个 PR 只包含一个功能或修复 |\n| 测试要求 | 所有新功能必须包含匹配的单元测试 |\n| 代码清理 | PR 前本地运行 ruff 和 mypy 检查 |\n| 代码行数 | 建议 PR 差异控制在 400 行以内 |\n| 无占位符 | 禁止 AI 生成的占位代码 |\n\n## CI/CD 集成\n\n### GitHub Actions 集成\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### Pre-commit Hook 配置\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 开发路线图\n\n| 阶段 | 状态 | 交付内容 |\n|------|------|----------|\n| **Phase 0** — 基础框架 | ✅ 已完成 | CLI 骨架、Rich 输出、`NormalizedFinding` 模型 |\n| **Phase 1** — 扫描管道 | ✅ 已完成 | 真正的密钥检测、Bandit、Semgrep、pip-audit、SARIF |\n| **Phase 2** — AI 层 | 🔨 进行中 | AI 优先级排序、可利用性评分、修复建议生成 |\n| **Phase 3** — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| **Phase 4** — Web 控制台 | 🔴 未开始 | Web UI、扫描历史、问题趋势 |\n\n资料来源：[README.md:1]()\n\n## 技术栈\n\n| 组件 | 技术选型 | 用途 |\n|------|----------|------|\n| CLI 框架 | Click | 命令行界面构建 |\n| 表格渲染 | Rich | 终端彩色输出 |\n| 类型系统 | Python 3.12+ | 静态类型检查 |\n| 代码检查 | Ruff | 格式化与 linting |\n| 静态分析 | Semgrep、Bandit | 代码安全分析 |\n| 依赖扫描 | pip-audit、Safety | 依赖漏洞检测 |\n| 密钥检测 | TruffleHog | 凭证扫描 |\n\n## 总结\n\nVelonus 是一个功能完整的 Python 安全扫描工具，通过统一界面整合多个业界领先的安全检测工具，为开发团队提供从本地开发到 CI/CD 流水线的全流程安全保障。项目采用严格的代码质量标准，确保长期可维护性，同时保持开放的贡献文化，欢迎社区参与改进。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI 命令行工具](#page-cli), [API 服务系统](#page-api), [安全扫描器管道](#page-scanner)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/shield/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/main.py)\n- [apps/api/shield_api/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/main.py)\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [infra/docker/docker-compose.yml](https://github.com/AliAmmar15/Velonus/blob/main/infra/docker/docker-compose.yml)\n \n\n# 系统架构\n\n## 概述\n\nVelonus 是一个模块化的安全扫描平台，采用分层架构设计。系统由 CLI 前端、扫描管道、多个检测器后端和输出格式化器组成。核心设计理念是将扫描逻辑与用户界面分离，使每个检测工具（Bandit、Semgrep、pip-audit、Safety、TruffleHog）能够独立工作，同时通过统一的 `RawFinding` 数据模型汇聚结果。\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph CLI层[\"CLI 层 (apps/cli/shield)\"]\n CLI[命令行入口]\n Formatters[格式化器]\n Main[main.py]\n end\n\n subgraph Scanner层[\"扫描器层 (packages/scanner)\"]\n Pipeline[扫描管道]\n Secrets[Secrets 检测器]\n Bandit[Bandit 检测器]\n Semgrep[Semgrep 检测器]\n PipAudit[pip-audit 检测器]\n Safety[Safety 检测器]\n end\n\n subgraph 数据模型[\"数据模型层\"]\n RawFinding[RawFinding 模型]\n NormalizedFinding[NormalizedFinding 模型]\n end\n\n subgraph API层[\"API 层 (apps/api)\"]\n API[Shield API]\n end\n\n CLI --> Main\n Main --> Formatters\n Main --> Pipeline\n Pipeline --> Secrets\n Pipeline --> Bandit\n Pipeline --> Semgrep\n Pipeline --> PipAudit\n Pipeline --> Safety\n Secrets --> RawFinding\n Bandit --> RawFinding\n Semgrep --> RawFinding\n PipAudit --> RawFinding\n Safety --> RawFinding\n Formatters --> NormalizedFinding\n Formatters --> RawFinding\n```\n\n## 核心组件\n\n### CLI 层\n\nCLI 层位于 `apps/cli/shield` 目录，负责用户交互和结果展示。\n\n| 组件 | 路径 | 职责 |\n|------|------|------|\n| main.py | apps/cli/shield/main.py | 命令行入口，参数解析，扫描协调 |\n| formatters/ | apps/cli/shield/formatters/ | 输出格式化（terminal、json、sarif） |\n| detectors/ | packages/scanner/scanner/detectors/ | 安全检测器实现 |\n\nCLI 支持的输出格式：\n\n| 格式 | 用途 | 状态 |\n|------|------|------|\n| terminal | 交互式彩色输出 | ✅ 已实现 |\n| json | 管道友好输出 | ✅ 已实现 |\n| sarif | GitHub Code Scanning 兼容 | ✅ 已实现 |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n### 扫描管道\n\n扫描管道 (`packages/scanner/scanner/pipeline.py`) 是核心编排组件，负责：\n\n1. 依次调用各个检测器\n2. 收集并归一化扫描结果\n3. 处理检测器的执行超时和错误\n\n```mermaid\ngraph LR\n A[扫描目标] --> B[Secrets 检测器]\n B --> C[Bandit 检测器]\n C --> D[Semgrep 检测器]\n D --> E[pip-audit 检测器]\n E --> F[Safety 检测器]\n F --> G[结果聚合]\n```\n\n每个检测器返回 `RawFinding` 列表，管道统一收集后传递给格式化器。\n\n### 检测器架构\n\n检测器采用统一的接口设计，每个检测器继承基础类并实现 `scan()` 方法。\n\n#### Secrets 检测器\n\n位于 `packages/scanner/scanner/detectors/secrets.py` 和 `packages/scanner/detectors/secrets.py`，实现两层检测：\n\n| 检测模式 | 描述 |\n|----------|------|\n| TruffleHog | 使用 TruffleHog 进行已知格式密钥检测 |\n| 熵值分析 | Shannon 熵阈值检测高随机性字符串 |\n\n```python\n# 熵值阈值常量\n_ENTROPY_THRESHOLD = 4.5\n```\n\n当 TruffleHog 未安装时，自动降级到熵值分析模式。检测结果包含：\n\n- `detector`: 检测器类型名称\n- `verified`: 是否经过 TruffleHog 验证\n- `decoder`: 使用的解码器名称\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:1-150](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n\n#### Semgrep 检测器\n\n位于 `packages/scanner/scanner/detectors/semgrep.py`，使用 `p/python` 规则集。\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| --config | p/python | Semgrep 规则集 |\n| --json | - | JSON 输出格式 |\n| --quiet | - | 静默模式 |\n| --metrics | off | 禁用遥测 |\n\nSemgrep 返回 1 表示发现漏洞（正常行为），返回 2+ 才表示错误。\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-50](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n\n#### 依赖漏洞检测器\n\n##### pip-audit 检测器\n\n位于 `packages/scanner/scanner/detectors/pip_audit.py`，检测 Python 依赖中的已知漏洞。\n\n关键元数据字段：\n\n| 字段 | 说明 |\n|------|------|\n| package_name | 包名称 |\n| package_version | 安装版本 |\n| cvss_score | CVSS v3 评分 |\n| fix_versions | 可修复版本列表 |\n| fix_available | 是否有修复版本 |\n\n##### Safety 检测器\n\n位于 `packages/scanner/scanner/detectors/safety.py`，支持两种输出格式：\n\n| Safety 版本 | 数据格式 |\n|-------------|----------|\n| v2 (>=2.0) | `{\"vulnerabilities\": [...]}` |\n| v1 (<2.0) | 5 元素列表数组 |\n\nCVSS 评分提取逻辑处理嵌套的 severity 字典结构。\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:1-100](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n\n## 数据模型\n\n### RawFinding\n\n所有检测器返回统一的 `RawFinding` 对象：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| tool | str | 来源工具名称 |\n| rule_id | str | 规则标识符 |\n| file | str | 文件路径 |\n| line | int | 行号 |\n| severity | str | 严重级别 |\n| message | str | 人类可读消息 |\n| code_snippet | str | 相关代码片段 |\n| metadata | dict | 工具特定元数据 |\n\n### 严重级别\n\n| 级别 | 颜色 | 典型场景 |\n|------|------|----------|\n| CRITICAL | 红色 | 硬编码密钥、RCE、认证绕过 |\n| HIGH | 橙色 | SQL 注入、命令注入 |\n| MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| LOW | 蓝色 | 不安全默认值 |\n| INFO | 灰色 | 样式问题 |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## 格式化输出\n\n### SARIF 格式化器\n\n位于 `apps/cli/shield/formatters/sarif.py`，实现 SARIF 2.1.0 规范。\n\n关键转换函数：\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"将 rule_id 转换为 PascalCase 显示名称\"\"\"\n base = rule_id.split(\"/\")[-1]\n return \"\".join(word.capitalize() for word in base.replace(\"-\", \"_\").split(\"_\"))\n```\n\n目录 URI 处理遵循 SARIF 规范 §3.14.14，强制添加尾部斜杠。\n\n### 输出格式映射\n\n| 内部级别 | SARIF 级别 |\n|----------|-----------|\n| CRITICAL | error |\n| HIGH | error |\n| MEDIUM | warning |\n| LOW | note |\n| INFO | note |\n\n## API 层\n\n位于 `apps/api/shield_api/main.py`，为 Phase 2 及后续功能预留。\n\n当前阶段：\n\n| 阶段 | 功能 | 状态 |\n|------|------|------|\n| Phase 0 | CLI 框架 | ✅ 完成 |\n| Phase 1 | 扫描管道 | ✅ 完成 |\n| Phase 2 | AI 上下文引擎 | 🔨 开发中 |\n| Phase 3 | GitHub PR 集成 | 📋 计划中 |\n| Phase 4 | Web 仪表板 | 📋 计划中 |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## 部署架构\n\n### Docker 部署\n\n项目提供 Docker Compose 配置用于容器化部署：\n\n```yaml\n# infra/docker/docker-compose.yml 结构\nservices:\n shield-api: # API 服务\n scanner: # 扫描引擎\n dashboard: # Web UI (Phase 4)\n```\n\n### CI/CD 集成\n\n系统设计支持多种 CI 场景：\n\n| 集成方式 | 配置示例 |\n|----------|----------|\n| GitHub Actions | .github/workflows/security.yml |\n| Pre-commit hook | .pre-commit-config.yaml |\n\nVelonus 在发现 HIGH 或 CRITICAL 漏洞时返回退出码 1，可作为 CI 门禁。\n\n## 贡献与质量保障\n\n项目要求严格的代码质量标准：\n\n| 检查项 | 工具 | 命令 |\n|--------|------|------|\n| 代码格式 | ruff | `ruff format --check .` |\n| 代码检查 | ruff | `ruff check .` |\n| 类型检查 | mypy | `mypy --strict` |\n\nPR 规范：\n\n- 每个 PR 只做一个改动\n- 必须包含测试\n- Diff 行数建议小于 400\n- 禁止 AI 生成的占位代码\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n## 工作流程图\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as CLI\n participant Pipeline as 扫描管道\n participant Detectors as 检测器\n participant Formatter as 格式化器\n\n User->>CLI: velonus scan ./ --severity high\n CLI->>Pipeline: 初始化扫描任务\n Pipeline->>Detectors: 并行/顺序执行检测\n Detectors-->>Pipeline: RawFinding[]\n Pipeline->>Formatter: 聚合结果\n Formatter->>User: 格式化输出\n```\n\n## 总结\n\nVelonus 采用插件化的检测器架构，每个安全工具（Bandit、Semgrep、pip-audit、Safety、TruffleHog）作为独立模块接入管道。这种设计使得系统易于扩展，新增检测器只需实现统一的 `scan()` 接口并返回 `RawFinding` 对象即可。CLI 与扫描逻辑的分离确保了核心功能可以在多种场景下复用，包括本地 CLI、CI/CD 管道和 Web 仪表板。\n\n---\n\n\n\n## CLI 命令行工具\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [API 服务系统](#page-api), [使用指南与最佳实践](#page-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/shield/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/main.py)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n \n\n# CLI 命令行工具\n\n## 概述\n\nVelonus CLI 是一个基于 Python 的命令行安全扫描工具，采用 Typer 框架构建，为开发者提供本地化的应用安全测试能力。CLI 工具支持多种安全扫描器集成，包括密钥检测、代码漏洞扫描、依赖漏洞审计等，并能输出多种格式的结果用于不同场景。\n\nCLI 的核心定位是**本地优先**，即所有核心扫描功能在不依赖后端 API 的情况下完全可用。身份验证和云端功能（如 AI 优先级排序、修复建议生成）则在后续阶段（Phase 2+）逐步实现。 资料来源：[apps/cli/shield/main.py:1-17]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[\"velonus CLI 入口
(main.py)\"] --> B[\"Typer 应用层\"]\n B --> C[\"命令模块
(commands/)\"]\n \n C --> D[\"scan 命令\"]\n C --> E[\"auth 命令\"]\n C --> F[\"config 命令\"]\n \n D --> G[\"scanner 包
(packages/scanner)\"]\n G --> H[\"检测器引擎\"]\n \n H --> I[\"secrets.py
密钥检测\"]\n H --> J[\"semgrep.py
代码模式扫描\"]\n H --> K[\"pip_audit.py
依赖漏洞审计\"]\n H --> L[\"safety.py
安全依赖检查\"]\n \n D --> M[\"格式化器
(formatters/)\"]\n M --> N[\"terminal.py
终端输出\"]\n M --> O[\"sarif.py
SARIF 格式\"]\n```\n\n### 模块职责\n\n| 模块路径 | 职责 | 状态 |\n|---|---|---|\n| `main.py` | CLI 根应用定义、Typer 实例初始化、命令组注册 | 稳定 |\n| `commands/scan.py` | `velonus scan` 命令实现、参数解析、扫描执行 | 稳定 |\n| `commands/auth.py` | `velonus auth` 认证命令（登录/登出/状态） | Phase 2 |\n| `commands/config.py` | `velonus config` 配置管理命令 | Phase 2 |\n| `core/api_client.py` | 与 Velonus 后端 API 通信 | Phase 2 |\n| `core/config.py` | 本地配置加载与存储 | Phase 2 |\n| `formatters/terminal.py` | 终端 Rich 表格输出 | 稳定 |\n| `formatters/sarif.py` | SARIF 格式生成 | Phase 1 |\n\n## 命令详解\n\n### velonus scan\n\n`velonus scan` 是核心命令，用于在本地路径上运行安全扫描管道。\n\n#### 命令语法\n\n```\nvelonus scan [PATH] [OPTIONS]\n```\n\n#### 参数与选项\n\n| 参数/选项 | 默认值 | 描述 |\n|---|---|---|\n| `PATH` | `.` | 要扫描的项目路径或文件 |\n| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |\n| `--severity`, `-s` | `info` | 最低显示严重级别：`critical`、`high`、`medium`、`low`、`info` |\n| `--verbose`, `-v` | 关闭 | 显示解析后的目标路径及额外详情 |\n| `--help` | - | 显示帮助信息并退出 |\n\n#### 使用示例\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 扫描子目录\nvelonus scan ./apps/api\n\n# 仅显示高危和严重漏洞\nvelonus scan ./ --severity high\n\n# 显示详细路径信息\nvelonus scan ./ --verbose\n\n# 导出为 JSON\nvelonus scan ./ --format json\n\n# 导出为 SARIF 格式\nvelonus scan ./ --format sarif\n\n# 高危以上结果重定向到文件\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n#### 退出码\n\n| 退出码 | 含义 |\n|---|---|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |\n\n退出码 `1` 是有意设计的，可作为 CI/CD 门禁阻止合并。 资料来源：[apps/cli/README.md:1-80]()\n\n### velonus auth\n\n认证命令用于与 Velonus API 建立连接，目前处于 **Phase 2** 阶段（桩代码状态）。\n\n| 子命令 | 描述 |\n|---|---|\n| `velonus auth login` | 通过 Clerk（浏览器 OAuth 流程）进行身份验证 |\n| `velonus auth logout` | 清除存储的凭证 |\n| `velonus auth status` | 显示当前认证状态 |\n\n```bash\nvelonus auth login\nvelonus auth logout\nvelonus auth status\n```\n\n> Phase 0 阶段这些命令为桩代码，将在 Phase 2 后端 API 上线后完整实现。\n\n### velonus config\n\n本地 CLI 配置管理命令，目前处于 **Phase 2** 阶段（桩代码状态）。\n\n| 子命令 | 描述 |\n|---|---|\n| `velonus config show` | 打印当前配置 |\n| `velonus config set ` | 设置配置值 |\n\n```bash\nvelonus config show\nvelonus config set api_url https://api.velonus.dev\n```\n\n## 输出格式\n\n### terminal（默认）\n\n使用 Rich 库渲染彩色表格，包含严重级别徽章、文件路径、行号、规则 ID 和消息。适合交互式使用。 资料来源：[apps/cli/README.md:100-130]()\n\n```\n┏━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃\n┡━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩\n│ 🔴 CRITICAL│ secrets│ config.yml │ 5 │ aws-key │ AWS key detected │\n│ 🟠 HIGH │ bandit │ app.py │ 42 │ B301 │ Pickle deserial... │\n└────────────┴────────┴────────────┴───────┴──────────┴────────────────────┘\n```\n\n### JSON\n\n适合管道传递或存储结果。\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n### SARIF\n\n静态分析结果交换格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具。**Phase 1** 可用。\n\nSARIF 格式化器负责将扫描结果转换为符合规范的 SARIF 2.1.0 输出：\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"Convert a rule_id to a PascalCase display name for SARIF.\n\n Strips any tool-prefix segment (e.g. ``\"secrets/generic-api-key\"``\n becomes ``\"GenericApiKey\"``).\"\"\"\n```\n\n目录 URI 处理遵循 SARIF 规范 §3.14.14，确保目录 URI 以 `/` 结尾：\n\n```python\ndef _dir_uri(path: Path) -> str:\n \"\"\"Return a file:// URI for a directory, ensuring a trailing slash.\"\"\"\n uri = path.as_uri()\n return uri if uri.endswith(\"/\") else uri + \"/\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:1-50]()\n\n## 严重级别\n\n| 徽章 | 级别 | 颜色 | 适用场景 |\n|---|---|---|---|\n| 🔴 | `CRITICAL` | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 | `LOW` | 蓝色 | 不安全默认值、次要配置错误 |\n| ⚪ | `INFO` | 灰色 | 样式问题、信息性备注 |\n\n建议使用 `--severity high` 仅显示需要立即处理的问题；使用 `--severity info`（默认）查看所有发现。\n\n## 扫描管道\n\n扫描管道由多个检测器组成，每个检测器负责特定类型的安全问题扫描。\n\n### secrets — 密钥检测\n\n支持两种检测模式：\n\n1. **TruffleHog 集成**：调用 TruffleHog3 二进制进行已知密钥模式检测\n2. **熵值检测回退**：基于 Shannon 熵阈值检测高熵字符串\n\n```python\ndef _entropy_scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Entropy-based regex secret scanner — trufflehog fallback.\n\n Walks the target path recursively, skipping non-code directories and\n binary file extensions.\"\"\"\n```\n\n跳过目录包括：`.git`、`node_modules`、`__pycache__`、`.venv`、`venv`、`.env`、`dist`、`build` 等。 资料来源：[packages/scanner/scanner/detectors/secrets.py:1-80]()\n\n### semgrep — 代码模式扫描\n\n调用 Semgrep 进行基于规则的代码静态分析，默认使用 `p/python` 规则集。\n\n```python\ndef scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Run semgrep on target and return findings as RawFinding instances.\n\n Invokes ``semgrep scan --config p/python --json --quiet --metrics=off ``.\"\"\"\n```\n\nSemgrep 以退出码 1 返回发现时，**不**视为错误——JSON 输出仍然完全有效并正常解析。退出码 2+ 才表示真正的错误。 资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-50]()\n\n### pip-audit — 依赖漏洞审计\n\n解析 pip-audit 的 JSON 输出，提取漏洞信息、CWE 分类和修复版本建议。\n\n```python\ndef _extract_cvss_score(cvss_list: Any) -> float | None:\n \"\"\"Extract the highest CVSS v3 base score from pip-audit's cvss array.\n\n pip-audit embeds CVSS data as a list of score objects::\n\n [{\"type\": \"CVSS_V3\", \"score\": \"CVSS:3.1/...\", \"base_score\": 7.5}]\"\"\"\n```\n\n漏洞元数据包含：包名、包版本、别名、修复版本、CVSS 评分、CWE、OWASP 分类，以及 `fix_available` 标志驱动终端格式化器的 UI 徽章。 资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1-60]()\n\n### safety — 安全依赖检查\n\n支持 Safety CLI 的 v1 和 v2 两种 JSON 输出格式：\n\n- **v2 格式**：字典结构，包含 `\"vulnerabilities\"` 键\n- **v1 格式**：列表结构，每个元素为 5 元素列表\n\n```python\ndef _parse_entry_v2(self, entry: dict, attribution_path: str) -> RawFinding | None:\n \"\"\"Parse a v2-format vulnerability entry.\n\n Required fields: ``vulnerability_id``, ``package_name``,\n ``analyzed_version``.\"\"\"\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:1-100]()\n\n## CI/CD 集成\n\n### GitHub Actions\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n # exits 1 if HIGH or CRITICAL findings are found — blocks the merge\n```\n\n### Pre-commit Hook\n\n添加到 `.pre-commit-config.yaml`：\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 发展阶段路线图\n\n| 阶段 | 状态 | 功能范围 |\n|---|---|---|\n| Phase 0 — 基础 | ✅ 完成 | CLI 骨架、Rich 输出、`NormalizedFinding` 模型 |\n| Phase 1 — 扫描管道 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、SARIF |\n| Phase 2 — AI 层 | 🔨 进行中 | AI 优先级排序、可利用性评分、修复生成 |\n| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| Phase 4 — 仪表盘 | 🔴 未开始 | Web UI、扫描历史、问题趋势 |\n\n## 代码质量要求\n\n项目对 CLI 代码有严格的代码质量标准：\n\n### Ruff 格式化\n\n```bash\n# 检查格式化\nruff format --check .\n\n# 自动格式化\nruff format .\n```\n\n### Mypy 严格模式\n\n```bash\nmypy apps/cli/shield --strict --ignore-missing-imports\nmypy packages/scanner --strict --ignore-missing-imports\n```\n\n所有新代码必须通过 mypy 严格检查且零错误。引入 `type: ignore` 注释的 PR 需要在代码注释中附带说明。 资料来源：[CONTRIBUTING.md:1-50]()\n\n### PR 指南\n\n1. **每次 PR 一个功能或修复**：不要捆绑不相关的更改\n2. **必须包含测试**：每个新的扫描器包装器、格式化器或工具函数需要匹配的单元测试\n3. **Ruff 必须通过**：本地推送前运行 `ruff check . && ruff format --check .`\n4. **mypy 必须通过**：本地运行 `mypy apps/cli/shield --strict --ignore-missing-imports`\n5. **目标 main 分支**：所有 PR 合并到 main，无长期特性分支\n6. **描述变更**：填写 PR 模板，清晰的描述和完整的检查清单\n7. **保持小规模**：400 行以下 diff 的 PR 审核更快，必要时拆分大型更改\n8. **禁止 AI 占位代码**：每个函数必须功能完整且经过测试\n\n---\n\n\n\n## API 服务系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [AI 引擎](#page-ai-engine), [部署与基础设施](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n**注意：以下API相关文件未在当前检索上下文中找到实际源码内容，页面内容基于项目文档和已知架构信息整理。**\n\n- [apps/api/shield_api/main.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/main.py)\n- [apps/api/shield_api/routers/scans.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/scans.py)\n- [apps/api/shield_api/routers/findings.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/findings.py)\n- [apps/api/shield_api/routers/remediation.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/remediation.py)\n- [apps/api/shield_api/routers/github.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/routers/github.py)\n- [apps/api/shield_api/services/scan_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/scan_service.py)\n- [apps/api/shield_api/services/ai_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/ai_service.py)\n- [apps/api/shield_api/middleware/auth.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/middleware/auth.py)\n- [apps/api/shield_api/middleware/rate_limit.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/middleware/rate_limit.py)\n- [apps/api/shield_api/background/ai_worker.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/background/ai_worker.py)\n- [apps/api/shield_api/background/scan_worker.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/background/scan_worker.py)\n \n\n# API 服务系统\n\n## 概述\n\nVelonus 的 API 服务系统（`apps/api/shield_api/`）是整个安全扫描平台的核心后端服务，负责接收扫描请求、协调安全工具执行、管理扫描结果，并提供 AI 驱动的漏洞修复建议。该系统基于 FastAPI 构建，采用模块化架构设计，将功能划分为路由（routers）、服务（services）、中间件（middleware）和后台任务（background workers）四个层次。\n\n根据项目路线图，API 服务系统属于 **Phase 2 — AI Layer** 阶段的核心组件，目前处于 `Building`（构建中）状态。资料来源：[README.md]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[客户端 / CLI] -->|HTTP REST API| B[API Gateway]\n B --> C[认证中间件
auth.py]\n B --> D[限流中间件
rate_limit.py]\n C --> E[路由层]\n \n E --> F1[scans.py]\n E --> F2[findings.py]\n E --> F3[remediation.py]\n E --> F4[github.py]\n \n F1 --> G1[scan_service.py]\n F2 --> G1\n F3 --> G2[ai_service.py]\n \n G1 --> H1[scan_worker.py
后台扫描任务]\n G2 --> H2[ai_worker.py
AI 任务队列]\n \n H1 --> I[安全扫描器]\n I --> J1[Bandit]\n I --> J2[Semgrep]\n I --> J3[pip-audit]\n I --> J4[Safety]\n I --> J5[Trufflehog]\n \n H2 --> K[AI 修复建议引擎]\n \n G1 --> L[(结果存储)]\n H2 --> L\n```\n\n### 核心组件说明\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| **main.py** | `apps/api/shield_api/main.py` | FastAPI 应用入口，配置路由、中间件和生命周期事件 |\n| **scans.py** | `apps/api/shield_api/routers/scans.py` | 扫描任务的创建、查询和状态管理 API |\n| **findings.py** | `apps/api/shield_api/routers/findings.py` | 漏洞发现结果的分页查询和过滤 API |\n| **remediation.py** | `apps/api/shield_api/routers/remediation.py` | AI 驱动的漏洞修复建议 API |\n| **github.py** | `apps/api/shield_api/routers/github.py` | GitHub 集成相关 API（Webhooks、PR 评论） |\n| **scan_service.py** | `apps/api/shield_api/services/scan_service.py` | 扫描编排服务，协调各安全工具执行 |\n| **ai_service.py** | `apps/api/shield_api/services/ai_service.py` | AI 修复建议生成服务 |\n| **auth.py** | `apps/api/shield_api/middleware/auth.py` | Clerk OAuth 认证中间件 |\n| **rate_limit.py** | `apps/api/shield_api/middleware/rate_limit.py` | API 请求限流中间件 |\n| **scan_worker.py** | `apps/api/shield_api/background/scan_worker.py` | 异步扫描任务执行器 |\n| **ai_worker.py** | `apps/api/shield_api/background/ai_worker.py` | 异步 AI 任务处理器 |\n\n## 认证与授权\n\n### 认证机制\n\nVelonus API 使用 **Clerk** 进行身份认证，支持浏览器 OAuth 流程。资料来源：[apps/cli/README.md]()\n\n认证中间件 `auth.py` 负责：\n\n- 验证用户访问令牌的有效性\n- 提取用户身份信息并注入请求上下文\n- 保护需要认证的 API 端点\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API\n participant Clerk\n \n Client->>API: 请求 + Bearer Token\n API->>Clerk: 验证 Token\n Clerk-->>API: Token 有效 / 无效\n API->>Client: 200 OK / 401 Unauthorized\n```\n\n### CLI 认证命令\n\n| 命令 | 功能 |\n|------|------|\n| `velonus auth login` | 通过 Clerk 浏览器 OAuth 流程认证 |\n| `velonus auth logout` | 清除存储的凭证 |\n| `velonus auth status` | 显示当前认证状态 |\n\n> 注意：认证功能在 Phase 2 阶段完全可用，Phase 0 阶段仅为存根实现。资料来源：[apps/cli/README.md]()\n\n## 限流策略\n\n`rate_limit.py` 中间件实现了 API 请求限流机制，用于：\n\n- 防止 API 滥用和资源耗尽\n- 确保多租户环境下的公平使用\n- 保护后端扫描任务不被过度触发\n\n限流策略的具体参数和阈值需参考实际配置文件或环境变量设置。\n\n## 扫描服务\n\n### 扫描流程\n\n```mermaid\ngraph LR\n A[创建扫描任务] --> B[scan_worker 接收]\n B --> C[调用 scan_service]\n C --> D[并行执行安全工具]\n D --> E1[Bandit]\n D --> E2[Semgrep]\n D --> E3[pip-audit]\n D --> E4[Safety]\n D --> E5[Trufflehog]\n E1 --> F[结果标准化]\n E2 --> F\n E3 --> F\n E4 --> F\n E5 --> F\n F --> G[存储 NormalizedFinding]\n G --> H[返回扫描结果]\n```\n\n### 支持的安全扫描器\n\n| 扫描器 | 类型 | 用途 |\n|--------|------|------|\n| **Bandit** | SAST | Python 代码安全分析 |\n| **Semgrep** | SAST | 多语言代码规则扫描（使用 `p/python` 规则集） |\n| **pip-audit** | 依赖审计 | Python 依赖漏洞扫描 |\n| **Safety** | 依赖审计 | Python 依赖安全检查（支持 v1/v2 两种输出格式） |\n| **Trufflehog** | 密钥扫描 | 高熵值密钥和敏感信息检测 |\n\n### 扫描退出码语义\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别漏洞 |\n| `1` | 扫描完成，发现一个或多个 HIGH/CRITICAL 级别漏洞 |\n\n退出码 1 是有意设计的，用于 CI/CD 流程中的门禁检查。资料来源：[apps/cli/README.md]()\n\n## AI 修复服务\n\n### AI 层架构\n\nPhase 2 的核心功能是 AI 驱动的漏洞优先级排序和修复建议生成。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n A[发现结果] --> B[ai_service.py]\n B --> C[可利用性评分]\n B --> D[优先级计算]\n B --> E[修复建议生成]\n \n C --> F[AI 评分模型]\n D --> F\n E --> G[ai_worker.py]\n G --> H[修复方案输出]\n```\n\n### ai_worker.py 职责\n\n`ai_worker.py` 是后台 AI 任务处理器，负责：\n\n- 接收来自 AI 服务的异步任务\n- 调用 AI 模型进行漏洞分析和修复建议生成\n- 管理任务队列和重试逻辑\n- 返回结构化的修复方案\n\n## GitHub 集成\n\n`github.py` 路由提供与 GitHub 平台的集成能力：\n\n- 接收 GitHub Webhook 事件（push、pull_request）\n- 在 PR 中内联显示安全扫描结果\n- 提供一键修复建议的接受功能\n\n此功能属于 **Phase 3 — GitHub PR Integration** 阶段，规划中。资料来源：[README.md]()\n\n## 数据模型\n\n### NormalizedFinding\n\n核心数据结构，用于统一不同安全工具的输出格式：\n\n```python\n@dataclass\nclass NormalizedFinding:\n tool: str # 来源工具名称\n rule_id: str # 规则标识符\n file: str # 文件路径\n line: int # 代码行号\n severity: str # 严重级别\n message: str # 人类可读消息\n code_snippet: str # 代码片段\n metadata: dict # 额外元数据\n```\n\n### 严重级别定义\n\n| 级别 | 颜色 | 场景 |\n|------|------|------|\n| 🔴 CRITICAL | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 LOW | 蓝色 | 不安全默认值、轻微配置问题 |\n| ⚪ INFO | 灰色 | 样式问题、信息性提示 |\n\n资料来源：[apps/cli/README.md]()\n\n## API 端点概览\n\n### 扫描相关\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/scans` | POST | 创建新扫描任务 |\n| `/scans/{id}` | GET | 获取扫描详情 |\n| `/scans/{id}/status` | GET | 获取扫描状态 |\n\n### 发现结果\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/findings` | GET | 分页查询漏洞发现 |\n| `/findings/{id}` | GET | 获取单个发现详情 |\n| `/findings/{id}/metadata` | GET | 获取发现元数据 |\n\n### 修复建议\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/remediation/{finding_id}` | GET | 获取 AI 修复建议 |\n| `/remediation/{finding_id}/apply` | POST | 尝试应用修复 |\n\n### GitHub 集成\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/github/webhook` | POST | 接收 GitHub Webhook 事件 |\n| `/github/pr-comment` | POST | 在 PR 中添加评论 |\n\n## 输出格式\n\n### 支持的格式\n\n| 格式 | 用途 | 适用场景 |\n|------|------|----------|\n| `terminal` | 彩色 Rich 表格（默认） | 交互式使用 |\n| `json` | 结构化 JSON | 管道处理、工具集成 |\n| `sarif` | SARIF 标准格式 | GitHub Code Scanning、VS Code |\n\n### SARIF 输出\n\nSARIF（Static Analysis Results Interchange Format）输出与 GitHub Security 标签兼容，可直接上传至 GitHub 进行漏洞展示。资料来源：[apps/cli/shield/formatters/sarif.py]()\n\n## 部署配置\n\n### 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `CLERK_PUBLISHABLE_KEY` | Clerk 认证公钥 |\n| `CLERK_SECRET_KEY` | Clerk 认证密钥 |\n| `DATABASE_URL` | 数据库连接字符串 |\n| `REDIS_URL` | Redis 连接（任务队列） |\n\n### 配置管理\n\n```bash\n# 查看当前配置\nvelonus config show\n\n# 设置配置项\nvelonus config set api_url https://api.velonus.dev\n```\n\n## 开发与贡献\n\n### 代码质量要求\n\n| 检查工具 | 模式 | 说明 |\n|----------|------|------|\n| **ruff** | 格式检查 | `ruff format --check .` |\n| **ruff** | 代码检查 | `ruff check .` |\n| **mypy** | 严格类型检查 | `mypy apps/cli/shield --strict --ignore-missing-imports` |\n\n### PR 指南\n\n1. **单功能原则**：每个 PR 只包含一个功能或修复\n2. **测试要求**：新增功能必须附带对应的单元测试\n3. **代码规范**：必须通过 ruff 和 mypy 检查\n4. **PR 描述**：清晰说明变更内容和动机\n5. **代码行数**：建议 PR 变更行数小于 400 行\n\n资料来源：[CONTRIBUTING.md]()\n\n## 路线图\n\n| 阶段 | 状态 | 功能 |\n|------|------|------|\n| Phase 0 — Foundation | ✅ 完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |\n| Phase 1 — Scanner Pipeline | ✅ 完成 | 密钥检测、Bandit、Semgrep、pip-audit、SARIF |\n| **Phase 2 — AI Layer** | 🔨 构建中 | AI 优先级排序、可利用性评分、修复生成 |\n| Phase 3 — GitHub Integration | 🔜 规划中 | PR 内联评论、一键修复建议 |\n| Phase 4 — Dashboard | 🔜 规划中 | Web UI、扫描历史、漏洞趋势 |\n\n资料来源：[README.md]()\n\n## 状态说明\n\n| 符号 | 含义 |\n|------|------|\n| ✅ | 已完成 |\n| 🔨 | 正在构建 |\n| 🔜 | 规划中 |\n\n> **Alpha 提示**：Velonus 当前处于 Alpha 阶段，API 服务系统仍在积极开发中，可能存在不稳定性和 API 变更。请关注 [GitHub Issues](https://github.com/AliAmmar15/Velonus/issues) 获取最新动态并报告问题。\n\n---\n\n\n\n## 安全扫描器管道\n\n### 相关页面\n\n相关主题：[数据标准化模块](#page-normalizer), [系统架构](#page-architecture), [使用指南与最佳实践](#page-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [packages/scanner/scanner/detectors/bandit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/bandit.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n \n\n# 安全扫描器管道\n\n## 概述\n\n安全扫描器管道（Scanner Pipeline）是 Velonus 安全扫描工具的核心组件，负责协调和执行多种安全扫描工具，对代码仓库进行全面的安全漏洞检测。管道设计遵循模块化架构，将不同的安全检测工具（检测器）作为独立的插件集成到统一的工作流中。\n\n管道的主要职责包括：\n\n- **并行执行**：协调多个安全扫描工具的并发执行\n- **结果收集**：统一收集各检测器的原始发现（RawFinding）\n- **数据规范化**：将不同工具的输出格式转换为统一的 NormalizedFinding 数据结构\n- **格式输出**：支持多种输出格式（终端、JSON、SARIF）\n\n资料来源：[packages/scanner/scanner/pipeline.py]()\n\n## 架构设计\n\n### 整体架构\n\nVelonus 的安全扫描器采用插件化架构，核心管道负责调度，各检测器负责具体的扫描逻辑。这种设计使得添加新的扫描工具变得简单，只需实现对应的检测器接口即可。\n\n```mermaid\ngraph TD\n A[用户输入
velonus scan ./] --> B[ScannerPipeline]\n B --> C[SecretDetector]\n B --> D[BanditDetector]\n B --> E[SemgrepDetector]\n B --> F[PipAuditDetector]\n B --> G[SafetyDetector]\n C --> H[RawFinding List]\n D --> I[RawFinding List]\n E --> J[RawFinding List]\n F --> K[RawFinding List]\n G --> L[RawFinding List]\n H --> M[FindingNormalizer]\n I --> M\n J --> M\n K --> M\n L --> M\n M --> N[NormalizedFinding List]\n N --> O[Output Formatters]\n O --> P[Terminal
JSON
SARIF]\n```\n\n### 组件层次\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 入口层 | CLI (`velonus scan`) | 解析命令行参数，调用管道 |\n| 管道层 | `ScannerPipeline` | 协调检测器执行，收集结果 |\n| 检测层 | 各 Detector 实现 | 执行具体的扫描工具 |\n| 规范化层 | `FindingNormalizer` | 转换为统一数据模型 |\n| 输出层 | Formatters | 将结果渲染为不同格式 |\n\n## 扫描管道核心\n\n### ScannerPipeline 类\n\n`ScannerPipeline` 是管道的中央调度器，负责管理检测器的生命周期和执行顺序。\n\n```mermaid\ngraph LR\n A[初始化] --> B[执行扫描]\n B --> C[并行运行所有检测器]\n C --> D[收集RawFinding]\n D --> E[规范化处理]\n E --> F[返回NormalizedFinding列表]\n```\n\n管道支持以下配置参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `target` | `Path` | 必需 | 扫描目标路径（文件或目录） |\n| `severity` | `str` | `\"info\"` | 最小严重级别过滤 |\n| `tools` | `list[str]` | `None` | 指定运行的检测器，None表示全部 |\n| `verbose` | `bool` | `False` | 是否显示详细输出 |\n\n### 执行流程\n\n1. **初始化阶段**：加载所有启用的检测器实例\n2. **扫描阶段**：各检测器独立扫描目标路径，管道等待所有检测完成\n3. **规范化阶段**：将 RawFinding 转换为 NormalizedFinding 统一格式\n4. **输出阶段**：根据用户指定的格式输出结果\n\n## 检测器模块\n\n### 密钥检测器（SecretsDetector）\n\n**文件位置**：`packages/scanner/scanner/detectors/secrets.py`\n\n密钥检测器是 Velonus 的核心检测功能，负责发现代码库中的敏感信息泄露，包括 API 密钥、密码、证书等。\n\n#### 检测策略\n\n密钥检测器采用双重检测机制：\n\n```mermaid\ngraph TD\n A[扫描目标] --> B{Trufflehog可用?}\n B -->|是| C[使用Trufflehog检测]\n B -->|否| D[使用熵值检测]\n C --> E[返回验证/未验证的密钥发现]\n D --> F[正则匹配已知模式]\n D --> G[Shannon熵阈值分析]\n F --> H[高熵值判断]\n G --> H\n H --> I[返回高熵密钥发现]\n```\n\n#### Trufflehog 集成\n\n当 Trufflehog 可用时，检测器调用 Trufflehog 的解码器对文件进行深度扫描：\n\n```python\n_raw_findings.append(\n RawFinding(\n tool=\"secrets\",\n rule_id=f\"trufflehog-{detector_name.lower().replace(' ', '-')}\",\n file=file_path,\n line=line_num,\n severity=\"CRITICAL\",\n message=(\n f\"{'Verified' if verified else 'Potential'} secret detected \"\n f\"[{detector_name}] — value starts: {redacted}\"\n ),\n code_snippet=redacted,\n metadata={\n \"detector\": detector_name,\n \"verified\": verified,\n \"decoder\": str(obj.get(\"DecoderName\", \"\")),\n },\n )\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:20-35]()\n\n#### 熵值检测（后备方案）\n\n当 Trufflehog 不可用时，使用基于 Shannon 熵的启发式检测方法：\n\n- **跳过目录**：`.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build` 等\n- **跳过文件扩展名**：二进制文件（图片、压缩包等）被排除\n- **熵值阈值**：当字符串的 Shannon 熵超过阈值时，判定为可能的密钥\n\n```python\nif entropy >= _ENTROPY_THRESHOLD:\n findings.append(\n RawFinding(\n tool=\"secrets\",\n rule_id=\"high-entropy-secret\",\n file=str(path),\n line=line_num,\n severity=\"CRITICAL\",\n message=(\n f\"High-entropy string in secret assignment \"\n f\"(Shannon entropy={entropy:.2f}) — likely a hardcoded credential\"\n ),\n code_snippet=_redact_line(line_text, candidate),\n metadata={\"entropy\": round(entropy, 3)},\n )\n )\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:60-80]()\n\n### Bandit 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/bandit.py`\n\nBandit 是一个专门用于检测 Python 代码安全问题的静态分析工具，Velonus 通过 subprocess 调用 Bandit 并解析其 JSON 输出。\n\n| 特性 | 说明 |\n|------|------|\n| 工具类型 | 本地 Python 安全扫描器 |\n| 依赖 | Bandit 必须安装（`pip install bandit`） |\n| 输出格式 | JSON → RawFinding |\n\n### Semgrep 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/semgrep.py`\n\nSemgrep 是一个支持多语言的静态分析工具，Velonus 使用其 Python 规则集进行扫描。\n\n#### 可用性检查\n\n检测器首先检查 Semgrep 是否在 PATH 中可用：\n\n```python\ndef _semgrep_available(self) -> bool:\n try:\n subprocess.run(\n [\"semgrep\", \"--version\"],\n capture_output=True,\n check=False,\n timeout=10,\n )\n return True\n except FileNotFoundError:\n return False\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:50-60]()\n\n#### 执行命令\n\n```bash\nsemgrep scan --config p/python --json --quiet --metrics=off \n```\n\n| 参数 | 说明 |\n|------|------|\n| `--config p/python` | 使用 Python 规则集 |\n| `--json` | 输出 JSON 格式 |\n| `--quiet` | 抑制非必要输出 |\n| `--metrics=off` | 禁用遥测数据收集 |\n\n### pip-audit 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/pip_audit.py`\n\npip-audit 是 Python 生态系统的依赖漏洞扫描工具，用于检测项目依赖中已知的 CVE 漏洞。\n\n#### 严重级别映射\n\n| CVSS 分数范围 | 严重级别 |\n|--------------|---------|\n| 9.0 - 10.0 | CRITICAL |\n| 7.0 - 8.9 | HIGH |\n| 4.0 - 6.9 | MEDIUM |\n| 0.1 - 3.9 | LOW |\n| 0 | INFO |\n\n#### CVSS 分数提取\n\n```python\ndef _extract_cvss_score(cvss_list: Any) -> float | None:\n \"\"\"Extract the highest CVSS v3 base score from pip-audit's cvss array.\n\n pip-audit embeds CVSS data as a list of score objects::\n\n [{\"type\": \"CVSS_V3\", \"score\": \"CVSS:3.1/...\", \"base_score\": 7.5}]\n \"\"\"\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:80-95]()\n\n### Safety 检测器\n\n**文件位置**：`packages/scanner/scanner/detectors/safety.py`\n\nSafety 是另一个 Python 依赖安全扫描工具，与 pip-audit 互补使用以获得更全面的覆盖。\n\n#### 必需字段\n\n解析 Safety 输出时，以下字段为必需：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `vulnerability_id` | `str` | 漏洞唯一标识 |\n| `package_name` | `str` | 受影响包名 |\n| `analyzed_version` | `str` | 当前安装版本 |\n\n缺少必需字段的条目将被跳过并记录警告：\n\n```python\ntry:\n vuln_id: str = str(entry[\"vulnerability_id\"])\n package_name: str = str(entry[\"package_name\"])\n installed_version: str = str(entry[\"analyzed_version\"])\nexcept (KeyError, TypeError) as exc:\n logger.warning(\"safety v2: skipping malformed entry: %s\", exc)\n return None\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:45-60]()\n\n## 数据模型\n\n### RawFinding\n\n各检测器输出的原始发现对象，包含工具特定的数据结构。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tool` | `str` | 来源工具名称 |\n| `rule_id` | `str` | 规则标识符 |\n| `file` | `str` | 关联文件路径 |\n| `line` | `int` | 代码行号 |\n| `severity` | `str` | 严重级别 |\n| `message` | `str` | 人类可读的消息 |\n| `code_snippet` | `str` | 相关代码片段 |\n| `metadata` | `dict` | 额外元数据 |\n\n### NormalizedFinding\n\n规范化的统一发现格式，支持跨扫描去重和一致输出。\n\n**文件位置**：`packages/normalizer/models.py`\n\n```mermaid\nclassDiagram\n class NormalizedFinding {\n +str id\n +str tool\n +str rule_id\n +list~str~ cwe\n +list~str~ owasp\n +Severity severity\n +Confidence confidence\n +str file\n +int line_start\n +int line_end\n +str code_snippet\n +str message\n +bool fix_available\n +bool suppressed\n +datetime first_seen\n }\n \n class Severity {\n <>\n CRITICAL\n HIGH\n MEDIUM\n LOW\n INFO\n }\n \n class Confidence {\n <>\n HIGH\n MEDIUM\n LOW\n }\n```\n\n#### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `str` | 确定性 SHA-256 指纹（tool+file+line+rule_id 前16位） |\n| `cwe` | `list[str]` | CWE 列表，如 `[\"CWE-89\"]` |\n| `owasp` | `list[str]` | OWASP 分类，如 `[\"A03:2021\"]` |\n| `fix_available` | `bool` | 是否有可用修复版本 |\n| `suppressed` | `bool` | 是否被规则抑制 |\n\n资料来源：[packages/normalizer/models.py:35-60]()\n\n## 使用方式\n\n### 命令行接口\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 指定路径扫描\nvelonus scan ./my-project\n\n# 仅显示高危和严重问题\nvelonus scan ./ --severity high\n\n# JSON 格式输出\nvelonus scan ./ --format json\n\n# SARIF 格式（用于 GitHub Security）\nvelonus scan ./ --format sarif -o results.sarif\n\n# 详细输出模式\nvelonus scan ./ --verbose\n```\n\n### 退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 问题 |\n\n退出码 `1` 用于 CI/CD 流程中阻断合并。\n\n### CI/CD 集成\n\n#### GitHub Actions\n\n```yaml\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n - name: Install velonus-cli\n run: pip install -e apps/cli\n - name: Run security scan\n run: velonus scan ./ --severity high\n```\n\n#### Pre-commit Hook\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 扩展开发\n\n### 添加新检测器\n\n要添加新的安全检测工具，需要创建新的检测器类并实现标准接口：\n\n1. **创建检测器类**，继承基础 Detector 接口\n2. **实现 `scan()` 方法**，返回 `list[RawFinding]`\n3. **处理工具不存在**的情况，返回空列表\n4. **在管道中注册**检测器\n\n```python\nclass NewToolDetector:\n def scan(self, target: Path) -> list[RawFinding]:\n \"\"\"执行新工具扫描并返回标准化发现\"\"\"\n if not self._tool_available():\n logger.warning(\"new-tool not found — skipping\")\n return []\n return self._run_scan(target)\n```\n\n### 严重级别过滤\n\n管道支持按严重级别过滤结果：\n\n| 级别 | 颜色 | 用途 |\n|------|------|------|\n| CRITICAL | 红色 | 硬编码密钥、RCE、认证绕过 |\n| HIGH | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| MEDIUM | 黄色 | XSS、弱加密、路径遍历 |\n| LOW | 蓝色 | 不安全默认值、次要配置错误 |\n| INFO | 灰色 | 样式问题、信息性说明 |\n\n## 相关资源\n\n- 源码仓库：[Velonus GitHub](https://github.com/AliAmmar15/Velonus)\n- 问题反馈：[GitHub Issues](https://github.com/AliAmmar15/Velonus/issues)\n- 安全漏洞：请参阅 [SECURITY.md](SECURITY.md)（不要公开提交）\n\n---\n\n\n\n## 数据标准化模块\n\n### 相关页面\n\n相关主题：[安全扫描器管道](#page-scanner), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/normalizer/normalizer.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/normalizer.py)\n- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n- [packages/normalizer/deduplicator.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/deduplicator.py)\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n \n\n# 数据标准化模块\n\n## 模块概述\n\n数据标准化模块（Normalizer Package）是 Velonus 安全扫描系统的核心组件之一，负责将来自不同安全工具的扫描结果统一转换为标准的发现数据格式。该模块位于 `packages/normalizer/` 目录下，是连接扫描检测器与输出格式化器的桥梁。\n\n数据标准化模块的主要职责包括：\n\n1. **格式统一**：将 Bandit、Semgrep、pip-audit、Safety、Secrets 等多种扫描工具的原始输出转换为统一的 `NormalizedFinding` 数据结构\n2. **数据去重**：基于确定性哈希算法消除跨扫描的重复发现\n3. **元数据丰富**：提取 CWE、OWASP 等安全分类标准，增强发现数据的可分析性\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph 扫描检测器层\n B[Bandit]\n SG[Semgrep]\n PA[pip-audit]\n SA[Safety]\n ST[Secrets]\n end\n \n subgraph 数据标准化模块\n RF[RawFinding 原始发现]\n FN[FindingNormalizer 标准化器]\n DF[DeduplicationFilter 去重过滤器]\n NF[NormalizedFinding 标准发现]\n end\n \n subgraph 输出格式化层\n TF[Terminal 终端]\n JF[JSON]\n SF[SARIF]\n end\n \n B --> RF\n SG --> RF\n PA --> RF\n SA --> RF\n ST --> RF\n RF --> FN\n FN --> DF\n DF --> NF\n NF --> TF\n NF --> JF\n NF --> SF\n```\n\n## 核心数据模型\n\n### RawFinding（原始发现）\n\n`RawFinding` 是各扫描检测器产生的原始数据结构，包含扫描工具返回的原始字段信息。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `tool` | `str` | 工具名称（bandit/semgrep/pip-audit/safety/secrets） |\n| `rule_id` | `str` | 规则标识符 |\n| `file` | `str` | 发现的文件路径 |\n| `line` | `int` | 代码行号 |\n| `severity` | `str` | 严重程度（CRITICAL/HIGH/MEDIUM/LOW/INFO） |\n| `message` | `str` | 发现描述信息 |\n| `code_snippet` | `str` | 相关代码片段 |\n| `metadata` | `dict` | 工具特定的元数据 |\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:90-110]()\n\n### NormalizedFinding（标准发现）\n\n`NormalizedFinding` 是整个系统的规范发现格式，所有扫描工具的输出最终都会转换为这种格式。\n\n```python\n@dataclass\nclass NormalizedFinding:\n id: str # deterministic: sha256(tool+file+line+rule_id)[:16]\n tool: str # \"bandit\"|\"semgrep\"|\"secrets\"|\"pip-audit\"|\"safety\"\n rule_id: str\n cwe: list[str] # e.g. [\"CWE-89\"]\n owasp: list[str] # e.g. [\"A03:2021\"]\n severity: Severity # CRITICAL | HIGH | MEDIUM | LOW | INFO\n confidence: Confidence # HIGH | MEDIUM | LOW\n file: str\n line_start: int\n line_end: int\n code_snippet: str\n message: str\n fix_available: bool = False\n suppressed: bool = False\n first_seen: datetime = field(default_factory=datetime.utcnow)\n```\n\n**关键设计特点**：\n\n- **确定性 ID**：通过 SHA-256 哈希算法 `sha256(tool + file + line + rule_id)` 生成前 16 位十六进制字符作为唯一标识符，确保相同漏洞在不同扫描中具有相同 ID\n- **安全分类**：标准化提取 CWE 和 OWASP 分类标识符\n- **时间追踪**：记录首次发现时间 `first_seen`\n\n资料来源：[packages/normalizer/models.py:46-70]()\n\n### Severity 枚举\n\n严重程度等级定义：\n\n| 枚举值 | 说明 | 使用场景 |\n|--------|------|----------|\n| `CRITICAL` | 严重 | 硬编码密钥、RCE、认证绕过 |\n| `HIGH` | 高危 | SQL 注入、命令注入、不安全反序列化 |\n| `MEDIUM` | 中危 | XSS、弱加密、路径遍历 |\n| `LOW` | 低危 | 不安全默认值、轻微配置错误 |\n| `INFO` | 信息 | 代码风格问题、信息性备注 |\n\n### Confidence 枚举\n\n置信度等级反映工具的检测确定性（非严重程度）：\n\n| 枚举值 | 说明 |\n|--------|------|\n| `HIGH` | 高置信度，检测结果可靠 |\n| `MEDIUM` | 中置信度，需人工复核 |\n| `LOW` | 低置信度，建议验证 |\n\n## 标准化流程\n\n### 完整处理流水线\n\n```mermaid\nsequenceDiagram\n participant 检测器 as 扫描检测器\n participant 标准化器 as FindingNormalizer\n participant 去重器 as DeduplicationFilter\n participant 格式化器 as 输出格式化器\n \n 检测器->>检测器: 执行安全扫描\n 检测器->>标准化器: 产出 RawFinding 列表\n 标准化器->>标准化器: 验证必填字段\n 标准化器->>标准化器: 映射严重程度\n 标准化器->>标准化器: 提取 CWE/OWASP\n 标准化器->>标准化器: 生成确定性 ID\n 标准化器->>去重器: 产出 NormalizedFinding\n 去重器->>去重器: 计算哈希指纹\n 去重器->>去重器: 过滤重复发现\n 去重器->>格式化器: 返回去重后列表\n```\n\n### FindingNormalizer 标准化器\n\n`FindingNormalizer` 负责将 `RawFinding` 转换为 `NormalizedFinding`，主要处理逻辑包括：\n\n1. **字段验证**：检查必填字段（tool、rule_id、file）是否存在\n2. **严重程度映射**：将各工具的原始严重程度值映射到规范枚举值\n3. **分类提取**：从元数据中提取 CWE 和 OWASP 分类代码\n4. **ID 生成**：计算确定性哈希作为唯一标识符\n\n```python\n# 严重程度映射示例（Semgrep → 规范值）\n_SEVERITY_MAP = {\n \"ERROR\": \"HIGH\",\n \"WARNING\": \"MEDIUM\",\n \"INFO\": \"INFO\",\n}\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:40-50]()\n\n### CWE 提取逻辑\n\nCWE（Common Weakness Enumeration）分类通过正则表达式从工具元数据中提取：\n\n```python\n_CWE_EXTRACT_RE = re.compile(r\"CWE-\\d+\", re.IGNORECASE)\n\ndef _extract_cwe(raw: Any) -> list[str]:\n \"\"\"从 semgrep 元数据提取规范化 CWE 标识符\"\"\"\n if not raw:\n return []\n items: list[Any] = raw if isinstance(raw, list) else [raw]\n # 正则匹配并去重\n ...\n return result # e.g. [\"CWE-78\", \"CWE-89\"]\n```\n\n**提取规则**：\n- 支持字符串或列表格式的输入\n- 正则表达式匹配：`CWE-\\d+`（不区分大小写）\n- 自动规范化为首字母大写格式（如 `cwe-78` → `CWE-78`）\n- 自动去重，保持插入顺序\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:25-45]()\n\n### OWASP 提取逻辑\n\nOWASP（Open Web Application Security Project）分类的提取方式与 CWE 类似：\n\n```python\n_OWASP_EXTRACT_RE = re.compile(r\"A\\d{2}(?::\\d{4})?\", re.IGNORECASE)\n\ndef _extract_owasp(raw: Any) -> list[str]:\n \"\"\"从 semgrep 元数据提取规范化 OWASP 代码\"\"\"\n # 支持多种格式：[\"A03:2021 - Injection\"] | \"A03:2021\" | []\n ...\n return result # e.g. [\"A03:2021\"]\n```\n\n**支持的格式**：\n- 完整描述：`[\"A03:2021 - Injection\"]`\n- 纯代码格式：`\"A03:2021\"`\n- 空值：`[]` 或 `None`\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:55-80]()\n\n## 去重机制\n\n### DeduplicationFilter\n\n`DeduplicationFilter` 组件负责跨扫描会话的发现去重，基于 `NormalizedFinding.id` 字段进行哈希比对。\n\n```mermaid\ngraph LR\n A[发现 A: ID=abc123] --> B{已见过?}\n C[发现 C: ID=abc123] --> B\n D[发现 B: ID=def456] --> B\n B -->|是| E[跳过]\n B -->|否| F[保留并记录]\n```\n\n**去重策略**：\n\n| 策略 | 说明 |\n|------|------|\n| 基于 ID 去重 | 同一工具、文件、行号、规则的发现视为同一漏洞 |\n| 跨工具去重 | 不同工具检测到同一漏洞时合并 |\n| 时间窗口 | 保留首次发现时间 `first_seen` |\n\n**确定性 ID 算法**：\n\n```\nID = SHA-256(tool + file + line + rule_id)[:16]\n```\n\n这种设计确保：\n- 相同漏洞在不同扫描中产生相同 ID\n- 便于历史数据比对和趋势分析\n- 支持增量扫描和变更检测\n\n资料来源：[packages/normalizer/models.py:50-55]()\n\n## 与扫描管道的集成\n\n### ScanPipeline 集成架构\n\n`ScanPipeline` 是扫描流水线的主协调器，集成数据标准化模块的处理流程：\n\n```python\nfrom normalizer.deduplicator import DeduplicationFilter\nfrom normalizer.normalizer import FindingNormalizer\nfrom normalizer.models import NormalizedFinding, Severity\n\nclass ScanPipeline:\n async def run(self, target: Path, verbose: bool = False) -> list[NormalizedFinding]:\n # 1. 并行运行所有检测器\n raw_findings = await self._run_all_detectors(target)\n \n # 2. 标准化处理\n normalizer = FindingNormalizer()\n normalized = normalizer.normalize(raw_findings)\n \n # 3. 去重过滤\n deduplicator = DeduplicationFilter()\n deduplicated = deduplicator.filter(normalized)\n \n return deduplicated\n```\n\n**并行检测器支持**：\n\n| 检测器 | 工具类型 | 输出格式 |\n|--------|----------|----------|\n| `BanditRunner` | 静态分析 | JSON |\n| `SemgrepRunner` | 静态分析 | JSON |\n| `PipAuditRunner` | 依赖审计 | JSON |\n| `SafetyRunner` | 依赖审计 | JSON |\n| `SecretsDetector` | 密钥扫描 | 自定义 |\n\n资料来源：[packages/scanner/scanner/pipeline.py:1-50]()\n\n### 执行时序\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 命令行\n participant Pipeline as ScanPipeline\n participant Detector as 检测器集合\n participant Normalizer as FindingNormalizer\n participant Deduplicator as DeduplicationFilter\n \n CLI->>Pipeline: scan(path, options)\n Pipeline->>Detector: 并行执行 5 个检测器\n Detector-->>Pipeline: RawFinding[]\n Pipeline->>Normalizer: normalize(raw_findings)\n Normalizer-->>Pipeline: NormalizedFinding[]\n Pipeline->>Deduplicator: filter(findings)\n Deduplicator-->>Pipeline: 去重后列表\n Pipeline-->>CLI: 最终结果\n```\n\n## 输出格式支持\n\n标准化后的 `NormalizedFinding` 支持多种输出格式：\n\n| 格式 | 用途 | 文件 |\n|------|------|------|\n| `terminal` | 交互式彩色输出（默认） | Rich 表格 + 严重程度徽章 |\n| `json` | 机器可读格式 | 管道集成 |\n| `sarif` | GitHub Code Scanning | SARIF 规范 |\n\n### SARIF 格式化\n\nSARIF（Static Analysis Results Interchange Format）格式化器将标准发现转换为符合 OASIS SARIF 规范的输出：\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"将 rule_id 转换为 PascalCase 显示名称\"\"\"\n base = rule_id.split(\"/\")[-1]\n return \"\".join(word.capitalize() for word in base.replace(\"-\", \"_\").split(\"_\"))\n```\n\n**转换示例**：\n- `generic-api-key` → `GenericApiKey`\n- `secrets/aws-access-key-id` → `AwsAccessKeyId`\n\n资料来源：[apps/cli/shield/formatters/sarif.py:40-60]()\n\n## 错误处理与容错\n\n### 字段缺失处理\n\n标准化器对缺失字段采用宽松策略：\n\n| 场景 | 处理方式 | 日志级别 |\n|------|----------|----------|\n| 必填字段缺失 | 跳过该发现 | WARNING |\n| 可选字段缺失 | 使用默认值 | DEBUG |\n| JSON 解析失败 | 返回空列表 | ERROR |\n\n```python\ntry:\n check_id: str = str(entry[\"check_id\"])\n path: str = str(entry[\"path\"])\n start_line: int = int(entry[\"start\"][\"line\"])\nexcept (KeyError, ValueError, TypeError) as exc:\n logger.warning(\"Skipping malformed semgrep result: %s\", exc)\n return None # 不中断整个扫描\n```\n\n### 日志记录\n\n模块使用 Python 标准 `logging` 模块，遵循以下日志级别约定：\n\n| 级别 | 使用场景 |\n|------|----------|\n| DEBUG | 详细流程信息、解析计数 |\n| INFO | 扫描完成摘要、处理统计 |\n| WARNING | 单个发现跳过（不影响整体） |\n| ERROR | 致命错误（如 JSON 解析失败） |\n\n## 配置与扩展\n\n### 严重程度阈值\n\n用户可通过 CLI 参数控制最低显示严重程度：\n\n```bash\nvelonus scan ./ --severity high # 仅显示 HIGH 和 CRITICAL\nvelonus scan ./ --severity medium # 显示 MEDIUM 及以上\n```\n\n### 新增检测器集成\n\n集成新的扫描工具需要：\n\n1. 实现检测器类，返回 `RawFinding` 列表\n2. 在 `ScanPipeline` 中注册检测器\n3. 配置严重程度映射（如需要）\n4. 添加 CWE/OWASP 元数据提取（如适用）\n\n```python\n# packages/scanner/scanner/detectors/custom.py\nfrom .secrets import RawFinding\n\nclass CustomRunner:\n def run(self, target: Path) -> list[RawFinding]:\n # 实现扫描逻辑\n ...\n```\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n normalizer -->|无外部依赖| stdlib\n \n scanner_pipeline --> normalizer\n scanner_pipeline --> detectors\n \n scanners --> scanner_pipeline\n \n cli --> scanners\n cli --> formatters\n \n formatters --> normalizer\n```\n\n**依赖约束**：\n- `normalizer` 包不依赖其他业务包，仅依赖 Python 标准库\n- `scanner` 包依赖 `normalizer` 包\n- `apps/cli` 依赖 `scanner` 和 `normalizer`\n\n## 总结\n\n数据标准化模块是 Velonus 安全扫描系统的基础设施层，承担着格式统一、数据丰富和去重过滤的关键职责。通过 `RawFinding` → `NormalizedFinding` → 去重过滤的处理流程，系统实现了：\n\n- **多工具统一**：不同扫描工具的输出具有一致的内部表示\n- **跨扫描去重**：基于确定性哈希避免重复报告\n- **分类标准化**：CWE/OWASP 分类的自动提取和规范化\n- **格式灵活**：支持多种输出格式适应不同使用场景\n\n该模块的解耦设计确保了系统的可扩展性，便于后续集成新的安全检测工具。\n\n---\n\n\n\n## AI 引擎\n\n### 相关页面\n\n相关主题：[API 服务系统](#page-api), [GitHub 集成](#page-github-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n- [packages/ai-engine/remediation_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/remediation_engine.py)\n- [packages/ai-engine/prompts.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/prompts.py)\n- [packages/ai-engine/cache.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/cache.py)\n- [apps/api/shield_api/services/ai_service.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/api/shield_api/services/ai_service.py)\n\n**注意**：上述文件在本次检索的上下文（START_OF_CONTEXT 至 END_OF_CONTEXT）中未找到相关内容。本页说明基于项目文档（README.md、apps/cli/README.md、CONTRIBUTING.md）中的 AI 引擎相关描述以及项目路线图生成。如需获取完整的 AI 引擎实现细节，请确保在检索上下文中包含 `packages/ai-engine/` 目录下的所有源码文件。\n\n \n\n# AI 引擎\n\n## 概述\n\nAI 引擎（AI Engine）是 Velonus 安全扫描平台的核心智能组件，属于项目的 **Phase 2 — AI Layer** 阶段。根据项目路线图，AI 引擎的主要职责包括：\n\n- **漏洞优先级排序**（AI prioritization）\n- **可利用性评分**（Exploitability scoring）\n- **修复建议生成**（Fix generation）\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\nAI 引擎作为 Phase 2 的核心功能，目前处于 **Building（开发中）** 状态，尚未完成实现。\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## 架构组件\n\n根据源码文件结构，AI 引擎由以下核心模块组成：\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| **Context Engine** | `packages/ai-engine/context_engine.py` | 上下文分析引擎，处理安全发现的上下文信息 |\n| **Remediation Engine** | `packages/ai-engine/remediation_engine.py` | 修复引擎，生成漏洞修复建议 |\n| **Prompts** | `packages/ai-engine/prompts.py` | LLM 提示词管理，定义与 AI 交互的模板 |\n| **Cache** | `packages/ai-engine/cache.py` | 缓存模块，存储 AI 响应以减少 API 调用 |\n| **AI Service** | `apps/api/shield_api/services/ai_service.py` | API 服务层，暴露 AI 引擎能力给前端 |\n\n## 工作流程\n\nAI 引擎的整体工作流程如下：\n\n```mermaid\ngraph TD\n A[安全扫描结果] --> B[Context Engine
上下文分析]\n B --> C{缓存命中?}\n C -->|是| D[返回缓存结果]\n C -->|否| E[Remediation Engine
修复建议生成]\n E --> F[LLM API 调用]\n F --> G[Cache 存储结果]\n G --> D\n D --> H[AI Service API]\n H --> I[前端展示/用户交互]\n \n style A fill:#f9f,stroke:#333,stroke-width:2px\n style I fill:#ccf,stroke:#333,stroke-width:2px\n style F fill:#ffc,stroke:#333,stroke-width:2px\n```\n\n## 核心功能模块\n\n### 1. Context Engine（上下文引擎）\n\n`context_engine.py` 负责处理安全发现的上下文信息。该模块分析扫描结果中的漏洞详情，包括：\n\n- 漏洞类型与严重程度\n- 受影响文件的代码上下文\n- 相关依赖信息\n- 历史修复记录\n\n### 2. Remediation Engine（修复引擎）\n\n`remediation_engine.py` 是 AI 引擎的核心组件，负责生成针对具体漏洞的修复建议。其主要功能包括：\n\n- 分析漏洞根因\n- 生成代码级别的修复方案\n- 提供多种修复策略选项\n- 评估修复方案的安全性与兼容性\n\n### 3. Prompts（提示词管理）\n\n`prompts.py` 集中管理所有与 LLM 交互的提示词模板，包括：\n\n- 漏洞分析提示词\n- 修复建议生成提示词\n- 可利用性评估提示词\n- 优先级排序提示词\n\n### 4. Cache（缓存模块）\n\n`cache.py` 实现响应缓存机制，用于：\n\n- 减少重复的 LLM API 调用\n- 加速相同漏洞的响应时间\n- 降低 API 使用成本\n\n### 5. AI Service（API 服务）\n\n`apps/api/shield_api/services/ai_service.py` 是 AI 引擎对外暴露的 REST API 服务，提供：\n\n- 漏洞分析接口\n- 修复建议获取接口\n- 批量处理接口\n\n## 可利用性评分\n\nAI 引擎通过对漏洞的多个维度进行分析来计算可利用性评分：\n\n| 维度 | 说明 |\n|------|------|\n| **CVSS 基础分数** | 来自漏洞数据库的标准评分 |\n| **代码上下文** | 漏洞代码在实际项目中的使用方式 |\n| **攻击面** | 漏洞是否暴露在外部可访问的范围 |\n| **现有利用条件** | 是否存在已知的利用工具或脚本 |\n| **修复难度** | 应用修复方案的复杂程度 |\n\n资料来源：[apps/cli/README.md - Severity Levels](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## 修复建议生成\n\nAI 引擎生成的修复建议包含以下层次：\n\n### 代码级修复\n\n- 直接的代码修改建议\n- 安全的 API 替换方案\n- 参数化/规范化建议\n\n### 依赖级修复\n\n- 需要升级的包版本\n- 替代库建议\n- 配置修改指导\n\n### 架构级建议\n\n- 安全设计模式推荐\n- 架构重构方向\n- 防御纵深建议\n\n## 与 Phase 1 的关系\n\nAI 引擎建立在 Phase 1 扫描管道的基础之上：\n\n```mermaid\ngraph LR\n A[Phase 1
扫描管道] -->|RawFinding| B[AI Engine
上下文分析]\n B --> C[可利用性评分]\n C --> D[优先级排序]\n D --> E[修复建议生成]\n \n A -->|Bandit| A1[代码安全]\n A -->|Semgrep| A2[代码模式]\n A -->|pip-audit| A3[依赖漏洞]\n A -->|Safety| A4[包安全]\n A -->|Secrets| A5[密钥泄露]\n \n style A fill:#9f9,stroke:#333,stroke-width:2px\n style B fill:#f96,stroke:#333,stroke-width:2px\n```\n\nPhase 1 已实现的扫描工具包括：\n\n| 工具 | 用途 | 状态 |\n|------|------|------|\n| Bandit | Python 代码安全分析 | ✅ 完成 |\n| Semgrep | 多语言代码模式扫描 | ✅ 完成 |\n| pip-audit | pip 依赖漏洞审计 | ✅ 完成 |\n| Safety | Python 包安全扫描 | ✅ 完成 |\n| Secrets | 密钥/凭证检测 | ✅ 完成 |\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Phase 3 与 Phase 4 的集成\n\nAI 引擎的能力将在后续阶段被进一步利用：\n\n### Phase 3 — GitHub PR 集成\n\nAI 引擎生成的修复建议将通过 PR 内联评论直接展示给开发者，实现一键接受修复的功能。\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n### Phase 4 — Web 仪表盘\n\nAI 引擎的分析结果将集成到 Web 仪表盘中，提供：\n\n- 扫描历史趋势\n- 发现趋势分析\n- 团队安全态势概览\n\n## 认证与配置\n\nAI 引擎的功能需要通过 Velonus API 访问，认证方式采用 Clerk 浏览器 OAuth 流程：\n\n```bash\nvelonus auth login # 认证登录\nvelonus auth logout # 清除存储的凭证\nvelonus auth status # 查看当前认证状态\n```\n\n配置管理通过以下命令实现：\n\n```bash\nvelonus config show # 显示当前配置\nvelonus config set api_url https://api.velonus.dev # 设置 API 地址\n```\n\n资料来源：[apps/cli/README.md - velonus auth](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n> ⚠️ **注意**：认证和配置功能目前处于 Phase 0 的存根（stubbed）状态，将在 Phase 2 API 后端上线后完全可用。\n\n## 开发指南\n\n根据 CONTRIBUTING.md 的要求，AI 引擎代码开发需遵循以下规范：\n\n| 要求 | 说明 |\n|------|------|\n| **类型检查** | 必须通过 mypy strict 模式检查 |\n| **代码格式** | 必须通过 ruff format 检查 |\n| **代码检查** | 必须通过 ruff check 检查 |\n| **测试覆盖** | 所有新功能必须有对应的单元测试 |\n| **PR 规范** | 每个 PR 不超过 400 行 diff |\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n## 当前状态\n\n| 项目 | 状态 | 说明 |\n|------|------|------|\n| CLI 基础框架 | ✅ 完成 | Phase 0 |\n| 扫描管道 | ✅ 完成 | Phase 1 |\n| AI 上下文引擎 | 🔨 开发中 | Phase 2 |\n| 可利用性评分 | 🔨 开发中 | Phase 2 |\n| 修复建议生成 | 🔨 开发中 | Phase 2 |\n| GitHub PR 集成 | 🔜 计划中 | Phase 3 |\n| Web 仪表盘 | 🔜 计划中 | Phase 4 |\n\n资料来源：[README.md - Roadmap](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## 相关文档\n\n- [README 主页](../README.md) — 项目概览与快速开始\n- [CLI 使用指南](../apps/cli/README.md) — 命令行工具详细文档\n- [贡献指南](../CONTRIBUTING.md) — 开发者贡献规范\n- [安全策略](../SECURITY.md) — 安全漏洞报告流程\n\n---\n\n\n\n## GitHub 集成\n\n### 相关页面\n\n相关主题：[AI 引擎](#page-ai-engine), [部署与基础设施](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n \n\n# GitHub 集成\n\n## 概述\n\nVelonus 的 GitHub 集成功能旨在将安全扫描能力深度嵌入到 GitHub 的开发工作流中。根据项目路线图，GitHub 集成属于 **Phase 3** 阶段，规划功能包括 PR 内联评论（inline review comments）和一键修复建议（one-click fix suggestions）。资料来源：[README.md:70-73]()\n\n当前版本（Phase 0-1）已实现与 GitHub 的基础集成能力，主要通过以下方式：\n\n- **GitHub Actions 工作流** 集成\n- **SARIF 格式输出** 与 GitHub Security tab 兼容\n- **Pre-commit hook** 支持\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[开发者提交代码] --> B[GitHub Actions 触发]\n B --> C[velonus scan 命令执行]\n C --> D{SARIF 输出}\n D --> E[github/codeql-action/upload-sarif]\n E --> F[GitHub Security tab]\n D --> G{Exit Code}\n G --> H[exit 0: 无高危漏洞]\n G --> I[exit 1: 发现 HIGH/CRITICAL]\n I --> J[PR 合并被阻断]\n \n subgraph \"Phase 3 规划功能\"\n K[PR 内联评论] \n L[一键修复建议]\n K --> M[velonus auth 认证]\n L --> M\n end\n```\n\n## 当前支持的集成方式\n\n### GitHub Actions 工作流集成\n\nVelonus 可作为 GitHub Actions 工作流中的安全扫描步骤运行。通过 `github/codeql-action/upload-sarif@v4` 将扫描结果上传至 GitHub Security tab。\n\n#### 基础工作流配置\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n # exits 1 if HIGH or CRITICAL findings are found — blocks the merge\n```\n\n资料来源：[apps/cli/README.md:89-111]()\n\n#### 带 SARIF 输出的工作流配置\n\n```yaml\n- name: Velonus security scan\n run: velonus scan . --sarif -o velonus-results.sarif\n\n- name: Upload to GitHub Security tab\n uses: github/codeql-action/upload-sarif@v4\n with:\n sarif_file: velonus-results.sarif\n```\n\n资料来源：[README.md:50-60]()\n\n### Pre-commit Hook 集成\n\nVelonus 可配置为 pre-commit hook，在每次提交前自动执行安全扫描。\n\n#### 配置示例\n\n在项目根目录的 `.pre-commit-config.yaml` 中添加：\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n资料来源：[apps/cli/README.md:113-122]()\n\n### Pre-commit Hook 配置参数\n\n| 参数 | 说明 |\n|------|------|\n| `entry` | 执行命令 `velonus scan` |\n| `args` | 扫描参数，`[\"/\", \"--severity\", \"high\"]` 表示扫描当前目录且仅显示 HIGH 及以上级别 |\n| `language` | `system` 表示使用系统环境中的 Python |\n| `pass_filenames` | `false` 表示不传递文件名给扫描器 |\n\n## SARIF 输出格式\n\n### 概述\n\nSARIF（Static Analysis Results Interchange Format）是与 GitHub Code Scanning、VS Code SARIF Viewer 等 SAST 工具兼容的标准输出格式。Velonus 通过 `--sarif` 参数生成 SARIF 文件。\n\n资料来源：[README.md:45-47]()\n\n### SARIF 文件生成命令\n\n| 命令 | 说明 |\n|------|------|\n| `velonus scan ./ --sarif` | 生成默认路径 `results/velonus.sarif` |\n| `velonus scan ./ -o results/velonus.sarif` | 指定自定义输出路径 |\n\n资料来源：[README.md:48-52]()\n\n### SARIF 规则 ID 转换\n\nVelonus 在生成 SARIF 输出时，会将内部规则 ID 转换为 PascalCase 格式的显示名称，便于在 GitHub 界面中阅读。\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"Convert a rule_id to a PascalCase display name for SARIF.\n\n Strips any tool-prefix segment (e.g. ``\"secrets/generic-api-key\"``\n becomes ``\"GenericApiKey\"``).\n \"\"\"\n base = rule_id.split(\"/\")[-1]\n return \"\".join(word.capitalize() for word in base.replace(\"-\", \"_\").split(\"_\"))\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:51-62]()\n\n### 目录 URI 规范\n\nSARIF 规范要求目录 URI 必须以斜杠结尾，Velonus 在生成输出时遵循此规范：\n\n```python\ndef _dir_uri(path: Path) -> str:\n \"\"\"Return a file:// URI for a directory, ensuring a trailing slash.\n\n SARIF spec §3.14.14 requires directory URIs to end with ``/``.\n \"\"\"\n uri = path.as_uri()\n return uri if uri.endswith(\"/\") else uri + \"/\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:28-37]()\n\n## CI/CD 阻断机制\n\n### 退出码机制\n\nVelonus 使用退出码（exit code）作为 CI/CD 管道中的安全门禁：\n\n| 退出码 | 含义 | CI 行为 |\n|--------|------|---------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别漏洞 | 允许合并 |\n| `1` | 扫描完成，发现一个或多个 HIGH/CRITICAL 级别漏洞 | 阻断合并 |\n\n资料来源：[apps/cli/README.md:73-76]()\n\n### 严重级别定义\n\n| 徽章 | 级别 | 颜色 | 典型场景 |\n|------|------|------|---------|\n| 🔴 | `CRITICAL` | 粗体红色 | 硬编码密钥、RCE、认证绕过 |\n| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 | `LOW` | 蓝色 | 不安全默认值、次要配置问题 |\n| ⚪ | `INFO` | 灰色 | 样式问题、信息性备注 |\n\n资料来源：[apps/cli/README.md:61-69]()\n\n### 推荐配置策略\n\n```bash\n# 仅显示 HIGH 和 CRITICAL 级别\nvelonus scan ./ --severity high\n\n# 导出 JSON 格式（高危过滤）\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n## Phase 3 规划功能\n\n根据项目路线图，Phase 3 将实现更深入的 GitHub 集成：\n\n| 功能 | 说明 | 状态 |\n|------|------|------|\n| **PR 内联评论** | 在代码行级别展示漏洞信息 | 🔜 规划中 |\n| **一键修复建议** | 提供自动化修复建议并支持一键接受 | 🔜 规划中 |\n\n### Phase 3 依赖的前置条件\n\nPhase 3 功能需要以下基础设施支持：\n\n1. **认证系统**：`velonus auth` 命令（Phase 2 实现）\n ```bash\n velonus auth login # 通过 Clerk 浏览器 OAuth 流程认证\n velonus auth logout # 清除存储的凭证\n velonus auth status # 显示当前认证状态\n ```\n 资料来源：[apps/cli/README.md:77-92]()\n\n2. **配置文件管理**：`velonus config` 命令（Phase 2 实现）\n ```bash\n velonus config show # 显示当前配置\n velonus config set api_url https://api.velonus.dev # 设置配置值\n ```\n 资料来源：[apps/cli/README.md:93-104]()\n\n## 输出格式对比\n\n| 格式 | 用途 | GitHub 兼容 |\n|------|------|------------|\n| `terminal`（默认） | 交互式终端输出，彩色 Rich 表格 | ❌ |\n| `json` | 管道传输或程序化处理 | ❌ |\n| `sarif` | GitHub Code Scanning 集成 | ✅ |\n\n资料来源：[README.md:40-60]()\n\n## 相关扫描器与 GitHub 集成的漏洞数据\n\nVelonus 的各个扫描器均支持提取与 GitHub 漏洞数据库兼容的元数据：\n\n### Semgrep CWE/OWASP 提取\n\n```python\ndef _extract_cwe(raw: Any) -> list[str]:\n \"\"\"Extract canonical CWE identifiers from semgrep rule metadata.\"\"\"\n # 规范化格式：cwe-78 → CWE-78\n for match in _CWE_EXTRACT_RE.findall(str(item)):\n normalised = match.upper()\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:45-58]()\n\n### Safety CVSS 评分\n\n```python\ndef _cvss_to_severity(score: float | None) -> str:\n \"\"\"Convert CVSS v3 base score to severity level.\"\"\"\n if score is None:\n return \"MEDIUM\"\n if score >= _CVSS_CRITICAL:\n return \"CRITICAL\"\n # ...\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:80-90]()\n\n## 项目阶段概览\n\n| 阶段 | 状态 | 交付内容 |\n|------|------|---------|\n| Phase 0 — 基础 | ✅ 完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |\n| Phase 1 — 扫描管道 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、Safety |\n| Phase 2 — AI 层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复生成 |\n| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| Phase 4 — Web 仪表盘 | 🔴 未开始 | Web UI、扫描历史、漏洞趋势 |\n\n资料来源：[README.md:65-73]()\n\n## 常见问题\n\n### Q: 如何仅扫描并显示高危漏洞？\n\n```bash\nvelonus scan ./ --severity high\n```\n\n### Q: 如何将扫描结果上传到 GitHub Security tab？\n\n1. 生成 SARIF 文件：`velonus scan ./ --sarif -o velonus.sarif`\n2. 在 workflow 中使用 `github/codeql-action/upload-sarif@v4`\n\n### Q: Velonus 如何在 CI 中实现阻断？\n\n当发现 HIGH 或 CRITICAL 级别漏洞时，Velonus 返回退出码 `1`，GitHub Actions 将该步骤标记为失败，从而阻断 PR 合并。\n\n---\n\n\n\n## 部署与基础设施\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [API 服务系统](#page-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/scanner/scanner/pipeline.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n> **注意**：查询中提到的 `infra/docker/` 目录下的 Docker 相关文件（Dockerfile.api、Dockerfile.worker、docker-compose.yml）以及 `apps/api/pyproject.toml` 未包含在当前上下文检索结果中，以下内容基于可检索的源码文件进行分析。\n\n \n\n# 部署与基础设施\n\n## 概述\n\nVelonus 是一个 Python 编写的安全扫描工具，采用单体仓库（monorepo）结构管理多个包和应用。项目当前处于 Alpha 阶段，CLI 工具已完成并可直接使用，但完整的 API 后端服务仍在开发中。资料来源：[README.md]()\n\n当前项目分为以下主要组件：\n\n| 组件 | 路径 | 用途 | 状态 |\n|------|------|------|------|\n| CLI 应用 | `apps/cli/` | 命令行入口，提供 `velonus scan` 等命令 | ✅ 已完成 |\n| Scanner 包 | `packages/scanner/` | 安全扫描引擎，包含多个检测器 | ✅ 已完成 |\n| Normalizer 包 | `packages/normalizer/` | 发现标准化与去重 | ✅ 已完成 |\n| API 服务 | `apps/api/` | AI 层与认证后端 | 🔨 Phase 2 开发中 |\n| Worker 服务 | - | 异步任务处理 | 规划中 |\n\n## 项目架构\n\nVelonus 采用分层架构设计，CLI 作为前端入口调用 Scanner 包中的各个检测器。\n\n```mermaid\ngraph TD\n A[用户终端] --> B[velonus CLI]\n B --> C[ScanPipeline]\n C --> D1[SecretsDetector]\n C --> D2[BanditRunner]\n C --> D3[SemgrepRunner]\n C --> D4[PipAuditRunner]\n C --> D5[SafetyRunner]\n D1 --> E[FindingNormalizer]\n D2 --> E\n D3 --> E\n D4 --> E\n D5 --> E\n E --> F[DeduplicationFilter]\n F --> G[NormalizedFinding]\n G --> H[Formatter]\n H --> I[终端输出 / JSON / SARIF]\n```\n\n## Scanner 包架构\n\n`packages/scanner/scanner/pipeline.py` 定义了核心扫描管道，所有检测器并行执行：\n\n```python\nfrom .detectors.bandit import BanditRunner\nfrom .detectors.pip_audit import PipAuditRunner\nfrom .detectors.safety import SafetyRunner\nfrom .detectors.secrets import SecretsDetector\nfrom .detectors.semgrep import SemgrepRunner\n```\n\n检测器执行顺序（对应索引 0-4）：\n\n```mermaid\ngraph LR\n subgraph 检测器层\n S[SecretsDetector
索引 0]\n B[BanditRunner
索引 1]\n SG[SemgrepRunner
索引 2]\n PA[PipAuditRunner
索引 3]\n SF[SafetyRunner
索引 4]\n end\n```\n\n### 检测器类型定义\n\n```python\n_ParallelRunner = BanditRunner | SemgrepRunner | PipAuditRunner | SafetyRunner\n```\n\n资料来源：[packages/scanner/scanner/pipeline.py:33]()\n\n## 开发环境部署\n\n### 环境要求\n\n| 依赖 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 最低支持版本 |\n| uv | 最新版 | 包管理工具 |\n\n资料来源：[CONTRIBUTING.md]()\n\n### 安装步骤\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/AliAmmar15/Velonus\ncd Velonus\n\n# 2. 安装所有工作区包和开发依赖\nuv sync --all-extras --dev\n\n# 3. 激活虚拟环境\nsource .venv/bin/activate # macOS / Linux\n.venv\\Scripts\\Activate.ps1 # Windows PowerShell\n\n# 4. 以可编辑模式安装 CLI 和 Scanner\npip install -e apps/cli\npip install -e packages/scanner\npip install -e packages/normalizer\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 验证安装\n\n```bash\nvelonus --help\nvelonus scan ./apps/cli/shield\n```\n\n## 本地运行\n\n### CLI 扫描命令\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 指定扫描路径\nvelonus scan ./my-project\n\n# 仅显示高危及以上级别\nvelonus scan ./ --severity high\n\n# 详细输出\nvelonus scan ./ --verbose\n\n# JSON 格式输出\nvelonus scan ./ --format json\n\n# SARIF 格式输出（用于 GitHub Security）\nvelonus scan ./ --format sarif\n```\n\n### 输出格式\n\n| 格式 | 用途 | 说明 |\n|------|------|------|\n| `terminal` | 交互式使用 | 带颜色的 Rich 表格，含徽章、路径、行号 |\n| `json` | 管道集成 | 适合传递给其他工具或存储结果 |\n| `sarif` | CI/CD 集成 | 兼容 GitHub Code Scanning，Phase 1 可用 |\n\n资料来源：[apps/cli/README.md]()\n\n### 退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 发现 HIGH 或 CRITICAL 级别问题（用作 CI 门禁） |\n\n资料来源：[apps/cli/README.md]()\n\n## CI/CD 集成\n\n### GitHub Actions 集成\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n```\n\n资料来源：[apps/cli/README.md]()\n\n### Pre-commit Hook\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n## 扫描管道技术细节\n\n### PipAuditRunner\n\n`packages/scanner/scanner/detectors/pip_audit.py` 负责检测依赖漏洞：\n\n- 执行 `pip-audit --format json --progress-spinner off` 子命令\n- 超时设置：120 秒（考虑 PyPI advisory DB 网络延迟）\n- 返回码处理：退出码 2+ 表示真实错误，退出码 1 表示发现漏洞（正常处理）\n\n```python\ncmd: list[str] = [\n \"pip-audit\",\n \"--format\",\n \"json\",\n \"--progress-spinner\",\n \"off\",\n]\nif req_file is not None:\n cmd.extend([\"-r\", str(req_file)])\nelse:\n cmd.append(\"--local\")\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py]()\n\n### SafetyRunner\n\n`packages/scanner/scanner/detectors/safety.py` 支持两种格式：\n\n| Safety 版本 | 输出格式 | 数据结构 |\n|-------------|----------|----------|\n| v2 (>=2.0) | JSON 对象 | `{\"vulnerabilities\": [...]}` |\n| v1 (<2.0) | JSON 列表 | `[vuln_id, pkg, version, ...]` |\n\nCVSS 评分提取逻辑：\n\n```python\ncvss_score: float | None = _extract_cvss_v2(entry.get(\"severity\"))\nseverity: str = _cvss_to_severity(cvss_score)\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py]()\n\n### SemgrepRunner\n\n`packages/scanner/scanner/detectors/semgrep.py` 使用 Semgrep 公共 Python 规则集：\n\n- 配置：`p/python`\n- 命令：`semgrep scan --config p/python --json --quiet --metrics=off `\n- 退出码 1 = 正常发现（JSON 仍有效），退出码 2+ = 错误\n\n```python\nRULESET: str = \"p/python\"\n\ndef _semgrep_available(self) -> bool:\n try:\n subprocess.run(\n [\"semgrep\", \"--version\"],\n capture_output=True,\n check=False,\n timeout=10,\n )\n return True\n except FileNotFoundError:\n return False\n```\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py]()\n\n## 阶段性规划\n\n| 阶段 | 状态 | 内容 |\n|------|------|------|\n| Phase 0 — 基础 | ✅ 已完成 | CLI 骨架、Rich 输出、NormalizedFinding 模型 |\n| Phase 1 — 扫描管道 | ✅ 已完成 | Secret 检测、Bandit、Semgrep、pip-audit、SARIF |\n| Phase 2 — AI 层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复建议生成 |\n| Phase 3 — GitHub 集成 | 🔴 未开始 | PR 内联评论、一键修复建议 |\n| Phase 4 — Web 仪表板 | 🔴 未开始 | Web UI、扫描历史、趋势分析 |\n\n资料来源：[README.md]()\n\n## 本地开发命令\n\n### 运行测试\n\n```bash\n# 运行全部测试（当前 367 个测试，覆盖 6 个文件）\npytest apps/cli/tests/\n\n# 详细输出\npytest apps/cli/tests/ -v\n```\n\n### 代码检查\n\n```bash\n# Ruff 检查和格式化检查\nruff check . && ruff format --check .\n\n# 自动格式化\nruff format .\n\n# 类型检查（严格模式）\nmypy apps/cli/shield --strict --ignore-missing-imports\nmypy packages/normalizer --strict --ignore-missing-imports\nmypy packages/scanner --strict --ignore-missing-imports\n```\n\n> 所有新代码必须通过 mypy 严格模式检查，PR 中引入 `type: ignore` 注释需在代码注释中提供说明。\n\n资料来源：[CONTRIBUTING.md]()\n\n## 未来部署架构（规划中）\n\n当 Phase 2 API 后端上线后，系统架构预计如下：\n\n```mermaid\ngraph TD\n subgraph 前端层\n CLI[velonus CLI]\n Web[Web Dashboard
Phase 4]\n end\n \n subgraph 后端服务\n API[API Server
Phase 2]\n Worker[Async Worker
Phase 3+]\n end\n \n subgraph 数据层\n DB[(Database)]\n Cache[(Cache)]\n end\n \n CLI -->|REST API| API\n Web -->|REST API| API\n API --> DB\n API --> Cache\n Worker --> DB\n Worker --> Cache\n \n subgraph 认证\n Clerk[Clerk OAuth]\n end\n \n API --> Clerk\n```\n\n### 认证命令（Phase 2 规划）\n\n```bash\nvelonus auth login # 通过 Clerk 浏览器 OAuth 流程认证\nvelonus auth logout # 清除存储的凭证\nvelonus auth status # 显示当前认证状态\n```\n\n### 配置管理（Phase 2 规划）\n\n```bash\nvelonus config show # 打印当前配置\nvelonus config set api_url # 设置配置值\n```\n\n> Phase 0/1 中这些命令为存根实现，将在 Phase 2 API 上线后完整实现。\n\n## 项目结构总览\n\n```\nVelonus/\n├── apps/\n│ ├── cli/ # CLI 应用入口\n│ │ ├── shield/ # CLI 核心模块\n│ │ ├── formatters/ # 输出格式化器（terminal/json/sarif）\n│ │ └── tests/ # 测试套件（367 个测试）\n│ └── api/ # API 后端（Phase 2）\n│ └── pyproject.toml # API 依赖配置\n├── packages/\n│ ├── scanner/ # 扫描引擎\n│ │ └── scanner/\n│ │ ├── detectors/ # 检测器实现\n│ │ │ ├── bandit.py\n│ │ │ ├── semgrep.py\n│ │ │ ├── pip_audit.py\n│ │ │ ├── safety.py\n│ │ │ └── secrets.py\n│ │ └── pipeline.py # 扫描管道编排\n│ └── normalizer/ # 发现标准化与去重\n├── infra/\n│ └── docker/ # Docker 部署配置（待实现）\n│ ├── Dockerfile.api\n│ ├── Dockerfile.worker\n│ └── docker-compose.yml\n└── pyproject.toml # 根工作区配置\n```\n\n## 依赖管理\n\n项目使用 `uv` 作为包管理工具，所有包的依赖定义在各自目录的 `pyproject.toml` 中：\n\n- 根目录 `pyproject.toml`：定义 uv 工作区\n- `apps/cli/pyproject.toml`：CLI 应用依赖\n- `packages/scanner/pyproject.toml`：扫描器依赖（包含 bandit、semgrep 等）\n- `packages/normalizer/pyproject.toml`：标准化器依赖\n\n安装所有 extras 和 dev 依赖：\n\n```bash\nuv sync --all-extras --dev\n```\n\n## 安全门禁配置\n\nVelonus 设计为可作为安全 CI 门禁使用：\n\n```bash\n# 硬性门禁：发现 HIGH 或 CRITICAL 时退出码为 1\nvelonus scan ./ --severity high\n```\n\n建议在 CI 中配置：\n\n1. 使用 `--severity high` 过滤，仅阻断高危及以上问题\n2. 定期使用 `--severity info` 全量扫描\n3. 导出 SARIF 格式上传至 GitHub Security 标签页\n\n---\n\n> 本页基于 Velonus 项目当前阶段的源码文件编写。API 和 Worker 的 Docker 容器化部署配置将在 Phase 2/3 实现后补充。\n\n---\n\n\n\n## 使用指南与最佳实践\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI 命令行工具](#page-cli), [安全扫描器管道](#page-scanner)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n \n\n# 使用指南与最佳实践\n\nVelonus 是一款针对 Python 项目开发的自动化安全扫描工具，专注于代码中的敏感信息检测、依赖漏洞发现以及静态代码分析。本页面将详细介绍 Velonus 的安装配置、基本使用、输出格式、CI/CD 集成以及开发最佳实践，帮助用户和贡献者高效地使用该工具。\n\n---\n\n## 1. 快速入门\n\n### 1.1 安装方式\n\nVelonus 支持多种安装方式，用户可根据实际需求选择合适的方案。\n\n```bash\n# 从源码安装 CLI（开发模式）\npip install -e apps/cli\n\n# 验证安装\nvelonus --version\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 1.2 首次扫描\n\n安装完成后，即可对本地项目执行安全扫描。以下是最基础的扫描命令：\n\n```bash\n# 扫描当前目录\nvelonus scan ./\n\n# 扫描指定项目路径\nvelonus scan ./my-python-project\n```\n\nVelonus 默认会递归扫描目标路径下的所有 Python 源文件，并调用多个安全检测工具协同工作。\n\n资料来源：[README.md:1]()\n\n---\n\n## 2. 核心命令详解\n\n### 2.1 `velonus scan` 命令\n\n`scan` 命令是 Velonus 的核心功能，用于执行完整的安全扫描流水线。\n\n```\nvelonus scan [PATH] [OPTIONS]\n```\n\n#### 参数与选项说明\n\n| 参数/选项 | 默认值 | 说明 |\n|---|---|---|\n| `PATH` | `.` | 要扫描的项目或文件路径 |\n| `--format`, `-f` | `terminal` | 输出格式：`terminal`、`json`、`sarif` |\n| `--severity`, `-s` | `info` | 最低显示严重级别：`critical`、`high`、`medium`、`low`、`info` |\n| `--verbose`, `-v` | off | 显示解析后的目标路径及额外详情 |\n| `--help` | - | 显示帮助信息并退出 |\n\n资料来源：[apps/cli/README.md:1]()\n\n#### 常用扫描示例\n\n```bash\n# 显示所有级别（默认行为）\nvelonus scan ./\n\n# 仅显示高危和严重问题\nvelonus scan ./ --severity high\n\n# 显示详细输出\nvelonus scan ./ --verbose\n\n# 导出 JSON 格式\nvelonus scan ./ --format json\n\n# 高危以上问题导出 JSON 到文件\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 2.2 `velonus auth` 命令（Phase 2）\n\n身份认证命令用于与 Velonus API 进行交互，目前在 Phase 0 阶段为存根实现，将在 Phase 2 阶段完整实现。\n\n```\nvelonus auth [COMMAND]\n```\n\n| 子命令 | 说明 |\n|---|---|\n| `velonus auth login` | 通过 Clerk 浏览器 OAuth 流程认证 |\n| `velonus auth logout` | 清除存储的凭据 |\n| `velonus auth status` | 显示当前认证状态 |\n\n资料来源：[apps/cli/README.md:1]()\n\n### 2.3 `velonus config` 命令（Phase 2）\n\n本地配置管理命令用于设置和查看 CLI 配置参数，同样在 Phase 2 阶段完整实现。\n\n```\nvelonus config [COMMAND]\n```\n\n| 子命令 | 说明 |\n|---|---|\n| `show` | 打印当前配置 |\n| `set ` | 设置配置值 |\n\n资料来源：[apps/cli/README.md:1]()\n\n---\n\n## 3. 输出格式详解\n\nVelonus 支持三种输出格式，适用于不同场景的需求。\n\n### 3.1 Terminal 格式（默认）\n\n终端格式使用 Rich 库渲染带有颜色和严重级别徽章的表格，包含文件路径、行号、规则 ID 和消息描述，是交互式使用场景的最佳选择。\n\n```\n┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 3.2 JSON 格式\n\n适用于管道传输或结果存储的纯 JSON 格式：\n\n```bash\n# 格式化输出\nvelonus scan ./ --format json | python -m json.tool\n\n# 写入文件\nvelonus scan ./ --format json > scan-results.json\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 3.3 SARIF 格式\n\nSARIF（Static Analysis Results Interchange Format）是一种标准化的静态分析结果交换格式，兼容 GitHub Code Scanning、VS Code SARIF Viewer 等主流 SAST 工具。该格式将在 Phase 1 阶段完整支持。\n\n```bash\n# 输出 SARIF 到默认路径\nvelonus scan ./ --sarif\n\n# 输出到自定义路径\nvelonus scan ./ -o results/velonus.sarif\n```\n\n资料来源：[README.md:1]()\n\n---\n\n## 4. 严重级别体系\n\nVelonus 定义了五个严重级别，帮助用户快速识别和优先处理安全问题。\n\n| 徽章 | 级别 | 颜色 | 适用场景 |\n|---|---|---|---|\n| 🔴 | `CRITICAL` | 粗体红色 | 硬编码凭据、RCE、认证绕过 |\n| 🟠 | `HIGH` | 橙色 | SQL 注入、命令注入、不安全反序列化 |\n| 🟡 | `MEDIUM` | 黄色 | XSS、弱加密、路径遍历 |\n| 🔵 | `LOW` | 蓝色 | 不安全默认值、轻微配置错误 |\n| ⚪ | `INFO` | 灰色 | 代码风格问题、信息性备注 |\n\n资料来源：[apps/cli/README.md:1]()\n\n### 退出码规则\n\n| 退出码 | 含义 |\n|---|---|\n| `0` | 扫描完成，未发现 HIGH 或 CRITICAL 级别问题 |\n| `1` | 扫描完成，发现一个或多个 HIGH 或 CRITICAL 级别问题 |\n\n当检测到 HIGH 或 CRITICAL 问题时返回退出码 1，这是设计上的意图，可用于 CI 环境作为合并门禁。\n\n资料来源：[apps/cli/README.md:1]()\n\n---\n\n## 5. 扫描流水线架构\n\nVelonus 的扫描功能由多个检测器协同工作完成，形成完整的静态分析流水线。\n\n```mermaid\ngraph TD\n A[velonus scan] --> B[目标路径解析]\n B --> C[Secret 检测 TruffleHog]\n B --> D[Bandit 静态分析]\n B --> E[Semgrep 代码模式扫描]\n B --> F[pip-audit 依赖审计]\n B --> G[Safety 依赖检查]\n \n C --> H[NormalizedFinding 聚合]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[格式化输出]\n I --> J[Terminal]\n I --> K[JSON]\n I --> L[SARIF]\n```\n\n### 5.1 Secret 检测（secrets.py）\n\nSecret 检测器负责发现代码中硬编码的敏感凭据，包括：\n\n- **TruffleHog 检测器**：使用正则模式匹配已知类型的密钥（如 AWS 访问密钥、API 令牌等）\n- **熵值检测器**：当 TruffleHog 无法识别时，使用香农熵算法检测高熵字符串，识别潜在凭据\n\n```python\nif entropy >= _ENTROPY_THRESHOLD:\n findings.append(\n RawFinding(\n tool=\"secrets\",\n rule_id=\"high-entropy-secret\",\n severity=\"CRITICAL\",\n message=f\"High-entropy string in secret assignment (Shannon entropy={entropy:.2f})\"\n )\n )\n```\n\n资料来源：[packages/scanner/detectors/secrets.py:1]()\n\n### 5.2 Semgrep 静态分析\n\nSemgrep 检测器运行 Semgrep 规则集 `p/python`，执行代码模式匹配和自定义规则扫描。\n\n```python\ndef scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Run semgrep on target and return findings as RawFinding instances.\"\"\"\n if not self._semgrep_available():\n logger.warning(\"semgrep not found on PATH\")\n return []\n return self._run_semgrep(target)\n```\n\nSemgrep 以 JSON 格式输出结果，Velonus 提取关键字段并映射到标准化格式：\n\n- CWE（Common Weakness Enumeration）标识符\n- OWASP 分类代码\n- 规则级别和置信度\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:1]()\n\n### 5.3 pip-audit 依赖审计\n\npip-audit 检测器扫描 Python 项目的依赖包，识别已知漏洞。\n\n```python\ncvss_score: float | None = _extract_cvss_score(cvss_list)\nseverity: str = _cvss_to_severity(cvss_score)\n```\n\n输出包含：\n\n- CVE 或漏洞 ID\n- 受影响包名及版本\n- 修复版本建议\n- CVSS v3 评分\n\n```python\nmessage = (\n f\"[{display_id}] {package_name}=={package_version} has a known vulnerability.{fix_hint}\"\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1]()\n\n### 5.4 Safety 依赖检查\n\nSafety 检测器提供额外的依赖漏洞检测能力，支持两种输出格式：\n\n- **v2 格式**：字典结构，包含 `vulnerabilities` 列表\n- **v1 格式**：列表结构，每个元素为 5 元组\n\n```python\n# Format A: safety >= 2.0\nif isinstance(data, dict):\n vulns = data.get(\"vulnerabilities\", [])\n findings = [_parse_entry_v2(entry, ...) for entry in vulns]\n\n# Format B: safety < 2.0\nif isinstance(data, list):\n findings = [_parse_entry_v1(entry, ...) for entry in data]\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:1]()\n\n---\n\n## 6. CI/CD 集成指南\n\n### 6.1 GitHub Actions 集成\n\n在项目中添加 `.github/workflows/security.yml` 以自动执行安全扫描：\n\n```yaml\nname: Velonus Security Scan\n\non: [push, pull_request]\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n\n - name: Install velonus-cli\n run: pip install -e apps/cli\n\n - name: Run security scan\n run: velonus scan ./ --severity high\n # exits 1 if HIGH or CRITICAL findings are found\n```\n\n资料来源：[apps/cli/README.md:1]()\n\n### 6.2 SARIF 上传到 GitHub Security\n\n将扫描结果上传到 GitHub Security tab：\n\n```yaml\n- name: Velonus security scan\n run: |\n pip install velonus\n velonus scan . --sarif -o velonus.sarif\n\n- name: Upload to GitHub Security tab\n uses: github/codeql-action/upload-sarif@v4\n with:\n sarif_file: velonus.sarif\n```\n\n资料来源：[README.md:1]()\n\n### 6.3 Pre-commit 钩子配置\n\n在 `.pre-commit-config.yaml` 中配置本地钩子：\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: velonus-scan\n name: Velonus Security Scan\n entry: velonus scan\n args: [\"./\", \"--severity\", \"high\"]\n language: system\n pass_filenames: false\n```\n\n资料来源：[README.md:1]()\n\n---\n\n## 7. 开发贡献指南\n\n### 7.1 开发环境配置\n\n克隆仓库后，安装开发依赖：\n\n```bash\ngit clone https://github.com/AliAmmar15/Velonus\ncd Velonus\npip install -e apps/cli\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 7.2 代码格式化\n\n项目使用 `ruff` 进行代码格式化和检查：\n\n```bash\n# 检查格式问题\nruff format --check .\n\n# 自动格式化所有文件\nruff format .\n```\n\n建议在提交前同时运行检查和格式化：\n\n```bash\nruff check . && ruff format .\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 7.3 类型检查\n\n项目使用 mypy 严格模式进行类型检查：\n\n```bash\nmypy apps/cli/shield --strict --ignore-missing-imports\nmypy packages/normalizer --strict --ignore-missing-imports\nmypy packages/scanner --strict --ignore-missing-imports\n```\n\n所有新代码必须通过 mypy 严格检查，PR 中引入 `type: ignore` 注释时需要在代码注释中提供说明。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 7.4 PR 提交规范\n\n#### 提交信息格式\n\n```\n: <简短祈使句描述>\n\nTypes: feat | fix | refactor | test | docs | infra | chore\n```\n\n#### 示例\n\n```\nfeat: add semgrep CWE extraction from rule metadata\nfix: handle bandit exit code 2 on bad target path\ntest: cover pip-audit CVSS v3 threshold edge cases\ndocs: add CONTRIBUTING.md and issue templates\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n#### PR 审核准则\n\n| 准则 | 说明 |\n|---|---|\n| **单一职责** | 每个 PR 只做一个功能或修复 |\n| **测试要求** | 所有新功能必须有对应的单元测试 |\n| **代码规范** | 必须通过 ruff 和 mypy 检查 |\n| **目标分支** | 所有 PR 合并到 `main` 分支 |\n| **规模控制** | 建议 PR 少于 400 行 diff |\n| **代码质量** | 不接受 AI 生成的占位符代码 |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n## 8. 项目路线图\n\n| 阶段 | 状态 | 内容 |\n|---|---|---|\n| **Phase 0** — 基础框架 | ✅ 完成 | CLI 框架、Rich 输出、NormalizedFinding 模型 |\n| **Phase 1** — 扫描流水线 | ✅ 完成 | 真实密钥检测、Bandit、Semgrep、pip-audit、Safety、SARIF |\n| **Phase 2** — AI 增强层 | 🔨 开发中 | AI 优先级排序、可利用性评分、修复建议生成 |\n| **Phase 3** — GitHub 集成 | 🔴 未开始 | PR 行内评论、一键修复建议 |\n| **Phase 4** — Web 控制台 | 🔴 未开始 | Web UI、扫描历史、问题趋势分析 |\n\n资料来源：[README.md:1]()\n\n---\n\n## 9. 最佳实践总结\n\n### 9.1 扫描策略建议\n\n| 场景 | 推荐配置 |\n|---|---|\n| 交互式开发 | `velonus scan ./ --severity info`（显示所有问题） |\n| CI/CD 门禁 | `velonus scan ./ --severity high`（仅阻断高危） |\n| 报告生成 | `velonus scan ./ --format json --severity high > findings.json` |\n| 详细调试 | `velonus scan ./ --verbose` |\n\n### 9.2 性能优化\n\n- 定期运行扫描，避免累积大量问题\n- 使用 `--severity` 参数过滤低优先级问题以减少噪音\n- 在 CI 中仅扫描变更文件路径（需配合 pre-commit 钩子）\n\n### 9.3 安全配置\n\n- 敏感项目建议集成 pre-commit 钩子，在提交前强制扫描\n- 使用 GitHub Actions 自动扫描主分支和 PR\n- 定期更新本地依赖以获取最新的漏洞数据库\n\n---\n\n## 10. 常见问题\n\n**Q: 为什么扫描结果中没有 Semgrep 输出？**\n\nA: 请确认 Semgrep 已正确安装：`semgrep --version`。Velonus 会自动跳过未安装的工具并输出警告。\n\n**Q: 如何处理误报？**\n\nA: 当前版本建议使用 `--severity` 参数过滤低置信度问题。Phase 2 将提供基于 AI 的可利用性评分来辅助判断。\n\n**Q: SARIF 格式有什么用途？**\n\nA: SARIF 是静态分析结果的标准格式，可导入 GitHub Security tab、VS Code SARIF Viewer 等工具，实现可视化展示和趋势追踪。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：aliammar15/velonus\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)。\n\n## 1. 安装坑 · 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_62cdd9b76ac447b8b11064afda81fb9a | https://github.com/AliAmmar15/Velonus/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a9b7a6193ee4ea289f4dc4a12f6a0c1 | https://github.com/AliAmmar15/Velonus/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：aliammar15/velonus\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)。\n\n## 1. 安装坑 · 来源证据：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_62cdd9b76ac447b8b11064afda81fb9a | https://github.com/AliAmmar15/Velonus/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] Same vulnerability reported twice when detected by both Bandit and Semgrep\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a9b7a6193ee4ea289f4dc4a12f6a0c1 | https://github.com/AliAmmar15/Velonus/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# velonus - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 velonus 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: [](https://github.com/AliAmmar15/Velonus/actions) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-cli：CLI 命令行工具。围绕“CLI 命令行工具”模拟一次用户任务，不展示安装或运行结果。\n4. page-api：API 服务系统。围绕“API 服务系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-scanner：安全扫描器管道。围绕“安全扫描器管道”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-cli\n输入：用户提供的“CLI 命令行工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-api\n输入：用户提供的“API 服务系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-scanner\n输入：用户提供的“安全扫描器管道”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-cli：Step 3 必须围绕“CLI 命令行工具”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-api：Step 4 必须围绕“API 服务系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-scanner：Step 5 必须围绕“安全扫描器管道”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://news.ycombinator.com/item?id=48143235\n- https://github.com/AliAmmar15/Velonus#readme\n- README.md\n- pyproject.toml\n- CONTRIBUTING.md\n- apps/cli/shield/main.py\n- apps/api/shield_api/main.py\n- packages/scanner/scanner/pipeline.py\n- infra/docker/docker-compose.yml\n- apps/cli/shield/commands/scan.py\n- apps/cli/shield/commands/auth.py\n- apps/cli/shield/commands/pr.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 velonus 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：aliammar15/velonus\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install velonus\n```\n\n来源：https://github.com/AliAmmar15/Velonus#readme\n\n## 来源\n\n- hn: https://news.ycombinator.com/item?id=48143235\n- docs: https://github.com/AliAmmar15/Velonus#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_910361ca834d4aa6b030e19a6074b3fc"
}