@lievclouds/dsh-cortex 0.3.9 → 0.4.2

package/src/host/cortex/normalize-asset.js

@@ -0,0 +1,208 @@
+/**
+ * Defensive normalizers for agent-written asset JSON.
+ *
+ * MCP-era skills asked agents for one canonical shape; with the plugin tools
+ * the model sometimes writes aliases (`raw` instead of `request`, `type`/`file`
+ * instead of `info_type`/`source`, `param`/`where`/`example` instead of
+ * `name`/`location`/`values`). The original renderer and the memory-graph
+ * builder assume the canonical shape, so malformed-but-useful records used to
+ * crash the asset drawer / the nebula graph. Normalize on read and on write.
+ */
+
+export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']
+export const LEAKED_INFO_TYPES = [
+  'Credential',
+  'API_Key',
+  'Token',
+  'PII',
+  'Internal_IP',
+  'Other',
+]
+export const TEST_PARAMETER_LOCATIONS = ['path', 'query', 'body', 'header', 'cookie']
+
+const text = (value) => (typeof value === 'string' ? value.trim() : '')
+const pick = (...values) => {
+  for (const value of values) {
+    const candidate = text(value)
+    if (candidate.length > 0) return candidate
+  }
+  return ''
+}
+
+/**
+ * Canonical project label: agents sometimes write `上海春芝堂 SRC` and
+ * `上海春芝堂_SRC`; underscores and repeated spaces are display noise. The
+ * graph groups by this value, so normalizing it merges variant roots.
+ */
+export function normalizeProjectName(value) {
+  const label = (typeof value === 'string' ? value : '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  // CJK projects often get written as `上海春芝堂_SRC` vs `上海春芝堂 SRC`;
+  // merge those variants without renaming pure-ASCII projects like `app_web`.
+  return /[\u4e00-\u9fff]/.test(label) ? label.replace(/_/g, ' ').replace(/\s+/g, ' ').trim() : label
+}
+
+export function parseJsonArray(value) {
+  if (Array.isArray(value)) return value
+  if (typeof value === 'string' && value.trim().length > 0) {
+    try {
+      const parsed = JSON.parse(value)
+      return Array.isArray(parsed) ? parsed : []
+    } catch {
+      return []
+    }
+  }
+  return []
+}
+
+/** Pull the query string / body out of a captured raw HTTP request. */
+export function extractParamsFromRaw(raw) {
+  const source = text(raw).replace(/\r\n/g, '\n')
+  if (source.length === 0) return ''
+  const lines = source.split('\n')
+  const requestLine = lines[0] || ''
+  const queryIndex = requestLine.indexOf('?')
+  const query = queryIndex >= 0 ? requestLine.slice(queryIndex).trim() : ''
+  const separator = source.indexOf('\n\n')
+  const body = separator >= 0 ? source.slice(separator + 2).trim() : ''
+  return [query, body].filter((part) => part.length > 0).join('\n')
+}
+
+/** @returns {{path:string, method?:string, params?:string, request?:string}|null} */
+export function normalizeInterface(raw) {
+  if (typeof raw === 'string') {
+    const path = raw.trim()
+    return path.length > 0 ? { path } : null
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const path = pick(raw.path, raw.url, raw.route, raw.endpoint)
+  if (path.length === 0) return null
+  const entry = { path }
+  const method = pick(raw.method).toUpperCase()
+  if (HTTP_METHODS.includes(method)) entry.method = method
+  const request = pick(raw.request, raw.raw, raw.http)
+  const params = pick(raw.params, raw.parameters, raw.query, raw.data) || extractParamsFromRaw(request)
+  if (params.length > 0) entry.params = params
+  if (request.length > 0) entry.request = request
+  return entry
+}
+
+/** @returns {Array<{path:string, method?:string, params?:string, request?:string}>} */
+export function normalizeInterfaces(raw, interfaceDir) {
+  const result = []
+  const seen = new Set()
+  const push = (entry) => {
+    if (!entry) return
+    const key = `${entry.method || ''}\u0000${entry.path}`
+    if (seen.has(key)) return
+    seen.add(key)
+    result.push(entry)
+  }
+  for (const item of parseJsonArray(raw)) push(normalizeInterface(item))
+  for (const item of parseJsonArray(interfaceDir)) {
+    const path = text(item)
+    if (path.length > 0) push(normalizeInterface({ path }))
+  }
+  return result
+}
+
+/** @returns {{info_type:string, value:string, source:string, potential_impact:string}} */
+export function normalizeLeak(raw) {
+  const item = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {}
+  const rawType = pick(item.info_type, item.infoType, item.type, item.kind, item.category)
+  const infoType = LEAKED_INFO_TYPES.includes(rawType)
+    ? rawType
+    : rawType === 'public_config' || rawType === 'config'
+      ? 'Other'
+      : 'Other'
+  return {
+    info_type: infoType,
+    value: pick(item.value, item.content, item.data, item.secret, item.example),
+    source: pick(item.source, item.file, item.where, item.url, item.path, item.endpoint),
+    potential_impact: pick(item.potential_impact, item.potentialImpact, item.impact, item.note),
+  }
+}
+
+/** @returns {Array<ReturnType<typeof normalizeLeak>>} */
+export function normalizeLeaks(raw) {
+  const result = []
+  for (const item of parseJsonArray(raw)) {
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) continue
+    const leak = normalizeLeak(item)
+    if (leak.value.length === 0 && leak.source.length === 0) continue
+    result.push(leak)
+  }
+  return result
+}
+
+/** @returns {object|null} canonical TestParameterCandidate */
+export function normalizeTestParameter(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const name = pick(raw.name, raw.param, raw.key)
+  const endpoint = pick(raw.endpoint, raw.interface, raw.api, raw.path)
+  const values = Array.isArray(raw.values)
+    ? raw.values.filter((value) => typeof value === 'string' || typeof value === 'number').map(String)
+    : [pick(raw.example, raw.example_value, raw.value, raw.sample)].filter((value) => value.length > 0)
+  const locationRaw = pick(raw.location, raw.where, raw.in).toLowerCase()
+  const locationAliases = {
+    json: 'body',
+    form: 'body',
+    formdata: 'body',
+    post: 'body',
+    query: 'query',
+    querystring: 'query',
+    url: 'query',
+    header: 'header',
+    headers: 'header',
+    cookie: 'cookie',
+    path: 'path',
+  }
+  const mappedLocation = locationAliases[locationRaw] || locationRaw
+  const location = TEST_PARAMETER_LOCATIONS.includes(mappedLocation) ? mappedLocation : 'query'
+  const source = pick(raw.source, raw.file, raw.interface, raw.endpoint)
+  if (name.length === 0 && endpoint.length === 0 && values.length === 0) return null
+  const entry = {
+    name: name || 'value',
+    endpoint: endpoint || source || '(unknown)',
+    location,
+    values: values.slice(0, 50),
+    source: source || endpoint || '(unknown)',
+    tested: raw.tested === true,
+    related_vuln_ids: Array.isArray(raw.related_vuln_ids)
+      ? raw.related_vuln_ids.filter((value) => typeof value === 'string' && value.trim().length > 0)
+      : [],
+  }
+  const pattern = pick(raw.pattern)
+  if (pattern.length > 0) entry.pattern = pattern
+  const notes = pick(raw.notes, raw.note)
+  if (notes.length > 0) entry.notes = notes
+  return entry
+}
+
+/** @returns {Array<ReturnType<typeof normalizeTestParameter>>} */
+export function normalizeTestParameters(raw) {
+  const result = []
+  const seen = new Set()
+  for (const item of parseJsonArray(raw)) {
+    const entry = normalizeTestParameter(item)
+    if (!entry) continue
+    const key = `${entry.endpoint}\u0000${entry.name}\u0000${entry.location}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(entry)
+  }
+  return result
+}
+
+/** Normalize one raw asset row for API / graph consumers. */
+export function normalizeAssetRow(row) {
+  if (!row || typeof row !== 'object') return row
+  return {
+    ...row,
+    interfaces: normalizeInterfaces(row.interfaces, row.interface_dir),
+    leaked_infos: normalizeLeaks(row.leaked_infos),
+    test_parameters: normalizeTestParameters(row.test_parameters),
+    related_vuln_ids: parseJsonArray(row.related_vuln_ids).filter((value) => typeof value === 'string'),
+  }
+}

package/src/host/cortex/tools.js

@@ -7,6 +7,13 @@
  * honours the same schema-v5 guard and read-only mode as the HTTP API.
  */
 import { withBusyRetry } from '../db.js'
+import {
+  normalizeInterfaces,
+  normalizeLeaks,
+  normalizeProjectName,
+  normalizeTestParameters,
+} from './normalize-asset.js'
+import { auditCompleteness, syncInternalScope } from './data-tools.js'
 
 const SEVERITIES = ['Critical', 'High', 'Medium', 'Low', 'Info']
 const STATUSES = ['Confirmed', 'Inconclusive', 'Retest_Passed']
@@ -394,7 +401,7 @@ export function createCortexToolDefinitions({ holder, config }) {
 
   const syncAsset = defineTool(
     'cortex_sync_asset_info',
-    'Insert or update local Cortex asset context (fingerprints, structured interfaces, leaked info, test parameters, related vulns). mode=merge (default) appends new array entries and only overwrites provided scalars; mode=replace replaces the whole asset snapshot.',
+    'Insert or update local Cortex asset context. mode=merge (default) appends canonicalized array entries and only overwrites provided scalars; mode=replace replaces the whole asset snapshot. Canonical fields: interfaces[] = {path, method?, params?, request?} where request is a complete raw HTTP request; leaked_infos[] = {info_type, value, source, potential_impact}; test_parameters[] = {name, endpoint, location (path|query|body|header|cookie), values[], pattern?, source, tested?, notes?, related_vuln_ids?}. Common aliases are normalized (raw->request, type->info_type, file->source, param->name, where->location, example->values[0]).',
     {
       host_port: { type: 'string', description: 'Full URL/authority, e.g. http://127.0.0.1:8080/' },
       project_name: { type: 'string' },
@@ -402,9 +409,53 @@ export function createCortexToolDefinitions({ holder, config }) {
       tech_stack: { type: 'string' },
       auth_required: { type: 'boolean' },
       status: { type: 'string', enum: ['Alive', 'Dead', 'WAF_Blocked'] },
-      interfaces: { type: 'array', items: { type: 'object' } },
-      leaked_infos: { type: 'array', items: { type: 'object' } },
-      test_parameters: { type: 'array', items: { type: 'object' } },
+      interfaces: {
+        type: 'array',
+        description: 'Structured API interfaces; raw static files are not interfaces. Example: {path: "/api/login", method: "POST", params: "{\\"user\\":\\"a\\"}", request: "POST /api/login HTTP/1.1\nHost: host\n\n{...}"}',
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'API path (required)' },
+            method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'] },
+            params: { type: 'string', description: 'Query string or body fields' },
+            request: { type: 'string', description: 'Complete raw HTTP request (request line + headers + blank line + body)' },
+          },
+          required: ['path'],
+        },
+      },
+      leaked_infos: {
+        type: 'array',
+        description: 'Secrets/PII/internal IPs. Example: {info_type: "Token", value: "eyJ...", source: "/js/app.js", potential_impact: "可伪造会话"}',
+        items: {
+          type: 'object',
+          properties: {
+            info_type: { type: 'string', enum: ['Credential', 'API_Key', 'Token', 'PII', 'Internal_IP', 'Other'] },
+            value: { type: 'string' },
+            source: { type: 'string', description: 'Where it was found (URL/file/JS bundle)' },
+            potential_impact: { type: 'string' },
+          },
+          required: ['info_type', 'value', 'source', 'potential_impact'],
+        },
+      },
+      test_parameters: {
+        type: 'array',
+        description: 'Non-secret seeds for authz tests. Example: {name: "orderId", endpoint: "GET /api/orders/{id}", location: "path", values: ["1001"], source: "/js/app.js", pattern: "sequential numeric"}',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            endpoint: { type: 'string' },
+            location: { type: 'string', enum: ['path', 'query', 'body', 'header', 'cookie'] },
+            values: { type: 'array', items: { type: 'string' } },
+            pattern: { type: 'string' },
+            source: { type: 'string' },
+            tested: { type: 'boolean' },
+            notes: { type: 'string' },
+            related_vuln_ids: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['name', 'endpoint', 'location', 'source'],
+        },
+      },
       related_vuln_ids: { type: 'array', items: { type: 'string' } },
       mode: { type: 'string', enum: ['merge', 'replace'] },
     },
@@ -413,15 +464,14 @@ export function createCortexToolDefinitions({ holder, config }) {
       assertWritable(holder)
       const db = ensureDb(holder)
       const hostPort = text(args.host_port).trim()
-      const project = text(args.project_name).trim()
+      const project = normalizeProjectName(text(args.project_name))
       if (!hostPort || !project) throw new Error('host_port and project_name are required')
       const merge = args.mode !== 'replace'
       const existing = db.prepare('SELECT * FROM assets WHERE host_port = ?').get(hostPort)
       const now = new Date().toISOString()
-      const arrayField = (name) => {
-        const value = Array.isArray(args[name]) ? args[name] : undefined
+      const arrayField = (name, normalize) => {
+        const value = args[name] !== undefined && normalize ? normalize(args[name]) : undefined
         if (merge && existing) return jsonColumn(uniqueJsonMerge(existing[name], value))
-        if (merge && !existing) return jsonColumn(value)
         return jsonColumn(value)
       }
       const scalar = (name, fallback) =>
@@ -432,10 +482,12 @@ export function createCortexToolDefinitions({ holder, config }) {
         tech_stack: args.tech_stack !== undefined ? text(args.tech_stack) : merge && existing ? existing.tech_stack : '',
         auth_required: scalar('auth_required', false) ? 1 : 0,
         status: scalar('status', 'Alive'),
-        interfaces: arrayField('interfaces'),
-        leaked_infos: arrayField('leaked_infos'),
-        test_parameters: arrayField('test_parameters'),
-        related_vuln_ids: arrayField('related_vuln_ids'),
+        interfaces: arrayField('interfaces', normalizeInterfaces),
+        leaked_infos: arrayField('leaked_infos', normalizeLeaks),
+        test_parameters: arrayField('test_parameters', normalizeTestParameters),
+        related_vuln_ids: arrayField('related_vuln_ids', (value) =>
+          Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [],
+        ),
         last_seen: now,
       }
       runWrite(db, () => {
@@ -454,12 +506,157 @@ export function createCortexToolDefinitions({ holder, config }) {
         }
       })
       holder.refreshFileStamp()
+      const counts = {
+        interfaces: jsonArray(values.interfaces).length,
+        leaks: jsonArray(values.leaked_infos).length,
+        parameters: jsonArray(values.test_parameters).length,
+      }
+      const warnings = []
+      for (const [name, key] of [
+        ['interfaces', 'interfaces'],
+        ['leaked_infos', 'leaks'],
+        ['test_parameters', 'parameters'],
+      ]) {
+        if (args[name] === undefined) continue
+        const sent = Array.isArray(args[name]) ? args[name].length : 0
+        if (sent > counts[key]) warnings.push(`${name}: ${sent - counts[key]} invalid entries dropped by normalization`)
+      }
+      if (counts.interfaces === 0) warnings.push('interfaces is empty — add {path, method, params?, request?} for each API')
+      if (counts.leaks === 0) warnings.push('leaked_infos is empty — record secrets/tokens/internal IPs with value+source+impact')
+      if (counts.parameters === 0) warnings.push('test_parameters is empty — record id/tenant/order seeds with name+endpoint+location+values+source')
       return {
-        text: `${LOG} ${existing ? (merge ? 'merged' : 'replaced') : 'created'} asset ${hostPort} (project ${project})`,
+        text: [
+          `${LOG} ${existing ? (merge ? 'merged' : 'replaced') : 'created'} asset ${hostPort} (project ${project})`,
+          `stored: interfaces=${counts.interfaces}, leaked_infos=${counts.leaks}, test_parameters=${counts.parameters}`,
+          ...warnings.map((warning) => `warning: ${warning}`),
+        ].join('\n'),
       }
     },
   )
 
+  const saveSnapshot = defineTool(
+    'cortex_save_snapshot',
+    'Create or update a local Cortex cognitive snapshot (认知快照) for the current task: project, phase, targets, unfinished tasks, failed paths, tested interfaces/notes/next steps and related vulns. Call it at task milestones, before context compaction and at session end. Omit session_id to create a new snapshot; pass session_id to update one; force_new=true creates another session for a project that already has one. Updates keep a previous_state rollback buffer.',
+    {
+      project_name: { type: 'string', minLength: 1, maxLength: 120 },
+      current_phase: { type: 'string', maxLength: 200 },
+      target_hosts: { type: 'array', items: { type: 'string' } },
+      unfinished_tasks: { type: 'array', items: { type: 'string' } },
+      failed_paths: { type: 'array', items: { type: 'string' } },
+      tested_interfaces: { type: 'array', items: { type: 'object' }, description: 'Tested interface matrix entries (endpoint/result/...)' },
+      notes: { type: 'string', maxLength: 30000 },
+      related_vuln_ids: { type: 'array', items: { type: 'string' } },
+      next_steps: { type: 'string', maxLength: 10000 },
+      session_id: { type: 'string', maxLength: 100 },
+      parent_session_id: { type: 'string', maxLength: 100 },
+      force_new: { type: 'boolean' },
+    },
+    ['project_name'],
+    async (args) => {
+      assertWritable(holder)
+      const db = ensureDb(holder)
+      const project = normalizeProjectName(text(args.project_name))
+      if (!project) throw new Error('project_name is required')
+      const stringList = (name) =>
+        args[name] === undefined
+          ? undefined
+          : JSON.stringify(
+              (Array.isArray(args[name]) ? args[name] : [])
+                .filter((entry) => typeof entry === 'string')
+                .map((entry) => entry.trim())
+                .filter((entry) => entry.length > 0),
+            )
+      const objectList = (name) =>
+        args[name] === undefined
+          ? undefined
+          : JSON.stringify((Array.isArray(args[name]) ? args[name] : []).filter((entry) => entry && typeof entry === 'object'))
+      const fields = {
+        project_name: project,
+        current_phase: args.current_phase !== undefined ? text(args.current_phase) : undefined,
+        target_hosts: stringList('target_hosts'),
+        unfinished_tasks: stringList('unfinished_tasks'),
+        failed_paths: stringList('failed_paths'),
+        tested_interfaces: objectList('tested_interfaces'),
+        notes: args.notes !== undefined ? text(args.notes) : undefined,
+        related_vuln_ids: stringList('related_vuln_ids'),
+        next_steps: args.next_steps !== undefined ? text(args.next_steps) : undefined,
+      }
+      const now = new Date().toISOString()
+      const sessionId = text(args.session_id).trim()
+      if (sessionId) {
+        const existing = db.prepare('SELECT * FROM snapshot_sessions WHERE session_id = ?').get(sessionId)
+        if (!existing) throw new Error(`snapshot ${sessionId} not found; omit session_id to create a new one`)
+        const previous = {
+          project_name: existing.project_name,
+          target_hosts: jsonArray(existing.target_hosts),
+          current_phase: existing.current_phase,
+          unfinished_tasks: jsonArray(existing.unfinished_tasks),
+          failed_paths: jsonArray(existing.failed_paths),
+          tested_interfaces: jsonArray(existing.tested_interfaces),
+          notes: existing.notes,
+          related_vuln_ids: jsonArray(existing.related_vuln_ids),
+          next_steps: existing.next_steps,
+        }
+        const sets = []
+        const values = []
+        for (const [column, value] of Object.entries(fields)) {
+          if (value === undefined) continue
+          sets.push(`${column} = ?`)
+          values.push(value)
+        }
+        sets.push('previous_state = ?', 'updated_at = ?')
+        values.push(JSON.stringify(previous), now, sessionId)
+        await runWrite(db, () =>
+          db.prepare(`UPDATE snapshot_sessions SET ${sets.join(', ')} WHERE session_id = ?`).run(...values),
+        )
+        holder.refreshFileStamp()
+        return { text: `${LOG} snapshot updated: ${sessionId} | ${project} | phase: ${fields.current_phase ?? existing.current_phase}` }
+      }
+      if (args.force_new !== true) {
+        const candidates = db
+          .prepare('SELECT session_id, current_phase, updated_at FROM snapshot_sessions WHERE project_name = ? AND archived_at IS NULL ORDER BY updated_at DESC LIMIT 5')
+          .all(project)
+        if (candidates.length > 0) {
+          return {
+            text: `${LOG} project ${project} already has snapshots: ${candidates
+              .map((row) => `${row.session_id} (${row.current_phase || '-'}, ${row.updated_at})`)
+              .join('; ')} — pass session_id to update one, or force_new=true to create a new session.`,
+          }
+        }
+      }
+      const id = globalThis.crypto?.randomUUID?.() ?? `snap-${Date.now()}-${Math.random().toString(16).slice(2)}`
+      const columns = [
+        'session_id', 'project_name', 'target_hosts', 'current_phase', 'unfinished_tasks', 'failed_paths',
+        'tested_interfaces', 'notes', 'related_vuln_ids', 'next_steps', 'previous_state',
+        'parent_session_id', 'archived_at', 'created_at', 'updated_at',
+      ]
+      const values = [
+        id,
+        project,
+        fields.target_hosts ?? '[]',
+        fields.current_phase ?? '',
+        fields.unfinished_tasks ?? '[]',
+        fields.failed_paths ?? '[]',
+        fields.tested_interfaces ?? '[]',
+        fields.notes ?? '',
+        fields.related_vuln_ids ?? '[]',
+        fields.next_steps ?? '',
+        null,
+        text(args.parent_session_id) || null,
+        null,
+        now,
+        now,
+      ]
+      await runWrite(db, () =>
+        db
+          .prepare(`INSERT INTO snapshot_sessions (${columns.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`)
+          .run(...values),
+      )
+      holder.refreshFileStamp()
+      return { text: `${LOG} snapshot saved: ${id} | ${project} | phase: ${fields.current_phase || '-'}` }
+    },
+  )
+
   const listAssets = defineTool(
     'cortex_list_assets',
     'List local Cortex assets (host_port, project, tech stack, interface/leak/test-parameter counts). Optional search/status/project filters.',
@@ -493,7 +690,7 @@ export function createCortexToolDefinitions({ holder, config }) {
         .all(...params)
       const lines = rows.map(
         (row) =>
-          `${row.host_port} | ${row.status} | ${row.project_name} | ifaces=${jsonArray(row.interfaces).length} leaks=${jsonArray(row.leaked_infos).length} params=${jsonArray(row.test_parameters).length} vulns=${jsonArray(row.related_vuln_ids).length} | ${row.tech_stack}`,
+          `${row.host_port} | ${row.status} | ${normalizeProjectName(row.project_name)} | ifaces=${jsonArray(row.interfaces).length} leaks=${jsonArray(row.leaked_infos).length} params=${jsonArray(row.test_parameters).length} vulns=${jsonArray(row.related_vuln_ids).length} | ${row.tech_stack}`,
       )
       return { text: [`${LOG} ${rows.length} assets`, ...lines].join('\n') }
     },
@@ -508,22 +705,26 @@ export function createCortexToolDefinitions({ holder, config }) {
       const db = ensureDb(holder)
       const row = db.prepare('SELECT * FROM assets WHERE host_port = ?').get(text(args.hostPort).trim())
       if (!row) return { text: `${LOG} asset not found: ${args.hostPort}` }
+      const interfaces = normalizeInterfaces(row.interfaces, row.interface_dir)
+      const leaks = normalizeLeaks(row.leaked_infos)
+      const testParameters = normalizeTestParameters(row.test_parameters)
+      const relatedIds = jsonArray(row.related_vuln_ids).filter((entry) => typeof entry === 'string')
       const parts = [
         `# ${row.host_port}`,
-        `host: ${row.host} · project: ${row.project_name}`,
+        `host: ${row.host} · project: ${normalizeProjectName(row.project_name)}`,
         `status: ${row.status} · auth_required: ${row.auth_required ? 'true' : 'false'} · last_seen: ${row.last_seen}`,
         `tech_stack: ${row.tech_stack}`,
         '',
-        `## interfaces (${jsonArray(row.interfaces).length})`,
-        JSON.stringify(jsonArray(row.interfaces), null, 2),
+        `## interfaces (${interfaces.length})`,
+        JSON.stringify(interfaces, null, 2),
         '',
-        `## leaked_infos (${jsonArray(row.leaked_infos).length})`,
-        JSON.stringify(jsonArray(row.leaked_infos), null, 2),
+        `## leaked_infos (${leaks.length})`,
+        JSON.stringify(leaks, null, 2),
         '',
-        `## test_parameters (${jsonArray(row.test_parameters).length})`,
-        JSON.stringify(jsonArray(row.test_parameters), null, 2),
+        `## test_parameters (${testParameters.length})`,
+        JSON.stringify(testParameters, null, 2),
         '',
-        `## related_vuln_ids\n${jsonArray(row.related_vuln_ids).join(', ')}`,
+        `## related_vuln_ids\n${relatedIds.join(', ')}`,
       ]
       return { text: parts.join('\n') }
     },
@@ -650,6 +851,120 @@ export function createCortexToolDefinitions({ holder, config }) {
     },
   )
 
+  const auditTool = defineTool(
+    'cortex_audit_completeness',
+    'Audit local Cortex data completeness: per project assets missing interfaces/leaks/test parameters, vulnerability records with incomplete evidence, internal-scope entity counts and snapshot counts. Run this after a testing phase and fill every reported gap before finishing.',
+    { project_name: { type: 'string', description: 'Optional project filter (canonical name)' } },
+    [],
+    async (args) => ({ text: auditCompleteness({ holder, args }).text }),
+  )
+
+  const internalSyncTool = defineTool(
+    'cortex_sync_internal_scope',
+    'Register internal operations data for a project (schema v3): internal_hosts, internal_services, footholds, credentials and pivots. Call it after initial access and whenever new internal hosts/services/credentials are found. Arrays are upserted; footholds accept host_ips to link reachable hosts, pivots accept hops [{ref_kind, ref_id, label?, via?}].',
+    {
+      project_name: { type: 'string', minLength: 1, maxLength: 120 },
+      internal_hosts: {
+        type: 'array',
+        description: 'Example: {ip: "10.0.0.5", hostname: "db01", os: "Ubuntu 22.04", subnet: "10.0.0.0/24", state: "alive", source: "nmap"}',
+        items: {
+          type: 'object',
+          properties: {
+            ip: { type: 'string' },
+            hostname: { type: 'string' },
+            os: { type: 'string' },
+            subnet: { type: 'string' },
+            state: { type: 'string', enum: ['unknown', 'alive', 'compromised', 'unreachable', 'firewalled'] },
+            source: { type: 'string' },
+            confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+          },
+          required: ['ip'],
+        },
+      },
+      internal_services: {
+        type: 'array',
+        description: 'Example: {ip: "10.0.0.5", port: 6379, protocol: "tcp", service: "redis", banner: "Redis 7.4", state: "open"}',
+        items: {
+          type: 'object',
+          properties: {
+            ip: { type: 'string' },
+            host_id: { type: 'string' },
+            port: { type: 'integer' },
+            protocol: { type: 'string' },
+            service: { type: 'string' },
+            banner: { type: 'string' },
+            state: { type: 'string', enum: ['open', 'closed', 'filtered', 'unknown'] },
+            source: { type: 'string' },
+          },
+          required: ['port'],
+        },
+      },
+      footholds: {
+        type: 'array',
+        description: 'Example: {entry_host_port: "https://target/", entry_vuln_id: "VULN-...", access_type: "rce", privilege_level: "admin", host_ips: ["10.0.0.5"], evidence: "id; whoami", notes: "..."}',
+        items: {
+          type: 'object',
+          properties: {
+            entry_host_port: { type: 'string' },
+            entry_vuln_id: { type: 'string' },
+            access_type: { type: 'string', enum: ['rce', 'webshell', 'ssrf_proxy', 'credential', 'vpn', 'other'] },
+            privilege_level: { type: 'string', enum: ['user', 'admin', 'system', 'domain_admin', 'unknown'] },
+            status: { type: 'string', enum: ['planned', 'established', 'degraded', 'lost'] },
+            evidence: { type: 'string' },
+            notes: { type: 'string' },
+            host_ips: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['entry_host_port'],
+        },
+      },
+      credentials: {
+        type: 'array',
+        description: 'Example: {type: "password", username: "deploy", secret: "***", host: "10.0.0.5", service: "ssh", source: "backup.sh", confidence: "high", status: "valid"}',
+        items: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', enum: ['password', 'ntlm_hash', 'netntlmv2', 'kerberos_ticket', 'ssh_key', 'cert', 'api_key', 'other'] },
+            username: { type: 'string' },
+            domain: { type: 'string' },
+            secret: { type: 'string' },
+            host: { type: 'string' },
+            port: { type: 'integer' },
+            protocol: { type: 'string' },
+            service: { type: 'string' },
+            source: { type: 'string' },
+            confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+            status: { type: 'string', enum: ['untested', 'valid', 'invalid', 'expired'] },
+            notes: { type: 'string' },
+          },
+        },
+      },
+      pivots: {
+        type: 'array',
+        description: 'Example: {entry_host_port: "https://target/", kind: "proxy", local_port: 1080, local_protocol: "socks5", tool: "chisel", status: "established"}',
+        items: {
+          type: 'object',
+          properties: {
+            foothold_id: { type: 'string' },
+            entry_host_port: { type: 'string' },
+            kind: { type: 'string', enum: ['chain', 'proxy'] },
+            local_host: { type: 'string' },
+            local_port: { type: 'integer' },
+            local_protocol: { type: 'string' },
+            tool: { type: 'string' },
+            status: { type: 'string', enum: ['planned', 'established', 'degraded', 'lost'] },
+            notes: { type: 'string' },
+            hops: { type: 'array', items: { type: 'object' } },
+          },
+        },
+      },
+    },
+    ['project_name'],
+    async (args) => {
+      assertWritable(holder)
+      return { text: syncInternalScope({ holder, args }).text }
+    },
+  )
+
   const tools = [
     listVulns,
     getVuln,
@@ -661,8 +976,11 @@ export function createCortexToolDefinitions({ holder, config }) {
     getAsset,
     listSnapshots,
     getSnapshot,
+    saveSnapshot,
     internalOverview,
     graphSummary,
+    auditTool,
+    internalSyncTool,
   ]
   return readOnly ? tools.map((tool) => ({ ...tool, description: `${tool.description} (current host: read-only)` })) : tools
 }