# dsh-pentester

一次授权渗透测试活动的领域：Project 是工作区，PentestRun 是一次测试，Stage 推进流程，Root Agent 通过 Delegation 派发 AgentProfile，产物就是 Deliverable 文件。

## Language

### Run

**Project**:
承载一次渗透测试的工作区根目录。一个 Project 可以包含多个 Target，每个 Target 有独立的 PentestRun。
_Avoid_: Engagement, workspace（当指领域对象时）, session

**PentestRun**:
一次完整的授权安全测试活动，针对单一 Target，从 Pre-engagement 到 Reporting。
持有双重身份：`id`（内部 UUID，durable identity）与 `instanceId`（7 位
lowercase hex 的人类可读 Run Instance Identity，显示为 `#abcd123`；Docker
容器名 `dsh-pentester-<instanceId>`，身份权威是 Docker labels）。
生命周期（`pentester_run` 唯一管理）：`active → stop → stopped → resume →
active`；reporting 完成后 `completed`（终态）。stop 是可逆暂停（同 run 同
instanceId，数据全保留）；Restart = 新 PentestRun 实例（新 UUID + 新
instanceId，绝不复用旧值）。
_Avoid_: Engagement, session, pentest job

**Bootstrap**:
首次初始化。Pre-engagement 不创建 Worker（由 User + Root + `ask_user_question`
完成）；由 `pentester_run({action:"start"})` 创建 Target 记录、workspace 骨架、
run.json、target 文件并 git init，随后完成 pre-engagement checkpoint 并激活
intelligence-gathering。`pentester_delegate` 不 bootstrap，无 Run 时明确报错。
_Avoid_: 在 delegate 里初始化 run

**Target**:
创建 PentestRun 时用户明确给出的测试入口与边界。每个 Target 有独立的 Run、
Root Session、Git 仓库和 Toolbox 运行时。
_Avoid_: Asset, host, URL（当指初始意图时）

**TargetContext**:
解析后的 Target 上下文，是所有 target-scoped 操作的唯一路径解析器。所有
target 级函数（store、workspace、git、docker）必须先 resolve TargetContext。
_Avoid_: 直接使用 projectDir 做 target 级操作

**Stage**:
PTES 生命周期中的一个业务阶段，共七个。Stage 的推进由 Root Agent 判断、host 只校验线性顺序；Stage Advance Policy 为 manual/custom 时 host 额外要求人工推进确认（见 StageAdvancePolicy）。
_Avoid_: Agent, phase（泛称）, workflow state machine

**Delegation**:
Root Agent 发起的一次委托 = 一个 DSH 官方 continuable child 会话
（`ctx.subagents.startContinuable('spawn')`，durable child 跨 Activation 持续，官方管理 cold resume）。持不可变的 task_prompt snapshot；可并行存在多个。
状态：`starting → active → cancelling → closed`（或 interrupted/failed）；
cancel 必须携带经验证的 Harness interrupt authority（live Root agent 为
ancestor，或 registry 记录的 Root session id 为 direct parent —— 绝不是
child 自己的 id）；UNAUTHORIZED/interrupt 失败 fail loud，绝不伪装 closed。
interrupt 准许后先进入 cancelling 并排空该 Delegation 已准入的 in-flight
command，再落 closed。
_Avoid_: Task, Agent Run, job, spawn request

**Deliverable**:
Delegation 产出的文件，落在 `workspace/stages/<NN>-<stage>/delegations/D-00N/` 目录（work/ artifacts/ evidence/ result.md）。文件即交付物，没有数据库实体。
_Avoid_: Artifact, Evidence, Finding Occurrence（作为实体类型时）

**StageStatus**:
Stage 生命周期状态：`pending → active → reviewing → completed`。进入阶段为 active；该阶段最后一个 delegation 结算后 host 标 reviewing；advance 时标 completed 并进入下一阶段 active。记录在 run.json 的 `stageStatuses`。
_Avoid_: workflow state machine

**result.md**:
Delegation 的当前正式可交付结果。Worker 写/更新 result.md 作为当前产出（不是 Session 终止标志）；continuable child 跨轮持续，宿主不做自动 settle/完成检测。宿主不自动生成；Worker 每轮最终回复总结所做、所发现、所写文件与下一步建议。
_Avoid_: submission, completion receipt 文件

**StageAdvancePolicy**:
Pre-engagement 第 6 题（`stage_advance_policy`）的权威记录，由 Host 从验证后的
ask_user_question proof 派生并持久化到 run.json（`stageAdvancePolicy` 字段；旧 Run
缺省 = automatic）。`automatic`：Root 判断 Exit Criteria 满足后自主推进；
`manual`：每次 advance 前必须获得针对当前 Stage 的人工确认（ask_user_question
id `stage_advance_confirm:<stageId>`，且晚于该 Stage 当前 entry —— 跨 Stage 不可
复用），否则 `stage_advance_confirmation_required`；`custom`：用户自定义规则，
Host 不解释自然语言，保守按 manual gate 处理，instruction 注入 Root 状态。
_Avoid_: approval flow, criteria engine

**Stage summary**:
每个已完成 Stage 的 `stages/<NN>-<stage>/summary.md`。内容由 Root 通过 `pentester_advance_stage(summary)` 提供，宿主只写磁盘、不解析。
_Avoid_: stage report, handoff document 实体

**delivery receipt**:
宿主可按需读取的 delegation 交付 compact 清单（result.md + artifacts/evidence 文件路径）。只存在于运行时响应，不持久化（continuable 模式下不自动 settle）。
_Avoid_: INDEX, catalog, registry

**GitCheckpoint**:
每阶段完成时宿主对 workspace git 仓库执行的约定式 commit + tag（`ptes(<NN>-<stage>): complete` / `ptes/<NN>-<stage>`）。git 仓库只在宿主侧（`workspace/.git`），Worker 容器内无 .git；run.json 位于 git 树内，checkpoint 记录 transition 后的机器状态。
_Avoid_: 让 Worker 执行 git

**rollback**:
Root 通过 `pentester_rollback_stage(stage, reason)` 把 timeline 回退到某已完成 Stage 的 checkpoint，从下一 Stage 的 rework branch 重新开始。宿主先取消 running workers、dirty 时保存 WIP backup branch，不重写历史。
_Avoid_: git reset, undo, revert

**rework timeline**:
rollback 后从 checkpoint 创建的新分支（`rework/<next-stage>-<n>`），是新的 active PTES timeline。D-ID 在 branch timeline 内跨 Stage 全局递增，新 branch 允许复用旧编号。
_Avoid_: global D-ID allocator, timeline controller

### Agents

**Root Agent**:
唯一的 Orchestrator。读取 Stage goal / exit criteria / 已有交付物，判断信息缺口，派发 Delegation，决定何时 advance stage。
_Avoid_: OrchestratorController, Workflow Engine, DecisionEngine

**AgentProfile**:
可复用的专家角色定义，分两层：磁盘上的原始定义（`AgentProfileDefinition`：system prompt + skills + model + 单继承字段 extends/skills/skillsRemove/systemPromptAppend）与继承解析后的 `ResolvedAgentProfile`（含 extendsChain + revision）。存放在 `agents/<id>/profile.yml`（builtin，只读）或 `$DSH_HOME/dsh-pentester/agents/<id>/profile.yml`（custom，可读写）。
_Avoid_: Agent Template, Agent Run, persona card

**Agent Library**:
统一的 Agent/Skill 注册表（`src/agent-library/`）：builtin + custom 双 Map、profile 单继承解析（cycle/缺失 base 检测）、skill bundle 扫描、custom watcher（fs.watch + debounce + last-known-good）、Agent/Skill CRUD。ID 全局唯一（builtin 优先），Name 也全局唯一。
_Avoid_: profile registry file, stage-profiles.json

**Skill Bundle**:
`*.skill` 目录 + 必填 `SKILL.md`（frontmatter 定义 id/name/description）。`*.skills` 是顶层 Bundle（一等 Registry 实体，可整体分配，ID = 目录名去 .skills 后缀）；`*.skill` 是 Leaf Skill（可独立分配，Bundle 内 Leaf 亦可单独分配）。loader 遇 `*.skill` 停止深入。bundle 内禁止 symlink、限制大小；bundle path ≠ identity。
_Avoid_: skill folder（当指 bundle 时）, tool skill

**Skill Grant（Assignment）**:
Agent Profile 里 `skills`（grant/add，bundle 或 leaf）+ `skillsRemove`（减除）解析后得到 `allowedSkillIds` = Agent 被授权的能力边界。Assignment ≠ Catalog ≠ Load：授权 150 不等于 catalog 150，更不等于加载 150。Builtin 有默认 Grant，用户可 Create Profile From This / skills / skillsRemove / Builtin Override / Reset Override。
_Avoid_: 预加载, assigned skills 注入 prompt

**Skill Grant Snapshot（Frozen Grant）**:
Delegation 创建时把 allowedSkillIds 的 skill bundle 复制到 Host-private frozen snapshot（`pentesterHome/runtime/skill-snapshots/…`，不进 /workspace）并写 `manifest.json`（name/description/revision/relativeBundle）。此后 Settings 改动不影响该 Delegation；冷启动 resume 重新挂载同一 manifest。
_Avoid_: mutable grant, live library re-read

**Native Skill Catalog**:
Worker Session 经官方 `@deepseek-ai/dsh-tool-skill` 看到的 Skill summaries（durable user/message source.kind=skill-catalog，只含 name+description）。Catalog 精确等于该 Delegation 的 frozen grant —— 由 child-scoped provider `dsh-pentester-frozen` 提供，global/user/project unrelated skills 被同层遮蔽（mask）不进入模型面。
_Avoid_: persona 注入 catalog, 截断 skill 数量

**Native Skill Load**:
模型调用官方 `skill({name})` tool；Harness 从 child-scoped frozen SkillProvider on-demand 读取 SKILL.md 正文，返回标准 `<skill_content>` 结果（官方 Skill Row 渲染）。Loaded Skills 从 0 开始按 unique successful loads 增长。
_Avoid_: pentester_skill_load, 批量 preload

**Skill Search（V2.3，非 Worker runtime）**:
BM25/alias/relation/MMR 检索引擎，用于 Agent grant curation、Settings 推荐、benchmark 与离线分析；不再是 Worker 工具面（Worker 的路由由 native catalog + 模型决策完成）。
_Avoid_: 全局搜索, semantic/vector search（未启用）

**stageAgents (Settings V2+)**:
`settings.json` 的 `stageAgents: Record<StageId, string[]>`：每个 PTES Stage 允许 Root 使用的 Agent id 列表（默认 `DEFAULT_STAGE_AGENTS`——Agent Topology V3：19 Builtin Agents，18 个进入默认 PTES，ctf 为 Library-only；Pre-engagement 恒为空）。Root 只能从「当前 stage 允许的 Agent」中选择派发。`stageAgentsDefaultsVersion`（Settings V4）记录配置对齐的默认拓扑版本：升级时仍等于旧默认的 Stage 自动升级到新默认，用户改过的 Stage 原样保留。
_Avoid_: stage agentIds（stages.ts 硬编码）

**MCP Server**:
Host-side external tool provider, loaded through official
`@deepseek-ai/dsh-mcp-client`（stdio 进程跑在 DSH Host 上，不在 Pentester
Kali 容器中；HTTP 由 Host 直连远端）。定义在 `settings.json` V3 的
`mcpServers`（id → definition，discriminated union on transport）。工具经
官方 client 注册为 global ToolRuntime 工具
`mcp__<serverName>__<rawName>`；同一 server 的实例是 Host 共享的。
_Avoid_: MCP connection per Worker, MCP in Kali, mcp_lookup

**MCP Assignment**:
AgentProfile `mcps` + `mcpsRemove` resolved into the fixed MCP tool
surface a Delegation receives（继承语义与 Skill Grant 同构：parent + adds −
removes → dedup → deterministic sort）。Delegation 创建时经 Mandatory
Gate resolve 成 `toolFilter.allow` 的精确工具名集合 —— Worker 第一轮模型
请求即拥有；官方 continuable descriptor 在 cold resume 时重建相同可见性。
**Assignment ≠ Skill Load**：MCP 没有 Search/Load 步骤（对比 Skill 的
on-demand Search/Load 语义）。
_Avoid_: pentester_mcp_search, pentester_mcp_load, MCP Bundle, Capability Grant

**task_prompt**:
Root Agent 为某一次 Delegation 动态生成的任务上下文，持久化为不可变 snapshot（`input/task_prompt.md`）。
_Avoid_: system prompt, ContextBundle

**Worker**:
一个 Delegation 对应的执行 Agent（官方 `ctx.subagents.startContinuable('spawn')` 的 durable continuable child session，fresh context，不继承 Root transcript；可接收多轮 send_message）。不能创建其他 Delegation；编排树只有 Root → Workers 一层。
_Avoid_: Subagent tree, nested delegation

### Execution

**Toolbox Image**:
由本项目维护的 Dockerfile 构建出的容器镜像，是 container_exec 唯一允许的镜像来源。
_Avoid_: arbitrary image, docker pull at runtime

**container_exec**:
Worker 在 Toolbox 容器内执行命令的唯一工具。执行前有正式准入
（run 与 Delegation 必须 active，且 exec 启动前重读 authoritative run.json
作 race fence）；结果为结构化 discriminated status
（completed / timed_out / cancelled / runtime_error），未知退出状态绝不报
exitCode=0；timeout/AbortSignal 经 supervision guard 真正终止容器内命令
（TERM → grace → KILL，命令级、绝不 kill 共享的 Run Container）；
stdout/stderr 每流有界保留（truncated 标记）。
_Avoid_: host shell, Tool Broker, exec RPC

**authorized assessment**:
目标方明确允许的安全评估。本产品只服务这种工作。
_Avoid_: attack, hack, exploit development

### Not this glossary

Harness 打包与 Cordis 用词（bundle、profile、plugin、inject、Fiber）不是 PTES 领域对象。

## Runtime（Wave 14）

| 术语 | 定义 |
| --- | --- |
| **Runtime** | Pentester Worker 实际运行 `pentester_exec` 的执行环境（Docker 容器或远端 SSH 主机）。 |
| **RuntimeProfile** | 长期保存的 Runtime 配置（id / name / aliases / type / enabled / revision / config）。secret 只有 `credentialRef`。 |
| **FrozenRuntime** | PentestRun 创建时从 profile 拍下的不可变快照（`run.runtime`）。Run 内所有 Delegation 继承它；profile 之后被编辑 / 删除都不影响该 Run。 |
| **RuntimeManager** | Runtime 的唯一权威：profile CRUD、healthCheck、freeze、按 Run 返回 ExecutionRuntime、首条 prompt 的 runtime 匹配。 |
| **ExecutionRuntime** | Docker / SSH 共同实现的执行接口：prepare / healthCheck / exec / pushWorkspace / pullWorkspace / dispose。上层只认识它。 |
| **ExecutionService** | `pentester_exec` 的编排层：caller 校验、TargetContext / PentestRun / Delegation 解析、准入与 race 复核、逻辑 cwd 校验、Runtime 解析、exec 跟踪、审计、结果投影。 |
| **pentester_exec** | Worker 唯一的执行工具（argv 语义 + 逻辑 cwd）。Wave 14 起取代 `pentester_container_exec`（后者只作历史回放的只读兼容）。 |
| **FrozenRuntime 冻结失败** | healthCheck 未 ready → PentestRun 不创建，返回稳定错误码（runtime_unreachable / runtime_auth_failed / runtime_misconfigured / runtime_workspace_unwritable / runtime_image_missing / runtime_disabled / runtime_required / runtime_unavailable）。 |
| **Intake / Intake field** | Pre-engagement 的 8 个字段（runtime / target / scope / exclusions / rules_of_engagement / language / stage_advance_policy / final_confirmation）。首条 prompt 是信息源，只补问缺失字段。 |
| **ExecutionAudit** | 每次执行的结构化审计（executionId / runId / delegationId / stageId / runtime / argv 安全展示版本 / 时间 / 状态 / exitCode / timeout / truncation）。durable JSONL 位于 `<targetRoot>/.dsh-pentester/executions.jsonl`。 |