carabiner-sec 0.1.2__tar.gz

carabiner_sec-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritish Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

carabiner_sec-0.1.2/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: carabiner-sec
+Version: 0.1.2
+Summary: Make any repo secure by default, keep it that way, and prove the controls fire.
+Project-URL: Homepage, https://maximo000.github.io/carabiner/
+Project-URL: Source, https://github.com/MaXiMo000/carabiner
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Dynamic: license-file

carabiner_sec-0.1.2/README.md

@@ -0,0 +1,101 @@
+# carabiner
+
+> A carabiner is the piece of gear that locks the system together and is rated
+> to catch a fall. It is also the only piece you check *before* you need it.
+
+Make any repository secure by default in one command, keep it that way, and
+prove the protections actually fire.
+
+**→ [maximo000.github.io/carabiner](https://maximo000.github.io/carabiner/)**
+
+```
+$ carabiner scan
+  CRITICAL CI001  .github/workflows/pr.yml
+           job 'hello' runs on pull_request_target and checks out the PR head
+           -- untrusted code runs with your secrets
+           fix: use `pull_request`, or split into an untrusted build job and a
+                privileged job that never checks out the head
+
+  2 new, 340 accepted (carabiner debt)   0.02s
+```
+
+## Why another one
+
+Every scanner already exists and is free — gitleaks, Trivy, Semgrep,
+OSV-Scanner. They are excellent and carabiner does not reimplement any of them.
+And the median repository runs none of them, for three specific reasons:
+
+1. **Setup is per-tool, per-language, per-CI.** A two-hour job you do once.
+2. **The first run returns 400 findings and everyone gives up.** The gate gets
+   turned off, and the tool now has *negative* value — it looks like coverage.
+3. **A configured control is not a working control.** The hook is in
+   `.pre-commit-config.yaml` but nobody ran `pre-commit install`.
+
+## The three things that aren't a wrapper
+
+**The ratchet.** `carabiner lock` accepts every existing finding into a
+baseline. From then on CI fails only on what's *new*. You can adopt this in a
+ten-year-old repo on a Tuesday afternoon, and security only tightens from
+there. Accepted findings stay visible via `carabiner debt` — the debt is
+tracked, not deleted — and `--expires 90` puts a deadline on it, because
+without one "accepted" quietly means "forever".
+
+Findings are fingerprinted on `(engine, rule, path, normalized snippet)`, never
+on line numbers. Adding an import at the top of a file must not resurrect 400
+accepted findings; that's why baseline features elsewhere get abandoned.
+
+**The drill.** `carabiner drill` doesn't read configuration — it attacks the
+repo. It plants a private key and checks the installed pre-commit hooks actually
+stop it; asks GitHub whether push protection is really on; and verifies the
+security workflow is a *required* check rather than one that runs, fails, and
+merges anyway.
+
+```
+$ carabiner drill
+  HIGH     DRILL002  pre-commit hooks are configured but NOT installed --
+                     the config looks right and nothing runs
+  HIGH     DRILL012  the repository default GITHUB_TOKEN is read/WRITE
+```
+
+A drill that could not run **never reports as passing** — no token, no network,
+no `pre-commit` binary all produce "could NOT be verified", not a green check.
+Unverified is not secure. Drills are also never ratcheted: a control that
+stopped working is a regression today, not pre-existing debt to accept.
+
+> Most security tools check your configuration. carabiner checks your defenses
+> by trying to get past them.
+
+**One normalized model.** Every engine reports into one `Finding`. Deduplicated
+across engines — Trivy and OSV-Scanner both read your lockfile, and a developer
+shown the same CVE twice trusts the tool less each time — and emitted as SARIF
+so findings land in the PR Security tab.
+
+## Status
+
+Phase 0. Native engines only (`ci`, `repo`) — no external tools required, and
+they still find real problems. Scanner wrappers are Phase 1, the drill is
+Phase 3. See [PLAN.md](PLAN.md).
+
+```bash
+python3 -m carabiner.cli scan --root /path/to/repo
+python3 -m carabiner.cli lock --root /path/to/repo   # ratchet
+python3 -m carabiner.cli debt --root /path/to/repo
+```
+
+## Engines
+
+| Engine | Checks | Needs |
+|---|---|---|
+| `ci` (GitHub Actions) | CI001 `pull_request_target` + PR-head checkout · CI002 script injection from `github.event` into `run:` · CI003 unpinned actions · CI004/5 token blast radius · CI007 self-hosted runners | nothing |
+| `ci` (GitLab CI) | GL001 script injection from merge-request title or branch name · GL002 unpinned remote `include:` · GL003 mutable image/service tags | nothing |
+| `repo` | REPO001 `.gitignore` gaps · REPO002 committed key material · REPO003 no SECURITY.md · REPO004 credentials in git remotes | nothing |
+
+## What it will never do
+
+No SaaS. No dashboard. No account. No telemetry. No AI. No auto-rewriting your
+security config. And it never reimplements a scanner that already exists —
+the value is the ratchet, the drill, and the normalized model.
+
+Dependencies: PyYAML and the standard library. That is the whole list, on
+purpose — every dependency is a package a security auditor now implicitly
+vouches for.

carabiner_sec-0.1.2/carabiner/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

carabiner_sec-0.1.2/carabiner/baseline.py

@@ -0,0 +1,83 @@
+"""The ratchet.
+
+Existing findings are accepted once and recorded. From then on only *new*
+findings fail the build. Security tightens or holds; it does not loosen.
+
+This is what makes the tool installable in a ten-year-old repo on a Tuesday
+afternoon instead of requiring a cleanup sprint nobody will schedule.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from datetime import date, timedelta
+
+from .finding import Finding
+
+BASELINE_PATH = pathlib.Path(".carabiner/baseline.json")
+
+
+def load(root: pathlib.Path) -> dict[str, dict]:
+    path = root / BASELINE_PATH
+    if not path.exists():
+        return {}
+    data = json.loads(path.read_text() or "{}")
+    return data.get("accepted", {})
+
+
+def expired(entry: dict, today: str | None = None) -> bool:
+    """An accepted finding with a date on it stops being accepted when that date
+    passes. Without expiry, 'accepted' quietly means 'forever', which is how a
+    baseline turns into a place debt goes to be forgotten."""
+    stamp = entry.get("expires")
+    return bool(stamp) and stamp < (today or date.today().isoformat())
+
+
+def fixed(findings: list[Finding], accepted: dict[str, dict]) -> list[dict]:
+    """Accepted entries whose finding is gone. Worth saying out loud -- a review
+    that only ever reports new problems never tells anyone they are winning."""
+    live = {f.fingerprint for f in findings}
+    return [e for fp, e in accepted.items() if fp not in live]
+
+
+def save(root: pathlib.Path, findings: list[Finding], reason: str = "",
+         expires_days: int | None = None) -> int:
+    """Accept everything currently found. Keeps first_seen for entries we
+    already knew about, so the age of the debt survives a re-lock."""
+    path = root / BASELINE_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing = load(root)
+    today = date.today().isoformat()
+    horizon = ((date.today() + timedelta(days=expires_days)).isoformat()
+               if expires_days else None)
+    accepted = {}
+    for f in findings:
+        prior = existing.get(f.fingerprint, {})
+        entry = {
+            "rule": f.rule, "path": f.path, "severity": f.severity,
+            "message": f.message,
+            "first_seen": prior.get("first_seen", today),
+            "reason": prior.get("reason") or reason,
+        }
+        deadline = horizon or prior.get("expires")
+        if deadline:
+            entry["expires"] = deadline
+        accepted[f.fingerprint] = entry
+    path.write_text(json.dumps(
+        {"version": 1, "accepted": accepted}, indent=2, sort_keys=True) + "\n")
+    return len(accepted)
+
+
+def partition(findings: list[Finding], accepted: dict[str, dict]
+              ) -> tuple[list[Finding], list[Finding]]:
+    """-> (new, still_accepted). Only the first list should fail a build.
+
+    An expired acceptance counts as new. That is the whole point of putting a
+    date on it: the deadline has to actually arrive.
+    """
+    new, old = [], []
+    for f in findings:
+        entry = accepted.get(f.fingerprint)
+        (old if entry and not expired(entry) else new).append(f)
+    return new, old

carabiner_sec-0.1.2/carabiner/cli.py

@@ -0,0 +1,225 @@
+"""carabiner -- make a repo secure by default, keep it that way, prove it fires.
+
+    carabiner init     adopt: detect, configure, ratchet    once per repo
+    carabiner scan     what is new since the baseline       pre-commit, CI
+    carabiner lock     accept what exists today             deliberate debt
+    carabiner debt     what we are carrying                 sprint planning
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+import time
+
+from . import baseline, config, drill
+from .engines import ALL
+from .engines import missing as engines_missing
+from .finding import rank
+from .report import human, sarif
+
+
+def _collect(root: pathlib.Path, only: list[str] | None, full: bool = False,
+             cfg: config.Config | None = None):
+    cfg = cfg or config.Config()
+    findings = []
+    for name, engine in ALL.items():
+        if only and name not in only:
+            continue
+        if not cfg.enabled(name):
+            continue
+        if engine.available(root):
+            findings.extend(engine.run(root, full))
+    return [f for f in dedupe(findings) if not cfg.ignored(f)]
+
+
+def dedupe(findings):
+    """Collapse identical findings, keeping the most severe.
+
+    Severity is load-bearing, not cosmetic. The same secret found in the working
+    tree AND in history is one problem, but only the history version carries the
+    right remediation -- rotate and purge, not just delete. Keeping whichever
+    arrived first would quietly downgrade it. Same rule covers two scanners
+    disagreeing about a CVE's severity: believe the worse one.
+    """
+    best: dict[str, object] = {}
+    for f in findings:
+        prior = best.get(f.fingerprint)
+        if prior is None or rank(f.severity) > rank(prior.severity):
+            best[f.fingerprint] = f
+    return list(best.values())
+
+
+TEMPLATE = """\
+# carabiner -- https://github.com/MaXiMo000/carabiner
+version: 1
+
+engines:
+{engines}
+# Every suppression must carry a written reason. An ignore without one is a
+# config error, not a warning -- an unexplained ignore list is how a scan
+# quietly becomes decorative.
+#
+# ignore:
+#   - path: tests/fixtures/**
+#     reason: "deliberately vulnerable corpus"
+"""
+
+
+def _init(root: pathlib.Path, dry_run: bool) -> int:
+    detected = config.detect(root)
+    print("detected:")
+    for name, why in detected.items():
+        print(f"  {name:<9} {why}")
+
+    skipped = engines_missing(root)
+    for name, hint in skipped:
+        print(f"\n  '{name}' has nothing installed to run -- {hint}")
+
+    lines = "".join(
+        f"  {n}: {{enabled: true, fail_on: {'high' if n == 'deps' else 'medium'}}}\n"
+        for n in detected)
+    body = TEMPLATE.format(engines=lines)
+    cfg_path = root / config.CONFIG_NAME
+
+    print(f"\nwould write {config.CONFIG_NAME}:" if dry_run
+          else f"\nwriting {config.CONFIG_NAME}:")
+    print("".join(f"  | {l}\n" for l in body.splitlines()))
+
+    findings = _collect(root, None, full=True)
+    print(f"first scan: {len(findings)} findings")
+
+    if dry_run:
+        print(f"\n--dry-run: nothing written. Drop the flag to adopt.")
+        return 0
+
+    if cfg_path.exists():
+        print(f"{config.CONFIG_NAME} already exists -- left alone.")
+    else:
+        cfg_path.write_text(body)
+    n = baseline.save(root, findings, reason="accepted at carabiner init")
+
+    print(f"ratcheted {n} findings into {baseline.BASELINE_PATH}\n")
+    print("CI is green from here, and only NEW findings will fail it.")
+    print("Existing debt is recorded, not deleted -- see `carabiner debt`.")
+    print("Commit .carabiner.yml and .carabiner/ so the ratchet is shared.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="carabiner")
+    ap.add_argument("command", choices=["init", "scan", "drill", "lock", "debt"])
+    ap.add_argument("--root", type=pathlib.Path, default=pathlib.Path("."))
+    ap.add_argument("--engine", action="append", dest="engines")
+    ap.add_argument("--fail-on", default=None,
+                    help="override the per-engine threshold from .carabiner.yml")
+    ap.add_argument("--all", action="store_true", dest="full",
+                    help="every engine, whole history. CI cadence, not pre-commit.")
+    ap.add_argument("--dry-run", action="store_true", help="init: write nothing")
+    ap.add_argument("--offline", action="store_true",
+                    help="make no network calls; API drills report as unverified")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--sarif", metavar="PATH",
+                    help="write SARIF 2.1.0 for GitHub code scanning")
+    ap.add_argument("--summary", metavar="PATH",
+                    help="write a short markdown summary for a PR comment")
+    ap.add_argument("--expires", type=int, metavar="DAYS",
+                    help="lock: accept these findings for DAYS, then stop")
+    # No --token flag, deliberately: argv is world-readable via /proc and CI
+    # logs echo commands. Tokens come from the environment only.
+    args = ap.parse_args(argv)
+
+    root = args.root.resolve()
+    try:
+        cfg = config.load(root)
+    except config.ConfigError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    if args.command == "init":
+        return _init(root, args.dry_run)
+
+    if args.command == "drill":
+        started = time.monotonic()
+        found = drill.run(root, offline=args.offline)
+        print(human.render(found, [], time.monotonic() - started))
+        # Drills are not ratcheted. A control that stopped working is not
+        # pre-existing debt to accept -- it is a regression, today.
+        return cfg.gate(found)
+
+    started = time.monotonic()
+    findings = _collect(root, args.engines, args.full, cfg)
+    skipped = engines_missing(root)
+    accepted_map = baseline.load(root)
+    new, accepted = baseline.partition(findings, accepted_map)
+
+    if args.command == "lock":
+        n = baseline.save(root, findings, expires_days=args.expires)
+        print(f"ratcheted: {n} findings accepted -> {baseline.BASELINE_PATH}")
+        if args.expires:
+            print(f"expires in {args.expires} days, after which they fail again.")
+        print("only new findings will fail the build from here.")
+        return 0
+
+    if args.command == "debt":
+        gone = baseline.fixed(findings, accepted_map)
+        overdue = 0
+        for fp, e in sorted(accepted_map.items(),
+                            key=lambda kv: -rank(kv[1]["severity"])):
+            late = baseline.expired(e)
+            overdue += late
+            tail = f"   since {e['first_seen']}"
+            if e.get("expires"):
+                tail += f"   {'OVERDUE since' if late else 'due'} {e['expires']}"
+            print(f"  {e['severity']:<8} {e['rule']:<8} {e['path']}{tail}")
+            if e.get("reason"):
+                print(f"           {e['reason']}")
+        print(f"\n{len(accepted_map)} accepted"
+              + (f", {overdue} overdue" if overdue else "")
+              + (f", {len(gone)} already fixed (run `carabiner lock` to prune)"
+                 if gone else ""))
+        return 0
+
+    gone = baseline.fixed(findings, accepted_map)
+    if args.summary:
+        # Deliberately terse. A bot that restates the entire backlog on every PR
+        # gets muted, and then the two lines that mattered are muted with it.
+        bits = [f"**{len(new)} new**"]
+        if gone:
+            bits.append(f"{len(gone)} fixed")
+        bits.append(f"{len(accepted)} accepted")
+        lines = [f"### carabiner — {' · '.join(bits)}", ""]
+        for f in sorted(new, key=lambda x: -rank(x.severity))[:10]:
+            loc = f"`{f.path}`" + (f" line {f.line}" if f.line else "")
+            lines.append(f"- **{f.severity.upper()}** `{f.rule}` {loc} — {f.message}")
+        if len(new) > 10:
+            lines.append(f"- …and {len(new)-10} more")
+        if not new:
+            lines.append("No new findings.")
+        pathlib.Path(args.summary).write_text("\n".join(lines) + "\n")
+
+    if args.sarif:
+        # Every finding, not just the new ones: the Security tab is an inventory,
+        # not a diff, and GitHub does its own resolved/new tracking from the
+        # fingerprints. The build gate below still only considers what is new.
+        from . import __version__
+        pathlib.Path(args.sarif).write_text(sarif.render(findings, __version__))
+        print(f"wrote {len(findings)} findings to {args.sarif}")
+
+    if args.json:
+        print(json.dumps({"new": [f.as_dict() for f in new],
+                          "accepted": len(accepted)}, indent=2))
+    else:
+        print(human.render(new, accepted, time.monotonic() - started, skipped,
+                           len(gone)))
+
+    if args.fail_on:
+        worst = max((rank(f.severity) for f in new), default=-1)
+        return 1 if worst >= rank(args.fail_on) else 0
+    return cfg.gate(new)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

carabiner_sec-0.1.2/carabiner/config.py

@@ -0,0 +1,92 @@
+"""`.carabiner.yml` -- and the one piece of process the tool imposes.
+
+Every suppression must carry a written reason. An ignore without one is a config
+error, not a warning. That single rule is the difference between a tool people
+keep and a tool people route around: a silent `ignore:` list grows until the
+scan is decorative, whereas a reason has to be defended in code review.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import pathlib
+
+import yaml
+
+from .finding import Finding, rank
+
+CONFIG_NAME = ".carabiner.yml"
+DEFAULT_FAIL_ON = "medium"
+
+
+class ConfigError(Exception):
+    """Raised rather than warned. A misread config silently disables checks."""
+
+
+class Config:
+    def __init__(self, data: dict | None = None):
+        data = data or {}
+        self.engines: dict = data.get("engines") or {}
+        self.ignores: list[dict] = []
+        for i, entry in enumerate(data.get("ignore") or []):
+            if not isinstance(entry, dict) or not str(entry.get("reason") or "").strip():
+                raise ConfigError(
+                    f"{CONFIG_NAME}: ignore[{i}] has no `reason`. Every "
+                    "suppression must say why, in writing -- an unexplained "
+                    "ignore list is how a scan quietly becomes decorative.")
+            self.ignores.append(entry)
+
+    def enabled(self, engine: str) -> bool:
+        return (self.engines.get(engine) or {}).get("enabled", True) is not False
+
+    def fail_on(self, engine: str) -> str:
+        return (self.engines.get(engine) or {}).get("fail_on", DEFAULT_FAIL_ON)
+
+    def ignored(self, f: Finding) -> bool:
+        for entry in self.ignores:
+            pat, rule = entry.get("path"), entry.get("check")
+            if pat and not fnmatch.fnmatch(f.path, pat):
+                continue
+            if rule and rule != f.rule:
+                continue
+            if pat or rule:
+                return True
+        return False
+
+    def gate(self, findings: list[Finding]) -> int:
+        """Exit code. Per-engine thresholds, because a missing SECURITY.md and a
+        leaked key do not deserve the same gate."""
+        for f in findings:
+            if rank(f.severity) >= rank(self.fail_on(f.engine)):
+                return 1
+        return 0
+
+
+def load(root: pathlib.Path) -> Config:
+    path = root / CONFIG_NAME
+    if not path.exists():
+        return Config()
+    try:
+        data = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as e:
+        raise ConfigError(f"{CONFIG_NAME} is not valid YAML: {e}") from e
+    if data is not None and not isinstance(data, dict):
+        raise ConfigError(f"{CONFIG_NAME} must be a mapping")
+    return Config(data)
+
+
+def detect(root: pathlib.Path) -> dict[str, str]:
+    """What this repo actually is -> what to switch on. Reported to the user
+    rather than applied silently."""
+    from .engines import deps
+
+    found = {}
+    if (root / ".github" / "workflows").is_dir():
+        found["ci"] = "GitHub Actions workflows"
+    found["repo"] = "repository hygiene (always on)"
+    if (root / ".git").is_dir():
+        found["secrets"] = "git repository"
+    present = [m for m in deps.MANIFESTS if (root / m).exists()]
+    if present:
+        found["deps"] = ", ".join(present[:3])
+    return found