solidx-sysadm 0.1.0b1__py3-none-any.whl

bash_minus_minus/__init__.py

@@ -0,0 +1,17 @@
+"""Deterministic inspection policy and execution gateway."""
+
+from .policy import Decision, classify as classify_with_policy
+from .remote_policy import PolicyError, load_policy
+from .runner import execute
+
+
+def classify(command: str) -> Decision:
+    """Classify against the current managed policy, refreshing it when due.
+
+    Raises PolicyError if configured central policy cannot be loaded.
+    Use policy.classify for pure, explicitly supplied policy classification.
+    """
+    return classify_with_policy(command, policy=load_policy().policy)
+
+
+__all__ = ["Decision", "PolicyError", "classify", "execute", "load_policy"]

bash_minus_minus/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

bash_minus_minus/cli.py

@@ -0,0 +1,124 @@
+import argparse
+from dataclasses import asdict
+import json
+import shlex
+import sys
+
+from .policy import classify
+from .remote_policy import PolicyError, PolicyStore
+from .runner import execute
+from .suggestions import external_instruction
+from .workflows import bacpac_plan, render_plan
+
+
+def _terminal_safe(text: str) -> str:
+    # Retain newlines; escape terminal controls, including ANSI/OSC sequences.
+    return "".join(c if c == "\n" or c.isprintable() else ascii(c)[1:-1] for c in text)
+
+
+def show_plan(env_file=None, output_directory=None, *, as_json=False):
+    plan = bacpac_plan(env_file, output_directory)
+    print(json.dumps(plan.as_dict()) if as_json else _terminal_safe(render_plan(plan)))
+    return 0
+
+
+def run_command(command, *, as_json=False):
+    result = execute(command)
+    suggestion = None
+    if result.decision.status == "prohibited":
+        suggestion = external_instruction(command)
+    if result.policy_warning:
+        print(f"bash--: {_terminal_safe(result.policy_warning)}", file=sys.stderr)
+    if as_json:
+        data = asdict(result)
+        if suggestion:
+            data["external_terminal_instruction"] = suggestion
+            data["executed"] = False
+        print(json.dumps(data))
+    else:
+        if result.output:
+            print(_terminal_safe(result.output), end="")
+        if result.error:
+            print(f"bash--: {_terminal_safe(result.error)}", file=sys.stderr)
+        if suggestion:
+            print(_terminal_safe(suggestion))
+        if result.stopped:
+            print(f"bash--: stopped: {result.stopped}", file=sys.stderr)
+    return result.exit_code if 0 <= result.exit_code <= 255 else 1
+
+
+def _main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Fail-closed Linux and macOS inspection command gateway.")
+    parser.add_argument("command", nargs=argparse.REMAINDER, help="Quoted command or command arguments, e.g. ls -litr")
+    actions = parser.add_mutually_exclusive_group()
+    actions.add_argument("--check", action="store_true", help="Classify without executing")
+    parser.add_argument("--json", action="store_true", help="Return machine-readable JSON")
+    actions.add_argument("--list", action="store_true", help="List every approved command form")
+    actions.add_argument("--sync-policy", action="store_true", help="Fetch policy immediately")
+    actions.add_argument("--policy-status", action="store_true", help="Show effective policy metadata")
+    actions.add_argument("--repl", action="store_true", help="Start a policy-gated interactive session")
+    actions.add_argument("--plan", choices=["sqlserver-bacpac"], help="Print workflow instructions without executing them")
+    parser.add_argument("--env-file", help="Application .env used for non-secret database metadata only")
+    parser.add_argument("--output-dir", help="Suggested BACPAC output directory; never created by the planner")
+    parser.add_argument("--policy-url", help="Persist an HTTPS manifest URL and fetch its policy")
+    args = parser.parse_args(argv)
+    tokens = args.command
+    if tokens and tokens[0] == "--":
+        tokens = tokens[1:]
+    args.command = tokens[0] if len(tokens) == 1 else shlex.join(tokens) if tokens else None
+    if args.command is not None and (args.repl or args.plan):
+        parser.error("--repl and --plan do not accept a command")
+    if args.plan:
+        return show_plan(args.env_file, args.output_dir, as_json=args.json)
+    if args.repl or (args.command is None and not any((args.list, args.check, args.sync_policy, args.policy_status, args.policy_url))):
+        from .session import repl
+        return repl(env_file=args.env_file, output_directory=args.output_dir, as_json=args.json)
+    if args.command is not None and (args.list or args.sync_policy or args.policy_status):
+        parser.error("this action does not accept a command")
+    store = PolicyStore()
+    if args.policy_url:
+        store.configure(args.policy_url)
+    active = None
+    if args.list or args.check or args.sync_policy or args.policy_status or args.policy_url:
+        active = store.load(force=args.sync_policy or bool(args.policy_url))
+        if active.warning:
+            print(f"bash--: {_terminal_safe(active.warning)}", file=sys.stderr)
+    if args.sync_policy or args.policy_status or (args.policy_url and args.command is None and not args.list):
+        data = {"policy_version": active.policy.version, "source": active.source,
+                "revision": active.revision, "expires_at": active.expires_at,
+                "operating_system": active.policy.operating_system,
+                "supported_os": active.policy.supported_os,
+                "warning": active.warning}
+        print(json.dumps(data) if args.json else "\n".join(f"{key}: {value}" for key, value in data.items()))
+        return 0
+    if args.list:
+        forms = [" ".join((name, *options)) for name, variants in active.policy.forms.items()
+                 if name not in active.policy.prohibited for options in variants]
+        print(json.dumps({"policy_version": active.policy.version,
+                          "operating_system": active.policy.operating_system,
+                          "supported_os": active.policy.supported_os,
+                          "forms": forms}) if args.json else "\n".join(forms))
+        return 0
+    if args.command is None:
+        parser.error("provide a command or use --list")
+    if args.check:
+        decision = classify(args.command, policy=active.policy)
+        print(json.dumps(asdict(decision)) if args.json else f"{decision.status}: {decision.reason}")
+        return 0 if decision.allowed else 2
+    return run_command(args.command, as_json=args.json)
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        return _main(argv)
+    except (PolicyError, OSError, ValueError) as exc:
+        error = {"error": str(exc), "exit_code": 3}
+        if "--json" in (sys.argv[1:] if argv is None else argv):
+            print(json.dumps(error))
+        else:
+            print(f"bash--: {_terminal_safe(str(exc))}", file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bash_minus_minus/command_forms.py

@@ -0,0 +1,140 @@
+"""Reviewed operand grammars shared by Linux and macOS command profiles."""
+
+import re
+import shlex
+
+
+def _path(value):
+    # No stdin marker, option operands, expansions, or wildcard paths.
+    return (bool(value) and not value.startswith(("-", "+"))
+            and not any(c in value for c in "$`\\;|&<>(){}[]*?!~#"))
+
+
+def _flags(value, characters):
+    return (value.startswith("-") and 1 < len(value) <= 12
+            and all(c in characters for c in value[1:]))
+
+
+def _sed_print(value):
+    address = r"(?:[1-9][0-9]{0,5}|\$)"
+    return bool(re.fullmatch(rf"{address}(?:,{address})?p|/[^/\\]{{1,256}}/p", value))
+
+
+def _sed_substitute(value):
+    # Slash delimiter only. No backslashes, extra commands, or e/w flags.
+    return bool(re.fullmatch(r"s/[^/\\]{1,256}/[^/\\]{0,256}/g?", value))
+
+
+VALIDATORS = {
+    "<container>": lambda value: bool(re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}", value)),
+    "<files>": _path,
+    "<paths>": _path,
+    "<directory>": _path,
+    "<count>": lambda value: value.isascii() and value.isdecimal() and 1 <= int(value) <= 100000,
+    "<depth>": lambda value: value.isascii() and value.isdecimal() and 0 <= int(value) <= 32,
+    "<legacy-count>": lambda value: bool(re.fullmatch(r"-[1-9][0-9]{0,4}", value)),
+    "<pattern>": lambda value: 1 <= len(value) <= 256 and not value.startswith("-"),
+    "<glob>": lambda value: 1 <= len(value) <= 256,
+    "<ls-options>": lambda value: _flags(value, "laAhitrSdF"),
+    "<cat-options>": lambda value: _flags(value, "nbsvet"),
+    "<grep-options>": lambda value: _flags(value, "ivnHhclwoEFx"),
+    "<sed-print>": _sed_print,
+    "<sed-substitute>": _sed_substitute,
+}
+REPEATS = {"<files>": 16, "<paths>": 16, "<ls-options>": 8,
+           "<cat-options>": 8, "<grep-options>": 8}
+
+
+def match_arguments(arguments, form):
+    """Return (placeholder, value) bindings, or None when the template fails."""
+    def match(index, offset):
+        if index == len(form):
+            return () if offset == len(arguments) else None
+        atom = form[index]
+        if atom not in VALIDATORS:
+            if offset < len(arguments) and arguments[offset] == atom:
+                return match(index + 1, offset + 1)
+            return None
+        bindings = []
+        for count in range(1, min(REPEATS.get(atom, 1), len(arguments) - offset) + 1):
+            value = arguments[offset + count - 1]
+            if not VALIDATORS[atom](value):
+                break
+            bindings.append((atom, value))
+            remainder = match(index + 1, offset + count)
+            if remainder is not None:
+                return (*bindings, *remainder)
+        return None
+
+    return match(0, 0)
+
+
+def argument_bindings(arguments, forms):
+    for form in forms:
+        bindings = match_arguments(arguments, form)
+        if bindings is not None:
+            return bindings
+    return None
+
+
+def has_unquoted_shell_syntax(command):
+    """Allow metacharacters only as quoted data, subsequently grammar-checked."""
+    quote = None
+    escaped = False
+    for character in command:
+        if escaped:
+            escaped = False
+        elif quote:
+            if character == quote:
+                quote = None
+            elif quote == '"' and character == "\\":
+                escaped = True
+        elif character in "'\"":
+            quote = character
+        elif character in "$`\\;|&<>(){}[]*?!~#":
+            return True
+    return False
+
+
+COMMON_FORMS = {
+    "pwd": ((),),
+    "pm2": (("list",),),
+    "screen": (("-ls",),),
+    "sort": (("-h",),),
+    "docker": (("--version",), ("version",), ("ps",), ("ps", "-a"),
+               ("images",), ("volume", "ls"),
+               ("inspect", "--format", "{{.State.Status}}", "<container>")),
+    "dotnet": (("--version",), ("--list-sdks",), ("--list-runtimes",),
+               ("tool", "list", "--global")),
+    "sqlpackage": (("/Version",),),
+    "ls": ((), ("<paths>",), ("<ls-options>",), ("<ls-options>", "<paths>")),
+    "cat": (("<files>",), ("<cat-options>", "<files>")),
+    "head": (("<files>",), ("-n", "<count>", "<files>"),
+             ("-c", "<count>", "<files>"), ("<legacy-count>", "<files>")),
+    "tail": (("<files>",), ("-n", "<count>", "<files>"),
+             ("-c", "<count>", "<files>"), ("<legacy-count>", "<files>")),
+    "grep": (("<pattern>", "<files>"), ("<grep-options>", "<pattern>", "<files>")),
+    "sed": (("-n", "<sed-print>", "<files>"), ("<sed-substitute>", "<files>")),
+}
+COMMON_FORMS["find"] = tuple(
+    ("<directory>", *depth, *kind, *name, *output)
+    for depth in ((), ("-maxdepth", "<depth>"))
+    for kind in ((), ("-type", "f"), ("-type", "d"))
+    for name in ((), ("-name", "<glob>"), ("-iname", "<glob>"))
+    for output in ((), ("-print",))
+)
+
+def parse_invocation(command):
+    """Parse one literal executable invocation; never evaluate shell syntax."""
+    if (not isinstance(command, str) or not command.strip() or len(command) > 4096
+            or any(ord(character) < 32 or ord(character) == 127 for character in command)
+            or has_unquoted_shell_syntax(command)):
+        return None
+    try:
+        argv = tuple(shlex.split(command, comments=False, posix=True))
+    except ValueError:
+        return None
+    if (not argv or not argv[0] or len(argv) > 64
+            or any(not part or len(part) > 1024 for part in argv)):
+        return None
+    return argv

bash_minus_minus/policy.py

@@ -0,0 +1,103 @@
+"""A deliberately small command language, not a Bash parser."""
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Mapping
+import shlex
+import sys
+
+from .command_forms import COMMON_FORMS, argument_bindings, has_unquoted_shell_syntax
+from .suggestions import safe_argv
+
+POLICY_VERSION = "3"
+MAX_COMMAND_LENGTH = 4096
+
+# Each complete argument tuple is reviewed independently. No arbitrary operands.
+FORMS = {
+    "uptime": ((), ("-p",), ("-s",)),
+    "du": (("-xhd1", "<directory>"), ("-sh", "<directory>")),
+    "free": ((), ("-h",), ("-m",), ("-b",)),
+    "df": ((), ("-h",), ("-i",), ("-T",), ("-hT",)),
+    "ps": ((), ("aux",), ("-ef",)),
+    "uname": ((), ("-a",), ("-r",), ("-m",)),
+    **COMMON_FORMS,
+}
+MACOS_FORMS = {
+    "uptime": ((),),
+    "du": (("-h", "-d", "1", "-x", "<directory>"), ("-sh", "<directory>")),
+    "df": ((), ("-h",), ("-i",)),
+    "uname": ((), ("-a",), ("-r",), ("-m",)),
+    **COMMON_FORMS,
+}
+OS_FORMS = {"linux": FORMS, "macos": MACOS_FORMS}
+
+
+def operating_system() -> str:
+    return "macos" if sys.platform == "darwin" else sys.platform
+# Any executable may be requested and explicitly approved. Central manifest
+# denials remain authoritative; there is no client-side executable catalog.
+PROHIBITED = frozenset()
+
+
+@dataclass(frozen=True)
+class Policy:
+    version: str
+    forms: Mapping[str, tuple[tuple[str, ...], ...]]
+    prohibited: frozenset[str]
+    supported_os: tuple[str, ...] = ("linux",)
+    operating_system: str | None = None
+
+
+def builtin_policy() -> Policy:
+    system = operating_system()
+    return Policy(POLICY_VERSION, MappingProxyType(OS_FORMS.get(system, {})),
+                  PROHIBITED, tuple(OS_FORMS), system)
+
+
+BUILTIN_POLICY = builtin_policy()
+
+
+@dataclass(frozen=True)
+class Decision:
+    status: str
+    code: str
+    reason: str
+    argv: tuple[str, ...] = ()
+    policy_version: str = POLICY_VERSION
+
+    @property
+    def allowed(self) -> bool:
+        return self.status == "allowed"
+
+
+def classify(command: str, *, policy: Policy = BUILTIN_POLICY) -> Decision:
+    """Pure classification. Never reads the OS, expands input, or runs a command."""
+    def decision(*args):
+        if len(args) > 3 and args[0] != "allowed":
+            args = (*args[:3], safe_argv(args[3]))
+        return Decision(*args, policy_version=policy.version)
+
+    if policy.operating_system is not None and policy.operating_system not in policy.supported_os:
+        return decision("unsupported", "unsupported_os", "Policy does not support this operating system.")
+    if not isinstance(command, str) or not command.strip():
+        return decision("unsupported", "empty_input", "Provide one inspection command.")
+    if len(command) > MAX_COMMAND_LENGTH:
+        return decision("unsupported", "input_limit", "Command exceeds 4096 characters.")
+    # Metacharacters are permitted only as quoted, grammar-checked operands.
+    if any(ord(c) < 32 or ord(c) == 127 for c in command):
+        return decision("unsupported", "character", "Control characters are not supported.")
+    if has_unquoted_shell_syntax(command):
+        return decision("unsupported", "shell_syntax", "Shell operators and expansions are unsupported.")
+    try:
+        argv = tuple(shlex.split(command, comments=False, posix=True))
+    except ValueError:
+        return decision("unsupported", "quoting", "Input contains incomplete quoting.")
+    if not argv or not argv[0]:
+        return decision("unsupported", "empty_input", "Provide one inspection command.")
+    if argv[0].rsplit("/", 1)[-1] in policy.prohibited:
+        return decision("prohibited", "prohibited_command", "This executable is prohibited.", argv)
+    if argv[0] not in policy.forms:
+        return decision("unsupported", "unknown_command", "Executable has no inspection policy.", argv)
+    if argument_bindings(argv[1:], policy.forms[argv[0]]) is None:
+        return decision("unsupported", "arguments", "Arguments do not match an approved command form.", argv)
+    return decision("allowed", "inspection", "Approved inspection command form.", argv)