shellsafe 0.2.0__tar.gz → 0.3.1__tar.gz

{shellsafe-0.2.0 → shellsafe-0.3.1}/.github/workflows/ci.yml

@@ -25,4 +25,3 @@ jobs:
       - run: uv sync
       - run: uv run pytest -q
       - run: uv run ruff check .
-      - run: uv run mypy src/

{shellsafe-0.2.0 → shellsafe-0.3.1}/CHANGELOG.md

@@ -3,6 +3,43 @@
 All notable changes to this project are documented here. Format follows
 Keep a Changelog; versioning follows SemVer.
 
+## [0.3.1] - 2026-08-30
+
+### Added
+
+- AU002 rule: detect `shell=True` with dynamic content (.format(), string
+  concatenation, %-formatting, variables) in shell executor calls
+- AU002 fixture corpus: 6 positive cases + 5 safe cases
+- Unit tests for AU002 detection, confidence, and severity
+- Integration tests for CLI audit with AU002
+
+## [0.3.0] - 2026-08-29
+
+### Added
+
+- Offline audit scanner: AST-based detection of f-strings passed to shell
+  executors (`os.system`, `subprocess.run`, `subprocess.call`, etc.)
+- AU001 rule: flags f-string interpolation in shell executor arguments with
+  fix-hint suggesting template strings
+- Import alias tracking: handles `import subprocess as sp`, `from os import
+  system`, etc.
+- CLI `shellsafe audit` command with terminal table and JSON output
+- `--json` flag for machine-readable findings
+- `--severity` flag to filter by minimum severity level
+- Audit fixture corpus: 6 positive cases + 4 safe cases
+- Unit tests for scanner, integration tests for CLI audit
+
+### Changed
+
+- Collapse `audit/rules.py` and `reporters.py` into single `audit/scanner.py`
+- CLI refactored with dedicated `_run_audit` handler
+
+### Removed
+
+- mypy (ruff catches real bugs)
+- `cast()` calls on values that already have the right type
+
+
 ## [0.2.0] - 2026-08-27
 
 ### Added

{shellsafe-0.2.0 → shellsafe-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.2.0
+Version: 0.3.1
 Summary: Run shell commands safely using Python 3.14 template strings. Values can never turn into commands.
 Project-URL: Repository, https://github.com/rahulXs/shellsafe
 Project-URL: Issues, https://github.com/rahulXs/shellsafe/issues
@@ -47,9 +47,9 @@ subprocess.run(f"git commit -m {message}", shell=True)
 # if message = "fix; rm -rf ~"  ->  two commands run. The second one is bad.
 ```
 
-Python planned to solve this officially (PEP 787), but that plan was postponed.
-So today there is no standard way to run shell commands safely with templates.
-This package fills that gap.
+Python planned to solve this officially (PEP 787), but that PEP was deferred to
+at least Python 3.15. So today there is no standard way to run shell commands
+safely with templates. This package fills that gap.
 
 ## Install
 
@@ -61,7 +61,8 @@ Needs Python 3.14 or newer.
 
 ## How to use
 
-Run a command. Your values always stay one argument each:
+Run a command. Your values always stay one argument each. `run()` never invokes
+a shell, so injection is impossible on any platform:
 
 ```python
 from shellsafe import run
@@ -108,6 +109,27 @@ print(plan(t"git commit -m {message}"))
 `RAW(...)` marks content you have already made safe by hand. It is loud and easy
 to find in code review, so trust is never hidden.
 
+## Find old dangerous patterns
+
+Already have code using f-strings in shell commands? The scanner finds them:
+
+```bash
+shellsafe audit src/
+```
+
+It detects f-strings passed to `os.system`, `subprocess.run(shell=True)`, and
+other shell executors. Get machine-readable output:
+
+```bash
+shellsafe audit src/ --json
+```
+
+Filter by severity:
+
+```bash
+shellsafe audit src/ --severity warning
+```
+
 ## Limits
 
 - Shell features (pipes, redirections) work on Linux and macOS only. Windows

{shellsafe-0.2.0 → shellsafe-0.3.1}/README.md

@@ -25,9 +25,9 @@ subprocess.run(f"git commit -m {message}", shell=True)
 # if message = "fix; rm -rf ~"  ->  two commands run. The second one is bad.
 ```
 
-Python planned to solve this officially (PEP 787), but that plan was postponed.
-So today there is no standard way to run shell commands safely with templates.
-This package fills that gap.
+Python planned to solve this officially (PEP 787), but that PEP was deferred to
+at least Python 3.15. So today there is no standard way to run shell commands
+safely with templates. This package fills that gap.
 
 ## Install
 
@@ -39,7 +39,8 @@ Needs Python 3.14 or newer.
 
 ## How to use
 
-Run a command. Your values always stay one argument each:
+Run a command. Your values always stay one argument each. `run()` never invokes
+a shell, so injection is impossible on any platform:
 
 ```python
 from shellsafe import run
@@ -86,6 +87,27 @@ print(plan(t"git commit -m {message}"))
 `RAW(...)` marks content you have already made safe by hand. It is loud and easy
 to find in code review, so trust is never hidden.
 
+## Find old dangerous patterns
+
+Already have code using f-strings in shell commands? The scanner finds them:
+
+```bash
+shellsafe audit src/
+```
+
+It detects f-strings passed to `os.system`, `subprocess.run(shell=True)`, and
+other shell executors. Get machine-readable output:
+
+```bash
+shellsafe audit src/ --json
+```
+
+Filter by severity:
+
+```bash
+shellsafe audit src/ --severity warning
+```
+
 ## Limits
 
 - Shell features (pipes, redirections) work on Linux and macOS only. Windows

{shellsafe-0.2.0 → shellsafe-0.3.1}/pyproject.toml

@@ -50,10 +50,6 @@ select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF", "C901"]
 [tool.ruff.lint.mccabe]
 max-complexity = 10
 
-[tool.mypy]
-strict = true
-python_version = "3.14"
-
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-q --tb=short"
@@ -62,12 +58,13 @@ addopts = "-q --tb=short"
 # RAW() is a deliberate loud trust marker; the uppercase name is the API.
 "src/shellsafe/raw.py" = ["N802"]
 "src/shellsafe/__init__.py" = ["N999"]
+# Fixture files contain planted violations and undefined names on purpose.
+"tests/fixtures/**" = ["F821", "F841"]
 
 [dependency-groups]
 dev = [
     "pytest>=8",
     "ruff>=0.5",
-    "mypy>=1.10",
     "hypothesis>=6",
     "build>=1.2",
     "twine>=6",

shellsafe-0.3.1/src/shellsafe/_version.py

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

shellsafe-0.3.1/src/shellsafe/audit/__init__.py

@@ -0,0 +1,6 @@
+"""Offline AST audit for dangerous command construction."""
+
+
+from .scanner import Finding, scan, scan_report
+
+__all__ = ["Finding", "scan", "scan_report"]

shellsafe-0.3.1/src/shellsafe/audit/scanner.py

@@ -0,0 +1,290 @@
+"""Offline AST scanner for dangerous command construction.
+
+Never imports from the scanned project. Reads code only.
+"""
+
+import ast
+import json
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """One audit finding."""
+
+    rule_id: str
+    title: str
+    severity: str
+    confidence: float
+    path: str
+    lineno: int
+    col: int
+    message: str
+    evidence: dict[str, Any] = field(default_factory=dict)
+    fix_hint: str = ""
+    ignored: bool = False
+    ignore_reason: str | None = None
+
+
+_EXECUTORS = {
+    "system": "os.system",
+    "popen": "os.popen",
+    "run": "subprocess.run",
+    "call": "subprocess.call",
+    "check_call": "subprocess.check_call",
+    "check_output": "subprocess.check_output",
+    "Popen": "subprocess.Popen",
+    "getoutput": "subprocess.getoutput",
+}
+
+_IMPORT_ALIAS = {
+    "os": "os",
+    "subprocess": "subprocess",
+}
+
+
+def _resolve_callee(node: ast.expr, aliases: dict[str, str]) -> str | None:
+    """Resolve a Call.func to an executor label like 'os.system'."""
+    if (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.value, ast.Name)
+        and node.value.id in _IMPORT_ALIAS
+    ):
+        module = _IMPORT_ALIAS[node.value.id]
+        if node.attr in _EXECUTORS:
+            return f"{module}.{node.attr}"
+    if isinstance(node, ast.Name):
+        real = aliases.get(node.id, node.id)
+        if real in _EXECUTORS:
+            return _EXECUTORS[real]
+        if "." in real:
+            module, func = real.rsplit(".", 1)
+            if func in _EXECUTORS:
+                return f"{module}.{func}"
+    return None
+
+
+def au001(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
+    """f-string passed to a shell-executing call."""
+    callee = _resolve_callee(node.func, aliases)
+    if callee is None:
+        return None
+    for arg in node.args:
+        if isinstance(arg, ast.JoinedStr) and any(
+            isinstance(v, ast.FormattedValue) for v in arg.values
+        ):
+            return Finding(
+                rule_id="AU001",
+                title="f-string passed to shell-executing call",
+                severity="error",
+                confidence=0.95,
+                path=path,
+                lineno=node.lineno,
+                col=node.col_offset,
+                message=f"{callee} receives an f-string with interpolated value(s)",
+                evidence={
+                    "callee": callee,
+                    "interpolations": sum(
+                        1 for v in arg.values if isinstance(v, ast.FormattedValue)
+                    ),
+                },
+                fix_hint='use shellsafe.run(t"...") or pass an argv list',
+            )
+    return None
+
+
+def _has_shell_true(node: ast.Call) -> bool:
+    for kw in node.keywords:
+        if kw.arg == "shell" and isinstance(kw.value, ast.Constant) and kw.value.value is True:
+            return True
+    return False
+
+
+def _is_dynamic_string(node: ast.expr) -> bool:
+    if isinstance(node, ast.JoinedStr):
+        return any(isinstance(v, ast.FormattedValue) for v in node.values)
+    if (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "format"
+    ):
+        return True
+    if isinstance(node, ast.BinOp) and isinstance(node.op, (ast.Add, ast.Mod)):
+        return True
+    return isinstance(node, (ast.Name, ast.Attribute))
+
+
+def au002(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
+    """shell=True with dynamic content in shell-executing call."""
+    callee = _resolve_callee(node.func, aliases)
+    if callee is None:
+        return None
+    if not _has_shell_true(node):
+        return None
+    for arg in node.args:
+        if _is_dynamic_string(arg):
+            kind = "f-string" if isinstance(arg, ast.JoinedStr) else "dynamic content"
+            if isinstance(arg, ast.Call) and isinstance(arg.func, ast.Attribute):
+                kind = ".format() call"
+            elif isinstance(arg, ast.BinOp) and isinstance(arg.op, ast.Add):
+                kind = "string concatenation"
+            elif isinstance(arg, ast.BinOp) and isinstance(arg.op, ast.Mod):
+                kind = "%-format string"
+            elif isinstance(arg, (ast.Name, ast.Attribute)):
+                kind = "variable"
+            return Finding(
+                rule_id="AU002",
+                title="shell=True with dynamic content",
+                severity="warning",
+                confidence=0.90,
+                path=path,
+                lineno=node.lineno,
+                col=node.col_offset,
+                message=f"{callee} uses shell=True with {kind}",
+                evidence={
+                    "callee": callee,
+                    "kind": kind,
+                },
+                fix_hint='use shellsafe.run(t"...") or pass an argv list without shell=True',
+            )
+    return None
+
+
+RULES: list[tuple[str, Callable[..., Finding | None]]] = [
+    ("AU001", au001),
+    ("AU002", au002),
+]
+
+
+def _discover(paths: list[str]) -> list[Path]:
+    files: list[Path] = []
+    for raw in paths:
+        p = Path(raw)
+        if p.is_file() and p.suffix == ".py":
+            files.append(p)
+        elif p.is_dir():
+            files.extend(
+                f
+                for f in sorted(p.rglob("*.py"))
+                if not any(part.startswith(".") or part == "__pycache__" for part in f.parts)
+            )
+    return files
+
+
+def _import_aliases(tree: ast.Module) -> dict[str, str]:
+    """Map local names to real module.function for executor imports."""
+    aliases: dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                local = alias.asname or alias.name
+                aliases[local] = alias.name
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module or ""
+            for alias in node.names:
+                local = alias.asname or alias.name
+                aliases[local] = f"{module}.{alias.name}"
+    return aliases
+
+
+def scan(paths: list[str]) -> list[Finding]:
+    """Scan Python files for audit findings."""
+    findings: list[Finding] = []
+    for path in _discover(paths):
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        except (SyntaxError, UnicodeDecodeError):
+            continue
+        aliases = _import_aliases(tree)
+        rel = str(path)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                for _, rule in RULES:
+                    result = rule(node, aliases, rel)
+                    if result is not None:
+                        findings.append(result)
+    findings.sort(key=lambda f: (f.severity != "error", f.path, f.lineno))
+    return findings
+
+
+_COLORS = {"error": "\033[31m", "warning": "\033[33m", "info": "\033[36m", "reset": "\033[0m"}
+
+
+def _color(text: str, severity: str) -> str:
+    c = _COLORS.get(severity, "")
+    return f"{c}{text}{_COLORS['reset']}" if c else text
+
+
+def report_terminal(findings: list[Finding]) -> str:
+    """Render findings as a terminal table."""
+    if not findings:
+        return "no findings"
+    use_color = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+    lines = [
+        f"{'SEV':<9} {'RULE':<7} {'FILE':<40} {'LINE':>5}  MESSAGE",
+        "-" * 90,
+    ]
+    for f in findings:
+        sev = _color(f.severity.upper(), f.severity) if use_color else f.severity.upper()
+        path = f.path if len(f.path) <= 40 else "..." + f.path[-37:]
+        lines.append(f"{sev:<18} {f.rule_id:<7} {path:<40} {f.lineno:>5}  {f.message}")
+    return "\n".join(lines)
+
+
+def report_json(report: dict[str, object]) -> str:
+    """Render the full report as JSON."""
+    return json.dumps(report, indent=2)
+
+
+def scan_report(paths: list[str]) -> dict[str, object]:
+    """Scan and return a report dict matching schema v1."""
+    start = time.monotonic()
+    findings = scan(paths)
+    duration_ms = round((time.monotonic() - start) * 1000, 1)
+
+    errors = sum(1 for f in findings if f.severity == "error" and not f.ignored)
+    warnings = sum(1 for f in findings if f.severity == "warning" and not f.ignored)
+    info = sum(1 for f in findings if f.severity == "info" and not f.ignored)
+    ignored = sum(1 for f in findings if f.ignored)
+
+    from .._version import __version__
+
+    return {
+        "schema_version": 1,
+        "tool": {"name": "shellsafe", "version": __version__},
+        "run": {
+            "duration_ms": duration_ms,
+            "host_python": f"{sys.version_info.major}.{sys.version_info.minor}"
+            f".{sys.version_info.micro}",
+            "paths": paths,
+        },
+        "summary": {
+            "errors": errors,
+            "warnings": warnings,
+            "info": info,
+            "ignored": ignored,
+            "verdict": "fail" if errors > 0 else "pass",
+        },
+        "findings": [
+            {
+                "rule_id": f.rule_id,
+                "title": f.title,
+                "severity": f.severity,
+                "confidence": f.confidence,
+                "path": f.path,
+                "lineno": f.lineno,
+                "col": f.col,
+                "message": f.message,
+                "evidence": f.evidence,
+                "fix_hint": f.fix_hint,
+                "ignored": f.ignored,
+                "ignore_reason": f.ignore_reason,
+            }
+            for f in findings
+        ],
+    }

shellsafe-0.3.1/src/shellsafe/cli.py

@@ -0,0 +1,70 @@
+"""CLI: audit, version. Business logic lives in the stages."""
+
+import argparse
+import platform
+import sys
+
+from . import exitcodes
+from ._version import __version__
+
+_SEVERITY_ORDER = {"error": 0, "warning": 1, "info": 2}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="shellsafe")
+    parser.add_argument("-V", "--version", action="store_true")
+    sub = parser.add_subparsers(dest="command")
+
+    audit = sub.add_parser("audit", help="scan code for dangerous command construction")
+    audit.add_argument("paths", nargs="*", default=["."], help="files or directories to scan")
+    audit.add_argument("--json", action="store_true", dest="json_output", help="output JSON report")
+    audit.add_argument(
+        "--severity",
+        choices=["error", "warning", "info"],
+        default="warning",
+        help="minimum severity to report (default: warning)",
+    )
+
+    sub.add_parser("version", help="detailed version and capability matrix")
+    return parser
+
+
+def _run_audit(args: argparse.Namespace) -> int:
+    from .audit.scanner import Finding, report_json, report_terminal, scan_report
+
+    report = scan_report(args.paths)
+    findings = report.get("findings", [])
+
+    min_sev = _SEVERITY_ORDER.get(args.severity, 1)
+    filtered = [
+        f for f in findings
+        if _SEVERITY_ORDER.get(str(f.get("severity", "")), 9) <= min_sev
+    ]
+
+    if args.json_output:
+        print(report_json(report))
+    else:
+        print(report_terminal([Finding(**f) for f in filtered]))
+
+    summary = report.get("summary", {})
+    return exitcodes.FINDINGS if summary.get("errors", 0) > 0 else exitcodes.OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        print(f"shellsafe {__version__}")
+        return exitcodes.OK
+    if args.command == "version":
+        py = platform.python_version()
+        print(f"shellsafe {__version__} . python {py} . {sys.platform}")
+        print("argv-mode: available")
+        print("shell-mode: available (posix)")
+        print("audit: available (AU001)")
+        return exitcodes.OK
+    if args.command == "audit":
+        return _run_audit(args)
+    parser.print_help()
+    return exitcodes.OK

{shellsafe-0.2.0 → shellsafe-0.3.1}/src/shellsafe/execute.py

@@ -1,11 +1,9 @@
 """Subprocess wrappers over rendered ExecutionPlans."""
 
-from __future__ import annotations
-
 import subprocess
 import sys
 from dataclasses import dataclass
-from typing import Any, cast
+from typing import Any
 
 from .errors import ArgvOnlyError, ShellSafeError
 from .raw import Raw  # noqa: F401  (re-exported through the package root)
@@ -29,7 +27,7 @@ _ALLOWED_KWARGS = frozenset(
 )
 
 
-def _validate_kwargs(kwargs: dict[str, object]) -> None:
+def _validate_kwargs(kwargs: dict[str, object]):
     if "shell" in kwargs:
         raise ShellSafeError(
             "shellsafe never passes shell=True; use shx() for pipes and "
@@ -51,11 +49,7 @@ def plan(template: object) -> ExecutionPlan:
 
 
 def _pass_through(kwargs: dict[str, object]) -> dict[str, Any]:
-    """Filter kwargs to the allowed subprocess.run set."""
-    return cast(
-        "dict[str, Any]",
-        {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS},
-    )
+    return {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS}
 
 
 def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[str]:
@@ -78,8 +72,7 @@ def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[st
             "run() to execute pipes and redirections"
         )
     assert rendered.argv is not None
-    result = subprocess.run(rendered.argv, **_pass_through(kwargs))
-    return cast("subprocess.CompletedProcess[str]", result)
+    return subprocess.run(rendered.argv, **_pass_through(kwargs))
 
 
 @dataclass(frozen=True, slots=True)
@@ -98,8 +91,6 @@ def capture(template: object, /, **kwargs: object) -> CaptureResult:
     kwargs["text"] = True
     kwargs["encoding"] = "utf-8"
     completed = run(template, **kwargs)
-    assert isinstance(completed.stdout, str)
-    assert isinstance(completed.stderr, str)
     return CaptureResult(
         stdout=completed.stdout,
         stderr=completed.stderr,
@@ -122,8 +113,7 @@ def shx(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[st
             "template contains no shell metacharacters; use run() instead"
         )
     assert rendered.shell_line is not None
-    result = subprocess.run(
+    return subprocess.run(
         ["/bin/sh", "-c", rendered.shell_line],
         **_pass_through(kwargs),
     )
-    return cast("subprocess.CompletedProcess[str]", result)

shellsafe-0.3.1/src/shellsafe/platforms.py

@@ -0,0 +1,25 @@
+"""Platform policy tables and route decision."""
+
+import sys
+
+METACHARACTERS = frozenset("|&;()<>$`\"'*?!#\\\n\r\t")
+
+IS_WINDOWS = sys.platform.startswith("win")
+
+
+def route_for(static_text: str) -> str:
+    """Return "argv" or "shell" for the given static template text.
+
+    Raises UnsupportedPlatformError on Windows when shell features are requested.
+    """
+    if not any(ch in METACHARACTERS for ch in static_text):
+        return "argv"
+    if IS_WINDOWS:
+        from .errors import UnsupportedPlatformError
+
+        raise UnsupportedPlatformError(
+            "shell metacharacters in a shellsafe template require posix sh; "
+            "windows cmd.exe quoting cannot be made injection-safe. "
+            "restructure without pipes/redirections, or run under wsl."
+        )
+    return "shell"

{shellsafe-0.2.0 → shellsafe-0.3.1}/src/shellsafe/raw.py

@@ -1,6 +1,5 @@
 """RAW marker: the single explicit trust boundary."""
 
-from __future__ import annotations
 
 from .errors import RawUsageError