relay-shell 0.1.0__tar.gz

relay_shell-0.1.0/.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bats:*)",
+      "Bash(bash -n:*)",
+      "Bash(bash --version)",
+      "Bash(just:*)"
+    ]
+  }
+}

relay_shell-0.1.0/.env.example

@@ -0,0 +1,63 @@
+# relay-shell configuration. Copy to .env (never commit a real .env).
+# All variables are optional; defaults are shown.
+
+# --- Transport ---
+# stdio | http
+RELAY_SHELL_TRANSPORT=stdio
+RELAY_SHELL_HTTP_HOST=127.0.0.1
+RELAY_SHELL_HTTP_PORT=8080
+
+# --- Limits (bytes / seconds) ---
+RELAY_SHELL_MAX_OUTPUT=65536
+RELAY_SHELL_MAX_OUTPUT_HARD=1048576
+RELAY_SHELL_DEFAULT_TIMEOUT=60
+RELAY_SHELL_MAX_TIMEOUT=900
+RELAY_SHELL_MAX_SESSIONS=64
+RELAY_SHELL_SESSION_IDLE_TIMEOUT=1800
+RELAY_SHELL_SESSION_BUFFER_BYTES=262144
+
+# --- Policy ---
+# open | guarded | readonly
+#   open     : full access (default; matches the documented single-owner posture)
+#   guarded  : Tier 2+ commands are refused unless RELAY_SHELL_POLICY_ALLOW matches
+#   readonly : only Tier 0 (read-only) commands permitted
+RELAY_SHELL_POLICY_MODE=open
+RELAY_SHELL_POLICY_DENY=
+RELAY_SHELL_POLICY_ALLOW=
+
+# --- Audit ---
+RELAY_SHELL_AUDIT_PATH=/var/log/relay-shell/audit.jsonl
+RELAY_SHELL_AUDIT_STDERR=false
+# jsonl | cef | leef
+RELAY_SHELL_AUDIT_FORMAT=jsonl
+
+# --- SSH ---
+RELAY_SHELL_SSH_CONFIG=~/.ssh/config
+RELAY_SHELL_INVENTORY=
+# strict | accept-new | ignore
+RELAY_SHELL_SSH_KNOWN_HOSTS=accept-new
+RELAY_SHELL_SSH_CONNECT_TIMEOUT=10
+RELAY_SHELL_SSH_KEEPALIVE=30
+
+# --- Edge TLS (consumed by deploy/install-edge.sh and the Caddyfile) ---
+# Required to issue a public Let's Encrypt certificate:
+RELAY_SHELL_EDGE_DOMAIN=
+RELAY_SHELL_EDGE_ACME_EMAIL=
+# Space-separated source allowlist for tool traffic and /token. Defaults to
+# loopback only, which blocks remote clients until you set this. The value
+# is quoted so it is safe both as a systemd EnvironmentFile entry and as a
+# bash-sourced assignment.
+RELAY_SHELL_EDGE_CLIENT_CIDRS="127.0.0.1/8 ::1"
+# Override only if relay-shell binds a non-default loopback host:port.
+RELAY_SHELL_EDGE_UPSTREAM=127.0.0.1:8080
+# Set to https://acme-staging-v02.api.letsencrypt.org/directory for dry runs.
+RELAY_SHELL_EDGE_ACME_CA=https://acme-v02.api.letsencrypt.org/directory
+
+# --- OAuth 2.1 (HTTP transport only; requires the [http] extra) ---
+RELAY_SHELL_AUTH_ENABLED=false
+RELAY_SHELL_AUTH_ISSUER=https://localhost:8080
+RELAY_SHELL_AUTH_STATE_DIR=/var/lib/relay-shell/oauth
+RELAY_SHELL_AUTH_SINGLE_CLIENT=true
+RELAY_SHELL_AUTH_ACCESS_TTL=3600
+RELAY_SHELL_AUTH_REFRESH_TTL=2592000
+RELAY_SHELL_AUTH_CODE_TTL=300

relay_shell-0.1.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,57 @@
+---
+name: Bug report
+about: A tool behaves incorrectly, a guarantee is violated, or output is wrong.
+title: "[bug] "
+labels: ["bug"]
+---
+
+<!--
+For security-sensitive bugs (audit-trail evasion, policy bypass, secret
+leak, transport / auth issues) please use the "Security report" template
+or open a private advisory instead. See SECURITY.md for the disclosure
+process.
+-->
+
+## What happened
+
+<!-- One or two sentences. What did the tool do, and what was wrong
+about it? Paste the relevant `[ERROR: ...]` / `[DENIED: ...]` string if
+there was one. -->
+
+## Expected behavior
+
+<!-- What should have happened, and where is that contract documented
+(`docs/tools.md`, an ADR, a runbook section)? -->
+
+## Reproduction
+
+```text
+# Minimal command or MCP tool call that reproduces the issue.
+# If reproducing through an MCP client, include the tool name and
+# arguments. Redact any real secrets before pasting.
+```
+
+## Environment
+
+- `relay-shell` version (`relay-shell --help` or `pyproject.toml`):
+- Python version (`python --version`):
+- OS / distro:
+- Transport (`stdio` / `http`):
+- Policy mode (`RELAY_SHELL_POLICY_MODE`):
+- MCP client (Claude Desktop / Inspector / SDK / other):
+
+## Audit record (if relevant)
+
+<!-- One JSON line from `audit.jsonl` if applicable. Strip the args
+field if it might contain anything sensitive; the rest of the record
+(timestamp, tool, tier, output_sha256, output_len, exit_code) is
+generally safe to share. -->
+
+```json
+```
+
+## Logs / additional context
+
+<!-- Anything else that helps. Stack traces are appreciated but bear in
+mind that user-facing output is intentionally bounded; checking the
+server's stderr is usually more informative. -->

relay_shell-0.1.0/.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,58 @@
+---
+name: Feature request
+about: Propose a new tool, transport, auth provider, or capability.
+title: "[feature] "
+labels: ["enhancement"]
+---
+
+<!--
+Before filing, check `docs/runbook.md` §7 to see if this is already in
+the backlog. If it is, reference the backlog ID (e.g. B-007) in this
+issue's body so the maintainer can link the discussion to the existing
+item instead of treating it as a duplicate.
+
+The runbook §6 has recipes for adding tools / transports / auth
+providers / policy heuristics / redaction rules. If you plan to send
+the PR yourself, skim the relevant recipe first.
+-->
+
+## Problem
+
+<!-- The operational need this addresses. Not "add X" but "I cannot do
+Y today because Z." -->
+
+## Proposal
+
+<!-- The change in one paragraph. Tool name (if applicable), default
+tier, the parameters it takes, the shape of the response, the failure
+modes. -->
+
+## Capability impact
+
+- [ ] Adds a new tool. Default tier: <!-- 0 / 1 / 2 / 3 -->
+- [ ] Adds a new transport (`stdio` / `streamable-http` / other).
+- [ ] Adds a new auth provider.
+- [ ] Adds a new policy heuristic.
+- [ ] Adds a new redaction rule.
+- [ ] Adds a new env var (`RELAY_SHELL_*`).
+- [ ] Adds a new runtime dependency.
+
+## Alternatives considered
+
+<!-- Existing tools that almost solve this; why they fall short. If the
+operator can already accomplish this via composition (e.g. `shell_exec`
+plus a script) and the only ask is ergonomics, say so explicitly. -->
+
+## Documentation and tests this will need (best guess)
+
+<!-- Reference the runbook §6 recipe. For a new tool that is:
+- a row in `docs/tools.md`
+- an entry in `tests/test_server.py::_EXPECTED` plus the `len()` assertion
+- an entry in the README capability table
+- a unit test of the underlying helper
+- a wiring test that exercises the tool through FastMCP
+- the `_INSTRUCTIONS` string in `server.py` -->
+
+## Out of scope
+
+<!-- Anything related you do *not* want addressed in the same PR. -->

relay_shell-0.1.0/.github/ISSUE_TEMPLATE/security.md

@@ -0,0 +1,73 @@
+---
+name: Security report
+about: Report a vulnerability or a violation of a security guarantee.
+title: "[security] "
+labels: ["security"]
+---
+
+<!--
+STOP. Please do not paste working exploit payloads into a public issue.
+
+Preferred reporting channels (in order):
+
+1. Open a private security advisory on the repository:
+   https://github.com/rmednitzer/relay-shell/security/advisories/new
+2. Or open an issue without exploit detail and request a private channel
+   to follow up.
+
+This template exists so that something *can* be filed publicly when the
+finding is generic (e.g. "the redaction pattern misses a known token
+shape") and exploitability is low. Use the private path for anything
+sensitive. See SECURITY.md.
+
+Indicative response target: 7 days to triage.
+-->
+
+## In scope?
+
+The following are explicitly in scope (per `SECURITY.md`):
+
+- [ ] Audit-trail evasion (output body leaking into the audit log, hash
+      / length missing, append-only bypass).
+- [ ] Policy / tier bypass (denylist bypass; `readonly` or `guarded`
+      admitting commands they should refuse).
+- [ ] Secret leakage into logs (a real secret shape that redaction
+      misses).
+- [ ] Auth or transport handling (OAuth provider, TLS edge, CIDR
+      allowlist).
+- [ ] Sandbox-escape-equivalent privilege gain *beyond* the documented
+      service-account posture.
+
+Out of scope: the documented unsandboxed full-access posture itself,
+and the ability of a correctly authenticated, policy-permitted caller
+to run commands.
+
+## Summary
+
+<!-- One or two sentences. What is the issue and which guarantee does
+it violate? Reference the section of `SECURITY.md` or the ADR it
+contradicts. -->
+
+## Impact
+
+<!-- Which posture is affected (scoped / privileged), which mode (open
+/ guarded / readonly), and what the attacker gains. Be specific about
+prerequisites (already-authenticated MCP client? Compromised SSH host?
+Local user on the relay host?). -->
+
+## Reproduction sketch
+
+<!-- Enough to confirm the issue. Do NOT include working exploit code
+in a public issue. A sentence and a pointer to the affected file is
+fine; use the private advisory channel for full detail. -->
+
+## Suggested mitigation (optional)
+
+<!-- Where in the source the fix likely belongs. Helpful but not
+required. -->
+
+## Disclosure preference
+
+- [ ] Standard disclosure (public issue + fix in a regular release).
+- [ ] Coordinated disclosure (private advisory until fix ships; credit
+      requested as `<your handle>`).

relay_shell-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,71 @@
+<!--
+Thanks for contributing to relay-shell.
+
+Before opening this PR, walk the runbook §3.1 checklist below. The
+checklist enforces the project's "documentation moves with code" rule:
+new tools, env vars, and modules must be reflected in every cross-
+referenced source in the same PR.
+
+Run the local loop before pushing:
+
+    ruff check . && ruff format --check . && mypy && pytest -q
+
+Reference: docs/runbook.md
+-->
+
+## Summary
+
+<!-- One or two sentences explaining what changes and why. Link the
+backlog item if applicable: "Closes B-007 from docs/runbook.md". -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New capability (tool / transport / auth provider)
+- [ ] Security hardening
+- [ ] Documentation
+- [ ] Build, CI, or release automation
+- [ ] Refactor / cleanup (no behavior change)
+
+## Runbook §3.1 checklist
+
+- [ ] CI is green on the PR head commit (lint, type-check, tests,
+      CodeQL, dependency-review).
+- [ ] No new file is undocumented in `docs/architecture.md` module
+      table.
+- [ ] No new tool is missing from `docs/tools.md`,
+      `tests/test_server.py::_EXPECTED`, and the README capability
+      tables.
+- [ ] No new env var is missing from `.env.example`, `Settings`, and
+      `docs/deployment.md`.
+- [ ] No new dependency is added without a justification in the PR body
+      and a pinned version in `requirements.txt`.
+
+## Security-sensitive diff (runbook §3.3)
+
+Tick if this PR touches any of: `audit.py`, `redaction.py`,
+`policy.py`, the `Relay.run()` body in `server.py`, `auth/oauth.py`,
+`deploy/install*.sh`, or `deploy/Caddyfile`.
+
+- [ ] This PR is security-sensitive.
+
+If ticked, also confirm:
+
+- [ ] `/security-review` was run on the diff (or the manual checklist
+      in runbook §3.3 was walked).
+- [ ] Audit-record fields unchanged (`ts, tool, tier, denied, args,
+      output_sha256, output_len, exit_code`); output body still hashed
+      only.
+- [ ] `policy_text` passed to `Relay.run()` covers every byte the
+      executor will see (command + stdin + env_json + script body).
+- [ ] Redaction patterns have paired over-scrub and under-scrub tests.
+
+## Test plan
+
+<!-- How was this verified locally? Which tests were added or changed?
+For UI-less server changes the full local loop is usually enough;
+for behavior changes, name the new test(s). -->
+
+- [ ] `ruff check . && ruff format --check . && mypy && pytest -q`
+      passes locally.
+- [ ] New behavior has a paired test (under `tests/`).

relay_shell-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"

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

@@ -0,0 +1,59 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    permissions:
+      contents: read
+    timeout-minutes: 20
+    runs-on: ubuntu-latest
+    strategy:
+      # Surface every Python version's result so a single 3.14 wheel gap
+      # does not mask a 3.13 regression. The package floor is `>=3.12` in
+      # pyproject.toml; the matrix covers the floor plus the two newer
+      # interpreters in active CPython support.
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    name: check (py${{ matrix.python-version }})
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          # Wire subprocess coverage: the stdio e2e launches `python -m
+          # relay_shell` in a child, so without this the server.py wrappers
+          # register as uncovered. The .pth runs at every interpreter start;
+          # COVERAGE_PROCESS_START gates the actual recording to runs that opt
+          # in. See `docs/runbook.md` §4.3.
+          python -c "import site, pathlib; \
+            pathlib.Path(site.getsitepackages()[0], 'coverage_subprocess.pth') \
+              .write_text('import coverage; coverage.process_startup()\n')"
+
+      - name: Lint (ruff)
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Type-check (mypy --strict)
+        run: mypy
+
+      - name: Test (pytest with coverage)
+        env:
+          COVERAGE_PROCESS_START: ${{ github.workspace }}/pyproject.toml
+        run: |
+          coverage erase
+          coverage run -m pytest -q
+          coverage combine
+          coverage report

relay_shell-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,38 @@
+name: codeql
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "26 4 * * 1"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4

relay_shell-0.1.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,24 @@
+name: dependency-review
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        # actions/checkout@v6 ships with persist-credentials default-off;
+        # the dependency-review-action then shells out to `git fetch` for
+        # base/head refs and is prompted for a username (terminal prompts
+        # disabled -> exit 128). Restoring the credential helper here
+        # keeps the workflow byte-cheap and pinned to v6 elsewhere.
+        with:
+          persist-credentials: true
+      - name: Dependency review
+        uses: actions/dependency-review-action@v5

relay_shell-0.1.0/.github/workflows/nightly-fuzz.yml

@@ -0,0 +1,41 @@
+name: nightly-fuzz
+
+# Hypothesis-driven property-based fuzz tests for `redact` and `classify`.
+# These live behind the `fuzz` pytest marker and are deselected from the
+# default `pytest` run via `pyproject.toml`'s `addopts`. This workflow
+# opts back in and runs them with an amplified example budget
+# (HYPOTHESIS_PROFILE=ci) once a day so the security-sensitive
+# primitives keep finding latent counterexamples.
+
+on:
+  schedule:
+    # 04:17 UTC daily. The odd minute avoids the on-the-hour spike that
+    # the GitHub Actions scheduler is known to delay under load.
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  fuzz:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run fuzz suite (HYPOTHESIS_PROFILE=ci)
+        env:
+          HYPOTHESIS_PROFILE: ci
+        # Opt back in to the `fuzz` marker (default addopts deselects it).
+        run: pytest -m fuzz -v