voidaccess 1.8.0__tar.gz → 1.8.1__tar.gz

{voidaccess-1.8.0/voidaccess.egg-info → voidaccess-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidaccess
-Version: 1.8.0
+Version: 1.8.1
 Summary: Dark web OSINT CLI — automated threat intelligence from query to report
 Author: VoidAccess
 License-Expression: MIT

{voidaccess-1.8.0 → voidaccess-1.8.1}/db/models.py

@@ -75,7 +75,7 @@ class RelationshipType(str, enum.Enum):
     LINKED_TO = "LINKED_TO"
     PAID_TO = "PAID_TO"
     MEMBER_OF = "MEMBER_OF"
-    USED = "USED"
+    USES = "USES"
     CLAIMED = "CLAIMED"
     LIKELY_SAME_ACTOR = "LIKELY_SAME_ACTOR"
     CONFIRMED_SAME_ACTOR = "CONFIRMED_SAME_ACTOR"

{voidaccess-1.8.0 → voidaccess-1.8.1}/export/ioc_package.py

@@ -54,7 +54,7 @@ logger = logging.getLogger(__name__)
 # ---------------------------------------------------------------------------
 
 PACKAGE_FORMAT = "voidaccess-ioc-v1"
-PACKAGE_VERSION = "1.8.0"
+PACKAGE_VERSION = "1.8.1"
 SNORT_SID_BASE = 9000001  # 9xxxxxx reserved for VoidAccess-generated rules
 
 # Map extractor upper-case entity types to the per-file bucket they belong to.

{voidaccess-1.8.0 → voidaccess-1.8.1}/export/stix.py

@@ -508,7 +508,7 @@ def _edge_type_to_stix(edge_type: str) -> str:
         "LINKED_TO": "related-to",
         "PAID_TO": "related-to",
         "MEMBER_OF": "member-of",
-        "USED": "uses",
+        "USES": "uses",
         "CLAIMED": "attributed-to",
         "LIKELY_SAME_ACTOR": "related-to",
         "CONFIRMED_SAME_ACTOR": "related-to",

{voidaccess-1.8.0 → voidaccess-1.8.1}/extractor/normalizer.py

@@ -887,6 +887,27 @@ _RFC5737_NETWORKS: list[tuple[str, str]] = [
     ("203.0.113.0", "255.255.255.0"),   # 203.0.113.0/24
 ]
 
+# Real, routable IPs that are never a meaningful indicator of compromise:
+# the unspecified/null address, the broadcast address, and the well-known
+# public DNS resolvers that appear constantly in technical content for
+# reasons unrelated to being an IOC.  Filtered like the RFC 5737 ranges so a
+# user pulling ip_addresses.txt into a blocklist can't end up blocking a
+# legitimate public resolver or a null route.
+_NON_ACTIONABLE_IPS: frozenset[str] = frozenset({
+    "0.0.0.0",              # unspecified / null route — never a real host
+    "255.255.255.255",      # limited broadcast
+    "8.8.8.8", "8.8.4.4",           # Google Public DNS
+    "1.1.1.1", "1.0.0.1",           # Cloudflare Public DNS
+    "9.9.9.9", "149.112.112.112",   # Quad9
+    "208.67.222.222", "208.67.220.220",  # OpenDNS
+    "4.2.2.1", "4.2.2.2",           # Level3 legacy resolvers
+})
+
+
+def _is_non_actionable_ip(value: str) -> bool:
+    """Return True for real IPs that are never meaningful IOCs (null route, public DNS)."""
+    return value.strip() in _NON_ACTIONABLE_IPS
+
 # RFC 2606 reserved domain names.
 _RFC2606_DOMAINS: frozenset[str] = frozenset({
     "example.com",
@@ -1563,6 +1584,14 @@ def normalize_entities(
                 )
                 continue
 
+            if entity_type == "IP_ADDRESS" and _is_non_actionable_ip(canonical):
+                source_quality = 0.0
+                logger.debug(
+                    "Non-actionable IP rejected (null route / broadcast / public DNS resolver): %s",
+                    canonical,
+                )
+                continue
+
             if entity_type == "DOMAIN" and _is_rfc2606_domain(canonical):
                 source_quality = 0.0
                 logger.debug(

{voidaccess-1.8.0 → voidaccess-1.8.1}/extractor/relationship_extract.py

@@ -60,8 +60,8 @@ _DEFAULT_MAX_RELATIONSHIPS_PER_PAGE = 60
 # EDGE_TYPES).  Passive forms map to the same stored type but flip the edge
 # direction (handled below) so the stored edge always reads source -> target.
 _LLM_REL_VOCAB: dict[str, str] = {
-    "uses": "USED",
-    "used": "USED",
+    "uses": "USES",
+    "used": "USES",
     "drops": "DROPS",
     "controls": "CONTROLS",
     "targets": "TARGETS",
@@ -144,17 +144,41 @@ def _parse_relationship_json(raw: str) -> list[dict]:
     return rels if isinstance(rels, list) else []
 
 
+class RelationshipLLMCallError(Exception):
+    """Raised when the relationship-extraction LLM invocation itself fails.
+
+    Distinct from a call that *succeeds* and legitimately returns no
+    relationships — callers use this to log a visible warning so a broken LLM
+    integration can never masquerade as "the LLM found no relationships".
+    """
+
+
 async def _invoke_llm(prompt: str, llm) -> str:
-    """Call the LLM with streaming/callbacks disabled (mirrors llm_extract)."""
-    try:
+    """Call the LLM with streaming/callbacks disabled (mirrors llm_extract).
+
+    Raises :class:`RelationshipLLMCallError` if the underlying invocation
+    fails, so the caller can distinguish a *failed* call from a successful
+    call that found nothing.
+    """
+    # ``bind(callbacks=[])`` puts ``callbacks`` into the model's invocation
+    # kwargs, which LangChain forwards to ``agenerate_prompt`` as ``**kwargs``
+    # — while ``ainvoke`` ALSO passes ``callbacks`` explicitly, raising
+    # "agenerate_prompt() got multiple values for keyword argument 'callbacks'".
+    # ``with_config`` overrides callbacks for this call WITHOUT adding model
+    # kwargs, exactly as extractor/llm_extract._extract_chunk does.
+    if hasattr(llm, "with_config"):
+        silent_llm = llm.with_config({"callbacks": []})
+    else:
         silent_llm = llm.bind(streaming=False, callbacks=[])
+    try:
+        # Guard stdout in case a legacy constructor callback still streams
+        # partial JSON tokens even with an empty per-call callback list.
         with redirect_stdout(io.StringIO()):
             response = await silent_llm.ainvoke(prompt)
-        content = response.content if hasattr(response, "content") else str(response)
-        return content.strip()
-    except Exception as exc:  # noqa: BLE001 — never let one page break the pass
-        logger.warning("Relationship LLM call failed: %s", exc)
-        return ""
+    except Exception as exc:  # noqa: BLE001 — surface as a typed failure
+        raise RelationshipLLMCallError(str(exc)) from exc
+    content = response.content if hasattr(response, "content") else str(response)
+    return content.strip()
 
 
 async def extract_relationships_for_page(
@@ -194,7 +218,19 @@ async def extract_relationships_for_page(
     content = page_text[:max_chunk_chars]
     prompt = _PROMPT_TEMPLATE.format(entities=entity_lines, content=content)
 
-    raw = await _invoke_llm(prompt, llm)
+    try:
+        raw = await _invoke_llm(prompt, llm)
+    except RelationshipLLMCallError as exc:
+        # The LLM call itself failed — this is NOT the same as the LLM running
+        # successfully and finding no relationship.  Log loudly so a broken
+        # integration is visible in normal operation instead of silently
+        # degrading every page to zero typed relationships.
+        logger.warning(
+            "Relationship extraction: LLM call FAILED (%s) — this page yielded "
+            "NO typed relationships due to an error, not because none exist",
+            exc,
+        )
+        return []
     rels = _parse_relationship_json(raw)
     if not rels:
         return []

{voidaccess-1.8.0 → voidaccess-1.8.1}/graph/model.py

@@ -77,7 +77,7 @@ class EDGE_TYPES:
     POSTED_BY = "POSTED_BY"                     # content attributed to a handle
     LINKED_TO = "LINKED_TO"                     # URL links to URL
     MEMBER_OF = "MEMBER_OF"                     # handle to group/forum
-    USED = "USED"                               # actor used a malware family
+    USES = "USES"                               # actor uses a malware family
     CLAIMED = "CLAIMED"                         # group claimed an attack
     LIKELY_SAME_ACTOR = "LIKELY_SAME_ACTOR"     # inferred, medium confidence
     CONFIRMED_SAME_ACTOR = "CONFIRMED_SAME_ACTOR"  # PGP key match, high confidence

{voidaccess-1.8.0 → voidaccess-1.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voidaccess"
-version = "1.8.0"
+version = "1.8.1"
 description = "Dark web OSINT CLI — automated threat intelligence from query to report"
 readme = "README.md"
 license = "MIT"

{voidaccess-1.8.0 → voidaccess-1.8.1}/sources/enrichment.py

@@ -565,6 +565,42 @@ def abusech_to_pages(
 _RANSOMWARE_LIVE_BASE = "https://api.ransomware.live/v2"
 _RANSOMWARE_LIVE_HEADERS = {"User-Agent": "VoidAccess-OSINT/1.0", "Accept": "application/json"}
 
+# Generic words that carry no group-identity signal in a realistic analyst
+# query ("LockBit ransomware leak site").  Stripped before matching so the
+# meaningful token(s) — e.g. "lockbit" — are what we match on, rather than
+# requiring the whole query string to appear literally in a group name.
+_GROUP_QUERY_STOPWORDS: frozenset[str] = frozenset({
+    "ransomware", "ransom", "group", "gang", "crew", "team",
+    "leak", "leaks", "leaksite", "site", "blog", "portal",
+    "data", "the", "and", "actor", "threat", "malware",
+})
+
+
+def _significant_group_tokens(query: str) -> list[str]:
+    """Meaningful lowercase tokens from a group query, stopwords removed.
+
+    Falls back to all tokens if every token was a stopword, so a query made
+    entirely of generic words still matches on something rather than nothing.
+    """
+    tokens = re.findall(r"[a-z0-9.]+", (query or "").lower())
+    tokens = [t.strip(".") for t in tokens if t.strip(".")]
+    significant = [t for t in tokens if t not in _GROUP_QUERY_STOPWORDS and len(t) >= 3]
+    return significant or tokens
+
+
+def _group_name_matches_query(name: str, tokens: list[str]) -> bool:
+    """Token-based match of a tracked group name against query tokens.
+
+    A token matches if it is a substring of the group name (so ``lockbit``
+    matches ``lockbit``, ``lockbit2``, ``lockbit3``) or the group name is a
+    substring of the token.  This is how an analyst actually phrases a query,
+    versus the old "entire query string must appear in the name" rule.
+    """
+    n = (name or "").lower()
+    if not n:
+        return False
+    return any(t and (t in n or n in t) for t in tokens)
+
 
 def _rl_extract_onion_urls(group: dict) -> list[str]:
     """Extract .onion leak-site URLs from a group dict (available sites first)."""
@@ -609,10 +645,11 @@ async def fetch_ransomware_live(query: str) -> list[dict]:
                     return []
                 all_groups = await resp.json(content_type=None)
 
+            _tokens = _significant_group_tokens(query)
             matched_summary: list[dict] = []
             for g in (all_groups if isinstance(all_groups, list) else []):
                 name = (g.get("name") or "").lower()
-                if q in name:
+                if _group_name_matches_query(name, _tokens):
                     matched_summary.append(g)
 
             if not matched_summary:
@@ -904,7 +941,8 @@ async def fetch_ransomlook(query: str) -> list[dict]:
                 all_groups = await resp.json(content_type=None)
 
             group_names = [g for g in all_groups if isinstance(g, str)] if isinstance(all_groups, list) else []
-            matched = [name for name in group_names if q in name.lower()]
+            _tokens = _significant_group_tokens(query)
+            matched = [name for name in group_names if _group_name_matches_query(name, _tokens)]
 
             if not matched:
                 logger.info("ransomlook.io: no groups matched %r", query)

{voidaccess-1.8.0 → voidaccess-1.8.1}/tests/test_db.py

@@ -395,7 +395,7 @@ class TestEntityRelationship:
         rel = EntityRelationship(
             entity_a_id=e1.id,
             entity_b_id=e2.id,
-            relationship_type=RelationshipType.USED.value,
+            relationship_type=RelationshipType.USES.value,
             source_page_id=page.id,
             confidence=0.85,
         )
@@ -404,7 +404,7 @@ class TestEntityRelationship:
 
         assert rel.id is not None
         assert rel.confidence == 0.85
-        assert rel.relationship_type == "USED"
+        assert rel.relationship_type == "USES"
 
     def test_bidirectional_orm_access(self, session):
         from db.models import EntityRelationship
@@ -788,12 +788,12 @@ class TestQueries:
             session,
             entity_a_id=e1.id,
             entity_b_id=e2.id,
-            relationship_type="USED",
+            relationship_type="USES",
             source_page_id=page.id,
             confidence=0.9,
         )
         assert rel.id is not None
-        assert rel.relationship_type == "USED"
+        assert rel.relationship_type == "USES"
         assert rel.confidence == 0.9
 
     def test_get_relationships_for_entity(self, session):
@@ -809,7 +809,7 @@ class TestQueries:
         e2 = create_entity(session, page_id=page.id, entity_type="malware", value="Malware_Q")
         e3 = create_entity(session, page_id=page.id, entity_type="handle", value="alias_q")
 
-        create_entity_relationship(session, e1.id, e2.id, "USED", page.id)
+        create_entity_relationship(session, e1.id, e2.id, "USES", page.id)
         create_entity_relationship(session, e3.id, e1.id, "LIKELY_SAME_ACTOR", page.id)
 
         rels = get_relationships_for_entity(session, e1.id)
@@ -849,8 +849,9 @@ class TestEnums:
         from db.models import RelationshipType
         expected = {
             "CO_APPEARED_ON", "POSTED_BY", "LINKED_TO", "PAID_TO",
-            "MEMBER_OF", "USED", "CLAIMED", "LIKELY_SAME_ACTOR",
+            "MEMBER_OF", "USES", "CLAIMED", "LIKELY_SAME_ACTOR",
             "CONFIRMED_SAME_ACTOR", "FUNDED_BY", "POSSIBLE_SAME_AUTHOR",
+            "DROPS", "CONTROLS", "TARGETS", "EXPLOITS", "COMMUNICATES_WITH",
         }
         actual = {r.value for r in RelationshipType}
         assert expected == actual

{voidaccess-1.8.0 → voidaccess-1.8.1}/tests/test_graph.py

@@ -61,7 +61,7 @@ def _make_graph_with_nodes() -> nx.MultiDiGraph:
     # Edges
     g.add_edge("actor1", "wallet1", edge_type="CO_APPEARED_ON", confidence=1.0,
                source_url="http://forum1.onion/page", timestamp=now, metadata={})
-    g.add_edge("actor1", "malware1", edge_type="USED", confidence=0.9,
+    g.add_edge("actor1", "malware1", edge_type="USES", confidence=0.9,
                source_url="http://forum1.onion/page", timestamp=now, metadata={})
     g.add_edge("actor1", "forum1", edge_type="MEMBER_OF", confidence=1.0,
                source_url="", timestamp=now, metadata={})
@@ -122,7 +122,7 @@ class TestModel(unittest.TestCase):
     def test_edge_types_are_strings(self):
         et = self.m.EDGE_TYPES
         for attr in ("CO_APPEARED_ON", "POSTED_BY", "LINKED_TO", "MEMBER_OF",
-                     "USED", "CLAIMED", "LIKELY_SAME_ACTOR", "CONFIRMED_SAME_ACTOR"):
+                     "USES", "CLAIMED", "LIKELY_SAME_ACTOR", "CONFIRMED_SAME_ACTOR"):
             self.assertIsInstance(getattr(et, attr), str, msg=f"EDGE_TYPES.{attr} is not str")
 
     def test_node_types_no_duplicates(self):
@@ -138,7 +138,7 @@ class TestModel(unittest.TestCase):
         et = self.m.EDGE_TYPES
         values = [
             et.CO_APPEARED_ON, et.POSTED_BY, et.LINKED_TO, et.MEMBER_OF,
-            et.USED, et.CLAIMED, et.LIKELY_SAME_ACTOR, et.CONFIRMED_SAME_ACTOR,
+            et.USES, et.CLAIMED, et.LIKELY_SAME_ACTOR, et.CONFIRMED_SAME_ACTOR,
         ]
         self.assertEqual(len(values), len(set(values)), "Duplicate EDGE_TYPES values detected")
 
@@ -700,9 +700,9 @@ class TestQueries(unittest.TestCase):
     def test_get_neighbors_edge_type_filter(self):
         """get_neighbors with edge_type filter only traverses matching edges."""
         from graph.queries import get_neighbors
-        result = get_neighbors(self.graph, "actor1", hops=2, edge_types=["USED"])
+        result = get_neighbors(self.graph, "actor1", hops=2, edge_types=["USES"])
 
-        # Only malware1 should be reachable via USED edge
+        # Only malware1 should be reachable via USES edge
         hop1_ids = {n.node_id for n in result.get("1", [])}
         self.assertIn("malware1", hop1_ids)
         # wallet1 should NOT be in hop 1 (it's connected via CO_APPEARED_ON)

{voidaccess-1.8.0 → voidaccess-1.8.1/voidaccess.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidaccess
-Version: 1.8.0
+Version: 1.8.1
 Summary: Dark web OSINT CLI — automated threat intelligence from query to report
 Author: VoidAccess
 License-Expression: MIT

{voidaccess-1.8.0 → voidaccess-1.8.1}/voidaccess_cli/__init__.py

@@ -1,3 +1,3 @@
 """voidaccess CLI — dark-web OSINT command-line interface."""
 
-__version__ = "1.8.0"
+__version__ = "1.8.1"

{voidaccess-1.8.0 → voidaccess-1.8.1}/voidaccess_cli/commands/investigate.py

@@ -80,6 +80,27 @@ def run(
 
     cli_config.apply_env()
 
+    # Validate the query BEFORE any network activity.  An empty/whitespace-only
+    # or trivially short query cannot yield real intelligence — accepting it
+    # silently produces a report that looks identical to a genuine one but is
+    # just noise from an essentially meaningless search.  Reject up front.
+    MIN_QUERY_LENGTH = 3
+    stripped_query = (query or "").strip()
+    if not stripped_query:
+        console.print(
+            "[red]Empty query.[/red] Provide something to investigate, e.g. "
+            '[bold]voidaccess investigate "LockBit ransomware"[/bold].'
+        )
+        raise typer.Exit(code=2)
+    if len(stripped_query) < MIN_QUERY_LENGTH:
+        console.print(
+            f"[red]Query too short.[/red] '{stripped_query}' is only "
+            f"{len(stripped_query)} character(s); provide at least {MIN_QUERY_LENGTH} "
+            "characters of meaningful context so results reflect a real query, "
+            "not generic noise."
+        )
+        raise typer.Exit(code=2)
+
     # v1.6.2 — --use-scraping-api and --use-proxies are one-shot CLI flags
     # for activating the two independent clearnet transports in-process
     # only.  The REST API flag sets VOIDACCESS_USE_PROXIES=true; the
@@ -352,10 +373,21 @@ async def _run_investigation(
     pipeline_metrics = InvestigationMetrics(inv_uuid)
     set_current(pipeline_metrics)
 
+    # Step-cost instrumentation.  ``start``/``finish`` bracket each phase so
+    # duration_ms is recorded, and — critically — so ``record_llm_call`` (which
+    # only credits steps that are currently *active*) attributes LLM calls to
+    # the right step.  Mirrors the API pipeline's _metric_start/_metric_finish.
+    def _metric_start(step_name: str) -> None:
+        pipeline_metrics.start(step_name)
+
+    def _metric_finish(step_name: str) -> None:
+        pipeline_metrics.finish(step_name)
+
     sources_used: dict[str, dict[str, Any]] = {}
     page_count_by_url: dict[str, dict[str, Any]] = {}
 
     # --- Step 1 — refine query -------------------------------------------
+    _metric_start("query_refinement")
     display.update_step("Refining query", "active")
     refined = query
     if llm is not None:
@@ -370,8 +402,10 @@ async def _run_investigation(
     else:
         display.update_step("Refining query", "skip", "--no-llm")
     sqlite_adapter.update_investigation(investigation_id, {"refined_query": refined})
+    _metric_finish("query_refinement")
 
     # --- Step 2 — search fan-out -----------------------------------------
+    _metric_start("source_gathering")
     display.update_step("Searching dark web", "active")
     search_links: list[dict] = []
     paste_pages: list[dict] = []
@@ -412,6 +446,14 @@ async def _run_investigation(
             return []
 
     async def _onionsearch():
+        # --no-tor means NO Tor traffic for the entire run.  Torch and
+        # Haystack are .onion search engines fetched over the Tor SOCKS proxy,
+        # and they return real .onion result URLs that would otherwise be
+        # appended to the scrape list and routed back through Tor.  Skipping
+        # the lookup entirely is what makes "zero Tor traffic" a direct
+        # consequence rather than a downstream filter after Tor was contacted.
+        if no_tor:
+            return []
         from sources.engines import search_onionsearch
         return await search_onionsearch(refined)
 
@@ -441,6 +483,10 @@ async def _run_investigation(
     if not os.getenv("TELEGRAM_API_ID", "").strip() or not os.getenv("TELEGRAM_API_HASH", "").strip():
         sources_used["telegram"] = {"status": "skipped_no_key"}
     for _engine_name in ("Torch", "Haystack"):
+        if no_tor:
+            # Onion search engines are never contacted in --no-tor mode.
+            sources_used[_engine_name.lower()] = {"status": "skipped", "count": 0}
+            continue
         _count = sum(1 for item in onion_pages if item.get("source") == _engine_name)
         from sources.engines import get_last_onionsearch_status
         _engine_status = get_last_onionsearch_status().get(_engine_name, "ok")
@@ -449,6 +495,25 @@ async def _run_investigation(
             "count": _count,
         }
 
+    # --no-tor defence-in-depth: even though the Tor search branch and the
+    # onion search engines are both skipped above, strip any .onion URL that
+    # may have reached the link list from ANY other side-source before it can
+    # be handed to the scraper (the scraper correctly routes .onion links
+    # through Tor, which is exactly what --no-tor must prevent).  This runs
+    # BEFORE any scrape, so no Tor connection is ever attempted.
+    if no_tor:
+        _before = len(search_links)
+        search_links = [
+            _l for _l in search_links
+            if ".onion" not in str(_l.get("link", "")).lower()
+        ]
+        _stripped = _before - len(search_links)
+        if _stripped:
+            logger.warning(
+                "[no-tor] Stripped %d .onion link(s) from search results before scraping",
+                _stripped,
+            )
+
     if not no_tor and search_summary:
         display.update_step(
             "Searching dark web",
@@ -495,7 +560,10 @@ async def _run_investigation(
         filtered_links = (search_links or [])[:filter_top_n]
         display.update_step("Filtering results", "skip" if no_llm else "ok", f"{len(filtered_links)} kept")
 
+    _metric_finish("source_gathering")
+
     # --- Step 4 — scrape pages -------------------------------------------
+    _metric_start("scraping")
     display.update_step("Scraping pages", "active")
     scraped_pages: list[dict] = []
     if filtered_links:
@@ -521,11 +589,18 @@ async def _run_investigation(
             for url, text in results.items():
                 if text:
                     scraped_pages.append({"url": url, "text": text, "source": "tor_search"})
+            _fetched = sum(1 for _t in results.values() if _t)
+            pipeline_metrics.record_scraping(
+                attempted=len(filtered_links),
+                fetched=_fetched,
+                cache_hits=0,
+            )
             display.update_step("Scraping pages", "ok", f"{len(scraped_pages)} pages")
         except Exception as exc:
             display.update_step("Scraping pages", "fail", str(exc))
     else:
         display.update_step("Scraping pages", "skip", "no links")
+    _metric_finish("scraping")
 
     # --- Step 4.1 — discover seeds from scraped pages --------------------
     # scrape_multiple already submits discovered seeds fire-and-forget, but
@@ -576,6 +651,7 @@ async def _run_investigation(
     page_count_by_url = {p["url"]: p for p in scraped_pages}
 
     # --- Step 5 — extract entities ---------------------------------------
+    _metric_start("entity_extraction")
     display.update_step("Extracting entities", "active")
     extraction_results = []
     try:
@@ -591,8 +667,10 @@ async def _run_investigation(
         display.update_step("Extracting entities", "ok", f"{total_entities} entities")
     except Exception as exc:
         display.update_step("Extracting entities", "fail", str(exc))
+    _metric_finish("entity_extraction")
 
     # --- Step 6 — enrich intelligence (OTX + IP) ---------------------------
+    _metric_start("enrichment")
     display.update_step("Enriching intelligence", "active")
     enrichment_pages: list[dict] = []
     try:
@@ -735,6 +813,7 @@ async def _run_investigation(
             )
         except Exception as exc:
             console.print(f"[grey50]Enrichment extraction failed: {exc}[/grey50]")
+    _metric_finish("enrichment")
 
     # --- Step 6.9 — Update persistent actor profiles (non-blocking) -------
     # Aggregate THREAT_ACTOR_HANDLE / RANSOMWARE_GROUP entities from the
@@ -770,6 +849,7 @@ async def _run_investigation(
     # --- Step 7 — build graph (co-occurrence) ----------------------------
     # Phase 6.2 — capped by CLI_PHASE_TIMEOUTS["graph_build"] so a large
     # entity table doesn't pin the CLI thread indefinitely.
+    _metric_start("graph_build")
     display.update_step("Building graph", "active")
     try:
         edges_written = await asyncio.wait_for(
@@ -798,10 +878,12 @@ async def _run_investigation(
         )
     except Exception as exc:
         logger.debug("Community detection skipped: %s", exc)
+    _metric_finish("graph_build")
 
     # --- Step 8 — summary -------------------------------------------------
     # Phase 6.2 — capped by CLI_PHASE_TIMEOUTS["summary"] so a slow LLM
     # call never holds the CLI process open past its budget.
+    _metric_start("summary_generation")
     display.update_step("Generating summary", "active")
     summary_text = ""
     if llm is not None:
@@ -826,8 +908,10 @@ async def _run_investigation(
             display.update_step("Generating summary", "fail", str(exc))
     else:
         display.update_step("Generating summary", "skip", "--no-llm")
+    _metric_finish("summary_generation")
 
     # --- Step 9 — finalize & write outputs --------------------------------
+    _metric_start("finalization")
     display.update_step("Finalizing results", "active")
     final_entities = sqlite_adapter.get_entities(investigation_id)
     final_relationships = sqlite_adapter.get_relationships(investigation_id)
@@ -886,6 +970,7 @@ async def _run_investigation(
         md_path.write_text(_render_markdown(payload), encoding="utf-8")
 
     display.update_step("Finalizing results", "ok")
+    _metric_finish("finalization")
 
     # Drain any background tasks scheduled during the pipeline (e.g. the
     # actor-profile aggregator).  This keeps the "fire-and-forget"