fix: make reveal's Ghidra enrichment opt-in, not automatic (#277)

* fix: make reveal's Ghidra enrichment opt-in, not automatic

Follow-up to #275 (the target_reveal_dir hang fix): revealing a target has
always ALSO auto-triggered optional Ghidra enrichment whenever
features.ghidra.enrich_recon is on — a coupling that predates #275 and
that #275 only made non-blocking, not optional. On review with the
operator: "reveal" reads as a pure visibility toggle, but silently queuing
a potentially long-running background analysis job for every revealed
target is surprising — this coupling is what actually caused the incident
(revealing an Erlang erts/bin directory queued a dozen-plus background
Ghidra jobs the operator never explicitly asked for on that call).

set_visible/reveal_dir gain an explicit `enrich: bool = False` parameter.
Enrichment now requires BOTH the global features.ghidra.enrich_recon
setting AND an explicit per-call enrich=True — reveal alone never queues
analysis. The capability isn't removed (an agent doing deliberate VR work
can still opt in per call), just no longer implicit.

Threaded through the whole stack: engine (reveal.py), MCP tools + catalog
schemas, REST (VisibleUpdate/RevealDir gain enrich: bool = False), and
frontend API types. FilesystemBrowser.tsx's reveal actions don't pass
enrich=true (reveal-to-browse shouldn't trigger analysis); the now-dead
"Ghidra enrichment running" UI message for a directory reveal was removed
since it can no longer fire from that path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: fix stale _maybe_enrich_ghidra docstring after the enrich opt-in change

Flagged in #277's review: the docstring still said "reveal runs this
enrichment then" — no longer true now that reveal requires an explicit
per-call enrich=True, not just the global feature flag.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: branover

frontend/src/api.ts

@@ -306,12 +306,15 @@ export const api = {
   filesystem: (tid: string) => getJSON<{ unpacked: boolean; method?: string; files: FsEntry[] }>(`/api/targets/${tid}/filesystem`),
   promoteFile: (pid: string, fwId: string, rel: string) => postJSON<any>(`/api/projects/${pid}/targets/${fwId}/promote-file`, { rel }),
   // Reveal/re-hide a target in the curated graph. Firmware ELF children are hidden by default
-  // (unpack registers them all); revealing materializes the target's recon nodes from stored facts.
-  setTargetVisible: (pid: string, tid: string, visible: boolean) => postJSON<{ target_id: string; name: string; visible: boolean; materialized: boolean; enrichment_queued: boolean }>(`/api/projects/${pid}/targets/${tid}/visible`, { visible }),
+  // (unpack registers them all); revealing materializes the target's recon nodes from stored
+  // facts. Ghidra enrichment does NOT run automatically — pass enrich:true to also queue it,
+  // detached (default false: revealing to browse shouldn't silently kick off analysis jobs).
+  setTargetVisible: (pid: string, tid: string, visible: boolean, enrich = false) => postJSON<{ target_id: string; name: string; visible: boolean; materialized: boolean; enrichment_queued: boolean }>(`/api/projects/${pid}/targets/${tid}/visible`, { visible, enrich }),
   // Bulk-reveal every hidden firmware child whose rootfs path is under `prefix` (e.g. "usr/sbin").
-  // `enrichment_queued` = how many revealed targets got a background Ghidra enrichment task
-  // (revealing/materializing itself is synchronous and fast; enrichment is not).
-  revealDir: (pid: string, fwId: string, prefix: string) => postJSON<{ firmware_target_id: string; prefix: string; revealed: number; target_ids: string[]; enrichment_queued: number }>(`/api/projects/${pid}/targets/${fwId}/reveal-dir`, { prefix }),
+  // `enrichment_queued` = how many revealed targets got queued into ONE background batch
+  // Ghidra-enrichment task (revealing/materializing itself is always synchronous and fast;
+  // enrichment only happens at all when enrich:true is passed — default false).
+  revealDir: (pid: string, fwId: string, prefix: string, enrich = false) => postJSON<{ firmware_target_id: string; prefix: string; revealed: number; target_ids: string[]; enrichment_queued: number }>(`/api/projects/${pid}/targets/${fwId}/reveal-dir`, { prefix, enrich }),
   // Target-level follow-up suggestions from enriched recon metadata (e.g. risky-sink → static-analyze).
   targetSuggestions: (tid: string) => getJSON<any[]>(`/api/targets/${tid}/suggestions`),
   // Source trees (Phase 1 — read-only IDE browse)

frontend/src/components/FilesystemBrowser.tsx

@@ -68,18 +68,16 @@ export default function FilesystemBrowser({ projectId, targetId, onChanged }: {
     finally { setBusy(""); }
   };
 
-  // Reveal every hidden child under a directory prefix in one call.
+  // Reveal every hidden child under a directory prefix in one call. Ghidra enrichment is
+  // NOT requested here (api.revealDir's enrich param defaults to false) — reveal is a fast,
+  // predictable visibility toggle; deliberately opting a whole directory into a dozen-plus
+  // background Ghidra analyses is a bigger decision than "let me see what's in here",
+  // and doing it implicitly on every reveal is what caused a real 2+ hour incident.
   const revealDir = async (prefix: string) => {
     setBusy("dir:" + prefix);
     try {
       const r = await api.revealDir(projectId, targetId, prefix);
       if (r.revealed === 0) alert("No hidden binaries to reveal under " + (prefix || "/"));
-      // Ghidra enrichment per binary (if enabled) runs in the background — a directory with
-      // many binaries would otherwise block this call for a long time (each is a cold headless
-      // Ghidra pass). The binaries are already revealed/searchable; enrichment just deepens them.
-      else if (r.enrichment_queued > 0)
-        alert(`Revealed ${r.revealed} binaries. Ghidra enrichment for ${r.enrichment_queued} of `
-          + `them is running in the background and may take a while.`);
       await load(); onChanged?.();
     } catch (e: any) { alert(String(e.message || e)); }
     finally { setBusy(""); }

src/hexgraph/agent/mcp_catalog.py

@@ -125,10 +125,10 @@
      {"type": "object", "properties": {"project_id": {"type": "string"}, "target_id": {"type": "string"}}, "required": ["project_id", "target_id"]}),
     ("write", "target_restore", _t.restore_target, "Un-archive a previously soft-removed target subtree (its nodes/findings reappear).",
      {"type": "object", "properties": {"project_id": {"type": "string"}, "target_id": {"type": "string"}}, "required": ["project_id", "target_id"]}),
-    ("write", "target_set_visible", _t.set_visible, "REVEAL (visible=true) or re-HIDE (visible=false) ONE target in the curated graph. Firmware ELF children are hidden by default — unpack registers each (searchable via target_list(include_hidden=true), addressable, recon-enriched) but they'd flood the graph, so they contribute NOTHING to it until revealed. Revealing materializes the target's recon symbol/string nodes from the already-stored facts (no re-run) so it joins the graph + Targets pane immediately; optional Ghidra enrichment (if enabled) runs DETACHED in the background — a cold headless pass can take minutes, this call does not wait for it. Use after target_list(include_hidden=true)/fs_list surfaces a child worth analyzing. Returns {target_id, name, visible, materialized, enrichment_queued}.",
-     {"type": "object", "properties": {"project_id": {"type": "string"}, "target_id": {"type": "string"}, "visible": {"type": "boolean", "description": "true to reveal (default), false to re-hide"}}, "required": ["project_id", "target_id"]}),
-    ("write", "target_reveal_dir", _t.reveal_dir, "REVEAL every HIDDEN child of a firmware whose rootfs path is under `prefix` (e.g. prefix='usr/sbin' reveals all ELFs in /usr/sbin) — the bulk counterpart to target_set_visible for bringing a whole directory of binaries into the curated graph at once. An empty prefix reveals ALL hidden children. Materializes each revealed child's recon nodes from stored facts (no re-run) — fast, even for a directory with many binaries; optional per-binary Ghidra enrichment (if enabled) runs DETACHED in the background instead of blocking this call (a dozen+ binaries analyzed sequentially can take hours). `target_id` is the firmware. Returns {firmware_target_id, prefix, revealed, target_ids, enrichment_queued}.",
-     {"type": "object", "properties": {"project_id": {"type": "string"}, "target_id": {"type": "string", "description": "the firmware target whose children to reveal"}, "prefix": {"type": "string", "description": "rootfs directory prefix (e.g. 'usr/sbin'); empty reveals all hidden children"}}, "required": ["project_id", "target_id"]}),
+    ("write", "target_set_visible", _t.set_visible, "REVEAL (visible=true) or re-HIDE (visible=false) ONE target in the curated graph. Firmware ELF children are hidden by default — unpack registers each (searchable via target_list(include_hidden=true), addressable, recon-enriched) but they'd flood the graph, so they contribute NOTHING to it until revealed. Revealing materializes the target's recon symbol/string nodes from the already-stored facts (no re-run) so it joins the graph + Targets pane immediately. Ghidra enrichment does NOT run automatically — pass `enrich=true` to also queue it DETACHED in the background (a cold headless pass can take minutes; still needs features.ghidra.enrich_recon on — enrich=true is an ADDITIONAL opt-in per call, not a replacement). Use after target_list(include_hidden=true)/fs_list surfaces a child worth analyzing. Returns {target_id, name, visible, materialized, enrichment_queued}.",
+     {"type": "object", "properties": {"project_id": {"type": "string"}, "target_id": {"type": "string"}, "visible": {"type": "boolean", "description": "true to reveal (default), false to re-hide"}, "enrich": {"type": "boolean", "description": "also queue detached Ghidra enrichment for this target (default false — reveal alone does not trigger analysis)"}}, "required": ["project_id", "target_id"]}),
+    ("write", "target_reveal_dir", _t.reveal_dir, "REVEAL every HIDDEN child of a firmware whose rootfs path is under `prefix` (e.g. prefix='usr/sbin' reveals all ELFs in /usr/sbin) — the bulk counterpart to target_set_visible for bringing a whole directory of binaries into the curated graph at once. An empty prefix reveals ALL hidden children. Materializes each revealed child's recon nodes from stored facts (no re-run) — fast, even for a directory with many binaries. Ghidra enrichment does NOT run automatically — pass `enrich=true` to also queue it for the WHOLE batch as one detached background process working through them sequentially (a dozen+ binaries can take hours; still needs features.ghidra.enrich_recon on). Don't pass enrich=true reflexively; it's for when you deliberately want deep analysis on everything in that directory, not the default way to browse. `target_id` is the firmware. Returns {firmware_target_id, prefix, revealed, target_ids, enrichment_queued}.",
+     {"type": "object", "properties": {"project_id": {"type": "string"}, "target_id": {"type": "string", "description": "the firmware target whose children to reveal"}, "prefix": {"type": "string", "description": "rootfs directory prefix (e.g. 'usr/sbin'); empty reveals all hidden children"}, "enrich": {"type": "boolean", "description": "also queue detached Ghidra enrichment for every revealed binary, as one batched background process (default false)"}}, "required": ["project_id", "target_id"]}),
 
     # ---- re: static reverse engineering ---------------------------------------------
     ("read", "re_list_functions", _t.list_functions, "List/GREP the functions discovered in a target (name + the discovered set) for a substring `pattern` (or a regex with regex=true) — the fast function-name search. Server-side filtered + PAGINATED exactly like re_list_strings: pass `pattern` to filter by name, `offset`/`limit` to page (default 200, max 1000); the result reports the total match count + the next offset. With no `pattern` it pages the whole list. QUERY: records a function_list Observation; adds no graph nodes. Requires a saved analysis when Ghidra is the active backend (run re_analyze first on a warm miss).", {"type": "object", "properties": {"target_id": {"type": "string"}, "pattern": {"type": "string", "description": "substring to grep the function names for"}, "regex": {"type": "boolean", "description": "treat pattern as a regex (falls back to substring if it doesn't compile)"}, "offset": {"type": "integer", "description": "page start index into the matches (default 0)"}, "limit": {"type": "integer", "description": "max names to return (default 200, clamped 1-1000)"}}, "required": ["target_id"]}),

src/hexgraph/agent/mcp_tools.py

@@ -1543,38 +1543,43 @@ def restore_target(project_id: str, target_id: str) -> dict:
             return {"error": str(exc)}
 
 
-def set_visible(project_id: str, target_id: str, visible: bool = True) -> dict:
+def set_visible(project_id: str, target_id: str, visible: bool = True, enrich: bool = False) -> dict:
     """REVEAL (visible=true) or re-HIDE (visible=false) one target in the curated graph.
     Firmware ELF children are HIDDEN by default (unpack registers each so it's searchable
     and addressable, but a 765-ELF firmware would otherwise flood the graph/Targets pane);
     recon already enriched them. Revealing materializes the target's recon nodes from the
-    already-stored facts (no re-run) so it joins the graph immediately; optional Ghidra
-    enrichment (if enabled) runs DETACHED in the background — `enrichment_queued` says
-    whether a task was kicked off (a cold headless Ghidra pass can take minutes; this call
-    does not wait for it). Returns {target_id, name, visible, materialized, enrichment_queued}."""
+    already-stored facts (no re-run) so it joins the graph immediately. Ghidra enrichment does
+    NOT happen automatically — pass `enrich=true` to also queue it, DETACHED in the background
+    (a cold headless Ghidra pass can take minutes; still requires features.ghidra.enrich_recon
+    to be on, `enrich=true` is an additional opt-in per call, not a replacement for it).
+    `enrichment_queued` says whether a task was actually kicked off. Returns {target_id, name,
+    visible, materialized, enrichment_queued}."""
     from hexgraph.engine.targets.reveal import set_visible as _set
 
     with session_scope() as s:
         if s.get(Project, project_id) is None:
             return {"error": "project not found"}
         try:
-            return _set(s, project_id, target_id, visible)
+            return _set(s, project_id, target_id, visible, enrich=enrich)
         except ValueError as exc:
             return {"error": str(exc)}
 
 
-def reveal_dir(project_id: str, target_id: str, prefix: str = "") -> dict:
+def reveal_dir(project_id: str, target_id: str, prefix: str = "", enrich: bool = False) -> dict:
     """REVEAL every HIDDEN child of a firmware whose rootfs path is under `prefix`
     (e.g. prefix='usr/sbin' reveals all ELFs in /usr/sbin) — the bulk counterpart to
     target_set_visible for bringing a whole directory of binaries into the curated graph
     at once. An empty prefix reveals ALL hidden children. Materializes each revealed
     child's recon nodes from stored facts (no re-run) — fast, even for a directory with many
-    binaries. Optional Ghidra enrichment per binary (if enabled) runs DETACHED in the
-    background rather than blocking this call (a cold headless Ghidra pass on a dozen+
-    binaries sequentially can take hours; this call returns as soon as they're revealed).
+    binaries. Ghidra enrichment does NOT happen automatically — pass `enrich=true` to also
+    queue it for the whole batch as ONE detached background process working through them
+    sequentially (a cold headless Ghidra pass on a dozen+ binaries can take hours; still
+    requires features.ghidra.enrich_recon to be on). Don't pass enrich=true reflexively —
+    it's meant for when you deliberately want deep analysis on everything in that directory,
+    not as the default way to browse a firmware's contents.
     `target_id` is the firmware. Returns {firmware_target_id, prefix, revealed, target_ids,
-    enrichment_queued} (enrichment_queued = how many revealed targets got a background
-    enrichment task)."""
+    enrichment_queued} (enrichment_queued = how many revealed targets got queued into that
+    background batch; always 0 when enrich=false)."""
     # NB: the catalog advertises this arg as `target_id` (the firmware), and the MCP
     # server dispatches by KEYWORD (`fn(**arguments)`), so this param name MUST match
     # the catalog schema — otherwise every MCP call raises TypeError.
@@ -1584,7 +1589,7 @@ def reveal_dir(project_id: str, target_id: str, prefix: str = "") -> dict:
         if s.get(Project, project_id) is None:
             return {"error": "project not found"}
         try:
-            return _reveal(s, project_id, target_id, prefix)
+            return _reveal(s, project_id, target_id, prefix, enrich=enrich)
         except ValueError as exc:
             return {"error": str(exc)}
 

src/hexgraph/agent/vr_skill.py

@@ -417,10 +417,12 @@
   `fs_list` entry that's `added` but not `revealed` already IS a target — reveal it (recon
   already enriched it; reveal materializes its nodes, no re-run) rather than re-promoting.
   Reveal the binaries worth analyzing, then decompile / `task_run` / fuzz them like any other.
-  If Ghidra enrichment is enabled, it runs DETACHED per revealed binary (`enrichment_queued`
-  in the response) — a directory can have a dozen-plus binaries, each a cold headless Ghidra
-  pass; don't expect it done by the time this call returns, and don't loop calling
-  `target_reveal_dir` back-to-back on overlapping prefixes waiting for it to "finish".
+  Ghidra enrichment does NOT run automatically on reveal — pass `enrich=true` only when you
+  deliberately want deep Ghidra analysis on everything you're revealing (still needs
+  features.ghidra.enrich_recon on). When you do, it runs DETACHED as one batched background
+  process, not one per binary (`enrichment_queued` in the response) — a directory can have a
+  dozen-plus binaries; don't expect it done by the time this call returns, and don't loop
+  calling `target_reveal_dir` back-to-back on overlapping prefixes waiting for it to "finish".
 - **target_promote_file(target_id, path)** — promote a NON-ELF file or one unpack didn't register
   (a CGI script, a helper) into its OWN child target (created visible), then analyze it. Use
   `target_set_visible`/`target_reveal_dir` for the ELF children that already exist hidden, and

src/hexgraph/api/routers/targets.py

@@ -177,41 +177,49 @@ def api_remove_target(project_id: str, target_id: str):
 
 class VisibleUpdate(BaseModel):
     visible: bool = True
+    # Off by default: revealing a target and running a (detached, but still real) Ghidra
+    # analysis on it are separate decisions — see engine.targets.reveal for why auto-enrich
+    # on reveal was a real incident (an operator paged 2+ hours revealing a directory whose
+    # dozen-plus binaries each silently queued a background analysis).
+    enrich: bool = False
 
 
 @router.post("/api/projects/{project_id}/targets/{target_id}/visible")
 def api_set_target_visible(project_id: str, target_id: str, body: VisibleUpdate):
     """Reveal (visible=true) or re-hide (visible=false) one target. Firmware children
     are HIDDEN by default (unpack registers them so they're searchable/addressable, but
     they add nothing to the curated graph); revealing materializes the target's recon
-    nodes from the already-stored facts (no re-run)."""
+    nodes from the already-stored facts (no re-run). Ghidra enrichment does not run
+    automatically — pass enrich=true to also queue it, detached."""
     from hexgraph.engine.targets.reveal import set_visible
 
     with session_scope() as s:
         if s.get(Project, project_id) is None:
             raise HTTPException(404, "project not found")
         try:
-            return set_visible(s, project_id, target_id, body.visible)
+            return set_visible(s, project_id, target_id, body.visible, enrich=body.enrich)
         except ValueError as exc:
             raise HTTPException(404, str(exc))
 
 
 class RevealDir(BaseModel):
     prefix: str = ""
+    enrich: bool = False
 
 
 @router.post("/api/projects/{project_id}/targets/{target_id}/reveal-dir")
 def api_reveal_dir(project_id: str, target_id: str, body: RevealDir):
     """Reveal every HIDDEN child of a firmware whose rootfs path is under `prefix`
     (e.g. "usr/sbin" reveals all ELFs under that directory). Materializes each revealed
-    child's recon nodes. `target_id` is the firmware target."""
+    child's recon nodes. `target_id` is the firmware target. Ghidra enrichment does not run
+    automatically — pass enrich=true to also queue it for the whole batch, detached."""
     from hexgraph.engine.targets.reveal import reveal_dir
 
     with session_scope() as s:
         if s.get(Project, project_id) is None:
             raise HTTPException(404, "project not found")
         try:
-            return reveal_dir(s, project_id, target_id, body.prefix)
+            return reveal_dir(s, project_id, target_id, body.prefix, enrich=body.enrich)
         except ValueError as exc:
             raise HTTPException(404, str(exc))
 

src/hexgraph/engine/pipeline.py

@@ -53,8 +53,9 @@ def _record_progress(session: Session, target: Target, stage: str, **extra) -> N
 def _maybe_enrich_ghidra(session: Session, project: Project, target: Target, facts: dict) -> None:
     """Optionally fold Ghidra's function/call-graph/struct inventory into the graph
     (Settings → features.ghidra.enrich_recon). Best-effort: never breaks recon.
-    Skipped for HIDDEN targets — a hidden target adds nothing to the curated graph
-    until revealed (reveal runs this enrichment then)."""
+    Skipped for HIDDEN targets — a hidden target adds nothing to the curated graph until
+    revealed, and revealing no longer auto-enriches either (engine.targets.reveal requires
+    an explicit per-call `enrich=True`, not just the global setting)."""
     if not target.visible:
         return
     if facts.get("kind") not in _ENRICHABLE_KINDS: