shellsafe 0.1.1__tar.gz → 0.3.0__tar.gz

{shellsafe-0.1.1 → shellsafe-0.3.0}/.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.3.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+Keep a Changelog; versioning follows SemVer.
+
+## [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
+
+- Shell-mode execution: `shx()` runs pipes, redirections, and globs via
+  `/bin/sh -c` on Linux and macOS; interpolated values are `shlex`-quoted
+  automatically
+- Shell-mode payload corpus: 15 injection cases verified as single tokens via
+  `shlex.split` round-trip
+- Shell-mode property tests: arbitrary values stay single shell tokens under
+  pipe templates
+- Cyclomatic complexity lint (`C901`, max-complexity 10) enabled in CI
+
+### Changed
+
+- `run()` now rejects templates that contain shell metacharacters with guidance
+  to use `shx()` instead
+- CLI version matrix shows shell-mode availability
+
+### Removed
+
+- Dead `METACHARACTERS` constant from render.py (platforms.py owns it)
+
+## [0.1.1] - 2026-08-24
+
+### Changed
+
+- Project description rewritten
+- README restructured for PyPI: package page now leads with the why, usage and
+  limits; contributing details stay in the repository only
+
+## [0.1.0] - 2026-08-24
+
+### Added
+
+- Argv-mode rendering and execution via template strings
+- RAW trust marker with argv splicing
+- capture() helper with utf-8 stdout/stderr
+- plan() helper for inspecting commands before execution
+- Injection payload corpus as a release gate; all cases render inert

{shellsafe-0.1.1 → shellsafe-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.1.1
+Version: 0.3.0
 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
@@ -108,9 +108,33 @@ 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
 
-- On Windows, commands with pipes do not work. Plain commands work fully.
+- Shell features (pipes, redirections) work on Linux and macOS only. Windows
+  supports plain commands only.
+- `run()` refuses templates that contain shell metacharacters. Use `shx()` for
+  those.
 - Byte values are rejected. Decode them first.
 - We keep your command safe to build and run. Testing what your command does is
   still your job.

{shellsafe-0.1.1 → shellsafe-0.3.0}/README.md

@@ -86,9 +86,33 @@ 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
 
-- On Windows, commands with pipes do not work. Plain commands work fully.
+- Shell features (pipes, redirections) work on Linux and macOS only. Windows
+  supports plain commands only.
+- `run()` refuses templates that contain shell metacharacters. Use `shx()` for
+  those.
 - Byte values are rejected. Decode them first.
 - We keep your command safe to build and run. Testing what your command does is
   still your job.

{shellsafe-0.1.1 → shellsafe-0.3.0}/pyproject.toml

@@ -45,11 +45,10 @@ target-version = "py314"
 line-length = 100
 
 [tool.ruff.lint]
-select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF", "C901"]
 
-[tool.mypy]
-strict = true
-python_version = "3.14"
+[tool.ruff.lint.mccabe]
+max-complexity = 10
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -59,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.0/src/shellsafe/_version.py

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

shellsafe-0.3.0/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.0/src/shellsafe/audit/scanner.py

@@ -0,0 +1,232 @@
+"""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
+
+
+RULES: list[tuple[str, Callable[..., Finding | None]]] = [
+    ("AU001", au001),
+]
+
+
+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.0/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.1.1 → shellsafe-0.3.0}/src/shellsafe/execute.py

@@ -1,20 +1,14 @@
 """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)
 from .render import ExecutionPlan
 
-_SHELL_MODE_PENDS = (
-    "shell-mode execution arrives in shellsafe 0.2; "
-    "this release covers argv-mode commands"
-)
-
 _ALLOWED_KWARGS = frozenset(
     {
         "check",
@@ -33,11 +27,11 @@ _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() on posix for pipes and "
-            "redirections"
+            "shellsafe never passes shell=True; use shx() for pipes and "
+            "redirections on posix"
         )
     unknown = set(kwargs) - _ALLOWED_KWARGS
     if unknown:
@@ -54,6 +48,10 @@ def plan(template: object) -> ExecutionPlan:
     return render_plan(template)
 
 
+def _pass_through(kwargs: dict[str, object]) -> dict[str, Any]:
+    return {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS}
+
+
 def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[str]:
     """Render the template and execute it.
 
@@ -64,15 +62,17 @@ def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[st
     _validate_kwargs(kwargs)
     rendered = plan(template)
     if rendered.mode == "shell":
-        raise ShellSafeError(_SHELL_MODE_PENDS)
+        if sys.platform.startswith("win"):
+            raise ShellSafeError(
+                "shell mode is posix-only; restructure the command without "
+                "pipes or redirections, or run under wsl"
+            )
+        raise ShellSafeError(
+            "this command contains shell metacharacters; use shx() instead of "
+            "run() to execute pipes and redirections"
+        )
     assert rendered.argv is not None
-    # passthrough boundary: values are caller-owned subprocess kwargs
-    typed_kwargs = cast(
-        "dict[str, Any]",
-        {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS},
-    )
-    result = subprocess.run(rendered.argv, **typed_kwargs)
-    return cast("subprocess.CompletedProcess[str]", result)
+    return subprocess.run(rendered.argv, **_pass_through(kwargs))
 
 
 @dataclass(frozen=True, slots=True)
@@ -91,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,
@@ -101,12 +99,12 @@ def capture(template: object, /, **kwargs: object) -> CaptureResult:
     )
 
 
-def shx(template: object, /, **kwargs: object) -> object:
-    """Shell-route alias for templates that need pipes or redirections.
+def shx(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[str]:
+    """Execute a shell-routed template (pipes, redirections, globs).
 
-    Raises ArgvOnlyError when the template needs no shell at all, so a missing
-    pipe is never silently ignored. Full shell execution ships in shellsafe 0.2;
-    rendering and inspection work today via shellsafe.plan().
+    Interpolated values are POSIX shell-quoted automatically. The rendered line
+    runs under /bin/sh -c. Raises ArgvOnlyError when the template has no shell
+    metacharacters (use run() instead).
     """
     _validate_kwargs(kwargs)
     rendered = plan(template)
@@ -114,4 +112,8 @@ def shx(template: object, /, **kwargs: object) -> object:
         raise ArgvOnlyError(
             "template contains no shell metacharacters; use run() instead"
         )
-    raise ShellSafeError(_SHELL_MODE_PENDS)
+    assert rendered.shell_line is not None
+    return subprocess.run(
+        ["/bin/sh", "-c", rendered.shell_line],
+        **_pass_through(kwargs),
+    )

shellsafe-0.3.0/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.1.1 → shellsafe-0.3.0}/src/shellsafe/raw.py

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