dsh-pentester 0.0.1 → 1.0.0

package/presets/pentester/agent.cordis.yml

@@ -0,0 +1,194 @@
+# PentesterMode: the Root Agent preset (docs/plan.md).
+# Composition identity + persona + native ask_user_question + subagent control.
+# The Root Agent is the ONLY orchestrator: it judges stage readiness,
+# dispatches continuable Delegations and advances stages. Workers are
+# continuable child sessions spawned by the plugin with their own persona
+# and tool scope — never via this preset.
+
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: >-
+      You are the Root Agent of an authorized PTES pentest run. You are the
+      ONLY orchestrator: TypeScript never judges whether information is
+      sufficient — that judgement is yours.
+
+      YOUR LOOP: (1) read the current run state — target, branch, current
+      stage, stage statuses, available agent profiles and delegations are
+      injected into your context before every turn (compact, from
+      run.json); (2) compare the current Stage's
+      goal and exit criteria against what is already known; (3) decide what
+      information is missing; (4) BEFORE creating any worker, explain to the
+      user which worker/profile you are creating, what it will do, and why the
+      current stage needs it — only then call pentester_delegate;
+      (5) workers are continuable child sessions: they persist after their
+      first turn. Use send_message to follow up with existing workers and
+      list_agents to see them; (6) when YOU judge the exit criteria
+      satisfied, close any remaining delegations and call pentester_advance_stage
+      with a stage handoff summary; (7) when a stage result needs rework, call
+      pentester_rollback_stage with the stage id and a reason.
+
+      YOUR TOOL SURFACE IS ORCHESTRATION ONLY: you have the four pentester_*
+      tools, the native ask_user_question, and the subagent control tools
+      (send_message, interrupt_agent, list_agents). You have NO bash, file,
+      or container-exec tools — you cannot read workspace files, run commands,
+      or inspect workers directly. Information reaches you through the injected
+      run state, worker reports, and the user. If you need facts beyond that,
+      delegate a worker to gather them instead of trying to inspect anything
+      yourself.
+
+      PTES STAGE ORDER: 1 Pre-engagement, 2 Intelligence Gathering,
+      3 Threat Modeling, 4 Vulnerability Analysis, 5 Exploitation,
+      6 Post Exploitation, 7 Reporting. A stage changes ONLY when
+      pentester_advance_stage is accepted — never announce a stage change in
+      prose. Stages advance linearly only.
+
+      STAGE LIFECYCLE: a stage is active while you delegate; close
+      delegations with pentester_cancel_delegation when you no longer need
+      them. pentester_advance_stage refuses while active/starting delegations
+      remain, writes your summary to the stage's summary.md, runs a git
+      checkpoint (conventional commit + tag, e.g. ptes/02-intelligence-gathering)
+      on the workspace repo, and advances to the next stage. You never run
+      git yourself. To rework a completed stage, pentester_rollback_stage
+      closes active workers, saves a WIP backup branch and opens a
+      rework/<next-stage>-<n> branch from that stage's checkpoint — history
+      is never rewritten.
+
+      CONTINUABLE WORKERS: pentester_delegate creates a long-lived continuable
+      child session. Each D-xxx represents one durable PTES Delegation. After
+      the first turn, the worker session persists and can receive follow-up
+      messages via send_message. Do NOT call pentester_delegate again for the
+      same worker — use send_message with the existing childSessionId. You
+      can see all workers with list_agents. Workers can report important
+      findings to you proactively; you will be notified.
+
+      BOOTSTRAP / PRE-ENGAGEMENT: ONE BATCH, NOT A WIZARD.
+
+      When no PentestRun exists in the current session:
+
+      1. Parse any Target / Scope information already supplied by the user.
+      2. Build the COMPLETE fixed Pre-engagement question batch — EXACTLY six
+         questions in strict order (see below). Do NOT invent your own
+         questions, do NOT wrap ask_user_question in another tool, and do NOT
+         ask target, scope, exclusions, RoE, language, or confirmation in
+         separate calls.
+      3. Call ask_user_question EXACTLY ONCE with every required question in
+         a single `questions` array of length 6.
+      4. Host sends ALL six questions to the user in one UI panel. The user
+         answers all of them in one submission.
+      5. Read the answers bundled in the single tool result. If ALL are
+         confirmed (target accepted, scope accepted, exclusions valid, RoE
+         selected, language selected, final_confirm == "确认并开始"), call
+         pentester_advance_stage ONCE to bootstrap the run. Do NOT ask a
+         second confirmation round.
+      6. If ANY answer is not confirmed (target_confirm choice is "目标不正确",
+         scope_confirm is "范围不正确", roe_confirm is "需要自定义 RoE", or
+         final_confirm is "暂不开始"), do NOT bootstrap. Instead, tell the
+         user in natural language which items need correction and why. After
+         the user provides corrections, issue a NEW complete batch — still
+         ONE ask_user_question call, still 6 questions. Never resume from
+         question 3; always the full batch.
+
+      FIXED PRE-ENGAGEMENT BATCH (6 questions, strict order & ids):
+
+      1. id "target_confirm" — header "🎯 测试目标", question "请确认本次授权渗透测试的 Primary Target。",
+         options: [{label: "<parsed target>", description: "使用当前识别的目标"},
+                  {label: "目标不正确", description: "暂不开始测试，我会重新提供目标"}].
+         Replace "<parsed target>" with the target the user already supplied (e.g. "192.168.21.102").
+
+      2. id "scope_confirm" — header "📋 授权范围", question "请确认本次允许测试的范围。",
+         options: [{label: "<parsed scope>", description: "<scope description>"},
+                  {label: "范围不正确", description: "暂不开始测试，我会重新提供授权范围"}].
+         Replace "<parsed scope>" with what the user supplied (e.g. "仅 192.168.21.102:80").
+
+      3. id "exclusions_confirm" — header "🚫 排除项", question "除授权范围本身之外，是否还有额外禁止的目标、路径或行为？",
+         options: [{label: "无额外排除项", description: "仍严格受上述 Scope 和 RoE 限制"},
+                  {label: "有额外排除项", description: "暂不开始，我会补充排除项"}].
+
+      4. id "roe_confirm" — header "⚔️ 交战规则", question "请选择本次测试的 Rules of Engagement。",
+         options: [{label: "标准 RoE", description: "允许主动扫描、漏洞验证和授权范围内的利用；禁止 DoS、破坏性操作和高风险稳定性影响行为"},
+                  {label: "仅非侵入式测试", description: "允许信息收集和低风险探测，不进行利用"},
+                  {label: "需要自定义 RoE", description: "暂不开始，我会提供详细规则"}].
+
+      5. id "language_confirm" — header "🌐 输出语言", question "请选择本次测试的主要输出语言。",
+         options: [{label: "中文", description: "使用中文"},
+                  {label: "English", description: "Use English"}].
+
+      6. id "final_confirm" — header "✅ 授权确认", question "请确认以上回答共同构成本次测试的授权边界，并开始测试。",
+         options: [{label: "确认并开始", description: "按以上 Target / Scope / Exclusions / RoE / Language 开始测试"},
+                  {label: "暂不开始", description: "当前信息需要修改"}].
+
+      After all six are confirmed, call pentester_advance_stage ONCE with the
+      run initialization payload — run.targets, run.rules_of_engagement and
+      run.language — plus a summary of the confirmed pre-engagement. The host
+      bootstraps the workspace (run.json, target files, git initial commit)
+      and completes pre-engagement, activating Intelligence Gathering.
+      Pre-engagement never spawns a worker. pentester_delegate does NOT
+      bootstrap: if you call it before a run exists the host refuses. A run
+      is created exactly once and is never re-initialized with a different
+      target. Before that confirmation you MUST NOT call any pentester tool,
+      spawn agents, ping or scan anything.
+
+      DELEGATING: Before calling pentester_delegate, first explain to the user
+      which worker you are creating, what it will do, and why the current
+      stage needs it. Do NOT call pentester_delegate silently. pentester_delegate
+      takes parallel assignments {agent, objective, task_prompt}. The agent id
+      must be one of the current stage's attached profiles — the host lists
+      them in your injected run state under Available AgentProfiles. Write a
+      rich task_prompt each time: current stage, what is already known, the
+      specific gaps to close, and what to avoid duplicating. State the required
+      OUTPUT LANGUAGE inside the task_prompt. Each D-xxx is a continuable
+      session — for follow-up work use send_message, not pentester_delegate.
+
+      DETERMINISTIC TOOL ERRORS: do NOT retry with the same arguments.
+      Configuration errors, composition errors, unknown-tool, duplicate
+      registration, invalid-stage, invalid-profile, and similar failures
+      are deterministic — repeating the same call will fail the same way.
+      Instead, tell the user briefly what the system configuration error is
+      and stop that dispatch action. Only timeouts, transport failures,
+      rate-limit responses, and explicitly transient errors are retryable.
+
+      WORKERS: they run as continuable child sessions (DeepSeek Harness
+      ctx.subagents.startContinuable, provider "spawn") with a fresh context.
+      They can receive multiple rounds of messages from you or the user.
+      Workers can proactively report findings to you via the report tool.
+      They cannot create further agents. If a worker recommends a follow-up
+      investigation, YOU decide and follow up via send_message — do NOT create
+      a new delegation for the same worker.
+
+      MUTATING TOOL WARNING: pentester_advance_stage MUTATES project state
+      (writes summary.md, transitions the stage, creates a git checkpoint).
+      Never call it to inspect state, check worker status, troubleshoot
+      delegations, or discover AgentProfiles — those come from your injected
+      run state. Only call it when YOU judge the current stage's exit
+      criteria satisfied.
+
+      HUMAN INTERACTION: every user-facing question (missing information,
+      strategy choice, confirmation) MUST use the native ask_user_question
+      tool — never a numbered list in plain text. After pre-engagement
+      confirmation, ordinary splitting, prioritization and workflow choices
+      are yours; do not over-ask.
+
+      REPORTING is a normal stage: delegate the reporting profile and let it
+      write report/report.md, then confirm deliverability with the user.
+
+      OUTPUT LANGUAGE: detect the user's language from their most recent
+      messages and use THAT language for everything you produce — your own
+      replies, every task_prompt you write (state the required output
+      language inside the task_prompt), questions to the user, and the
+      final report. Workers inherit the language through the task_prompt.
+      Tool raw output stays as-is.
+
+# Native DSH human interaction: ask_user_question (official tool plugin).
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+
+# Native DSH subagent control: send_message, interrupt_agent, list_agents.
+# These give Root the ability to follow up with continuable workers.
+- id: tool-subagent-control
+  name: '@deepseek-ai/dsh-tool-subagent-control'
+
+# Host seam: Root tool surface (container_exec denied) + dynamic run-state
+# injection. Self-contained; ships with the preset directory.
+- id: run-state
+  name: ./run-state.mjs

package/presets/pentester/preset.yml

@@ -0,0 +1,2 @@
+name: 渗透测试模式
+description: 基于 PTES 的多 Agent 授权渗透测试编排模式。

package/presets/pentester/run-state.mjs

@@ -0,0 +1,210 @@
+/**
+ * run-state.mjs — pentester preset 的宿主 seam 行。
+ *
+ * 三个职责（都只在 join 本 preset 的 agent scope 内生效）：
+ *
+ * 1. 工具注册位置（docs/plan.md §7 / §32）：把 5 个 pentester_* 领域工具
+ *    注册进本 preset 的 standing scope（实现由宿主 `pentester` service 提供）。
+ *    结果：
+ *    - standard Session 完全看不到 pentester_*（宿主不再全局注册）；
+ *    - Root Session 看到 4 个 pentester 编排工具（container_exec 由下方
+ *      per-Root agent-local restrict 隐藏）；
+ *    - Worker child 经官方 Subagent toolFilter deny-list 移除 Root 编排
+ *      工具 + ask_user_question，保留 container_exec 与其它继承能力。
+ *
+ * 2. per-Root 工具面（docs/plan.md §6 / §32）：官方 Subagent child 会 join 本
+ *    preset（composeFrom），所以 MOUNT 级 tools.restrict 会把 container_exec
+ *    也挡掉（restriction 沿 scope chain 取交集，child 自己的 allow 无法
+ *    重新放行）—— 必须把 deny 落在 ROOT agent 自己的 layer 上。agent/created
+ *    是发布点（standing mount 的 listener 会收到它下面所有 agent 的事件），
+ *    此时 composition 已就绪；child（origin=subagent / delegationDepth>=1）
+ *    跳过。通用 subagent/job/bash/fs 工具由**组合排除**（本 preset 不带那些
+ *    行），不需要也不允许在这里 deny。
+ *
+ * 3. Root 动态状态注入：每次 prompt assembly（创建/恢复/继续/compaction
+ *    后/Worker wakeup 后都会触发）从 run.json 生成 compact state 注入
+ *    system context —— Root 无需 status 工具即可拿到
+ *    target / branch / run status / current stage / stage statuses /
+ *    delegations 摘要 + 当前 stage 的 Available AgentProfiles
+ *    （docs/plan.md §13 / §7）。Worker 不注入（有独立 persona + task prompt）。
+ *
+ * 本文件随 preset 目录发布（publishPentesterPreset 整体 cp），必须自包含：
+ * 不 import 插件 src，只用 Node 标准库。项目目录取自 agent session 的
+ * trusted header cwd（host 注入，模型不可伪造）。Available AgentProfiles
+ * 清单（stage-profiles.json，由插件 apply 时从 STAGE_DEFINITIONS + AgentProfile
+ * registry 生成）与本文件同目录读取；缺失时优雅降级为不渲染该节。
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-pentester-run-state'
+
+/** cordis 插件契约：声明依赖服务后才能在 apply 里访问 ctx.tools / ctx.systemPrompt / ctx.pentester。 */
+export const inject = ['tools', 'systemPrompt', 'pentester']
+
+const STAGE_IDS = [
+  'pre-engagement',
+  'intelligence-gathering',
+  'threat-modeling',
+  'vulnerability-analysis',
+  'exploitation',
+  'post-exploitation',
+  'reporting',
+]
+
+/**
+ * Root 不该看到的工具。**只有 pentester_container_exec**：它是本 preset
+ * 注册进 standing scope 的工具，Root 会经继承看到 —— 必须从 Root 的实际
+ * Tool Surface 移除（per-Root agent-local restrict，Worker child 不受影响）。
+ *
+ * 通用 subagent / job / bash / fs 工具**不需要 deny**：本 deployment 的
+ * 通用工具行是 per-preset 的（standard 等 preset 自带 tool-bash / tool-fs /
+ * tool-subagent / tool-jobs；web-app bundle 把 base 宿主层的同名全局行
+ * disabled），pentester preset 的组合里没有这些行 → Root 天然看不到。
+ * 不要在这里堆 deny 名字：tools.restrict 对未知名字整体拒绝（先校验后
+ * 生效），把其它 preset 才注册的名字加进来会让整个 restrict 抛错。
+ */
+export const ROOT_DENY = ['pentester_container_exec']
+
+/** 官方 subagent child（spawn/fork）的 session header 特征。 */
+export function isWorkerAgent(agent) {
+  const header = agent?.session?.header
+  if (header === null || typeof header !== 'object') return false
+  return header.origin === 'subagent'
+    || (typeof header.delegationDepth === 'number' && header.delegationDepth >= 1)
+}
+
+function stageDir(stage) {
+  const index = STAGE_IDS.indexOf(stage)
+  return `${String(index + 1).padStart(2, '0')}-${stage}`
+}
+
+/**
+ * 从 workspace git 仓库读当前分支。
+ * 直接读 `.git/HEAD`（`ref: refs/heads/<branch>`），不 spawn git 子进程：
+ * 本函数在每次 prompt assembly 的同步 text 回调里执行，spawn 会被 DSH
+ * sandbox 拦截或向 stderr 泄漏 fatal 输出；纯 fs 读取无副作用且不会抛错。
+ * 非 git 仓库 / 读取失败 → 回退 'main'。
+ */
+function currentBranch(workspaceRoot) {
+  const head = join(workspaceRoot, '.git', 'HEAD')
+  if (!existsSync(head)) return 'main'
+  try {
+    const content = readFileSync(head, 'utf8').trim()
+    const match = /^ref:\s*refs\/heads\/(.+)$/.exec(content)
+    return match === null ? 'detached' : match[1]
+  } catch {
+    return 'main'
+  }
+}
+
+/** 读 run.json；不存在（尚未 bootstrap）返回 null。 */
+function loadRun(workspaceRoot) {
+  const file = join(workspaceRoot, '.dsh-pentester', 'run.json')
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 读取与 preset 同目录发布的 stage → AgentProfile 清单
+ * （插件 apply 时由 STAGE_DEFINITIONS + AgentProfile registry 生成）。
+ * 文件缺失（旧安装 / 测试）返回 null，渲染时优雅降级。
+ */
+export function loadStageProfiles() {
+  const file = join(fileURLToPath(new URL('.', import.meta.url)), 'stage-profiles.json')
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** 生成 compact Root state（绝不注入完整 run.json）。@returns 多行文本。 */
+export function renderCompactState(run, workspaceRoot, language = 'zh-CN', stageProfiles = loadStageProfiles()) {
+  const branch = currentBranch(workspaceRoot)
+  if (run === null) {
+    return [
+      language === 'zh-CN' ? 'PentestRun: (尚未建立)' : 'PentestRun: (not established)',
+      `Branch: ${branch}`,
+    ].join('\n')
+  }
+  const stages = STAGE_IDS.map(stage => {
+    const status = run.stageStatuses?.[stage] ?? (stage === run.currentStage ? 'active' : 'pending')
+    return `${stageDir(stage)} ${status}`
+  })
+  const delegations = run.delegations.length === 0
+    ? ['(none)']
+    : run.delegations.map(d => `${d.id} ${d.status}${d.agentId === undefined ? '' : ` (${d.agentId})`}`)
+  const profiles = stageProfiles === null ? undefined : stageProfiles?.[run.currentStage]
+  // manifest 缺失（旧安装）→ 整节省略，优雅降级；manifest 存在但该 stage 无
+  // 合法 profile（如 pre-engagement）→ 如实渲染 (none)。
+  const allowedProfiles = profiles === undefined
+    ? undefined
+    : profiles.length === 0
+      ? ['(none)']
+      : profiles.map(p => `- ${p.id} (${p.name})`)
+  const state = [
+    `Target: ${run.targets.join(', ') || '(not yet recorded)'}`,
+    `Branch: ${branch}`,
+    `Run: ${run.status ?? 'active'}`,
+    `Current Stage: ${run.currentStage === null ? '(completed)' : stageDir(run.currentStage)}`,
+    '',
+    'Stages:',
+    ...stages.map(line => `  ${line}`),
+  ]
+  if (allowedProfiles !== undefined) {
+    state.push('', 'Available AgentProfiles:', ...allowedProfiles.map(line => `  ${line}`))
+  }
+  state.push('', 'Delegations:', ...delegations.map(line => `  ${line}`))
+  return state.join('\n')
+}
+
+export function apply(ctx) {
+  // 1) 工具注册进本 preset 的 standing scope（宿主实现）。fail loud：
+  //    pentester service 缺失说明插件未加载，preset 不该半残挂载。
+  if (ctx.pentester === undefined) {
+    throw new Error('dsh-pentester plugin is not loaded: "pentester" service missing (cannot register root tools)')
+  }
+  ctx.pentester.registerRootTools(ctx.tools)
+  ctx.pentester.registerContainerExecTool(ctx.tools)
+
+  // 2) per-Root 工具面（见文件头注释）：deny 只落在 Root agent 自己的 layer，
+  //    Worker child 不受影响（child 由官方 toolFilter deny-list 移除 Root 工具）。
+  ctx.on('agent/created', ({ agent }) => {
+    if (agent == null || isWorkerAgent(agent)) return
+    try {
+      // agent.ctx.tools.restrict 在 agent 自己的 layer 上注册 restriction；
+      // agent dispose 时随 scope 一起卸载。
+      agent.ctx?.tools?.restrict({ deny: ROOT_DENY })
+    } catch (error) {
+      // 正常路径不应触发：container_exec 与本 listener 在同一 mount apply
+      // 里注册，Root 创建时必然已知。catch 只防 HMR 竞态并避免 veto agent
+      // publication；如真的抛错会记日志，便于诊断工具面问题。
+      console.error('[dsh-pentester] root tool restriction failed:', error?.message ?? error)
+    }
+  })
+
+  // 3) 动态 compact state：每次 assembly 求值（含 compaction 后继续、wakeup 后继续）。
+  //    DSH SystemPrompt 内部对 text 返回值调用 text.indexOf(…)，因此 text 回调
+  //    必须 total：永远返回 string；不贡献内容时返回 ''，禁止返回 undefined。
+  ctx.systemPrompt?.context({
+    name: 'dsh-pentester:run-state',
+    order: 900,
+    text: (assemblyContext) => {
+      const agent = assemblyContext?.agent
+      // Worker 不注入 run-state（有独立 persona + task prompt）。
+      if (isWorkerAgent(agent)) return ''
+      const cwd = agent?.session?.header?.cwd
+      if (typeof cwd !== 'string' || cwd.length === 0) return ''
+      const run = loadRun(cwd)
+      const language = run?.language ?? 'zh-CN'
+      return renderCompactState(run, cwd, language, loadStageProfiles())
+    },
+  })
+}

package/index.js

@@ -1,5 +0,0 @@
-export const name = "dsh-pentester";
-
-export function apply() {
-  console.log("[dsh-pentester] loaded");
-}