@gpzhang2001/sharpkit-reporting 0.2.1 → 0.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gpzhang2001/sharpkit-reporting",
   "description": "Vulnerability/dependency reporting tools + sharpkit_runs artifacts (run.json, vuln markdown, csv/json, SARIF 2.1.0)",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "publishConfig": {
     "access": "public"
   },

package/src/index.ts

@@ -11,8 +11,9 @@
  * @module @gpzhang2001/sharpkit-reporting
  */
 
+import { existsSync } from 'node:fs'
 import { mkdir, readFile } from 'node:fs/promises'
-import { join, resolve } from 'node:path'
+import { isAbsolute, join, resolve } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type Schema from '@deepseek-ai/schemastery'
 import z from '@deepseek-ai/schemastery'
@@ -245,8 +246,11 @@ const DYNAMIC_ONLY_UPDATE_FIELDS = new Set(['endpoint', 'method', 'poc_descripti
 
 export interface ReportingHandle {
   readonly state: ReportState
+  /** Directory of the most recently resolved run (sync view; resolve via {@link runDirFor} for accuracy). */
   readonly runDir: string
-  finishScan(sections: { readonly executiveSummary: string; readonly methodology: string; readonly technicalAnalysis: string; readonly recommendations: string }, status?: string): Promise<void>
+  /** Resolve (memoize per scan) this session's run directory — see apply() for the rules. */
+  runDirFor(session: unknown): Promise<string>
+  finishScan(sections: { readonly executiveSummary: string; readonly methodology: string; readonly technicalAnalysis: string; readonly recommendations: string }, status?: string, extras?: Readonly<Record<string, unknown>>): Promise<void>
   writeNow(): Promise<void>
   readRaw(relative: string): Promise<string>
 }
@@ -364,42 +368,178 @@ interface GetArgs {
 
 export function apply(ctx: Context, config: Config = {}): ReportingHandle {
   const runsRoot = config.runsRoot ?? 'sharpkit_runs'
-  const runName = config.runName ?? `pentest-${Math.random().toString(16).slice(2, 6)}`
-  const runDir = resolve(join(resolve(runsRoot), runName))
-  const state = new ReportState({ runName })
+  const fallbackRunName = config.runName ?? `pentest-${Math.random().toString(16).slice(2, 6)}`
+  const state = new ReportState({ runName: fallbackRunName })
   const toolVersion = config.toolVersion ?? '0.1.0'
   /** scan_results block, set by finishScan and appended to run.json. */
   let scanResults: Record<string, unknown> | undefined
 
-  // llm_usage ledger: session assistant/message usage events are the only
-  // host-side token source (dsh emits no cost events). Counts every session
-  // in this host process — single-scan deployments are exact; concurrent
-  // scans in one host share the ledger (session log stays authoritative).
-  const usageLedger = { requests: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
-  void ctx.on('session/event', (_session: unknown, event: unknown) => {
+  // ---- Run-directory resolution: artifacts follow the dsh working directory ----
+
+  /**
+   * Structural view of the dsh Session behind a tool execution: `agent.session`
+   * (the same seam the approval gates use) carries a `header` with the session
+   * id, its absolute working directory, and — for subagent children — the
+   * owning root session. A scan's identity is the ROOT session id, so the
+   * whole subagent tree shares one run directory; the header cwd is the base
+   * a user's own writes would land in, which is where they expect artifacts.
+   */
+  interface SessionLike { header?: { id?: unknown; cwd?: unknown; parentSession?: unknown } }
+  const scanFactsOf = (session: unknown): { id: string; key: string; cwd: string } => {
+    const header = (session as SessionLike | undefined)?.header
+    const id = typeof header?.id === 'string' ? header.id : ''
+    const parent = typeof header?.parentSession === 'string' ? header.parentSession : ''
+    const cwd = typeof header?.cwd === 'string' && header.cwd !== '' ? header.cwd : ''
+    return { id, key: parent !== '' ? parent : id, cwd }
+  }
+  const sessionOf = (exec: unknown): unknown => (exec as { agent?: { session?: unknown } } | undefined)?.agent?.session
+  const AGENTLESS = ':agentless'
+  /** Per-scan memo: resolved run dir by scan key (root session id). */
+  const resolvedRunDirs = new Map<string, string>()
+  /** The session noted by the most recent tool execute (one scan per host at a time). */
+  let activeSession: unknown
+  /** sessionId → scan key: lets the usage ledger attribute assistant messages to the owning scan. */
+  const scanKeyOfSession = new Map<string, string>()
+  const noteScanKey = (session: unknown): void => {
+    const facts = scanFactsOf(session)
+    if (facts.id === '') return
+    const previous = scanKeyOfSession.get(facts.id)
+    scanKeyOfSession.set(facts.id, facts.key)
+    // First sighting of a subagent: fold any orphan usage account accumulated
+    // under its own id (messages that predate its first tool execute) into the
+    // root scan's account, so a scan's llm_usage stays whole.
+    if (previous !== facts.key && facts.key !== facts.id) {
+      const orphan = usageByScan.get(facts.id)
+      if (orphan !== undefined) {
+        const root = usageAccountOf(facts.key)
+        root.requests += orphan.requests
+        root.inputTokens += orphan.inputTokens
+        root.outputTokens += orphan.outputTokens
+        root.totalTokens += orphan.totalTokens
+        usageByScan.delete(facts.id)
+      }
+    }
+  }
+  const noteExec = (rawExec: never): void => {
+    const session = sessionOf(rawExec)
+    if (session !== undefined) {
+      activeSession = session
+      noteScanKey(session)
+    }
+  }
+
+  /** Occupancy facts of an existing run dir (best-effort read of its run.json). */
+  const runInfoOf = async (dir: string): Promise<{ completed: boolean; scanKey: string | null }> => {
+    try {
+      const raw = JSON.parse(await readFile(join(dir, 'run.json'), 'utf8')) as {
+        status?: unknown
+        session_id?: unknown
+        scan_results?: { scan_completed?: unknown } | undefined
+      }
+      const completed = raw['status'] === 'completed' || raw['scan_results']?.['scan_completed'] === true
+      const scanKey = typeof raw['session_id'] === 'string' ? raw['session_id'] : null
+      return { completed, scanKey }
+    } catch {
+      return { completed: false, scanKey: null }
+    }
+  }
+
+  /**
+   * Resolve this scan's run directory, memoized per scan key:
+   * - an absolute `runsRoot` pins the base (tests, explicit configs — unchanged);
+   * - the default relative root resolves against the session header cwd,
+   *   falling back to process.cwd() for agentless calls;
+   * - the name is the configured `runName`, else `pentest-<scan key short>`
+   *   (unique per scan, stable across restarts);
+   * - a fresh scan NEVER overwrites a completed or foreign run: the name gains
+   *   a -2/-3… suffix; the same scan resuming its own incomplete run reuses
+   *   its directory (crash resume).
+   */
+  const runDirFor = async (session: unknown): Promise<string> => {
+    if (session !== undefined) {
+      activeSession = session
+      noteScanKey(session)
+    }
+    const facts = scanFactsOf(session)
+    const key = facts.key !== '' ? facts.key : AGENTLESS
+    const memo = resolvedRunDirs.get(key)
+    if (memo !== undefined) return memo
+    const base = isAbsolute(runsRoot) ? resolve(runsRoot) : resolve(facts.cwd !== '' ? facts.cwd : process.cwd(), runsRoot)
+    const nameBase = config.runName ?? (facts.key !== '' ? `pentest-${facts.key.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8)}` : fallbackRunName)
+    let name = nameBase
+    let dir = resolve(join(base, name))
+    for (let suffix = 2; existsSync(dir); suffix++) {
+      const info = await runInfoOf(dir)
+      // Same scan resuming its own incomplete run reuses the directory;
+      // anything else (a completed run, a stale residue, a foreign scan) is kept.
+      if (!info.completed && info.scanKey === key && key !== AGENTLESS) break
+      if (suffix === 2) {
+        ctx.logger.warn(`pentest-reporting: run dir '${name}' already holds ${info.completed ? 'a completed run' : 'another run'}; the new run goes to '${nameBase}-<n>'`)
+      }
+      name = `${nameBase}-${suffix}`
+      dir = resolve(join(base, name))
+    }
+    resolvedRunDirs.set(key, dir)
+    if (state.runName !== name) state.runName = name
+    // Each newly resolved run dir gets a fresh run id: the state is shared for
+    // multi-round continuation, but two rounds' run.json must not show the
+    // same run_id (2026-09-22: both read run-22f45fc7).
+    state.reseatRunId()
+    return dir
+  }
+
+  /** Resolve the directory for the last-noted session (tools set it at execute start). */
+  const currentRunDir = (): Promise<string> => runDirFor(activeSession)
+
+  // llm_usage ledger, accounted PER SCAN KEY (root session): session
+  // assistant/message usage events are the only host-side token source (dsh
+  // emits no cost events). A second scan in the same host process starts its
+  // own account instead of inheriting the previous scan's tokens
+  // (2026-09-22: round 2's run.json carried round 1's whole 78M ledger).
+  interface UsageAccount { requests: number; inputTokens: number; outputTokens: number; totalTokens: number }
+  const usageByScan = new Map<string, UsageAccount>()
+  const usageAccountOf = (key: string): UsageAccount => {
+    let account = usageByScan.get(key)
+    if (account === undefined) {
+      account = { requests: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+      usageByScan.set(key, account)
+    }
+    return account
+  }
+  void ctx.on('session/event', (session: { id?: unknown } | undefined, event: unknown) => {
     const record = event as { type?: string; data?: { usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number } } }
     if (record.type !== 'assistant/message') return
     const usage = record.data?.usage
     if (usage === undefined || usage === null) return
-    usageLedger.requests += 1
-    usageLedger.inputTokens += usage.inputTokens ?? 0
-    usageLedger.outputTokens += usage.outputTokens ?? 0
-    usageLedger.totalTokens += usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
-  })
-  const llmUsageRecord = (): Record<string, unknown> => ({
-    requests: usageLedger.requests,
-    input_tokens: usageLedger.inputTokens,
-    output_tokens: usageLedger.outputTokens,
-    total_tokens: usageLedger.totalTokens,
-    // dsh session events carry tokens only; cost stays null (parity deviation
-    // recorded in the manual — strix estimates cost via LiteLLM callbacks).
-    cost: null,
-    agents: [],
+    const sessionId = typeof session?.id === 'string' ? session.id : ''
+    if (sessionId === '') return
+    // Sessions the tools have not seen yet account under their own id; a
+    // subagent's account folds into its root scan at its first noteExec.
+    const account = usageAccountOf(scanKeyOfSession.get(sessionId) ?? sessionId)
+    account.requests += 1
+    account.inputTokens += usage.inputTokens ?? 0
+    account.outputTokens += usage.outputTokens ?? 0
+    account.totalTokens += usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
   })
+  const llmUsageRecord = (): Record<string, unknown> => {
+    const facts = activeSession !== undefined ? scanFactsOf(activeSession) : { id: '', key: '', cwd: '' }
+    const account = usageAccountOf(facts.key !== '' ? facts.key : AGENTLESS)
+    return {
+      requests: account.requests,
+      input_tokens: account.inputTokens,
+      output_tokens: account.outputTokens,
+      total_tokens: account.totalTokens,
+      // dsh session events carry tokens only; cost stays null (parity deviation
+      // recorded in the manual — strix estimates cost via LiteLLM callbacks).
+      cost: null,
+      agents: [],
+    }
+  }
 
   const ensureRunDir = async (): Promise<string> => {
-    await mkdir(runDir, { recursive: true })
-    return runDir
+    const dir = await currentRunDir()
+    await mkdir(dir, { recursive: true })
+    return dir
   }
 
   /** Resolve the coverage source: Config hook first, else the analysis package's service. */
@@ -465,6 +605,10 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
       const runRecord: Record<string, unknown> = {
         run_id: state.runId,
         run_name: state.runName,
+        session_id: (() => {
+          const key = scanFactsOf(activeSession).key
+          return key !== '' ? key : null
+        })(),
         start_time: state.startTime,
         end_time: state.endTime,
         status: state.status,
@@ -526,7 +670,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
 
   ctx.tools.register(defineTool({
     name: 'create_vulnerability_report',
-    description: "File a vulnerability report — one report per fully-verified finding, with a working PoC. Severity and CVSS are computed from the 8-metric cvss_breakdown you provide. On a duplicate verdict, revise the existing report via update_vulnerability_report instead of retrying. Never for known-CVE dependency findings — use create_dependency_report.",
+    description: "File a vulnerability report — one report per fully-verified finding, with a working PoC. Severity and CVSS are computed from the 8-metric cvss_breakdown you provide. Validation contract (checked before filing, get these right the first time): cvss_breakdown must carry all 8 CVSS v3.1 metrics (attack_vector, attack_complexity, privileges_required, user_interaction, scope, confidentiality, integrity, availability) with their exact enum values; confidence != high requires confidence_rationale; any code_locations entry with fix_after requires fix_verification; cve must match CVE-YYYY-NNNNN and cwe must be a specific CWE-NNN child. On a duplicate verdict, revise the existing report via update_vulnerability_report instead of retrying. Never for known-CVE dependency findings — use create_dependency_report.",
     parameters: {
       title: { type: 'string', required: true, description: 'Specific finding title (e.g. "SQL Injection in /api/users login parameter").' },
       description: { type: 'string', required: true, description: 'Concise, non-technical TL;DR (1-3 sentences).' },
@@ -578,6 +722,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
       presentationMeta: (args: unknown, value: unknown) => findingPresentationMeta(args, value),
     },
     execute: (async (rawArgs: never, rawExec: never) => {
+      noteExec(rawExec)
       const args = rawArgs as never as CreateVulnArgs
       const exec = rawExec as never as ToolRunContextLike
       void exec
@@ -672,6 +817,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
       presentationMeta: (args: unknown, value: unknown) => findingPresentationMeta(args, value),
     },
     execute: (async (rawArgs: never, rawExec: never) => {
+      noteExec(rawExec)
       const args = rawArgs as never as UpdateArgs
       const exec = rawExec as never as ToolRunContextLike
       void exec
@@ -750,7 +896,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
 
   ctx.tools.register(defineTool({
     name: 'create_dependency_report',
-    description: "File a known-CVE dependency (SCA) finding — one report per CVE x package. For vulnerable third-party package versions pinned in a lockfile/manifest/SBOM; no live PoC needed. Severity comes from the contextual_cvss_breakdown when provided, else the advisory score. Never for dynamically-proven vulnerabilities — use create_vulnerability_report.",
+    description: "File a known-CVE dependency (SCA) finding — one report per CVE x package. For vulnerable third-party package versions pinned in a lockfile/manifest/SBOM; no live PoC needed. Severity comes from the contextual_cvss_breakdown when provided, else the advisory score. Validation contract: besides the marked-required fields, manifest_path, reachability_evidence, contextual_cvss_breakdown AND contextual_cvss_reasoning are all required and must be non-empty (the '(required)' hints in their descriptions are enforced at execution time). Never for dynamically-proven vulnerabilities — use create_vulnerability_report.",
     parameters: {
       title: { type: 'string', required: true, description: 'e.g. "CVE-2024-1234 in lodash 4.17.20 (prototype pollution)".' },
       description: { type: 'string', required: true, description: 'What the CVE is and why the pinned version is affected.' },
@@ -790,6 +936,12 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
           confidence: { type: 'number' },
           reason: { type: 'string' },
           warning: { type: 'string' },
+          // persistCreate returns this whenever the filed report carries a
+          // cvss (always, for dependency findings) — omitted from the schema
+          // it made dsh reject the output AFTER persisting: the model saw a
+          // phantom failure, re-filed 3 duplicates, and retracted them
+          // (2026-09-22 live test, vuln-0037..0039).
+          cvss_score: { type: 'number' },
         },
         additionalProperties: false,
       },
@@ -801,6 +953,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
       presentationMeta: (args: unknown, value: unknown) => findingPresentationMeta(args, value),
     },
     execute: (async (rawArgs: never, _rawExec: never) => {
+      noteExec(_rawExec)
       const args = rawArgs as never as CreateDepArgs
       const errors: string[] = []
       const requireText = (value: string | undefined, name: string): string | undefined => {
@@ -900,6 +1053,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
       },
     },
     execute: (async (rawArgs: never, rawExec: never) => {
+      noteExec(rawExec)
       const args = rawArgs as never as ListArgs
       const exec = rawExec as never as ToolRunContextLike
       void exec
@@ -968,6 +1122,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
       },
     },
     execute: (async (rawArgs: never, rawExec: never) => {
+      noteExec(rawExec)
       const args = rawArgs as never as GetArgs
       const exec = rawExec as never as ToolRunContextLike
       void exec
@@ -1015,12 +1170,27 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
 
   const handle: ReportingHandle = {
     state,
-    runDir,
+    /**
+     * Sync view of the run directory: the resolved dir of the last-noted
+     * session when one exists, else the unguarded default (no occupancy
+     * check). Accuracy for a fresh session comes from runDirFor().
+     */
+    get runDir(): string {
+      const facts = scanFactsOf(activeSession)
+      const key = facts.key !== '' ? facts.key : ':agentless'
+      const memo = resolvedRunDirs.get(key)
+      if (memo !== undefined) return memo
+      const base = isAbsolute(runsRoot) ? resolve(runsRoot) : resolve(facts.cwd !== '' ? facts.cwd : process.cwd(), runsRoot)
+      return resolve(join(base, config.runName ?? (facts.key !== '' ? `pentest-${facts.key.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8)}` : fallbackRunName)))
+    },
+    runDirFor: (session: unknown) => runDirFor(session),
     /** Mark the scan complete and write the final report + artifacts. */
-    async finishScan(sections: { readonly executiveSummary: string; readonly methodology: string; readonly technicalAnalysis: string; readonly recommendations: string }, status = 'completed'): Promise<void> {
+    async finishScan(sections: { readonly executiveSummary: string; readonly methodology: string; readonly technicalAnalysis: string; readonly recommendations: string }, status = 'completed', extras?: Readonly<Record<string, unknown>>): Promise<void> {
       state.finalScanResult = composeFinalReport(sections)
       state.complete(status)
       // strix `update_scan_final_fields` (finish tool → state.py :560-582).
+      // `extras` carries reconciliation facts the caller measured at close
+      // time (e.g. proxy-captured request count) into the persisted run.json.
       scanResults = {
         scan_completed: true,
         executive_summary: sections.executiveSummary,
@@ -1028,6 +1198,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
         technical_analysis: sections.technicalAnalysis,
         recommendations: sections.recommendations,
         success: status === 'completed',
+        ...extras,
       }
       const dir = await ensureRunDir()
       await writeExecutiveReport(dir, state.finalScanResult, formatTimestamp(new Date()))
@@ -1037,7 +1208,7 @@ export function apply(ctx: Context, config: Config = {}): ReportingHandle {
     async writeNow(): Promise<void> {
       await saveArtifacts()
     },
-    readRaw: async (relative: string): Promise<string> => readFile(join(runDir, relative), 'utf8'),
+    readRaw: async (relative: string): Promise<string> => readFile(join(await currentRunDir(), relative), 'utf8'),
   }
   ctx.provide('pentestReporting', handle)
   return handle

package/src/state.ts

@@ -107,7 +107,8 @@ export type UpdateOutcome =
  * per-scan instance in dsh).
  */
 export class ReportState {
-  readonly runId: string
+  /** Reseated per resolved run dir (see reseatRunId); NOT per-process — the state is shared for multi-round continuation. */
+  runId: string
   runName: string | null
   readonly startTime: string
   endTime: string | null = null
@@ -126,6 +127,17 @@ export class ReportState {
     this.startTime = formatIso(this.clock())
   }
 
+  /**
+   * Fresh run id for a newly resolved run directory. The state object stays
+   * process-shared so a second scan in the same host process CONTINUES the
+   * report ledger (multi-round retest mode) — but each run dir must carry its
+   * own id: before this, both rounds' run.json showed the same run_id because
+   * the id was minted once per process (2026-09-22).
+   */
+  reseatRunId(): void {
+    this.runId = `run-${Math.random().toString(16).slice(2, 10)}`
+  }
+
   /** Allocate the next sequential id (state.py :343 — length-derived). */
   private nextId(): string {
     return `vuln-${String(this.vulnerabilityReports.length + 1).padStart(4, '0')}`