shellsafe 0.1.0__tar.gz

shellsafe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental == true }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, python: "3.14" }
+          - { os: ubuntu-latest, python: "3.14t", experimental: true }
+          - { os: macos-latest, python: "3.14" }
+          - { os: windows-latest, python: "3.14" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run pytest -q
+      - run: uv run ruff check .
+      - run: uv run mypy src/

shellsafe-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv run twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

shellsafe-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+.lazyfix/

shellsafe-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+Keep a Changelog; versioning follows SemVer.
+
+## [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.0/CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+Issues and PRs welcome.
+
+1. Run the verification commands (pytest, ruff, mypy) after every change; PRs
+   must arrive green.
+2. Security-relevant changes require corpus or property coverage in the same PR.
+3. Commit subjects follow Conventional Commits.
+4. Prose follows plain technical writing: no marketing adjectives, state limits.
+
+Report security vulnerabilities privately to the maintainer address in
+pyproject.toml; do not open public issues.

shellsafe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul Sharma (rahulXs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shellsafe-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: shellsafe
+Version: 0.1.0
+Summary: Safe shell commands via Python 3.14 template strings. Injection-proof by construction.
+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
+Author-email: Rahul Sharma <rahulxsh@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,command-injection,injection,pep750,security,shell,subprocess,t-strings,template-strings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# shellsafe
+
+> Safe shell commands via Python 3.14 template strings. Injection-proof by
+> construction.
+
+```python
+from shellsafe import run
+
+message = get_user_input()          # "fix; rm -rf ~"
+run(t"git commit -m {message}")
+# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
+# one command; the scary text is just an argument
+```
+
+## Why
+
+The dominant pattern in scripts and automation is still this:
+
+```python
+subprocess.run(f"git commit -m {message}", shell=True)   # injection waiting to happen
+```
+
+Python 3.14 template strings (`t"..."`) separate static text from interpolated
+values. shellsafe turns that structure into argv lists where interpolated values
+are always data, never commands. When you genuinely need pipes, shell mode quotes
+every value with POSIX rules first.
+
+## Install
+
+```bash
+pip install shellsafe
+```
+
+Requires Python 3.14+ (template strings).
+
+## Usage
+
+Run a command. Interpolated values are always single arguments:
+
+```python
+from shellsafe import run
+
+run(t"mkdir {path}")
+run(t"docker build -t {tag} .", check=True, timeout=300)
+```
+
+Capture output as text:
+
+```python
+from shellsafe import capture
+
+res = capture(t"grep {pattern} {file}")
+print(res.stdout, res.returncode)
+```
+
+Pipes and redirections on POSIX (values are quoted with `shlex.quote` first):
+
+```python
+from shellsafe import shx
+
+shx(t"cat {file} | wc -l")
+```
+
+Inspect exactly what will execute:
+
+```python
+from shellsafe import plan  # lower-level: render without running
+
+print(plan(t"git commit -m {message}"))
+# argv: ["git","commit","-m","fix; rm -rf ~"]
+```
+
+## What it refuses
+
+| Case | Behavior |
+|---|---|
+| Interpolation as the executable | error: the command comes from static text only |
+| Shell route on Windows | error: cmd.exe quoting cannot be made injection-safe; use argv mode |
+| RAW misuse | error: one argument, verbatim, nesting refused |
+
+`RAW("...")` / `RAW(["a", "b"])` is the single explicit trust boundary for
+pre-quoted content. Every use site is greppable.
+
+## Limits
+
+- Windows: interpolated shell routes are refused rather than approximated;
+  argv-mode commands work fully.
+- Bytes interpolations are rejected: decode explicitly first.
+- Runtime behavior after import is your test suite's job, same trust model as
+  calling subprocess yourself.
+
+## Contributing
+
+Issues and PRs welcome. Security reports go privately to the maintainer, never
+through public issues.
+
+## Requirements
+
+- CPython >= 3.14 (uses template strings from PEP 750)
+- Linux, macOS, Windows (Windows supports argv mode; POSIX-only shell mode)
+
+## License
+
+MIT

shellsafe-0.1.0/README.md

@@ -0,0 +1,104 @@
+# shellsafe
+
+> Safe shell commands via Python 3.14 template strings. Injection-proof by
+> construction.
+
+```python
+from shellsafe import run
+
+message = get_user_input()          # "fix; rm -rf ~"
+run(t"git commit -m {message}")
+# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
+# one command; the scary text is just an argument
+```
+
+## Why
+
+The dominant pattern in scripts and automation is still this:
+
+```python
+subprocess.run(f"git commit -m {message}", shell=True)   # injection waiting to happen
+```
+
+Python 3.14 template strings (`t"..."`) separate static text from interpolated
+values. shellsafe turns that structure into argv lists where interpolated values
+are always data, never commands. When you genuinely need pipes, shell mode quotes
+every value with POSIX rules first.
+
+## Install
+
+```bash
+pip install shellsafe
+```
+
+Requires Python 3.14+ (template strings).
+
+## Usage
+
+Run a command. Interpolated values are always single arguments:
+
+```python
+from shellsafe import run
+
+run(t"mkdir {path}")
+run(t"docker build -t {tag} .", check=True, timeout=300)
+```
+
+Capture output as text:
+
+```python
+from shellsafe import capture
+
+res = capture(t"grep {pattern} {file}")
+print(res.stdout, res.returncode)
+```
+
+Pipes and redirections on POSIX (values are quoted with `shlex.quote` first):
+
+```python
+from shellsafe import shx
+
+shx(t"cat {file} | wc -l")
+```
+
+Inspect exactly what will execute:
+
+```python
+from shellsafe import plan  # lower-level: render without running
+
+print(plan(t"git commit -m {message}"))
+# argv: ["git","commit","-m","fix; rm -rf ~"]
+```
+
+## What it refuses
+
+| Case | Behavior |
+|---|---|
+| Interpolation as the executable | error: the command comes from static text only |
+| Shell route on Windows | error: cmd.exe quoting cannot be made injection-safe; use argv mode |
+| RAW misuse | error: one argument, verbatim, nesting refused |
+
+`RAW("...")` / `RAW(["a", "b"])` is the single explicit trust boundary for
+pre-quoted content. Every use site is greppable.
+
+## Limits
+
+- Windows: interpolated shell routes are refused rather than approximated;
+  argv-mode commands work fully.
+- Bytes interpolations are rejected: decode explicitly first.
+- Runtime behavior after import is your test suite's job, same trust model as
+  calling subprocess yourself.
+
+## Contributing
+
+Issues and PRs welcome. Security reports go privately to the maintainer, never
+through public issues.
+
+## Requirements
+
+- CPython >= 3.14 (uses template strings from PEP 750)
+- Linux, macOS, Windows (Windows supports argv mode; POSIX-only shell mode)
+
+## License
+
+MIT

shellsafe-0.1.0/examples/demo.py

@@ -0,0 +1,33 @@
+"""Side-by-side demo: the classic injection, rendered inert.
+
+Run from an environment where shellsafe is importable:
+
+    python examples/demo.py
+"""
+
+import sys
+from pathlib import Path
+from string.templatelib import Interpolation, Template
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from shellsafe.render import plan
+
+
+def main() -> int:
+    message = "fix; rm -rf ~"
+
+    print("UNSAFE (f-string into a shell):")
+    print(f"  $ git commit -m {message}")
+    print("  -> two commands; the second one deletes your home directory")
+    print()
+
+    print("SAFE (shellsafe):")
+    p = plan(Template("git commit -m ", Interpolation(message, "message", None, "")))
+    print(f"  $ {p!r}")
+    print("  -> one command; the scary text is just an argument")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shellsafe-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shellsafe"
+dynamic = ["version"]
+description = "Safe shell commands via Python 3.14 template strings. Injection-proof by construction."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+authors = [{ name = "Rahul Sharma", email = "rahulxsh@gmail.com" }]
+keywords = [
+    "shell", "subprocess", "injection", "security", "template-strings",
+    "t-strings", "pep750", "command-injection", "automation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.scripts]
+shellsafe = "shellsafe.cli:main"
+
+[project.urls]
+Repository = "https://github.com/rahulXs/shellsafe"
+Issues = "https://github.com/rahulXs/shellsafe/issues"
+Changelog = "https://github.com/rahulXs/shellsafe/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/shellsafe/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shellsafe"]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+python_version = "3.14"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --tb=short"
+
+[tool.ruff.lint.per-file-ignores]
+# RAW() is a deliberate loud trust marker; the uppercase name is the API.
+"src/shellsafe/raw.py" = ["N802"]
+"src/shellsafe/__init__.py" = ["N999"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "hypothesis>=6",
+    "build>=1.2",
+    "twine>=6",
+]

shellsafe-0.1.0/src/shellsafe/__init__.py

@@ -0,0 +1,18 @@
+"""shellsafe: safe shell commands via Python 3.14 template strings.
+
+Public surface (stable names, additive only through 1.0):
+run, capture, shx, RAW, CaptureResult.
+"""
+
+from ._version import __version__
+from .execute import CaptureResult, capture, run, shx
+from .raw import RAW
+
+__all__ = [
+    "RAW",
+    "CaptureResult",
+    "__version__",
+    "capture",
+    "run",
+    "shx",
+]

shellsafe-0.1.0/src/shellsafe/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

shellsafe-0.1.0/src/shellsafe/_version.py

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

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

@@ -0,0 +1,10 @@
+"""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.1.0/src/shellsafe/cli.py

@@ -0,0 +1,44 @@
+"""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: arriving in 0.2")
+    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.1.0/src/shellsafe/errors.py

@@ -0,0 +1,36 @@
+"""Exception hierarchy for shellsafe.
+
+Every error raised publicly inherits from ShellSafeError so callers can catch
+broadly. Messages are lowercase, state got and expected, and include the fix.
+"""
+
+
+class ShellSafeError(Exception):
+    """Base class for every error shellsafe raises."""
+
+
+class ShellSafeTypeError(ShellSafeError):
+    """A template or interpolated value has an unsupported type."""
+
+
+class UnsupportedPlatformError(ShellSafeError):
+    """The requested shell route cannot be made safe on this platform.
+
+    Interpolated shell routes are refused on Windows by policy; restructure the
+    command as argv mode (no pipes or redirections) instead.
+    """
+
+
+class ArgvOnlyError(ShellSafeError):
+    """shx() was called with a template that needs no shell at all.
+
+    Use run() for plain commands; shx() exists for pipes and redirections.
+    """
+
+
+class RawUsageError(ShellSafeError):
+    """RAW() was used incorrectly.
+
+    RAW takes exactly one argument: a list of strings in argv mode or a string
+    in shell mode. RAW values are never nested and never modified.
+    """