bash-classify 0.1.0__py3-none-any.whl

bash_classify/__init__.py

@@ -0,0 +1,14 @@
+"""bash-classify: Classify bash expressions by their side-effect risk level."""
+
+from bash_classify.classifier import classify_expression
+from bash_classify.database import CommandDatabase, load_database
+from bash_classify.models import Classification, CommandResult, ExpressionResult
+
+__all__ = [
+    "classify_expression",
+    "load_database",
+    "CommandDatabase",
+    "Classification",
+    "ExpressionResult",
+    "CommandResult",
+]

bash_classify/__main__.py

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

bash_classify/classifier.py

@@ -0,0 +1,244 @@
+"""Top-level classifier orchestrating parsing, matching, and classification."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from .database import load_database
+from .matcher import match_command
+from .models import (
+    Classification,
+    CommandDef,
+    CommandResult,
+    ExpressionResult,
+    InnerCommandResult,
+    Redirect,
+)
+from .parser import parse_expression
+
+_SYSTEM_DIRS = (
+    "/etc",
+    "/lib",
+    "/lib64",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/boot",
+    "/sys",
+    "/proc",
+    "/run",
+    "/srv",
+    "/root",
+    "/opt",
+    "/var",
+    "/dev",
+)
+_SAFE_PREFIXES = (
+    "/tmp",
+    "/var/tmp",
+    "/home",
+    "/dev/null",
+    "/dev/stdin",
+    "/dev/stdout",
+    "/dev/stderr",
+    "/dev/fd",
+    "/dev/tcp",
+    "/dev/udp",
+)
+
+
+def _is_system_path(path: str) -> bool:
+    """Check if a path is a system directory that should trigger DANGEROUS when written to."""
+    if not path.startswith("/"):
+        return False
+    # Check safe prefixes first (more specific)
+    for safe in _SAFE_PREFIXES:
+        if path == safe or path.startswith(safe + "/"):
+            return False
+    # Check system dirs
+    return any(path == sysdir or path.startswith(sysdir + "/") for sysdir in _SYSTEM_DIRS)
+
+
+def classify_expression(
+    expression: str,
+    database: Mapping[str, CommandDef] | None = None,
+) -> ExpressionResult:
+    """Classify a bash expression.
+
+    Parses the expression, matches each command against the database,
+    and returns a composite classification result.
+
+    Args:
+        expression: A bash expression string.
+        database: Optional pre-loaded command database. If None, loads the default.
+
+    Returns:
+        An ExpressionResult with the overall classification and per-command details.
+    """
+    # Step 1: Load database if not provided
+    if database is None:
+        database = load_database()
+
+    # Step 2: Parse the expression
+    invocations, parse_warnings = parse_expression(expression)
+
+    # Step 3: Match each command invocation
+    command_results: list[CommandResult] = []
+    all_redirects: list[Redirect] = []
+
+    for invocation in invocations:
+        # Check for variable expansion in command position
+        if invocation.argv and invocation.argv[0].startswith("$"):
+            result = CommandResult(
+                command=[invocation.argv[0]],
+                argv=list(invocation.argv),
+                classification=Classification.DANGEROUS,
+                matched_rule=None,
+                inner_commands=[],
+                classification_reason="variable expansion in command position",
+            )
+        else:
+            result = match_command(invocation, database)
+
+        # Step 4: Apply redirect classification
+        for redirect in invocation.redirects:
+            if redirect.affects_classification:
+                elevated = Classification.max_severity(result.classification, Classification.WRITE)
+                if elevated != result.classification:
+                    result.classification = elevated
+                    result.classification_reason = (
+                        f"{result.classification_reason}; elevated by output redirect"
+                        if result.classification_reason
+                        else "elevated by output redirect"
+                    )
+            # /dev/tcp and /dev/udp redirects are network access -> DANGEROUS
+            if redirect.target.startswith("/dev/tcp/") or redirect.target.startswith("/dev/udp/"):
+                elevated = Classification.max_severity(result.classification, Classification.DANGEROUS)
+                if elevated != result.classification:
+                    result.classification = elevated
+                    result.classification_reason = "elevated to DANGEROUS: /dev/tcp or /dev/udp access detected"
+
+        # Step 4b: Check for /dev/tcp and /dev/udp in command arguments
+        for arg in invocation.argv:
+            if arg.startswith("/dev/tcp/") or arg.startswith("/dev/udp/"):
+                elevated = Classification.max_severity(result.classification, Classification.DANGEROUS)
+                if elevated != result.classification:
+                    result.classification = elevated
+                    result.classification_reason = "elevated to DANGEROUS: /dev/tcp or /dev/udp access detected"
+
+        # Step 5: Apply backgrounding
+        if invocation.is_background:
+            elevated = Classification.max_severity(result.classification, Classification.WRITE)
+            if elevated != result.classification:
+                result.classification = elevated
+                result.classification_reason = (
+                    f"{result.classification_reason}; elevated by backgrounding"
+                    if result.classification_reason
+                    else "elevated by backgrounding"
+                )
+
+        # Step 6: Elevate to DANGEROUS when writing to system directories
+        if result.classification.severity() >= Classification.WRITE.severity():
+            system_paths_found = []
+            # Check argv tokens
+            for token in invocation.argv:
+                if _is_system_path(token):
+                    system_paths_found.append(token)
+            # Check redirect targets
+            for redirect in invocation.redirects:
+                if _is_system_path(redirect.target):
+                    system_paths_found.append(redirect.target)
+
+            if system_paths_found and result.classification != Classification.DANGEROUS:
+                result.classification = Classification.DANGEROUS
+                result.classification_reason = (
+                    result.classification_reason or ""
+                ) + f"; elevated to DANGEROUS: system path {system_paths_found[0]}"
+
+        command_results.append(result)
+        all_redirects.extend(invocation.redirects)
+
+    # Step 7: Collect directories
+    directories = _collect_directories(command_results)
+
+    # Step 8: Compute composite classification
+    if not command_results and parse_warnings:
+        overall = Classification.UNKNOWN
+    elif command_results:
+        overall = Classification.max_severity(*(r.classification for r in command_results))
+    else:
+        overall = Classification.READONLY  # empty input
+
+    return ExpressionResult(
+        expression=expression,
+        classification=overall,
+        directories=directories,
+        commands=command_results,
+        redirects=all_redirects,
+        parse_warnings=parse_warnings,
+    )
+
+
+def _extract_directories_from_argv(command: list[str], argv: list[str]) -> list[str]:
+    """Extract directories from a command's argv based on well-known command patterns.
+
+    Handles find, ls (first positional arg is a directory) and
+    cat/head/tail/less/more (dirname of first positional arg containing /).
+    """
+    if not command or len(argv) <= 1:
+        return []
+
+    binary = command[0]
+
+    # find and ls: first positional (non-option) arg is typically the directory
+    if binary in ("find", "ls"):
+        for arg in argv[1:]:
+            if not arg.startswith("-"):
+                return [arg]
+        return []
+
+    # File-reading commands: extract dirname from first positional arg containing /
+    if binary in ("cat", "head", "tail", "less", "more"):
+        for arg in argv[1:]:
+            if not arg.startswith("-") and "/" in arg:
+                dirname = os.path.dirname(arg)
+                if dirname:
+                    return [dirname]
+                return []
+        return []
+
+    return []
+
+
+def _collect_directories(results: list[CommandResult]) -> list[str]:
+    """Collect directories from command results, including inner commands."""
+    directories: list[str] = []
+
+    for result in results:
+        # Directory builtins: cd, pushd, popd
+        if result.command and result.command[0] in ("cd", "pushd") and len(result.argv) > 1:
+            directories.append(result.argv[1])
+
+        # Directories captured from global options (e.g., git -C /path)
+        if result.directories:
+            directories.extend(result.directories)
+
+        # Well-known commands that take directory arguments
+        directories.extend(_extract_directories_from_argv(result.command, result.argv))
+
+        # Collect directories from inner commands recursively
+        directories.extend(_collect_inner_directories(result.inner_commands))
+
+    return directories
+
+
+def _collect_inner_directories(results: list[InnerCommandResult]) -> list[str]:
+    """Collect directories from inner command results recursively."""
+    directories: list[str] = []
+
+    for result in results:
+        directories.extend(_extract_directories_from_argv(result.command, result.argv))
+        directories.extend(_collect_inner_directories(result.inner_commands))
+
+    return directories

bash_classify/cli.py

@@ -0,0 +1,110 @@
+"""CLI entry point for bash-classify."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .classifier import classify_expression
+from .models import (
+    CommandResult,
+    ExpressionResult,
+    InnerCommandResult,
+    Redirect,
+)
+
+
+def _inner_command_to_dict(result: InnerCommandResult) -> dict:
+    """Convert an InnerCommandResult to a JSON-serializable dict."""
+    d: dict = {
+        "delegation_mode": result.delegation_mode,
+        "delegation_source": result.delegation_source,
+        "command": result.command,
+        "argv": result.argv,
+        "classification": result.classification.value,
+        "matched_rule": result.matched_rule,
+    }
+
+    if result.ignored_options:
+        d["ignored_options"] = result.ignored_options
+    if result.remaining_options:
+        d["remaining_options"] = result.remaining_options
+    if result.overriding_option is not None:
+        d["overriding_option"] = result.overriding_option
+
+    d["inner_commands"] = [_inner_command_to_dict(ic) for ic in result.inner_commands]
+
+    return d
+
+
+def _command_to_dict(result: CommandResult) -> dict:
+    """Convert a CommandResult to a JSON-serializable dict."""
+    d: dict = {
+        "command": result.command,
+        "argv": result.argv,
+        "classification": result.classification.value,
+        "matched_rule": result.matched_rule,
+    }
+
+    if result.ignored_options:
+        d["ignored_options"] = result.ignored_options
+    if result.remaining_options:
+        d["remaining_options"] = result.remaining_options
+    if result.classification_reason is not None:
+        d["classification_reason"] = result.classification_reason
+    if result.overriding_option is not None:
+        d["overriding_option"] = result.overriding_option
+
+    d["inner_commands"] = [_inner_command_to_dict(ic) for ic in result.inner_commands]
+
+    return d
+
+
+def _redirect_to_dict(redirect: Redirect) -> dict:
+    """Convert a Redirect to a JSON-serializable dict."""
+    return {
+        "operator": redirect.operator,
+        "target": redirect.target,
+        "affects_classification": redirect.affects_classification,
+    }
+
+
+def _result_to_dict(result: ExpressionResult) -> dict:
+    """Convert an ExpressionResult to a JSON-serializable dict."""
+    d: dict = {
+        "expression": result.expression,
+        "classification": result.classification.value,
+        "directories": result.directories,
+        "commands": [_command_to_dict(cmd) for cmd in result.commands],
+    }
+
+    if result.redirects:
+        d["redirects"] = [_redirect_to_dict(r) for r in result.redirects]
+
+    if result.parse_warnings:
+        d["parse_warnings"] = result.parse_warnings
+
+    return d
+
+
+def main() -> None:
+    """Read bash expressions from stdin, classify, and output JSON.
+
+    Exit codes:
+        0 - successfully classified
+        1 - parse error (invalid bash syntax)
+        2 - internal error
+    """
+    try:
+        expression = sys.stdin.read().strip()
+        if not expression:
+            sys.exit(1)
+
+        result = classify_expression(expression)
+        output = _result_to_dict(result)
+        json.dump(output, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        sys.exit(0)
+    except Exception as e:
+        print(f"bash-classify: internal error: {e}", file=sys.stderr)
+        sys.exit(2)

bash_classify/commands/apt.yaml

@@ -0,0 +1,23 @@
+# $schema: ../../../schemas/command.schema.json
+command: apt
+description: "Debian package management tool"
+strict: false
+subcommands:
+  list:
+    classification: READONLY
+  show:
+    classification: READONLY
+  search:
+    classification: READONLY
+  install:
+    classification: DANGEROUS
+  remove:
+    classification: DANGEROUS
+  purge:
+    classification: DANGEROUS
+  update:
+    classification: WRITE
+  upgrade:
+    classification: DANGEROUS
+  autoremove:
+    classification: DANGEROUS

bash_classify/commands/awk.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: awk
+description: "Pattern scanning and text processing language"
+classification: READONLY
+strict: false

bash_classify/commands/basename.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: basename
+description: "Strip directory and suffix from filenames"
+classification: READONLY
+strict: false

bash_classify/commands/bash.yaml

@@ -0,0 +1,18 @@
+# $schema: ../../../schemas/command.schema.json
+command: bash
+description: "GNU Bourne-Again SHell"
+classification: DANGEROUS
+strict: false
+delegates_to:
+  mode: flag_value_is_expression
+  flag: -c
+options:
+  -c: {takes_value: true}
+  -e: {}
+  -x: {}
+  -i: {}
+  --norc: {}
+  --noprofile: {}
+  -l: {}
+  --login: {aliases: [-l]}
+  -n: {}

bash_classify/commands/brew.yaml

@@ -0,0 +1,25 @@
+# $schema: ../../../schemas/command.schema.json
+command: brew
+description: "macOS and Linux package manager"
+strict: false
+subcommands:
+  list:
+    classification: READONLY
+  info:
+    classification: READONLY
+  search:
+    classification: READONLY
+  install:
+    classification: WRITE
+  uninstall:
+    classification: WRITE
+  update:
+    classification: WRITE
+  upgrade:
+    classification: WRITE
+  cleanup:
+    classification: WRITE
+  doctor:
+    classification: READONLY
+  config:
+    classification: READONLY

bash_classify/commands/builtin.yaml

@@ -0,0 +1,6 @@
+# $schema: ../../../schemas/command.schema.json
+command: builtin
+description: "Execute a shell builtin command"
+classification: READONLY
+delegates_to:
+  mode: rest_are_argv

bash_classify/commands/cargo.yaml

@@ -0,0 +1,29 @@
+# $schema: ../../../schemas/command.schema.json
+command: cargo
+description: "Rust package manager and build tool"
+strict: false
+subcommands:
+  build:
+    classification: WRITE
+  test:
+    classification: WRITE
+  run:
+    classification: DANGEROUS
+  check:
+    classification: READONLY
+  clippy:
+    classification: READONLY
+    options:
+      --fix: {overrides: WRITE}
+  fmt:
+    classification: WRITE
+  doc:
+    classification: WRITE
+  publish:
+    classification: DANGEROUS
+  install:
+    classification: WRITE
+  clean:
+    classification: WRITE
+  update:
+    classification: WRITE

bash_classify/commands/cat.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: cat
+description: "Concatenate and print files"
+classification: READONLY
+strict: false

bash_classify/commands/chgrp.yaml

@@ -0,0 +1,8 @@
+# $schema: ../../../schemas/command.schema.json
+command: chgrp
+description: "Change group ownership of files"
+classification: WRITE
+strict: false
+options:
+  -R: {overrides: DANGEROUS}
+  --recursive: {overrides: DANGEROUS, aliases: [-R]}

bash_classify/commands/chmod.yaml

@@ -0,0 +1,8 @@
+# $schema: ../../../schemas/command.schema.json
+command: chmod
+description: "Change file mode bits"
+classification: WRITE
+strict: false
+options:
+  -R: {overrides: DANGEROUS}
+  --recursive: {overrides: DANGEROUS, aliases: [-R]}

bash_classify/commands/chown.yaml

@@ -0,0 +1,8 @@
+# $schema: ../../../schemas/command.schema.json
+command: chown
+description: "Change file owner and group"
+classification: WRITE
+strict: false
+options:
+  -R: {overrides: DANGEROUS}
+  --recursive: {overrides: DANGEROUS, aliases: [-R]}

bash_classify/commands/column.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: column
+description: "Format input into multiple columns"
+classification: READONLY
+strict: false

bash_classify/commands/comm.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: comm
+description: "Compare two sorted files line by line"
+classification: READONLY
+strict: false

bash_classify/commands/command.yaml

@@ -0,0 +1,10 @@
+# $schema: ../../../schemas/command.schema.json
+command: command
+description: "Execute a command or display command info"
+classification: READONLY
+delegates_to:
+  mode: rest_are_argv
+options:
+  -v: {}
+  -V: {}
+  -p: {}

bash_classify/commands/cp.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: cp
+description: "Copy files and directories"
+classification: WRITE
+strict: false

bash_classify/commands/curl.yaml

@@ -0,0 +1,28 @@
+# $schema: ../../../schemas/command.schema.json
+command: curl
+description: "Transfer data from or to a server"
+classification: WRITE
+strict: false
+options:
+  -o: {takes_value: true, overrides: WRITE}
+  --output: {takes_value: true, overrides: WRITE, aliases: [-o]}
+  -O: {overrides: WRITE}
+  --remote-name: {overrides: WRITE, aliases: [-O]}
+  -T: {takes_value: true, overrides: WRITE}
+  --upload-file: {takes_value: true, overrides: WRITE, aliases: [-T]}
+  -X: {takes_value: true}
+  --request: {takes_value: true, aliases: [-X]}
+  -d: {takes_value: true, overrides: WRITE}
+  --data: {takes_value: true, overrides: WRITE, aliases: [-d]}
+  -F: {takes_value: true, overrides: WRITE}
+  --form: {takes_value: true, overrides: WRITE, aliases: [-F]}
+  -H: {takes_value: true}
+  --header: {takes_value: true, aliases: [-H]}
+  -s: {}
+  --silent: {aliases: [-s]}
+  -f: {}
+  --fail: {aliases: [-f]}
+  -L: {}
+  --location: {aliases: [-L]}
+  -k: {}
+  --insecure: {aliases: [-k]}

bash_classify/commands/cut.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: cut
+description: "Remove sections from each line of files"
+classification: READONLY
+strict: false

bash_classify/commands/date.yaml

@@ -0,0 +1,8 @@
+# $schema: ../../../schemas/command.schema.json
+command: date
+description: "Display or set the system date and time"
+classification: READONLY
+strict: true
+options:
+  -s: {takes_value: true, overrides: DANGEROUS}
+  --set: {takes_value: true, overrides: DANGEROUS, aliases: [-s]}

bash_classify/commands/df.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: df
+description: "Report file system disk space usage"
+classification: READONLY
+strict: false

bash_classify/commands/diff.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: diff
+description: "Compare files line by line"
+classification: READONLY
+strict: false

bash_classify/commands/dig.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: dig
+description: "DNS lookup utility"
+classification: READONLY
+strict: false

bash_classify/commands/dirname.yaml

@@ -0,0 +1,5 @@
+# $schema: ../../../schemas/command.schema.json
+command: dirname
+description: "Strip last component from file name"
+classification: READONLY
+strict: false