rce-path 0.1.0__py3-none-any.whl

rce_path/__init__.py

@@ -0,0 +1,8 @@
+"""Public, static-first API. Importing this package does not load AI SDKs."""
+
+from .config import ScanConfig
+from .findings import Finding, ScanReport
+from .ingest import scan
+
+__version__ = "0.1.0"
+__all__ = ["Finding", "ScanConfig", "ScanReport", "scan"]

rce_path/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rce_path/_worker.py

@@ -0,0 +1,149 @@
+"""Trusted isolated worker entry point. Never import anything from the target tree."""
+
+from __future__ import annotations
+
+import ast
+import ctypes
+import json
+import os
+import sys
+from pathlib import Path
+
+# -I removes cwd/PYTHONPATH; only the installed package's source root is reintroduced.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+_job_handle = None
+
+
+def memory_limit(megabytes: int) -> None:
+    global _job_handle
+    amount = megabytes * 1024 * 1024
+    if os.name != "nt":
+        import resource
+
+        getattr(resource, "setrlimit")(getattr(resource, "RLIMIT_AS"), (amount, amount))
+        return
+    from ctypes import wintypes
+
+    class Basic(ctypes.Structure):
+        _fields_ = [
+            ("PerProcessUserTimeLimit", ctypes.c_int64),
+            ("PerJobUserTimeLimit", ctypes.c_int64),
+            ("LimitFlags", wintypes.DWORD),
+            ("MinimumWorkingSetSize", ctypes.c_size_t),
+            ("MaximumWorkingSetSize", ctypes.c_size_t),
+            ("ActiveProcessLimit", wintypes.DWORD),
+            ("Affinity", ctypes.c_size_t),
+            ("PriorityClass", wintypes.DWORD),
+            ("SchedulingClass", wintypes.DWORD),
+        ]
+
+    class IO(ctypes.Structure):
+        _fields_ = [
+            (name, ctypes.c_uint64)
+            for name in (
+                "ReadOperationCount",
+                "WriteOperationCount",
+                "OtherOperationCount",
+                "ReadTransferCount",
+                "WriteTransferCount",
+                "OtherTransferCount",
+            )
+        ]
+
+    class Extended(ctypes.Structure):
+        _fields_ = [
+            ("BasicLimitInformation", Basic),
+            ("IoInfo", IO),
+            ("ProcessMemoryLimit", ctypes.c_size_t),
+            ("JobMemoryLimit", ctypes.c_size_t),
+            ("PeakProcessMemoryUsed", ctypes.c_size_t),
+            ("PeakJobMemoryUsed", ctypes.c_size_t),
+        ]
+
+    kernel = getattr(ctypes, "WinDLL")("kernel32", use_last_error=True)
+    kernel.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]
+    kernel.CreateJobObjectW.restype = wintypes.HANDLE
+    kernel.GetCurrentProcess.restype = wintypes.HANDLE
+    kernel.SetInformationJobObject.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+    ]
+    kernel.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
+    handle = kernel.CreateJobObjectW(None, None)
+    limits = Extended()
+    limits.BasicLimitInformation.LimitFlags = 0x100  # JOB_OBJECT_LIMIT_PROCESS_MEMORY
+    limits.ProcessMemoryLimit = amount
+    if not handle or not kernel.SetInformationJobObject(
+        handle, 9, ctypes.byref(limits), ctypes.sizeof(limits)
+    ):
+        raise OSError("Could not enforce parser-worker memory limit")
+    if not kernel.AssignProcessToJobObject(handle, kernel.GetCurrentProcess()):
+        raise OSError("Could not assign parser-worker memory limit")
+    _job_handle = handle  # retain until process exit
+
+
+def main() -> None:
+    from rce_path.config import ScanConfig
+    from rce_path.flow import Analyzer
+
+    request = json.loads(sys.stdin.buffer.read(25_000_000))
+    config = ScanConfig.model_validate_json(json.dumps(request["config"]))
+    memory_limit(config.parser_memory_mb)
+    source = request["source"]
+    file = request["file"]
+    try:
+        tree = ast.parse(source, filename=file)
+        count = 0
+        for _ in ast.walk(tree):
+            count += 1
+            if count > config.max_ast_nodes:
+                raise ValueError("AST node budget exhausted")
+        findings, diagnostics = Analyzer(source, file, config).analyze(tree)
+        payload = {
+            "findings": [f.model_dump() for f in findings],
+            "diagnostics": [d.model_dump() for d in diagnostics],
+        }
+    except (SyntaxError, UnicodeError, ValueError, RecursionError, MemoryError) as error:
+        payload = {
+            "findings": [],
+            "diagnostics": [
+                {
+                    "code": "parse_error",
+                    "file": file,
+                    "line": getattr(error, "lineno", None),
+                    "affects_completion": True,
+                    "message": f"{type(error).__name__}: {str(error)[:200]}",
+                }
+            ],
+        }
+    # Bound serialized evidence before it enters the parent's capture buffer.
+    chunks = []
+    size = 0
+    for chunk in json.JSONEncoder().iterencode(payload):
+        size += len(chunk.encode())
+        if size > 16_000_000:
+            chunks = [
+                json.dumps(
+                    {
+                        "findings": [],
+                        "diagnostics": [
+                            {
+                                "code": "evidence_response_limit",
+                                "file": file,
+                                "message": "Worker evidence response exceeded size budget.",
+                                "affects_completion": True,
+                            }
+                        ],
+                    }
+                )
+            ]
+            break
+        chunks.append(chunk)
+    sys.stdout.write("".join(chunks))
+
+
+if __name__ == "__main__":
+    main()

rce_path/cfg.py

@@ -0,0 +1,76 @@
+"""Structured per-scope control-flow graphs; no target code is evaluated."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Edge:
+    target: int
+    condition: ast.expr | None = None
+    truth: bool = True
+
+
+@dataclass
+class Block:
+    id: int
+    statement: ast.AST | None
+    edges: list[Edge] = field(default_factory=list)
+
+
+@dataclass
+class Graph:
+    blocks: dict[int, Block]
+    entry: int
+
+
+class Builder:
+    def __init__(self) -> None:
+        self.blocks: dict[int, Block] = {}
+
+    def node(self, stmt: ast.AST | None) -> int:
+        index = len(self.blocks)
+        self.blocks[index] = Block(index, stmt)
+        return index
+
+    def sequence(
+        self, statements: list[ast.stmt], after: int, loop: tuple[int, int] | None = None
+    ) -> int:
+        current = after
+        for stmt in reversed(statements):
+            index = self.node(stmt)
+            if isinstance(stmt, ast.If):
+                yes = self.sequence(stmt.body, current, loop)
+                no = self.sequence(stmt.orelse, current, loop)
+                self.blocks[index].edges = [Edge(yes, stmt.test), Edge(no, stmt.test, False)]
+            elif isinstance(stmt, (ast.While, ast.For, ast.AsyncFor)):
+                otherwise = self.sequence(stmt.orelse, current, loop)
+                body = self.sequence(stmt.body, index, (current, index))
+                test = stmt.test if isinstance(stmt, ast.While) else None
+                self.blocks[index].edges = [Edge(body, test), Edge(otherwise, test, False)]
+            elif isinstance(stmt, ast.Break):
+                self.blocks[index].edges = [Edge(loop[0])] if loop else []
+            elif isinstance(stmt, ast.Continue):
+                self.blocks[index].edges = [Edge(loop[1])] if loop else []
+            elif isinstance(stmt, (ast.Return, ast.Raise)):
+                self.blocks[index].edges = []
+            elif isinstance(stmt, (ast.With, ast.AsyncWith)):
+                self.blocks[index].edges = [Edge(self.sequence(stmt.body, current, loop))]
+            elif isinstance(stmt, (ast.Try, ast.TryStar)):
+                # Exception edges conservatively join; completion diagnostics disclose this model.
+                final = self.sequence(stmt.finalbody, current, loop)
+                normal = self.sequence(stmt.orelse, final, loop)
+                entries = [self.sequence(stmt.body, normal, loop)]
+                entries.extend(self.sequence(h.body, final, loop) for h in stmt.handlers)
+                self.blocks[index].edges = [Edge(item) for item in entries]
+            else:
+                self.blocks[index].edges = [Edge(current)]
+            current = index
+        return current
+
+    def build(self, statements: list[ast.stmt]) -> Graph:
+        exit_node = self.node(None)
+        entry = self.sequence(statements, exit_node)
+        return Graph(self.blocks, entry)

rce_path/cli.py

@@ -0,0 +1,78 @@
+"""CLI policies are explicit; incomplete scans always take precedence."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .config import ScanConfig, load_config
+from .ingest import scan
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="rce-path",
+        description="Investigate modeled Python execution paths without executing the target.",
+    )
+    parser.add_argument("--version", action="version", version="rce-path 0.1.0")
+    commands = parser.add_subparsers(dest="command", required=True)
+    command = commands.add_parser("scan")
+    command.add_argument("path")
+    command.add_argument("--format", choices=["json", "markdown"], default="json")
+    command.add_argument("--output", type=Path)
+    command.add_argument("--config", type=Path)
+    command.add_argument("--fail-on", choices=["none", "static-path", "any"], default="none")
+    command.add_argument("--ai", choices=["openai", "ollama"])
+    command.add_argument("--model")
+    command.add_argument("--endpoint")
+    command.add_argument("--allow-remote-code", action="store_true")
+    command.add_argument("--accept-config-ai-endpoint", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        target = Path(args.path)
+        root = target if target.is_dir() else target.parent
+        config_path = args.config or root / "rce-path.toml"
+        if args.config or config_path.exists():
+            if config_path.is_symlink() or (
+                getattr(config_path.lstat(), "st_file_attributes", 0) & 0x400
+            ):
+                raise ValueError("configuration symlinks/reparse points are not accepted")
+            config = load_config(config_path, accept_ai_endpoint=args.accept_config_ai_endpoint)
+        else:
+            config = ScanConfig()
+        updates = {"ai_enabled": bool(args.ai), "allow_remote_code": args.allow_remote_code}
+        for name, value in (
+            ("ai_provider", args.ai),
+            ("ai_model", args.model),
+            ("ai_endpoint", args.endpoint),
+        ):
+            if value is not None:
+                updates[name] = value
+        config = ScanConfig(**(config.model_dump() | updates))
+        if config.ai_enabled and config.ai_provider == "openai" and not config.allow_remote_code:
+            raise ValueError("OpenAI code transmission requires --allow-remote-code")
+        report = scan(args.path, config)
+        output = report.to_json() if args.format == "json" else report.to_markdown()
+        if args.output:
+            args.output.write_text(output + "\n", encoding="utf-8")
+        else:
+            print(output)
+        if report.status != "completed" or report.ai_status not in {
+            "disabled",
+            "completed",
+            "no_findings",
+        }:
+            return 2
+        failed = args.fail_on == "any" and bool(report.findings)
+        failed |= args.fail_on == "static-path" and any(
+            f.evidence_tier == "static_path" for f in report.findings
+        )
+        return 1 if failed else 0
+    except (OSError, ValueError) as error:
+        print(f"rce-path: {str(error)[:500]}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rce_path/config.py

@@ -0,0 +1,100 @@
+"""Strict operator configuration. Repository settings cannot enable AI or grant consent."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+DEFAULT_EXCLUDES = (
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "env",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    ".tox",
+    ".nox",
+    "site-packages",
+    ".eggs",
+)
+RULE_IDS = ("python.eval", "python.exec", "os.system", "os.popen", "subprocess.shell")
+
+
+class ScanConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+    excludes: tuple[str, ...] = DEFAULT_EXCLUDES
+    rules: tuple[str, ...] = RULE_IDS
+    max_file_bytes: int = Field(default=1_000_000, ge=1, le=20_000_000)
+    max_files: int = Field(default=10_000, ge=1, le=1_000_000)
+    max_inventory_entries: int = Field(default=100_000, ge=1, le=1_000_000)
+    parser_timeout_seconds: float = Field(default=10.0, gt=0, le=300)
+    parser_memory_mb: int = Field(default=256, ge=64, le=4096)
+    scan_timeout_seconds: float = Field(default=120.0, gt=0, le=86400)
+    max_ast_nodes: int = Field(default=30_000, ge=1, le=1_000_000)
+    max_flow_steps: int = Field(default=20_000, ge=1, le=1_000_000)
+    loop_iterations: int = Field(default=8, ge=1, le=100)
+    max_evidence_steps: int = Field(default=64, ge=2, le=512)
+    ai_enabled: bool = False
+    ai_provider: Literal["openai", "ollama"] = "ollama"
+    ai_model: str | None = None
+    allow_remote_code: bool = False
+    ai_endpoint: str | None = None
+    ai_timeout_seconds: float = Field(default=30.0, gt=0, le=300)
+    ai_max_reviews: int = Field(default=20, ge=1, le=1000)
+    ai_max_input_bytes: int = Field(default=16_000, ge=512, le=200_000)
+    ai_max_output_tokens: int = Field(default=1024, ge=64, le=8192)
+    ai_total_token_budget: int = Field(default=50_000, ge=64, le=10_000_000)
+
+    @model_validator(mode="after")
+    def valid_selection(self) -> ScanConfig:
+        if not self.rules or set(self.rules) - set(RULE_IDS):
+            raise ValueError("rules must be a nonempty selection of built-in Phase 1 rules")
+        if self.ai_enabled and not self.ai_model:
+            raise ValueError("an explicit ai_model is required when AI is enabled")
+        if any(not item or "\\" in item for item in self.excludes):
+            raise ValueError("excludes must be nonempty names or forward-slash glob patterns")
+        return self
+
+
+def load_config(path: Path, *, accept_ai_endpoint: bool = False) -> ScanConfig:
+    from .ingest import _read
+
+    path = path.absolute()
+    raw = tomllib.loads(_read(path, path.parent.resolve(), 64_000).decode("utf-8"))
+    if any(not isinstance(raw.get(section, {}), dict) for section in ("scan", "ai")):
+        raise ValueError("scan and ai must be TOML tables")
+    if set(raw) - {"scan", "ai"}:
+        raise ValueError("unknown configuration section")
+    settings = dict(raw.get("scan", {}))
+    for key in ("excludes", "rules"):
+        if key in settings and isinstance(settings[key], list):
+            settings[key] = tuple(settings[key])
+    ai = dict(raw.get("ai", {}))
+    allowed_ai = {
+        "provider",
+        "model",
+        "endpoint",
+        "timeout_seconds",
+        "max_reviews",
+        "max_input_bytes",
+        "max_output_tokens",
+        "total_token_budget",
+    }
+    if set(ai) - allowed_ai:
+        raise ValueError("unknown AI setting; runtime opt-in/consent belongs on the command line")
+    if set(settings) - (
+        set(ScanConfig.model_fields) - {"ai_enabled", "allow_remote_code", "ai_endpoint"}
+    ):
+        raise ValueError("unknown or privileged scan setting")
+    for key, value in ai.items():
+        if key == "endpoint" and not accept_ai_endpoint:
+            continue
+        settings[f"ai_{key}"] = value
+    return ScanConfig(**settings)

rce_path/findings.py

@@ -0,0 +1,108 @@
+"""Versioned evidence contracts, independent of analysis and provider implementations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+SCHEMA_VERSION = "1.0"
+RULE_VERSION = "0.1.0"
+SourceCategory = Literal["caller_parameter", "network_request", "local_input", "unknown"]
+
+
+class Record(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Location(Record):
+    file: str
+    line: int = Field(ge=1)
+    column: int = Field(ge=0)
+    end_line: int = Field(ge=1)
+    end_column: int = Field(ge=0)
+
+
+class EvidenceStep(Record):
+    id: str
+    kind: str
+    location: Location
+    description: str
+    snippet: str = ""
+
+
+class Diagnostic(Record):
+    code: str
+    message: str
+    file: str | None = None
+    line: int | None = None
+    affects_completion: bool = False
+
+
+class Finding(Record):
+    schema_version: str = SCHEMA_VERSION
+    rule_version: str = RULE_VERSION
+    fingerprint: str
+    rule_id: str
+    sink: str
+    argument: str
+    location: Location
+    source_category: SourceCategory
+    source: Location | None = None
+    evidence_tier: Literal["sink_only", "static_path", "canary_validated"]
+    remote_reachability: Literal["network_source_modeled", "caller_controlled_only", "unknown"]
+    impact: str
+    steps: tuple[EvidenceStep, ...]
+    conditions: tuple[str, ...] = ()
+    assumptions: tuple[str, ...] = ()
+    unresolved_edges: tuple[EvidenceStep, ...] = ()
+    dependencies: dict[str, str] = Field(default_factory=dict)
+    human_review: Literal["unreviewed", "confirmed", "dismissed", "needs_information"] = (
+        "unreviewed"
+    )
+    human_rationale: str | None = None
+    review_notes: tuple[str, ...] = ()
+
+
+class ScanReport(Record):
+    schema_version: str = SCHEMA_VERSION
+    tool_version: str = "0.1.0"
+    rule_version: str = RULE_VERSION
+    root: str
+    status: Literal["completed", "incomplete", "error"]
+    findings: tuple[Finding, ...] = ()
+    diagnostics: tuple[Diagnostic, ...] = ()
+    analyzed_files: int = 0
+    skipped_files: int = 0
+    content_hashes: dict[str, str] = Field(default_factory=dict)
+    revision: str | None = None
+    limits: dict[str, int | float] = Field(default_factory=dict)
+    enabled_rules: tuple[str, ...] = ()
+    exclusions: tuple[str, ...] = ()
+    target_syntax: str
+    ai_status: str = "disabled"
+    ai_reviews: dict[str, dict] = Field(default_factory=dict)
+
+    @property
+    def summary(self) -> str:
+        if self.status != "completed":
+            return "Incomplete scan; coverage diagnostics require review."
+        return (
+            f"{len(self.findings)} modeled findings." if self.findings else "No modeled findings."
+        )
+
+    def to_json(self) -> str:
+        return self.model_dump_json(indent=2)
+
+    def to_markdown(self) -> str:
+        from .reports import markdown
+
+        return markdown(self)
+
+
+def fingerprint(rule: str, location: Location, source: Location | None) -> str:
+    """Stable across roots, timestamps, rendering, and AI annotations."""
+    payload = [RULE_VERSION, rule, location.model_dump(), source.model_dump() if source else None]
+    return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()