shellsafe 0.3.0__tar.gz → 0.3.1__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.3.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

{shellsafe-0.3.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

shellsafe-0.3.1/src/shellsafe/_version.py

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

{shellsafe-0.3.0 → shellsafe-0.3.1}/src/shellsafe/audit/scanner.py

@@ -98,8 +98,66 @@ def au001(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
     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),
 ]
 
 

shellsafe-0.3.1/tests/fixtures/audit/au002_sample.py

@@ -0,0 +1,41 @@
+"""AU002 fixture: planted violations and safe twins for shell=True rule."""
+
+import subprocess
+
+# --- positive cases (should produce AU002 findings) ---
+
+# f-string with shell=True (also caught by AU001)
+subprocess.run(f"echo {user_input}", shell=True)
+
+# .format() with shell=True
+subprocess.run("echo {}".format(name), shell=True)  # noqa: UP032
+
+# string concatenation with shell=True
+subprocess.run("echo " + name, shell=True)
+
+# %-format with shell=True
+subprocess.run("echo %s" % name, shell=True)  # noqa: UP031
+
+# variable with shell=True
+subprocess.run(cmd, shell=True)
+
+# attribute with shell=True
+subprocess.run(config.command, shell=True)
+
+
+# --- safe cases (should NOT produce AU002 findings) ---
+
+# shell=True with list (safe)
+subprocess.run(["echo", user_input], shell=True)
+
+# shell=True with static string (safe)
+subprocess.run("echo hello", shell=True)
+
+# no shell=True with f-string (AU001, not AU002)
+subprocess.run(f"echo {user_input}")
+
+# no shell=True with variable (safe)
+subprocess.run(cmd)
+
+# shell=False explicitly
+subprocess.run("echo hello", shell=False)

shellsafe-0.3.1/tests/integration/test_cli_audit.py

@@ -0,0 +1,136 @@
+"""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
+    au001_findings = [f for f in report["findings"] if f["rule_id"] == "AU001"]
+    assert len(au001_findings) == 6
+    assert report["summary"]["errors"] == 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
+
+
+def test_audit_cli_au002_finds_issues():
+    out = subprocess.run(
+        [sys.executable, "-m", "shellsafe", "audit", str(FIXTURES / "au002_sample.py")],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 1
+    assert "AU002" in out.stdout
+
+
+def test_audit_cli_au002_json_output():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "au002_sample.py"),
+            "--json",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 1
+    report = json.loads(out.stdout)
+    au002_findings = [f for f in report["findings"] if f["rule_id"] == "AU002"]
+    assert len(au002_findings) == 6
+    assert report["summary"]["warnings"] >= 6
+
+
+def test_audit_cli_au002_severity_filter():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "au002_sample.py"),
+            "--severity",
+            "error",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    # au002_sample.py has an f-string with shell=True (line 12) caught by AU001
+    # but AU002 warnings should be excluded
+    assert "AU002" not in out.stdout
+
+
+def test_audit_cli_both_rules():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES),
+            "--json",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 1
+    report = json.loads(out.stdout)
+    rule_ids = {f["rule_id"] for f in report["findings"]}
+    assert "AU001" in rule_ids
+    assert "AU002" in rule_ids

shellsafe-0.3.1/tests/unit/test_audit.py

@@ -0,0 +1,104 @@
+"""Audit scanner tests: AU001 and AU002 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")])
+    au001 = [f for f in findings if f.rule_id == "AU001"]
+    for f in au001:
+        assert f.confidence == 0.95
+
+
+def test_au001_severity():
+    findings = scan([str(FIXTURES / "au001_sample.py")])
+    au001 = [f for f in findings if f.rule_id == "AU001"]
+    for f in au001:
+        assert f.severity == "error"
+
+
+def test_au002_detects_positive_cases():
+    findings = scan([str(FIXTURES / "au002_sample.py")])
+    au002 = [f for f in findings if f.rule_id == "AU002"]
+    assert len(au002) == 6
+    kinds = {f.evidence["kind"] for f in au002}
+    assert "f-string" in kinds
+    assert ".format() call" in kinds
+    assert "string concatenation" in kinds
+    assert "%-format string" in kinds
+    assert "variable" in kinds
+
+
+def test_au002_ignores_safe_cases():
+    findings = scan([str(FIXTURES / "au002_sample.py")])
+    au002_lines = {f.lineno for f in findings if f.rule_id == "AU002"}
+    # safe cases are on lines 28-38; none should appear
+    for line in range(28, 39):
+        assert line not in au002_lines, f"false positive on line {line}"
+
+
+def test_au002_confidence():
+    findings = scan([str(FIXTURES / "au002_sample.py")])
+    au002 = [f for f in findings if f.rule_id == "AU002"]
+    for f in au002:
+        assert f.confidence == 0.90
+
+
+def test_au002_severity():
+    findings = scan([str(FIXTURES / "au002_sample.py")])
+    au002 = [f for f in findings if f.rule_id == "AU002"]
+    for f in au002:
+        assert f.severity == "warning"
+
+
+def test_au002_does_not_flag_au001_cases():
+    findings = scan([str(FIXTURES / "au001_sample.py")])
+    au002 = [f for f in findings if f.rule_id == "AU002"]
+    # line 12 has shell=True with f-string, AU002 correctly flags it too
+    # but lines without shell=True should not be flagged
+    au002_lines = {f.lineno for f in au002}
+    assert 12 in au002_lines
+    assert len(au002) == 1
+
+
+def test_scan_returns_sorted():
+    findings = scan([str(FIXTURES / "au002_sample.py")])
+    severities = [f.severity for f in findings]
+    errors = [s for s in severities if s == "error"]
+    warnings = [s for s in severities if s == "warning"]
+    assert errors + warnings == severities
+
+
+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.3.0/src/shellsafe/_version.py

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

shellsafe-0.3.0/tests/integration/test_cli_audit.py

@@ -1,66 +0,0 @@
-"""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.3.0/tests/unit/test_audit.py

@@ -1,56 +0,0 @@
-"""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 == []