sshfc 0.1.0__py3-none-any.whl

sshfc/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright (C) 2026 Stephen T. Jibson.
+#  SPDX-License-Identifier: MIT
+
+"""SSH Force Command validator."""

sshfc/cli.py

@@ -0,0 +1,160 @@
+#  Copyright (C) 2026 Stephen T. Jibson.
+#  SPDX-License-Identifier: MIT
+
+"""CLI entrypoint for sshfc.
+
+sshfc's own arguments come from ``command="..."`` in authorized_keys (or ``ForceCommand`` in sshd_config), so they
+are controlled by the admin, never by the SSH user. The SSH user's requested command comes from
+``SSH_ORIGINAL_COMMAND``, or from ``-c`` for local testing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import sys
+import time
+from importlib import resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sshfc.core.audit import AuditLog
+from sshfc.core.check import check_policy
+from sshfc.core.config import DEFAULT_PATH, ConfigError, load_policy
+from sshfc.core.executor import execute
+from sshfc.core.parser import InvalidCommandError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+# Shown to the SSH user when the policy can't be loaded; the details go to the audit log only.
+_CONFIG_ERROR_MSG = "SSH command rejected: sshfc is misconfigured; contact the administrator"
+
+
+def _parse_args(args: Sequence[str] | None) -> argparse.Namespace:
+    """Parse sshfc's own arguments."""
+    parser = argparse.ArgumentParser(
+        prog="sshfc",
+        description="Run an SSH user's requested command only if it is in the allowed command set.",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=DEFAULT_PATH,
+        metavar="PATH",
+        help=f"Policy file, or directory of *.toml policy files (default: {DEFAULT_PATH}).",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Print the command that would run instead of running it."
+    )
+    parser.add_argument(
+        "-c",
+        dest="command",
+        metavar="COMMAND",
+        help="Validate COMMAND instead of $SSH_ORIGINAL_COMMAND (for local testing). Quote it as one string.",
+    )
+    parser.add_argument(
+        "--key-id",
+        metavar="LABEL",
+        help="Label included in audit records, e.g. to tell apart keys that share an account.",
+    )
+    parser.add_argument(
+        "--insecure-config",
+        action="store_true",
+        help="Skip the policy ownership checks (only with --dry-run or --check, e.g. to try a policy in a checkout).",
+    )
+    modes = parser.add_mutually_exclusive_group()
+    modes.add_argument(
+        "--check",
+        action="store_true",
+        help="Check the policy and run every command's accept/reject examples, then exit.",
+    )
+    modes.add_argument(
+        "--samples",
+        nargs="?",
+        const="",
+        metavar="NAME",
+        help="List the sample policy files shipped with sshfc, or print one, then exit.",
+    )
+    options = parser.parse_args(args)
+    if options.insecure_config and not (options.dry_run or options.check):
+        parser.error("--insecure-config requires --dry-run or --check")
+    return options
+
+
+def main(args: Sequence[str] | None = None, environ: Mapping[str, str] | None = None) -> None:
+    """Validate the requested command, then run it (or, with --dry-run, show what would run)."""
+    options = _parse_args(args)
+    if options.samples is not None:
+        raise SystemExit(_samples(options.samples))
+    if options.check:
+        raise SystemExit(_check(options.config, check_owners=not options.insecure_config))
+
+    environ = os.environ if environ is None else environ
+    audit = AuditLog(environ, key_id=options.key_id)
+
+    # No command at all (e.g. an interactive login) is rejected like any other invalid command, listing the choices.
+    if options.command is not None:
+        source, cmd_str = "-c", options.command
+    elif "SSH_ORIGINAL_COMMAND" in environ:
+        source, cmd_str = "SSH_ORIGINAL_COMMAND", environ["SSH_ORIGINAL_COMMAND"]
+    else:
+        source, cmd_str = "none", ""
+
+    # Fail closed: if the policy can't be loaded, reject everything.
+    try:
+        policy = load_policy(options.config, check_owners=not options.insecure_config)
+    except ConfigError as e:
+        audit.config_error(source=source, command=cmd_str, error=str(e), dry_run=options.dry_run)
+        raise SystemExit(_CONFIG_ERROR_MSG) from e
+
+    try:
+        argv, command = policy.root.parse_command(cmd_str)
+    except InvalidCommandError as e:
+        audit.rejected(source=source, command=cmd_str, reason=str(e), dry_run=options.dry_run)
+        raise SystemExit(str(e)) from e
+
+    audit.accepted(source=source, command=cmd_str, argv=argv, policy=command.source, dry_run=options.dry_run)
+    if options.dry_run:
+        print(f"Would run: {shlex.join(argv)}")
+        return
+
+    start = time.monotonic()
+    status = execute(argv)
+    audit.exited(argv=argv, status=status, duration=time.monotonic() - start)
+    raise SystemExit(status)
+
+
+def _check(path: Path, *, check_owners: bool) -> int:
+    """Check a policy, print the results, and return an exit status."""
+    result = check_policy(path, check_owners=check_owners)
+    for warning in result.warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    for error in result.errors:
+        print(f"error: {error}", file=sys.stderr)
+    if result.errors:
+        return 1
+    assert result.policy is not None  # noqa: S101 -- no errors means the policy loaded.
+    names = ", ".join(f.name for f in result.policy.files)
+    print(f"OK: {path} ({len(result.policy.files)} file(s): {names})")
+    return 0
+
+
+def _samples(name: str) -> int:
+    """List the sample policy files, or print one; return an exit status."""
+    samples = resources.files("sshfc") / "samples"
+    files = sorted((f for f in samples.iterdir() if f.name.endswith(".toml")), key=lambda f: f.name)
+    if not name:
+        print(f"Sample policy files in {samples}:")
+        for file in files:
+            first_line = file.read_text().partition("\n")[0].removeprefix("#").strip()
+            print(f"  {file.name:24} {first_line}")
+        print("\nCopy or symlink the ones you want into your policy directory, then run: sshfc --check")
+        return 0
+    for file in files:
+        if name in {file.name, file.name.removesuffix(".toml")}:
+            print(file.read_text(), end="")
+            return 0
+    print(f"sshfc: no sample named {name!r}; run 'sshfc --samples' to list them", file=sys.stderr)
+    return 1

sshfc/core/__init__.py

@@ -0,0 +1,30 @@
+#  Copyright (C) 2026 Stephen T. Jibson.
+#  SPDX-License-Identifier: MIT
+
+"""sshfc infrastructure.
+
+Policies are normally TOML files (see ``sshfc.core.config``); this package's top level is also a Python API for
+building and checking command specs directly.
+"""
+
+from sshfc.core.config import ConfigError, Policy, load_policy
+from sshfc.core.parser import CommandRoot, InvalidCommandError, SpecError
+from sshfc.core.spec import Command, Flag, Option, Positional, Validator
+from sshfc.core.validators import CONTAINER_NAME, GoTemplateFormat, Pattern
+
+__all__ = [
+    "CONTAINER_NAME",
+    "Command",
+    "CommandRoot",
+    "ConfigError",
+    "Flag",
+    "GoTemplateFormat",
+    "InvalidCommandError",
+    "Option",
+    "Pattern",
+    "Policy",
+    "Positional",
+    "SpecError",
+    "Validator",
+    "load_policy",
+]

sshfc/core/audit.py

@@ -0,0 +1,77 @@
+#  Copyright (C) 2026 Stephen T. Jibson.
+#  SPDX-License-Identifier: MIT
+
+"""Audit log of accepted and rejected commands.
+
+Each record is one JSON line sent to syslog (facility authpriv where available, else auth; ident ``sshfc``). The
+command string is SSH-user input, so JSON encoding with ASCII escaping is also what prevents log injection: control
+characters and newlines can't forge or split records.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pwd
+import syslog
+from typing import TYPE_CHECKING, Any, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+#: Receives (syslog priority, message).
+type Emitter = Callable[[int, str], None]
+
+_FACILITY: Final = getattr(syslog, "LOG_AUTHPRIV", syslog.LOG_AUTH)
+
+
+def _syslog_emit(priority: int, message: str) -> None:
+    """Send a record to syslog."""
+    syslog.openlog("sshfc", syslog.LOG_PID, _FACILITY)
+    syslog.syslog(priority, message)
+
+
+class AuditLog:
+    """Writes audit records for one sshfc invocation."""
+
+    def __init__(self, environ: Mapping[str, str], key_id: str | None = None, emit: Emitter | None = None) -> None:
+        """Initialize with the context common to every record of this invocation."""
+        self._emit = _syslog_emit if emit is None else emit
+        client = environ.get("SSH_CONNECTION", "").split()  # "client_ip client_port server_ip server_port"
+        self._context: dict[str, Any] = {
+            "user": pwd.getpwuid(os.getuid()).pw_name,
+            "key_id": key_id,
+            "client": " ".join(client[:2]) or None,
+        }
+
+    def rejected(self, *, source: str, command: str, reason: str, dry_run: bool) -> None:
+        """Record a rejected command."""
+        self._log(syslog.LOG_WARNING, "rejected", source=source, command=command, reason=reason, dry_run=dry_run)
+
+    def accepted(self, *, source: str, command: str, argv: Sequence[str], policy: str | None, dry_run: bool) -> None:
+        """Record an accepted command (before it runs, so there's a record even if it never finishes).
+
+        ``policy`` names the policy file(s) that define the matched command.
+        """
+        self._log(
+            syslog.LOG_INFO,
+            "accepted",
+            source=source,
+            command=command,
+            argv=list(argv),
+            policy=policy,
+            dry_run=dry_run,
+        )
+
+    def config_error(self, *, source: str, command: str, error: str, dry_run: bool) -> None:
+        """Record that the policy couldn't be loaded, so the command was rejected without being checked."""
+        self._log(syslog.LOG_ERR, "config_error", source=source, command=command, error=error, dry_run=dry_run)
+
+    def exited(self, *, argv: Sequence[str], status: int, duration: float) -> None:
+        """Record an executed command's exit status and how long it ran."""
+        self._log(syslog.LOG_INFO, "exited", argv=list(argv), status=status, duration_s=round(duration, 3))
+
+    def _log(self, priority: int, event: str, **fields: Any) -> None:  # noqa: ANN401
+        """Emit one record."""
+        record = {"event": event, **self._context, **fields}
+        self._emit(priority, json.dumps(record, ensure_ascii=True, separators=(",", ":")))

sshfc/core/check.py

@@ -0,0 +1,104 @@
+#  Copyright (C) 2026 Stephen T. Jibson.
+#  SPDX-License-Identifier: MIT
+
+"""Check a policy: load it and run every command's accept/reject examples against the merged result."""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from sshfc.core.config import ConfigError, check_ownership, load_policy, policy_files
+from sshfc.core.parser import InvalidCommandError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+    from pathlib import Path
+
+    from sshfc.core.config import Policy
+    from sshfc.core.spec import Command
+
+
+@dataclass
+class CheckResult:
+    """Problems found by check_policy()."""
+
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    policy: Policy | None = None
+
+
+def check_policy(path: Path, *, check_owners: bool = True) -> CheckResult:
+    """Check the policy at path, collecting every problem rather than stopping at the first."""
+    result = CheckResult()
+    try:
+        files = policy_files(path)
+    except ConfigError as e:
+        result.errors.append(str(e))
+        return result
+    if check_owners:
+        for checked in [path, *files]:
+            try:
+                check_ownership(checked)
+            except ConfigError as e:
+                result.errors.append(str(e))
+    try:
+        result.policy = load_policy(path, check_owners=False)
+    except ConfigError as e:
+        result.errors.append(str(e))
+        return result
+
+    if not result.policy.commands:
+        result.warnings.append(f"{path}: no commands defined; every command will be rejected")
+    result.errors.extend(run_examples(result.policy))
+    return result
+
+
+def run_examples(policy: Policy) -> list[str]:
+    """Run every accept/reject example against the whole policy; return a message for each failure."""
+    failures: list[str] = []
+    for where, command in _walk(policy.commands):
+        top = where.split(" ", 1)[0]
+        prefix = f"{command.source}: commands.{where!r}"
+        for example in command.accept:
+            cmd_str, expected = example if isinstance(example, tuple) else (example, None)
+            if not _starts_with(cmd_str, top):
+                failures.append(f"{prefix}: accept example {cmd_str!r} must be a full command line from {top!r}")
+                continue
+            try:
+                argv = policy.root.parse(cmd_str)
+            except InvalidCommandError as e:
+                failures.append(f"{prefix}: accept example {cmd_str!r} was rejected: {e}")
+                continue
+            if expected is not None and shlex.join(argv) != expected:
+                failures.append(
+                    f"{prefix}: accept example {cmd_str!r} would run {shlex.join(argv)!r}, expected {expected!r}"
+                )
+        for cmd_str in command.reject:
+            if not _starts_with(cmd_str, top):
+                failures.append(f"{prefix}: reject example {cmd_str!r} must be a full command line from {top!r}")
+                continue
+            try:
+                argv = policy.root.parse(cmd_str)
+            except InvalidCommandError:
+                continue
+            failures.append(f"{prefix}: reject example {cmd_str!r} was accepted (would run {shlex.join(argv)!r})")
+    return failures
+
+
+def _starts_with(cmd_str: str, top: str) -> bool:
+    """Return whether a command line starts with the given top-level command name."""
+    try:
+        words = shlex.split(cmd_str)
+    except ValueError:
+        return cmd_str.split(" ", 1)[0] == top
+    return bool(words) and words[0] == top
+
+
+def _walk(commands: Sequence[Command], path: str = "") -> Iterator[tuple[str, Command]]:
+    """Yield (path, command) for every command in the tree."""
+    for command in commands:
+        here = f"{path} {command.name}".strip()
+        yield here, command
+        yield from _walk(command.subcommands, here)