appsec-agent

AppSec Agent

编排端到端的 OpenTaint 安全分析。将耗时的项目构建和每次全项目扫描都保留在此主会话中；把每个范围明确的 source、approximation、sink、triage 和 PoC 阶段委派给 orchestrate-stage 子 Agent，由其负责自己的叶节点扇出和汇总。

OpenTaint 是一种全程序、过程间、字段敏感的别名分析 SAST。运行会生成已确认的漏洞，以及可复用的项目专属规则和近似配置，并统一存放在项目根目录下独立完整的 .opentaint/ 目录中。

设置

1. 确认工具链

运行 opentaint -v，确认 opentaint 位于 PATH 中。如果缺少该工具，不要默默继续——请告知用户，并提供适用于其平台的安装命令；只有在用户明确确认后才执行安装：

• macOS / Linux，按顺序：brew install --cask seqra/tap/opentaint · npm install -g @seqra/opentaint
• Windows：npm install -g @seqra/opentaint

安装完成后，运行 opentaint health，确认所有问题都已解决。

2. 确认 Agent 嵌套

此工作流需要两层子 Agent：MAIN → 阶段编排器 → 叶节点。开始前确认运行环境允许嵌套深度为 2；否则请用户启用此功能。

3. 确定语言

读取项目的构建文件，以确定目标语言——Maven/Gradle → java，go.mod → go，依此类推。在引导阶段记录该语言；阶段编排器会将其传递给与语言相关的叶节点。

4. 选择工作流

请用户一次性选择以下两个级别：

1. 扫描级别 — lite · normal · deep
   • lite — 构建 + 扫描（已有产物时的预期选择）
   • normal — 构建 + 扫描 + 自定义近似配置
   • deep — 构建 + 扫描 + 自定义近似配置 + 自定义规则
   • 根据磁盘上的内容给出建议：首次运行（没有 .opentaint 产物）→ deep；已有先前运行的产物 → lite
2. Triage 级别 — static · dynamic
   • static — 根据模型对发现项分类，不运行应用
   • dynamic — 静态分析 + 为每个已确认的 TP 生成 PoC。此选项会在用户的机器上启动少量测试服务（本地实例和端口），并在运行结束时关闭。请明确告知用户这一点

5. 引导初始化

使用选定的级别和语言，为运行状态及工作树设置初始内容：

uv run <skill-dir>/scripts/generate.py init --scan-level <lite|normal|deep> --triage-level <static|dynamic> --language <lang>

此操作会写入 state.yaml、初始化 history.yaml、创建 .opentaint/ 目录树，并生成 tracking/rules/tags.yaml。全新的目录树会盘点内置 lib 标签；恢复使用的目录树会从内置标签和 .opentaint/rules 刷新。只有在需要明确恢复该注册表时才使用 generate.py tags。

工作流

运行采用固定流水线；所选级别决定涵盖哪些阶段。使用 uv run <skill-dir>/scripts/get_status.py 选择下一步操作：

build                       → MAIN: build
discover / source_rules     → stage subagent: sources
scan                        → MAIN: scan
approximations              → stage subagent: approx-round, then MAIN: rescan; repeat
sink_rules                  → stage subagent: sinks, then MAIN: rescan
triage                      → stage subagent: triage
poc                         → stage subagent: poc

在 MAIN 中构建

状态报告为 build 时，在此主会话中加载并遵循 build-project 技能。将 state.yaml 中已有的任何特定语言构建字段作为 build-hints 传入。通过运行环境的主会话后台命令功能执行耗时的构建命令，并等待其完成事件。

构建成功后，将所选 build-project 参考文档指定的特定语言构建字段写入 .opentaint/tracking/state.yaml。仅当没有未提交的源文件时，才将完整 HEAD 记录为 model_commit；否则将其设为 null。构建无法收敛会阻止整个运行，因为没有模型就无法继续后续阶段。

在 MAIN 中扫描

当状态报告显示 scan，或某个阶段返回时有待执行的重新扫描，请在此 MAIN 会话中加载并遵循 run-scan 技能。使用 harness 的主会话后台命令功能启动扫描，保留引擎自身的超时设置，另外添加 1200 秒的外部兜底超时，并等待进程完成事件。

有效的 .opentaint/results/report.sarif 表示扫描已完成，包括引擎超时后以退出码 254 结束的情况。如果扫描需要增加内存，请记录 max_memory: 16G，并在后续扫描中复用该值。如果经过允许的重试和兜底等待后仍无 SARIF 文件，若原因为格式错误的规则／近似，请按下方的修复路径处理；否则，使用 stage: escalation 和扫描的 setup 分派 orchestrate-stage，以记录扫描范围的资源问题，然后停止。

如果扫描或后续阶段报告近似存在格式错误、创建的规则无法加载、联接无效，或创建的规则存在误报／漏报，请按照 Dispatching 中的说明，将确切诊断和构件路径／ID 转交给负责的阶段 Agent，然后在 MAIN 中重新扫描。

每次构建、扫描或阶段返回后，运行一次 uv run <skill-dir>/scripts/get_status.py，以选择下一步操作。在运行开始时、恢复运行时，或简要输出无法明确回答问题时，使用 --full。

分派

每次调用阶段时，恰好分派一个阶段编排子 Agent：

Invoke the Skill orchestrate-stage first, then follow its instructions precisely
Inputs:
  stage: <sources|approx-round|sinks|triage|poc|escalation>

对于 deep 近似轮次，还要传入 sinks: true。子 Agent 会继承项目根目录作为工作目录，因此省略 project-root。

阶段上下文：

• sources — 发现依赖项来源，并编写按标签分组的来源规则
• approx-round — 对一个被丢弃方法的前沿进行分类和构建；每个新的前沿都使用一个全新的 Agent
• sinks — 编写经过分类的汇点规则并配置联接
• triage — 对最新发现进行分类并更新漏洞报告
• poc — 复现已确认的发现，并将结果添加到报告中
• escalation — 修复或处理某个阶段的构件，或报告扫描范围内的无 SARIF 文件故障

保留每个 Agent 的 ID，直到下一次扫描验证其构件。遇到由阶段负责的错误时，使用 stage: escalation、确切错误和构件路径／ID 恢复该 Agent。如果其会话不可用，则启动一个可重入的 orchestrate-stage Agent，并提供该诊断信息。

每次分派子 Agent 时都要使用全新 Agent，不要将上下文分叉给它。然后等待其自然完成，不要每分钟监控或轮询。如果 harness 强制设置等待超时，将其设为约 1 小时，并在超时返回后再次等待。

状态与恢复

使用此所有权映射来分派工作和扫描错误：

.opentaint/
  project/             MAIN build
  results/             MAIN scan
  rules/               sources or sinks stage
  pass-through/        approximation stage
  dataflow/            approximation stage
  tracking/state.yaml  MAIN run knobs
  tracking/            stage agents, leaves, and join scripts otherwise
  vulnerabilities.md   triage / PoC stage
  issues/               escalation stage

该树会长期保留。恢复运行时，复用 DONE 构件；get_status.py 会根据磁盘内容推导下一阶段。现有规则和近似适用于每次扫描。

state.yaml 的结构：

scan_level: deep
triage_level: dynamic
language: <language>
model_commit: 0123456789abcdef0123456789abcdef01234567
max_memory: null

所选 build-project 语言参考可能会定义其他构建字段；恢复运行时请保留这些字段，并将其作为 build-hints 传回。

关键约束

• 通过 <skill-dir>/scripts/get_status.py 读取流水线状态，不要手动操作；不要通过 glob／grep／python3 -c／扫描 .opentaint/tracking、results 或 *.yaml 来重新推导状态，也不要仅为查看进度而打开发现项／单元／SARIF 文件。如果其输出仍无法明确回答问题，打开任何文件前先使用 --full 重新运行
• 不要编写或编辑由阶段负责的构件或跟踪数据；MAIN 只能在 state.yaml 中写入 model_commit、max_memory 以及所选 build-project 参考定义的构建字段
• 整个运行只保留一个生成的项目模型；分析过程中绝不要手动编辑或替换它——修复构建并重新构建，然后再开始新的运行