rung-cli 0.1.2__py3-none-any.whl

rung/checks/deps.py

@@ -0,0 +1,230 @@
+"""Deps checker: every newly added dependency must exist and must not be brand new.
+
+Coding agents sometimes add packages that do not exist; attackers register those
+names (slopsquatting) or publish look-alikes shortly before they are used. This
+check reads the dependency manifests, finds packages that are new relative to
+the merge base (or to a recorded baseline), and asks the public registry about
+each one. A package that is missing, or younger than `min_age_days`, blocks
+until a person adds it to `allow`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tomllib
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from rung.checks.base import Checker, Context, Outcome
+from rung.core import git
+from rung.core.config import Check
+from rung.core.errors import RungError
+
+MANIFESTS = ["**/requirements*.txt", "**/requirements/*.txt", "**/pyproject.toml", "**/package.json"]
+_REQ_NAME = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)")
+
+
+@dataclass(frozen=True)
+class Package:
+    ecosystem: str  # pypi | npm
+    name: str
+
+
+def _normalize_pypi(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def requirement_name(spec: str) -> str:
+    """The normalized package name in a requirement such as `playwright>=1.40`, or empty."""
+    m = _REQ_NAME.match(spec)
+    return _normalize_pypi(m.group(1)) if m else ""
+
+
+def _pep508_names(specs: list[str]) -> set[str]:
+    names = set()
+    for spec in specs:
+        if m := _REQ_NAME.match(spec):
+            names.add(_normalize_pypi(m.group(1)))
+    return names
+
+
+def parse_manifest(
+    path: str, text: str, read: Callable[[str], str | None] | None = None, seen: frozenset[str] = frozenset()
+) -> set[Package]:
+    """Direct dependencies declared in one manifest file.
+
+    `read(relative_path)` returns another file's text (or None), used to follow `-r` includes
+    in requirements files at the same revision. Includes outside the repository, and cycles, are
+    not followed. A manifest that cannot be parsed raises RungError.
+    """
+    try:
+        return _parse_manifest(path, text, read, seen | {path})
+    except (json.JSONDecodeError, tomllib.TOMLDecodeError, AttributeError, TypeError) as exc:
+        raise RungError(f"{path}: cannot read its dependencies ({exc})") from exc
+
+
+def _parse_manifest(
+    path: str, text: str, read: Callable[[str], str | None] | None, seen: frozenset[str]
+) -> set[Package]:
+    name = Path(path).name
+    if name.endswith(".txt"):
+        names: set[str] = set()
+        specs = []
+        for raw in text.splitlines():
+            line = raw.split("#", 1)[0].strip()
+            if line.startswith(("-r ", "--requirement ", "-c ", "--constraint ")) and read:
+                included = os.path.normpath(Path(path).parent / line.split(None, 1)[1].strip())
+                if included.startswith(("..", "/")) or included in seen:
+                    continue
+                if (inner := read(included)) is not None:
+                    names |= {p.name for p in parse_manifest(included, inner, read, seen)}
+            elif line and not line.startswith(("-", "git+", "http:", "https:", ".", "/")):
+                specs.append(line)
+        return {Package("pypi", n) for n in names | _pep508_names(specs)}
+    if name == "pyproject.toml":
+        data = tomllib.loads(text)
+        project = data.get("project", {})
+        specs = list(project.get("dependencies", []))
+        for group in project.get("optional-dependencies", {}).values():
+            specs += group
+        for group in data.get("dependency-groups", {}).values():
+            specs += [s for s in group if isinstance(s, str)]
+        poetry = data.get("tool", {}).get("poetry", {})
+        poetry_tables = [poetry.get("dependencies", {}), poetry.get("dev-dependencies", {})]
+        poetry_tables += [g.get("dependencies", {}) for g in poetry.get("group", {}).values()]
+        for table in poetry_tables:
+            specs += [k for k, v in table.items() if k.lower() != "python" and not _poetry_local(v)]
+        own = _normalize_pypi(project.get("name", "")) if project.get("name") else None
+        return {Package("pypi", n) for n in _pep508_names(specs) if n != own}
+    if name == "package.json":
+        data = json.loads(text)
+        packages: set[str] = set()
+        for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
+            for dep, version in (data.get(key) or {}).items():
+                version = str(version)
+                if version.startswith("npm:"):  # an alias: vet the package actually installed
+                    target = version[4:]
+                    packages.add(target.rsplit("@", 1)[0] if target.count("@") > (1 if target.startswith("@") else 0)
+                                 else target)  # fmt: skip
+                elif not version.startswith(("file:", "link:", "workspace:", "git", "http", "github:")):
+                    packages.add(dep)
+        return {Package("npm", n) for n in packages}
+    return set()
+
+
+def _poetry_local(spec: object) -> bool:
+    return isinstance(spec, dict) and any(k in spec for k in ("path", "git", "url"))
+
+
+def fetch_json(url: str, timeout: int = 20) -> dict | None:
+    """GET a registry document; None means the package does not exist."""
+    request = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": "rung"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return None
+        raise RungError(f"{url} returned HTTP {exc.code}") from exc
+    except urllib.error.URLError as exc:
+        raise RungError(f"cannot reach {url}: {exc.reason}") from exc
+    except (TimeoutError, OSError) as exc:
+        raise RungError(f"{url} did not answer: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise RungError(f"{url} returned malformed JSON") from exc
+
+
+def first_published(pkg: Package) -> datetime | None:
+    """When the package first appeared on its registry; None if it does not exist."""
+    if pkg.ecosystem == "pypi":
+        doc = fetch_json(f"https://pypi.org/pypi/{urllib.parse.quote(pkg.name)}/json")
+        if doc is None:
+            return None
+        times = [
+            f["upload_time_iso_8601"]
+            for files in (doc.get("releases") or {}).values()
+            for f in files
+            if f.get("upload_time_iso_8601")
+        ]
+        return min((datetime.fromisoformat(t.replace("Z", "+00:00")) for t in times), default=datetime.now(UTC))
+    doc = fetch_json(f"https://registry.npmjs.org/{urllib.parse.quote(pkg.name, safe='@')}")
+    if doc is None:
+        return None
+    created = (doc.get("time") or {}).get("created")
+    return datetime.fromisoformat(created.replace("Z", "+00:00")) if created else datetime.now(UTC)
+
+
+def _is_manifest(path: str) -> bool:
+    return any(git.glob_match(p, path) for p in MANIFESTS) and "node_modules/" not in path
+
+
+def declared(root: Path) -> set[Package]:
+    def read(rel: str) -> str | None:
+        target = root / rel
+        return target.read_text(errors="ignore") if target.is_file() else None
+
+    out: set[Package] = set()
+    for rel in (f for f in git.list_files(root) if _is_manifest(f)):
+        out |= parse_manifest(rel, read(rel) or "", read)
+    return out
+
+
+def declared_at(root: Path, commit: str) -> set[Package]:
+    """Dependencies declared at `commit`, reading that revision's own manifests (renames included)."""
+
+    def read(rel: str) -> str | None:
+        try:
+            return git.show(root, commit, rel)
+        except git.GitError:
+            return None
+
+    out: set[Package] = set()
+    for rel in (f for f in git.files_at(root, commit) if _is_manifest(f)):
+        out |= parse_manifest(rel, read(rel) or "", read)
+    return out
+
+
+class DepsChecker(Checker):
+    kind = "deps"
+    summary = "New dependencies must exist on their registry and not be brand new"
+
+    def max_age_days(self, check: Check) -> int | None:
+        # A package can be published, yanked or taken over without any file here changing.
+        return check.get_int("max_age_days", 1) or None
+
+    def default_covers(self, check: Check) -> list[str]:
+        return list(MANIFESTS)
+
+    def run(self, ctx: Context, check: Check) -> Outcome:
+        min_age = check.get_int("min_age_days", 30)
+        allow = {_normalize_pypi(a) for a in check.get_list("allow")}
+        head = declared(ctx.root)
+        base = declared_at(ctx.root, ctx.base) if ctx.base else set()
+        added = sorted(
+            (p for p in head - base if _normalize_pypi(p.name) not in allow), key=lambda p: (p.ecosystem, p.name)
+        )
+        if not added:
+            return Outcome("pass", f"no new dependencies to vet ({len(head)} declared)")
+
+        with ThreadPoolExecutor(max_workers=8) as pool:
+            published = dict(zip(added, pool.map(first_published, added), strict=True))
+        now = datetime.now(UTC)
+        missing = [p for p, t in published.items() if t is None]
+        young = [(p, (now - t).days) for p, t in published.items() if t is not None and (now - t).days < min_age]
+
+        scope = f"new since {ctx.base[:10]}" if ctx.base else "declared"
+        lines = [f"{len(added)} {scope} package(s) vetted against their registries"]
+        lines += [f"MISSING {p.ecosystem}:{p.name}: not on the registry (hallucinated or private?)" for p in missing]
+        lines += [f"NEW     {p.ecosystem}:{p.name}: first published {d} day(s) ago" for p, d in young]
+        if missing or young:
+            lines.append("If a package is intended, add it to `allow` for this check after reviewing it.")
+            return Outcome("fail", f"{len(missing)} missing, {len(young)} younger than {min_age} days", lines)
+        return Outcome("pass", f"{len(added)} {scope} package(s) exist and are at least {min_age} days old", lines)

rung/checks/findings.py

@@ -0,0 +1,153 @@
+"""Baselines and waivers: how a team adopts a scanner without drowning in old findings.
+
+Turning on a security scanner in a real codebase usually produces hundreds of
+existing findings, and a gate that fails on all of them gets switched off. Rung
+gates on what a change *introduces* instead. The comparison point is either the
+merge base of the branch (computed fresh) or a committed baseline file recorded
+deliberately with `rung baseline`.
+
+A finding that must stay can be waived, but only with a reason, an approver and
+an expiry date. Expired waivers stop applying and are reported, so "temporary"
+exceptions cannot quietly become permanent.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime
+from pathlib import Path
+
+from rung.core.config import toml_value, write_atomic
+from rung.engines.sarif import Finding, at_least, diff
+
+BASELINE_DIR = Path(".rung") / "baselines"
+WAIVERS_FILE = Path(".rung") / "waivers.toml"
+
+
+def baseline_path_rel(check_id: str) -> str:
+    return (BASELINE_DIR / f"{check_id}.json").as_posix()
+
+
+def baseline_path(root: Path, check_id: str) -> Path:
+    return root / baseline_path_rel(check_id)
+
+
+def load_baseline(root: Path, check_id: str) -> list[Finding] | None:
+    path = baseline_path(root, check_id)
+    if not path.exists():
+        return None
+    data = json.loads(path.read_text())
+    return [Finding.from_dict(f) for f in data.get("findings", [])]
+
+
+def save_baseline(root: Path, check_id: str, findings: list[Finding], commit: str) -> Path:
+    path = baseline_path(root, check_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "check": check_id,
+        "recorded": datetime.now(UTC).isoformat(timespec="seconds"),
+        "commit": commit,
+        "findings": [f.to_dict() for f in sorted(findings, key=lambda f: (f.path, f.rule, f.fingerprint))],
+    }
+    write_atomic(path, json.dumps(payload, indent=2) + "\n")
+    return path
+
+
+@dataclass
+class Waiver:
+    check: str
+    fingerprint: str
+    reason: str
+    approved_by: str
+    expires: date
+
+    def active(self, today: date) -> bool:
+        return today <= self.expires
+
+
+def load_waivers(root: Path) -> list[Waiver]:
+    path = root / WAIVERS_FILE
+    if not path.exists():
+        return []
+    raw = tomllib.loads(path.read_text())
+    out = []
+    for w in raw.get("waiver", []):
+        expires = w["expires"]
+        if isinstance(expires, str):
+            expires = date.fromisoformat(expires)
+        out.append(Waiver(w["check"], w["fingerprint"], w["reason"], w["approved_by"], expires))
+    return out
+
+
+def add_waiver(root: Path, waiver: Waiver) -> Path:
+    if not waiver.reason.strip():
+        raise ValueError("a waiver needs a reason")
+    path = root / WAIVERS_FILE
+    existing = path.read_text() if path.exists() else ""
+    block = (
+        "\n[[waiver]]\n"
+        f"check = {toml_value(waiver.check)}\n"
+        f"fingerprint = {toml_value(waiver.fingerprint)}\n"
+        f"reason = {toml_value(waiver.reason)}\n"
+        f"approved_by = {toml_value(waiver.approved_by)}\n"
+        f"expires = {waiver.expires.isoformat()}\n"
+    )
+    text = existing + block
+    tomllib.loads(text)  # never write a waivers file Rung could not read back
+    write_atomic(path, text)
+    return path
+
+
+@dataclass
+class Triage:
+    blocking: list[Finding] = field(default_factory=list)
+    nonblocking: list[Finding] = field(default_factory=list)
+    waived: list[Finding] = field(default_factory=list)
+    resolved: list[Finding] = field(default_factory=list)
+    expired: list[Waiver] = field(default_factory=list)
+    compared_with: str = "nothing (every finding counts as new)"
+    valid_until: str = ""  # the earliest expiry among waivers this result relied on
+
+
+def triage(
+    check_id: str,
+    head: list[Finding],
+    base: list[Finding] | None,
+    waivers: list[Waiver],
+    *,
+    fail_on: str,
+    today: date | None = None,
+    compared_with: str = "",
+) -> Triage:
+    """Split the head run's findings into what blocks, what does not, and what is waived."""
+    today = today or date.today()
+    mine = [w for w in waivers if w.check == check_id]
+    active = {w.fingerprint for w in mine if w.active(today)}
+    expired = [w for w in mine if not w.active(today)]
+    introduced, resolved = diff(base or [], head)
+    # A finding that already existed below the threshold and now meets it has escalated: it blocks too.
+    base_levels: dict[str, str] = {}
+    for f in base or []:
+        if f.fingerprint not in base_levels or at_least(f.level, base_levels[f.fingerprint]):
+            base_levels[f.fingerprint] = f.level
+    new_ids = {id(f) for f in introduced}
+    escalated = [
+        f for f in head
+        if id(f) not in new_ids and f.fingerprint in base_levels
+        and at_least(f.level, fail_on) and not at_least(base_levels[f.fingerprint], fail_on)
+    ]  # fmt: skip
+    result = Triage(resolved=resolved, expired=expired)
+    if compared_with:
+        result.compared_with = compared_with
+    for f in [*introduced, *escalated]:
+        if f.fingerprint in active:
+            result.waived.append(f)
+        elif at_least(f.level, fail_on):
+            result.blocking.append(f)
+        else:
+            result.nonblocking.append(f)
+    used = [w.expires for w in mine if w.active(today) and any(f.fingerprint == w.fingerprint for f in result.waived)]
+    result.valid_until = min(used).isoformat() if used else ""
+    return result

rung/checks/formal.py

@@ -0,0 +1,112 @@
+"""Formal checkers: TLA+ model checking, Lean proofs, and differential testing against a model."""
+
+from __future__ import annotations
+
+import shlex
+
+from rung.checks.base import Checker, Context, Outcome
+from rung.core.config import Check, ConfigError
+from rung.engines import drt, lean, tla
+
+
+class TLAChecker(Checker):
+    kind = "tla"
+    summary = "Model-check a TLA+ spec with TLC"
+
+    def specs(self, check: Check) -> list[str]:
+        files = [check.require("spec")]
+        if cfg := check.get("config"):
+            files.append(cfg)
+        return files
+
+    def run(self, ctx: Context, check: Check) -> Outcome:
+        cfg = check.get("config")
+        if not cfg:
+            raise ConfigError(f"check {check.id!r}: a TLA+ check needs a `config` (.cfg) listing what to check")
+        declared = tla.declared_properties(ctx.root / cfg)
+        if not declared["invariants"] and not declared["properties"]:
+            return Outcome("fail", "the .cfg declares no INVARIANT or PROPERTY, so TLC checked nothing", [
+                f"add e.g. `INVARIANT TypeOK` to {cfg}",
+            ])  # fmt: skip
+        result = tla.run(
+            ctx.root / check.require("spec"),
+            ctx.root / cfg if cfg else None,
+            timeout=check.get_int("timeout", 600),
+        )
+        lines = [f"{result.distinct_states} distinct states explored"] if result.distinct_states else []
+        checked = declared["invariants"] + declared["properties"]
+        lines.append("checked: " + ", ".join(checked))
+        if declared["narrowing"]:
+            lines.append("note: " + "; ".join(declared["narrowing"]) + " (narrows what a pass covers)")
+        if result.trace:
+            lines.append(f"counterexample ({len(result.trace)} states):")
+            lines.append(tla.render_trace(result.trace))
+        elif result.verdict == "error":
+            lines.append(result.output.strip()[-1500:])
+        if result.verdict == "pass" and result.distinct_states <= 1:
+            # A spec that reaches one state checks nothing; treat it as a spec bug.
+            return Outcome("fail", "spec reaches at most one state; invariants are vacuous", lines)
+        return Outcome(result.verdict, result.reason, lines)
+
+
+class LeanChecker(Checker):
+    kind = "lean"
+    summary = "Build a Lean project and audit its theorems' axioms"
+
+    def specs(self, check: Check) -> list[str]:
+        project = check.require("project").rstrip("/")
+        return [f"{project}/**/*.lean", f"{project}/lakefile.*", f"{project}/lean-toolchain"]
+
+    def run(self, ctx: Context, check: Check) -> Outcome:
+        result = lean.run(
+            ctx.root / check.require("project"),
+            check.get_list("theorems"),
+            timeout=check.get_int("timeout", 1800),
+        )
+        lines = list(result.findings) + [f"WEAK {w}" for w in result.warnings]
+        for theorem, axioms in result.axioms.items():
+            lines.append(f"{theorem}: axioms [{', '.join(axioms) or 'none'}]")
+        if result.verdict != "pass" and not result.findings:
+            lines.append(result.output.strip()[-1500:])
+        return Outcome(result.verdict, result.reason, lines)
+
+
+def _resolve_tools(command: str) -> str:
+    """Point a leading `lake` at the elan install, which is often not on PATH."""
+    parts = shlex.split(command)
+    if parts and parts[0] == "lake":
+        parts[0] = lean.find_lake()
+    return shlex.join(parts)
+
+
+class DRTChecker(Checker):
+    kind = "drt"
+    summary = "Differentially test the implementation against an executable model"
+
+    def run(self, ctx: Context, check: Check) -> Outcome:
+        cases, min_len, max_len = check.get_int("cases", 1000), check.get_int("min_len", 0), check.get_int("max_len", 8)
+        if cases < 1:
+            raise ConfigError(f"check {check.id!r}: `cases` must be at least 1; zero inputs prove nothing")
+        if min_len > max_len:
+            raise ConfigError(f"check {check.id!r}: `min_len` ({min_len}) is greater than `max_len` ({max_len})")
+        model = drt.Side(_resolve_tools(check.require("model")), ctx.root / check.get("model_cwd", "."))
+        impl = drt.Side(_resolve_tools(check.require("impl")), ctx.root / check.get("impl_cwd", "."))
+        result = drt.run(
+            model,
+            impl,
+            alphabet=[str(t) for t in check.require("alphabet")],
+            cases=cases,
+            min_len=min_len,
+            max_len=max_len,
+            seed=check.get_int("seed", 0),
+            timeout=check.get_int("timeout", 600),
+        )
+        lines = []
+        if result.minimal:
+            m = result.minimal
+            lines += [
+                f"minimal diverging input: {m.input or '(empty)'}",
+                f"  model: {m.model}",
+                f"  impl:  {m.impl}",
+            ]
+        return Outcome(result.verdict, result.reason, lines)

rung/checks/presets.py

@@ -0,0 +1,96 @@
+"""Built-in scanner presets for `kind = "scan"` checks.
+
+Each preset is a command that writes SARIF, plus sensible defaults for which
+files it covers and which severity blocks. `{out}` in a command is replaced with
+a temporary file path; a command without `{out}` must write SARIF to stdout.
+
+Commands marked `verified` were run against real output while writing Rung.
+Any preset can be overridden field by field in `rung.toml`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Preset:
+    name: str
+    purpose: str
+    run: str
+    install: str
+    fail_on: str = "warning"
+    # Severity for results the tool reports without a level (gitleaks reports none).
+    default_level: str = "warning"
+    # Days a verdict stays valid even if no file changes: advisory databases update daily.
+    max_age_days: int | None = None
+    covers: list[str] = field(default_factory=lambda: ["**/*"])
+    verified: bool = False
+
+
+PRESETS: dict[str, Preset] = {
+    p.name: p
+    for p in (
+        Preset(
+            "gitleaks",
+            "secrets committed to the code",
+            # --redact keeps secret values out of the report, the ledger and the terminal.
+            "gitleaks dir . --no-banner --redact -f sarif -r {out}",
+            "brew install gitleaks  |  https://github.com/gitleaks/gitleaks",
+            default_level="error",
+            verified=True,
+        ),
+        Preset(
+            "osv-scanner",
+            "dependencies with known vulnerabilities",
+            "osv-scanner scan source -r . -f sarif --output-file {out}",
+            "brew install osv-scanner  |  https://github.com/google/osv-scanner",
+            max_age_days=1,
+            covers=[
+                "**/requirements*.txt",
+                "**/pyproject.toml",
+                "**/poetry.lock",
+                "**/uv.lock",
+                "**/Pipfile.lock",
+                "**/package.json",
+                "**/package-lock.json",
+                "**/pnpm-lock.yaml",
+                "**/yarn.lock",
+                "**/go.mod",
+                "**/go.sum",
+                "**/Cargo.lock",
+                "**/Gemfile.lock",
+                "**/composer.lock",
+                "**/pom.xml",
+                "**/gradle.lockfile",
+            ],
+            verified=True,
+        ),
+        Preset(
+            "zizmor",
+            "insecure GitHub Actions workflows",
+            "zizmor --offline --format sarif .",
+            "brew install zizmor  |  https://github.com/zizmorcore/zizmor",
+            covers=[".github/workflows/**", ".github/actions/**", "action.yml", "action.yaml"],
+            verified=True,
+        ),
+        Preset(
+            "semgrep",
+            "insecure code patterns (injection, SSRF, unsafe deserialization)",
+            "semgrep scan --config p/default --sarif --metrics off --quiet --output {out}",
+            "pipx install semgrep  |  https://semgrep.dev",
+        ),
+        Preset(
+            "opengrep",
+            "insecure code patterns, with the open Semgrep fork",
+            "opengrep scan --config p/default --sarif --quiet --output {out}",
+            "https://github.com/opengrep/opengrep",
+        ),
+        Preset(
+            "trivy",
+            "vulnerabilities and misconfigurations in containers and infrastructure code",
+            "trivy fs --scanners vuln,misconfig,secret --format sarif --output {out} .",
+            "brew install trivy  |  https://trivy.dev",
+        ),
+    )
+}