sshscript 2.0.2__tar.gz → 3.1.4__tar.gz

sshscript-3.1.4/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    target-branch: release
+    schedule:
+      interval: weekly
+    groups:
+      python-patch-and-minor:
+        patterns:
+          - "*"
+        update-types:
+          - patch
+          - minor
+
+  - package-ecosystem: github-actions
+    directory: /
+    target-branch: release
+    schedule:
+      interval: weekly
+    groups:
+      actions-patch-and-minor:
+        patterns:
+          - "*"
+        update-types:
+          - patch
+          - minor

sshscript-3.1.4/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  verify:
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test and build dependencies
+        run: python -m pip install 'paramiko>=2.11,<5' 'packaging>=21' build twine
+      - name: Test source
+        run: python tools/run_checks.py
+      - name: Build and verify installed release
+        run: python tools/check_release.py --output '${{ runner.temp }}/verified-artifacts'
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: sshscript-${{ matrix.os }}-${{ matrix.python-version }}
+          path: ${{ runner.temp }}/verified-artifacts/
+
+  openssh-integration:
+    name: OpenSSH integration (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test and build dependencies
+        run: python -m pip install 'paramiko>=2.11,<5' 'packaging>=21' build twine
+      - name: Build and verify wheel
+        run: python tools/check_release.py --output "$RUNNER_TEMP/verified-artifacts"
+      - name: Install verified wheel
+        run: python -m pip install --force-reinstall "$RUNNER_TEMP"/verified-artifacts/*.whl
+      - name: Provision loopback OpenSSH server
+        run: bash tools/setup_openssh_ci.sh "$GITHUB_ENV"
+      - name: Test installed wheel against OpenSSH
+        run: |
+          mkdir -p "$RUNNER_TEMP/openssh-tests"
+          cp src/sshscript/unittest/test_openssh_integration.py "$RUNNER_TEMP/openssh-tests/"
+          cd "$RUNNER_TEMP/openssh-tests"
+          python -I test_openssh_integration.py -v
+      - name: Upload OpenSSH server log
+        if: ${{ failure() && env.SSHSCRIPT_OPENSSH_LOG != '' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: openssh-log-python-${{ matrix.python-version }}
+          if-no-files-found: warn
+          path: ${{ env.SSHSCRIPT_OPENSSH_LOG }}
+      - name: Remove disposable OpenSSH state
+        if: always()
+        run: |
+          if [[ -n "${SSHSCRIPT_OPENSSH_PID_FILE:-}" && -s "$SSHSCRIPT_OPENSSH_PID_FILE" ]]; then
+            sudo kill "$(cat "$SSHSCRIPT_OPENSSH_PID_FILE")" || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_SUDOERS:-}" ]]; then
+            sudo rm -f "$SSHSCRIPT_OPENSSH_SUDOERS"
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_TARGET_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_TARGET_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_ROOT:-}" && "$SSHSCRIPT_OPENSSH_ROOT" == "$RUNNER_TEMP"/sshscript-openssh.* ]]; then
+            sudo rm -rf -- "$SSHSCRIPT_OPENSSH_ROOT"
+          fi

sshscript-3.1.4/.github/workflows/codeql.yml

@@ -0,0 +1,30 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [release]
+  pull_request:
+    branches: [release]
+  schedule:
+    - cron: "17 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: CodeQL (Python and Actions)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4
+        with:
+          languages: python, actions
+      - uses: github/codeql-action/analyze@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4

sshscript-3.1.4/.github/workflows/release.yml

@@ -0,0 +1,214 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Verify and attest release artifacts
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.11"
+      - name: Install pinned build dependencies
+        run: >-
+          python -m pip install
+          'paramiko>=2.11,<5' 'packaging>=21'
+          'build==1.6.1' 'twine==7.0.0'
+      - name: Verify tag targets the current release branch
+        run: |
+          git fetch --no-tags --depth=1 origin release
+          test "$(git rev-parse HEAD)" = "$(git rev-parse FETCH_HEAD)"
+      - name: Verify tag and package version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          PACKAGE_VERSION=$(python -c "import runpy; print(runpy.run_path('src/sshscript/_version.py')['__version__'])")
+          test "$RELEASE_TAG" = "v$PACKAGE_VERSION"
+      - name: Stabilize build timestamps
+        run: echo "SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD)" >> "$GITHUB_ENV"
+      - name: Run release gates and build verified artifacts
+        run: |
+          python tools/run_checks.py
+          python tools/check_release.py --output "$RUNNER_TEMP/sshscript-release"
+      - name: Attest wheel and source distribution
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4
+        with:
+          subject-path: |
+            ${{ runner.temp }}/sshscript-release/*.whl
+            ${{ runner.temp }}/sshscript-release/*.tar.gz
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: python-package-distributions
+          if-no-files-found: error
+          path: ${{ runner.temp }}/sshscript-release/
+
+  openssh-integration:
+    name: Release OpenSSH integration (Python ${{ matrix.python-version }})
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Install verified wheel
+        run: python -m pip install dist/*.whl
+      - name: Provision loopback OpenSSH server
+        run: bash tools/setup_openssh_ci.sh "$GITHUB_ENV"
+      - name: Test installed wheel against OpenSSH
+        run: |
+          mkdir -p "$RUNNER_TEMP/openssh-tests"
+          cp src/sshscript/unittest/test_openssh_integration.py "$RUNNER_TEMP/openssh-tests/"
+          cd "$RUNNER_TEMP/openssh-tests"
+          python -I test_openssh_integration.py -v
+      - name: Upload OpenSSH server log
+        if: ${{ failure() && env.SSHSCRIPT_OPENSSH_LOG != '' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: release-openssh-log-python-${{ matrix.python-version }}
+          if-no-files-found: warn
+          path: ${{ env.SSHSCRIPT_OPENSSH_LOG }}
+      - name: Remove disposable OpenSSH state
+        if: always()
+        run: |
+          if [[ -n "${SSHSCRIPT_OPENSSH_PID_FILE:-}" && -s "$SSHSCRIPT_OPENSSH_PID_FILE" ]]; then
+            sudo kill "$(cat "$SSHSCRIPT_OPENSSH_PID_FILE")" || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_SUDOERS:-}" ]]; then
+            sudo rm -f "$SSHSCRIPT_OPENSSH_SUDOERS"
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_TARGET_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_TARGET_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_ROOT:-}" && "$SSHSCRIPT_OPENSSH_ROOT" == "$RUNNER_TEMP"/sshscript-openssh.* ]]; then
+            sudo rm -rf -- "$SSHSCRIPT_OPENSSH_ROOT"
+          fi
+
+  draft-github-release:
+    name: Create draft GitHub Release
+    needs: [build, openssh-integration]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.11"
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Verify artifact hashes
+        run: |
+          python - <<'PY'
+          import hashlib
+          import json
+          from pathlib import Path
+
+          root = Path("dist")
+          manifest = json.loads((root / "verified.json").read_text())
+          if len(manifest) != 2:
+              raise SystemExit("expected exactly two verified distributions")
+          for name, expected in manifest.items():
+              if Path(name).name != name:
+                  raise SystemExit(f"invalid distribution name: {name}")
+              actual = hashlib.sha256((root / name).read_bytes()).hexdigest()
+              if actual != expected:
+                  raise SystemExit(f"artifact hash mismatch: {name}")
+          PY
+      - name: Create immutable draft with verified assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: >-
+          gh release create "$RELEASE_TAG"
+          dist/*.whl dist/*.tar.gz dist/verified.json
+          --repo "$GITHUB_REPOSITORY"
+          --verify-tag --draft --generate-notes
+          --title "SSHScript ${RELEASE_TAG#v}"
+
+  publish-to-pypi:
+    name: Publish distributions to PyPI
+    needs: draft-github-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sshscript
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.11"
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Recheck hashes and isolate distributions
+        run: |
+          python - <<'PY'
+          import hashlib
+          import json
+          from pathlib import Path
+
+          root = Path("dist")
+          manifest = json.loads((root / "verified.json").read_text())
+          if len(manifest) != 2:
+              raise SystemExit("expected exactly two verified distributions")
+          publish = Path("publish")
+          publish.mkdir()
+          for name, expected in manifest.items():
+              if Path(name).name != name:
+                  raise SystemExit(f"invalid distribution name: {name}")
+              source = root / name
+              actual = hashlib.sha256(source.read_bytes()).hexdigest()
+              if actual != expected:
+                  raise SystemExit(f"artifact hash mismatch: {name}")
+              (publish / name).write_bytes(source.read_bytes())
+          PY
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: publish/
+
+  publish-github-release:
+    name: Publish GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish the verified draft
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release edit "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --draft=false

sshscript-3.1.4/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 3.1.4 - 2026-09-23
+
+### Production hardening
+
+- Require Python 3.11 or newer; CI targets 3.11, 3.12, 3.13, and 3.14.
+- Replace package runtime assertions with the stable exception contract in
+  EXCEPTIONS.md, including validation under `python -O`.
+- Make listener removal, hijack/release, and last-layer checks atomic and
+  non-mutating on failure; fix positive session-stack indexing.
+- Reject invalid command, PTY, pattern, and output arguments before execution
+  or buffer mutation. Disconnected SFTP access raises SSHScriptException.
+- Move embedded stdio tests into the credential-free suite and add normal,
+  optimized, and package AST assertion release gates.
+- AssertionError was never a supported API contract. User-written `.spy`
+  assertions are preserved, but production command-success handling must use
+  explicit checks or `check=True`, because optimized Python removes assertions.
+- Validate closed and hijacked channel operations, AST invariants, persistent
+  commands, PTY modes, and output buffers with stable exception types.
+
+
+### Security
+
+- Verify SSH host keys by default; insecure automatic key acceptance now
+  requires an explicit Paramiko policy.
+- Stop forwarding the complete local environment to interactive SSH sessions.
+- Read remote private keys through SFTP instead of interpolated shell commands.
+- Remove SSH hostnames and complete local/remote paths from upload/download
+  INFO logs.
+- Add CodeQL, Dependabot, private vulnerability reporting guidance, and an
+  OIDC-based trusted publishing workflow.
+- Pin release actions and build tooling, attest distributions, retain their
+  hash manifest, and keep the GitHub Release in draft until PyPI succeeds.
+
+### Fixed
+
+- Drain remote stdout and stderr concurrently and send stdin EOF.
+- Make session cleanup failures observable and optionally strict.
+- Preserve `$.break(code)` as the CLI exit status.
+- Simplify `run_file()` to execute exactly one file; compose scripts through
+  include syntax or Python imports instead of directory/glob execution.
+- Make `.spy` importing explicit with `sshscript.spy_imports()` and scope the
+  importer automatically while `run_file()` is executing.
+- Stop patching `threading.Thread`, `warnings`, and `__main__` during import.
+- Preserve `.spy` thread session inheritance with a context-aware Thread
+  created by the source transformer instead of a process-wide monkey patch.
+- Make `Session()` construction side-effect free and scope stack activation to
+  `run()`, context managers, or an explicit unscoped `$.connect()` operation.
+
+### Project
+
+- Add packaging metadata, license, contributor guidance, and CI configuration.
+- Add a disposable loopback OpenSSH integration gate covering host keys, SFTP,
+  PTY behavior, sudo/su, and timeout handling.

sshscript-3.1.4/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+## Development setup
+
+Use Python 3.11 or newer. The development checkout is a flat source tree, so
+install its development dependencies rather than installing it in editable
+mode:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install 'paramiko>=2.11,<5' 'packaging>=21' build twine
+```
+
+## Required checks
+
+Run the complete credential-free gate before proposing a change:
+
+```sh
+python3 tools/run_checks.py
+python3 tools/check_release.py --output /tmp/sshscript-candidate-UNIQUE
+```
+
+Tests under `unittest/` must not require network access, SSH agents, private
+keys, passwords, or host-specific configuration. A regression fix should add a
+credential-free test whenever the behavior can be reproduced with a fake
+Paramiko client or local subprocess.
+
+## Credentialed integration tests
+
+`unittest-v3/` contains historical and site-specific SSH scenarios. Treat them
+as manual integration tests:
+
+- run them only against disposable hosts;
+- never commit credentials, keys, host inventories, or captured secrets;
+- review commands for destructive effects before execution;
+- use environment variables or ignored local files for configuration.
+
+Credentialed tests are not evidence that the credential-free release gate may
+fail. Both layers must be healthy before a release.
+
+The public CI also provisions a disposable loopback OpenSSH server and runs
+`unittest/test_openssh_integration.py` against the built wheel. The setup uses
+ephemeral users, passwords and keys generated inside the CI runner; it must
+never target a persistent host. See `tools/setup_openssh_ci.sh` for the exact
+environment contract.
+
+## Compatibility and public APIs
+
+Changes to `Session`, `run_file()`, CLI exit statuses, dollar syntax, logging,
+or SSH security defaults require synchronized implementation, tests, README,
+and changelog updates. Avoid silently accepting insecure behavior.
+
+
+Before release, run all normal, optimized, compile, and AST gates listed in
+[EXCEPTIONS.md](EXCEPTIONS.md). CI targets Python 3.11 through 3.14.

sshscript-3.1.4/EXCEPTIONS.md

@@ -0,0 +1,45 @@
+# Stable exception contract
+
+The following contract applies with and without `python -O`.
+
+| Failure | Exception |
+| --- | --- |
+| Wrong argument type | `TypeError` |
+| Correct type but invalid value, content, or combination | `ValueError` |
+| Invalid session, console, or channel lifecycle state | `RuntimeError` |
+| Operation on a closed channel or transport | `BrokenPipeError` |
+| Channel ends while waiting | `EOFError` |
+| Timeout | `TimeoutError` |
+| Disconnected `Session.sftp`, upload, or download | `SSHScriptException` |
+| Filesystem failure | Appropriate `OSError` subclass |
+| Paramiko failure | Original Paramiko exception and traceback |
+| Internal AST or data-structure invariant failure | Descriptive `RuntimeError` |
+| Stack indexing outside its bounds | `IndexError`, following `deque` |
+
+Nonzero command exit status remains data unless `check=True` requests failure
+handling. `AssertionError` was never a supported SSHScript API contract.
+
+User-written `assert` in `.spy` files is preserved as Python syntax. Python's
+optimized mode removes these statements, including any calls inside them.
+Production scripts must not depend on `assert` for command-success handling.
+For local execution, use `session.exec_command(command, check=True)`, or explicitly inspect
+`session.exitcode` and raise an application exception when appropriate.
+
+`for_with` must be strictly bool. `get_pty` must be None or bool. Commands must
+be nonempty strings, and persistent commands must contain only one line.
+Compiled bytes regular expressions are not accepted by text-output matching.
+Listener removal requires the identical top listener; failed removal, duplicate
+hijack/release, and last-layer removal leave their associated state unchanged.
+
+Run release gates from the project root using a supported interpreter:
+
+```sh
+python -m unittest discover -v -s unittest -p 'test_*.py'
+python -O -m unittest discover -v -s unittest -p 'test_*.py'
+python sshscript.py unittest/dollar_syntax.spy
+python -m compileall -q -x 'unittest-v3' .
+python unittest/check_package_asserts.py
+```
+
+CI runs on Python 3.11–3.14 on Linux and macOS. The AST gate scans the flat
+package's root Python modules; tests and historical `unittest-v3` are excluded.

{sshscript-2.0.2 → sshscript-3.1.4}/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Hsin Yuan Yeh
+Copyright (c) 2022-2026 Hsin Yuan Yeh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

sshscript-3.1.4/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md LICENSE.txt RELEASING.md
+include CHANGELOG.md CONTRIBUTING.md EXCEPTIONS.md SECURITY.md SUPPORT.md
+recursive-include tools *.py
+include tools/setup_openssh_ci.sh
+include .github/dependabot.yml
+recursive-include .github/workflows *.yml
+recursive-include src/sshscript/unittest *.py *.spy