ultrasec

ultrasec — 基于证据而非猜测的跨文件安全审计

有关引擎证据和覆盖范围限制，请阅读 engine-evidence。

ultrasec 通过推理不可信数据如何在函数和文件之间流动来查找漏洞，然后根据代码验证每个候选问题。确定性、零依赖的引擎负责机械性工作——链接图、候选 source→sink 路径、扫描器运行和证据包；你负责安全推理——判断哪些数据流真实且可利用，找出工具遗漏的隐蔽漏洞，并进行验证。

核心规则：

1. 依据证据推理，而非凭记忆。 根据 dossier 展示的真实代码判断每个发现，并按精确的引用格式标注 [file:line]。check 会 REJECT 引用位置无法解析的任何发现——因此不要编造行号。
2. 引擎找出候选问题；由你来判断。 枚举出的污点路径具有确定性，并以提高召回率为导向——其中许多按设计就是误报。在认定为漏洞前，请确认可达性和可利用性：references/adjudication.md。
3. 保持谨慎。 只有能明确反驳高危/严重发现时，才将其 dismiss，并说明依据：references/dismissal-brocards.md。无法确定 ⇒ needs-human。激进的自动抑制会漏掉真实漏洞。
4. 使用工具，然后进一步深入。 运行已安装的扫描器（tools），分流其输出，并补充只有语义推理才能发现的问题——授权/IDOR、业务逻辑、身份验证、密码学、竞态：references/attack-classes.md。个人数据需要回答另一个问题——数据流向何处、会保留多久：references/privacy-and-data-protection.md。
5. 只报告你能利用的问题。 每个发现都需要具体的攻击者场景（谁 · 发送什么 · 得到什么），而不是“可能”。如果其他层已经阻止了某个缺陷，那它是加固建议，而不是发现：references/severity-and-discipline.md。
6. 代码要已读取；CVE 要已分流。 安全公告是按风险排序的列表——按风险顺序处理，达到你的门槛后停止，将剩余项留为 open。只有打开文件才能判定代码候选问题，因此如果你自己的代码中还有高危/严重问题尚未给出判定，绝不要生成报告：render 会将报告标记为 DRAFT。使用 --surface code 将它们分开。

运行引擎

使用 scan --require-tools a,b 要求必须运行指定扫描器（这些扫描器会加入 auto；执行范围扫描时，只运行指定的扫描器）。 请参阅完成策略。执行成功并不能证明安全。

一个已提交的零依赖程序包——无需 npm install，也无需 API 密钥。

使用绝对路径。 解析一次 <skill-dir>/scripts/ultrasec.mjs，并将绝对路径也提供给子 Agent：已安装的技能位于项目之外，子 Agent 的 cwd 也可能不同。下文中的 ultrasec 指该路径。

ULTRASEC="<skill-dir>/scripts/ultrasec.mjs"     # then: node "$ULTRASEC" <command>

--help 会列出所有命令；大多数命令都接受 --json。退出码统一为——0 成功 · 1 门禁未通过 · 2 用法/运行时错误。完整标志、默认值和产物请参阅：references/commands.md。

速查表

ultrasec audit   --repo . --out .ultrasec       # ONE command → .ultrasec/REPORT.md, nothing else kept
  # --html (REPORT.html) · --full (exhaustive annexes) · --keep-work (keep the JSON worklists)
  # --powered <cli> / --council "<reviewer:model,…>" (opt-in agent calls) · scan flags pass through
ultrasec tools                                  # which scanners are installed (+ --upgrade)
ultrasec map     --repo . --out .ultrasec       # cheap attack-surface recon; no taint, no network
ultrasec context --repo . --out .ultrasec       # scaffold → you author .ultrasec/CONTEXT.md
ultrasec scan    --repo . --out .ultrasec       # graph + cross-file taint + tools → the dossier
  # focus:  --scope <dir> --include/--exclude <glob> --max-files N --gitignore
  #         --include-vendored (audit node_modules/.venv/dist too — pruned by default)
  # budget: --budget quick|standard|thorough  --max-candidates N  --max-depth N
  # again:  --diff origin/main --merge --resume        # incremental, folds into one run
  # recall: --sinks (orphan sinks: calls AND assignments)  --log-hygiene  --blame
  #         --no-env-sources (drop env-rooted flows)  --strict-scope (drop cross-function-in-file)
  # net:    --offline / --no-enrich (no EPSS/KEV)      --docker (scanners without installing)
ultrasec paths   --run .ultrasec                # the candidate chains  (--kind sql --min-severity high)
  # --surface code|supply|deps|code+supply|all  # YOUR code · secrets+CI/IaC · advisories  (also triage/verify/orchestrate)
ultrasec dossier <id> --run .ultrasec           # ONE finding: enclosing function, callers, route, guards, sanitizers
  # --brief; a,b,c                              # compact packet; a comma list = one family
ultrasec graph   <file|symbol> --run .ultrasec  # cross-file links into/out of a node
ultrasec assumptions --run .ultrasec            # what each unit trusts that NOTHING enforces (--apply)
ultrasec triage  --run .ultrasec                # cheap noise|keep fast-lane, low/medium only (--apply TRIAGE.json)
ultrasec guards  --run .ultrasec                # entry point × auth guard — the MISSING check (--apply)
  # --lens throttle                             # …and the MISSING rate limit
ultrasec investigate --run .ultrasec            # hunt authz/logic  (--apply INVESTIGATE.json)
ultrasec verify  --run .ultrasec                # adversarial worklist → write verdicts.json
ultrasec verify  --apply verdicts.json --run .ultrasec       # a file, comma-list, DIRECTORY, or -
  # any --apply: refused rows are listed with their reason; --strict exits 1 on any
ultrasec revalidate --run .ultrasec             # git-history FP cut  (--apply REVALIDATE.json)
ultrasec variants   --run .ultrasec             # where ELSE this root cause appears (--apply)
ultrasec coverage --run .ultrasec               # what was NOT looked at: counts (--full matrix, --write)
  # standard: --standard asvs|owasp-top10|owasp-api-top10|masvs|cwe-top25   (default asvs)
ultrasec check   --run .ultrasec --semantic     # THE GATE: grounded + adjudicated; advisories never block
ultrasec narrative --run .ultrasec              # → you author NARRATIVE.json
ultrasec render  --run .ultrasec                # THE report: REPORT.md (--html), folds NARRATIVE.json
  # an unread HIGH/CRITICAL CODE candidate ⇒ DRAFT banner; exit 0, --strict exits 1
ultrasec implement --run .ultrasec              # remediation-PRD draft → the `to-prd` skill
ultrasec run     --repo . --out .ultrasec       # sequence every stage (ZERO external calls)
ultrasec orchestrate --run .ultrasec --phase verify   # multi-agent fan-out: families, ≤12 agents
ultrasec council --run .ultrasec                # other model families review a HEAD snapshot (--models, --apply)
ultrasec logs    ./var/log --out .ultrasec-logs # blue team: forensics over EXISTING log files
  # detections: --sigma → ultrasec-logs.sigma.yml (SIEM pack, like variants→semgrep)
  # anywhere: --report out.md|html|json (archive this output)  --no-journal  --md (worklist briefs)
ultrasec import  findings.json --run .ultrasec  # ingest a deepsec export as candidates
ultrasec clean   --run .ultrasec                # keeps REPORT, findings, manifest, CONTEXT, NARRATIVE
ultrasec probe   https://you-own-this --i-own-this   # DYNAMIC live-site posture → PROBE.json (isolated)
  # probe: --allow-private (localhost)  --graphql  --deep (exposed files)  --timeout ms  --strict
ultrasec route   app.apk | ./bin/x.so | https://host # OUT-OF-SCOPE triage → methodology + tools (advisory)
  # route: URL → probe · source/dir → scan · else → jadx/radare2/wireshark/… (--write ROUTE.md)

按场景选择

1. “审计此仓库” — audit --keep-work，审定 JSON 工作清单，执行 render、clean： 生成一个 REPORT.md。references/audit-playbook.md。
2. “全面细致”/ 高保证性 — 按类别和入口点拆分，分派分析器和质疑者子 Agent，循环审查直至没有发现： references/deep-audit-playbook.md。
3. “审计整个平台”/ 仓库太大，无法扫描 — 先执行 map，然后在预算范围内逐个深入检查目标，合并到一次运行中；CI 中增量 --diff 重新审计也采用相同流程： references/scale-audit-playbook.md。
4. “这是真的吗？”/“看起来像误报” — FP 分类、反驳标准、如何编写漏洞利用证明，以及示例： references/adjudication.md。
5. “我还应该检查什么？” — 污点分析无法覆盖的类别，按机制层面划分： references/attack-classes.md；它们在技术栈中的藏匿位置： references/frameworks.md；应首先运用的分析视角： references/hunting-heuristics.md。
6. “检查我的依赖项 / 密钥 / CI” — 分诊流程、密钥响应、GitHub Actions、IaC： references/supply-chain.md；扫描器工具集： references/tools.md。将仓库自身的事件数据交给编码 Agent 的工作流属于独立类别，由 scan 审计： references/agentic-ci.md。 6b. “审计这个库 / SDK / API” — 问题有所不同：不是是否存在漏洞，而是 这种设计是否让不安全的用法比安全用法更容易。 investigate --lens sharp-edges · references/sharp-edges.md。
7. “这有多严重？” — 严重性评估标准及配套校准示例： references/severity-and-discipline.md。
8. “分析我的访问 / 身份验证日志”/“有人攻击我们了吗” — 蓝队、只读分析、独立档案： references/log-forensics-playbook.md。
9. “自主运行” — 让外部 Agent CLI 填写工作清单（可选启用，密钥保存在该 CLI 中）： references/powered-mode.md。
10. “寻求第二意见”/ 使用其他模型 — council：让审查者基于快照盲审，然后由唱反调者复核；--apply 会校验引文： references/deep-audit-playbook.md。

工作流（标准审计）

返回有依据、有引用的审计结果，不要在运行过程中途交还控制权。每个阶段都会增加结果；按任务需要选用其中一部分即可。每个阶段的结构相同：引擎生成工作清单 → 你填写清单 → --apply 按保守规则将其合并回来。各阶段的确切 JSON 格式： references/schemas.md。

1. 准备上下文 (杠杆最高)。运行 context --repo <dir> --out <run>，然后编写 <run>/CONTEXT.md — 说明用途、信任模型、身份验证方案、框架防护措施，以及用于校准严重性的同类应用。添加 Exposure: 和 Criticality:（风险评分会读取它们），并针对每个信任边界进行 STRIDE/LINDDUN 分析 — 这决定了你要寻找什么，而不是让工具来决定： references/threat-modeling.md。 references/context-playbook.md。

2. 扫描。 运行 scan --repo <dir> --out <run>。先运行 tools 以获得更全面的覆盖（Trivy 的杠杆最高）；征得用户同意后，运行 tools --upgrade（--dry-run 可预览）。

3. 确认运行结果真实可靠——在读取任何发现之前，先打开 <run>/manifest.json：

   • extraction.ast: false ⇒ tree-sitter 不可用，运行的是 regex 提取器——覆盖的跨文件流不足一半。使用语法重新运行，或说明这一点。
   • truncation 非零 ⇒ 触发了上限；提高 --max-candidates 或缩小 --scope。
   • toolStatus ⇒ 查看哪些扫描器已运行、哪些被跳过（覆盖缺口）、哪些运行失败。
   • weaknessClasses ⇒ degraded/not-covered 单元格表示缺口，可由 investigate 查找； resolutionGaps ⇒ 未跟踪的导入。

   运行结果降级时，绝不能报告为完整运行。

4. 读取索引，而不是数据。 <run>/DOSSIER.md 每个候选项占一行，并按优先级排序。切勿完整打开 findings.json 或 .work/graph.json：使用 paths、dossier <id> --brief，并直接填写 *.todo.json 工作清单（--md 会额外生成人工简报，无人需要这些简报）。

5. 分诊（可选）。 triage --run <run>，标记为 noise|keep，然后运行 triage --apply。它只会列出 低、中、信息级别的问题；高危/严重问题直接进入验证阶段。

6. 依据证据裁定——优先检查代码。 检查 paths --surface code，而不是打开整个开放层级； 依赖部分按列表分诊，绝不为每个 CVE 单独查看一份 dossier (references/supply-chain.md)。dossier <id> 会给出两端的完整 外围函数，以及谁可以访问此处——范围内的路由文件、调用方、身份验证和速率限制标记，以及路径附近的清理器。回答以下问题：SOURCE 是否受攻击者控制？该值是否在每一跳都未改变地到达 SINK？是否有清理器/授权检查？SINK 能否利用传入的数据？你能写出 PoC 吗？ 按类别而非发现项分配时间：阅读一次即可判断整组问题（产生此运行结果的项目中，242 个候选项归为 62 组）。 references/adjudication.md。

6b. 梳理假设（在搜寻之前）。assumptions --run <run>——逐个单元列出其保证（附引用）以及依赖的、未受任何机制强制执行的条件。nothing-found 表示代码依赖某项无人记录的条件：没有危险调用，任何单独页面看起来都没有问题，检测引擎也无法发现。--apply 会将线索提供给 investigate。 references/assumptions-playbook.md。

6c. 枚举缺失的防护措施。 guards --run <run> 会列出所有在范围内读取请求数据、但没有身份验证标记的处理器——污点分析无法触及这类情况，因为缺失的检查没有代码行可供追踪。标记只是一个候选项：阅读处理器，确认它确实在访问对象之前检查了授权。--apply 会将 unguarded 转为带引用的发现。使用 --lens throttle 再运行一次，查找另一种缺失情况——没有受到任何速率限制的处理器；身份验证路由会单独标出。使用任一视角时，任何位置都没有标记是一个架构事实，而不是 N 个发现：在 CONTEXT.md 中统一说明——项目级防护辅助函数也是如此：Auth markers: assertServerSession。 references/hunting-heuristics.md。

7. 搜寻检测引擎无法枚举的问题。 investigate --run <run> 会按区域归类攻击面；查找访问控制失效/IDOR、业务逻辑、身份验证/会话/JWT、加密、竞态、功能滥用和链式攻击，并生成有依据的 Discovery[]——导入前会检查引用，因此多报的成本很低。hunt: 项是某个框架中没有任何规则包覆盖的矩阵单元格：使用发现项、你识别出的 idioms（不安全用法和防护用法）以及 hunted 来作答。 references/investigate-playbook.md。

8. 验证。 verify --run <run> → 工作清单；记录 supported|partial|unsupported|refuted 并附注释，对于受支持的问题，还要提供 exploitPath；然后运行 verify --apply。保持怀疑态度，但不要驳回你实际上无法证伪的高严重性问题。

9. 根据 git 历史重新验证。 在 verify --apply 后（其范围已确认为已确认/需要人工处理，因此此前工作清单为空）：判定为 still-valid|fixed|false-positive|uncertain。 references/revalidate-playbook.md。

9b. 查找变体。 variants --run <run> —— 一个根本原因几乎不会只产生一个实例。说明 原因，每次只泛化一个维度，并生成 Semgrep 规则，防止同类问题再次出现：references/variant-analysis.md。

10. 把关。 check --run <run> --semantic。修复任何悬空引用，裁定所有遗留项，并核对 CONTEXT.md 中与代码相矛盾的否定表述——一句声称某个类不存在的话，可能导致这个类未经检查。

10b. 说明覆盖范围。 coverage --run <run> —— 列出本次审计检查和未检查内容的 ASVS 矩阵。一份简短报告读起来可能像是“什么问题都没有”，但实际意思是“在我检查的范围内没有问题”；该矩阵会将两者区分开来。内容会自动并入 REPORT.md。

11. 撰写说明并渲染。 narrative --run <run>，编写 <run>/NARRATIVE.json（summary、包含 effort 的修复方案、攻击链、根本原因、hardeningNotes），然后运行 render --run <run> → 生成一个 REPORT.md（--html）：按严重性和领域列出发现，并包含场景 · 修复方案 · 优先级；依赖项按每个包一行列出；提供 P0–P3 计划；汇总驳回项（使用 --full 查看全部）。 未读取的 HIGH/CRITICAL 代码候选项仍属于草稿（退出码为 0；--strict 的退出码为 1）——返回第 6 步，或明确说明这一点。然后运行 clean。提供报告路径、已确认的发现以及需要人工处理的清单。references/narrative-playbook.md。

12. 规划修复（可选）。 implement --run <run> → 生成 IMPLEMENT.md，一份按根本原因分组的修复 PRD 草稿。将其交给 to-prd 技能或实施人员。 references/implement-playbook.md。

编排——按运行环境路由

判定阶段会分派工作：findings.json 中待处理的候选项（裁定）、VERIFY.todo.json、REVALIDATE.todo.json 和 INVESTIGATE.todo.json 均为独立的逐项工作清单。orchestrate 根据当前工作清单生成分派任务：将完整的问题族分组，最多分配给 12 个 Agent，每个提示词都包含对应条目：

ultrasec orchestrate --run <dir> [--phase adjudicate|verify|revalidate|investigate] [--eco] [--list]

运行环境	各判定阶段的运行方式
Claude Code 提供 Workflow	运行 orchestrate --run <run> --phase <p>，然后运行 Workflow({ scriptPath: "<run>/.work/orchestration/<p>.workflow.mjs" })。子 Agent 返回判定/发现片段；由你将其合并到一个 apply 文件中，然后运行工作流末尾所示的 --apply 汇总步骤。
Codex/其他宿主提供子 Agent	同样运行 orchestrate；按照 <run>/.work/orchestration/agents/<role>.md 为每个批次分派一个子 Agent（工作流脚本会显示批次和提示词）。由一名写入者负责：由你合并并汇总。
Eco 模式，或没有子 Agent	运行 orchestrate --run <run> --eco → 按顺序遵循 <run>/.work/orchestration/RUNBOOK.md，自行扮演每个角色。正确性相同，只有耗时不同。

分派任务是一种优化手段，而非必需条件——每个阶段都有顺序执行的备用方案，生成的产物完全相同。子 Agent 从不写入：约定以单一写入者规则（仅运行只读命令）结束，而 --apply 由你执行，因此无论由谁裁定，不确定的高严重性发现仍会归入需要人工处理。每当工作清单发生变化时，都要重新运行 orchestrate（生成过程具有幂等性）；如果对应工作清单尚未生成就运行 --phase <p>，命令会失败并指出用于生成该清单的命令。

运行结果异常时

症状	处理方法
scan 找到 0 个候选项	检查 manifest.extraction.ast（是否为正则表达式层？）和 languages——不受支持的技术栈不会生成图。尝试 --sinks，并用 investigate 手动排查。
候选项远少于预期	同上，另外检查 truncation（是否触发上限）以及 --scope/--gitignore 是否裁剪得超出预期。
toolStatus 显示所有内容都被跳过	未安装扫描器——查看 tools 获取提示，或运行 scan --docker。
check 一直失败	引用的 [file:line] 无法解析：文件已移动、行号超出范围，或该位置是编造的。重新打开 dossier <id>，修正引用，或删除该发现。
check --semantic 失败	某个 HIGH/CRITICAL 级代码或配置候选项仍处于 open 状态（建议不会阻止检查）。对其作出判定。
--apply 以状态码 2 退出	失败即关闭：文件格式错误，或文件中的 ID 与 dossier 均不匹配（片段已过期）。重新生成待办清单并重新填写。
从目录运行 --apply 后未折叠任何内容	片段名称必须符合阶段的模式——commands.md 中有列出。
investigate --apply 拒绝了一项发现	可能是其 [file:line] 无法解析——这是防幻觉检查生效了；找到真实行号后重新提交——也可能是某个字段超出其词汇范围。原因会指出字段和值。类别名称（xss、dos、disclosure……）会归入 category，不会被拒绝。
首次运行很慢／访问网络	全新机器会下载约 22 MB 的 tree-sitter 语法一次（--offline 不会阻止下载）。请提前预热，或设置 CODEINDEX_GRAMMARS_DIR。
限定范围的重新扫描似乎丢失了发现	使用 --merge——它会保留先前的判定，并保留范围外的发现。

常见错误

1. 通过相对路径运行引擎。 除技能目录外，在任何当前工作目录中都会失败。请使用绝对路径 <skill-dir>/scripts/ultrasec.mjs，并为子 Agent 提供相同路径。
2. 将降级运行报告为已完成。 请先检查 extraction/truncation/toolStatus。
3. 未阅读代码就提升候选项。 候选项的设计目标是尽可能提高召回率；阅读 dossier 才是工作的基本单位。
4. 把仅仅无法确认的内容判为不成立。 未能证明不等于证明其不成立——应标为 needs-human。
5. 将纵深防御评为 HIGH。 如果另一层能阻止问题，这只是加固建议。
6. 用 LOW 项凑数。 三个真实的 MEDIUM 项胜过十个理论上的 LOW 项。
7. 止步于扫描器。 它们覆盖已知模式；权限控制、业务逻辑和竞态问题才是人工检查发挥价值的地方。
8. 跳过 context。 没有信任模型，你评估的就只是抽象问题。
9. 只排查引擎列出的内容。 它能发现模式，而非缺失项——运行 guards，并使用两种视角。扫描器失败也是同一个陷阱：一个看起来像空结果的漏洞。
10. 输出转储内容，或把审计时间都花在 CVE 列表上。 有次运行生成了 882 个候选项，却一个都没有判定，还标注为“未确认任何问题”——根本没人检查过。建议已按优先级排序，数据流则没有：先读代码；DRAFT 横幅不算交付成果。

禁止事项

• 绝不手动编辑 findings.json。 这会绕过引用检查，并破坏由内容生成的 id，导致重新扫描和 --merge 无法保持幂等——请使用 investigate --apply。
• 绝不让子 Agent 运行 --apply 或 verify --shards。 两者都会写入运行目录；编排器是唯一写入者。
• 绝不自动驳回无法明确反驳的 HIGH/CRITICAL 级发现。
• 绝不编造 [file:line]。 请从 dossier、graph 或 rg -n 获取。
• 绝不运行会造成破坏或窃取数据的漏洞利用。 请用无害标记验证控制能力：sleep(5)、<b> 标签或金丝雀字符串。

范围说明

• 确定性核心，可选工具。 对未更改的仓库进行两次扫描，在相同提取层级上会得到相同的污点候选项；外部工具的结果取决于已安装的工具，也可能访问网络（咨询数据库）。不需要任何外部工具。
• 风险排序与关联具有确定性。 同一个问题被多个工具发现时，会合并为一个发现项，其 sources[] 会列出每个发现来源，并按 EPSS/KEV/CVSS 复合 risk 排序。数据源会缓存（每日 TTL）；计算过程离线进行。--offline 仅按严重性排序。
• 约 15 种语言适用于链接图（JS/TS、Python、Go、Java、Ruby、PHP、Rust、C/C++、C#、Kotlin、Swift、Scala、shell、Lua、Elixir）；目录对 Web 技术栈的覆盖最深入 — references/catalog.md。
• **它不会做什么：**不进行 DAST、不进行模糊测试、不进行身份验证后的爬取，也不进行运行时测试。references/attack-classes.md 中的每个类别都需要手动检查，而且单次扫描只会读取你深入检查过的路径 — 建议重新运行并使用 --merge。
• 经过测量。 OWASP Benchmark 上各 CWE 的得分： references/BENCHMARK.md，也包含不足之处 — 对注入问题表现出色，对不符合 source→sink 形态的问题则得分为零。coverage 会说明覆盖情况。
• 不能替代判断。 ultrasec 会将庞大的仓库范围缩小到少数有证据支持的候选项，并以机械方式验证那些枯燥的部分；安全判断由你负责。

参考资料

方法 — adjudication.md（误报分类、PoC 评估标准、示例） · severity-and-discipline.md（评估标准 + 校准示例） · citation-format.md（证据支撑约定） · schemas.md（所有工作清单 JSON）。

安全知识 — attack-classes.md（污点分析无法触及的类别） · access-control.md（IDOR/BOLA/BFLA，--lens access-control） · privacy-and-data-protection.md（数据传输、保留、假名化） · frameworks.md（各技术栈中容易被忽略的位置） · hunting-heuristics.md（攻击者视角 + 侦察命令） · supply-chain.md（依赖项、机密、CI、IaC） · catalog.md（引擎会枚举的内容）。

操作指南 — audit-playbook.md（标准） · deep-audit-playbook.md（深入） · scale-audit-playbook.md（大型仓库、CI） · context-playbook.md · investigate-playbook.md · revalidate-playbook.md · narrative-playbook.md · implement-playbook.md · log-forensics-playbook.md（蓝队） · probe-playbook.md（动态探测线上站点安全态势，隔离进行） · route-playbook.md（将范围外目标分流至工具） · powered-mode.md（自主运行）。

引擎 — commands.md（完整 CLI） · tools.md（扫描工具集） · tooling-internals.md。