entrygraph 0.1.5__tar.gz → 0.1.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: entrygraph
-Version: 0.1.5
+Version: 0.1.6
 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>
@@ -197,6 +197,9 @@ entrygraph paths --source '*' --sink-category command_exec
 
 - **CI gate**: exits `0` when a path is found, `1` when none —
   `entrygraph paths --source '*' --sink-category command_exec && echo reachable`.
+- **Catalog sources**: instead of a `--source` glob, use `--source-category` to
+  start from every call site of a registered taint source (e.g.
+  `--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

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

@@ -146,6 +146,9 @@ entrygraph paths --source '*' --sink-category command_exec
 
 - **CI gate**: exits `0` when a path is found, `1` when none —
   `entrygraph paths --source '*' --sink-category command_exec && echo reachable`.
+- **Catalog sources**: instead of a `--source` glob, use `--source-category` to
+  start from every call site of a registered taint source (e.g.
+  `--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

{entrygraph-0.1.5 → entrygraph-0.1.6}/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.5'
-__version_tuple__ = version_tuple = (0, 1, 5)
+__version__ = version = '0.1.6'
+__version_tuple__ = version_tuple = (0, 1, 6)
 
 __commit_id__ = commit_id = None

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

@@ -251,7 +251,8 @@ class CodeGraph:
     def paths(
         self,
         *,
-        source: SourceSpec,
+        source: SourceSpec | None = None,
+        source_category: str | None = None,
         sink: SourceSpec | None = None,
         sink_category: str | None = None,
         max_depth: int = 25,
@@ -266,6 +267,11 @@ class CodeGraph:
     ) -> list[CallPath]:
         """Enumerate source->sink call paths, risk-ranked (highest first).
 
+        Sources are an explicit `source` spec (qname/glob/Symbol/Entrypoint) and/or
+        a `source_category` resolved from the taint-source catalog (e.g. every call
+        site of an `http_input`/`env` source). Sinks work the same via `sink` /
+        `sink_category`.
+
         By default only EXACT/IMPORT edges are traversed; `include_fuzzy` /
         `include_unresolved` lower the confidence floor (an explicit
         `min_confidence` int overrides the flags). `include_callbacks` also
@@ -276,7 +282,7 @@ class CodeGraph:
         floor, include_cha = _traversal_params(min_confidence, include_fuzzy, include_unresolved)
         kinds = (*edge_kinds, "callback") if include_callbacks else edge_kinds
         with self._session_factory() as session:
-            sources = self._spec_to_ids(session, source)
+            sources = self._source_ids(session, source, source_category)
             sinks = self._sink_ids(session, sink, sink_category)
             if not sources or not sinks:
                 return []
@@ -305,7 +311,8 @@ class CodeGraph:
     def reachable(
         self,
         *,
-        source: SourceSpec,
+        source: SourceSpec | None = None,
+        source_category: str | None = None,
         sink: SourceSpec | None = None,
         sink_category: str | None = None,
         max_depth: int = 25,
@@ -319,7 +326,7 @@ class CodeGraph:
         floor, include_cha = _traversal_params(min_confidence, include_fuzzy, include_unresolved)
         kinds = (*edge_kinds, "callback") if include_callbacks else edge_kinds
         with self._session_factory() as session:
-            sources = self._spec_to_ids(session, source)
+            sources = self._source_ids(session, source, source_category)
             sinks = self._sink_ids(session, sink, sink_category)
             if not sources or not sinks:
                 return False
@@ -362,6 +369,9 @@ class CodeGraph:
                 sink_edges=count(
                     select(func.count(models.Edge.id)).where(models.Edge.sink_id.is_not(None))
                 ),
+                source_edges=count(
+                    select(func.count(models.Edge.id)).where(models.Edge.source_id.is_not(None))
+                ),
             )
 
     def session(self) -> Session:
@@ -426,6 +436,22 @@ class CodeGraph:
             return {spec.symbol.id}
         return q.symbol_ids_matching(session, str(spec))
 
+    def _source_ids(self, session: Session, source, source_category: str | None) -> set[int]:
+        """Taint origins: explicit `source` spec plus, for `source_category`, every
+        symbol that calls a matching catalog taint-source function."""
+        ids = self._spec_to_ids(session, source) if source is not None else set()
+        if source_category is not None:
+            registry = self._registry(session)
+            source_pattern_ids = registry.source_ids_for_category(source_category)
+            if source_pattern_ids:
+                rows = session.execute(
+                    select(models.Edge.src_symbol_id).where(
+                        models.Edge.source_id.in_(source_pattern_ids)
+                    )
+                ).scalars()
+                ids |= set(rows)
+        return ids
+
     def _sink_ids(self, session: Session, sink, sink_category: str | None) -> set[int]:
         ids = self._spec_to_ids(session, sink) if sink is not None else set()
         if sink_category is not None:
@@ -474,18 +500,26 @@ class CodeGraph:
 
     @staticmethod
     def _tainted_source_ids(session: Session, sources: set[int]) -> set[int]:
-        """Source symbol ids that are entrypoints with known user-controlled params."""
+        """Source symbol ids known to carry user-controlled data: entrypoints with
+        tainted params, plus call sites of catalog taint-source functions."""
         if not sources:
             return set()
+        tainted: set[int] = set()
         rows = session.execute(
             select(models.Entrypoint.symbol_id, models.Entrypoint.extra).where(
                 models.Entrypoint.symbol_id.in_(sources)
             )
         ).all()
-        tainted: set[int] = set()
         for sid, extra in rows:
             if extra and json.loads(extra).get("tainted_params"):
                 tainted.add(sid)
+        source_callers = session.execute(
+            select(models.Edge.src_symbol_id).where(
+                models.Edge.source_id.is_not(None),
+                models.Edge.src_symbol_id.in_(sources),
+            )
+        ).scalars()
+        tainted |= set(source_callers)
         return tainted
 
     @staticmethod

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

@@ -261,9 +261,12 @@ def _path_tree(index: int, path) -> Tree:
 
 
 def cmd_paths(args) -> int:
+    if not args.source and not args.source_category:
+        raise EntrygraphError("provide --source and/or --source-category")
     with _open(args) as graph:
         paths = graph.paths(
             source=args.source,
+            source_category=args.source_category,
             sink=args.sink,
             sink_category=args.sink_category,
             max_depth=args.max_depth,
@@ -297,8 +300,11 @@ def cmd_paths(args) -> int:
             Panel("[yellow]No source → sink paths found.[/]", border_style="yellow", expand=False)
         )
         return 1
+    origin = (
+        args.source or (args.source_category and f"category:{args.source_category}") or "source"
+    )
     target = args.sink or (args.sink_category and f"category:{args.sink_category}") or "sink"
-    con.print(f"[bold]{len(paths)}[/] path(s)  [dim]{args.source} → {target}[/]\n")
+    con.print(f"[bold]{len(paths)}[/] path(s)  [dim]{origin} → {target}[/]\n")
     for i, path in enumerate(paths, 1):
         con.print(_path_tree(i, path))
     return 0
@@ -374,7 +380,12 @@ def build_parser() -> argparse.ArgumentParser:
 
     p = sub.add_parser("paths", help="source -> sink call paths")
     add_db(p)
-    p.add_argument("--source", required=True, help="qname or glob")
+    p.add_argument("--source", help="qname or glob")
+    p.add_argument(
+        "--source-category",
+        dest="source_category",
+        help="named taint-source category (e.g. http_input, env)",
+    )
     p.add_argument("--sink", help="qname or glob (e.g. py:subprocess.run)")
     p.add_argument(
         "--sink-category", dest="sink_category", help="named sink category (e.g. command_exec, sql)"

{entrygraph-0.1.5 → entrygraph-0.1.6}/src/entrygraph/db/meta.py

@@ -15,7 +15,7 @@ from sqlalchemy.orm import Session
 from entrygraph.db.models import Base, Meta
 from entrygraph.errors import SchemaMismatchError
 
-SCHEMA_VERSION = 2
+SCHEMA_VERSION = 3
 
 
 def create_schema(engine: Engine) -> None:

{entrygraph-0.1.5 → entrygraph-0.1.6}/src/entrygraph/db/models.py

@@ -127,6 +127,9 @@ class Edge(Base):
     confidence: Mapped[int] = mapped_column(Integer, default=0)  # kinds.Confidence value
     arg_preview: Mapped[str | None] = mapped_column(Text)
     sink_id: Mapped[str | None] = mapped_column(String(64))  # pre-tagged at index time
+    # A call to a taint-source function (request/env/stdin/...) tags its calling
+    # edge; the src symbol is then a taint origin. Pre-tagged at index time.
+    source_id: Mapped[str | None] = mapped_column(String(64))
     # Edge provenance for edges not resolved by the direct import/scope pass:
     # "cha" (class-hierarchy candidate), "dynamic" (getattr/computed call),
     # "reexport" (chased through a barrel file). NULL for directly-resolved edges.
@@ -138,6 +141,7 @@ class Edge(Base):
         Index("ix_edges_srcfile", "src_file_id"),
         Index("ix_edges_unresolved", "dst_qname", sqlite_where=text("dst_symbol_id IS NULL")),
         Index("ix_edges_sink", "sink_id", sqlite_where=text("sink_id IS NOT NULL")),
+        Index("ix_edges_source", "source_id", sqlite_where=text("source_id IS NOT NULL")),
         Index("ix_edges_via", "via", sqlite_where=text("via IS NOT NULL")),
     )
 

{entrygraph-0.1.5 → entrygraph-0.1.6}/src/entrygraph/detect/taint.py

@@ -85,6 +85,7 @@ class SinkRegistry:
         self.sources = {s.id: s for s in sources}
         self.sanitizers = {s.id: s for s in (sanitizers or [])}
         self._compiled = [(_compile(s.callee), s) for s in sinks]
+        self._compiled_sources = [(_compile(s.callee), s) for s in sources]
         self._compiled_sanitizers = [(_compile(s.callee), s) for s in (sanitizers or [])]
 
     def match(self, canonical_callee: str, arg_preview: str | None = None) -> str | None:
@@ -98,6 +99,17 @@ class SinkRegistry:
                 return sink.id
         return None
 
+    def match_source(self, canonical_callee: str) -> str | None:
+        """Return the first matching taint-source id for this callee, or None.
+
+        A call to a source function (e.g. ``flask.request.args.get``, ``os.getenv``)
+        marks its calling site as a taint origin. Stamped on edges at index time,
+        symmetric to :meth:`match`."""
+        for regex, source in self._compiled_sources:
+            if regex.match(canonical_callee):
+                return source.id
+        return None
+
     def match_sanitizers(self, canonical_callee: str) -> list[SanitizerPattern]:
         """Sanitizers whose pattern matches this callee qname."""
         return [s for regex, s in self._compiled_sanitizers if regex.match(canonical_callee)]
@@ -108,6 +120,9 @@ class SinkRegistry:
     def ids_for_category(self, category: str) -> set[str]:
         return {s.id for s in self.sinks.values() if s.category == category}
 
+    def source_ids_for_category(self, category: str) -> set[str]:
+        return {s.id for s in self.sources.values() if s.category == category}
+
     def severity_of(self, sink_id: str | None) -> str | None:
         sink = self.sinks.get(sink_id) if sink_id else None
         return sink.severity if sink else None

{entrygraph-0.1.5 → entrygraph-0.1.6}/src/entrygraph/pipeline/scanner.py

@@ -435,11 +435,9 @@ def _write_edges_and_entrypoints(
         resolver = FileResolver(x, module_ids[path], table, externals, is_package)
         file_id = file_id_by_path[path]
         for edge in resolver.resolve():
-            sink_id = (
-                sink_registry.match(edge.dst_qname, edge.arg_preview)
-                if edge.kind is EdgeKind.CALLS
-                else None
-            )
+            is_call = edge.kind is EdgeKind.CALLS
+            sink_id = sink_registry.match(edge.dst_qname, edge.arg_preview) if is_call else None
+            source_id = sink_registry.match_source(edge.dst_qname) if is_call else None
             edge_rows.append(
                 {
                     "id": alloc.take(Edge),
@@ -452,6 +450,7 @@ def _write_edges_and_entrypoints(
                     "confidence": int(edge.confidence),
                     "arg_preview": edge.arg_preview,
                     "sink_id": sink_id,
+                    "source_id": source_id,
                     "via": edge.via,
                 }
             )

{entrygraph-0.1.5 → entrygraph-0.1.6}/src/entrygraph/results.py

@@ -136,3 +136,4 @@ class GraphStats:
     resolved_edges: int
     entrypoints: int
     sink_edges: int
+    source_edges: int

entrygraph-0.1.6/tests/fixtures/python/taint_source/handler.py

@@ -0,0 +1,12 @@
+import os
+
+
+def handler():
+    # os.getenv is a registered taint source (category "env_input").
+    cmd = os.getenv("CMD")
+    run(cmd)
+
+
+def run(cmd):
+    # os.system is a registered command_exec sink.
+    os.system(cmd)

{entrygraph-0.1.5 → entrygraph-0.1.6}/tests/test_taint.py

@@ -4,6 +4,7 @@ from entrygraph.detect.taint import (
     SanitizerPattern,
     SinkPattern,
     SinkRegistry,
+    SourcePattern,
     _load_toml,
     builtin_registry,
 )
@@ -56,6 +57,25 @@ def test_sanitizer_matching_and_category_lookup():
     assert reg.sanitizers_for_category("command_exec")[0].id == "san"
 
 
+def test_match_source_and_source_category():
+    reg = SinkRegistry(
+        sinks=[],
+        sources=[
+            SourcePattern(id="env", category="env_input", callee="py:{os.getenv,os.environ.get}"),
+            SourcePattern(id="http", category="http_input", callee="py:flask.request*"),
+        ],
+    )
+    assert reg.match_source("py:os.getenv") == "env"
+    assert reg.match_source("py:flask.request.args.get") == "http"
+    assert reg.match_source("py:os.system") is None
+    assert reg.source_ids_for_category("env_input") == {"env"}
+
+
+def test_builtin_registry_matches_env_source():
+    reg = builtin_registry()
+    assert reg.match_source("py:os.getenv") == "py.env"
+
+
 def test_builtin_registry_loads_library_summaries_and_sanitizers():
     reg = builtin_registry()
     # library summary: paramiko exec_command mapped to command_exec

entrygraph-0.1.6/tests/test_taint_sources.py

@@ -0,0 +1,50 @@
+"""End-to-end taint-source catalog wiring (Phase 1.1).
+
+Regression: `[[source]]` catalog entries used to be dead configuration — parsed
+but never matched or stamped, so `paths(source_category=...)` was impossible.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from entrygraph import CodeGraph
+
+TAINT_SOURCE_APP = Path(__file__).parent / "fixtures" / "python" / "taint_source"
+
+
+@pytest.fixture(scope="module")
+def graph(tmp_path_factory) -> CodeGraph:
+    db = tmp_path_factory.mktemp("db") / "graph.db"
+    g = CodeGraph.index(TAINT_SOURCE_APP, db=db)
+    yield g
+    g.close()
+
+
+def test_source_edges_stamped(graph):
+    # os.getenv call in handler() is stamped as a taint source
+    assert graph.stats().source_edges >= 1
+
+
+def test_paths_from_source_category_to_sink_category(graph):
+    # env_input source (os.getenv) reaches a command_exec sink (os.system)
+    paths = graph.paths(source_category="env_input", sink_category="command_exec")
+    assert paths
+    qnames = [s.qname for s in paths[0].symbols]
+    assert qnames[0] == "handler.handler"
+    assert qnames[-1] == "py:os.system"
+
+
+def test_reachable_from_source_category(graph):
+    assert graph.reachable(source_category="env_input", sink_category="command_exec")
+    # a category with no matching source in this repo yields no reach
+    assert not graph.reachable(source_category="http_input", sink_category="command_exec")
+
+
+def test_catalog_source_marks_origin_tainted(graph):
+    # the source-tainted risk factor should apply (handler calls os.getenv), so
+    # the path risk exceeds the untainted-source baseline discount
+    path = graph.paths(source_category="env_input", sink_category="command_exec")[0]
+    assert path.risk_score and path.risk_score > 0.5