{ "canonical_name": "aliammar15/velonus", "compilation_id": "pack_e7d443ca21964a97872905dd0bc903ca", "created_at": "2026-05-15T09:51:12.165710+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": "[![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](https://github.com/AliAmmar15/Velonus/actions)", "one_liner_zh": "[![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](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": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-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": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "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": "[![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](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": "[![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](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- 安装前能力预览: [![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](https://github.com/AliAmmar15/Velonus/actions) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Introduction to Velonus。围绕“Introduction to Velonus”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：Quick Start Guide。围绕“Quick Start Guide”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：System Architecture。围绕“System Architecture”模拟一次用户任务，不展示安装或运行结果。\n4. cli-components：CLI Components。围绕“CLI Components”模拟一次用户任务，不展示安装或运行结果。\n5. api-backend：API Backend。围绕“API Backend”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction to Velonus”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“Quick Start Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“System Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. cli-components\n输入：用户提供的“CLI Components”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. api-backend\n输入：用户提供的“API Backend”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction to Velonus”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“Quick Start Guide”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“System Architecture”形成一个小中间产物，并等待用户确认。\n- Step 4 / cli-components：Step 4 必须围绕“CLI Components”形成一个小中间产物，并等待用户确认。\n- Step 5 / api-backend：Step 5 必须围绕“API Backend”形成一个小中间产物，并等待用户确认。\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- apps/cli/shield/main.py\n- apps/cli/shield/commands/scan.py\n- apps/cli/pyproject.toml\n- apps/api/pyproject.toml\n- packages/scanner/pyproject.toml\n- apps/cli/shield/commands/auth.py\n- apps/cli/shield/commands/config.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": "[![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](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 09:28:06 UTC\n\n## 目录\n\n- [Introduction to Velonus](#introduction)\n- [Quick Start Guide](#quick-start)\n- [System Architecture](#architecture-overview)\n- [CLI Components](#cli-components)\n- [API Backend](#api-backend)\n- [Scanner Pipeline](#scanner-pipeline)\n- [Security Detectors](#security-detectors)\n- [Output Formats](#output-formats)\n- [AI Engine](#ai-engine)\n- [GitHub PR Reviewer](#github-pr-reviewer)\n\n\n\n## Introduction to Velonus\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quick-start), [System Architecture](#architecture-overview), [Scanner Pipeline](#scanner-pipeline)\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/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.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/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/normalizer/deduplicator.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/deduplicator.py)\n- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n
\n\n# Introduction to Velonus\n\nVelonus is an open-source security scanner CLI designed to detect secrets, vulnerabilities, and security issues in codebases. It aggregates multiple industry-standard security tools into a unified pipeline with normalized output formats and deduplication logic. Velonus is particularly useful for development teams seeking to integrate security scanning into their CI/CD pipelines and local development workflows.\n\n## Overview\n\nVelonus provides a command-line interface that orchestrates multiple security scanners to analyze source code and dependencies. The tool normalizes findings from different sources into a canonical data model, removes duplicates, and presents results in multiple output formats including terminal, JSON, and SARIF. 资料来源：[README.md]()\n\nThe project is structured as a monorepo with three main packages:\n\n| Package | Location | Purpose |\n|---------|----------|---------|\n| `scanner` | `packages/scanner/` | Security tool wrappers and detectors |\n| `normalizer` | `packages/normalizer/` | Data normalization and deduplication |\n| `cli` (shield) | `apps/cli/shield/` | CLI interface and output formatters |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Architecture\n\n### High-Level Component Architecture\n\n```mermaid\ngraph TD\n User --> CLI[CLI Interface
apps/cli/shield/]\n CLI --> Scanner[Scanner Package
packages/scanner/]\n Scanner --> Secrets[Secrets Detector
trufflehog + entropy]\n Scanner --> Bandit[Bandit Detector
Python security linter]\n Scanner --> Semgrep[Semgrep Detector
Static analysis]\n Scanner --> PipAudit[pip-audit Detector
Dependency vulnerabilities]\n Scanner --> Safety[Safety Detector
Python package safety]\n \n Scanner --> Normalizer[Normalizer Package
packages/normalizer/]\n Normalizer --> Models[NormalizedFinding Model]\n Models --> Deduplicator[Deduplication Filter]\n \n Deduplicator --> Formatters[Output Formatters]\n Formatters --> Terminal[Terminal Formatter
Rich tables]\n Formatters --> JSON[JSON Formatter]\n Formatters --> SARIF[SARIF Formatter
GitHub Code Scanning]\n```\n\n### Scanner Pipeline Flow\n\n```mermaid\ngraph LR\n A[Input Path] --> B[Secrets Scan]\n B --> C[Bandit Scan]\n C --> D[Semgrep Scan]\n D --> E[pip-audit Scan]\n E --> F[Safety Scan]\n F --> G[Normalize]\n G --> H[Deduplicate]\n H --> I[Format Output]\n```\n\n资料来源：[packages/normalizer/deduplicator.py:1-30]()\n\n## Supported Security Tools\n\nVelonus wraps and orchestrates the following security scanners:\n\n### Scanner Comparison Table\n\n| Tool | Purpose | Phase | Status |\n|------|---------|-------|--------|\n| **Secrets** | Hardcoded credential detection via TruffleHog + entropy analysis | Phase 0 | ✅ Complete |\n| **Bandit** | Python-specific security issue detection | Phase 1 | ✅ Complete |\n| **Semgrep** | Multi-language static analysis with custom rules | Phase 1 | ✅ Complete |\n| **pip-audit** | Python dependency vulnerability scanning | Phase 1 | ✅ Complete |\n| **Safety** | Python package security database scanning | Phase 1 | ✅ Complete |\n\n资料来源：[README.md]()\n资料来源：[packages/scanner/scanner/detectors/secrets.py:1-50]()\n\n## Data Models\n\n### NormalizedFinding Schema\n\nThe core data model used throughout Velonus is `NormalizedFinding`, which provides a canonical representation of security findings regardless of their source tool. 资料来源：[packages/normalizer/models.py:1-50]()\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `str` | SHA-256 fingerprint (first 16 hex chars) of `tool+file+line+rule_id` |\n| `tool` | `str` | Source tool: `bandit`, `semgrep`, `secrets`, `pip-audit`, `safety` |\n| `rule_id` | `str` | Tool-specific rule identifier |\n| `cwe` | `list[str]` | CWE identifiers (e.g., `[\"CWE-89\"]`) |\n| `owasp` | `list[str]` | OWASP categories (e.g., `[\"A03:2021\"]`) |\n| `severity` | `Severity` | CRITICAL, HIGH, MEDIUM, LOW, INFO |\n| `confidence` | `Confidence` | HIGH, MEDIUM, LOW |\n| `file` | `str` | File path of the finding |\n| `line_start` | `int` | Starting line number |\n| `line_end` | `int` | Ending line number |\n| `code_snippet` | `str` | Relevant code snippet |\n| `message` | `str` | Human-readable finding message |\n| `fix_available` | `bool` | Whether a fix is available |\n| `suppressed` | `bool` | Whether the finding is suppressed |\n| `first_seen` | `datetime` | Timestamp when first detected |\n\n资料来源：[packages/normalizer/models.py:50-75]()\n\n### Severity Levels\n\n| Badge | Level | Color | Typical Issues |\n|-------|-------|-------|----------------|\n| 🔴 | CRITICAL | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | HIGH | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | MEDIUM | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | LOW | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | INFO | Grey | Style issues, informational notes |\n\n资料来源：[apps/cli/README.md]()\n\n## Core Components\n\n### Scanner Package\n\nThe scanner package (`packages/scanner/`) contains wrappers for each security tool. Each detector implements a common interface and produces `RawFinding` objects that are later normalized.\n\n#### Secrets Detector\n\nThe secrets detector performs two types of secret scanning:\n\n1. **TruffleHog Integration**: Scans for verified and potential secrets using known detector patterns\n2. **Entropy-based Fallback**: Uses Shannon entropy thresholding to detect high-entropy strings in credential assignments\n\n```python\n# Detection logic in secrets.py\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 detected (Shannon entropy={entropy:.2f})\",\n metadata={\"entropy\": round(entropy, 3)},\n )\n )\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:1-60]()\n\n#### pip-audit and Safety Detectors\n\nBoth dependency vulnerability detectors extract CVSS v3 scores and map them to Velonus severity levels:\n\n```python\n# Severity mapping from CVSS score\nif score >= _CVSS_CRITICAL:\n return \"CRITICAL\"\nif score >= _CVSS_HIGH:\n return \"HIGH\"\nif score >= _CVSS_MEDIUM:\n return \"MEDIUM\"\nreturn \"LOW\"\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1-30]()\n资料来源：[packages/scanner/scanner/detectors/safety.py:1-50]()\n\n### Normalizer Package\n\nThe normalizer package (`packages/normalizer/`) transforms raw findings from various tools into the canonical `NormalizedFinding` format and handles deduplication.\n\n#### Deduplication Strategy\n\nDeduplication uses the deterministic `id` field as the key:\n\n- Findings are processed in pipeline order: `secrets → bandit → semgrep → pip-audit → safety`\n- The **first occurrence** of each `id` is kept (highest-priority tool wins)\n- Subsequent duplicates are discarded at DEBUG level\n\n**Important**: Cross-tool duplicates (e.g., bandit and semgrep flagging the same `eval()` call) are intentionally **not** deduplicated because they have different `id` values (the `id` includes `tool`). This allows the AI layer to analyze each finding independently. 资料来源：[packages/normalizer/deduplicator.py:1-35]()\n\n### CLI Package (Shield)\n\nThe CLI package (`apps/cli/shield/`) provides the user interface, argument parsing, and output formatting.\n\n#### Output Formatters\n\n| Format | Use Case | File |\n|--------|----------|------|\n| `terminal` (default) | Interactive use with colored Rich tables | Rich formatter |\n| `json` | Piping to other tools, storing results | JSON formatter |\n| `sarif` | GitHub Code Scanning, VS Code SARIF Viewer | SARIF formatter |\n\nThe SARIF formatter includes helper functions for URI conversion and rule naming:\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"Convert rule_id to PascalCase display name for SARIF.\"\"\"\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:1-40]()\n\n## CLI Usage\n\n### Basic Commands\n\n```bash\n# Scan current directory\nvelonus scan ./\n\n# Scan with severity filter\nvelonus scan ./ --severity high\n\n# Output as JSON\nvelonus scan ./ --format json\n\n# Export SARIF for GitHub Security tab\nvelonus scan ./ --format sarif -o results/velonus.sarif\n\n# Show verbose output\nvelonus scan ./ --verbose\n```\n\n### Command Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `PATH` | `.` | Path to scan |\n| `--format`, `-f` | `terminal` | Output format: `terminal`, `json`, `sarif` |\n| `--severity`, `-s` | `info` | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--verbose`, `-v` | off | Show resolved path and extra detail |\n| `-o` | stdout | Output file path |\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH or CRITICAL findings |\n| `1` | Scan completed, one or more HIGH or CRITICAL findings found |\n\nExit code `1` on HIGH/CRITICAL is intentional and enables CI gate functionality. 资料来源：[apps/cli/README.md]()\n\n## CI/CD Integration\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 - 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资料来源：[README.md]()\n\n### Pre-commit Hook\n\n```yaml\n# .pre-commit-config.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## Development Setup\n\n### Requirements\n\n- Python 3.10+ 资料来源：[CONTRIBUTING.md]()\n- [uv](https://docs.astral.sh/uv/) package manager\n\n### Setup Commands\n\n```bash\n# Clone and enter directory\ngit clone https://github.com/AliAmmar15/Velonus\ncd Velonus\n\n# Install all workspace packages and dev dependencies\nuv sync --all-extras --dev\n\n# Activate virtual environment\nsource .venv/bin/activate\n\n# Install packages in editable mode\npip install -e apps/cli\npip install -e packages/scanner\npip install -e packages/normalizer\n\n# Verify installation\nvelonus --help\n```\n\n### Code Quality Standards\n\nAll code must pass the following checks before PR submission:\n\n| Tool | Purpose | Command |\n|------|---------|---------|\n| **ruff** | Linting and formatting | `ruff check . && ruff format .` |\n| **mypy** | Type checking (strict mode) | `mypy apps/cli/shield --strict --ignore-missing-imports` |\n| **pytest** | Unit tests | `pytest apps/cli/tests/` |\n\n资料来源：[CONTRIBUTING.md]()\n\n### PR Guidelines\n\n1. **One feature or fix per PR** — do not bundle unrelated changes\n2. **Tests are required** — every new scanner wrapper, formatter, or utility needs matching unit tests\n3. **Keep it small** — PRs under 400 lines of diff get reviewed faster\n4. **No AI-generated placeholder code** — every function must be functional and tested\n5. **Target `main`** — all PRs merge into main; no long-lived feature branches\n\n## Roadmap\n\n| Phase | Status | Features |\n|-------|--------|----------|\n| Phase 0 — Foundation | ✅ Complete | CLI skeleton, Rich output, `NormalizedFinding` model |\n| Phase 1 — Scanner Pipeline | ✅ Complete | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| Phase 2 — AI Layer | 🔨 Building | AI prioritization, exploitability scoring, fix generation |\n| Phase 3 — GitHub Integration | 🔜 Planned | PR inline review comments, one-click fix suggestions |\n| Phase 4 — Web Dashboard | 🔜 Planned | Web UI, scan history, finding trends |\n\n资料来源：[README.md]()\n\n## Alpha Status\n\nVelonus is currently in **alpha**. The tool is functional and actively used internally, but users should expect rough edges. The development team encourages feedback through GitHub issues. 资料来源：[README.md]()\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to Velonus](#introduction), [CLI Components](#cli-components)\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/shield/commands/scan.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/scan.py)\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.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/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n
\n\n# Quick Start Guide\n\n## Overview\n\nThe **Quick Start Guide** provides developers and security teams with the essential steps to install, configure, and run Velonus for security scanning of Python projects. Velonus is a multi-tool security scanner that aggregates findings from Bandit, Semgrep, pip-audit, Safety, and TruffleHog into a unified output with severity-based filtering.\n\nThis guide covers:\n- Installation from source\n- Basic scan execution\n- Output format configuration\n- Severity filtering\n- CI/CD integration patterns\n\n资料来源：[README.md:1-10]()\n\n## Prerequisites\n\n### System Requirements\n\n| Requirement | Version/Notes |\n|-------------|---------------|\n| Python | 3.12+ |\n| pip | Latest recommended |\n| OS | Linux, macOS, Windows (PowerShell) |\n\n### Required Tools for Full Functionality\n\n| Tool | Purpose | Install Command |\n|------|---------|-----------------|\n| semgrep | Static analysis for Python security rules | `pip install semgrep` |\n| Bandit | Python security linter | `pip install bandit` |\n| pip-audit | Dependency vulnerability scanner | `pip install pip-audit` |\n| Safety | Additional dependency checking | `pip install safety` |\n| TruffleHog | Secret detection | `pip install trufflehog` |\n\nVelonus gracefully handles missing tools—scanners skip silently if their dependency is not installed, logging a warning message.\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-20]()\n\n## Installation\n\n### From Source\n\nClone the repository and install the CLI package:\n\n```bash\ngit clone https://github.com/AliAmmar15/Velonus.git\ncd Velonus\npip install -e apps/cli\n```\n\n### Verify Installation\n\n```bash\nvelonus --version\n```\n\n资料来源：[apps/cli/README.md:1-30]()\n\n## Basic Usage\n\n### Running Your First Scan\n\nScan the current directory:\n\n```bash\nvelonus scan ./\n```\n\nScan a specific project path:\n\n```bash\nvelonus scan ./my-python-project\n```\n\n### Workflow Overview\n\n```mermaid\ngraph TD\n A[User runs velonus scan] --> B[Resolve target path]\n B --> C[Run secret detection
TruffleHog + entropy scan]\n C --> D[Run Bandit static analysis]\n D --> E[Run Semgrep security rules]\n E --> F[Run pip-audit dependency scan]\n F --> G[Run Safety dependency check]\n G --> H[Normalize all findings]\n H --> I[Filter by severity]\n I --> J[Format output]\n J --> K[Print to terminal
or write to file]\n K --> L[Exit with status code]\n```\n\n资料来源：[apps/cli/shield/commands/scan.py:1-50]()\n\n## Scan Command Options\n\n### Syntax\n\n```\nvelonus scan [PATH] [OPTIONS]\n```\n\n### Options Reference\n\n| Option | Short | Default | Description |\n|--------|-------|---------|-------------|\n| `PATH` | — | `.` | Path to project or file to scan |\n| `--format`, `-f` | — | `terminal` | Output format: `terminal`, `json`, `sarif` |\n| `--severity`, `-s` | — | `info` | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--verbose`, `-v` | — | off | Show resolved target path and extra detail |\n| `--help` | — | — | Show help and exit |\n\n资料来源：[apps/cli/README.md:40-60]()\n\n### Severity Filtering Examples\n\n```bash\n# Show all findings (info and above)\nvelonus scan ./\n\n# Only HIGH and CRITICAL findings\nvelonus scan ./ --severity high\n\n# Only CRITICAL findings\nvelonus scan ./ --severity critical\n```\n\n### Output Format Examples\n\n```bash\n# Default: rich terminal table with colored output\nvelonus scan ./\n\n# JSON output for piping\nvelonus scan ./ --format json\n\n# SARIF output for GitHub Security tab\nvelonus scan ./ --format sarif\n\n# Write SARIF to custom path\nvelonus scan ./ -o results/velonus.sarif\n```\n\n资料来源：[apps/cli/README.md:70-100]()\n\n## Output Formats\n\n### Terminal (Default)\n\nRich table with severity badges, file paths, line numbers, rule IDs, and messages. Optimized for interactive use.\n\n| Badge | Severity | Color | Typical Issues |\n|-------|----------|-------|----------------|\n| 🔴 | CRITICAL | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | HIGH | Orange | SQL injection, command injection |\n| 🟡 | MEDIUM | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | LOW | Blue | Insecure defaults, minor issues |\n| ⚪ | INFO | Grey | Style issues, informational notes |\n\n### JSON\n\nMachine-readable format suitable for piping into other tools:\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n### SARIF\n\nStatic Analysis Results Interchange Format for GitHub Code Scanning and VS Code SARIF Viewer integration:\n\n```bash\nvelonus scan ./ --format sarif\nvelonus scan ./ -o results/scan.sarif\n```\n\n资料来源：[README.md:30-60]()\n\n## Exit Codes\n\n| Code | Meaning | Use Case |\n|------|---------|----------|\n| `0` | Scan completed, no HIGH or CRITICAL findings | CI gate passes |\n| `1` | Scan completed, HIGH or CRITICAL findings found | CI gate blocks merge |\n\nThe exit code behavior is intentional for CI/CD gate integration:\n\n```bash\n# CI will fail if HIGH or CRITICAL findings exist\nvelonus scan ./ --severity high\n```\n\n资料来源：[apps/cli/README.md:100-115]()\n\n## CI/CD Integration\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 found\n```\n\n### Pre-commit Hook\n\nAdd to `.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:60-95]()\n\n## Common Workflows\n\n### Quick Security Audit\n\n```bash\nvelonus scan ./ --severity high\n```\n\n### Comprehensive Scan with Verbose Output\n\n```bash\nvelonus scan ./ --verbose --format json > full-scan.json\n```\n\n### Generate SARIF for GitHub Security Tab\n\n```bash\nvelonus scan ./ --format sarif -o velonus.sarif\n```\n\n### Export Findings as JSON\n\n```bash\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n## Project Status\n\nVelonus follows a phased development approach:\n\n| Phase | Status | Features |\n|-------|--------|----------|\n| Phase 0 | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 | ✅ Done | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| Phase 2 | 🔨 Building | AI context engine (exploitability scoring + fix generation) |\n| Phase 3 | 🔜 Planned | GitHub PR integration (inline fixes, one-click accept) |\n| Phase 4 | 🔜 Planned | Web dashboard |\n\n资料来源：[README.md:100-120]()\n\n## Next Steps\n\n- **Configuration**: Explore `velonus config` for API URL settings (Phase 2)\n- **Authentication**: Set up API authentication with `velonus auth login` (Phase 2)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines\n- **Issues**: Report problems at [github.com/AliAmmar15/Velonus/issues](https://github.com/AliAmmar15/Velonus/issues)\n\nVelonus is in alpha. The core scanning functionality works reliably—use it in CI today with the exit code gate.\n\n资料来源：[README.md:120-130]()\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to Velonus](#introduction), [CLI Components](#cli-components), [API Backend](#api-backend), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/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/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.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/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n
\n\n# System Architecture\n\n## Overview\n\nVelonus is a multi-tool security scanning platform designed to identify vulnerabilities in Python projects through a modular scanner pipeline. The system integrates multiple security tools (TruffleHog, Semgrep, Bandit, pip-audit, Safety) into a unified CLI experience with flexible output formats for both interactive use and CI/CD integration.\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## High-Level Architecture\n\nVelonus follows a layered architecture with clear separation between the CLI interface, scanner core, detectors, and output formatters.\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[velonus CLI]\n Commands[scan / auth / config]\n end\n \n subgraph \"Core Layer\"\n Scanner[Scanner Pipeline]\n Normalizer[Normalizer]\n Formatters[Formatters]\n end\n \n subgraph \"Detector Layer\"\n Secrets[Secrets Detector]\n Semgrep[Semgrep Detector]\n PipAudit[pip-audit Detector]\n Safety[Safety Detector]\n end\n \n subgraph \"External Tools\"\n TH[TruffleHog]\n SG[Semgrep Binary]\n PA[pip-audit]\n SF[safety]\n end\n \n CLI --> Commands\n Commands --> Scanner\n Scanner --> Normalizer\n Scanner --> Detectors\n Detectors --> TH\n Detectors --> SG\n Detectors --> PA\n Detectors --> SF\n Normalizer --> Formatters\n Formatters --> Output[terminal / json / sarif]\n```\n\n## Project Structure\n\nThe repository is organized as a monorepo with separate packages and applications.\n\n| Component | Path | Purpose |\n|-----------|------|---------|\n| CLI Application | `apps/cli/` | Command-line interface entry point |\n| API Application | `apps/api/` | Backend API (Phase 2) |\n| Scanner Package | `packages/scanner/` | Core scanner pipeline and detectors |\n| Normalizer Package | `packages/normalizer/` | Finding normalization |\n\n资料来源：[CONTRIBUTING.md:6-8](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n## Scanner Pipeline\n\n### Pipeline Architecture\n\nThe scanner pipeline orchestrates multiple security tools and aggregates their findings into a unified format.\n\n```mermaid\ngraph LR\n Input[Target Path] --> Resolve[Path Resolution]\n Resolve --> SD[Secrets Detection]\n Resolve --> SEM[Semgrep Scan]\n Resolve --> PA[pip-audit]\n Resolve --> SF[Safety Scan]\n SD --> RF1[RawFinding]\n SEM --> RF2[RawFinding]\n PA --> RF3[RawFinding]\n SF --> RF4[RawFinding]\n RF1 --> Aggregate[Aggregate Findings]\n RF2 --> Aggregate\n RF3 --> Aggregate\n RF4 --> Aggregate\n Aggregate --> Normalize[Normalize to NormalizedFinding]\n Normalize --> Format[Format Output]\n```\n\n### Core Components\n\n#### RawFinding Data Model\n\nAll detectors produce `RawFinding` objects as the initial representation of a security finding:\n\n```python\nRawFinding(\n tool=\"pip-audit\", # Source tool identifier\n rule_id=\"CVE-2023-12345\", # Vulnerability identifier\n file=\"requirements.txt\", # Affected file path\n line=0, # Line number (0 for dep issues)\n severity=\"HIGH\", # CRITICAL/HIGH/MEDIUM/LOW/INFO\n message=\"...\", # Human-readable message\n code_snippet=\"...\", # Relevant code context\n metadata={ # Tool-specific metadata\n \"package_name\": \"requests\",\n \"package_version\": \"2.28.0\",\n \"cvss_score\": 7.5,\n \"fix_available\": True\n }\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:49-61](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n\n#### NormalizedFinding\n\nThe normalizer transforms `RawFinding` objects into a standardized `NormalizedFinding` format for consistent output across all tools.\n\n### Detector Interface\n\nAll detectors implement a common interface:\n\n| Method | Purpose |\n|--------|---------|\n| `scan(target: Path) -> list[RawFinding]` | Execute scan and return findings |\n\n## Security Detectors\n\n### Secrets Detector\n\nThe secrets detector identifies hardcoded credentials and sensitive information using two complementary approaches:\n\n#### TruffleHog Integration\n\nPrimary detection method that leverages TruffleHog's extensive secret detection rules.\n\n```python\nRawFinding(\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=f\"{'Verified' if verified else 'Potential'} secret detected [{detector_name}]\",\n metadata={\n \"detector\": detector_name,\n \"verified\": verified,\n \"decoder\": decoder_name\n }\n)\n```\n\n资料来源：[packages/scanner/detectors/secrets.py:45-57](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.py)\n\n#### Entropy-Based Fallback\n\nWhen TruffleHog is unavailable, a Shannon entropy-based scanner detects high-entropy strings in credential assignments.\n\n| Parameter | Value | Description |\n|-----------|-------|-------------|\n| Entropy Threshold | 4.5 | Minimum Shannon entropy to flag |\n| Skipped Dirs | `.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build` | Directories excluded from scanning |\n\n```python\nRawFinding(\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 metadata={\"entropy\": round(entropy, 3)}\n)\n```\n\n资料来源：[packages/scanner/detectors/secrets.py:78-91](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.py)\n\n### Semgrep Detector\n\nRuns Semgrep with the `p/python` ruleset for Python-specific security analysis.\n\n```mermaid\ngraph TD\n Check[Check semgrep availability] -->|found| Run[Run semgrep scan]\n Check -->|not found| Skip[Return empty list + warning]\n Run --> Parse[Parse JSON output]\n Parse --> Extract[Extract CWE/OWASP metadata]\n Extract --> Create[Create RawFinding objects]\n```\n\n**Configuration:**\n- Ruleset: `p/python`\n- Flags: `--json --quiet --metrics=off`\n- Exit code 1: Findings present (not an error)\n- Exit code 2+: Real error\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:35-55](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n\n**Metadata Extraction:**\n\n| Metadata Field | Extraction Method |\n|---------------|-------------------|\n| CWE | Regex extraction from `extra.metadata.cwe` |\n| OWASP | List deduplication from `extra.metadata.owasp` |\n\n### pip-audit Detector\n\nScans Python dependencies for known vulnerabilities using `pip-audit`.\n\n**Finding Structure:**\n```python\nRawFinding(\n tool=\"pip-audit\",\n rule_id=vuln_id,\n file=attribution_path,\n line=0, # Dependency vulnerabilities are file-level\n severity=severity,\n metadata={\n \"package_name\": package_name,\n \"package_version\": package_version,\n \"aliases\": aliases,\n \"fix_versions\": fix_versions,\n \"cvss_score\": cvss_score,\n \"cwe\": _CWE,\n \"owasp\": _OWASP,\n \"fix_available\": bool(fix_versions)\n }\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:49-61](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n\n**CVSS to Severity Mapping:**\n\n| CVSS Score Range | Severity |\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.0 | INFO |\n\n### Safety Detector\n\nHandles both Safety v1 and v2 output formats for Python vulnerability scanning.\n\n**Supported Formats:**\n\n| Format | Source | Structure |\n|--------|--------|-----------|\n| Format A (v2) | `safety >= 2.0` | Dict with `vulnerabilities` list |\n| Format B (v1) | `safety < 2.0` | List of 5-element lists |\n\n**Vulnerability Entry Parsing:**\n\n```python\n# Required fields for v2\nvuln_id: str = str(entry[\"vulnerability_id\"])\npackage_name: str = str(entry[\"package_name\"])\ninstalled_version: str = str(entry[\"analyzed_version\"])\n\n# Optional fields\nadvisory: str = str(entry.get(\"advisory\", \"\"))\ncve: str = str(entry.get(\"CVE\", \"\"))\nfix_versions: list[str] = [str(v) for v in entry.get(\"fixed_versions\", [])]\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:50-65](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n\n## CLI Architecture\n\n### Command Structure\n\n```\nvelonus [OPTIONS] COMMAND [ARGS]...\n```\n\n| Command | Description | Phase |\n|---------|-------------|-------|\n| `scan` | Run security scanner pipeline | Phase 0 |\n| `auth` | Manage API authentication | Phase 2 |\n| `config` | Manage local configuration | Phase 2 |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n### Scan Command Interface\n\n```bash\nvelonus scan [PATH] [OPTIONS]\n```\n\n| Argument/Option | Default | Description |\n|-----------------|---------|-------------|\n| `PATH` | `.` | Target project path |\n| `--format`, `-f` | `terminal` | Output format |\n| `--severity`, `-s` | `info` | Minimum severity filter |\n| `--verbose`, `-v` | off | Show detailed output |\n\n**Exit Codes:**\n\n| Code | Meaning |\n|------|---------|\n| 0 | Scan completed, no HIGH/CRITICAL findings |\n| 1 | Scan completed, HIGH or CRITICAL findings found |\n\n## Output Formatters\n\n### Terminal Formatter\n\nRich-formatted table with colored severity badges:\n\n```\n┏━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ Rule ┃ Message ┃\n┡━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩\n│ 🔴 CRITICAL │ secrets │ aws-access-key │ Hardcoded │\n│ 🟠 HIGH │ bandit │ B413 │ Blacklist │\n```\n\n### JSON Formatter\n\nStructured JSON output for piping and tooling:\n\n```json\n{\n \"findings\": [\n {\n \"severity\": \"CRITICAL\",\n \"tool\": \"secrets\",\n \"rule_id\": \"trufflehog-aws-access-key\",\n \"file\": \"config.py\",\n \"line\": 42,\n \"message\": \"Verified secret detected [AWS Access Key]\"\n }\n ]\n}\n```\n\n### SARIF Formatter\n\nStatic Analysis Results Interchange Format for GitHub Code Scanning integration.\n\n**Key SARIF Elements:**\n\n| Element | Purpose |\n|---------|---------|\n| `runs[].results[]` | Individual findings |\n| `runs[].tool.driver.rules[]` | Rule definitions |\n| `runs[].artifacts` | Scanned files |\n| `runs[].logicalLocations` | Code structure |\n\n**Rule ID Transformation:**\n```\nsecrets/aws-access-key-id → AwsAccessKeyId\ngeneric-api-key → GenericApiKey\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:40-58](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n\n## Severity Classification\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | CRITICAL | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | HIGH | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | MEDIUM | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | LOW | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | INFO | Grey | Style issues, informational notes |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## Development Standards\n\n### Code Quality Requirements\n\nAll code must pass:\n\n| Tool | Purpose | Command |\n|------|---------|---------|\n| ruff | Linting & formatting | `ruff check . && ruff format --check .` |\n| mypy | Type checking (strict) | `mypy --strict --ignore-missing-imports` |\n\n**Strict Requirements:**\n- Zero mypy errors in strict mode\n- No `type: ignore` without explanation comment\n- All functions must be functional and tested\n- No AI-generated placeholder code\n\n资料来源：[CONTRIBUTING.md:32-44](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n### PR Guidelines\n\n| Rule | Description |\n|------|-------------|\n| One feature per PR | No bundling unrelated changes |\n| Tests required | Every new scanner wrapper needs unit tests |\n| Small diffs | Target under 400 lines for faster review |\n| Target main | No long-lived feature branches |\n\n## Roadmap\n\n| Phase | Status | Deliverables |\n|-------|--------|--------------|\n| Phase 0 | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 | ✅ Done | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| Phase 2 | 🔨 Building | AI prioritization, exploitability scoring, fix generation |\n| Phase 3 | 🔜 Planned | PR inline review comments, one-click fix suggestions |\n| Phase 4 | 🔜 Planned | Web UI, scan history, finding trends |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## CI/CD Integration\n\n### GitHub Actions Workflow\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资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n---\n\n\n\n## CLI Components\n\n### 相关页面\n\n相关主题：[Scanner Pipeline](#scanner-pipeline), [API Backend](#api-backend), [Output Formats](#output-formats)\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/shield/commands/scan.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/scan.py)\n- [apps/cli/shield/commands/auth.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/auth.py)\n- [apps/cli/shield/commands/config.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/config.py)\n- [apps/cli/shield/commands/pr.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/pr.py)\n- [apps/cli/shield/formatters/terminal.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/terminal.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n- [apps/cli/shield/core/api_client.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/api_client.py)\n
\n\n# CLI Components\n\n## Overview\n\nThe Velonus CLI is a Typer-based command-line application that provides a unified interface for running security scans on local codebases. The CLI operates in **local-only mode** without requiring an API connection, making it immediately usable for developers and CI/CD pipelines.\n\nThe CLI is structured around command groups that delegate to specialized modules for scanning, authentication, configuration, and PR integration.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[\"velonus (main.py)\"] --> B[\"scan.app\"]\n A --> C[\"auth.app\"]\n A --> D[\"config.app\"]\n A --> E[\"pr.app\"]\n \n B --> F[\"scanner pipeline\"]\n B --> G[\"formatters\"]\n \n G --> H[\"terminal.py\"]\n G --> I[\"sarif.py\"]\n G --> J[\"json.py\"]\n \n C --> K[\"api_client.py\"]\n D --> L[\"config storage\"]\n \n F --> M[\"NormalizedFinding\"]\n M --> G\n```\n\n## Command Groups\n\n### Root Application\n\nThe root Typer application is defined in `apps/cli/shield/main.py` and registers all command subgroups:\n\n```python\napp = typer.Typer(\n name=\"velonus\",\n help=\"[bold green]Velonus[/bold green] — AI-native AppSec scanner for developers.\",\n rich_markup_mode=\"rich\",\n no_args_is_help=True,\n pretty_exceptions_enable=True,\n pretty_exceptions_show_locals=False,\n)\n```\n\n资料来源：[apps/cli/shield/main.py:17-22]()\n\n| Property | Value | Purpose |\n|----------|-------|---------|\n| `name` | `velonus` | CLI command name |\n| `rich_markup_mode` | `rich` | Enable Rich markup for colored output |\n| `no_args_is_help` | `True` | Show help when no arguments provided |\n| `pretty_exceptions_enable` | `True` | Enhanced error tracebacks |\n\n### Command Registration\n\n| Command | Module | Phase | Description |\n|---------|--------|-------|-------------|\n| `velonus scan` | `shield.commands.scan` | Phase 0 | Run security scans on local paths |\n| `velonus auth` | `shield.commands.auth` | Phase 2 | Authenticate with Velonus API |\n| `velonus config` | `shield.commands.config` | Phase 2 | Manage local CLI configuration |\n| `velonus pr` | `shield.commands.pr` | Phase 3 | GitHub PR integration utilities |\n\n资料来源：[apps/cli/shield/main.py:29-32]()\n\n## The `scan` Command\n\nThe `scan` command is the primary interface for running security analysis on local codebases.\n\n### Command Interface\n\n```bash\nvelonus scan [PATH] [OPTIONS]\n```\n\n| Argument/Option | Default | Type | Description |\n|-----------------|---------|------|-------------|\n| `PATH` | `.` | Path | Project or file to scan |\n| `--format`, `-f` | `terminal` | Choice | Output format: `terminal`, `json`, `sarif` |\n| `--severity`, `-s` | `info` | Choice | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--verbose`, `-v` | `off` | Flag | Show resolved target path and extra detail |\n| `--output`, `-o` | stdout | Path | Write output to file (SARIF/JSON) |\n\n资料来源：[apps/cli/shield/commands/scan.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/scan.py)\n\n### Severity Levels\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | `CRITICAL` | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | `HIGH` | Orange | SQL injection, command injection |\n| 🟡 | `MEDIUM` | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | `LOW` | Blue | Insecure defaults, minor misconfigs |\n| ⚪ | `INFO` | Grey | Style issues, informational notes |\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH/CRITICAL findings |\n| `1` | Scan completed with HIGH or CRITICAL findings (blocks CI) |\n\n## Output Formatters\n\nThe CLI supports multiple output formats through a pluggable formatter system.\n\n```mermaid\ngraph LR\n A[\"NormalizedFinding\"] --> B[\"Formatter Interface\"]\n B --> C[\"TerminalFormatter\"]\n B --> D[\"SarifFormatter\"]\n B --> E[\"JsonFormatter\"]\n```\n\n### Terminal Formatter\n\nRenders findings as colored Rich tables with severity badges, file paths, line numbers, rule IDs, and human-readable messages. This is the default format for interactive use.\n\n**Output Structure:**\n```\n┏━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃\n┡━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩\n```\n\n### SARIF Formatter\n\nGenerates Static Analysis Results Interchange Format output compatible with GitHub Code Scanning, VS Code SARIF Viewer, and other SAST tooling.\n\n**Key transformations:**\n- Converts rule IDs to PascalCase display names via `_rule_id_to_name()`\n- Generates `file://` URIs for directory paths with trailing slashes per SARIF spec §3.14.14\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\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:58-68]()\n\n### JSON Formatter\n\nOutputs findings as structured JSON for piping into other tools or storing results:\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n## Authentication Module\n\nThe `auth` command manages authentication with the Velonus API backend.\n\n| Command | Description | Phase |\n|---------|-------------|-------|\n| `velonus auth login` | Authenticate via Clerk (browser OAuth flow) | Phase 2 |\n| `velonus auth logout` | Clear stored credentials | Phase 2 |\n| `velonus auth status` | Show current authentication status | Phase 2 |\n\n> These commands are stubbed in Phase 0 and become functional in Phase 2 when the API backend is live.\n\n## Configuration Module\n\nThe `config` command manages local CLI settings stored on disk.\n\n| Command | Description |\n|---------|-------------|\n| `velonus config show` | Print current configuration |\n| `velonus config set ` | Set a configuration value |\n\n**Example configuration:**\n```bash\nvelonus config set api_url https://api.velonus.dev\n```\n\n> Stubbed in Phase 0, fully functional in Phase 2.\n\n## PR Integration Module\n\nThe `pr` command provides GitHub PR integration utilities for Phase 3. This module is planned but not yet implemented in Phase 0.\n\n## Core API Client\n\nThe `api_client` module in `shield/core/` handles communication with the Velonus backend API. It is used by the auth and config modules when API connectivity is required.\n\n资料来源：[apps/cli/shield/core/api_client.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/api_client.py)\n\n## Module Structure\n\n```\napps/cli/shield/\n├── main.py # Root Typer application\n├── commands/\n│ ├── __init__.py\n│ ├── scan.py # Security scan command\n│ ├── auth.py # Authentication commands\n│ ├── config.py # Configuration commands\n│ └── pr.py # PR integration (Phase 3)\n├── formatters/\n│ ├── __init__.py\n│ ├── terminal.py # Rich table output\n│ ├── sarif.py # SARIF format output\n│ └── json.py # JSON output\n└── core/\n ├── __init__.py\n └── api_client.py # Backend API communication\n```\n\n## CLI Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as velonus scan\n participant Scanner as scanner.pipeline\n participant Formatter\n participant Output\n\n User->>CLI: velonus scan ./ --severity high\n CLI->>Scanner: Run detectors (secrets, bandit, semgrep, etc.)\n Scanner-->>CLI: List[NormalizedFinding]\n CLI->>Formatter: Format findings based on --format\n Formatter-->>Output: Rendered output (terminal/JSON/SARIF)\n Output-->>User: Display or write to file\n \n alt HIGH/CRITICAL findings\n CLI-->>User: Exit code 1 (CI block)\n else Clean scan\n CLI-->>User: Exit code 0\n end\n```\n\n## Usage Examples\n\n### Basic Scan\n\n```bash\nvelonus scan ./\n```\n\n### Severity Filtered Scan\n\n```bash\nvelonus scan ./ --severity high\n```\n\n### Export to SARIF\n\n```bash\nvelonus scan ./ -o results/velonus.sarif --format sarif\n```\n\n### Verbose Output\n\n```bash\nvelonus scan ./ --verbose\n```\n\n### CI/CD Integration\n\n```yaml\n- name: Velonus security scan\n run: velonus scan . --severity high\n```\n\n## Development Guidelines\n\nPer the project's contribution guidelines:\n\n| Requirement | Tool | Command |\n|-------------|------|---------|\n| Linting | Ruff | `ruff check .` |\n| Formatting | Ruff | `ruff format .` |\n| Type Checking | mypy | `mypy apps/cli/shield --strict --ignore-missing-imports` |\n| Testing | pytest | `pytest apps/cli/tests/` |\n\nAll new CLI components must include matching unit tests. The test suite currently has **367 tests** covering scanner wrappers and formatters.\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## API Backend\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture-overview), [Scanner Pipeline](#scanner-pipeline), [AI Engine](#ai-engine), [GitHub PR Reviewer](#github-pr-reviewer)\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/shield/core/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/__init__.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.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- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\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
\n\n# API Backend\n\n## Overview\n\nThe Velonus API Backend is a FastAPI-based service layer that provides remote scanning capabilities, AI-powered analysis, GitHub integration, and programmatic access to security findings. Currently planned for **Phase 2** of the Velonus roadmap, the API backend will extend the CLI's local-only scanning with cloud-native features including authentication, rate limiting, background processing, and AI-driven remediation suggestions.\n\n**Current Status:** The API backend is in the planning/stub phase. The CLI is fully functional in local-only mode. Auth, config, and GitHub integration commands are stubbed and will be activated once the backend is live. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n Client[\"Client
(CLI / Web UI)\"] --> |\"HTTP/REST\"| API[\"API Gateway
(FastAPI)\"]\n \n API --> |\"Auth\"| AuthMW[\"Auth Middleware
(Clerk OAuth)\"]\n API --> |\"Rate Limit\"| RateMW[\"Rate Limit Middleware\"]\n \n AuthMW --> |\"Validated\"| Routers[\"Routers\"]\n RateMW --> |\"Allowed\"| Routers\n \n Routers --> Scans[\"/scans\"]\n Routers --> Findings[\"/findings\"]\n Routers --> GitHub[\"/github\"]\n Routers --> Remediation[\"/remediation\"]\n \n Scans --> ScanSvc[\"Scan Service\"]\n Findings --> ScanSvc\n GitHub --> GitHubSvc[\"GitHub Service\"]\n Remediation --> AISvc[\"AI Service\"]\n \n ScanSvc --> ScanWorker[\"Scan Worker
(Background)\"]\n AISvc --> AIWorker[\"AI Worker
(Background)\"]\n \n ScanWorker --> |\"Results\"| DB[\"Database\"]\n AIWorker --> |\"Analysis\"| DB\n \n DB --> Findings\n```\n\n## Planned Components\n\n### Directory Structure\n\n```\napps/api/shield_api/\n├── main.py # FastAPI application entry point\n├── middleware/\n│ ├── auth.py # Clerk OAuth authentication\n│ └── rate_limit.py # Request rate limiting\n├── routers/\n│ ├── scans.py # Scan management endpoints\n│ ├── findings.py # Finding retrieval endpoints\n│ ├── github.py # GitHub integration endpoints\n│ └── remediation.py # AI remediation endpoints\n├── services/\n│ ├── scan_service.py # Scan orchestration logic\n│ ├── ai_service.py # AI analysis and scoring\n│ └── github_service.py # GitHub API integration\n└── background/\n ├── scan_worker.py # Background scan processor\n └── ai_worker.py # Background AI worker\n```\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Middleware Layer\n\n### Authentication Middleware\n\nThe authentication middleware integrates with **Clerk** for browser-based OAuth authentication. This enables secure API access for authenticated users while maintaining compatibility with the CLI's local-only mode.\n\n| Feature | Description |\n|---------|-------------|\n| Provider | Clerk (OAuth 2.0) |\n| Token Type | Bearer JWT |\n| Protected Routes | All `/scans`, `/findings`, `/github`, `/remediation` endpoints |\n| CLI Bypass | Local scans work without authentication |\n\nThe `velonus auth` command group will provide login/logout/status operations once the backend is live. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n### Rate Limiting Middleware\n\nRate limiting protects the API from abuse and ensures fair resource allocation across users.\n\n| Tier | Limit | Purpose |\n|------|-------|---------|\n| Anonymous | TBD | Limited scans per hour |\n| Authenticated | TBD | Higher quotas for logged-in users |\n| Enterprise | TBD | Custom limits based on subscription |\n\n## Router Modules\n\n### `/scans` - Scan Management\n\nManages scan lifecycle including creation, status tracking, and result retrieval.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/scans` | POST | Create a new scan job |\n| `/scans/{id}` | GET | Get scan status and metadata |\n| `/scans/{id}/results` | GET | Retrieve scan results |\n| `/scans/{id}/cancel` | POST | Cancel a running scan |\n\n#### Request/Response Model\n\n```json\n{\n \"id\": \"uuid\",\n \"status\": \"pending|running|completed|failed\",\n \"target_path\": \"/path/to/project\",\n \"created_at\": \"ISO8601 timestamp\",\n \"completed_at\": \"ISO8601 timestamp|null\",\n \"tools_run\": [\"secrets\", \"bandit\", \"semgrep\", \"pip-audit\", \"safety\"],\n \"findings_count\": {\n \"critical\": 0,\n \"high\": 0,\n \"medium\": 0,\n \"low\": 0,\n \"info\": 0\n }\n}\n```\n\n### `/findings` - Finding Retrieval\n\nProvides filtered access to security findings from completed scans.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/findings` | GET | List findings with filters |\n| `/findings/{id}` | GET | Get single finding details |\n| `/findings/{id}/acknowledge` | POST | Mark finding as acknowledged |\n\n#### Query Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `scan_id` | UUID | Filter by scan |\n| `severity` | string | `critical`, `high`, `medium`, `low`, `info` |\n| `tool` | string | `secrets`, `bandit`, `semgrep`, `pip-audit`, `safety` |\n| `cwe` | string | Filter by CWE identifier |\n| `owasp` | string | Filter by OWASP category |\n| `page` | int | Pagination page number |\n| `limit` | int | Results per page (max 100) |\n\n### `/github` - GitHub Integration\n\nEnables GitHub Actions integration and PR inline comments for Phase 3.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/github/webhook` | POST | Receive GitHub webhook events |\n| `/github/install` | POST | Install GitHub App |\n| `/github/scan` | POST | Trigger scan from PR |\n| `/github/comments` | POST | Post inline review comments |\n\nThis router integrates with the GitHub Service for repository access and comment posting. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n### `/remediation` - AI-Powered Fixes\n\nProvides AI-generated fix suggestions for security findings.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/remediation/{finding_id}` | GET | Get AI fix suggestion |\n| `/remediation/{finding_id}/apply` | POST | Apply fix to codebase |\n| `/remediation/pr` | POST | Create PR with fixes |\n\nPhase 2 features include AI prioritization and exploitability scoring. Phase 3 adds one-click fix suggestions. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Service Layer\n\n### Scan Service\n\nOrchestrates the security scanning pipeline across multiple tools:\n\n| Tool | Purpose | Finding Type |\n|------|---------|--------------|\n| **Secrets** | TruffleHog-based secret detection | Hardcoded credentials, API keys |\n| **Bandit** | Python static analysis | Security bugs, common vulnerabilities |\n| **Semgrep** | Rule-based pattern matching | Custom security rules, CWE coverage |\n| **pip-audit** | Dependency vulnerability scanning | Known CVEs in Python packages |\n| **Safety** | Python dependency security | Vulnerable package versions |\n\nThe service normalizes findings into the `NormalizedFinding` model before storage. 资料来源：[packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n\n### AI Service\n\nProvides AI-powered analysis capabilities for Phase 2:\n\n| Feature | Description |\n|---------|-------------|\n| Exploitability Scoring | Assess if a vulnerability is actually exploitable in context |\n| Fix Generation | Generate code patches for identified issues |\n| False Positive Detection | Reduce noise by validating findings |\n| Prioritization | Rank findings by real-world impact |\n\n### GitHub Service\n\nHandles GitHub API interactions:\n\n| Feature | Description |\n|---------|-------------|\n| Repository Access | Read code from GitHub repos |\n| Comment Posting | Post inline PR comments with findings |\n| Status Checks | Update commit status for CI/CD gates |\n| Webhook Handling | Process GitHub webhook events |\n\n## Background Workers\n\n### Scan Worker\n\nProcesses scan jobs asynchronously to avoid blocking HTTP requests.\n\n```mermaid\ngraph LR\n A[Scan Request] --> B[Queue]\n B --> C[Worker Pool]\n C --> D[Tool 1: Secrets]\n C --> E[Tool 2: Bandit]\n C --> F[Tool 3: Semgrep]\n C --> G[Tool 4: pip-audit]\n C --> H[Tool 5: Safety]\n D & E & F & G & H --> I[Normalize]\n I --> J[Store Results]\n```\n\n### AI Worker\n\nProcesses AI analysis requests in the background:\n\n| Task | Description |\n|------|-------------|\n| Batch Analysis | Analyze multiple findings together |\n| Fix Generation | Generate remediation code |\n| Score Updates | Recalculate exploitability scores |\n\n## Data Models\n\n### NormalizedFinding\n\nAll scanners output findings in a standardized format:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `tool` | string | Source scanner name |\n| `rule_id` | string | Rule identifier (e.g., CWE-78) |\n| `file` | string | File path with finding |\n| `line` | int | Line number (0 for dependencies) |\n| `severity` | enum | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO` |\n| `message` | string | Human-readable description |\n| `code_snippet` | string | Relevant source code (if applicable) |\n| `metadata` | dict | Scanner-specific data (CVE, CVSS, fix versions) |\n\n#### Metadata Schema\n\n| Key | Tool | Description |\n|-----|------|-------------|\n| `cwe` | semgrep, bandit | CWE identifier(s) |\n| `owasp` | semgrep | OWASP category code |\n| `cvss_score` | pip-audit, safety | CVSS v3 base score |\n| `package_name` | pip-audit, safety | Vulnerable package name |\n| `fix_versions` | pip-audit, safety | Safe package versions |\n| `detector` | secrets | Secret detector name |\n| `verified` | secrets | Whether secret was verified |\n| `confidence` | semgrep | Rule confidence level |\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n\n## Output Formats\n\nThe API supports multiple output formats for findings:\n\n| Format | Use Case | Phase |\n|--------|----------|-------|\n| `terminal` | Interactive CLI output | Phase 0 |\n| `json` | Piping, tooling integration | Phase 0 |\n| `sarif` | GitHub Code Scanning, VS Code | Phase 1 |\n\n### SARIF Output\n\nSARIF (Static Analysis Results Interchange Format) provides standardized output for integration with security tooling:\n\n```json\n{\n \"version\": \"2.1.0\",\n \"$schema\": \"https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json\",\n \"runs\": [{\n \"tool\": {\n \"driver\": {\n \"name\": \"Velonus\",\n \"version\": \"0.1.0\"\n }\n },\n \"results\": [...]\n }]\n}\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n\n## Severity Levels\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | `CRITICAL` | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | `HIGH` | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | `MEDIUM` | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | `LOW` | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | `INFO` | Grey | Style issues, informational notes |\n\n## Roadmap Integration\n\n| Phase | Status | API Features |\n|-------|--------|--------------|\n| **Phase 0** | ✅ Complete | CLI skeleton, local scanning |\n| **Phase 1** | ✅ Complete | Scanner pipeline, SARIF output |\n| **Phase 2** | 🔨 Building | AI layer, API backend, authentication |\n| **Phase 3** | 🔜 Planned | GitHub PR integration, inline fixes |\n| **Phase 4** | 🔜 Planned | Web dashboard, scan history |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## CLI vs API Mode\n\n| Aspect | Local CLI | API Backend |\n|--------|-----------|-------------|\n| Authentication | Not required | Clerk OAuth required |\n| Rate Limiting | None | Enforced per user |\n| Scan Execution | Synchronous | Background workers |\n| Results Storage | stdout only | Database |\n| GitHub Integration | None | PR comments, status checks |\n| AI Features | None | Fix generation, scoring |\n\nWhen the API backend is live, users can choose between:\n\n```bash\n# Local mode (always works)\nvelonus scan ./my-project\n\n# Cloud mode (requires auth)\nvelonus auth login\nvelonus scan ./my-project --remote\n```\n\n## Configuration\n\n### CLI Configuration\n\nThe `velonus config` command manages local CLI settings:\n\n| Command | Description |\n|---------|-------------|\n| `velonus config show` | Print current configuration |\n| `velonus config set api_url ` | Set API endpoint |\n| `velonus config set api_key ` | Set API authentication key |\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `VELONUS_API_URL` | API backend URL | `https://api.velonus.dev` |\n| `VELONUS_API_KEY` | Authentication key | None |\n| `VELONUS_TIMEOUT` | Scan timeout in seconds | 300 |\n\n## Error Handling\n\n| HTTP Code | Meaning |\n|-----------|---------|\n| `200` | Success |\n| `400` | Invalid request parameters |\n| `401` | Not authenticated |\n| `403` | Forbidden (insufficient permissions) |\n| `404` | Resource not found |\n| `429` | Rate limit exceeded |\n| `500` | Internal server error |\n| `503` | Service unavailable (maintenance) |\n\nCLI exit codes:\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH/CRITICAL findings |\n| `1` | Scan completed, HIGH/CRITICAL findings found |\n\n## Development Guidelines\n\nThe API backend follows the project's contribution standards:\n\n- All code must pass `ruff check` and `ruff format --check`\n- Type checking with `mypy --strict --ignore-missing-imports`\n- Unit tests required for all new endpoints and services\n- PRs should be under 400 lines of diff\n- No AI-generated placeholder code\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## Scanner Pipeline\n\n### 相关页面\n\n相关主题：[Security Detectors](#security-detectors), [Output Formats](#output-formats), [API Backend](#api-backend)\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/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/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n
\n\n# Scanner Pipeline\n\n## Overview\n\nThe Scanner Pipeline is the core orchestration layer in Velonus that coordinates multiple security scanning tools into a unified, concurrent execution framework. It provides a single entry point for running comprehensive security analysis across Python codebases, combining static analysis, secret detection, and dependency vulnerability scanning.\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:1-15]()\n\n## Architecture\n\nThe pipeline follows a parallel execution model using Python's `asyncio` framework. Each security tool runs concurrently, with results collected, normalized, and deduplicated before presentation.\n\n```mermaid\ngraph TD\n A[User Input: Target Path] --> B[ScanPipeline.run]\n B --> C{Is Async Context?}\n C -->|Yes| D[Direct await]\n C -->|No| E[asyncio.run wrapper]\n D --> F[Parallel Scanner Execution]\n E --> F\n F --> G[Secrets Detector]\n F --> H[Bandit Detector]\n F --> I[Semgrep Detector]\n F --> J[pip-audit Detector]\n F --> K[Safety Detector]\n G --> L[RawFinding List]\n H --> L\n I --> L\n J --> L\n K --> L\n L --> M[FindingNormalizer]\n M --> N[DeduplicationFilter]\n N --> O[NormalizedFinding List]\n O --> P[Output Formatters]\n P --> Q[Terminal / JSON / SARIF]\n```\n\n## Pipeline Execution Model\n\n### Concurrent Execution\n\nThe pipeline executes all five detectors in parallel using `asyncio.gather()`. This approach minimizes total scan time by running independent security checks simultaneously rather than sequentially.\n\n```python\nresults: list[list[RawFinding]] = await asyncio.gather(\n self._run_detector(secrets_runner, target, verbose),\n self._run_detector(bandit_runner, target, verbose),\n self._run_detector(semgrep_runner, target, verbose),\n self._run_detector(pip_audit_runner, target, verbose),\n self._run_detector(safety_runner, target, verbose),\n)\n```\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:80-90]()\n\n### Execution Order\n\nDetectors are executed in a fixed order for consistent logging output:\n\n| Order | Tool | Purpose |\n|-------|------|---------|\n| 0 | secrets | Hardcoded secrets and high-entropy strings |\n| 1 | bandit | Python security best practices |\n| 2 | semgrep | Custom ruleset scanning |\n| 3 | pip-audit | Python dependency vulnerabilities |\n| 4 | safety | Additional dependency checking |\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:69-70]()\n\n### Dual Context Support\n\nThe pipeline supports both async and sync usage patterns:\n\n```python\n# Async context (e.g., API background worker)\npipeline = ScanPipeline()\nfindings = await pipeline.run(Path(\"./my-project\"), verbose=True)\n\n# Sync context (CLI)\nimport asyncio\nfindings = asyncio.run(ScanPipeline().run(Path(\"./my-project\")))\n```\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:14-25]()\n\n## Supported Detectors\n\n### Secrets Detector\n\nThe secrets detector provides dual-layer secret detection:\n\n#### TruffleHog Integration\n\nTruffleHog is the primary secret scanner. It uses commit history analysis and regex-based detector rules to identify verified secrets with high confidence.\n\n**资料来源：** [packages/scanner/scanner/detectors/secrets.py:40-60]()\n\n#### Entropy-Based Fallback\n\nWhen TruffleHog detects a high-entropy string, it flags potential hardcoded credentials:\n\n```python\nmessage=(\n f\"High-entropy string in secret assignment \"\n f\"(Shannon entropy={entropy:.2f}) — likely a hardcoded credential\"\n)\n```\n\n**资料来源：** [packages/scanner/scanner/detectors/secrets.py:180-185]()\n\nThe entropy scanner walks the target path recursively, skipping non-code directories and binary files:\n\n**Skipped directories:** `.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build`\n\n**资料来源：** [packages/scanner/scanner/detectors/secrets.py:95-100]()\n\n### Bandit Detector\n\nBandit analyzes Python code for common security issues using configurable test sets. It produces findings with severity ratings based on the potential impact of identified issues.\n\n### Semgrep Detector\n\nSemgrep runs rule-based analysis using the `p/python` ruleset:\n\n```python\ndef scan(self, target: Path) -> list[RawFinding]:\n return self._run_semgrep(target)\n```\n\n**Invocation command:** `semgrep scan --config p/python --json --quiet --metrics=off `\n\n**资料来源：** [packages/scanner/scanner/detectors/semgrep.py:22-30]()\n\n#### Availability Check\n\nSemgrep availability is verified via a lightweight version check:\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:55-65]()\n\nIf semgrep is not installed, the detector logs a warning and skips analysis rather than failing the entire scan.\n\n### pip-audit Detector\n\npip-audit scans Python dependencies against the Python Packaging Advisory Database. It extracts CVSS v3 scores to determine severity ratings and identifies available fix versions.\n\n**资料来源：** [packages/scanner/scanner/detectors/pip_audit.py:60-85]()\n\n### Safety Detector\n\nSafety provides an additional layer of dependency vulnerability checking, extracting CVE identifiers and advisory information for prioritization.\n\n**资料来源：** [packages/scanner/scanner/detectors/safety.py:1-30]()\n\n## Data Flow\n\n```mermaid\ngraph LR\n A[RawFinding] --> B[FindingNormalizer]\n B --> C[NormalizedFinding]\n C --> D[DeduplicationFilter]\n D --> E[Final Findings]\n \n F[tool+file+line+rule_id] --> G[SHA-256 Hash]\n G --> H[16-char ID]\n```\n\n### Raw Finding Structure\n\nDetectors produce `RawFinding` objects containing raw output from security tools:\n\n```python\n@dataclass\nclass RawFinding:\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[str, Any]\n```\n\n### Normalized Finding Structure\n\n`FindingNormalizer` converts raw findings into a canonical format:\n\n```python\n@dataclass\nclass NormalizedFinding:\n id: str # SHA-256[:16] of tool+file+line+rule_id\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\n```\n\n**资料来源：** [packages/normalizer/models.py:1-50]()\n\n### Deduplication\n\nThe `DeduplicationFilter` removes duplicate findings across scans using deterministic SHA-256 identifiers derived from `tool + file + line + rule_id`. This ensures consistent identification of the same vulnerability across multiple scans.\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:77-78]()\n\n## Severity Classification\n\n| Level | Badge | Use Case |\n|-------|-------|----------|\n| CRITICAL | 🔴 | Hardcoded secrets, RCE, auth bypass |\n| HIGH | 🟠 | SQL injection, command injection, insecure deserialization |\n| MEDIUM | 🟡 | XSS, weak crypto, path traversal |\n| LOW | 🔵 | Insecure defaults, minor misconfigurations |\n| INFO | ⚪ | Style issues, informational notes |\n\n**资料来源：** [apps/cli/README.md:95-105]()\n\n## Usage Examples\n\n### Async Usage\n\n```python\nfrom scanner.pipeline import ScanPipeline\nfrom pathlib import Path\n\nasync def scan_project():\n pipeline = ScanPipeline()\n findings = await pipeline.run(Path(\"./my-project\"), verbose=True)\n return findings\n```\n\n### Sync Usage\n\n```python\nimport asyncio\nfrom scanner.pipeline import ScanPipeline\nfrom pathlib import Path\n\nfindings = asyncio.run(\n ScanPipeline().run(Path(\"./my-project\"))\n)\n```\n\n### CLI Usage\n\n```bash\n# Full scan with all detectors\nvelonus scan ./\n\n# High severity only (CI gate)\nvelonus scan ./ --severity high\n\n# JSON output for tooling\nvelonus scan ./ --format json\n\n# SARIF output for GitHub Security tab\nvelonus scan ./ --format sarif -o results.sarif\n\n# Verbose timing output\nvelonus scan ./ --verbose\n```\n\n**资料来源：** [README.md:20-40]()\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Scan completed, no HIGH or CRITICAL findings |\n| 1 | Scan completed, one or more HIGH or CRITICAL findings found |\n\nExit code 1 on HIGH/CRITICAL is intentional for CI/CD integration, enabling automated blocking of merges.\n\n**资料来源：** [apps/cli/README.md:70-80]()\n\n## Error Handling\n\n### Semgrep Exit Code Handling\n\nSemgrep exits with code 1 when findings are present. This is not treated as an error:\n\n> Semgrep exits with code 1 when findings are present. This is NOT treated as an error — the JSON output is still fully valid and parsed normally. Exit code 2+ indicates a real error (bad arguments, semgrep crash).\n\n**资料来源：** [packages/scanner/scanner/detectors/semgrep.py:22-30]()\n\n### Missing Tool Handling\n\nIf a security tool is not installed, the detector logs a warning and returns an empty list rather than failing the scan:\n\n```python\nif not self._semgrep_available():\n logger.warning(\n \"semgrep not found on PATH — skipping Semgrep analysis. \"\n \"Install with: pip install semgrep\"\n )\n return []\n```\n\n**资料来源：** [packages/scanner/scanner/detectors/semgrep.py:32-37]()\n\n## Performance Characteristics\n\n- **Parallel execution** of all detectors minimizes total scan time\n- **Timing logging** occurs at INFO level when `verbose=True`, DEBUG otherwise\n- **Skip patterns** exclude common non-code directories to reduce scan scope\n- **Empty results** are handled gracefully, allowing partial scans when tools are unavailable\n\n---\n\n\n\n## Security Detectors\n\n### 相关页面\n\n相关主题：[Scanner Pipeline](#scanner-pipeline), [Output Formats](#output-formats)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [packages/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.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# Security Detectors\n\n## Overview\n\nSecurity Detectors are the core scanning engines within Velonus that identify vulnerabilities, secrets, and insecure code patterns. Each detector wraps an external security tool (TruffleHog, Bandit, Semgrep, pip-audit, Safety) and normalizes its output into a unified `RawFinding` format. This abstraction layer enables Velonus to run multiple security scanners through a single interface while presenting results in a consistent structure.\n\nThe detector system is located in `packages/scanner/detectors/` and `packages/scanner/scanner/detectors/`, with each module handling a specific security tool. Detectors serve as the first stage in Velonus's scanning pipeline, producing raw findings that are later normalized by the `FindingNormalizer` into the canonical `NormalizedFinding` model. [资料来源：packages/scanner/detectors/__init__.py:1]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Scan Request] --> B[Scanner Pipeline]\n B --> C[Secrets Detector]\n B --> D[Bandit Detector]\n B --> E[Semgrep Detector]\n B --> F[pip-audit Detector]\n B --> G[Safety Detector]\n \n C --> H[RawFinding Objects]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[FindingNormalizer]\n I --> J[NormalizedFinding Objects]\n J --> K[Output Formatters]\n K --> L[Terminal / JSON / SARIF]\n```\n\n### Component Overview\n\n| Detector | Tool Wrapped | Purpose |\n|----------|--------------|---------|\n| `secrets` | TruffleHog + Entropy | Hardcoded secrets and credentials |\n| `bandit` | Bandit | Python security issues |\n| `semgrep` | Semgrep | Custom security rules |\n| `pip-audit` | pip-audit | Python dependency vulnerabilities |\n| `safety` | Safety | Legacy Python dependency vulnerabilities |\n\n## Secrets Detector\n\nThe Secrets Detector identifies hardcoded secrets, API keys, passwords, and other sensitive credentials in source code. It employs a two-tier detection strategy: primary TruffleHog scanning followed by an entropy-based fallback for generic high-entropy strings.\n\n### Detection Pipeline\n\n```mermaid\ngraph LR\n A[File Input] --> B{TruffleHog Scan}\n B -->|Verified Secrets| C[RawFinding]\n B -->|No Secrets Found| D[Entropy Fallback]\n D -->|High Entropy| E[RawFinding]\n D -->|Low Entropy| F[Skip]\n```\n\n### TruffleHog Integration\n\nThe detector invokes TruffleHog as the primary secret scanner. When TruffleHog returns results, each finding is parsed and converted to a `RawFinding` object with the following characteristics:\n\n- **Tool**: `secrets`\n- **Rule ID**: `trufflehog-{detector-name}` (lowercase, spaces replaced with hyphens)\n- **Severity**: `CRITICAL` (all TruffleHog findings)\n- **Verification Status**: Captured in metadata as `verified: bool`\n- **Decoder Information**: Extracted from `DecoderName` in TruffleHog output\n\n[资料来源：packages/scanner/detectors/secrets.py:1-30]()\n\n### Entropy-Based Fallback\n\nWhen TruffleHog is unavailable or returns no findings, the detector falls back to an entropy-based scanner (`_entropy_scan`). This method:\n\n1. Walks the target directory recursively\n2. Skips non-code directories (`.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build`)\n3. Applies regex patterns for known secret types\n4. Calculates Shannon entropy for candidate strings\n5. Flags strings exceeding the `_ENTROPY_THRESHOLD`\n\n[资料来源：packages/scanner/detectors/secrets.py:50-80]()\n\n### File Iteration Logic\n\nThe `_iter_files` method yields scannable source files while excluding:\n\n```python\n# Skipped directories\n.git, node_modules, __pycache__, .venv, venv, \n.env, dist, build\n```\n\n### Finding Structure\n\nEach secrets finding includes:\n\n| Field | Value | Description |\n|-------|-------|-------------|\n| `tool` | `secrets` | Scanner identifier |\n| `rule_id` | `high-entropy-secret` or `trufflehog-{name}` | Rule identifier |\n| `severity` | `CRITICAL` | Always critical for secrets |\n| `message` | Dynamic | Includes entropy score or verification status |\n| `metadata` | `dict` | Contains entropy value, detector name, decoder |\n\n[资料来源：packages/scanner/detectors/secrets.py:100-130]()\n\n## Dependency Vulnerability Detectors\n\nVelonus includes two detectors for Python dependency vulnerabilities: **pip-audit** and **Safety**. Both analyze dependency manifests (e.g., `requirements.txt`) and report known CVEs.\n\n### pip-audit Detector\n\nThe pip-audit detector parses JSON output from the `pip-audit` tool and converts vulnerabilities into `RawFinding` objects.\n\n#### Data Extraction\n\nThe detector extracts the following fields from pip-audit JSON:\n\n| Field | Source | Purpose |\n|-------|--------|---------|\n| `package_name` | `entry` | Vulnerable package name |\n| `package_version` | `entry` | Installed version |\n| `vuln_id` | `entry` | Vulnerability identifier |\n| `aliases` | `entry` | Alternative IDs (CVEs, GHSA) |\n| `fix_versions` | `entry` | Safe versions to upgrade to |\n| `cvss_score` | Nested `severity` dict | CVSS v3 base score |\n| `fix_available` | `bool(fix_versions)` | Whether a fix exists |\n\n[资料来源：packages/scanner/scanner/detectors/pip_audit.py:1-50]()\n\n#### CVSS Score Extraction\n\nThe `_extract_cvss_score` helper parses pip-audit's nested CVSS format:\n\n```python\n[{\"type\": \"CVSS_V3\", \"score\": \"CVSS:3.1/...\", \"base_score\": 7.5}]\n```\n\nThe detector prefers CVSS v3 scores and selects the highest when multiple are present. [资料来源：packages/scanner/scanner/detectors/pip_audit.py:80-100]()\n\n#### Message Construction\n\nFinding messages include:\n- Package name and version\n- Vulnerability ID (preferred CVE alias)\n- Fix hint (if available)\n- Truncated description (max 200 characters)\n\n### Safety Detector\n\nThe Safety detector handles both Safety v1 and v2 JSON output formats, which differ significantly in structure.\n\n#### Supported Output Formats\n\n| Format | Version | Structure | Finding Count |\n|--------|---------|-----------|----------------|\n| Format A | Safety ≥2.0 | `{\"vulnerabilities\": [...]}` | One per entry |\n| Format B | Safety <2.0 | `[...]` (list of lists) | One per 5-element list |\n\n[资料来源：packages/scanner/scanner/detectors/safety.py:1-50]()\n\n#### Entry Parsing (v2 Format)\n\nFor Safety v2, each vulnerability entry must contain:\n\n```python\nrequired_fields = [\"vulnerability_id\", \"package_name\", \"analyzed_version\"]\n```\n\nEntries missing required fields are skipped with a warning. [资料来源：packages/scanner/scanner/detectors/safety.py:50-80]()\n\n#### Parsed Fields\n\n| Field | Extraction | Notes |\n|-------|------------|-------|\n| `vuln_id` | `entry[\"vulnerability_id\"]` | str conversion |\n| `package_name` | `entry[\"package_name\"]` | str conversion |\n| `installed_version` | `entry[\"analyzed_version\"]` | str conversion |\n| `advisory` | `entry.get(\"advisory\")` | Human-readable text |\n| `cve` | `entry.get(\"CVE\")` | CVE identifier (preferred display) |\n| `fix_versions` | `entry.get(\"fixed_versions\", [])` | List of safe versions |\n\n[资料来源：packages/scanner/scanner/detectors/safety.py:80-120]()\n\n#### Severity Mapping\n\nCVSS scores are converted to severity levels:\n\n```python\ndef _cvss_to_severity(cvss_score: float | None) -> str:\n if cvss_score is None:\n return \"MEDIUM\" # Default\n elif cvss_score >= 9.0:\n return \"CRITICAL\"\n elif cvss_score >= 7.0:\n return \"HIGH\"\n elif cvss_score >= 4.0:\n return \"MEDIUM\"\n else:\n return \"LOW\"\n```\n\n## Finding Data Models\n\n### RawFinding\n\nAll detectors produce `RawFinding` objects with this structure:\n\n```python\n@dataclass\nclass RawFinding:\n tool: str # \"bandit\"|\"semgrep\"|\"secrets\"|\"pip-audit\"|\"safety\"\n rule_id: str # Scanner-specific rule identifier\n file: str # Path to file containing the finding\n line: int # Line number (0 for dependency findings)\n severity: str # CRITICAL|HIGH|MEDIUM|LOW|INFO\n message: str # Human-readable description\n code_snippet: str # Relevant code (redacted for secrets)\n metadata: dict # Tool-specific additional data\n```\n\n### NormalizedFinding\n\nAfter normalization, findings conform to the canonical `NormalizedFinding` model:\n\n```python\n@dataclass\nclass NormalizedFinding:\n id: str # SHA-256: sha256(tool+file+line+rule_id)[:16]\n tool: str # Scanner identifier\n rule_id: str # Normalized rule identifier\n cwe: list[str] # CWE identifiers (e.g., [\"CWE-89\"])\n owasp: list[str] # OWASP categories (e.g., [\"A03:2021\"])\n severity: Severity # Enum: CRITICAL|HIGH|MEDIUM|LOW|INFO\n confidence: Confidence # Enum: HIGH|MEDIUM|LOW\n file: str # File path\n line_start: int # Start line\n line_end: int # End line\n code_snippet: str # Redacted code snippet\n message: str # Finding message\n fix_available: bool = False # Whether a fix exists\n suppressed: bool = False # Whether suppressed\n first_seen: datetime # Timestamp\n```\n\n[资料来源：packages/normalizer/models.py:1-50]()\n\n## Extensibility\n\nAdding a new detector follows a consistent pattern:\n\n1. **Create a new module** in `packages/scanner/detectors/`\n2. **Implement the detector class** with `_scan()` method\n3. **Return `RawFinding` objects** for each finding\n4. **Include metadata** for downstream normalization\n\n### Detector Interface Pattern\n\n```python\nclass BaseDetector:\n def _scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Main scanning entry point - override in subclasses.\"\"\"\n raise NotImplementedError\n \n def _iter_files(self, root: Path) -> Iterator[Path]:\n \"\"\"File iteration with exclusions - reusable utility.\"\"\"\n ...\n```\n\n## Severity Classification\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | `CRITICAL` | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | `HIGH` | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | `MEDIUM` | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | `LOW` | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | `INFO` | Grey | Style issues, informational notes |\n\n## Output Integration\n\nDetectors feed into Velonus's output formatters:\n\n| Format | Use Case | Consumer |\n|--------|----------|----------|\n| `terminal` | Interactive scanning | CLI users |\n| `json` | Piping to tools | CI/CD pipelines, scripting |\n| `sarif` | GitHub Security tab | GitHub integration |\n\nThe scanner exits with code `1` when CRITICAL or HIGH findings are detected, enabling use as a CI gate.\n\n---\n\n\n\n## Output Formats\n\n### 相关页面\n\n相关主题：[CLI Components](#cli-components), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/shield/formatters/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/__init__.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n- [apps/cli/shield/core/output.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/output.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/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- [packages/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.py)\n
\n\n# Output Formats\n\nVelonus supports multiple output formats for scan results, enabling integration with various security tooling, CI/CD pipelines, and developer workflows. Each format serves a specific use case and targets a different audience.\n\n## Overview\n\nThe output format system transforms normalized `RawFinding` objects into format-specific representations. This abstraction allows Velonus to aggregate results from multiple security scanners (Bandit, Semgrep, pip-audit, Safety, TruffleHog) while presenting them consistently regardless of the underlying tool.\n\n资料来源：[apps/cli/shield/formatters/__init__.py:1]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Scan Command] --> B[Scanner Pipeline]\n B --> C[RawFinding Objects]\n C --> D[Normalizer]\n D --> E[NormalizedFinding]\n E --> F[Output Formatters]\n \n F --> G[Terminal Formatter]\n F --> H[JSON Formatter]\n F --> I[SARIF Formatter]\n \n G --> J[Rich Console Output]\n H --> K[JSON File/Stream]\n I --> L[SARIF 2.1.0 File]\n```\n\n## Supported Formats\n\n| Format | Command Flag | Use Case | Phase |\n|--------|-------------|----------|-------|\n| `terminal` | `--format terminal` | Interactive scanning | Phase 0 |\n| `json` | `--format json` | Piping to tools, storage | Phase 0 |\n| `sarif` | `--format sarif` | GitHub Security tab, VS Code | Phase 1 |\n\n资料来源：[apps/cli/README.md:60-65]()\n\n## Terminal Format\n\nThe default output format using Rich library for colored, formatted tables with severity badges.\n\n### Severity Color Scheme\n\nThe terminal formatter uses a consistent color system defined in `output.py`:\n\n| Severity | Color | Badge | Description |\n|----------|-------|-------|-------------|\n| `CRITICAL` | Bold red | 🔴 | Hardcoded secrets, RCE, auth bypass |\n| `HIGH` | Dark orange | 🟠 | SQL injection, command injection |\n| `MEDIUM` | Yellow | 🟡 | XSS, weak crypto, path traversal |\n| `LOW` | Steel blue | 🔵 | Insecure defaults, minor issues |\n| `INFO` | Grey | ⚪ | Style issues, informational notes |\n\n资料来源：[apps/cli/shield/core/output.py:18-29]()\n\n### Output Table Columns\n\n| Column | Description |\n|--------|-------------|\n| Severity | Emoji badge and severity level |\n| Tool | Source scanner (bandit, semgrep, pip-audit, etc.) |\n| File | Path to affected file |\n| Line | Line number of finding |\n| Rule | Rule ID or check name |\n| Message | Human-readable finding description |\n\n### Terminal Usage\n\n```bash\n# Default terminal output\nvelonus scan ./\n\n# Explicit terminal format\nvelonus scan ./ --format terminal\n\n# Filter by severity\nvelonus scan ./ --severity high\n```\n\n## JSON Format\n\nMachine-readable JSON output suitable for piping into other tools or storing results.\n\n### JSON Output Structure\n\n```bash\nvelonus scan ./ --format json\n```\n\nProduces a JSON array of findings with the following schema:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `tool` | string | Source scanner name |\n| `rule_id` | string | Unique identifier for the rule |\n| `file` | string | Path to affected file |\n| `line` | integer | Line number (0 for dependency issues) |\n| `severity` | string | CRITICAL, HIGH, MEDIUM, LOW, INFO |\n| `message` | string | Human-readable description |\n| `code_snippet` | string | Relevant source code (may be redacted) |\n| `metadata` | object | Additional scanner-specific data |\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:40-52]()\n\n### JSON Usage Examples\n\n```bash\n# Pretty-print JSON\nvelonus scan ./ --format json | python -m json.tool\n\n# Save to file\nvelonus scan ./ --format json > scan-results.json\n\n# Filter by severity\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n## SARIF Format\n\nStatic Analysis Results Interchange Format (SARIF 2.1.0) for compatibility with security tooling.\n\n### SARIF Specification\n\n| Property | Value |\n|----------|-------|\n| Schema Version | 2.1.0 |\n| Specification URL | https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html |\n| Version Constant | `0.1.0` |\n\n资料来源：[apps/cli/shield/formatters/sarif.py:38-41]()\n\n### Severity Mapping\n\n| Velonus Severity | SARIF Level |\n|-----------------|-------------|\n| CRITICAL | `error` |\n| HIGH | `error` |\n| MEDIUM | `warning` |\n| LOW | `note` |\n| INFO | `note` |\n\n资料来源：[apps/cli/shield/formatters/sarif.py:48-54]()\n\n### Rule ID Transformation\n\nSARIF rule IDs are converted to PascalCase display names:\n\n```python\n\"generic-api-key\" → \"GenericApiKey\"\n\"secrets/aws-access-key-id\" → \"AwsAccessKeyId\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:59-60]()\n\n### Directory URI Handling\n\nPer SARIF spec §3.14.14, directory URIs must end with a trailing slash:\n\n```python\nuri = path.as_uri()\nreturn uri if uri.endswith(\"/\") else uri + \"/\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:23-24]()\n\n### SARIF Integration Points\n\n```mermaid\ngraph LR\n A[Velonus Scan] --> B[SARIF File]\n B --> C[GitHub Security Tab]\n B --> D[VS Code SARIF Viewer]\n B --> E[Other SARIF Tools]\n```\n\n### SARIF Usage\n\n```bash\n# Default SARIF output\nvelonus scan ./ --format sarif\n\n# Custom output path\nvelonus scan ./ -o results/velonus.sarif\n\n# Severity filtering (recommended for SARIF)\nvelonus scan ./ --format sarif --severity high -o findings.sarif\n```\n\n### GitHub Actions Integration\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:45-50]()\n\n## Finding Data Model\n\n### RawFinding Structure\n\nEach scanner produces `RawFinding` objects that are normalized before formatting:\n\n```python\nRawFinding(\n tool=\"pip-audit\",\n rule_id=vuln_id,\n file=attribution_path,\n line=0, # Dependency findings are file-level\n severity=severity,\n message=message,\n code_snippet=\"\",\n metadata={\n \"package_name\": package_name,\n \"package_version\": package_version,\n \"cvss_score\": cvss_score,\n \"fix_available\": bool(fix_versions),\n },\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:40-52]()\n\n### Metadata Fields by Scanner\n\n| Scanner | Unique Metadata Fields |\n|---------|----------------------|\n| pip-audit | `package_name`, `package_version`, `aliases`, `fix_versions`, `cvss_score`, `cwe`, `owasp`, `fix_available` |\n| safety | `vulnerable_spec`, `analysis`, `published_date`, `fixed_versions`, `advisory` |\n| semgrep | `cwe`, `owasp`, `confidence`, `rule_short` |\n| secrets | `detector`, `verified`, `decoder`, `entropy` |\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:25-35]()\n\n## CLI Options\n\n### Global Format Options\n\n| Option | Short | Default | Description |\n|--------|-------|---------|-------------|\n| `--format` | `-f` | `terminal` | Output format: `terminal`, `json`, `sarif` |\n| `--severity` | `-s` | `info` | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--output` | `-o` | (stdout) | Output file path (for SARIF/JSON) |\n| `--verbose` | `-v` | off | Show resolved target path and extra detail |\n\n资料来源：[apps/cli/README.md:61-66]()\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH or CRITICAL findings |\n| `1` | Scan completed, one or more HIGH or CRITICAL findings found |\n\n资料来源：[apps/cli/README.md:97-98]()\n\n## Format Selection Guide\n\n```mermaid\ngraph TD\n A[Choose Output Format] --> B{Use Case}\n \n B -->|Interactive scanning| C[terminal]\n B -->|CI/CD pipeline| D{Hosting Platform}\n B -->|Tooling integration| E[json]\n \n D -->|GitHub| F[sarif]\n D -->|GitLab| G[json]\n D -->|Azure DevOps| H[sarif]\n \n C --> I[Rich colored tables]\n F --> J[GitHub Security tab]\n E --> K[JSON API processing]\n```\n\n### Quick Reference\n\n| Scenario | Recommended Format |\n|----------|-------------------|\n| Local development | `terminal` (default) |\n| Pre-commit hooks | `terminal --severity high` |\n| CI gate (GitHub) | `sarif` |\n| Log aggregation | `json` |\n| Custom tooling | `json` |\n| Security dashboards | `sarif` |\n\n---\n\n\n\n## AI Engine\n\n### 相关页面\n\n相关主题：[API Backend](#api-backend), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/ai-engine/ai_engine/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/ai_engine/__init__.py)\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\n# AI Engine\n\nThe **AI Engine** is a core component of Velonus (Phase 2) that provides intelligent prioritization, exploitability scoring, and automated fix generation for security findings. It processes normalized findings from the scanner pipeline and applies AI-driven analysis to help developers focus on the most critical issues first.\n\n## Architecture Overview\n\nThe AI Engine is structured as a modular system with three primary sub-engines:\n\n| Component | Purpose |\n|-----------|---------|\n| **Context Engine** | Enriches findings with contextual information about the codebase |\n| **Remediation Engine** | Generates actionable fix suggestions for identified vulnerabilities |\n| **AI Service** | Handles API communication and LLM integration |\n\n```mermaid\ngraph TD\n A[NormalizedFindings] --> B[Context Engine]\n B --> C[Enriched Findings]\n C --> D[Remediation Engine]\n D --> E[Fix Suggestions]\n C --> F[Exploitability Scoring]\n F --> G[Priority Ranking]\n G --> H[Dashboard / CLI Output]\n```\n\n资料来源：[packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n\n## Core Sub-Engines\n\n### Context Engine\n\nThe Context Engine analyzes security findings in their broader codebase context to determine:\n\n- **Reachability analysis** — Is the vulnerable code actually executed?\n- **Data flow analysis** — Does user input reach the vulnerable code path?\n- **Dependency context** — Are there mitigating factors in dependencies?\n\n资料来源：[packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n\n### Remediation Engine\n\nThe Remediation Engine generates specific, actionable fix recommendations based on:\n\n- The vulnerability type and severity\n- The affected code location\n- Project-specific patterns and conventions\n\n资料来源：[packages/ai-engine/remediation_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/remediation_engine.py)\n\n### AI Service\n\nLocated in the API layer, the AI Service handles:\n\n- LLM provider integration\n- Request batching and rate limiting\n- Response parsing and validation\n\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## Prompt Engineering\n\nThe AI Engine uses carefully crafted prompts stored in `prompts.py` to guide the LLM in:\n\n| Task | Prompt Purpose |\n|------|----------------|\n| Exploitability Assessment | Determine if a vulnerability can be exploited in the given context |\n| Fix Generation | Generate code patches that resolve the vulnerability |\n| Impact Analysis | Evaluate the potential blast radius of a vulnerability |\n\n资料来源：[packages/ai-engine/prompts.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/prompts.py)\n\n## Caching Strategy\n\nTo optimize performance and reduce API costs, the AI Engine implements a caching layer:\n\n```mermaid\ngraph LR\n A[Finding Hash] --> B{Cache Lookup}\n B -->|Hit| C[Return Cached Result]\n B -->|Miss| D[Call LLM API]\n D --> E[Store in Cache]\n E --> C\n```\n\nCache entries are keyed by:\n- Finding hash (vulnerability type + file + line)\n- Code context snippet\n- Project fingerprint\n\n资料来源：[packages/ai-engine/cache.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/cache.py)\n\n## Exploitability Scoring\n\nThe AI Engine assigns exploitability scores (1-10) based on:\n\n| Factor | Weight | Description |\n|--------|--------|-------------|\n| Reachability | 30% | Is the code path executable? |\n| Attack Surface | 25% | Is user-controlled input present? |\n| Preconditions | 20% | What conditions must be met? |\n| Impact | 25% | What is the potential damage? |\n\n资料来源：[packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n\n## Integration with Scanner Pipeline\n\nThe AI Engine receives input from the [ScanPipeline](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py) after findings have been normalized:\n\n```python\n# Pipeline execution order (from packages/scanner/scanner/pipeline.py)\n# 0 = secrets, 1 = bandit, 2 = semgrep, 3 = pip-audit, 4 = safety\n```\n\nNormalized findings flow into the AI Engine which:\n1. Deduplicates findings using the [DeduplicationFilter](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n2. Enriches each finding with AI-generated context\n3. Ranks findings by priority\n4. Generates remediation suggestions\n\n## Configuration\n\nThe AI Engine is configured via the CLI configuration system (`velonus config set`):\n\n| Config Key | Default | Description |\n|------------|---------|-------------|\n| `ai_provider` | `openai` | LLM provider (openai, anthropic) |\n| `ai_model` | `gpt-4` | Model to use for analysis |\n| `ai_temperature` | `0.3` | Creativity level for fix generation |\n| `cache_enabled` | `true` | Enable/disable result caching |\n| `max_fixes_per_finding` | `3` | Maximum fix suggestions per vulnerability |\n\n资料来源：[packages/ai-engine/ai_engine/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/ai_engine/__init__.py)\n\n## CLI Integration\n\nThe AI Engine features are accessible through Phase 2 CLI commands:\n\n```bash\n# View AI-generated context for findings\nvelonus scan ./ --ai-context\n\n# Generate fix suggestions\nvelonus fix \n\n# Run with AI prioritization\nvelonus scan ./ --ai-prioritize\n```\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## Development Status\n\n| Phase | Status | Components |\n|-------|--------|------------|\n| Phase 0 | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 | ✅ Done | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| **Phase 2** | 🔨 **Building** | AI context engine, exploitability scoring, fix generation |\n| Phase 3 | 🔜 Planned | GitHub PR inline review comments, one-click fix suggestions |\n| Phase 4 | 🔜 Planned | Web UI, scan history, finding trends |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## API Endpoints\n\nThe AI Engine exposes REST endpoints via the API service:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v1/ai/enrich` | POST | Enrich findings with AI context |\n| `/api/v1/ai/score` | POST | Calculate exploitability scores |\n| `/api/v1/ai/remediate` | POST | Generate fix suggestions |\n\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## Security Considerations\n\nThe AI Engine handles sensitive data and implements the following safeguards:\n\n- **No code exfiltration** — Source code is only processed locally or sent to configured LLM providers\n- **Input sanitization** — All prompts are sanitized before sending to LLM\n- **Audit logging** — All AI requests are logged for compliance\n- **Cache encryption** — Cached results are encrypted at rest\n\n资料来源：[packages/ai-engine/cache.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/cache.py)\n\n---\n\n\n\n## GitHub PR Reviewer\n\n### 相关页面\n\n相关主题：[API Backend](#api-backend), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.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/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n
\n\n# GitHub PR Reviewer\n\n## Overview\n\nThe GitHub PR Reviewer is a planned feature in the Velonus security scanning platform designed to provide automated code review capabilities directly within GitHub Pull Requests. Based on the project roadmap, this feature is designated as **Phase 3 — GitHub Integration** and is currently marked as **Not Started**.\n\n资料来源：[README.md:Phase 3]()\n\nThe Velonus project is a security scanner designed to detect vulnerabilities, secrets, and security issues in Python codebases. The platform currently supports multiple security scanning tools including Bandit, Semgrep, pip-audit, Safety, and TruffleHog for secret detection.\n\n资料来源：[README.md:Roadmap]()\n\n## Project Architecture\n\nVelonus follows a modular architecture with clear separation between the CLI layer, scanner package, and planned API layer.\n\n```mermaid\ngraph TD\n A[velonus scan CLI] --> B[packages/scanner]\n B --> C[Detectors]\n C --> D[Secrets Scanner]\n C --> E[Bandit]\n C --> F[Semgrep]\n C --> G[pip-audit]\n C --> H[Safety]\n B --> I[Normalizer]\n I --> J[Formatted Output]\n J --> K[Terminal]\n J --> L[JSON]\n J --> M[SARIF]\n N[Planned: GitHub API] -.-> O[PR Reviewer]\n```\n\n资料来源：[README.md:Architecture Overview]()\n资料来源：[apps/cli/README.md:Commands]()\n\n## Current Scanner Pipeline\n\nThe existing scanner pipeline forms the foundation upon which GitHub PR Reviewer will build. The scanner orchestrates multiple security tools and normalizes their findings into a unified format.\n\n### Supported Detectors\n\n| Detector | Purpose | Severity Levels |\n|----------|---------|-----------------|\n| **Secrets Scanner** | Detects hardcoded credentials, API keys, and high-entropy strings | CRITICAL |\n| **Bandit** | Static security analysis for Python | CRITICAL, HIGH, MEDIUM, LOW |\n| **Semgrep** | Rule-based pattern matching (config: `p/python`) | Multiple |\n| **pip-audit** | Python dependency vulnerability scanning | Based on CVSS score |\n| **Safety** | Additional dependency checking | Based on CVSS score |\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:Entropy Scanner]()\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:RULESET Definition]()\n\n### Output Formats\n\nThe current implementation supports three output formats that GitHub PR Reviewer can leverage:\n\n| Format | Use Case | Status |\n|--------|----------|--------|\n| `terminal` | Interactive display with Rich tables | Default |\n| `json` | Programmatic consumption, piping | Available |\n| `sarif` | GitHub Code Scanning, VS Code SARIF Viewer | Phase 1 |\n\n资料来源：[apps/cli/README.md:Output Formats]()\n\nThe SARIF format is particularly relevant for future GitHub integration, as it provides compatibility with GitHub's security tab through the `github/codeql-action/upload-sarif` action.\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:CI Integration]()\n\n## Planned GitHub PR Reviewer Features\n\nBased on the project roadmap and existing architecture patterns, the GitHub PR Reviewer is expected to provide the following capabilities:\n\n### Inline Review Comments\n\nThe primary feature will be posting inline comments on pull requests directly where security issues are detected. This follows the pattern of existing GitHub code scanning integrations.\n\n| Feature | Description |\n|---------|-------------|\n| **Inline Comments** | Post findings as PR review comments with file paths and line numbers |\n| **One-Click Fixes** | Suggest code changes to remediate vulnerabilities |\n| **Status Checks** | Integration with GitHub's required status check system |\n\n资料来源：[README.md:Phase 3 — GitHub Integration]()\n\n### Severity-Based Filtering\n\nThe existing `--severity` filtering mechanism will be leveraged to determine which findings trigger PR blocking:\n\n| Severity | Color | CI Behavior |\n|----------|-------|-------------|\n| 🔴 CRITICAL | Bold red | Blocks merge |\n| 🟠 HIGH | Orange | Blocks merge |\n| 🟡 MEDIUM | Yellow | Warning only |\n| 🔵 LOW | Blue | Informational |\n| ⚪ INFO | Grey | Informational |\n\n资料来源：[apps/cli/README.md:Severity Levels]()\n\nThe CLI already exits with code `1` when CRITICAL or HIGH findings are detected, providing a natural CI gate mechanism.\n\n### Finding Metadata Structure\n\nThe normalized finding format provides the data structure that GitHub PR Reviewer will consume:\n\n```python\nRawFinding(\n tool=\"secrets\", # Source tool\n rule_id=\"high-entropy-secret\", # Finding type\n file=str(path), # File path\n line=line_num, # Line number\n severity=\"CRITICAL\", # Severity level\n message=str, # Human-readable message\n code_snippet=str, # Code context\n metadata={} # Additional data\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:RawFinding Creation]()\n\n## Current GitHub Integration Path\n\nWhile the full GitHub PR Reviewer is not yet implemented, the project provides alternative GitHub integration methods:\n\n### GitHub Actions Workflow\n\nFor CI/CD integration before Phase 3, users can leverage the existing Velonus CLI in 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 - 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资料来源：[apps/cli/README.md:GitHub Actions]()\n\n### Pre-commit Hook\n\nSecurity scanning can be integrated into the development workflow using pre-commit hooks:\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:Pre-commit hook]()\n\n## Development Guidelines\n\nThe project follows strict development standards that will apply to the GitHub PR Reviewer implementation:\n\n### Code Quality Requirements\n\n| Requirement | Tool | Command |\n|-------------|------|---------|\n| Linting | ruff | `ruff check .` |\n| Formatting | ruff | `ruff format .` |\n| Type Checking | mypy | `mypy --strict` |\n\n资料来源：[CONTRIBUTING.md:Code Quality]()\n\n### PR Guidelines\n\nThe contributing guidelines establish patterns that GitHub PR Reviewer development must follow:\n\n1. **One feature per PR** — No bundling unrelated changes\n2. **Tests required** — Every new component needs unit tests\n3. **Small PRs preferred** — Under 400 lines of diff for faster review\n4. **Target main** — All changes merge into main branch\n5. **No AI-generated placeholder code** — Every function must be functional\n\n资料来源：[CONTRIBUTING.md:PR Guidelines]()\n\n### Commit Message Format\n\n```\n: \n\nTypes: feat | fix | refactor | test | docs | infra | chore\n```\n\n资料来源：[CONTRIBUTING.md:Commit Message Format]()\n\n## Project Roadmap\n\n| Phase | Status | Components |\n|-------|--------|------------|\n| Phase 0 — Foundation | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 — Scanner Pipeline | ✅ Done | Bandit, Semgrep, pip-audit, Safety, SARIF |\n| Phase 2 — AI Layer | 🔨 Building | AI prioritization, exploitability scoring, fix generation |\n| **Phase 3 — GitHub Integration** | 🔴 Not Started | PR inline review comments, one-click fix suggestions |\n| Phase 4 — Dashboard | 🔴 Not Started | Web UI, scan history, finding trends |\n\n资料来源：[README.md:Roadmap]()\n\n## Dependencies and Requirements\n\nThe scanner already includes several dependencies that would support GitHub PR Reviewer functionality:\n\n### Security Scanning Dependencies\n\n- **TruffleHog** — For secrets detection with decoder support\n- **Bandit** — Python-specific security issues\n- **Semgrep** — Pattern-based security rules\n- **pip-audit** — Python dependency vulnerability scanning\n\n### CVSS Integration\n\nThe pip-audit and Safety detectors already extract and normalize CVSS scores:\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 # Returns CVSS:3.1/... formatted scores\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:CVSS Helpers]()\n\n## Summary\n\nThe GitHub PR Reviewer is an anticipated Phase 3 feature of the Velonus security scanning platform. While not yet implemented, the foundation is being built through:\n\n1. A robust scanner pipeline with multiple security tool integrations\n2. Normalized finding formats suitable for PR comment generation\n3. SARIF output for GitHub Security tab compatibility\n4. CI/CD integration patterns via GitHub Actions\n5. Strict code quality standards for future development\n\nThe existing architecture and roadmap indicate that when Phase 3 development begins, the PR Reviewer will leverage the normalized `RawFinding` data structures to generate inline comments on pull requests, provide one-click fix suggestions, and integrate with GitHub's status check system to block merges when critical vulnerabilities are detected.\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 项目说明书", "目录", "Introduction to Velonus", "Overview", "Architecture", "Supported Security Tools", "Data Models", "Core Components", "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- 文件总数：93\n- 重要文件覆盖：10/93\n- 证据索引条目：10\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- 共索引 10 条证据。\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- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\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- **Introduction to Velonus**：importance `high`\n - source_paths: README.md, pyproject.toml\n- **Quick Start Guide**：importance `high`\n - source_paths: apps/cli/shield/main.py, apps/cli/shield/commands/scan.py, README.md\n- **System Architecture**：importance `high`\n - source_paths: pyproject.toml, apps/cli/pyproject.toml, apps/api/pyproject.toml, packages/scanner/pyproject.toml\n- **CLI Components**：importance `high`\n - source_paths: apps/cli/shield/main.py, apps/cli/shield/commands/auth.py, apps/cli/shield/commands/config.py, apps/cli/shield/commands/scan.py, apps/cli/shield/commands/pr.py\n- **API Backend**：importance `high`\n - source_paths: apps/api/shield_api/main.py, apps/api/shield_api/middleware/auth.py, apps/api/shield_api/middleware/rate_limit.py, apps/api/shield_api/background/ai_worker.py, apps/api/shield_api/background/scan_worker.py\n- **Scanner Pipeline**：importance `high`\n - source_paths: packages/scanner/scanner/pipeline.py, packages/scanner/detectors/bandit.py, packages/scanner/detectors/semgrep.py, packages/scanner/detectors/pip_audit.py, packages/scanner/detectors/safety.py\n- **Security Detectors**：importance `high`\n - source_paths: packages/scanner/detectors/secrets.py, packages/scanner/detectors/bandit.py, packages/scanner/detectors/semgrep.py, packages/scanner/detectors/pip_audit.py, packages/scanner/detectors/safety.py\n- **Output Formats**：importance `medium`\n - source_paths: apps/cli/shield/formatters/terminal.py, apps/cli/shield/formatters/sarif.py, apps/cli/shield/commands/scan.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 09:28:06 UTC\n\n## 目录\n\n- [Introduction to Velonus](#introduction)\n- [Quick Start Guide](#quick-start)\n- [System Architecture](#architecture-overview)\n- [CLI Components](#cli-components)\n- [API Backend](#api-backend)\n- [Scanner Pipeline](#scanner-pipeline)\n- [Security Detectors](#security-detectors)\n- [Output Formats](#output-formats)\n- [AI Engine](#ai-engine)\n- [GitHub PR Reviewer](#github-pr-reviewer)\n\n\n\n## Introduction to Velonus\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quick-start), [System Architecture](#architecture-overview), [Scanner Pipeline](#scanner-pipeline)\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/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.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/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n- [packages/normalizer/deduplicator.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/deduplicator.py)\n- [packages/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n
\n\n# Introduction to Velonus\n\nVelonus is an open-source security scanner CLI designed to detect secrets, vulnerabilities, and security issues in codebases. It aggregates multiple industry-standard security tools into a unified pipeline with normalized output formats and deduplication logic. Velonus is particularly useful for development teams seeking to integrate security scanning into their CI/CD pipelines and local development workflows.\n\n## Overview\n\nVelonus provides a command-line interface that orchestrates multiple security scanners to analyze source code and dependencies. The tool normalizes findings from different sources into a canonical data model, removes duplicates, and presents results in multiple output formats including terminal, JSON, and SARIF. 资料来源：[README.md]()\n\nThe project is structured as a monorepo with three main packages:\n\n| Package | Location | Purpose |\n|---------|----------|---------|\n| `scanner` | `packages/scanner/` | Security tool wrappers and detectors |\n| `normalizer` | `packages/normalizer/` | Data normalization and deduplication |\n| `cli` (shield) | `apps/cli/shield/` | CLI interface and output formatters |\n\n资料来源：[CONTRIBUTING.md]()\n\n## Architecture\n\n### High-Level Component Architecture\n\n```mermaid\ngraph TD\n User --> CLI[CLI Interface
apps/cli/shield/]\n CLI --> Scanner[Scanner Package
packages/scanner/]\n Scanner --> Secrets[Secrets Detector
trufflehog + entropy]\n Scanner --> Bandit[Bandit Detector
Python security linter]\n Scanner --> Semgrep[Semgrep Detector
Static analysis]\n Scanner --> PipAudit[pip-audit Detector
Dependency vulnerabilities]\n Scanner --> Safety[Safety Detector
Python package safety]\n \n Scanner --> Normalizer[Normalizer Package
packages/normalizer/]\n Normalizer --> Models[NormalizedFinding Model]\n Models --> Deduplicator[Deduplication Filter]\n \n Deduplicator --> Formatters[Output Formatters]\n Formatters --> Terminal[Terminal Formatter
Rich tables]\n Formatters --> JSON[JSON Formatter]\n Formatters --> SARIF[SARIF Formatter
GitHub Code Scanning]\n```\n\n### Scanner Pipeline Flow\n\n```mermaid\ngraph LR\n A[Input Path] --> B[Secrets Scan]\n B --> C[Bandit Scan]\n C --> D[Semgrep Scan]\n D --> E[pip-audit Scan]\n E --> F[Safety Scan]\n F --> G[Normalize]\n G --> H[Deduplicate]\n H --> I[Format Output]\n```\n\n资料来源：[packages/normalizer/deduplicator.py:1-30]()\n\n## Supported Security Tools\n\nVelonus wraps and orchestrates the following security scanners:\n\n### Scanner Comparison Table\n\n| Tool | Purpose | Phase | Status |\n|------|---------|-------|--------|\n| **Secrets** | Hardcoded credential detection via TruffleHog + entropy analysis | Phase 0 | ✅ Complete |\n| **Bandit** | Python-specific security issue detection | Phase 1 | ✅ Complete |\n| **Semgrep** | Multi-language static analysis with custom rules | Phase 1 | ✅ Complete |\n| **pip-audit** | Python dependency vulnerability scanning | Phase 1 | ✅ Complete |\n| **Safety** | Python package security database scanning | Phase 1 | ✅ Complete |\n\n资料来源：[README.md]()\n资料来源：[packages/scanner/scanner/detectors/secrets.py:1-50]()\n\n## Data Models\n\n### NormalizedFinding Schema\n\nThe core data model used throughout Velonus is `NormalizedFinding`, which provides a canonical representation of security findings regardless of their source tool. 资料来源：[packages/normalizer/models.py:1-50]()\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `str` | SHA-256 fingerprint (first 16 hex chars) of `tool+file+line+rule_id` |\n| `tool` | `str` | Source tool: `bandit`, `semgrep`, `secrets`, `pip-audit`, `safety` |\n| `rule_id` | `str` | Tool-specific rule identifier |\n| `cwe` | `list[str]` | CWE identifiers (e.g., `[\"CWE-89\"]`) |\n| `owasp` | `list[str]` | OWASP categories (e.g., `[\"A03:2021\"]`) |\n| `severity` | `Severity` | CRITICAL, HIGH, MEDIUM, LOW, INFO |\n| `confidence` | `Confidence` | HIGH, MEDIUM, LOW |\n| `file` | `str` | File path of the finding |\n| `line_start` | `int` | Starting line number |\n| `line_end` | `int` | Ending line number |\n| `code_snippet` | `str` | Relevant code snippet |\n| `message` | `str` | Human-readable finding message |\n| `fix_available` | `bool` | Whether a fix is available |\n| `suppressed` | `bool` | Whether the finding is suppressed |\n| `first_seen` | `datetime` | Timestamp when first detected |\n\n资料来源：[packages/normalizer/models.py:50-75]()\n\n### Severity Levels\n\n| Badge | Level | Color | Typical Issues |\n|-------|-------|-------|----------------|\n| 🔴 | CRITICAL | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | HIGH | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | MEDIUM | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | LOW | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | INFO | Grey | Style issues, informational notes |\n\n资料来源：[apps/cli/README.md]()\n\n## Core Components\n\n### Scanner Package\n\nThe scanner package (`packages/scanner/`) contains wrappers for each security tool. Each detector implements a common interface and produces `RawFinding` objects that are later normalized.\n\n#### Secrets Detector\n\nThe secrets detector performs two types of secret scanning:\n\n1. **TruffleHog Integration**: Scans for verified and potential secrets using known detector patterns\n2. **Entropy-based Fallback**: Uses Shannon entropy thresholding to detect high-entropy strings in credential assignments\n\n```python\n# Detection logic in secrets.py\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 detected (Shannon entropy={entropy:.2f})\",\n metadata={\"entropy\": round(entropy, 3)},\n )\n )\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:1-60]()\n\n#### pip-audit and Safety Detectors\n\nBoth dependency vulnerability detectors extract CVSS v3 scores and map them to Velonus severity levels:\n\n```python\n# Severity mapping from CVSS score\nif score >= _CVSS_CRITICAL:\n return \"CRITICAL\"\nif score >= _CVSS_HIGH:\n return \"HIGH\"\nif score >= _CVSS_MEDIUM:\n return \"MEDIUM\"\nreturn \"LOW\"\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:1-30]()\n资料来源：[packages/scanner/scanner/detectors/safety.py:1-50]()\n\n### Normalizer Package\n\nThe normalizer package (`packages/normalizer/`) transforms raw findings from various tools into the canonical `NormalizedFinding` format and handles deduplication.\n\n#### Deduplication Strategy\n\nDeduplication uses the deterministic `id` field as the key:\n\n- Findings are processed in pipeline order: `secrets → bandit → semgrep → pip-audit → safety`\n- The **first occurrence** of each `id` is kept (highest-priority tool wins)\n- Subsequent duplicates are discarded at DEBUG level\n\n**Important**: Cross-tool duplicates (e.g., bandit and semgrep flagging the same `eval()` call) are intentionally **not** deduplicated because they have different `id` values (the `id` includes `tool`). This allows the AI layer to analyze each finding independently. 资料来源：[packages/normalizer/deduplicator.py:1-35]()\n\n### CLI Package (Shield)\n\nThe CLI package (`apps/cli/shield/`) provides the user interface, argument parsing, and output formatting.\n\n#### Output Formatters\n\n| Format | Use Case | File |\n|--------|----------|------|\n| `terminal` (default) | Interactive use with colored Rich tables | Rich formatter |\n| `json` | Piping to other tools, storing results | JSON formatter |\n| `sarif` | GitHub Code Scanning, VS Code SARIF Viewer | SARIF formatter |\n\nThe SARIF formatter includes helper functions for URI conversion and rule naming:\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\n \"\"\"Convert rule_id to PascalCase display name for SARIF.\"\"\"\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:1-40]()\n\n## CLI Usage\n\n### Basic Commands\n\n```bash\n# Scan current directory\nvelonus scan ./\n\n# Scan with severity filter\nvelonus scan ./ --severity high\n\n# Output as JSON\nvelonus scan ./ --format json\n\n# Export SARIF for GitHub Security tab\nvelonus scan ./ --format sarif -o results/velonus.sarif\n\n# Show verbose output\nvelonus scan ./ --verbose\n```\n\n### Command Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `PATH` | `.` | Path to scan |\n| `--format`, `-f` | `terminal` | Output format: `terminal`, `json`, `sarif` |\n| `--severity`, `-s` | `info` | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--verbose`, `-v` | off | Show resolved path and extra detail |\n| `-o` | stdout | Output file path |\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH or CRITICAL findings |\n| `1` | Scan completed, one or more HIGH or CRITICAL findings found |\n\nExit code `1` on HIGH/CRITICAL is intentional and enables CI gate functionality. 资料来源：[apps/cli/README.md]()\n\n## CI/CD Integration\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 - 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资料来源：[README.md]()\n\n### Pre-commit Hook\n\n```yaml\n# .pre-commit-config.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## Development Setup\n\n### Requirements\n\n- Python 3.10+ 资料来源：[CONTRIBUTING.md]()\n- [uv](https://docs.astral.sh/uv/) package manager\n\n### Setup Commands\n\n```bash\n# Clone and enter directory\ngit clone https://github.com/AliAmmar15/Velonus\ncd Velonus\n\n# Install all workspace packages and dev dependencies\nuv sync --all-extras --dev\n\n# Activate virtual environment\nsource .venv/bin/activate\n\n# Install packages in editable mode\npip install -e apps/cli\npip install -e packages/scanner\npip install -e packages/normalizer\n\n# Verify installation\nvelonus --help\n```\n\n### Code Quality Standards\n\nAll code must pass the following checks before PR submission:\n\n| Tool | Purpose | Command |\n|------|---------|---------|\n| **ruff** | Linting and formatting | `ruff check . && ruff format .` |\n| **mypy** | Type checking (strict mode) | `mypy apps/cli/shield --strict --ignore-missing-imports` |\n| **pytest** | Unit tests | `pytest apps/cli/tests/` |\n\n资料来源：[CONTRIBUTING.md]()\n\n### PR Guidelines\n\n1. **One feature or fix per PR** — do not bundle unrelated changes\n2. **Tests are required** — every new scanner wrapper, formatter, or utility needs matching unit tests\n3. **Keep it small** — PRs under 400 lines of diff get reviewed faster\n4. **No AI-generated placeholder code** — every function must be functional and tested\n5. **Target `main`** — all PRs merge into main; no long-lived feature branches\n\n## Roadmap\n\n| Phase | Status | Features |\n|-------|--------|----------|\n| Phase 0 — Foundation | ✅ Complete | CLI skeleton, Rich output, `NormalizedFinding` model |\n| Phase 1 — Scanner Pipeline | ✅ Complete | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| Phase 2 — AI Layer | 🔨 Building | AI prioritization, exploitability scoring, fix generation |\n| Phase 3 — GitHub Integration | 🔜 Planned | PR inline review comments, one-click fix suggestions |\n| Phase 4 — Web Dashboard | 🔜 Planned | Web UI, scan history, finding trends |\n\n资料来源：[README.md]()\n\n## Alpha Status\n\nVelonus is currently in **alpha**. The tool is functional and actively used internally, but users should expect rough edges. The development team encourages feedback through GitHub issues. 资料来源：[README.md]()\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to Velonus](#introduction), [CLI Components](#cli-components)\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/shield/commands/scan.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/scan.py)\n- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.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/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n
\n\n# Quick Start Guide\n\n## Overview\n\nThe **Quick Start Guide** provides developers and security teams with the essential steps to install, configure, and run Velonus for security scanning of Python projects. Velonus is a multi-tool security scanner that aggregates findings from Bandit, Semgrep, pip-audit, Safety, and TruffleHog into a unified output with severity-based filtering.\n\nThis guide covers:\n- Installation from source\n- Basic scan execution\n- Output format configuration\n- Severity filtering\n- CI/CD integration patterns\n\n资料来源：[README.md:1-10]()\n\n## Prerequisites\n\n### System Requirements\n\n| Requirement | Version/Notes |\n|-------------|---------------|\n| Python | 3.12+ |\n| pip | Latest recommended |\n| OS | Linux, macOS, Windows (PowerShell) |\n\n### Required Tools for Full Functionality\n\n| Tool | Purpose | Install Command |\n|------|---------|-----------------|\n| semgrep | Static analysis for Python security rules | `pip install semgrep` |\n| Bandit | Python security linter | `pip install bandit` |\n| pip-audit | Dependency vulnerability scanner | `pip install pip-audit` |\n| Safety | Additional dependency checking | `pip install safety` |\n| TruffleHog | Secret detection | `pip install trufflehog` |\n\nVelonus gracefully handles missing tools—scanners skip silently if their dependency is not installed, logging a warning message.\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:1-20]()\n\n## Installation\n\n### From Source\n\nClone the repository and install the CLI package:\n\n```bash\ngit clone https://github.com/AliAmmar15/Velonus.git\ncd Velonus\npip install -e apps/cli\n```\n\n### Verify Installation\n\n```bash\nvelonus --version\n```\n\n资料来源：[apps/cli/README.md:1-30]()\n\n## Basic Usage\n\n### Running Your First Scan\n\nScan the current directory:\n\n```bash\nvelonus scan ./\n```\n\nScan a specific project path:\n\n```bash\nvelonus scan ./my-python-project\n```\n\n### Workflow Overview\n\n```mermaid\ngraph TD\n A[User runs velonus scan] --> B[Resolve target path]\n B --> C[Run secret detection
TruffleHog + entropy scan]\n C --> D[Run Bandit static analysis]\n D --> E[Run Semgrep security rules]\n E --> F[Run pip-audit dependency scan]\n F --> G[Run Safety dependency check]\n G --> H[Normalize all findings]\n H --> I[Filter by severity]\n I --> J[Format output]\n J --> K[Print to terminal
or write to file]\n K --> L[Exit with status code]\n```\n\n资料来源：[apps/cli/shield/commands/scan.py:1-50]()\n\n## Scan Command Options\n\n### Syntax\n\n```\nvelonus scan [PATH] [OPTIONS]\n```\n\n### Options Reference\n\n| Option | Short | Default | Description |\n|--------|-------|---------|-------------|\n| `PATH` | — | `.` | Path to project or file to scan |\n| `--format`, `-f` | — | `terminal` | Output format: `terminal`, `json`, `sarif` |\n| `--severity`, `-s` | — | `info` | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--verbose`, `-v` | — | off | Show resolved target path and extra detail |\n| `--help` | — | — | Show help and exit |\n\n资料来源：[apps/cli/README.md:40-60]()\n\n### Severity Filtering Examples\n\n```bash\n# Show all findings (info and above)\nvelonus scan ./\n\n# Only HIGH and CRITICAL findings\nvelonus scan ./ --severity high\n\n# Only CRITICAL findings\nvelonus scan ./ --severity critical\n```\n\n### Output Format Examples\n\n```bash\n# Default: rich terminal table with colored output\nvelonus scan ./\n\n# JSON output for piping\nvelonus scan ./ --format json\n\n# SARIF output for GitHub Security tab\nvelonus scan ./ --format sarif\n\n# Write SARIF to custom path\nvelonus scan ./ -o results/velonus.sarif\n```\n\n资料来源：[apps/cli/README.md:70-100]()\n\n## Output Formats\n\n### Terminal (Default)\n\nRich table with severity badges, file paths, line numbers, rule IDs, and messages. Optimized for interactive use.\n\n| Badge | Severity | Color | Typical Issues |\n|-------|----------|-------|----------------|\n| 🔴 | CRITICAL | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | HIGH | Orange | SQL injection, command injection |\n| 🟡 | MEDIUM | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | LOW | Blue | Insecure defaults, minor issues |\n| ⚪ | INFO | Grey | Style issues, informational notes |\n\n### JSON\n\nMachine-readable format suitable for piping into other tools:\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n### SARIF\n\nStatic Analysis Results Interchange Format for GitHub Code Scanning and VS Code SARIF Viewer integration:\n\n```bash\nvelonus scan ./ --format sarif\nvelonus scan ./ -o results/scan.sarif\n```\n\n资料来源：[README.md:30-60]()\n\n## Exit Codes\n\n| Code | Meaning | Use Case |\n|------|---------|----------|\n| `0` | Scan completed, no HIGH or CRITICAL findings | CI gate passes |\n| `1` | Scan completed, HIGH or CRITICAL findings found | CI gate blocks merge |\n\nThe exit code behavior is intentional for CI/CD gate integration:\n\n```bash\n# CI will fail if HIGH or CRITICAL findings exist\nvelonus scan ./ --severity high\n```\n\n资料来源：[apps/cli/README.md:100-115]()\n\n## CI/CD Integration\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 found\n```\n\n### Pre-commit Hook\n\nAdd to `.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:60-95]()\n\n## Common Workflows\n\n### Quick Security Audit\n\n```bash\nvelonus scan ./ --severity high\n```\n\n### Comprehensive Scan with Verbose Output\n\n```bash\nvelonus scan ./ --verbose --format json > full-scan.json\n```\n\n### Generate SARIF for GitHub Security Tab\n\n```bash\nvelonus scan ./ --format sarif -o velonus.sarif\n```\n\n### Export Findings as JSON\n\n```bash\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n## Project Status\n\nVelonus follows a phased development approach:\n\n| Phase | Status | Features |\n|-------|--------|----------|\n| Phase 0 | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 | ✅ Done | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| Phase 2 | 🔨 Building | AI context engine (exploitability scoring + fix generation) |\n| Phase 3 | 🔜 Planned | GitHub PR integration (inline fixes, one-click accept) |\n| Phase 4 | 🔜 Planned | Web dashboard |\n\n资料来源：[README.md:100-120]()\n\n## Next Steps\n\n- **Configuration**: Explore `velonus config` for API URL settings (Phase 2)\n- **Authentication**: Set up API authentication with `velonus auth login` (Phase 2)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines\n- **Issues**: Report problems at [github.com/AliAmmar15/Velonus/issues](https://github.com/AliAmmar15/Velonus/issues)\n\nVelonus is in alpha. The core scanning functionality works reliably—use it in CI today with the exit code gate.\n\n资料来源：[README.md:120-130]()\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to Velonus](#introduction), [CLI Components](#cli-components), [API Backend](#api-backend), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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- [README.md](https://github.com/AliAmmar15/Velonus/blob/main/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/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.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/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n
\n\n# System Architecture\n\n## Overview\n\nVelonus is a multi-tool security scanning platform designed to identify vulnerabilities in Python projects through a modular scanner pipeline. The system integrates multiple security tools (TruffleHog, Semgrep, Bandit, pip-audit, Safety) into a unified CLI experience with flexible output formats for both interactive use and CI/CD integration.\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## High-Level Architecture\n\nVelonus follows a layered architecture with clear separation between the CLI interface, scanner core, detectors, and output formatters.\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[velonus CLI]\n Commands[scan / auth / config]\n end\n \n subgraph \"Core Layer\"\n Scanner[Scanner Pipeline]\n Normalizer[Normalizer]\n Formatters[Formatters]\n end\n \n subgraph \"Detector Layer\"\n Secrets[Secrets Detector]\n Semgrep[Semgrep Detector]\n PipAudit[pip-audit Detector]\n Safety[Safety Detector]\n end\n \n subgraph \"External Tools\"\n TH[TruffleHog]\n SG[Semgrep Binary]\n PA[pip-audit]\n SF[safety]\n end\n \n CLI --> Commands\n Commands --> Scanner\n Scanner --> Normalizer\n Scanner --> Detectors\n Detectors --> TH\n Detectors --> SG\n Detectors --> PA\n Detectors --> SF\n Normalizer --> Formatters\n Formatters --> Output[terminal / json / sarif]\n```\n\n## Project Structure\n\nThe repository is organized as a monorepo with separate packages and applications.\n\n| Component | Path | Purpose |\n|-----------|------|---------|\n| CLI Application | `apps/cli/` | Command-line interface entry point |\n| API Application | `apps/api/` | Backend API (Phase 2) |\n| Scanner Package | `packages/scanner/` | Core scanner pipeline and detectors |\n| Normalizer Package | `packages/normalizer/` | Finding normalization |\n\n资料来源：[CONTRIBUTING.md:6-8](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n## Scanner Pipeline\n\n### Pipeline Architecture\n\nThe scanner pipeline orchestrates multiple security tools and aggregates their findings into a unified format.\n\n```mermaid\ngraph LR\n Input[Target Path] --> Resolve[Path Resolution]\n Resolve --> SD[Secrets Detection]\n Resolve --> SEM[Semgrep Scan]\n Resolve --> PA[pip-audit]\n Resolve --> SF[Safety Scan]\n SD --> RF1[RawFinding]\n SEM --> RF2[RawFinding]\n PA --> RF3[RawFinding]\n SF --> RF4[RawFinding]\n RF1 --> Aggregate[Aggregate Findings]\n RF2 --> Aggregate\n RF3 --> Aggregate\n RF4 --> Aggregate\n Aggregate --> Normalize[Normalize to NormalizedFinding]\n Normalize --> Format[Format Output]\n```\n\n### Core Components\n\n#### RawFinding Data Model\n\nAll detectors produce `RawFinding` objects as the initial representation of a security finding:\n\n```python\nRawFinding(\n tool=\"pip-audit\", # Source tool identifier\n rule_id=\"CVE-2023-12345\", # Vulnerability identifier\n file=\"requirements.txt\", # Affected file path\n line=0, # Line number (0 for dep issues)\n severity=\"HIGH\", # CRITICAL/HIGH/MEDIUM/LOW/INFO\n message=\"...\", # Human-readable message\n code_snippet=\"...\", # Relevant code context\n metadata={ # Tool-specific metadata\n \"package_name\": \"requests\",\n \"package_version\": \"2.28.0\",\n \"cvss_score\": 7.5,\n \"fix_available\": True\n }\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:49-61](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n\n#### NormalizedFinding\n\nThe normalizer transforms `RawFinding` objects into a standardized `NormalizedFinding` format for consistent output across all tools.\n\n### Detector Interface\n\nAll detectors implement a common interface:\n\n| Method | Purpose |\n|--------|---------|\n| `scan(target: Path) -> list[RawFinding]` | Execute scan and return findings |\n\n## Security Detectors\n\n### Secrets Detector\n\nThe secrets detector identifies hardcoded credentials and sensitive information using two complementary approaches:\n\n#### TruffleHog Integration\n\nPrimary detection method that leverages TruffleHog's extensive secret detection rules.\n\n```python\nRawFinding(\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=f\"{'Verified' if verified else 'Potential'} secret detected [{detector_name}]\",\n metadata={\n \"detector\": detector_name,\n \"verified\": verified,\n \"decoder\": decoder_name\n }\n)\n```\n\n资料来源：[packages/scanner/detectors/secrets.py:45-57](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.py)\n\n#### Entropy-Based Fallback\n\nWhen TruffleHog is unavailable, a Shannon entropy-based scanner detects high-entropy strings in credential assignments.\n\n| Parameter | Value | Description |\n|-----------|-------|-------------|\n| Entropy Threshold | 4.5 | Minimum Shannon entropy to flag |\n| Skipped Dirs | `.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build` | Directories excluded from scanning |\n\n```python\nRawFinding(\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 metadata={\"entropy\": round(entropy, 3)}\n)\n```\n\n资料来源：[packages/scanner/detectors/secrets.py:78-91](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.py)\n\n### Semgrep Detector\n\nRuns Semgrep with the `p/python` ruleset for Python-specific security analysis.\n\n```mermaid\ngraph TD\n Check[Check semgrep availability] -->|found| Run[Run semgrep scan]\n Check -->|not found| Skip[Return empty list + warning]\n Run --> Parse[Parse JSON output]\n Parse --> Extract[Extract CWE/OWASP metadata]\n Extract --> Create[Create RawFinding objects]\n```\n\n**Configuration:**\n- Ruleset: `p/python`\n- Flags: `--json --quiet --metrics=off`\n- Exit code 1: Findings present (not an error)\n- Exit code 2+: Real error\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:35-55](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n\n**Metadata Extraction:**\n\n| Metadata Field | Extraction Method |\n|---------------|-------------------|\n| CWE | Regex extraction from `extra.metadata.cwe` |\n| OWASP | List deduplication from `extra.metadata.owasp` |\n\n### pip-audit Detector\n\nScans Python dependencies for known vulnerabilities using `pip-audit`.\n\n**Finding Structure:**\n```python\nRawFinding(\n tool=\"pip-audit\",\n rule_id=vuln_id,\n file=attribution_path,\n line=0, # Dependency vulnerabilities are file-level\n severity=severity,\n metadata={\n \"package_name\": package_name,\n \"package_version\": package_version,\n \"aliases\": aliases,\n \"fix_versions\": fix_versions,\n \"cvss_score\": cvss_score,\n \"cwe\": _CWE,\n \"owasp\": _OWASP,\n \"fix_available\": bool(fix_versions)\n }\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:49-61](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n\n**CVSS to Severity Mapping:**\n\n| CVSS Score Range | Severity |\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.0 | INFO |\n\n### Safety Detector\n\nHandles both Safety v1 and v2 output formats for Python vulnerability scanning.\n\n**Supported Formats:**\n\n| Format | Source | Structure |\n|--------|--------|-----------|\n| Format A (v2) | `safety >= 2.0` | Dict with `vulnerabilities` list |\n| Format B (v1) | `safety < 2.0` | List of 5-element lists |\n\n**Vulnerability Entry Parsing:**\n\n```python\n# Required fields for v2\nvuln_id: str = str(entry[\"vulnerability_id\"])\npackage_name: str = str(entry[\"package_name\"])\ninstalled_version: str = str(entry[\"analyzed_version\"])\n\n# Optional fields\nadvisory: str = str(entry.get(\"advisory\", \"\"))\ncve: str = str(entry.get(\"CVE\", \"\"))\nfix_versions: list[str] = [str(v) for v in entry.get(\"fixed_versions\", [])]\n```\n\n资料来源：[packages/scanner/scanner/detectors/safety.py:50-65](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n\n## CLI Architecture\n\n### Command Structure\n\n```\nvelonus [OPTIONS] COMMAND [ARGS]...\n```\n\n| Command | Description | Phase |\n|---------|-------------|-------|\n| `scan` | Run security scanner pipeline | Phase 0 |\n| `auth` | Manage API authentication | Phase 2 |\n| `config` | Manage local configuration | Phase 2 |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n### Scan Command Interface\n\n```bash\nvelonus scan [PATH] [OPTIONS]\n```\n\n| Argument/Option | Default | Description |\n|-----------------|---------|-------------|\n| `PATH` | `.` | Target project path |\n| `--format`, `-f` | `terminal` | Output format |\n| `--severity`, `-s` | `info` | Minimum severity filter |\n| `--verbose`, `-v` | off | Show detailed output |\n\n**Exit Codes:**\n\n| Code | Meaning |\n|------|---------|\n| 0 | Scan completed, no HIGH/CRITICAL findings |\n| 1 | Scan completed, HIGH or CRITICAL findings found |\n\n## Output Formatters\n\n### Terminal Formatter\n\nRich-formatted table with colored severity badges:\n\n```\n┏━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ Rule ┃ Message ┃\n┡━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩\n│ 🔴 CRITICAL │ secrets │ aws-access-key │ Hardcoded │\n│ 🟠 HIGH │ bandit │ B413 │ Blacklist │\n```\n\n### JSON Formatter\n\nStructured JSON output for piping and tooling:\n\n```json\n{\n \"findings\": [\n {\n \"severity\": \"CRITICAL\",\n \"tool\": \"secrets\",\n \"rule_id\": \"trufflehog-aws-access-key\",\n \"file\": \"config.py\",\n \"line\": 42,\n \"message\": \"Verified secret detected [AWS Access Key]\"\n }\n ]\n}\n```\n\n### SARIF Formatter\n\nStatic Analysis Results Interchange Format for GitHub Code Scanning integration.\n\n**Key SARIF Elements:**\n\n| Element | Purpose |\n|---------|---------|\n| `runs[].results[]` | Individual findings |\n| `runs[].tool.driver.rules[]` | Rule definitions |\n| `runs[].artifacts` | Scanned files |\n| `runs[].logicalLocations` | Code structure |\n\n**Rule ID Transformation:**\n```\nsecrets/aws-access-key-id → AwsAccessKeyId\ngeneric-api-key → GenericApiKey\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:40-58](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n\n## Severity Classification\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | CRITICAL | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | HIGH | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | MEDIUM | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | LOW | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | INFO | Grey | Style issues, informational notes |\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## Development Standards\n\n### Code Quality Requirements\n\nAll code must pass:\n\n| Tool | Purpose | Command |\n|------|---------|---------|\n| ruff | Linting & formatting | `ruff check . && ruff format --check .` |\n| mypy | Type checking (strict) | `mypy --strict --ignore-missing-imports` |\n\n**Strict Requirements:**\n- Zero mypy errors in strict mode\n- No `type: ignore` without explanation comment\n- All functions must be functional and tested\n- No AI-generated placeholder code\n\n资料来源：[CONTRIBUTING.md:32-44](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n### PR Guidelines\n\n| Rule | Description |\n|------|-------------|\n| One feature per PR | No bundling unrelated changes |\n| Tests required | Every new scanner wrapper needs unit tests |\n| Small diffs | Target under 400 lines for faster review |\n| Target main | No long-lived feature branches |\n\n## Roadmap\n\n| Phase | Status | Deliverables |\n|-------|--------|--------------|\n| Phase 0 | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 | ✅ Done | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| Phase 2 | 🔨 Building | AI prioritization, exploitability scoring, fix generation |\n| Phase 3 | 🔜 Planned | PR inline review comments, one-click fix suggestions |\n| Phase 4 | 🔜 Planned | Web UI, scan history, finding trends |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## CI/CD Integration\n\n### GitHub Actions Workflow\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资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n---\n\n\n\n## CLI Components\n\n### 相关页面\n\n相关主题：[Scanner Pipeline](#scanner-pipeline), [API Backend](#api-backend), [Output Formats](#output-formats)\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/shield/commands/scan.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/scan.py)\n- [apps/cli/shield/commands/auth.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/auth.py)\n- [apps/cli/shield/commands/config.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/config.py)\n- [apps/cli/shield/commands/pr.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/pr.py)\n- [apps/cli/shield/formatters/terminal.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/terminal.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n- [apps/cli/shield/core/api_client.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/api_client.py)\n
\n\n# CLI Components\n\n## Overview\n\nThe Velonus CLI is a Typer-based command-line application that provides a unified interface for running security scans on local codebases. The CLI operates in **local-only mode** without requiring an API connection, making it immediately usable for developers and CI/CD pipelines.\n\nThe CLI is structured around command groups that delegate to specialized modules for scanning, authentication, configuration, and PR integration.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[\"velonus (main.py)\"] --> B[\"scan.app\"]\n A --> C[\"auth.app\"]\n A --> D[\"config.app\"]\n A --> E[\"pr.app\"]\n \n B --> F[\"scanner pipeline\"]\n B --> G[\"formatters\"]\n \n G --> H[\"terminal.py\"]\n G --> I[\"sarif.py\"]\n G --> J[\"json.py\"]\n \n C --> K[\"api_client.py\"]\n D --> L[\"config storage\"]\n \n F --> M[\"NormalizedFinding\"]\n M --> G\n```\n\n## Command Groups\n\n### Root Application\n\nThe root Typer application is defined in `apps/cli/shield/main.py` and registers all command subgroups:\n\n```python\napp = typer.Typer(\n name=\"velonus\",\n help=\"[bold green]Velonus[/bold green] — AI-native AppSec scanner for developers.\",\n rich_markup_mode=\"rich\",\n no_args_is_help=True,\n pretty_exceptions_enable=True,\n pretty_exceptions_show_locals=False,\n)\n```\n\n资料来源：[apps/cli/shield/main.py:17-22]()\n\n| Property | Value | Purpose |\n|----------|-------|---------|\n| `name` | `velonus` | CLI command name |\n| `rich_markup_mode` | `rich` | Enable Rich markup for colored output |\n| `no_args_is_help` | `True` | Show help when no arguments provided |\n| `pretty_exceptions_enable` | `True` | Enhanced error tracebacks |\n\n### Command Registration\n\n| Command | Module | Phase | Description |\n|---------|--------|-------|-------------|\n| `velonus scan` | `shield.commands.scan` | Phase 0 | Run security scans on local paths |\n| `velonus auth` | `shield.commands.auth` | Phase 2 | Authenticate with Velonus API |\n| `velonus config` | `shield.commands.config` | Phase 2 | Manage local CLI configuration |\n| `velonus pr` | `shield.commands.pr` | Phase 3 | GitHub PR integration utilities |\n\n资料来源：[apps/cli/shield/main.py:29-32]()\n\n## The `scan` Command\n\nThe `scan` command is the primary interface for running security analysis on local codebases.\n\n### Command Interface\n\n```bash\nvelonus scan [PATH] [OPTIONS]\n```\n\n| Argument/Option | Default | Type | Description |\n|-----------------|---------|------|-------------|\n| `PATH` | `.` | Path | Project or file to scan |\n| `--format`, `-f` | `terminal` | Choice | Output format: `terminal`, `json`, `sarif` |\n| `--severity`, `-s` | `info` | Choice | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--verbose`, `-v` | `off` | Flag | Show resolved target path and extra detail |\n| `--output`, `-o` | stdout | Path | Write output to file (SARIF/JSON) |\n\n资料来源：[apps/cli/shield/commands/scan.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/commands/scan.py)\n\n### Severity Levels\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | `CRITICAL` | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | `HIGH` | Orange | SQL injection, command injection |\n| 🟡 | `MEDIUM` | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | `LOW` | Blue | Insecure defaults, minor misconfigs |\n| ⚪ | `INFO` | Grey | Style issues, informational notes |\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH/CRITICAL findings |\n| `1` | Scan completed with HIGH or CRITICAL findings (blocks CI) |\n\n## Output Formatters\n\nThe CLI supports multiple output formats through a pluggable formatter system.\n\n```mermaid\ngraph LR\n A[\"NormalizedFinding\"] --> B[\"Formatter Interface\"]\n B --> C[\"TerminalFormatter\"]\n B --> D[\"SarifFormatter\"]\n B --> E[\"JsonFormatter\"]\n```\n\n### Terminal Formatter\n\nRenders findings as colored Rich tables with severity badges, file paths, line numbers, rule IDs, and human-readable messages. This is the default format for interactive use.\n\n**Output Structure:**\n```\n┏━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓\n┃ Severity ┃ Tool ┃ File ┃ Line ┃ Rule ┃ Message ┃\n┡━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩\n```\n\n### SARIF Formatter\n\nGenerates Static Analysis Results Interchange Format output compatible with GitHub Code Scanning, VS Code SARIF Viewer, and other SAST tooling.\n\n**Key transformations:**\n- Converts rule IDs to PascalCase display names via `_rule_id_to_name()`\n- Generates `file://` URIs for directory paths with trailing slashes per SARIF spec §3.14.14\n\n```python\ndef _rule_id_to_name(rule_id: str) -> str:\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:58-68]()\n\n### JSON Formatter\n\nOutputs findings as structured JSON for piping into other tools or storing results:\n\n```bash\nvelonus scan ./ --format json | python -m json.tool\nvelonus scan ./ --format json > scan-results.json\n```\n\n## Authentication Module\n\nThe `auth` command manages authentication with the Velonus API backend.\n\n| Command | Description | Phase |\n|---------|-------------|-------|\n| `velonus auth login` | Authenticate via Clerk (browser OAuth flow) | Phase 2 |\n| `velonus auth logout` | Clear stored credentials | Phase 2 |\n| `velonus auth status` | Show current authentication status | Phase 2 |\n\n> These commands are stubbed in Phase 0 and become functional in Phase 2 when the API backend is live.\n\n## Configuration Module\n\nThe `config` command manages local CLI settings stored on disk.\n\n| Command | Description |\n|---------|-------------|\n| `velonus config show` | Print current configuration |\n| `velonus config set ` | Set a configuration value |\n\n**Example configuration:**\n```bash\nvelonus config set api_url https://api.velonus.dev\n```\n\n> Stubbed in Phase 0, fully functional in Phase 2.\n\n## PR Integration Module\n\nThe `pr` command provides GitHub PR integration utilities for Phase 3. This module is planned but not yet implemented in Phase 0.\n\n## Core API Client\n\nThe `api_client` module in `shield/core/` handles communication with the Velonus backend API. It is used by the auth and config modules when API connectivity is required.\n\n资料来源：[apps/cli/shield/core/api_client.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/api_client.py)\n\n## Module Structure\n\n```\napps/cli/shield/\n├── main.py # Root Typer application\n├── commands/\n│ ├── __init__.py\n│ ├── scan.py # Security scan command\n│ ├── auth.py # Authentication commands\n│ ├── config.py # Configuration commands\n│ └── pr.py # PR integration (Phase 3)\n├── formatters/\n│ ├── __init__.py\n│ ├── terminal.py # Rich table output\n│ ├── sarif.py # SARIF format output\n│ └── json.py # JSON output\n└── core/\n ├── __init__.py\n └── api_client.py # Backend API communication\n```\n\n## CLI Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as velonus scan\n participant Scanner as scanner.pipeline\n participant Formatter\n participant Output\n\n User->>CLI: velonus scan ./ --severity high\n CLI->>Scanner: Run detectors (secrets, bandit, semgrep, etc.)\n Scanner-->>CLI: List[NormalizedFinding]\n CLI->>Formatter: Format findings based on --format\n Formatter-->>Output: Rendered output (terminal/JSON/SARIF)\n Output-->>User: Display or write to file\n \n alt HIGH/CRITICAL findings\n CLI-->>User: Exit code 1 (CI block)\n else Clean scan\n CLI-->>User: Exit code 0\n end\n```\n\n## Usage Examples\n\n### Basic Scan\n\n```bash\nvelonus scan ./\n```\n\n### Severity Filtered Scan\n\n```bash\nvelonus scan ./ --severity high\n```\n\n### Export to SARIF\n\n```bash\nvelonus scan ./ -o results/velonus.sarif --format sarif\n```\n\n### Verbose Output\n\n```bash\nvelonus scan ./ --verbose\n```\n\n### CI/CD Integration\n\n```yaml\n- name: Velonus security scan\n run: velonus scan . --severity high\n```\n\n## Development Guidelines\n\nPer the project's contribution guidelines:\n\n| Requirement | Tool | Command |\n|-------------|------|---------|\n| Linting | Ruff | `ruff check .` |\n| Formatting | Ruff | `ruff format .` |\n| Type Checking | mypy | `mypy apps/cli/shield --strict --ignore-missing-imports` |\n| Testing | pytest | `pytest apps/cli/tests/` |\n\nAll new CLI components must include matching unit tests. The test suite currently has **367 tests** covering scanner wrappers and formatters.\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## API Backend\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture-overview), [Scanner Pipeline](#scanner-pipeline), [AI Engine](#ai-engine), [GitHub PR Reviewer](#github-pr-reviewer)\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/shield/core/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/__init__.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.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- [packages/scanner/scanner/detectors/safety.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/safety.py)\n- [packages/scanner/scanner/detectors/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\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
\n\n# API Backend\n\n## Overview\n\nThe Velonus API Backend is a FastAPI-based service layer that provides remote scanning capabilities, AI-powered analysis, GitHub integration, and programmatic access to security findings. Currently planned for **Phase 2** of the Velonus roadmap, the API backend will extend the CLI's local-only scanning with cloud-native features including authentication, rate limiting, background processing, and AI-driven remediation suggestions.\n\n**Current Status:** The API backend is in the planning/stub phase. The CLI is fully functional in local-only mode. Auth, config, and GitHub integration commands are stubbed and will be activated once the backend is live. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n Client[\"Client
(CLI / Web UI)\"] --> |\"HTTP/REST\"| API[\"API Gateway
(FastAPI)\"]\n \n API --> |\"Auth\"| AuthMW[\"Auth Middleware
(Clerk OAuth)\"]\n API --> |\"Rate Limit\"| RateMW[\"Rate Limit Middleware\"]\n \n AuthMW --> |\"Validated\"| Routers[\"Routers\"]\n RateMW --> |\"Allowed\"| Routers\n \n Routers --> Scans[\"/scans\"]\n Routers --> Findings[\"/findings\"]\n Routers --> GitHub[\"/github\"]\n Routers --> Remediation[\"/remediation\"]\n \n Scans --> ScanSvc[\"Scan Service\"]\n Findings --> ScanSvc\n GitHub --> GitHubSvc[\"GitHub Service\"]\n Remediation --> AISvc[\"AI Service\"]\n \n ScanSvc --> ScanWorker[\"Scan Worker
(Background)\"]\n AISvc --> AIWorker[\"AI Worker
(Background)\"]\n \n ScanWorker --> |\"Results\"| DB[\"Database\"]\n AIWorker --> |\"Analysis\"| DB\n \n DB --> Findings\n```\n\n## Planned Components\n\n### Directory Structure\n\n```\napps/api/shield_api/\n├── main.py # FastAPI application entry point\n├── middleware/\n│ ├── auth.py # Clerk OAuth authentication\n│ └── rate_limit.py # Request rate limiting\n├── routers/\n│ ├── scans.py # Scan management endpoints\n│ ├── findings.py # Finding retrieval endpoints\n│ ├── github.py # GitHub integration endpoints\n│ └── remediation.py # AI remediation endpoints\n├── services/\n│ ├── scan_service.py # Scan orchestration logic\n│ ├── ai_service.py # AI analysis and scoring\n│ └── github_service.py # GitHub API integration\n└── background/\n ├── scan_worker.py # Background scan processor\n └── ai_worker.py # Background AI worker\n```\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Middleware Layer\n\n### Authentication Middleware\n\nThe authentication middleware integrates with **Clerk** for browser-based OAuth authentication. This enables secure API access for authenticated users while maintaining compatibility with the CLI's local-only mode.\n\n| Feature | Description |\n|---------|-------------|\n| Provider | Clerk (OAuth 2.0) |\n| Token Type | Bearer JWT |\n| Protected Routes | All `/scans`, `/findings`, `/github`, `/remediation` endpoints |\n| CLI Bypass | Local scans work without authentication |\n\nThe `velonus auth` command group will provide login/logout/status operations once the backend is live. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n### Rate Limiting Middleware\n\nRate limiting protects the API from abuse and ensures fair resource allocation across users.\n\n| Tier | Limit | Purpose |\n|------|-------|---------|\n| Anonymous | TBD | Limited scans per hour |\n| Authenticated | TBD | Higher quotas for logged-in users |\n| Enterprise | TBD | Custom limits based on subscription |\n\n## Router Modules\n\n### `/scans` - Scan Management\n\nManages scan lifecycle including creation, status tracking, and result retrieval.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/scans` | POST | Create a new scan job |\n| `/scans/{id}` | GET | Get scan status and metadata |\n| `/scans/{id}/results` | GET | Retrieve scan results |\n| `/scans/{id}/cancel` | POST | Cancel a running scan |\n\n#### Request/Response Model\n\n```json\n{\n \"id\": \"uuid\",\n \"status\": \"pending|running|completed|failed\",\n \"target_path\": \"/path/to/project\",\n \"created_at\": \"ISO8601 timestamp\",\n \"completed_at\": \"ISO8601 timestamp|null\",\n \"tools_run\": [\"secrets\", \"bandit\", \"semgrep\", \"pip-audit\", \"safety\"],\n \"findings_count\": {\n \"critical\": 0,\n \"high\": 0,\n \"medium\": 0,\n \"low\": 0,\n \"info\": 0\n }\n}\n```\n\n### `/findings` - Finding Retrieval\n\nProvides filtered access to security findings from completed scans.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/findings` | GET | List findings with filters |\n| `/findings/{id}` | GET | Get single finding details |\n| `/findings/{id}/acknowledge` | POST | Mark finding as acknowledged |\n\n#### Query Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `scan_id` | UUID | Filter by scan |\n| `severity` | string | `critical`, `high`, `medium`, `low`, `info` |\n| `tool` | string | `secrets`, `bandit`, `semgrep`, `pip-audit`, `safety` |\n| `cwe` | string | Filter by CWE identifier |\n| `owasp` | string | Filter by OWASP category |\n| `page` | int | Pagination page number |\n| `limit` | int | Results per page (max 100) |\n\n### `/github` - GitHub Integration\n\nEnables GitHub Actions integration and PR inline comments for Phase 3.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/github/webhook` | POST | Receive GitHub webhook events |\n| `/github/install` | POST | Install GitHub App |\n| `/github/scan` | POST | Trigger scan from PR |\n| `/github/comments` | POST | Post inline review comments |\n\nThis router integrates with the GitHub Service for repository access and comment posting. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n### `/remediation` - AI-Powered Fixes\n\nProvides AI-generated fix suggestions for security findings.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/remediation/{finding_id}` | GET | Get AI fix suggestion |\n| `/remediation/{finding_id}/apply` | POST | Apply fix to codebase |\n| `/remediation/pr` | POST | Create PR with fixes |\n\nPhase 2 features include AI prioritization and exploitability scoring. Phase 3 adds one-click fix suggestions. 资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## Service Layer\n\n### Scan Service\n\nOrchestrates the security scanning pipeline across multiple tools:\n\n| Tool | Purpose | Finding Type |\n|------|---------|--------------|\n| **Secrets** | TruffleHog-based secret detection | Hardcoded credentials, API keys |\n| **Bandit** | Python static analysis | Security bugs, common vulnerabilities |\n| **Semgrep** | Rule-based pattern matching | Custom security rules, CWE coverage |\n| **pip-audit** | Dependency vulnerability scanning | Known CVEs in Python packages |\n| **Safety** | Python dependency security | Vulnerable package versions |\n\nThe service normalizes findings into the `NormalizedFinding` model before storage. 资料来源：[packages/scanner/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/secrets.py)\n\n### AI Service\n\nProvides AI-powered analysis capabilities for Phase 2:\n\n| Feature | Description |\n|---------|-------------|\n| Exploitability Scoring | Assess if a vulnerability is actually exploitable in context |\n| Fix Generation | Generate code patches for identified issues |\n| False Positive Detection | Reduce noise by validating findings |\n| Prioritization | Rank findings by real-world impact |\n\n### GitHub Service\n\nHandles GitHub API interactions:\n\n| Feature | Description |\n|---------|-------------|\n| Repository Access | Read code from GitHub repos |\n| Comment Posting | Post inline PR comments with findings |\n| Status Checks | Update commit status for CI/CD gates |\n| Webhook Handling | Process GitHub webhook events |\n\n## Background Workers\n\n### Scan Worker\n\nProcesses scan jobs asynchronously to avoid blocking HTTP requests.\n\n```mermaid\ngraph LR\n A[Scan Request] --> B[Queue]\n B --> C[Worker Pool]\n C --> D[Tool 1: Secrets]\n C --> E[Tool 2: Bandit]\n C --> F[Tool 3: Semgrep]\n C --> G[Tool 4: pip-audit]\n C --> H[Tool 5: Safety]\n D & E & F & G & H --> I[Normalize]\n I --> J[Store Results]\n```\n\n### AI Worker\n\nProcesses AI analysis requests in the background:\n\n| Task | Description |\n|------|-------------|\n| Batch Analysis | Analyze multiple findings together |\n| Fix Generation | Generate remediation code |\n| Score Updates | Recalculate exploitability scores |\n\n## Data Models\n\n### NormalizedFinding\n\nAll scanners output findings in a standardized format:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `tool` | string | Source scanner name |\n| `rule_id` | string | Rule identifier (e.g., CWE-78) |\n| `file` | string | File path with finding |\n| `line` | int | Line number (0 for dependencies) |\n| `severity` | enum | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO` |\n| `message` | string | Human-readable description |\n| `code_snippet` | string | Relevant source code (if applicable) |\n| `metadata` | dict | Scanner-specific data (CVE, CVSS, fix versions) |\n\n#### Metadata Schema\n\n| Key | Tool | Description |\n|-----|------|-------------|\n| `cwe` | semgrep, bandit | CWE identifier(s) |\n| `owasp` | semgrep | OWASP category code |\n| `cvss_score` | pip-audit, safety | CVSS v3 base score |\n| `package_name` | pip-audit, safety | Vulnerable package name |\n| `fix_versions` | pip-audit, safety | Safe package versions |\n| `detector` | secrets | Secret detector name |\n| `verified` | secrets | Whether secret was verified |\n| `confidence` | semgrep | Rule confidence level |\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n\n## Output Formats\n\nThe API supports multiple output formats for findings:\n\n| Format | Use Case | Phase |\n|--------|----------|-------|\n| `terminal` | Interactive CLI output | Phase 0 |\n| `json` | Piping, tooling integration | Phase 0 |\n| `sarif` | GitHub Code Scanning, VS Code | Phase 1 |\n\n### SARIF Output\n\nSARIF (Static Analysis Results Interchange Format) provides standardized output for integration with security tooling:\n\n```json\n{\n \"version\": \"2.1.0\",\n \"$schema\": \"https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json\",\n \"runs\": [{\n \"tool\": {\n \"driver\": {\n \"name\": \"Velonus\",\n \"version\": \"0.1.0\"\n }\n },\n \"results\": [...]\n }]\n}\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n\n## Severity Levels\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | `CRITICAL` | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | `HIGH` | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | `MEDIUM` | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | `LOW` | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | `INFO` | Grey | Style issues, informational notes |\n\n## Roadmap Integration\n\n| Phase | Status | API Features |\n|-------|--------|--------------|\n| **Phase 0** | ✅ Complete | CLI skeleton, local scanning |\n| **Phase 1** | ✅ Complete | Scanner pipeline, SARIF output |\n| **Phase 2** | 🔨 Building | AI layer, API backend, authentication |\n| **Phase 3** | 🔜 Planned | GitHub PR integration, inline fixes |\n| **Phase 4** | 🔜 Planned | Web dashboard, scan history |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## CLI vs API Mode\n\n| Aspect | Local CLI | API Backend |\n|--------|-----------|-------------|\n| Authentication | Not required | Clerk OAuth required |\n| Rate Limiting | None | Enforced per user |\n| Scan Execution | Synchronous | Background workers |\n| Results Storage | stdout only | Database |\n| GitHub Integration | None | PR comments, status checks |\n| AI Features | None | Fix generation, scoring |\n\nWhen the API backend is live, users can choose between:\n\n```bash\n# Local mode (always works)\nvelonus scan ./my-project\n\n# Cloud mode (requires auth)\nvelonus auth login\nvelonus scan ./my-project --remote\n```\n\n## Configuration\n\n### CLI Configuration\n\nThe `velonus config` command manages local CLI settings:\n\n| Command | Description |\n|---------|-------------|\n| `velonus config show` | Print current configuration |\n| `velonus config set api_url ` | Set API endpoint |\n| `velonus config set api_key ` | Set API authentication key |\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `VELONUS_API_URL` | API backend URL | `https://api.velonus.dev` |\n| `VELONUS_API_KEY` | Authentication key | None |\n| `VELONUS_TIMEOUT` | Scan timeout in seconds | 300 |\n\n## Error Handling\n\n| HTTP Code | Meaning |\n|-----------|---------|\n| `200` | Success |\n| `400` | Invalid request parameters |\n| `401` | Not authenticated |\n| `403` | Forbidden (insufficient permissions) |\n| `404` | Resource not found |\n| `429` | Rate limit exceeded |\n| `500` | Internal server error |\n| `503` | Service unavailable (maintenance) |\n\nCLI exit codes:\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH/CRITICAL findings |\n| `1` | Scan completed, HIGH/CRITICAL findings found |\n\n## Development Guidelines\n\nThe API backend follows the project's contribution standards:\n\n- All code must pass `ruff check` and `ruff format --check`\n- Type checking with `mypy --strict --ignore-missing-imports`\n- Unit tests required for all new endpoints and services\n- PRs should be under 400 lines of diff\n- No AI-generated placeholder code\n\n资料来源：[CONTRIBUTING.md](https://github.com/AliAmmar15/Velonus/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## Scanner Pipeline\n\n### 相关页面\n\n相关主题：[Security Detectors](#security-detectors), [Output Formats](#output-formats), [API Backend](#api-backend)\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/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/normalizer/models.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/normalizer/models.py)\n
\n\n# Scanner Pipeline\n\n## Overview\n\nThe Scanner Pipeline is the core orchestration layer in Velonus that coordinates multiple security scanning tools into a unified, concurrent execution framework. It provides a single entry point for running comprehensive security analysis across Python codebases, combining static analysis, secret detection, and dependency vulnerability scanning.\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:1-15]()\n\n## Architecture\n\nThe pipeline follows a parallel execution model using Python's `asyncio` framework. Each security tool runs concurrently, with results collected, normalized, and deduplicated before presentation.\n\n```mermaid\ngraph TD\n A[User Input: Target Path] --> B[ScanPipeline.run]\n B --> C{Is Async Context?}\n C -->|Yes| D[Direct await]\n C -->|No| E[asyncio.run wrapper]\n D --> F[Parallel Scanner Execution]\n E --> F\n F --> G[Secrets Detector]\n F --> H[Bandit Detector]\n F --> I[Semgrep Detector]\n F --> J[pip-audit Detector]\n F --> K[Safety Detector]\n G --> L[RawFinding List]\n H --> L\n I --> L\n J --> L\n K --> L\n L --> M[FindingNormalizer]\n M --> N[DeduplicationFilter]\n N --> O[NormalizedFinding List]\n O --> P[Output Formatters]\n P --> Q[Terminal / JSON / SARIF]\n```\n\n## Pipeline Execution Model\n\n### Concurrent Execution\n\nThe pipeline executes all five detectors in parallel using `asyncio.gather()`. This approach minimizes total scan time by running independent security checks simultaneously rather than sequentially.\n\n```python\nresults: list[list[RawFinding]] = await asyncio.gather(\n self._run_detector(secrets_runner, target, verbose),\n self._run_detector(bandit_runner, target, verbose),\n self._run_detector(semgrep_runner, target, verbose),\n self._run_detector(pip_audit_runner, target, verbose),\n self._run_detector(safety_runner, target, verbose),\n)\n```\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:80-90]()\n\n### Execution Order\n\nDetectors are executed in a fixed order for consistent logging output:\n\n| Order | Tool | Purpose |\n|-------|------|---------|\n| 0 | secrets | Hardcoded secrets and high-entropy strings |\n| 1 | bandit | Python security best practices |\n| 2 | semgrep | Custom ruleset scanning |\n| 3 | pip-audit | Python dependency vulnerabilities |\n| 4 | safety | Additional dependency checking |\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:69-70]()\n\n### Dual Context Support\n\nThe pipeline supports both async and sync usage patterns:\n\n```python\n# Async context (e.g., API background worker)\npipeline = ScanPipeline()\nfindings = await pipeline.run(Path(\"./my-project\"), verbose=True)\n\n# Sync context (CLI)\nimport asyncio\nfindings = asyncio.run(ScanPipeline().run(Path(\"./my-project\")))\n```\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:14-25]()\n\n## Supported Detectors\n\n### Secrets Detector\n\nThe secrets detector provides dual-layer secret detection:\n\n#### TruffleHog Integration\n\nTruffleHog is the primary secret scanner. It uses commit history analysis and regex-based detector rules to identify verified secrets with high confidence.\n\n**资料来源：** [packages/scanner/scanner/detectors/secrets.py:40-60]()\n\n#### Entropy-Based Fallback\n\nWhen TruffleHog detects a high-entropy string, it flags potential hardcoded credentials:\n\n```python\nmessage=(\n f\"High-entropy string in secret assignment \"\n f\"(Shannon entropy={entropy:.2f}) — likely a hardcoded credential\"\n)\n```\n\n**资料来源：** [packages/scanner/scanner/detectors/secrets.py:180-185]()\n\nThe entropy scanner walks the target path recursively, skipping non-code directories and binary files:\n\n**Skipped directories:** `.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build`\n\n**资料来源：** [packages/scanner/scanner/detectors/secrets.py:95-100]()\n\n### Bandit Detector\n\nBandit analyzes Python code for common security issues using configurable test sets. It produces findings with severity ratings based on the potential impact of identified issues.\n\n### Semgrep Detector\n\nSemgrep runs rule-based analysis using the `p/python` ruleset:\n\n```python\ndef scan(self, target: Path) -> list[RawFinding]:\n return self._run_semgrep(target)\n```\n\n**Invocation command:** `semgrep scan --config p/python --json --quiet --metrics=off `\n\n**资料来源：** [packages/scanner/scanner/detectors/semgrep.py:22-30]()\n\n#### Availability Check\n\nSemgrep availability is verified via a lightweight version check:\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:55-65]()\n\nIf semgrep is not installed, the detector logs a warning and skips analysis rather than failing the entire scan.\n\n### pip-audit Detector\n\npip-audit scans Python dependencies against the Python Packaging Advisory Database. It extracts CVSS v3 scores to determine severity ratings and identifies available fix versions.\n\n**资料来源：** [packages/scanner/scanner/detectors/pip_audit.py:60-85]()\n\n### Safety Detector\n\nSafety provides an additional layer of dependency vulnerability checking, extracting CVE identifiers and advisory information for prioritization.\n\n**资料来源：** [packages/scanner/scanner/detectors/safety.py:1-30]()\n\n## Data Flow\n\n```mermaid\ngraph LR\n A[RawFinding] --> B[FindingNormalizer]\n B --> C[NormalizedFinding]\n C --> D[DeduplicationFilter]\n D --> E[Final Findings]\n \n F[tool+file+line+rule_id] --> G[SHA-256 Hash]\n G --> H[16-char ID]\n```\n\n### Raw Finding Structure\n\nDetectors produce `RawFinding` objects containing raw output from security tools:\n\n```python\n@dataclass\nclass RawFinding:\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[str, Any]\n```\n\n### Normalized Finding Structure\n\n`FindingNormalizer` converts raw findings into a canonical format:\n\n```python\n@dataclass\nclass NormalizedFinding:\n id: str # SHA-256[:16] of tool+file+line+rule_id\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\n```\n\n**资料来源：** [packages/normalizer/models.py:1-50]()\n\n### Deduplication\n\nThe `DeduplicationFilter` removes duplicate findings across scans using deterministic SHA-256 identifiers derived from `tool + file + line + rule_id`. This ensures consistent identification of the same vulnerability across multiple scans.\n\n**资料来源：** [packages/scanner/scanner/pipeline.py:77-78]()\n\n## Severity Classification\n\n| Level | Badge | Use Case |\n|-------|-------|----------|\n| CRITICAL | 🔴 | Hardcoded secrets, RCE, auth bypass |\n| HIGH | 🟠 | SQL injection, command injection, insecure deserialization |\n| MEDIUM | 🟡 | XSS, weak crypto, path traversal |\n| LOW | 🔵 | Insecure defaults, minor misconfigurations |\n| INFO | ⚪ | Style issues, informational notes |\n\n**资料来源：** [apps/cli/README.md:95-105]()\n\n## Usage Examples\n\n### Async Usage\n\n```python\nfrom scanner.pipeline import ScanPipeline\nfrom pathlib import Path\n\nasync def scan_project():\n pipeline = ScanPipeline()\n findings = await pipeline.run(Path(\"./my-project\"), verbose=True)\n return findings\n```\n\n### Sync Usage\n\n```python\nimport asyncio\nfrom scanner.pipeline import ScanPipeline\nfrom pathlib import Path\n\nfindings = asyncio.run(\n ScanPipeline().run(Path(\"./my-project\"))\n)\n```\n\n### CLI Usage\n\n```bash\n# Full scan with all detectors\nvelonus scan ./\n\n# High severity only (CI gate)\nvelonus scan ./ --severity high\n\n# JSON output for tooling\nvelonus scan ./ --format json\n\n# SARIF output for GitHub Security tab\nvelonus scan ./ --format sarif -o results.sarif\n\n# Verbose timing output\nvelonus scan ./ --verbose\n```\n\n**资料来源：** [README.md:20-40]()\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Scan completed, no HIGH or CRITICAL findings |\n| 1 | Scan completed, one or more HIGH or CRITICAL findings found |\n\nExit code 1 on HIGH/CRITICAL is intentional for CI/CD integration, enabling automated blocking of merges.\n\n**资料来源：** [apps/cli/README.md:70-80]()\n\n## Error Handling\n\n### Semgrep Exit Code Handling\n\nSemgrep exits with code 1 when findings are present. This is not treated as an error:\n\n> Semgrep exits with code 1 when findings are present. This is NOT treated as an error — the JSON output is still fully valid and parsed normally. Exit code 2+ indicates a real error (bad arguments, semgrep crash).\n\n**资料来源：** [packages/scanner/scanner/detectors/semgrep.py:22-30]()\n\n### Missing Tool Handling\n\nIf a security tool is not installed, the detector logs a warning and returns an empty list rather than failing the scan:\n\n```python\nif not self._semgrep_available():\n logger.warning(\n \"semgrep not found on PATH — skipping Semgrep analysis. \"\n \"Install with: pip install semgrep\"\n )\n return []\n```\n\n**资料来源：** [packages/scanner/scanner/detectors/semgrep.py:32-37]()\n\n## Performance Characteristics\n\n- **Parallel execution** of all detectors minimizes total scan time\n- **Timing logging** occurs at INFO level when `verbose=True`, DEBUG otherwise\n- **Skip patterns** exclude common non-code directories to reduce scan scope\n- **Empty results** are handled gracefully, allowing partial scans when tools are unavailable\n\n---\n\n\n\n## Security Detectors\n\n### 相关页面\n\n相关主题：[Scanner Pipeline](#scanner-pipeline), [Output Formats](#output-formats)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [packages/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.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# Security Detectors\n\n## Overview\n\nSecurity Detectors are the core scanning engines within Velonus that identify vulnerabilities, secrets, and insecure code patterns. Each detector wraps an external security tool (TruffleHog, Bandit, Semgrep, pip-audit, Safety) and normalizes its output into a unified `RawFinding` format. This abstraction layer enables Velonus to run multiple security scanners through a single interface while presenting results in a consistent structure.\n\nThe detector system is located in `packages/scanner/detectors/` and `packages/scanner/scanner/detectors/`, with each module handling a specific security tool. Detectors serve as the first stage in Velonus's scanning pipeline, producing raw findings that are later normalized by the `FindingNormalizer` into the canonical `NormalizedFinding` model. [资料来源：packages/scanner/detectors/__init__.py:1]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Scan Request] --> B[Scanner Pipeline]\n B --> C[Secrets Detector]\n B --> D[Bandit Detector]\n B --> E[Semgrep Detector]\n B --> F[pip-audit Detector]\n B --> G[Safety Detector]\n \n C --> H[RawFinding Objects]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[FindingNormalizer]\n I --> J[NormalizedFinding Objects]\n J --> K[Output Formatters]\n K --> L[Terminal / JSON / SARIF]\n```\n\n### Component Overview\n\n| Detector | Tool Wrapped | Purpose |\n|----------|--------------|---------|\n| `secrets` | TruffleHog + Entropy | Hardcoded secrets and credentials |\n| `bandit` | Bandit | Python security issues |\n| `semgrep` | Semgrep | Custom security rules |\n| `pip-audit` | pip-audit | Python dependency vulnerabilities |\n| `safety` | Safety | Legacy Python dependency vulnerabilities |\n\n## Secrets Detector\n\nThe Secrets Detector identifies hardcoded secrets, API keys, passwords, and other sensitive credentials in source code. It employs a two-tier detection strategy: primary TruffleHog scanning followed by an entropy-based fallback for generic high-entropy strings.\n\n### Detection Pipeline\n\n```mermaid\ngraph LR\n A[File Input] --> B{TruffleHog Scan}\n B -->|Verified Secrets| C[RawFinding]\n B -->|No Secrets Found| D[Entropy Fallback]\n D -->|High Entropy| E[RawFinding]\n D -->|Low Entropy| F[Skip]\n```\n\n### TruffleHog Integration\n\nThe detector invokes TruffleHog as the primary secret scanner. When TruffleHog returns results, each finding is parsed and converted to a `RawFinding` object with the following characteristics:\n\n- **Tool**: `secrets`\n- **Rule ID**: `trufflehog-{detector-name}` (lowercase, spaces replaced with hyphens)\n- **Severity**: `CRITICAL` (all TruffleHog findings)\n- **Verification Status**: Captured in metadata as `verified: bool`\n- **Decoder Information**: Extracted from `DecoderName` in TruffleHog output\n\n[资料来源：packages/scanner/detectors/secrets.py:1-30]()\n\n### Entropy-Based Fallback\n\nWhen TruffleHog is unavailable or returns no findings, the detector falls back to an entropy-based scanner (`_entropy_scan`). This method:\n\n1. Walks the target directory recursively\n2. Skips non-code directories (`.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.env`, `dist`, `build`)\n3. Applies regex patterns for known secret types\n4. Calculates Shannon entropy for candidate strings\n5. Flags strings exceeding the `_ENTROPY_THRESHOLD`\n\n[资料来源：packages/scanner/detectors/secrets.py:50-80]()\n\n### File Iteration Logic\n\nThe `_iter_files` method yields scannable source files while excluding:\n\n```python\n# Skipped directories\n.git, node_modules, __pycache__, .venv, venv, \n.env, dist, build\n```\n\n### Finding Structure\n\nEach secrets finding includes:\n\n| Field | Value | Description |\n|-------|-------|-------------|\n| `tool` | `secrets` | Scanner identifier |\n| `rule_id` | `high-entropy-secret` or `trufflehog-{name}` | Rule identifier |\n| `severity` | `CRITICAL` | Always critical for secrets |\n| `message` | Dynamic | Includes entropy score or verification status |\n| `metadata` | `dict` | Contains entropy value, detector name, decoder |\n\n[资料来源：packages/scanner/detectors/secrets.py:100-130]()\n\n## Dependency Vulnerability Detectors\n\nVelonus includes two detectors for Python dependency vulnerabilities: **pip-audit** and **Safety**. Both analyze dependency manifests (e.g., `requirements.txt`) and report known CVEs.\n\n### pip-audit Detector\n\nThe pip-audit detector parses JSON output from the `pip-audit` tool and converts vulnerabilities into `RawFinding` objects.\n\n#### Data Extraction\n\nThe detector extracts the following fields from pip-audit JSON:\n\n| Field | Source | Purpose |\n|-------|--------|---------|\n| `package_name` | `entry` | Vulnerable package name |\n| `package_version` | `entry` | Installed version |\n| `vuln_id` | `entry` | Vulnerability identifier |\n| `aliases` | `entry` | Alternative IDs (CVEs, GHSA) |\n| `fix_versions` | `entry` | Safe versions to upgrade to |\n| `cvss_score` | Nested `severity` dict | CVSS v3 base score |\n| `fix_available` | `bool(fix_versions)` | Whether a fix exists |\n\n[资料来源：packages/scanner/scanner/detectors/pip_audit.py:1-50]()\n\n#### CVSS Score Extraction\n\nThe `_extract_cvss_score` helper parses pip-audit's nested CVSS format:\n\n```python\n[{\"type\": \"CVSS_V3\", \"score\": \"CVSS:3.1/...\", \"base_score\": 7.5}]\n```\n\nThe detector prefers CVSS v3 scores and selects the highest when multiple are present. [资料来源：packages/scanner/scanner/detectors/pip_audit.py:80-100]()\n\n#### Message Construction\n\nFinding messages include:\n- Package name and version\n- Vulnerability ID (preferred CVE alias)\n- Fix hint (if available)\n- Truncated description (max 200 characters)\n\n### Safety Detector\n\nThe Safety detector handles both Safety v1 and v2 JSON output formats, which differ significantly in structure.\n\n#### Supported Output Formats\n\n| Format | Version | Structure | Finding Count |\n|--------|---------|-----------|----------------|\n| Format A | Safety ≥2.0 | `{\"vulnerabilities\": [...]}` | One per entry |\n| Format B | Safety <2.0 | `[...]` (list of lists) | One per 5-element list |\n\n[资料来源：packages/scanner/scanner/detectors/safety.py:1-50]()\n\n#### Entry Parsing (v2 Format)\n\nFor Safety v2, each vulnerability entry must contain:\n\n```python\nrequired_fields = [\"vulnerability_id\", \"package_name\", \"analyzed_version\"]\n```\n\nEntries missing required fields are skipped with a warning. [资料来源：packages/scanner/scanner/detectors/safety.py:50-80]()\n\n#### Parsed Fields\n\n| Field | Extraction | Notes |\n|-------|------------|-------|\n| `vuln_id` | `entry[\"vulnerability_id\"]` | str conversion |\n| `package_name` | `entry[\"package_name\"]` | str conversion |\n| `installed_version` | `entry[\"analyzed_version\"]` | str conversion |\n| `advisory` | `entry.get(\"advisory\")` | Human-readable text |\n| `cve` | `entry.get(\"CVE\")` | CVE identifier (preferred display) |\n| `fix_versions` | `entry.get(\"fixed_versions\", [])` | List of safe versions |\n\n[资料来源：packages/scanner/scanner/detectors/safety.py:80-120]()\n\n#### Severity Mapping\n\nCVSS scores are converted to severity levels:\n\n```python\ndef _cvss_to_severity(cvss_score: float | None) -> str:\n if cvss_score is None:\n return \"MEDIUM\" # Default\n elif cvss_score >= 9.0:\n return \"CRITICAL\"\n elif cvss_score >= 7.0:\n return \"HIGH\"\n elif cvss_score >= 4.0:\n return \"MEDIUM\"\n else:\n return \"LOW\"\n```\n\n## Finding Data Models\n\n### RawFinding\n\nAll detectors produce `RawFinding` objects with this structure:\n\n```python\n@dataclass\nclass RawFinding:\n tool: str # \"bandit\"|\"semgrep\"|\"secrets\"|\"pip-audit\"|\"safety\"\n rule_id: str # Scanner-specific rule identifier\n file: str # Path to file containing the finding\n line: int # Line number (0 for dependency findings)\n severity: str # CRITICAL|HIGH|MEDIUM|LOW|INFO\n message: str # Human-readable description\n code_snippet: str # Relevant code (redacted for secrets)\n metadata: dict # Tool-specific additional data\n```\n\n### NormalizedFinding\n\nAfter normalization, findings conform to the canonical `NormalizedFinding` model:\n\n```python\n@dataclass\nclass NormalizedFinding:\n id: str # SHA-256: sha256(tool+file+line+rule_id)[:16]\n tool: str # Scanner identifier\n rule_id: str # Normalized rule identifier\n cwe: list[str] # CWE identifiers (e.g., [\"CWE-89\"])\n owasp: list[str] # OWASP categories (e.g., [\"A03:2021\"])\n severity: Severity # Enum: CRITICAL|HIGH|MEDIUM|LOW|INFO\n confidence: Confidence # Enum: HIGH|MEDIUM|LOW\n file: str # File path\n line_start: int # Start line\n line_end: int # End line\n code_snippet: str # Redacted code snippet\n message: str # Finding message\n fix_available: bool = False # Whether a fix exists\n suppressed: bool = False # Whether suppressed\n first_seen: datetime # Timestamp\n```\n\n[资料来源：packages/normalizer/models.py:1-50]()\n\n## Extensibility\n\nAdding a new detector follows a consistent pattern:\n\n1. **Create a new module** in `packages/scanner/detectors/`\n2. **Implement the detector class** with `_scan()` method\n3. **Return `RawFinding` objects** for each finding\n4. **Include metadata** for downstream normalization\n\n### Detector Interface Pattern\n\n```python\nclass BaseDetector:\n def _scan(self, target: Path) -> list[RawFinding]:\n \"\"\"Main scanning entry point - override in subclasses.\"\"\"\n raise NotImplementedError\n \n def _iter_files(self, root: Path) -> Iterator[Path]:\n \"\"\"File iteration with exclusions - reusable utility.\"\"\"\n ...\n```\n\n## Severity Classification\n\n| Badge | Level | Color | Use Case |\n|-------|-------|-------|----------|\n| 🔴 | `CRITICAL` | Bold red | Hardcoded secrets, RCE, auth bypass |\n| 🟠 | `HIGH` | Orange | SQL injection, command injection, insecure deserialization |\n| 🟡 | `MEDIUM` | Yellow | XSS, weak crypto, path traversal |\n| 🔵 | `LOW` | Blue | Insecure defaults, minor misconfigurations |\n| ⚪ | `INFO` | Grey | Style issues, informational notes |\n\n## Output Integration\n\nDetectors feed into Velonus's output formatters:\n\n| Format | Use Case | Consumer |\n|--------|----------|----------|\n| `terminal` | Interactive scanning | CLI users |\n| `json` | Piping to tools | CI/CD pipelines, scripting |\n| `sarif` | GitHub Security tab | GitHub integration |\n\nThe scanner exits with code `1` when CRITICAL or HIGH findings are detected, enabling use as a CI gate.\n\n---\n\n\n\n## Output Formats\n\n### 相关页面\n\n相关主题：[CLI Components](#cli-components), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/cli/shield/formatters/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/__init__.py)\n- [apps/cli/shield/formatters/sarif.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/formatters/sarif.py)\n- [apps/cli/shield/core/output.py](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/shield/core/output.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/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- [packages/scanner/detectors/secrets.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/detectors/secrets.py)\n
\n\n# Output Formats\n\nVelonus supports multiple output formats for scan results, enabling integration with various security tooling, CI/CD pipelines, and developer workflows. Each format serves a specific use case and targets a different audience.\n\n## Overview\n\nThe output format system transforms normalized `RawFinding` objects into format-specific representations. This abstraction allows Velonus to aggregate results from multiple security scanners (Bandit, Semgrep, pip-audit, Safety, TruffleHog) while presenting them consistently regardless of the underlying tool.\n\n资料来源：[apps/cli/shield/formatters/__init__.py:1]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Scan Command] --> B[Scanner Pipeline]\n B --> C[RawFinding Objects]\n C --> D[Normalizer]\n D --> E[NormalizedFinding]\n E --> F[Output Formatters]\n \n F --> G[Terminal Formatter]\n F --> H[JSON Formatter]\n F --> I[SARIF Formatter]\n \n G --> J[Rich Console Output]\n H --> K[JSON File/Stream]\n I --> L[SARIF 2.1.0 File]\n```\n\n## Supported Formats\n\n| Format | Command Flag | Use Case | Phase |\n|--------|-------------|----------|-------|\n| `terminal` | `--format terminal` | Interactive scanning | Phase 0 |\n| `json` | `--format json` | Piping to tools, storage | Phase 0 |\n| `sarif` | `--format sarif` | GitHub Security tab, VS Code | Phase 1 |\n\n资料来源：[apps/cli/README.md:60-65]()\n\n## Terminal Format\n\nThe default output format using Rich library for colored, formatted tables with severity badges.\n\n### Severity Color Scheme\n\nThe terminal formatter uses a consistent color system defined in `output.py`:\n\n| Severity | Color | Badge | Description |\n|----------|-------|-------|-------------|\n| `CRITICAL` | Bold red | 🔴 | Hardcoded secrets, RCE, auth bypass |\n| `HIGH` | Dark orange | 🟠 | SQL injection, command injection |\n| `MEDIUM` | Yellow | 🟡 | XSS, weak crypto, path traversal |\n| `LOW` | Steel blue | 🔵 | Insecure defaults, minor issues |\n| `INFO` | Grey | ⚪ | Style issues, informational notes |\n\n资料来源：[apps/cli/shield/core/output.py:18-29]()\n\n### Output Table Columns\n\n| Column | Description |\n|--------|-------------|\n| Severity | Emoji badge and severity level |\n| Tool | Source scanner (bandit, semgrep, pip-audit, etc.) |\n| File | Path to affected file |\n| Line | Line number of finding |\n| Rule | Rule ID or check name |\n| Message | Human-readable finding description |\n\n### Terminal Usage\n\n```bash\n# Default terminal output\nvelonus scan ./\n\n# Explicit terminal format\nvelonus scan ./ --format terminal\n\n# Filter by severity\nvelonus scan ./ --severity high\n```\n\n## JSON Format\n\nMachine-readable JSON output suitable for piping into other tools or storing results.\n\n### JSON Output Structure\n\n```bash\nvelonus scan ./ --format json\n```\n\nProduces a JSON array of findings with the following schema:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `tool` | string | Source scanner name |\n| `rule_id` | string | Unique identifier for the rule |\n| `file` | string | Path to affected file |\n| `line` | integer | Line number (0 for dependency issues) |\n| `severity` | string | CRITICAL, HIGH, MEDIUM, LOW, INFO |\n| `message` | string | Human-readable description |\n| `code_snippet` | string | Relevant source code (may be redacted) |\n| `metadata` | object | Additional scanner-specific data |\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:40-52]()\n\n### JSON Usage Examples\n\n```bash\n# Pretty-print JSON\nvelonus scan ./ --format json | python -m json.tool\n\n# Save to file\nvelonus scan ./ --format json > scan-results.json\n\n# Filter by severity\nvelonus scan ./ --format json --severity high > findings.json\n```\n\n## SARIF Format\n\nStatic Analysis Results Interchange Format (SARIF 2.1.0) for compatibility with security tooling.\n\n### SARIF Specification\n\n| Property | Value |\n|----------|-------|\n| Schema Version | 2.1.0 |\n| Specification URL | https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html |\n| Version Constant | `0.1.0` |\n\n资料来源：[apps/cli/shield/formatters/sarif.py:38-41]()\n\n### Severity Mapping\n\n| Velonus Severity | SARIF Level |\n|-----------------|-------------|\n| CRITICAL | `error` |\n| HIGH | `error` |\n| MEDIUM | `warning` |\n| LOW | `note` |\n| INFO | `note` |\n\n资料来源：[apps/cli/shield/formatters/sarif.py:48-54]()\n\n### Rule ID Transformation\n\nSARIF rule IDs are converted to PascalCase display names:\n\n```python\n\"generic-api-key\" → \"GenericApiKey\"\n\"secrets/aws-access-key-id\" → \"AwsAccessKeyId\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:59-60]()\n\n### Directory URI Handling\n\nPer SARIF spec §3.14.14, directory URIs must end with a trailing slash:\n\n```python\nuri = path.as_uri()\nreturn uri if uri.endswith(\"/\") else uri + \"/\"\n```\n\n资料来源：[apps/cli/shield/formatters/sarif.py:23-24]()\n\n### SARIF Integration Points\n\n```mermaid\ngraph LR\n A[Velonus Scan] --> B[SARIF File]\n B --> C[GitHub Security Tab]\n B --> D[VS Code SARIF Viewer]\n B --> E[Other SARIF Tools]\n```\n\n### SARIF Usage\n\n```bash\n# Default SARIF output\nvelonus scan ./ --format sarif\n\n# Custom output path\nvelonus scan ./ -o results/velonus.sarif\n\n# Severity filtering (recommended for SARIF)\nvelonus scan ./ --format sarif --severity high -o findings.sarif\n```\n\n### GitHub Actions Integration\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:45-50]()\n\n## Finding Data Model\n\n### RawFinding Structure\n\nEach scanner produces `RawFinding` objects that are normalized before formatting:\n\n```python\nRawFinding(\n tool=\"pip-audit\",\n rule_id=vuln_id,\n file=attribution_path,\n line=0, # Dependency findings are file-level\n severity=severity,\n message=message,\n code_snippet=\"\",\n metadata={\n \"package_name\": package_name,\n \"package_version\": package_version,\n \"cvss_score\": cvss_score,\n \"fix_available\": bool(fix_versions),\n },\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:40-52]()\n\n### Metadata Fields by Scanner\n\n| Scanner | Unique Metadata Fields |\n|---------|----------------------|\n| pip-audit | `package_name`, `package_version`, `aliases`, `fix_versions`, `cvss_score`, `cwe`, `owasp`, `fix_available` |\n| safety | `vulnerable_spec`, `analysis`, `published_date`, `fixed_versions`, `advisory` |\n| semgrep | `cwe`, `owasp`, `confidence`, `rule_short` |\n| secrets | `detector`, `verified`, `decoder`, `entropy` |\n\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:25-35]()\n\n## CLI Options\n\n### Global Format Options\n\n| Option | Short | Default | Description |\n|--------|-------|---------|-------------|\n| `--format` | `-f` | `terminal` | Output format: `terminal`, `json`, `sarif` |\n| `--severity` | `-s` | `info` | Minimum severity: `critical`, `high`, `medium`, `low`, `info` |\n| `--output` | `-o` | (stdout) | Output file path (for SARIF/JSON) |\n| `--verbose` | `-v` | off | Show resolved target path and extra detail |\n\n资料来源：[apps/cli/README.md:61-66]()\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Scan completed, no HIGH or CRITICAL findings |\n| `1` | Scan completed, one or more HIGH or CRITICAL findings found |\n\n资料来源：[apps/cli/README.md:97-98]()\n\n## Format Selection Guide\n\n```mermaid\ngraph TD\n A[Choose Output Format] --> B{Use Case}\n \n B -->|Interactive scanning| C[terminal]\n B -->|CI/CD pipeline| D{Hosting Platform}\n B -->|Tooling integration| E[json]\n \n D -->|GitHub| F[sarif]\n D -->|GitLab| G[json]\n D -->|Azure DevOps| H[sarif]\n \n C --> I[Rich colored tables]\n F --> J[GitHub Security tab]\n E --> K[JSON API processing]\n```\n\n### Quick Reference\n\n| Scenario | Recommended Format |\n|----------|-------------------|\n| Local development | `terminal` (default) |\n| Pre-commit hooks | `terminal --severity high` |\n| CI gate (GitHub) | `sarif` |\n| Log aggregation | `json` |\n| Custom tooling | `json` |\n| Security dashboards | `sarif` |\n\n---\n\n\n\n## AI Engine\n\n### 相关页面\n\n相关主题：[API Backend](#api-backend), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/ai-engine/ai_engine/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/ai_engine/__init__.py)\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\n# AI Engine\n\nThe **AI Engine** is a core component of Velonus (Phase 2) that provides intelligent prioritization, exploitability scoring, and automated fix generation for security findings. It processes normalized findings from the scanner pipeline and applies AI-driven analysis to help developers focus on the most critical issues first.\n\n## Architecture Overview\n\nThe AI Engine is structured as a modular system with three primary sub-engines:\n\n| Component | Purpose |\n|-----------|---------|\n| **Context Engine** | Enriches findings with contextual information about the codebase |\n| **Remediation Engine** | Generates actionable fix suggestions for identified vulnerabilities |\n| **AI Service** | Handles API communication and LLM integration |\n\n```mermaid\ngraph TD\n A[NormalizedFindings] --> B[Context Engine]\n B --> C[Enriched Findings]\n C --> D[Remediation Engine]\n D --> E[Fix Suggestions]\n C --> F[Exploitability Scoring]\n F --> G[Priority Ranking]\n G --> H[Dashboard / CLI Output]\n```\n\n资料来源：[packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n\n## Core Sub-Engines\n\n### Context Engine\n\nThe Context Engine analyzes security findings in their broader codebase context to determine:\n\n- **Reachability analysis** — Is the vulnerable code actually executed?\n- **Data flow analysis** — Does user input reach the vulnerable code path?\n- **Dependency context** — Are there mitigating factors in dependencies?\n\n资料来源：[packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n\n### Remediation Engine\n\nThe Remediation Engine generates specific, actionable fix recommendations based on:\n\n- The vulnerability type and severity\n- The affected code location\n- Project-specific patterns and conventions\n\n资料来源：[packages/ai-engine/remediation_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/remediation_engine.py)\n\n### AI Service\n\nLocated in the API layer, the AI Service handles:\n\n- LLM provider integration\n- Request batching and rate limiting\n- Response parsing and validation\n\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## Prompt Engineering\n\nThe AI Engine uses carefully crafted prompts stored in `prompts.py` to guide the LLM in:\n\n| Task | Prompt Purpose |\n|------|----------------|\n| Exploitability Assessment | Determine if a vulnerability can be exploited in the given context |\n| Fix Generation | Generate code patches that resolve the vulnerability |\n| Impact Analysis | Evaluate the potential blast radius of a vulnerability |\n\n资料来源：[packages/ai-engine/prompts.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/prompts.py)\n\n## Caching Strategy\n\nTo optimize performance and reduce API costs, the AI Engine implements a caching layer:\n\n```mermaid\ngraph LR\n A[Finding Hash] --> B{Cache Lookup}\n B -->|Hit| C[Return Cached Result]\n B -->|Miss| D[Call LLM API]\n D --> E[Store in Cache]\n E --> C\n```\n\nCache entries are keyed by:\n- Finding hash (vulnerability type + file + line)\n- Code context snippet\n- Project fingerprint\n\n资料来源：[packages/ai-engine/cache.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/cache.py)\n\n## Exploitability Scoring\n\nThe AI Engine assigns exploitability scores (1-10) based on:\n\n| Factor | Weight | Description |\n|--------|--------|-------------|\n| Reachability | 30% | Is the code path executable? |\n| Attack Surface | 25% | Is user-controlled input present? |\n| Preconditions | 20% | What conditions must be met? |\n| Impact | 25% | What is the potential damage? |\n\n资料来源：[packages/ai-engine/context_engine.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/context_engine.py)\n\n## Integration with Scanner Pipeline\n\nThe AI Engine receives input from the [ScanPipeline](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py) after findings have been normalized:\n\n```python\n# Pipeline execution order (from packages/scanner/scanner/pipeline.py)\n# 0 = secrets, 1 = bandit, 2 = semgrep, 3 = pip-audit, 4 = safety\n```\n\nNormalized findings flow into the AI Engine which:\n1. Deduplicates findings using the [DeduplicationFilter](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/pipeline.py)\n2. Enriches each finding with AI-generated context\n3. Ranks findings by priority\n4. Generates remediation suggestions\n\n## Configuration\n\nThe AI Engine is configured via the CLI configuration system (`velonus config set`):\n\n| Config Key | Default | Description |\n|------------|---------|-------------|\n| `ai_provider` | `openai` | LLM provider (openai, anthropic) |\n| `ai_model` | `gpt-4` | Model to use for analysis |\n| `ai_temperature` | `0.3` | Creativity level for fix generation |\n| `cache_enabled` | `true` | Enable/disable result caching |\n| `max_fixes_per_finding` | `3` | Maximum fix suggestions per vulnerability |\n\n资料来源：[packages/ai-engine/ai_engine/__init__.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/ai_engine/__init__.py)\n\n## CLI Integration\n\nThe AI Engine features are accessible through Phase 2 CLI commands:\n\n```bash\n# View AI-generated context for findings\nvelonus scan ./ --ai-context\n\n# Generate fix suggestions\nvelonus fix \n\n# Run with AI prioritization\nvelonus scan ./ --ai-prioritize\n```\n\n资料来源：[apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.md)\n\n## Development Status\n\n| Phase | Status | Components |\n|-------|--------|------------|\n| Phase 0 | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 | ✅ Done | Real secret detection, Bandit, Semgrep, pip-audit, SARIF |\n| **Phase 2** | 🔨 **Building** | AI context engine, exploitability scoring, fix generation |\n| Phase 3 | 🔜 Planned | GitHub PR inline review comments, one-click fix suggestions |\n| Phase 4 | 🔜 Planned | Web UI, scan history, finding trends |\n\n资料来源：[README.md](https://github.com/AliAmmar15/Velonus/blob/main/README.md)\n\n## API Endpoints\n\nThe AI Engine exposes REST endpoints via the API service:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v1/ai/enrich` | POST | Enrich findings with AI context |\n| `/api/v1/ai/score` | POST | Calculate exploitability scores |\n| `/api/v1/ai/remediate` | POST | Generate fix suggestions |\n\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## Security Considerations\n\nThe AI Engine handles sensitive data and implements the following safeguards:\n\n- **No code exfiltration** — Source code is only processed locally or sent to configured LLM providers\n- **Input sanitization** — All prompts are sanitized before sending to LLM\n- **Audit logging** — All AI requests are logged for compliance\n- **Cache encryption** — Cached results are encrypted at rest\n\n资料来源：[packages/ai-engine/cache.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/ai-engine/cache.py)\n\n---\n\n\n\n## GitHub PR Reviewer\n\n### 相关页面\n\n相关主题：[API Backend](#api-backend), [Scanner Pipeline](#scanner-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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- [apps/cli/README.md](https://github.com/AliAmmar15/Velonus/blob/main/apps/cli/README.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/pip_audit.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/pip_audit.py)\n- [packages/scanner/scanner/detectors/semgrep.py](https://github.com/AliAmmar15/Velonus/blob/main/packages/scanner/scanner/detectors/semgrep.py)\n
\n\n# GitHub PR Reviewer\n\n## Overview\n\nThe GitHub PR Reviewer is a planned feature in the Velonus security scanning platform designed to provide automated code review capabilities directly within GitHub Pull Requests. Based on the project roadmap, this feature is designated as **Phase 3 — GitHub Integration** and is currently marked as **Not Started**.\n\n资料来源：[README.md:Phase 3]()\n\nThe Velonus project is a security scanner designed to detect vulnerabilities, secrets, and security issues in Python codebases. The platform currently supports multiple security scanning tools including Bandit, Semgrep, pip-audit, Safety, and TruffleHog for secret detection.\n\n资料来源：[README.md:Roadmap]()\n\n## Project Architecture\n\nVelonus follows a modular architecture with clear separation between the CLI layer, scanner package, and planned API layer.\n\n```mermaid\ngraph TD\n A[velonus scan CLI] --> B[packages/scanner]\n B --> C[Detectors]\n C --> D[Secrets Scanner]\n C --> E[Bandit]\n C --> F[Semgrep]\n C --> G[pip-audit]\n C --> H[Safety]\n B --> I[Normalizer]\n I --> J[Formatted Output]\n J --> K[Terminal]\n J --> L[JSON]\n J --> M[SARIF]\n N[Planned: GitHub API] -.-> O[PR Reviewer]\n```\n\n资料来源：[README.md:Architecture Overview]()\n资料来源：[apps/cli/README.md:Commands]()\n\n## Current Scanner Pipeline\n\nThe existing scanner pipeline forms the foundation upon which GitHub PR Reviewer will build. The scanner orchestrates multiple security tools and normalizes their findings into a unified format.\n\n### Supported Detectors\n\n| Detector | Purpose | Severity Levels |\n|----------|---------|-----------------|\n| **Secrets Scanner** | Detects hardcoded credentials, API keys, and high-entropy strings | CRITICAL |\n| **Bandit** | Static security analysis for Python | CRITICAL, HIGH, MEDIUM, LOW |\n| **Semgrep** | Rule-based pattern matching (config: `p/python`) | Multiple |\n| **pip-audit** | Python dependency vulnerability scanning | Based on CVSS score |\n| **Safety** | Additional dependency checking | Based on CVSS score |\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:Entropy Scanner]()\n资料来源：[packages/scanner/scanner/detectors/semgrep.py:RULESET Definition]()\n\n### Output Formats\n\nThe current implementation supports three output formats that GitHub PR Reviewer can leverage:\n\n| Format | Use Case | Status |\n|--------|----------|--------|\n| `terminal` | Interactive display with Rich tables | Default |\n| `json` | Programmatic consumption, piping | Available |\n| `sarif` | GitHub Code Scanning, VS Code SARIF Viewer | Phase 1 |\n\n资料来源：[apps/cli/README.md:Output Formats]()\n\nThe SARIF format is particularly relevant for future GitHub integration, as it provides compatibility with GitHub's security tab through the `github/codeql-action/upload-sarif` action.\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:CI Integration]()\n\n## Planned GitHub PR Reviewer Features\n\nBased on the project roadmap and existing architecture patterns, the GitHub PR Reviewer is expected to provide the following capabilities:\n\n### Inline Review Comments\n\nThe primary feature will be posting inline comments on pull requests directly where security issues are detected. This follows the pattern of existing GitHub code scanning integrations.\n\n| Feature | Description |\n|---------|-------------|\n| **Inline Comments** | Post findings as PR review comments with file paths and line numbers |\n| **One-Click Fixes** | Suggest code changes to remediate vulnerabilities |\n| **Status Checks** | Integration with GitHub's required status check system |\n\n资料来源：[README.md:Phase 3 — GitHub Integration]()\n\n### Severity-Based Filtering\n\nThe existing `--severity` filtering mechanism will be leveraged to determine which findings trigger PR blocking:\n\n| Severity | Color | CI Behavior |\n|----------|-------|-------------|\n| 🔴 CRITICAL | Bold red | Blocks merge |\n| 🟠 HIGH | Orange | Blocks merge |\n| 🟡 MEDIUM | Yellow | Warning only |\n| 🔵 LOW | Blue | Informational |\n| ⚪ INFO | Grey | Informational |\n\n资料来源：[apps/cli/README.md:Severity Levels]()\n\nThe CLI already exits with code `1` when CRITICAL or HIGH findings are detected, providing a natural CI gate mechanism.\n\n### Finding Metadata Structure\n\nThe normalized finding format provides the data structure that GitHub PR Reviewer will consume:\n\n```python\nRawFinding(\n tool=\"secrets\", # Source tool\n rule_id=\"high-entropy-secret\", # Finding type\n file=str(path), # File path\n line=line_num, # Line number\n severity=\"CRITICAL\", # Severity level\n message=str, # Human-readable message\n code_snippet=str, # Code context\n metadata={} # Additional data\n)\n```\n\n资料来源：[packages/scanner/scanner/detectors/secrets.py:RawFinding Creation]()\n\n## Current GitHub Integration Path\n\nWhile the full GitHub PR Reviewer is not yet implemented, the project provides alternative GitHub integration methods:\n\n### GitHub Actions Workflow\n\nFor CI/CD integration before Phase 3, users can leverage the existing Velonus CLI in 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 - 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资料来源：[apps/cli/README.md:GitHub Actions]()\n\n### Pre-commit Hook\n\nSecurity scanning can be integrated into the development workflow using pre-commit hooks:\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:Pre-commit hook]()\n\n## Development Guidelines\n\nThe project follows strict development standards that will apply to the GitHub PR Reviewer implementation:\n\n### Code Quality Requirements\n\n| Requirement | Tool | Command |\n|-------------|------|---------|\n| Linting | ruff | `ruff check .` |\n| Formatting | ruff | `ruff format .` |\n| Type Checking | mypy | `mypy --strict` |\n\n资料来源：[CONTRIBUTING.md:Code Quality]()\n\n### PR Guidelines\n\nThe contributing guidelines establish patterns that GitHub PR Reviewer development must follow:\n\n1. **One feature per PR** — No bundling unrelated changes\n2. **Tests required** — Every new component needs unit tests\n3. **Small PRs preferred** — Under 400 lines of diff for faster review\n4. **Target main** — All changes merge into main branch\n5. **No AI-generated placeholder code** — Every function must be functional\n\n资料来源：[CONTRIBUTING.md:PR Guidelines]()\n\n### Commit Message Format\n\n```\n: \n\nTypes: feat | fix | refactor | test | docs | infra | chore\n```\n\n资料来源：[CONTRIBUTING.md:Commit Message Format]()\n\n## Project Roadmap\n\n| Phase | Status | Components |\n|-------|--------|------------|\n| Phase 0 — Foundation | ✅ Done | CLI skeleton, Rich output, NormalizedFinding model |\n| Phase 1 — Scanner Pipeline | ✅ Done | Bandit, Semgrep, pip-audit, Safety, SARIF |\n| Phase 2 — AI Layer | 🔨 Building | AI prioritization, exploitability scoring, fix generation |\n| **Phase 3 — GitHub Integration** | 🔴 Not Started | PR inline review comments, one-click fix suggestions |\n| Phase 4 — Dashboard | 🔴 Not Started | Web UI, scan history, finding trends |\n\n资料来源：[README.md:Roadmap]()\n\n## Dependencies and Requirements\n\nThe scanner already includes several dependencies that would support GitHub PR Reviewer functionality:\n\n### Security Scanning Dependencies\n\n- **TruffleHog** — For secrets detection with decoder support\n- **Bandit** — Python-specific security issues\n- **Semgrep** — Pattern-based security rules\n- **pip-audit** — Python dependency vulnerability scanning\n\n### CVSS Integration\n\nThe pip-audit and Safety detectors already extract and normalize CVSS scores:\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 # Returns CVSS:3.1/... formatted scores\n```\n\n资料来源：[packages/scanner/scanner/detectors/pip_audit.py:CVSS Helpers]()\n\n## Summary\n\nThe GitHub PR Reviewer is an anticipated Phase 3 feature of the Velonus security scanning platform. While not yet implemented, the foundation is being built through:\n\n1. A robust scanner pipeline with multiple security tool integrations\n2. Normalized finding formats suitable for PR comment generation\n3. SARIF output for GitHub Security tab compatibility\n4. CI/CD integration patterns via GitHub Actions\n5. Strict code quality standards for future development\n\nThe existing architecture and roadmap indicate that when Phase 3 development begins, the PR Reviewer will leverage the normalized `RawFinding` data structures to generate inline comments on pull requests, provide one-click fix suggestions, and integrate with GitHub's status check system to block merges when critical vulnerabilities are detected.\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- 安装前能力预览: [![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](https://github.com/AliAmmar15/Velonus/actions) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Introduction to Velonus。围绕“Introduction to Velonus”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：Quick Start Guide。围绕“Quick Start Guide”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：System Architecture。围绕“System Architecture”模拟一次用户任务，不展示安装或运行结果。\n4. cli-components：CLI Components。围绕“CLI Components”模拟一次用户任务，不展示安装或运行结果。\n5. api-backend：API Backend。围绕“API Backend”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction to Velonus”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“Quick Start Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“System Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. cli-components\n输入：用户提供的“CLI Components”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. api-backend\n输入：用户提供的“API Backend”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction to Velonus”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“Quick Start Guide”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“System Architecture”形成一个小中间产物，并等待用户确认。\n- Step 4 / cli-components：Step 4 必须围绕“CLI Components”形成一个小中间产物，并等待用户确认。\n- Step 5 / api-backend：Step 5 必须围绕“API Backend”形成一个小中间产物，并等待用户确认。\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- apps/cli/shield/main.py\n- apps/cli/shield/commands/scan.py\n- apps/cli/pyproject.toml\n- apps/api/pyproject.toml\n- packages/scanner/pyproject.toml\n- apps/cli/shield/commands/auth.py\n- apps/cli/shield/commands/config.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" }