coretrace-python-analyzer 0.1.0__py3-none-any.whl

coretrace_python/semantic/symbols.py

@@ -0,0 +1,87 @@
+"""Symbol analysis: resolve names to canonical identities (architecture §4.3)."""
+
+from __future__ import annotations
+
+import builtins
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import ClassVar
+
+from coretrace_python.analysis import Analysis, AnalysisContext, AnyAnalysis
+from coretrace_python.hir import nodes
+from coretrace_python.semantic.identity import SymbolId
+from coretrace_python.semantic.imports import ImportAnalysis, ImportTable
+from coretrace_python.semantic.scopes import ResolutionKind, ScopeAnalysis, ScopeId, ScopeTable
+
+BUILTIN_NAMES = frozenset(name for name in dir(builtins) if not name.startswith("_"))
+
+
+class SymbolTable:
+    """Resolve names to canonical symbols through scopes, imports, builtins and the
+    module-level instances created by calling a symbol (``app = Flask(__name__)``)."""
+
+    def __init__(
+        self,
+        scopes: ScopeTable,
+        imports: ImportTable,
+        instances: Mapping[str, SymbolId] | None = None,
+    ) -> None:
+        self._scopes = scopes
+        self._imports = imports
+        self._instances = MappingProxyType(dict(instances or {}))
+
+    def resolve(self, scope_id: ScopeId, name: str) -> SymbolId | None:
+        resolution = self._scopes.resolve(scope_id, name)
+        if resolution.kind is ResolutionKind.UNBOUND:
+            return SymbolId(f"python.builtins.{name}") if name in BUILTIN_NAMES else None
+        assert resolution.scope is not None
+        imported = self._imports.bindings(resolution.scope).get(name)
+        if imported is not None:
+            return imported
+        if resolution.scope == self._scopes.module_scope.id:
+            return self._instances.get(name)
+        return None
+
+    def resolve_expression(self, scope_id: ScopeId, node: nodes.Expression) -> SymbolId | None:
+        """The symbol of a name or attribute chain, or of the callee of a call."""
+
+        if isinstance(node, nodes.Name):
+            return self.resolve(scope_id, node.identifier)
+        if isinstance(node, nodes.Attribute):
+            parent = self.resolve_expression(scope_id, node.value)
+            return parent.attribute(node.name) if parent is not None else None
+        if isinstance(node, nodes.Call):
+            return self.resolve_expression(scope_id, node.callee)
+        return None
+
+
+def analyze_symbols(
+    scopes: ScopeTable, imports: ImportTable, module: nodes.Module | None = None
+) -> SymbolTable:
+    table = SymbolTable(scopes, imports)
+    if module is None:
+        return table
+    instances: dict[str, SymbolId] = {}
+    module_scope = scopes.module_scope.id
+    for statement in module.body:
+        if (
+            isinstance(statement, nodes.Assign)
+            and isinstance(statement.target, nodes.Name)
+            and isinstance(statement.value, nodes.Call)
+        ):
+            symbol = table.resolve_expression(module_scope, statement.value.callee)
+            if symbol is not None:
+                instances[statement.target.identifier] = symbol
+    return SymbolTable(scopes, imports, instances)
+
+
+class SymbolAnalysis(Analysis[SymbolTable]):
+    name: ClassVar[str] = "semantic.symbols"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({ScopeAnalysis, ImportAnalysis})
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext) -> SymbolTable:
+        return analyze_symbols(ctx.get(ScopeAnalysis), ctx.get(ImportAnalysis), ctx.module)
+
+
+__all__ = ["BUILTIN_NAMES", "SymbolAnalysis", "SymbolId", "SymbolTable", "analyze_symbols"]

coretrace_python/source/__init__.py

@@ -0,0 +1,13 @@
+"""Source storage and location primitives."""
+
+from coretrace_python.source.manager import SourceManager, decode_text
+from coretrace_python.source.model import SourceFile, SourceId, SourceSpan
+
+__all__ = [
+    "SourceFile",
+    "SourceId",
+    "SourceManager",
+    "SourceSpan",
+    "decode_text",
+]
+

coretrace_python/source/manager.py

@@ -0,0 +1,81 @@
+"""Ownership and loading of source files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from coretrace_python.source.model import SourceFile, SourceId
+
+
+def module_name_for(path: Path) -> str:
+    """Dotted module name of ``path``, walking up through ``__init__.py`` packages.
+
+    A package's ``__init__.py`` is named after the package itself."""
+
+    parts = [] if path.name == "__init__.py" else [path.stem]
+    directory = path.parent
+    while (directory / "__init__.py").is_file():
+        parts.append(directory.name)
+        directory = directory.parent
+    return ".".join(reversed(parts)) or path.stem
+
+
+def decode_text(data: bytes) -> str:
+    """Decode a text file, honouring a UTF-8 or UTF-16 byte order mark; Windows tools
+    such as ``pip freeze`` write UTF-16 with one."""
+
+    for mark, encoding in ((b"\xef\xbb\xbf", "utf-8-sig"), (b"\xff\xfe", "utf-16"), (b"\xfe\xff", "utf-16")):
+        if data.startswith(mark):
+            return data.decode(encoding)
+    return data.decode("utf-8")
+
+
+class SourceManager:
+    """Own source text and return one canonical object for each source ID."""
+
+    def __init__(self) -> None:
+        self._sources: dict[SourceId, SourceFile] = {}
+
+    def add_source(self, name: str, text: str, module_name: str | None = None) -> SourceFile:
+        source_id = SourceId(name)
+        existing = self._sources.get(source_id)
+        if existing is not None:
+            if existing.text != text:
+                raise ValueError(f"source {name!r} already exists with different text")
+            return existing
+
+        source = SourceFile(
+            source_id=source_id,
+            text=text,
+            module_name=module_name if module_name is not None else Path(name).stem,
+        )
+        self._sources[source_id] = source
+        return source
+
+    def load_file(self, path: str | Path) -> SourceFile:
+        resolved_path = Path(path).resolve()
+        source_id = SourceId(str(resolved_path))
+        existing = self._sources.get(source_id)
+        if existing is not None:
+            return existing
+
+        text = decode_text(resolved_path.read_bytes())
+        source = SourceFile(
+            source_id=source_id,
+            text=text,
+            module_name=module_name_for(resolved_path),
+            path=resolved_path,
+            is_package=resolved_path.name == "__init__.py",
+        )
+        self._sources[source_id] = source
+        return source
+
+    def get(self, source_id: SourceId) -> SourceFile:
+        try:
+            return self._sources[source_id]
+        except KeyError as error:
+            raise KeyError(f"unknown source ID: {source_id}") from error
+
+    def __len__(self) -> int:
+        return len(self._sources)
+

coretrace_python/source/model.py

@@ -0,0 +1,57 @@
+"""Immutable source files and locations shared by engine layers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, order=True)
+class SourceId:
+    """Stable identity for a source unit within an analysis invocation."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not self.value:
+            raise ValueError("source ID cannot be empty")
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    """One-based, half-open source range."""
+
+    source_id: SourceId
+    start_line: int
+    start_column: int
+    end_line: int | None = None
+    end_column: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.start_line < 1 or self.start_column < 1:
+            raise ValueError("source span start must be one-based")
+        if (self.end_line is None) != (self.end_column is None):
+            raise ValueError("source span end line and column must be provided together")
+        if self.end_line is not None and self.end_column is not None:
+            if self.end_line < self.start_line:
+                raise ValueError("source span cannot end before it starts")
+            if self.end_line == self.start_line and self.end_column < self.start_column:
+                raise ValueError("source span cannot end before it starts")
+
+    def display(self) -> str:
+        return f"{self.source_id}:{self.start_line}:{self.start_column}"
+
+
+@dataclass(frozen=True)
+class SourceFile:
+    """Decoded source text, its identity and its dotted module name."""
+
+    source_id: SourceId
+    text: str
+    module_name: str
+    path: Path | None = None
+    is_package: bool = False
+

coretrace_python/taint/__init__.py

@@ -0,0 +1,55 @@
+"""Security models and the global multi-kind taint engine (architecture §16, §17)."""
+
+from coretrace_python.taint.engine import (
+    Taint,
+    TaintAnalysis,
+    TaintFacts,
+    TaintFlow,
+    propagate_taint,
+)
+from coretrace_python.taint.models import (
+    AuthorizationGuard,
+    EntryPoint,
+    Model,
+    ModelError,
+    ModelTable,
+    NamedParameter,
+    RouteRegistrar,
+    Sanitizer,
+    SecurityModelAnalysis,
+    SecurityModelRegistry,
+    Sink,
+    Source,
+    SuffixSink,
+    TaintKind,
+    TypedParameter,
+    Validator,
+)
+from coretrace_python.taint.routes import RegisteredRoutes, Routes, registered_routes
+
+__all__ = [
+    "AuthorizationGuard",
+    "EntryPoint",
+    "Model",
+    "ModelError",
+    "ModelTable",
+    "NamedParameter",
+    "RegisteredRoutes",
+    "RouteRegistrar",
+    "Routes",
+    "Sanitizer",
+    "SecurityModelAnalysis",
+    "SecurityModelRegistry",
+    "Sink",
+    "Source",
+    "SuffixSink",
+    "Taint",
+    "TaintAnalysis",
+    "TaintFacts",
+    "TaintFlow",
+    "TaintKind",
+    "TypedParameter",
+    "Validator",
+    "propagate_taint",
+    "registered_routes",
+]