codegraph-brain 0.7.3__py3-none-any.whl → 0.7.5__py3-none-any.whl

cgis/api/mcp_server.py

@@ -85,20 +85,92 @@ def _render_subgraph(
     return f"❌ Unknown format '{output_format}'. Use 'mermaid' or 'json'."
 
 
+#: Names cgis will create a database under. Everything else is refused, so an
+#: agent cannot be talked into materialising `~/.ssh/authorized_keys` (#312).
+_DB_SUFFIXES = frozenset({".db", ".sqlite", ".sqlite3"})
+
+#: First 16 bytes of any SQLite file.
+_SQLITE_MAGIC = b"SQLite format 3\x00"
+
+
+def _reject_db_path(db_path: str) -> str | None:
+    """Return a refusal message for an unusable ``db_path``, or None if it is fine.
+
+    ``cgis_ingest`` is the only MCP tool that creates its database — the other
+    twelve refuse a path that does not already exist, which is guard enough for
+    them. It needs a different one: it reads untrusted repository content and is
+    then told by the same agent where to write, so ``db_path`` is attacker-
+    reachable in a way the read-only tools' paths are not.
+
+    Refuses an unexpected suffix, a missing parent directory (creating a tree is
+    never wanted), a directory target, and an existing file that is not a
+    database. The last is belt-and-braces — SQLite already declines to open a
+    non-database — but it fails with a message that says why.
+
+    Everything is judged on the **resolved** path. A dangling symlink is the
+    bypass this guard exists to stop: ``attack.db`` pointing at a target that
+    does not exist yet makes ``is_file()`` return False, every check passes, and
+    SQLite creates the target. Resolving first means the suffix rule applies to
+    where the write actually lands. (A symlink to an *existing* non-database was
+    already refused by the magic-byte check.)
+
+    The filesystem probes are wrapped: this runs *before* ``cgis_ingest``'s own
+    try/except, and ``Path.resolve()``, ``Path.is_dir()`` and friends propagate
+    ``OSError`` (a ``PermissionError`` on the parent, or a symlink loop), which
+    would escape the tool as a crash instead of a message the agent can act on.
+    """
+    try:
+        path = Path(db_path).resolve()
+    except OSError as exc:
+        return f"❌ Refusing db_path '{db_path}': path is inaccessible ({exc})."
+    # Case-insensitive: `.DB` carries the same intent, and on a case-insensitive
+    # filesystem it is literally the same file.
+    if path.suffix.lower() not in _DB_SUFFIXES:
+        allowed = ", ".join(sorted(_DB_SUFFIXES))
+        return f"❌ Refusing db_path '{db_path}': name must end in one of {allowed}."
+    try:
+        if path.is_dir():
+            return f"❌ Refusing db_path '{db_path}': it is a directory."
+        if not path.parent.is_dir():
+            return (
+                f"❌ Refusing db_path '{db_path}': parent directory does not exist. "
+                "cgis will not create one."
+            )
+        if path.is_file() and path.stat().st_size > 0:
+            with path.open("rb") as fh:
+                if fh.read(len(_SQLITE_MAGIC)) != _SQLITE_MAGIC:
+                    return (
+                        f"❌ Refusing db_path '{db_path}': existing file is not a SQLite database."
+                    )
+    except OSError as exc:
+        return f"❌ Refusing db_path '{db_path}': path is inaccessible ({exc})."
+    return None
+
+
 @mcp.tool()
 def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: bool = False) -> str:
     """Scan a local directory, extract all symbols, resolve links, and build the graph DB.
 
     Use this to initialise or refresh the code knowledge graph for a project.
-    Paths are normalised relative to the workspace root so the database is
+    Node FQNs are normalised relative to the workspace root so the graph is
     portable across machines.
 
+    ``db_path`` must name a database — it has to end in ``.db``, ``.sqlite`` or
+    ``.sqlite3``, live in a directory that already exists, and not point at an
+    existing file that is not a SQLite database. cgis will not create parent
+    directories.
+
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
     whole-graph total. Set ``full_rebuild=True`` to re-scan every file and
     overwrite the database from scratch — use this to drop nodes for files that
     were deleted or renamed, which an incremental run leaves behind.
     """
+    refusal = _reject_db_path(db_path)
+    if refusal is not None:
+        logger.warning("MCP ingest refused db_path", db=db_path)
+        return refusal
+
     pipeline = IngestionPipeline(_EXTRACTORS)
     try:
         with SQLiteStore(db_path) as store:

cgis/guardian/findings.py

@@ -5,7 +5,11 @@ from typing import Literal
 from pydantic import BaseModel, Field
 
 Severity = Literal["critical", "major", "minor"]
-Category = Literal["logic", "contract", "tests", "types", "ontology"]
+# "security" exists so curated ground truth can name an exploitable defect (#315).
+# The finder prompt does not yet offer it as a choice — teaching the finder to
+# emit it is #258, and needs bench validation. Scoring is unaffected either way:
+# bench matching compares file and line range, never category.
+Category = Literal["logic", "contract", "tests", "types", "ontology", "security"]
 Verdict = Literal["confirmed", "refuted", "uncertain"]
 
 

cgis/guardian/render.py

@@ -11,6 +11,7 @@ _CATEGORY_LABEL = {
     "tests": "Test Coverage",
     "types": "Type Safety",
     "ontology": "Ontology",
+    "security": "Security",
 }
 
 

cgis/resolver/engine.py

@@ -126,7 +126,7 @@ class ResolverEngine:
 
     def _ensure_virtual_node(self, target: str, virtual_nodes: dict[str, Node]) -> None:
         """Create a virtual boundary node for target if it is not already in the graph."""
-        if target not in self._index.nodes and target not in virtual_nodes:
+        if not self._index.has_node(target) and target not in virtual_nodes:
             virtual_nodes[target] = self._make_virtual_node(
                 target, self._index.classify_fqn(target)
             )

cgis/resolver/indices.py

@@ -3,7 +3,9 @@
 import builtins
 import os
 import sys
+from collections.abc import Mapping
 from dataclasses import dataclass
+from types import MappingProxyType
 
 from cgis.core.models import SELF_PREFIX, Node, NodeNamespace, NodeType
 
@@ -15,30 +17,37 @@ class SymbolIndex:
     """Immutable lookup indices over the extracted node set.
 
     Built by IndexBuilder, consumed by SymbolResolver and ResolverEngine.
-    Frozen by convention (field rebinding prevented); the contained dicts
-    are never mutated after construction.
+
+    Immutable in substance, not only by convention: the dataclass prevents
+    field rebinding, and ``IndexBuilder`` hands over read-only views, so a
+    stray write (a cache line added to a shared index, say) raises instead of
+    silently corrupting resolution for every later lookup (#183).
+
+    The views are shallow — the inner ``list``/``dict`` values are still
+    mutable. Deep-freezing would mean copying every one of them on a hot path;
+    the realistic mistake this guards is adding or replacing a top-level key.
     """
 
     # node id (FQN) -> Node
-    nodes: dict[str, Node]
+    nodes: Mapping[str, Node]
     # name -> list of FQNs
-    global_symbols: dict[str, list[str]]
+    global_symbols: Mapping[str, list[str]]
     # (file_path, name) -> list of FQNs (list handles conditional redefinitions)
-    file_global_symbols: dict[tuple[str, str], list[str]]
+    file_global_symbols: Mapping[tuple[str, str], list[str]]
     # class_fqn -> {method_name -> method_fqn}
-    class_methods: dict[str, dict[str, str]]
+    class_methods: Mapping[str, dict[str, str]]
     # DI-alias (VARIABLE) indices for raw_dep: resolution; kept separate
     # from global_symbols so call resolution behavior does not change.
-    variable_symbols: dict[str, list[str]]
-    file_variable_symbols: dict[tuple[str, str], list[str]]
+    variable_symbols: Mapping[str, list[str]]
+    file_variable_symbols: Mapping[tuple[str, str], list[str]]
     # normalized file_path -> {local_alias: target_fqn}  (from FILE node import_map)
-    file_imports: dict[str, dict[str, str]]
+    file_imports: Mapping[str, dict[str, str]]
     # suffix_fqn -> [full_node_ids]  (handles src/ layout prefix mismatch)
-    suffix_map: dict[str, list[str]]
+    suffix_map: Mapping[str, list[str]]
     # top-level root segments of all internal nodes (for classify)
-    internal_roots: set[str]
+    internal_roots: frozenset[str]
     # root segments of absolute imports (anything else is UNKNOWN)
-    external_roots: set[str]
+    external_roots: frozenset[str]
 
     def map_to_node_fqn(self, imported_fqn: str) -> str | None:
         """Resolve an imported FQN to an actual node in the graph.
@@ -65,6 +74,14 @@ class SymbolIndex:
                 return candidate
         return None
 
+    def has_node(self, fqn: str) -> bool:
+        """True if the graph holds a node with this exact FQN.
+
+        Saves callers reaching into ``nodes`` for a membership test, which is
+        the one place the index's internals leaked (#183).
+        """
+        return fqn in self.nodes
+
     def classify_fqn(self, fqn: str) -> NodeNamespace:
         """Classify an FQN as STDLIB, INTERNAL, EXTERNAL, or UNKNOWN.
 
@@ -145,17 +162,19 @@ class IndexBuilder:
             # "src.cgis.pipeline.X" → suffix "cgis.pipeline.X" also points to the node
             self._add_node_to_suffix_map(node.id, suffix_map, internal_roots)
 
+        # Read-only views, not copies: MappingProxyType wraps in O(1), so this
+        # buys write protection without touching ingest cost (#183).
         return SymbolIndex(
-            nodes=nodes_by_id,
-            global_symbols=global_symbols,
-            file_global_symbols=file_global_symbols,
-            class_methods=class_methods,
-            variable_symbols=variable_symbols,
-            file_variable_symbols=file_variable_symbols,
-            file_imports=file_imports,
-            suffix_map=suffix_map,
-            internal_roots=internal_roots,
-            external_roots=self._build_external_roots(file_imports),
+            nodes=MappingProxyType(nodes_by_id),
+            global_symbols=MappingProxyType(global_symbols),
+            file_global_symbols=MappingProxyType(file_global_symbols),
+            class_methods=MappingProxyType(class_methods),
+            variable_symbols=MappingProxyType(variable_symbols),
+            file_variable_symbols=MappingProxyType(file_variable_symbols),
+            file_imports=MappingProxyType(file_imports),
+            suffix_map=MappingProxyType(suffix_map),
+            internal_roots=frozenset(internal_roots),
+            external_roots=frozenset(self._build_external_roots(file_imports)),
         )
 
     def _add_node_to_suffix_map(

{codegraph_brain-0.7.3.dist-info → codegraph_brain-0.7.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-brain
-Version: 0.7.3
+Version: 0.7.5
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain

{codegraph_brain-0.7.3.dist-info → codegraph_brain-0.7.5.dist-info}/RECORD

@@ -5,7 +5,7 @@ cgis/pipeline.py,sha256=AJfBhlH5ZD4wkDX6QMScuDPbl_Wwr_ZFplNzfoorsqg,10529
 cgis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/api/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/api/__init__.py,sha256=wvFZK6oZspFGmonBz2rDg1aXxK7DHuE87or_w_cwY28,91
-cgis/api/mcp_server.py,sha256=n2RgUwzqfAZ-cZXzYSvC5CI8rJu8JyfX3v_Ax3NGCYA,22693
+cgis/api/mcp_server.py,sha256=ljg1kzH9WL4VobNiXnCtOFY_K8g5NESKYcXQN7P-NaA,26206
 cgis/core/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/core/models.py,sha256=VVnldYVFBDLa3cqMCH2GZAUHt3jelIV--lgsGFK103w,3694
 cgis/extractors/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -24,12 +24,12 @@ cgis/guardian/chunker.py,sha256=zm6EF7S8lKNNfeMu1W6z7a6FiBU2qBqRz2UcelnuYac,5705
 cgis/guardian/collector.py,sha256=E4g9eW_qOYSw5rr25c_wWFt4xa9luJzAW84_DCo97HM,13505
 cgis/guardian/core.py,sha256=nY8eTcaknfxLUa6u9YwLOdyM4ztb19-A49BfW_eh7uY,4981
 cgis/guardian/diff_index.py,sha256=513WDsnvmcYecqVgoPeeK0ZBLziZIYb0ibRXYEYusv0,6212
-cgis/guardian/findings.py,sha256=igJg99ZH0J13wLZtDSiA2GBejsqYetCA3cqADohbZIc,2691
+cgis/guardian/findings.py,sha256=ZhIaQjdconvliyWe7dJs3kJL3N8JYnZRQFAepRuvQ6g,3011
 cgis/guardian/github_poster.py,sha256=Rh1FKUC7ZC6IYWzKd-d7ewHq1L21Y1uUImTsn9J96x0,5658
 cgis/guardian/metrics.py,sha256=ITF2QrHLvNLYlLYYS1qU3baGi7oYETzHXMo7pKfYc70,3641
 cgis/guardian/prompts.py,sha256=xCjlTPx3U8_IX14n31mmYti68BcJkeQTcmU0e2nnv04,11012
 cgis/guardian/recording.py,sha256=LXopddHdnv-042-P5nQrPE4JIx6jQVmGjjWzftgdr40,3375
-cgis/guardian/render.py,sha256=w-F5MHyEsIxMHLe6zP05VtSdpzfBsRD9bpLJyUwoVHg,4701
+cgis/guardian/render.py,sha256=a31wUOWlogY4sY_5EYtGMOZW2m1SPKNfkxhM2yShqkQ,4729
 cgis/guardian/runner.py,sha256=bhgtjp1-qlyc232c2LqycJEODDU68sQ2GwEYSzdCdQs,12148
 cgis/guardian/skeptic.py,sha256=ey_6pzoC297mHXGIqvZlB9fSdTvTwgLI1h2yVJ7VeYY,8848
 cgis/guardian/providers/__init__.py,sha256=wFOW1w9NtI-LBDB9w5ICNPFcuT4Hi5soxzDwpdmgxSc,49
@@ -65,14 +65,14 @@ cgis/query/render/mermaid.py,sha256=60n26BB7hBhZSTfZq62yq38aeXi3p0gOI0ON2-5N6vM,
 cgis/query/render/metrics.py,sha256=tTHIJ5mWh--JchNvGCU7n7_S0pEXBCELzvKiseEiEvo,13929
 cgis/resolver/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/resolver/__init__.py,sha256=AYEjjKXi__LvceOV9mEjXXzQS6O03D4RQjuBjpJtGhA,75
-cgis/resolver/engine.py,sha256=zNErmZRpOdAHMux3YWCWz0YbXhorm8BcD7DSKGYJLgQ,6424
-cgis/resolver/indices.py,sha256=hof9PyDrOdbFCyE1urDOH3j5uKFHPutvpgetsLvxq8s,7994
+cgis/resolver/engine.py,sha256=3NKkvZNxD25vKOBB6NEKA8DobEanv1iMiuWEyrfWbLA,6425
+cgis/resolver/indices.py,sha256=eeVaI-QpqU73gR-UrhlpqARx7j_bQU1LoI-Y7YUy4Zo,9116
 cgis/resolver/symbols.py,sha256=6PNDIgoJ2Mj2xZ4XHpEXwjHe76fi9zvOwF7tAON1GBw,8513
 cgis/resolver/uplift.py,sha256=Hkye1q-kI-gKO6GIBYv3gUZj1AC0-_mkpoIpmwVsG4g,9591
 cgis/storage/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/storage/sqlite_store.py,sha256=Dkxkl0WDyTakZFfxWuVpYLNHA_H7CMvRkSUvev3MHew,24778
-codegraph_brain-0.7.3.dist-info/METADATA,sha256=Qk6-V9Em57bTdZByMD18KzvWSZ25ecQZvA8NGG1kwS4,13617
-codegraph_brain-0.7.3.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-codegraph_brain-0.7.3.dist-info/entry_points.txt,sha256=G_ekY569jca0ubm-I3gA9Id9xRj8fc42CDgLgTC-5L4,77
-codegraph_brain-0.7.3.dist-info/licenses/LICENSE,sha256=1X36nOG5VocDaEGzAZqIv7uawy_7sWlFoiwECwx5aBI,1065
-codegraph_brain-0.7.3.dist-info/RECORD,,
+codegraph_brain-0.7.5.dist-info/METADATA,sha256=SP_i4TO1ux803f9AWWre4bgsj015tiYmCI6YXDIsksA,13617
+codegraph_brain-0.7.5.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+codegraph_brain-0.7.5.dist-info/entry_points.txt,sha256=G_ekY569jca0ubm-I3gA9Id9xRj8fc42CDgLgTC-5L4,77
+codegraph_brain-0.7.5.dist-info/licenses/LICENSE,sha256=1X36nOG5VocDaEGzAZqIv7uawy_7sWlFoiwECwx5aBI,1065
+codegraph_brain-0.7.5.dist-info/RECORD,,