bashboy 0.1.0__py3-none-any.whl

bashboy/__init__.py

@@ -0,0 +1,5 @@
+"""BashBoy: a deny-only shell-command gate for coding agents."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

bashboy/__main__.py

@@ -0,0 +1,5 @@
+"""Enable ``python -m bashboy``."""
+
+from .cli import main
+
+raise SystemExit(main())

bashboy/classify.py

@@ -0,0 +1,124 @@
+"""Verdict pipeline: fast local paths first, model second, fail closed.
+
+Precedence is fixed and auditable:
+
+1. ``BASHBOY_DISABLE`` -- allow, source ``disabled`` (documented escape hatch).
+2. Blank command -- deny, source ``fallback``.
+3. Denylist -- deny, source ``denylist``.
+4. Allowlist -- allow, source ``allowlist``.
+5. Model -- allow/deny, source ``model``; any failure becomes ``fallback``.
+
+The provider is imported lazily inside branch 5 so the fast paths never pay for
+``urllib`` or ``json`` at startup.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from dataclasses import dataclass
+
+from .config import Config, api_key, load_config
+from .rules import check_allowlist, check_denylist
+
+_TRUTHY = frozenset({"1", "true", "yes"})
+
+
+def log(msg: str) -> None:
+    """Write a diagnostic line to stderr, but only when ``BASHBOY_DEBUG`` is truthy.
+
+    Never pass the API key, an ``Authorization`` header, or a full request body.
+    """
+    value = os.environ.get("BASHBOY_DEBUG", "")
+    if value.strip().lower() in _TRUTHY:
+        print(f"bashboy: {msg}", file=sys.stderr)
+
+
+def _enabled(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in _TRUTHY
+
+
+@dataclass(frozen=True)
+class Classification:
+    """The final verdict the CLI prints and the hooks act on."""
+
+    decision: str
+    source: str
+    reason: str
+    risk: str | None = None
+    latency_ms: int = 0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "latency_ms", int(self.latency_ms))
+
+    def to_dict(self) -> dict[str, object]:
+        # Key order is part of the CLI contract; keep it stable.
+        return {
+            "decision": self.decision,
+            "source": self.source,
+            "reason": self.reason,
+            "risk": self.risk,
+            "latency_ms": self.latency_ms,
+        }
+
+def _elapsed_ms(started: float) -> int:
+    return max(int((time.perf_counter() - started) * 1000), 0)
+
+
+def classify_command(
+    command: str,
+    cwd: str | None = None,
+    cfg: Config | None = None,
+    provider: object | None = None,
+) -> Classification:
+    """Classify ``command``. Never raises for provider problems; fails closed."""
+    started = time.perf_counter()
+    if cfg is None:
+        cfg = load_config()
+
+    if _enabled("BASHBOY_DISABLE"):
+        latency = _elapsed_ms(started)
+        log(f"BASHBOY_DISABLE is set: allowing without checks (latency={latency}ms)")
+        return Classification("allow", "disabled", "BASHBOY_DISABLE is set", None, latency)
+
+    if not isinstance(command, str) or not command.strip():
+        return Classification("deny", "fallback", "no command provided", None, _elapsed_ms(started))
+
+    if cfg.policy.denylist:
+        hit = check_denylist(command, cwd)
+        if hit is not None:
+            latency = _elapsed_ms(started)
+            log(f"denylist hit: {hit.reason} (latency={latency}ms)")
+            return Classification("deny", "denylist", hit.reason, None, latency)
+
+    if cfg.policy.allowlist:
+        label = check_allowlist(command)
+        if label is not None:
+            latency = _elapsed_ms(started)
+            log(f"allowlist hit: {label} (latency={latency}ms)")
+            return Classification(
+                "allow", "allowlist", f"matches allowlist: {label}", None, latency
+            )
+
+    from .provider import Provider
+
+    target_cwd = cwd or os.getcwd()
+    try:
+        model = provider if provider is not None else Provider(cfg.provider, key=api_key(cfg))
+        verdict = model.classify(target_cwd, command)  # type: ignore[attr-defined]
+    except Exception as exc:  # noqa: BLE001 - every failure must map to a verdict
+        fail_open = cfg.policy.fail_mode == "open"
+        decision = "allow" if fail_open else "deny"
+        latency = _elapsed_ms(started)
+        log(f"classifier unavailable: {exc} (latency={latency}ms)")
+        return Classification(
+            decision, "fallback", f"classifier unavailable: {exc}", None, latency
+        )
+
+    latency = _elapsed_ms(started)
+    log(
+        f"model verdict {verdict.decision} from {cfg.provider.endpoint} "
+        f"(latency={latency}ms)"
+    )
+    return Classification(verdict.decision, "model", verdict.reason, verdict.risk, latency)

bashboy/cli.py

@@ -0,0 +1,271 @@
+"""Command-line interface.
+
+stdout is reserved for verdict output (``--json``), hook payloads, and installer
+JSON in dry-run mode. Diagnostics go to stderr so ``| jq`` and hooks stay clean.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import sys
+from pathlib import Path
+
+from . import __version__
+from .classify import classify_command, log
+from .config import (
+    DEFAULT_CONFIG_TOML,
+    Config,
+    ConfigError,
+    api_key,
+    config_path,
+    load_config,
+)
+
+
+def _toml_bool(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def render_config(cfg: Config) -> str:
+    lines = [
+        f"# source: {cfg.path}",
+        "[provider]",
+        f'endpoint = "{cfg.provider.endpoint}"',
+        f'api_key_env = "{cfg.provider.api_key_env}"',
+        f"timeout_ms = {cfg.provider.timeout_ms}",
+        "",
+        "[policy]",
+        f'fail_mode = "{cfg.policy.fail_mode}"',
+        f"denylist = {_toml_bool(cfg.policy.denylist)}",
+        f"allowlist = {_toml_bool(cfg.policy.allowlist)}",
+        "",
+        "[integrations.claude]",
+        f"timeout_s = {cfg.claude.timeout_s}",
+        "",
+        "[integrations.opencode]",
+        f"timeout_ms = {cfg.opencode.timeout_ms}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+# --- check ----------------------------------------------------------------
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    if args.claude_hook:
+        from .hooks.claude import run_hook
+
+        return run_hook(sys.stdin, sys.stdout)
+
+    if args.command_text is None:
+        print("bashboy: --command is required (or use --claude-hook)", file=sys.stderr)
+        return 2
+
+    cfg = load_config()
+    log(f"config: {cfg.path}")
+    result = classify_command(args.command_text, cwd=args.cwd, cfg=cfg)
+
+    if args.json:
+        print(json.dumps(result.to_dict()))
+    else:
+        print(f"{result.decision} ({result.source}): {result.reason}")
+    return 0 if result.decision == "allow" else 1
+
+
+# --- config ---------------------------------------------------------------
+
+
+def _cmd_config(args: argparse.Namespace) -> int:
+    path = config_path()
+    if args.action is None or args.action == "path":
+        print(path)
+        return 0
+
+    if args.action == "show":
+        cfg = load_config()
+        sys.stdout.write(render_config(cfg))
+        return 0
+
+    if args.action == "init":
+        if path.exists() and not args.force:
+            print(f"{path} already exists; re-run with --force to overwrite")
+            return 1
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(DEFAULT_CONFIG_TOML, encoding="utf-8")
+        print(f"wrote {path}")
+        return 0
+
+    print(f"bashboy: unknown config action {args.action!r}", file=sys.stderr)
+    return 2
+
+
+# --- install --------------------------------------------------------------
+
+_DEFAULT_CLAUDE_SETTINGS = Path.home() / ".claude" / "settings.json"
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    both = args.all or (not args.claude and not args.opencode)
+    run_claude = args.claude or both
+    run_opencode = args.opencode or both
+
+    try:
+        from .installers.claude import install_claude
+        from .installers.opencode import install_opencode
+    except ImportError as exc:  # pragma: no cover - installers ship with the package
+        print(f"bashboy: installers unavailable: {exc}", file=sys.stderr)
+        return 2
+
+    results: dict[str, dict] = {}
+    try:
+        if run_claude:
+            results["claude"] = install_claude(
+                args.settings, from_spec=args.from_spec, dry_run=args.dry_run
+            )
+        if run_opencode:
+            results["opencode"] = install_opencode(args.config_dir, dry_run=args.dry_run)
+    except (ConfigError, OSError, ValueError) as exc:
+        print(f"bashboy: {exc}", file=sys.stderr)
+        return 2
+
+    if args.dry_run:
+        if run_claude and run_opencode:
+            print(json.dumps({"claude": results["claude"], "opencode": results["opencode"]}))
+        elif run_claude:
+            print(json.dumps(results["claude"]))
+        else:
+            print(json.dumps(results["opencode"]))
+        return 0
+
+    if run_claude:
+        settings = Path(args.settings) if args.settings else _DEFAULT_CLAUDE_SETTINGS
+        print(f"claude: settings updated at {settings}")
+    if run_opencode:
+        print(f"opencode: plugin written to {results['opencode']['plugin_path']}")
+    return 0
+
+
+# --- selftest / version ---------------------------------------------------
+
+
+class _FailingProvider:
+    """Stand-in provider used by ``selftest`` to prove the fail-closed path."""
+
+    def classify(self, cwd: str, command: str) -> object:
+        raise RuntimeError("selftest: simulated provider outage")
+
+
+def _cmd_selftest(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    checks: list[tuple[str, bool]] = []
+
+    deny_result = classify_command("rm -rf /", cfg=cfg)
+    checks.append(
+        ("deny 'rm -rf /' -> deny/denylist",
+         deny_result.decision == "deny" and deny_result.source == "denylist")
+    )
+
+    allow_result = classify_command("git status", cfg=cfg)
+    checks.append(
+        ("allow 'git status' -> allow/allowlist",
+         allow_result.decision == "allow" and allow_result.source == "allowlist")
+    )
+
+    fallback = classify_command("docker run --rm alpine sh", cfg=cfg, provider=_FailingProvider())
+    checks.append(
+        ("provider outage -> deny/fallback",
+         fallback.decision == "deny" and fallback.source == "fallback")
+    )
+
+    for name, ok in checks:
+        print(f"{'PASS' if ok else 'FAIL'} {name}")
+    passed = sum(1 for _, ok in checks if ok)
+    print(f"{passed}/{len(checks)} checks passed")
+
+    key = api_key(cfg)
+    if key:
+        try:
+            from .provider import Provider
+
+            verdict = Provider(cfg.provider, key=key).classify(os.getcwd(), "git status")
+            print(f"provider: ok ({verdict.decision})")
+        except Exception as exc:  # noqa: BLE001 - reported, never fatal
+            print(f"provider: FAILED ({exc})")
+    else:
+        print("provider: skipped (no API key)")
+
+    return 0 if passed == len(checks) else 1
+
+
+def _cmd_version(args: argparse.Namespace) -> int:
+    print(f"bashboy {__version__} (python {platform.python_version()})")
+    return 0
+
+
+# --- parser ---------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bashboy",
+        description="Classify shell commands as allow or deny before an agent runs them.",
+    )
+    sub = parser.add_subparsers(dest="subcommand")
+
+    check = sub.add_parser("check", help="classify a command")
+    check.add_argument("--command", dest="command_text", default=None, help="command to classify")
+    check.add_argument("--cwd", default=os.getcwd(), help="working directory for the command")
+    check.add_argument("--json", action="store_true", help="emit one JSON verdict object")
+    check.add_argument(
+        "--claude-hook",
+        action="store_true",
+        help="read a Claude Code PreToolUse payload from stdin",
+    )
+    check.set_defaults(handler=_cmd_check)
+
+    install = sub.add_parser("install", help="install host integrations")
+    install.add_argument("--claude", action="store_true", help="install the Claude Code hook")
+    install.add_argument("--opencode", action="store_true", help="install the OpenCode plugin")
+    install.add_argument("--all", action="store_true", help="install both integrations")
+    install.add_argument("--dry-run", action="store_true", help="print what would be written")
+    install.add_argument("--from", dest="from_spec", default=None, help="uvx --from SPEC")
+    install.add_argument("--settings", default=None, help="Claude settings.json path")
+    install.add_argument("--config-dir", default=None, help="OpenCode config directory")
+    install.set_defaults(handler=_cmd_install)
+
+    config = sub.add_parser("config", help="inspect or create the config file")
+    config.add_argument("action", nargs="?", choices=["path", "show", "init"], default="path")
+    config.add_argument("--force", action="store_true", help="overwrite an existing config")
+    config.set_defaults(handler=_cmd_config)
+
+    selftest = sub.add_parser("selftest", help="run offline self-checks")
+    selftest.set_defaults(handler=_cmd_selftest)
+
+    version = sub.add_parser("version", help="print the version")
+    version.set_defaults(handler=_cmd_version)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help(sys.stderr)
+        return 2
+    try:
+        return int(handler(args))
+    except ConfigError as exc:
+        print(f"bashboy: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:  # pragma: no cover - interactive only
+        print("bashboy: interrupted", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

bashboy/config.py

@@ -0,0 +1,219 @@
+"""Configuration loading for BashBoy.
+
+The config file is optional: a missing file means "documented defaults". A file
+that exists but cannot be parsed is a hard error (exit 2 at the CLI), never a
+silent fallback to defaults -- silently loosening policy would be worse than
+refusing to run.
+
+The API key is never read from, or written to, the config file. It is resolved
+from the environment at call time.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_CONFIG_TOML = """\
+[provider]
+endpoint = "https://clocked.rezolve.ai/clocked/fill"
+api_key_env = "CLOCKED_API_KEY"
+timeout_ms = 4000
+
+[policy]
+fail_mode = "closed"   # closed | open
+denylist = true
+allowlist = true
+
+[integrations.claude]
+timeout_s = 15
+
+[integrations.opencode]
+timeout_ms = 15000
+"""
+
+FAIL_MODES = ("closed", "open")
+
+DEFAULT_ENDPOINT = "https://clocked.rezolve.ai/clocked/fill"
+DEFAULT_API_KEY_ENV = "CLOCKED_API_KEY"
+DEFAULT_TIMEOUT_MS = 4000
+DEFAULT_CLAUDE_TIMEOUT_S = 15
+DEFAULT_OPENCODE_TIMEOUT_MS = 15000
+
+
+class ConfigError(Exception):
+    """Raised when the configuration file or environment is unusable."""
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    endpoint: str = DEFAULT_ENDPOINT
+    api_key_env: str = DEFAULT_API_KEY_ENV
+    timeout_ms: int = DEFAULT_TIMEOUT_MS
+
+
+@dataclass(frozen=True)
+class PolicyConfig:
+    fail_mode: str = "closed"
+    denylist: bool = True
+    allowlist: bool = True
+
+
+@dataclass(frozen=True)
+class ClaudeIntegration:
+    timeout_s: int = DEFAULT_CLAUDE_TIMEOUT_S
+
+
+@dataclass(frozen=True)
+class OpencodeIntegration:
+    timeout_ms: int = DEFAULT_OPENCODE_TIMEOUT_MS
+
+
+@dataclass(frozen=True)
+class Config:
+    provider: ProviderConfig
+    policy: PolicyConfig
+    claude: ClaudeIntegration
+    opencode: OpencodeIntegration
+    path: Path
+
+
+def config_path() -> Path:
+    """Return the config file location: ``BASHBOY_CONFIG`` or ``~/.bashboy/config.toml``."""
+    override = os.environ.get("BASHBOY_CONFIG")
+    if override and override.strip():
+        return Path(override.strip()).expanduser()
+    return Path.home() / ".bashboy" / "config.toml"
+
+
+def _table(parent: dict, key: str, where: Path) -> dict:
+    value = parent.get(key)
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"{where}: [{key}] must be a table")
+    return value
+
+
+def _as_str(table: dict, key: str, default: str, where: Path) -> str:
+    if key not in table:
+        return default
+    value = table[key]
+    if not isinstance(value, str):
+        raise ConfigError(f"{where}: '{key}' must be a string")
+    return value
+
+
+def _as_int(table: dict, key: str, default: int, where: Path) -> int:
+    if key not in table:
+        return default
+    value = table[key]
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ConfigError(f"{where}: '{key}' must be an integer")
+    return int(value)
+
+
+def _as_bool(table: dict, key: str, default: bool, where: Path) -> bool:
+    if key not in table:
+        return default
+    value = table[key]
+    if not isinstance(value, bool):
+        raise ConfigError(f"{where}: '{key}' must be true or false")
+    return value
+
+
+def load_config(path: Path | None = None) -> Config:
+    """Load configuration, applying documented defaults and environment overrides."""
+    target = Path(path) if path is not None else config_path()
+
+    raw = b""
+    try:
+        raw = target.read_bytes()
+    except FileNotFoundError:
+        raw = b""
+    except OSError as exc:
+        raise ConfigError(f"cannot read {target}: {exc}") from exc
+
+    data: dict = {}
+    if raw:
+        try:
+            decoded = raw.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ConfigError(f"{target}: not valid UTF-8: {exc}") from exc
+        try:
+            data = tomllib.loads(decoded)
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigError(f"{target}: invalid TOML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{target}: top-level value must be a table")
+
+    provider_tbl = _table(data, "provider", target)
+    policy_tbl = _table(data, "policy", target)
+    integrations_tbl = _table(data, "integrations", target)
+    claude_tbl = _table(integrations_tbl, "claude", target)
+    opencode_tbl = _table(integrations_tbl, "opencode", target)
+
+    provider = ProviderConfig(
+        endpoint=_as_str(provider_tbl, "endpoint", DEFAULT_ENDPOINT, target),
+        api_key_env=_as_str(provider_tbl, "api_key_env", DEFAULT_API_KEY_ENV, target),
+        timeout_ms=_as_int(provider_tbl, "timeout_ms", DEFAULT_TIMEOUT_MS, target),
+    )
+    policy = PolicyConfig(
+        fail_mode=_as_str(policy_tbl, "fail_mode", "closed", target),
+        denylist=_as_bool(policy_tbl, "denylist", True, target),
+        allowlist=_as_bool(policy_tbl, "allowlist", True, target),
+    )
+    claude = ClaudeIntegration(
+        timeout_s=_as_int(claude_tbl, "timeout_s", DEFAULT_CLAUDE_TIMEOUT_S, target),
+    )
+    opencode = OpencodeIntegration(
+        timeout_ms=_as_int(opencode_tbl, "timeout_ms", DEFAULT_OPENCODE_TIMEOUT_MS, target),
+    )
+
+    env_endpoint = os.environ.get("BASHBOY_ENDPOINT")
+    if env_endpoint and env_endpoint.strip():
+        provider = ProviderConfig(
+            endpoint=env_endpoint.strip(),
+            api_key_env=provider.api_key_env,
+            timeout_ms=provider.timeout_ms,
+        )
+
+    env_key_env = os.environ.get("BASHBOY_API_KEY_ENV")
+    if env_key_env and env_key_env.strip():
+        provider = ProviderConfig(
+            endpoint=provider.endpoint,
+            api_key_env=env_key_env.strip(),
+            timeout_ms=provider.timeout_ms,
+        )
+
+    env_fail_mode = os.environ.get("BASHBOY_FAIL_MODE")
+    if env_fail_mode and env_fail_mode.strip():
+        policy = PolicyConfig(
+            fail_mode=env_fail_mode.strip(),
+            denylist=policy.denylist,
+            allowlist=policy.allowlist,
+        )
+
+    if policy.fail_mode not in FAIL_MODES:
+        raise ConfigError(
+            f"{target}: fail_mode must be one of {', '.join(FAIL_MODES)} (got {policy.fail_mode!r})"
+        )
+
+    return Config(
+        provider=provider,
+        policy=policy,
+        claude=claude,
+        opencode=opencode,
+        path=target,
+    )
+
+
+def api_key(cfg: Config) -> str | None:
+    """Return the API key from the environment named by the config, or ``None``."""
+    raw = os.environ.get(cfg.provider.api_key_env)
+    if raw is None:
+        return None
+    raw = raw.strip()
+    return raw or None

bashboy/hooks/__init__.py

@@ -0,0 +1 @@
+"""Host adapters. Kept as a package so imports stay explicit and lazy."""