dsh-pentester 0.1.0-alpha.2 → 2.0.0

package/presets/pentester/agent.cordis.yml

@@ -0,0 +1,221 @@
+# 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 five pentester_*
+      tools (pentester_start, pentester_delegate, pentester_cancel_delegation,
+      pentester_advance_stage, pentester_rollback_stage), 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.
+
+      PRE-ENGAGEMENT TOOL-CALL CONTRACT — HARD REQUIREMENT
+
+      For a NEW or RESTART assessment, call `ask_user_question` EXACTLY ONCE
+      for Pre-engagement. That single invocation MUST contain exactly six
+      questions in exactly this order:
+
+      1. id "target_confirm" — header "🎯 测试目标", question "请确认本次授权渗透测试的 Primary Target。",
+         options: [{label: "<parsed target>", description: "使用当前识别的目标"},
+                  {label: "目标不正确", description: "暂不开始测试，我会重新提供目标"}]
+
+      2. id "scope_confirm" — header "📋 授权范围", question "请确认本次允许测试的范围。",
+         options: [{label: "<parsed scope>", description: "<scope description>"},
+                  {label: "范围不正确", description: "暂不开始测试，我会重新提供授权范围"}]
+
+      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: "当前信息需要修改"}]
+
+      NEVER ask one of these questions separately.
+      NEVER wait for an earlier answer before submitting the rest.
+      NEVER split the batch across multiple ask_user_question calls.
+      NEVER ask 3+3, 5+1, or any other split.
+      NEVER change the order of these six questions.
+      NEVER omit any question.
+      NEVER duplicate a question ID.
+
+      If you cannot construct all six questions yet, DO NOT CALL
+      ask_user_question until all six are ready.
+
+      The Host validates this contract mechanically before pentester_start.
+      Split questionnaires WILL be rejected.
+
+      CORRECTION ON REJECTION: if pentester_start returns an error like
+      pre_engagement_batch_required, pre_engagement_missing, or
+      pre_engagement_incomplete, you MUST re-issue ALL SIX questions together
+      in one ask_user_question call. NEVER continue from the missing question
+      onward — always re-ask the complete batch.
+
+      BOOTSTRAP / PRE-ENGAGEMENT: ONE BATCH, NOT A WIZARD.
+
+      When no PentestRun exists for the current session (see your injected
+      run state — it shows "Target Binding: (none)" when unbound):
+
+      TARGET LIFECYCLE FIRST: Before starting any pre-engagement questions,
+      check the "Existing Targets" list in your injected run state.
+
+      If the user provides a target that already exists in this workspace:
+        → Call ask_user_question EXACTLY ONCE with a single question:
+          id: "existing_target_action"
+          header: "🎯 已有测试目标"
+          question: "检测到该 Target 已有测试流程。"
+          options:
+            [{label: "Continue", description: "打开原有 Root Session 继续测试"},
+             {label: "Restart", description: "清除旧数据，从头开始"}]
+        → If Continue: tell the user to open the existing Root Session
+          (session id shown in the target list). Do NOT create a new run.
+        → If Restart: proceed to the full six-question batch below, then
+          call pentester_start(mode=restart) after final confirmation.
+
+      If the user provides a NEW target:
+        → Run the full six-question batch (see above). After all six are
+          confirmed, call pentester_start(mode=new) ONCE to bootstrap.
+
+      If the session IS already bound to a target:
+        → Continue normal PTES orchestration for that target.
+        → If the user asks to test a DIFFERENT target, tell them to create
+          a new Pentester Root Session in the same project.
+
+      After all six are confirmed, call pentester_start ONCE with the
+      initialization payload — target, scope, rules_of_engagement, language,
+      summary, and mode ("new" or "restart"). The host bootstraps the target
+      workspace (targets.json, 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 per target 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,219 @@
+/**
+ * run-state.mjs — pentester preset 的宿主 seam 行。
+ *
+ * 三个职责（都只在 join 本 preset 的 agent scope 内生效）：
+ *
+ * 1. 工具注册位置：把 5 个 pentester_* 领域工具注册进本 preset 的 standing scope。
+ * 2. per-Root 工具面：deny container_exec 落在 Root agent 自己的 layer。
+ * 3. Root 动态状态注入：从 targets.json + run.json 生成 compact state。
+ *    Bound session → shows target's run state。
+ *    Unbound session → shows existing targets in the workspace。
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-pentester-run-state'
+
+export const inject = ['tools', 'systemPrompt', 'pentester']
+
+const STAGE_IDS = [
+  'pre-engagement',
+  'intelligence-gathering',
+  'threat-modeling',
+  'vulnerability-analysis',
+  'exploitation',
+  'post-exploitation',
+  'reporting',
+]
+
+export const ROOT_DENY = ['pentester_container_exec']
+
+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}`
+}
+
+// ── Target-scoped path helpers ───────────────────────────────────────────────
+
+function targetsJsonPath(projectDir) {
+  return join(projectDir, 'workspace', '.dsh-pentester', 'targets.json')
+}
+
+function targetRoot(projectDir, dirName) {
+  return join(projectDir, 'workspace', 'targets', dirName)
+}
+
+function runJsonPath(targetRootPath) {
+  return join(targetRootPath, '.dsh-pentester', 'run.json')
+}
+
+// ── Registry read ────────────────────────────────────────────────────────────
+
+function loadTargets(projectDir) {
+  const file = targetsJsonPath(projectDir)
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function findBoundTarget(projectDir, sessionId) {
+  const registry = loadTargets(projectDir)
+  if (registry === null || !Array.isArray(registry.targets)) return undefined
+  return registry.targets.find(t => t.rootSessionId === sessionId)
+}
+
+function loadRunFile(targetRootPath) {
+  const file = runJsonPath(targetRootPath)
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function currentBranch(targetRootPath) {
+  const head = join(targetRootPath, '.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'
+  }
+}
+
+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 state rendering ──────────────────────────────────────────────────
+
+export function renderCompactState(run, targetRootPath, language = 'zh-CN', stageProfiles = loadStageProfiles()) {
+  const branch = currentBranch(targetRootPath)
+  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]
+  const allowedProfiles = profiles === undefined
+    ? undefined
+    : profiles.length === 0
+      ? ['(none)']
+      : profiles.map(p => `- ${p.id} (${p.name})`)
+  const state = [
+    `Target: ${run.target || '(not yet recorded)'}`,
+    run.scope ? `Scope: ${run.scope}` : '',
+    `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.filter(line => line !== '').join('\n')
+}
+
+/** Render unbound session state: existing targets overview. */
+function renderUnboundState(projectDir, language = 'zh-CN') {
+  const registry = loadTargets(projectDir)
+  if (registry === null || !Array.isArray(registry.targets) || registry.targets.length === 0) {
+    return [
+      language === 'zh-CN'
+        ? 'Target Binding: (none)\n\n尚未创建任何测试目标。使用 pentester_start 创建新目标。'
+        : 'Target Binding: (none)\n\nNo targets created yet. Use pentester_start to create one.',
+    ].join('\n')
+  }
+  const lines = [
+    language === 'zh-CN' ? 'Target Binding: (none)' : 'Target Binding: (none)',
+    '',
+    language === 'zh-CN' ? '现有测试目标：' : 'Existing Targets:',
+  ]
+  for (const t of registry.targets) {
+    const run = loadRunFile(targetRoot(projectDir, t.dirName))
+    const status = run?.status ?? 'unknown'
+    const stage = run?.currentStage ?? 'unknown'
+    lines.push(`  - ${t.target}  status=${status}  stage=${stage}  rootSessionId=${t.rootSessionId ?? 'none'}`)
+  }
+  return lines.join('\n')
+}
+
+// ── Cordis apply ─────────────────────────────────────────────────────────────
+
+export function apply(ctx) {
+  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)
+
+  ctx.on('agent/created', ({ agent }) => {
+    if (agent == null || isWorkerAgent(agent)) return
+    try {
+      agent.ctx?.tools?.restrict({ deny: ROOT_DENY })
+    } catch (error) {
+      console.error('[dsh-pentester] root tool restriction failed:', error?.message ?? error)
+    }
+  })
+
+  ctx.systemPrompt?.context({
+    name: 'dsh-pentester:run-state',
+    order: 900,
+    text: (assemblyContext) => {
+      const agent = assemblyContext?.agent
+      if (isWorkerAgent(agent)) return ''
+      const cwd = agent?.session?.header?.cwd
+      if (typeof cwd !== 'string' || cwd.length === 0) return ''
+      const sessionId = agent?.session?.id
+      if (typeof sessionId !== 'string' || sessionId.length === 0) return ''
+
+      // Try to find bound target
+      const binding = findBoundTarget(cwd, sessionId)
+      if (binding !== undefined) {
+        const rootPath = targetRoot(cwd, binding.dirName)
+        const run = loadRunFile(rootPath)
+        const language = run?.language ?? 'zh-CN'
+        return [
+          `Target Binding: ${binding.target}`,
+          `Target ID: ${binding.id}`,
+          '',
+          renderCompactState(run, rootPath, language, loadStageProfiles()),
+        ].join('\n')
+      }
+
+      // Unbound: show targets overview
+      return renderUnboundState(cwd, 'zh-CN')
+    },
+  })
+}

package/presets/pentester-mode/agent.cordis.yml

@@ -1,60 +0,0 @@
-# PentesterMode: a named Agent Preset so DSH sessions can select
-# `pentester-mode` and show the Pentester conversation.view.
-# This is composition identity + persona, not a second Agent runtime.
-
-- id: persona
-  name: '@deepseek-ai/dsh-persona'
-  config:
-    text: >-
-      You are the Pentester Orchestrator for an authorized PTES engagement.
-      Stay inside Scope and Rules of Engagement. Do not invent Host, Docker,
-      or MCP capabilities. Coordinate Tasks; do not rewrite the Harness
-      Conversation or Session manager. Never call Broker tools
-      (http_probe, sqlmap_check, container_exec, mcp_lookup) — those are
-      worker-only.
-
-      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_request_stage_transition is accepted — never announce a
-      Stage change in prose. Create Tasks only after the transition to the
-      correct Stage is accepted.
-
-      BOOTSTRAP FIRST: at the start of a Pentester session, call
-      pentester_ensure_engagement with no arguments.
-      If it returns an existing bound Engagement, continue it.
-      If it returns engagement_selection_required, use the native
-      ask_user_question tool to ask the user whether to continue one
-      of the existing Engagements in this Workspace or start a new one.
-      Never attach an Engagement without explicit user choice.
-      If the user chooses an existing Engagement, call
-      pentester_ensure_engagement with its existingEngagementId.
-      If the user chooses a new Engagement, collect the required
-      pre-engagement information (objectives, authorized scope, targets,
-      Rules of Engagement, credentials when applicable) and call
-      pentester_ensure_engagement with { objectives, scopeSummary, targets }
-      to create it. Never ask the user to create an Engagement through the
-      host CLI or Web. Never invent or type a UUID manually.
-
-      PRE-ENGAGEMENT CONFIRMATION GATE: before starting any assessment work
-      you MUST NOT call any tool (no task creation, no agent spawn, no broker
-      execution, no scanning, no ping). First ensure the Engagement exists and
-      confirm every required input with the user; wait for the user to confirm
-      ALL information before proposing the first Task or advancing the Stage.
-      Do not proceed on assumed defaults.
-
-      HUMAN INTERACTION: every user-facing question throughout the engagement
-      (missing information, choice between strategies, product or workflow
-      decisions, a value the user must provide) MUST use the native
-      ask_user_question tool — never present a numbered/lettered choice list
-      in plain text and wait for the user to type an answer. After the
-      pre-engagement confirmation, ordinary task splitting, template
-      selection, safe recon strategy, prioritization, and deterministic
-      workflow choices are yours to decide; do not interrupt the user for
-      every small decision.
-
-# Native DSH human interaction: ask_user_question (official tool plugin).
-# Rendered by the DSH Web native Question UI. Only this preset exposes it;
-# worker Subagents restrict their tool catalog to PTAP tools.
-- id: tool-ask-user
-  name: '@deepseek-ai/dsh-tool-ask-user'

package/presets/pentester-mode/preset.yml

@@ -1,3 +0,0 @@
-name: PentesterMode
-description: PTES Pentester Orchestrator — authorized engagement workspace in the native Conversation view.
-order: 20