shellsafe 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -3,6 +3,33 @@
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.2.0
+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,6 +108,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.0}/README.md

@@ -86,6 +86,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.0}/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.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.2.0 → shellsafe-0.3.0}/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.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.2.0 → 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
 

{shellsafe-0.2.0 → shellsafe-0.3.0}/src/shellsafe/render.py

@@ -1,4 +1,4 @@
-"""Template rendering: t-string in, ExecutionPlan out. Pure and deterministic.
+"""Template rendering: t-string in, ExecutionPlan out.
 
 Security invariants (property-tested, see docs/07_rendering_engine_spec.md):
 - INV-1: every interpolation contributes exactly one argv element equal to its
@@ -7,8 +7,6 @@ Security invariants (property-tested, see docs/07_rendering_engine_spec.md):
 - INV-3: element count equals static words plus interpolations plus RAW splices.
 """
 
-from __future__ import annotations
-
 import shlex
 from dataclasses import dataclass
 from string.templatelib import Interpolation, Template
@@ -29,25 +27,17 @@ class ExecutionPlan:
     shell_line: str | None = None
 
     def __repr__(self) -> str:
-        if self.mode == "argv":
-            assert self.argv is not None
+        if self.mode == "argv" and self.argv is not None:
             body = ",".join(repr(a) for a in self.argv)
             return f"argv: [{body}]"
-        assert self.shell_line is not None
         return f"shell: {self.shell_line}"
 
 
 Segment = str | Interpolation[str] | Raw
 
 
-def _walk(
-    template: Template, seen: frozenset[int]
-) -> list[Segment]:
-    """Flatten a template into an ordered list of static text and interpolations.
-
-    Nested templates (a t-string interpolated inside a t-string) splice their
-    segments at the interpolation position. Cycle-guarded via object ids.
-    """
+def _walk(template: Template, seen: frozenset[int]) -> list[Segment]:
+    """Flatten a Template into segments, recursing into nested templates."""
     parts: list[Segment] = []
     for element in template:
         if isinstance(element, str):
@@ -96,11 +86,10 @@ def _resolve(interpolation: Interpolation[str]) -> str:
         return format(converted, format_spec)
     if conversion is None:
         return str(converted)
-    assert isinstance(converted, str)
     return converted
 
 
-def _reject_nul(resolved: str) -> None:
+def _reject_nul(resolved: str):
     if _NUL in resolved:
         raise ShellSafeTypeError(
             "interpolated value contains a NUL byte after formatting; "

shellsafe-0.3.0/tests/fixtures/audit/au001_sample.py

@@ -0,0 +1,31 @@
+"""AU001 fixture: planted violations and safe twins for the f-string rule."""
+
+import os
+import subprocess
+from os import system
+from subprocess import run as subprocess_run
+
+# --- positive cases (should produce AU001 findings) ---
+
+os.system(f"echo {user_input}")
+
+subprocess.run(f"echo {user_input}", shell=True)
+
+subprocess.call(f"cat {filename}")
+
+system(f"rm -rf {path}")
+
+subprocess_run(f"grep {pattern} {file}")
+
+subprocess.getoutput(f"echo {user_input}")
+
+
+# --- safe cases (should NOT produce findings) ---
+
+subprocess.run(["echo", user_input])
+
+os.system("echo hello")
+
+subprocess.run(["cat", filename], shell=True)
+
+subprocess.run("echo hello")

shellsafe-0.3.0/tests/integration/test_cli_audit.py

@@ -0,0 +1,66 @@
+"""CLI integration tests for the audit command."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+FIXTURES = Path(__file__).parent.parent / "fixtures" / "audit"
+
+
+def test_audit_cli_finds_issues():
+    out = subprocess.run(
+        [sys.executable, "-m", "shellsafe", "audit", str(FIXTURES / "au001_sample.py")],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 1
+    assert "AU001" in out.stdout
+
+
+def test_audit_cli_clean_dir(tmp_path: Path):
+    out = subprocess.run(
+        [sys.executable, "-m", "shellsafe", "audit", str(tmp_path)],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 0
+    assert "no findings" in out.stdout
+
+
+def test_audit_cli_json_output():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "au001_sample.py"),
+            "--json",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 1
+    report = json.loads(out.stdout)
+    assert report["schema_version"] == 1
+    assert report["summary"]["errors"] == 6
+    assert len(report["findings"]) == 6
+
+
+def test_audit_cli_severity_filter():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "au001_sample.py"),
+            "--severity",
+            "info",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 1
+    assert "AU001" in out.stdout

{shellsafe-0.2.0 → shellsafe-0.3.0}/tests/integration/test_exec_posix.py

@@ -7,8 +7,6 @@ import pytest
 from shellsafe import capture, run, shx
 from shellsafe.errors import ArgvOnlyError, ShellSafeError, UnsupportedPlatformError
 
-# --- argv mode ---
-
 
 @pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
 def test_capture_round_trip():
@@ -33,7 +31,6 @@ def test_interpolation_with_spaces_stays_one_argument():
     assert res.stdout.strip() == "two words"
 
 
-# --- shell mode execution ---
 
 
 @pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
@@ -68,7 +65,6 @@ def test_shx_output_capture():
     assert res.stdout.strip() == "WORLD"
 
 
-# --- run() rejects shell mode ---
 
 
 @pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
@@ -77,7 +73,6 @@ def test_run_rejects_shell_metacharacters():
         run(t"echo hello | wc -l")
 
 
-# --- shx rejects argv-only templates ---
 
 
 @pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
@@ -86,7 +81,6 @@ def test_shx_rejects_argv_only_template():
         shx(t"echo hello")
 
 
-# --- Windows policy ---
 
 
 def test_shell_mode_execution_not_yet_available_on_windows():

{shellsafe-0.2.0 → shellsafe-0.3.0}/tests/property/test_invariants.py

@@ -14,7 +14,6 @@ from shellsafe.render import plan
 text_values = st.text(st.characters(blacklist_characters="\x00"), max_size=200)
 
 
-# --- argv mode invariants ---
 
 
 @settings(max_examples=300)
@@ -41,7 +40,6 @@ def test_repr_round_trip_is_byte_stable(value: str):
     assert repr(p1) == repr(p2)
 
 
-# --- shell mode invariants ---
 
 
 @pytest.mark.skipif(sys.platform == "win32", reason="shell mode is posix-only")

shellsafe-0.3.0/tests/unit/test_audit.py

@@ -0,0 +1,56 @@
+"""Audit scanner tests: AU001 rule detection against fixture corpus."""
+
+from pathlib import Path
+
+from shellsafe.audit.scanner import scan
+
+FIXTURES = Path(__file__).parent.parent / "fixtures" / "audit"
+
+
+def test_au001_detects_positive_cases():
+    findings = scan([str(FIXTURES / "au001_sample.py")])
+    au001 = [f for f in findings if f.rule_id == "AU001"]
+    assert len(au001) == 6
+    callees = {f.evidence["callee"] for f in au001}
+    assert "os.system" in callees
+    assert "subprocess.run" in callees
+    assert "subprocess.call" in callees
+    assert "subprocess.getoutput" in callees
+
+
+def test_au001_ignores_safe_cases():
+    findings = scan([str(FIXTURES / "au001_sample.py")])
+    flagged_lines = {f.lineno for f in findings}
+    # safe cases are on lines 26-32; none should appear
+    for line in range(26, 33):
+        assert line not in flagged_lines, f"false positive on line {line}"
+
+
+def test_au001_confidence():
+    findings = scan([str(FIXTURES / "au001_sample.py")])
+    for f in findings:
+        assert f.confidence == 0.95
+
+
+def test_au001_severity():
+    findings = scan([str(FIXTURES / "au001_sample.py")])
+    for f in findings:
+        assert f.severity == "error"
+
+
+def test_scan_returns_sorted():
+    findings = scan([str(FIXTURES / "au001_sample.py")])
+    severities = [f.severity for f in findings]
+    assert severities == ["error"] * len(findings)
+
+
+def test_scan_empty_dir(tmp_path: Path):
+    findings = scan([str(tmp_path)])
+    assert findings == []
+
+
+def test_scan_syntax_error_skipped(tmp_path: Path):
+    bad = tmp_path / "bad.py"
+    bad.write_text("def x(\n")
+    findings = scan([str(tmp_path)])
+    assert findings == []

{shellsafe-0.2.0 → shellsafe-0.3.0}/tests/unit/test_payload_corpus.py

@@ -33,7 +33,6 @@ def payloads() -> list[tuple[str, str]]:
     return out
 
 
-# --- argv mode ---
 
 
 @pytest.mark.parametrize(
@@ -47,7 +46,6 @@ def test_payload_stays_single_argument(name: str, payload: str):
     assert p.argv == ("echo", payload)
 
 
-# --- shell mode ---
 
 
 @pytest.mark.parametrize(

{shellsafe-0.2.0 → shellsafe-0.3.0}/tests/unit/test_render.py

@@ -59,7 +59,6 @@ def test_nested_template_splices():
     assert p.argv == ("git", "commit", "-m", "msg with spaces")
 
 
-# --- refusals ---
 
 
 def test_non_template_refused():
@@ -134,7 +133,6 @@ def test_raw_inside_real_tstring_syntax():
     assert p.argv == ("echo", "a", "b", "done")
 
 
-# --- shell route: rendering works now; execution arrives in 0.2 ---
 
 
 @pytest.mark.skipif(

shellsafe-0.2.0/src/shellsafe/_version.py

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

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

@@ -1,10 +0,0 @@
-"""Offline AST audit for dangerous command construction. Ships with v0.3.0."""
-
-from __future__ import annotations
-
-from ..errors import ShellSafeError
-
-
-def scan(paths: list[str]) -> list[dict[str, object]]:
-    """Scan paths for AU001-AU004 findings. Arrives in shellsafe 0.3."""
-    raise ShellSafeError("audit arrives in shellsafe 0.3")

shellsafe-0.2.0/src/shellsafe/cli.py

@@ -1,44 +0,0 @@
-"""CLI wiring: audit, demo, version. Business logic lives in the stages."""
-
-from __future__ import annotations
-
-import argparse
-import platform
-import sys
-
-from . import exitcodes
-from ._version import __version__
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="shellsafe")
-    parser.add_argument("-V", "--version", action="store_true")
-    sub = parser.add_subparsers(dest="command")
-
-    sub.add_parser("audit", help="scan code for dangerous command construction (v0.3)")
-    sub.add_parser("version", help="detailed version and capability matrix")
-    return parser
-
-
-def _print_version_matrix() -> None:
-    py = platform.python_version()
-    print(f"shellsafe {__version__} · python {py} · {sys.platform}")
-    print("argv-mode: available")
-    print("shell-mode: available (posix)")
-    print("audit: arriving in 0.3")
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = _build_parser().parse_args(argv)
-
-    if args.version:
-        print(f"shellsafe {__version__}")
-        return exitcodes.OK
-    if args.command == "version":
-        _print_version_matrix()
-        return exitcodes.OK
-    if args.command == "audit":
-        print("audit arrives in shellsafe 0.3", file=sys.stderr)
-        return exitcodes.USAGE
-    _build_parser().print_help()
-    return exitcodes.OK

shellsafe-0.2.0/src/shellsafe/platforms.py

@@ -1,35 +0,0 @@
-"""Platform policy tables and helpers. This module IS the security policy."""
-
-from __future__ import annotations
-
-import sys
-
-# Static template text containing any of these routes the command to shell mode.
-# Whitespace is not here: it splits words in argv mode.
-METACHARACTERS: frozenset[str] = 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 when shell features are requested on Windows;
-    cmd.exe quoting cannot be made injection-safe, so the refusal is the feature.
-    """
-    has_meta = any(ch in METACHARACTERS for ch in static_text)
-    if not has_meta:
-        return "argv"
-    if IS_WINDOWS:
-        raise _windows_error()
-    return "shell"
-
-
-def _windows_error() -> Exception:
-    from .errors import UnsupportedPlatformError
-
-    return 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."
-    )

shellsafe-0.2.0/src/shellsafe/reporters.py

@@ -1 +0,0 @@
-"""Finding reporters: terminal and json. Arrives in shellsafe 0.3."""