shellsafe 0.3.1__tar.gz → 0.3.2__tar.gz

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

@@ -3,6 +3,22 @@
 All notable changes to this project are documented here. Format follows
 Keep a Changelog; versioning follows SemVer.
 
+## [0.3.2] - 2026-08-30
+
+### Added
+
+- AU003 rule: detect command-string assembly (variable, concatenation,
+  .format(), f-string passed as command to shell executor)
+- AU004 rule: detect subprocess calls without timeout (info severity)
+- AU003 fixture corpus: 6 positive cases + 3 safe cases
+- AU004 fixture corpus: 5 positive cases + 4 safe cases
+- Unit tests for AU003 and AU004 detection
+- Integration tests for CLI audit with AU003 and AU004
+
+### Changed
+
+- CLI version string shows "AU001-AU004" instead of "AU001"
+
 ## [0.3.1] - 2026-08-30
 
 ### Added

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

@@ -1,7 +1,8 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.3.1
+Version: 0.3.2
 Summary: Run shell commands safely using Python 3.14 template strings. Values can never turn into commands.
+Project-URL: Homepage, https://github.com/rahulXs/shellsafe
 Project-URL: Repository, https://github.com/rahulXs/shellsafe
 Project-URL: Issues, https://github.com/rahulXs/shellsafe/issues
 Project-URL: Changelog, https://github.com/rahulXs/shellsafe/blob/main/CHANGELOG.md

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

@@ -30,6 +30,7 @@ dependencies = []
 shellsafe = "shellsafe.cli:main"
 
 [project.urls]
+Homepage = "https://github.com/rahulXs/shellsafe"
 Repository = "https://github.com/rahulXs/shellsafe"
 Issues = "https://github.com/rahulXs/shellsafe/issues"
 Changelog = "https://github.com/rahulXs/shellsafe/blob/main/CHANGELOG.md"

shellsafe-0.3.2/src/shellsafe/_version.py

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

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

@@ -155,9 +155,142 @@ def au002(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
     return None
 
 
+def _track_dynamic_vars(tree: ast.Module) -> set[str]:
+    """Find variables assigned dynamic string expressions."""
+    dynamic: set[str] = {}
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assign):
+            continue
+        if not _is_dynamic_string(node.value):
+            continue
+        for target in node.targets:
+            if isinstance(target, ast.Name):
+                dynamic.add(target.id)
+    return dynamic
+
+
+def au003(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
+    """Command string built by assembly passed to shell executor."""
+    callee = _resolve_callee(node.func, aliases)
+    if callee is None:
+        return None
+    for arg in node.args:
+        if isinstance(arg, ast.Name):
+            return Finding(
+                rule_id="AU003",
+                title="command string passed to shell executor",
+                severity="warning",
+                confidence=0.80,
+                path=path,
+                lineno=node.lineno,
+                col=node.col_offset,
+                message=f"{callee} receives variable '{arg.id}' as command string",
+                evidence={
+                    "callee": callee,
+                    "var": arg.id,
+                },
+                fix_hint='use shellsafe.run(t"...") or pass an argv list',
+            )
+        if isinstance(arg, ast.BinOp) and isinstance(arg.op, ast.Add):
+            return Finding(
+                rule_id="AU003",
+                title="command string passed to shell executor",
+                severity="warning",
+                confidence=0.85,
+                path=path,
+                lineno=node.lineno,
+                col=node.col_offset,
+                message=f"{callee} receives concatenated string as command",
+                evidence={
+                    "callee": callee,
+                    "kind": "concatenation",
+                },
+                fix_hint='use shellsafe.run(t"...") or pass an argv list',
+            )
+        if (
+            isinstance(arg, ast.Call)
+            and isinstance(arg.func, ast.Attribute)
+            and arg.func.attr == "format"
+        ):
+            return Finding(
+                rule_id="AU003",
+                title="command string passed to shell executor",
+                severity="warning",
+                confidence=0.85,
+                path=path,
+                lineno=node.lineno,
+                col=node.col_offset,
+                message=f"{callee} receives .format() result as command string",
+                evidence={
+                    "callee": callee,
+                    "kind": ".format()",
+                },
+                fix_hint='use shellsafe.run(t"...") or pass an argv list',
+            )
+        if (
+            isinstance(arg, ast.JoinedStr)
+            and any(isinstance(v, ast.FormattedValue) for v in arg.values)
+        ):
+            return Finding(
+                rule_id="AU003",
+                title="command string passed to shell executor",
+                severity="error",
+                confidence=0.95,
+                path=path,
+                lineno=node.lineno,
+                col=node.col_offset,
+                message=f"{callee} receives f-string as command string",
+                evidence={
+                    "callee": callee,
+                    "kind": "f-string",
+                },
+                fix_hint='use shellsafe.run(t"...") or pass an argv list',
+            )
+    return None
+
+
+def _has_timeout(node: ast.Call) -> bool:
+    return any(kw.arg == "timeout" for kw in node.keywords)
+
+
+_EXECUTORS_WITH_TIMEOUT = {
+    "subprocess.run",
+    "subprocess.call",
+    "subprocess.check_call",
+    "subprocess.check_output",
+}
+
+
+def au004(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
+    """Subprocess call without timeout."""
+    callee = _resolve_callee(node.func, aliases)
+    if callee is None:
+        return None
+    if callee not in _EXECUTORS_WITH_TIMEOUT:
+        return None
+    if _has_timeout(node):
+        return None
+    return Finding(
+        rule_id="AU004",
+        title="subprocess call without timeout",
+        severity="info",
+        confidence=0.95,
+        path=path,
+        lineno=node.lineno,
+        col=node.col_offset,
+        message=f"{callee} has no timeout parameter",
+        evidence={
+            "callee": callee,
+        },
+        fix_hint="add timeout= to prevent hanging",
+    )
+
+
 RULES: list[tuple[str, Callable[..., Finding | None]]] = [
     ("AU001", au001),
     ("AU002", au002),
+    ("AU003", au003),
+    ("AU004", au004),
 ]
 
 
@@ -178,7 +311,7 @@ def _discover(paths: list[str]) -> list[Path]:
 
 def _import_aliases(tree: ast.Module) -> dict[str, str]:
     """Map local names to real module.function for executor imports."""
-    aliases: dict[str, str] = {}
+    aliases = {}
     for node in ast.walk(tree):
         if isinstance(node, ast.Import):
             for alias in node.names:

{shellsafe-0.3.1 → shellsafe-0.3.2}/src/shellsafe/cli.py

@@ -62,7 +62,7 @@ def main(argv: list[str] | None = None) -> int:
         print(f"shellsafe {__version__} . python {py} . {sys.platform}")
         print("argv-mode: available")
         print("shell-mode: available (posix)")
-        print("audit: available (AU001)")
+        print("audit: available (AU001-AU004)")
         return exitcodes.OK
     if args.command == "audit":
         return _run_audit(args)

shellsafe-0.3.2/tests/fixtures/audit/au003_sample.py

@@ -0,0 +1,37 @@
+"""AU003 fixture: planted violations and safe twins for command-string assembly."""
+
+import os
+import subprocess
+
+# --- positive cases (should produce AU003 findings) ---
+
+# variable passed to executor
+cmd = "echo " + user_input
+os.system(cmd)
+
+# concatenation in call
+os.system("echo " + user_input)
+
+# .format() in call
+os.system("echo {}".format(user_input))  # noqa: UP032
+
+# f-string in call (also AU001)
+os.system(f"echo {user_input}")
+
+# variable with subprocess
+subprocess.run(cmd)
+
+# concatenation with subprocess
+subprocess.run("echo " + user_input)
+
+
+# --- safe cases (should NOT produce AU003 findings) ---
+
+# list form (safe)
+subprocess.run(["echo", user_input])
+
+# static string
+os.system("echo hello")
+
+# argv list
+subprocess.run(["git", "commit", "-m", "fix"])

shellsafe-0.3.2/tests/fixtures/audit/au004_sample.py

@@ -0,0 +1,28 @@
+"""AU004 fixture: planted violations and safe twins for missing timeout."""
+
+import subprocess
+from subprocess import run as subprocess_run
+
+# --- positive cases (should produce AU004 findings) ---
+
+subprocess.run(["echo", "hello"])
+
+subprocess.call(["echo", "hello"])
+
+subprocess.check_call(["echo", "hello"])
+
+subprocess.check_output(["echo", "hello"])
+
+subprocess_run(["echo", "hello"])
+
+
+# --- safe cases (should NOT produce AU004 findings) ---
+
+subprocess.run(["echo", "hello"], timeout=10)
+
+subprocess.call(["echo", "hello"], timeout=5)
+
+subprocess.check_output(["echo", "hello"], timeout=30)
+
+# Popen does not have timeout in the same way
+subprocess.Popen(["echo", "hello"])

{shellsafe-0.3.1 → shellsafe-0.3.2}/tests/integration/test_cli_audit.py

@@ -46,7 +46,7 @@ def test_audit_cli_json_output():
     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
+    assert report["summary"]["errors"] >= 6
 
 
 def test_audit_cli_severity_filter():
@@ -134,3 +134,72 @@ def test_audit_cli_both_rules():
     rule_ids = {f["rule_id"] for f in report["findings"]}
     assert "AU001" in rule_ids
     assert "AU002" in rule_ids
+
+
+def test_audit_cli_au003_finds_issues():
+    out = subprocess.run(
+        [sys.executable, "-m", "shellsafe", "audit", str(FIXTURES / "au003_sample.py")],
+        capture_output=True,
+        text=True,
+    )
+    assert out.returncode == 1
+    assert "AU003" in out.stdout
+
+
+def test_audit_cli_au004_finds_issues():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "au004_sample.py"),
+            "--severity",
+            "info",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    # AU004 is info severity, exit code 0 (no errors)
+    assert "AU004" in out.stdout
+    assert "subprocess.run has no timeout" in out.stdout
+
+
+def test_audit_cli_au004_severity_filter():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "au004_sample.py"),
+            "--severity",
+            "warning",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    # AU004 is info severity, should be excluded when filtering by warning
+    assert "AU004" not in out.stdout
+
+
+def test_audit_cli_all_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
+    assert "AU003" in rule_ids
+    assert "AU004" in rule_ids

{shellsafe-0.3.1 → shellsafe-0.3.2}/tests/unit/test_audit.py

@@ -1,4 +1,4 @@
-"""Audit scanner tests: AU001 and AU002 rule detection against fixture corpus."""
+"""Audit scanner tests: AU001-AU004 rule detection against fixture corpus."""
 
 from pathlib import Path
 
@@ -20,10 +20,9 @@ def test_au001_detects_positive_cases():
 
 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
+    au001_lines = {f.lineno for f in findings if f.rule_id == "AU001"}
     for line in range(26, 33):
-        assert line not in flagged_lines, f"false positive on line {line}"
+        assert line not in au001_lines, f"false positive on line {line}"
 
 
 def test_au001_confidence():
@@ -88,8 +87,8 @@ 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
+    non_errors = [s for s in severities if s != "error"]
+    assert severities == errors + non_errors
 
 
 def test_scan_empty_dir(tmp_path: Path):
@@ -102,3 +101,67 @@ def test_scan_syntax_error_skipped(tmp_path: Path):
     bad.write_text("def x(\n")
     findings = scan([str(tmp_path)])
     assert findings == []
+
+
+def test_au003_detects_positive_cases():
+    findings = scan([str(FIXTURES / "au003_sample.py")])
+    au003 = [f for f in findings if f.rule_id == "AU003"]
+    assert len(au003) == 6
+    callees = {f.evidence["callee"] for f in au003}
+    assert "os.system" in callees
+    assert "subprocess.run" in callees
+
+
+def test_au003_ignores_safe_cases():
+    findings = scan([str(FIXTURES / "au003_sample.py")])
+    au003_lines = {f.lineno for f in findings if f.rule_id == "AU003"}
+    for line in range(32, 40):
+        assert line not in au003_lines, f"false positive on line {line}"
+
+
+def test_au003_severity():
+    findings = scan([str(FIXTURES / "au003_sample.py")])
+    au003 = [f for f in findings if f.rule_id == "AU003"]
+    for f in au003:
+        assert f.severity in ("warning", "error")
+
+
+def test_au004_detects_positive_cases():
+    findings = scan([str(FIXTURES / "au004_sample.py")])
+    au004 = [f for f in findings if f.rule_id == "AU004"]
+    assert len(au004) == 5
+    callees = {f.evidence["callee"] for f in au004}
+    assert "subprocess.run" in callees
+    assert "subprocess.call" in callees
+    assert "subprocess.check_call" in callees
+    assert "subprocess.check_output" in callees
+
+
+def test_au004_ignores_safe_cases():
+    findings = scan([str(FIXTURES / "au004_sample.py")])
+    au004_lines = {f.lineno for f in findings if f.rule_id == "AU004"}
+    for line in range(21, 29):
+        assert line not in au004_lines, f"false positive on line {line}"
+
+
+def test_au004_severity():
+    findings = scan([str(FIXTURES / "au004_sample.py")])
+    au004 = [f for f in findings if f.rule_id == "AU004"]
+    for f in au004:
+        assert f.severity == "info"
+
+
+def test_au004_confidence():
+    findings = scan([str(FIXTURES / "au004_sample.py")])
+    au004 = [f for f in findings if f.rule_id == "AU004"]
+    for f in au004:
+        assert f.confidence == 0.95
+
+
+def test_all_rules_found():
+    findings = scan([str(FIXTURES)])
+    rule_ids = {f.rule_id for f in findings}
+    assert "AU001" in rule_ids
+    assert "AU002" in rule_ids
+    assert "AU003" in rule_ids
+    assert "AU004" in rule_ids

shellsafe-0.3.1/src/shellsafe/_version.py

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