entrygraph 0.1.6__tar.gz → 0.1.7__tar.gz

{entrygraph-0.1.6 → entrygraph-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: entrygraph
-Version: 0.1.6
+Version: 0.1.7
 Summary: Language-agnostic code graph: query symbols, entrypoints, and source-to-sink call paths from a SQLite index
 Project-URL: Repository, https://github.com/brettbergin/entrygraph
 Author-email: Brett Bergin <brettberginbc@yahoo.com>
@@ -202,8 +202,11 @@ entrygraph paths --source '*' --sink-category command_exec
   `--source-category http_input` / `env`) — `entrygraph paths --source-category http_input --sink-category sql`. Combine with `--source` to union both.
 - **Precision/recall dial**: by default only high-confidence edges are traversed.
   Widen with `--include-unresolved` (wildcard `py:*.execute` sinks + dynamic
-  calls) or `--include-fuzzy` (speculative class-hierarchy edges); drop
-  neutralized paths with `--prune-sanitized`.
+  calls) or `--include-fuzzy` (speculative class-hierarchy edges).
+- **Sanitizers**: a registered sanitizer for the sink's category called on a
+  path (e.g. `shlex.quote`) *discounts* its risk score — heuristically, since
+  there is no dataflow, so it never zeroes the risk or hides the path.
+  `--prune-sanitized` opts into dropping those paths entirely.
 - Target an exact sink with `--sink py:subprocess.run` instead of a category.
 
 ### `stats` & `--json`
@@ -294,7 +297,7 @@ graph.paths(source="app.routes.*", sink_category="sql",
 graph.paths(source="app.routes.*", sink_category="command_exec",
             include_fuzzy=True)        # follow speculative class-hierarchy (CHA) edges
 graph.paths(source="app.routes.*", sink_category="command_exec",
-            prune_sanitized=True)      # drop paths neutralized by a shlex.quote etc.
+            prune_sanitized=True)      # drop paths where a shlex.quote etc. is called
 
 # Incremental re-index (only changed/added/deleted files are reparsed)
 graph.refresh()
@@ -335,9 +338,11 @@ results are safe to hold and trivial to serialize.
   root with `[[sink]]` / `[[source]]` / `[[sanitizer]]` tables (same schema as
   the built-in `data/sinks/*.toml`), or call
   `entrygraph.detect.taint.register_sink(...)` / `register_sanitizer(...)`. A
-  `[[sanitizer]]` with `effect = "neutralizes"` prunes a path for its category;
-  `effect = "reduces"` only discounts the risk score. Third-party wrapper
-  libraries that reach a sink internally are covered by `data/sinks/lib_*.toml`
+  `[[sanitizer]]` called on a path discounts its risk score for that category;
+  since reachability has no dataflow, the discount is capped (a match never
+  zeroes risk or hides a path — use `--prune-sanitized` to drop them explicitly).
+  Third-party wrapper libraries that reach a sink internally are covered by
+  `data/sinks/lib_*.toml`
   "library summaries" (same schema, with a `library = "..."` tag).
 - **New frameworks / entrypoints** — register a `FrameworkSpec` and an
   `EntrypointRule`; adding a framework is usually a few lines.

{entrygraph-0.1.6 → entrygraph-0.1.7}/README.md

@@ -151,8 +151,11 @@ entrygraph paths --source '*' --sink-category command_exec
   `--source-category http_input` / `env`) — `entrygraph paths --source-category http_input --sink-category sql`. Combine with `--source` to union both.
 - **Precision/recall dial**: by default only high-confidence edges are traversed.
   Widen with `--include-unresolved` (wildcard `py:*.execute` sinks + dynamic
-  calls) or `--include-fuzzy` (speculative class-hierarchy edges); drop
-  neutralized paths with `--prune-sanitized`.
+  calls) or `--include-fuzzy` (speculative class-hierarchy edges).
+- **Sanitizers**: a registered sanitizer for the sink's category called on a
+  path (e.g. `shlex.quote`) *discounts* its risk score — heuristically, since
+  there is no dataflow, so it never zeroes the risk or hides the path.
+  `--prune-sanitized` opts into dropping those paths entirely.
 - Target an exact sink with `--sink py:subprocess.run` instead of a category.
 
 ### `stats` & `--json`
@@ -243,7 +246,7 @@ graph.paths(source="app.routes.*", sink_category="sql",
 graph.paths(source="app.routes.*", sink_category="command_exec",
             include_fuzzy=True)        # follow speculative class-hierarchy (CHA) edges
 graph.paths(source="app.routes.*", sink_category="command_exec",
-            prune_sanitized=True)      # drop paths neutralized by a shlex.quote etc.
+            prune_sanitized=True)      # drop paths where a shlex.quote etc. is called
 
 # Incremental re-index (only changed/added/deleted files are reparsed)
 graph.refresh()
@@ -284,9 +287,11 @@ results are safe to hold and trivial to serialize.
   root with `[[sink]]` / `[[source]]` / `[[sanitizer]]` tables (same schema as
   the built-in `data/sinks/*.toml`), or call
   `entrygraph.detect.taint.register_sink(...)` / `register_sanitizer(...)`. A
-  `[[sanitizer]]` with `effect = "neutralizes"` prunes a path for its category;
-  `effect = "reduces"` only discounts the risk score. Third-party wrapper
-  libraries that reach a sink internally are covered by `data/sinks/lib_*.toml`
+  `[[sanitizer]]` called on a path discounts its risk score for that category;
+  since reachability has no dataflow, the discount is capped (a match never
+  zeroes risk or hides a path — use `--prune-sanitized` to drop them explicitly).
+  Third-party wrapper libraries that reach a sink internally are covered by
+  `data/sinks/lib_*.toml`
   "library summaries" (same schema, with a `library = "..."` tag).
 - **New frameworks / entrypoints** — register a `FrameworkSpec` and an
   `EntrypointRule`; adding a framework is usually a few lines.

{entrygraph-0.1.6 → entrygraph-0.1.7}/src/entrygraph/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.6'
-__version_tuple__ = version_tuple = (0, 1, 6)
+__version__ = version = '0.1.7'
+__version_tuple__ = version_tuple = (0, 1, 7)
 
 __commit_id__ = commit_id = None

{entrygraph-0.1.6 → entrygraph-0.1.7}/src/entrygraph/api.py

@@ -66,9 +66,13 @@ def _traversal_params(
     return floor, include_fuzzy
 
 
-def _fully_sanitized(path: CallPath) -> bool:
-    """True if the terminal hop was neutralized by a sanitizer (risk driven to 0)."""
-    return path.risk_score == 0.0
+def _has_sanitizer(path: CallPath) -> bool:
+    """True if a category sanitizer is called on the path (heuristic, no dataflow).
+
+    Drives ``--prune-sanitized``. Sanitizer matches only discount risk (never zero
+    it), so pruning is an explicit opt-in that trades recall for noise reduction
+    rather than a silent, certain "this path is safe" claim."""
+    return any(e.sanitized_by for e in path.edges)
 
 
 class CodeGraph:
@@ -296,13 +300,20 @@ class CodeGraph:
             edge_map = self._edge_rows(session, raw_paths)
             tainted_sources = self._tainted_source_ids(session, sources)
             excluded_nodes = self._nodes_with_open_frontier(session, all_ids, kinds, floor)
+            sibling_calls = self._out_call_qnames(session, all_ids)
             built = [
                 self._materialize_path(
-                    path, symbol_map, edge_map, registry, tainted_sources, excluded_nodes
+                    path,
+                    symbol_map,
+                    edge_map,
+                    registry,
+                    tainted_sources,
+                    excluded_nodes,
+                    sibling_calls,
                 )
                 for path in raw_paths
             ]
-        results = [cp for cp in built if not (prune_sanitized and _fully_sanitized(cp))]
+        results = [cp for cp in built if not (prune_sanitized and _has_sanitizer(cp))]
         results.sort(
             key=lambda p: (-(p.risk_score or 0.0), len(p.symbols), [s.id for s in p.symbols])
         )
@@ -543,8 +554,38 @@ class CodeGraph:
         ).scalars()
         return set(rows)
 
+    @staticmethod
+    def _out_call_qnames(session: Session, node_ids: set[int]) -> dict[int, list[str]]:
+        """For each node, the callee qnames of its outgoing CALLS edges.
+
+        Used for sanitizer detection: a sanitizer is usually a *sibling* call of
+        an on-path function (`shlex.quote(x)` then `subprocess.run(...)`), not a
+        node on the source->sink path itself, so it never appears among the path's
+        own hops."""
+        if not node_ids:
+            return {}
+        from entrygraph.kinds import EdgeKind
+
+        rows = session.execute(
+            select(models.Edge.src_symbol_id, models.Edge.dst_qname).where(
+                models.Edge.src_symbol_id.in_(node_ids),
+                models.Edge.kind == EdgeKind.CALLS,
+            )
+        ).all()
+        out: dict[int, list[str]] = {}
+        for sid, dst_qname in rows:
+            out.setdefault(sid, []).append(dst_qname)
+        return out
+
     def _materialize_path(
-        self, path, symbol_map, edge_map, registry, tainted_sources, excluded_nodes
+        self,
+        path,
+        symbol_map,
+        edge_map,
+        registry,
+        tainted_sources,
+        excluded_nodes,
+        sibling_calls,
     ) -> CallPath:
         symbols = tuple(symbol_map[node] for node, _ in path)
         hops = [hop for _, hop in path[1:]]
@@ -556,10 +597,11 @@ class CodeGraph:
         sink_category = registry.sinks[sink_id].category if sink_id in registry.sinks else None
         terminal_const = is_constant_args(terminal.arg_preview) if terminal else False
 
-        # sanitizer detection: any on-path symbol OR sibling call matching a
-        # sanitizer for the sink's category
+        # sanitizer detection: a sanitizer for the sink's category called by any
+        # on-path node (its own hops OR a sibling call)
+        sibling_qnames = {q for node, _ in path for q in sibling_calls.get(node, ())}
         sanitized_ids, sanitized_effect = self._path_sanitizers(
-            symbols, rows, registry, sink_category
+            symbols, rows, sibling_qnames, registry, sink_category
         )
 
         path_edges: list[PathEdge] = []
@@ -593,17 +635,28 @@ class CodeGraph:
         )
 
     @staticmethod
-    def _path_sanitizers(symbols, rows, registry, sink_category):
-        """Return (matched sanitizer ids, strongest effect) for the sink category."""
+    def _path_sanitizers(symbols, rows, sibling_qnames, registry, sink_category):
+        """Return (matched sanitizer ids, effect) for the sink category.
+
+        Candidates are every callee reachable from an on-path node: the path's own
+        hops plus sibling calls (`sibling_qnames`). The effect is capped at
+        ``"reduces"`` regardless of the catalog's ``effect`` — with no dataflow we
+        cannot prove the sanitized value is the one reaching the sink, so a match
+        discounts risk but never drives it to zero (which would silently hide a
+        real path). ``--prune-sanitized`` is the explicit, heuristic opt-in to
+        drop these."""
         if not sink_category:
             return [], None
         matched: list = []
-        candidates = [s.qname for s in symbols] + [r.dst_qname for r in rows if r is not None]
+        candidates = (
+            [s.qname for s in symbols]
+            + [r.dst_qname for r in rows if r is not None]
+            + list(sibling_qnames)
+        )
         for qname in candidates:
             for san in registry.match_sanitizers(qname):
                 if san.category == sink_category:
                     matched.append(san)
         if not matched:
             return [], None
-        effect = "neutralizes" if any(s.effect == "neutralizes" for s in matched) else "reduces"
-        return [s.id for s in matched], effect
+        return [s.id for s in matched], "reduces"

{entrygraph-0.1.6 → entrygraph-0.1.7}/src/entrygraph/cli/main.py

@@ -415,7 +415,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--prune-sanitized",
         dest="prune_sanitized",
         action="store_true",
-        help="drop paths neutralized by a registered sanitizer",
+        help="drop paths where a category sanitizer is called (heuristic, no dataflow)",
     )
     p.set_defaults(func=cmd_paths)
 

entrygraph-0.1.7/tests/fixtures/python/sanitizer/app.py

@@ -0,0 +1,12 @@
+import shlex
+import subprocess
+
+
+def sanitized(cmd):
+    # shlex.quote is a registered command_exec sanitizer, called on the same
+    # function as the sink (a sibling call, not a node on the source->sink path).
+    subprocess.run(shlex.quote(cmd))
+
+
+def unsanitized(cmd):
+    subprocess.run(cmd)

entrygraph-0.1.7/tests/test_taint_sanitizers.py

@@ -0,0 +1,57 @@
+"""Sanitizer detection over sibling call edges (Phase 1.2).
+
+Regression: builtin sanitizers (external qnames like `py:shlex.quote`) could
+never fire — detection only looked at nodes on the source->sink path, but a
+sanitizer is a *sibling* call of an on-path function. And a heuristic match must
+only discount risk, never drive it to zero (which would hide a real path).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from entrygraph import CodeGraph
+
+SANITIZER_APP = Path(__file__).parent / "fixtures" / "python" / "sanitizer"
+
+
+@pytest.fixture(scope="module")
+def graph(tmp_path_factory) -> CodeGraph:
+    db = tmp_path_factory.mktemp("db") / "graph.db"
+    g = CodeGraph.index(SANITIZER_APP, db=db)
+    yield g
+    g.close()
+
+
+def _path(graph, source):
+    paths = graph.paths(source=source, sink_category="command_exec")
+    assert paths, f"expected a command_exec path from {source}"
+    return paths[0]
+
+
+def test_sibling_sanitizer_is_detected(graph):
+    # shlex.quote is a sibling call of app.sanitized, not a node on the path
+    path = _path(graph, "app.sanitized")
+    assert any("py.sanitize.shlex" in e.sanitized_by for e in path.edges)
+
+
+def test_unsanitized_path_has_no_sanitizer(graph):
+    path = _path(graph, "app.unsanitized")
+    assert all(not e.sanitized_by for e in path.edges)
+
+
+def test_sanitizer_discounts_but_does_not_zero_risk(graph):
+    # the sanitized path must still carry meaningful (nonzero) risk, and be
+    # strictly lower-risk than the identical unsanitized path
+    sanitized = _path(graph, "app.sanitized")
+    unsanitized = _path(graph, "app.unsanitized")
+    assert 0.0 < sanitized.risk_score < unsanitized.risk_score
+
+
+def test_prune_sanitized_drops_only_sanitized_paths(graph):
+    kept = graph.paths(source="app.*", sink_category="command_exec", prune_sanitized=True)
+    sources = {p.symbols[0].qname for p in kept}
+    assert "app.unsanitized" in sources
+    assert "app.sanitized" not in sources