sshfc 0.1.0__tar.gz

sshfc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen T. Jibson
+
+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.

sshfc-0.1.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: sshfc
+Version: 0.1.0
+Summary: Force command validator for SSH.
+Author: Steve Jibson
+Author-email: Steve Jibson <steve@jibson.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/toadstule/sshfc
+Description-Content-Type: text/markdown
+
+# sshfc
+
+A command validator for SSH's `ForceCommand`. sshfc lets an SSH user (a person or an agent) run only an explicit
+allowlist of commands, each with an explicit allowlist of arguments. Anything else is rejected with a short message
+explaining why and what is allowed.
+
+The allowlist is a **policy**: one or more TOML files in a directory, `/etc/sshfc/commands.d/` by default. sshfc ships
+sample policy files you can drop in as they are or adapt.
+
+> **Status: proof of concept.** Try a deployment with `--dry-run` first (see [Deploying](#deploying)).
+
+## Quick start
+
+```console
+$ sshfc --samples                          # list the shipped sample policy files
+$ sudo install -d -m 755 /etc/sshfc/commands.d
+$ sshfc --samples podman-readonly | sudo tee /etc/sshfc/commands.d/podman-readonly.toml >/dev/null
+$ sudo sshfc --check                       # check the policy and run its examples
+$ sshfc --dry-run -c 'podman ps'           # see what a command would run
+Would run: /usr/bin/podman ps
+```
+
+Then point an SSH key at sshfc (see [Deploying](#deploying)).
+
+## Running sshfc
+
+```
+sshfc [--config PATH] [--dry-run] [-c COMMAND] [--key-id LABEL] [--insecure-config]
+sshfc --check [--config PATH] [--insecure-config]
+sshfc --samples [NAME]
+```
+
+| Invocation | Command comes from | Action |
+|---|---|---|
+| `sshfc` | `$SSH_ORIGINAL_COMMAND` | Run it. This is the production mode. |
+| `sshfc --dry-run` | `$SSH_ORIGINAL_COMMAND` | Print `Would run: ...` and run nothing. |
+| `sshfc -c 'podman ps'` | `-c` | Run it. For local testing. |
+| `sshfc --dry-run -c 'podman ps'` | `-c` | Print `Would run: ...` and run nothing. |
+| `sshfc --check` | | Check the policy, run every example, report problems, and exit 1 if there are any. |
+| `sshfc --samples [NAME]` | | List the sample policy files, or print one. |
+
+- **Your options are separate from the SSH user's input.** sshfc's own options come from `command="..."` in
+  `authorized_keys` (or `ForceCommand` in `sshd_config`), so the admin controls them, never the SSH user.
+- **`--config PATH`** is a policy directory or a single policy file. Different keys can use different policies.
+- **`-c` takes a single string,** the same form as `SSH_ORIGINAL_COMMAND`, so local tests take the same path as
+  production. If both are present, `-c` wins.
+- **A login with no command is rejected.** If neither is present, as with an interactive `ssh host`, sshfc rejects it
+  and lists the available commands.
+- **Commands run without a shell,** with stdin, stdout and stderr passed through. sshfc exits with the program's
+  status, `128 + N` if it was killed by signal N, or 127/126 if the program can't be found or run.
+- **The environment is minimal.** `PATH` is fixed to `/usr/bin:/bin`. `HOME`, `USER` and `LOGNAME` come from the
+  passwd entry. Only `LANG`, `LC_ALL`, `TERM` and `XDG_RUNTIME_DIR` (needed by rootless podman) are passed through.
+
+### Policy security
+
+- **Ownership:** the policy directory, every policy file, the target of any symlink, and every directory above them
+  must be owned by root and not writable by group or others. A world-writable ancestor is allowed only if it has the
+  sticky bit, like `/tmp`. Otherwise the SSH account could change its own policy.
+- **`--insecure-config`** skips these checks so you can try a policy from a checkout. It's accepted only with
+  `--dry-run` or `--check`, so nothing can run under an unchecked policy.
+- **Fail closed:** if the policy is missing, insecure or malformed, every command is rejected. The SSH user sees only
+  `SSH command rejected: sshfc is misconfigured; contact the administrator`. The details go to the audit log as a
+  `config_error` record. Run `sshfc --check` to see them.
+
+### Deploying
+
+1. Create a dedicated, low-privilege account.
+2. Install a policy in `/etc/sshfc/commands.d/` (see [Quick start](#quick-start)), and run `sudo sshfc --check`.
+3. In the account's `~/.ssh/authorized_keys`, prefix each key with:
+
+   ```
+   command="/path/to/sshfc --dry-run",restrict ssh-ed25519 AAAA... user@example
+   ```
+
+4. Try commands through real SSH (`ssh host podman ps`) and check the `Would run:` output.
+5. Remove `--dry-run`.
+
+`restrict` turns off port, agent and X11 forwarding, PTY allocation, and `~/.ssh/rc`.
+
+If several people's keys share the account, give each key its own label so audit records show whose key was used. A
+key can also get its own policy:
+
+```
+command="/path/to/sshfc --key-id alice",restrict ssh-ed25519 AAAA... alice@example
+command="/path/to/sshfc --key-id ci --config /etc/sshfc/ci.d",restrict ssh-ed25519 AAAA... ci@example
+```
+
+### Audit log
+
+Every invocation is logged to syslog with the ident `sshfc`, under facility `authpriv` (`auth` where `authpriv`
+isn't available). That puts the records next to sshd's own: `/var/log/auth.log` or `/var/log/secure`, or
+`journalctl -t sshfc`. Each record is one JSON line:
+
+| Event | When | Priority | Fields (besides `user`, `key_id`, `client`) |
+|---|---|---|---|
+| `rejected` | The command isn't allowed. A login with no command has `source` `none`. | warning | `source`, `command`, `reason`, `dry_run` |
+| `accepted` | Before the command runs, so there's a record even if it never finishes. Also logged for dry runs. | info | `source`, `command`, `argv`, `policy`, `dry_run` |
+| `exited` | After the command finishes. | info | `argv`, `status`, `duration_s` |
+| `config_error` | The policy couldn't be loaded, so the command was rejected without being checked. | error | `source`, `command`, `error`, `dry_run` |
+
+```json
+{"event":"accepted","user":"svc","key_id":"alice","client":"192.0.2.7 51234","source":"SSH_ORIGINAL_COMMAND","command":"podman ps --format='{{ .ID }}'","argv":["/usr/bin/podman","ps","--format","{{.ID}}"],"policy":"podman-readonly.toml","dry_run":false}
+```
+
+- **`command` vs `argv`:** `command` is exactly what the SSH user sent, and `argv` is what sshfc ran.
+- **`policy`:** the policy file (or files) that define the matched command.
+- **`client`:** the client address and port from `SSH_CONNECTION`.
+- **Log injection:** records are JSON with every non-ASCII and control character escaped, so a crafted command can't
+  split a record or forge a new one.
+
+## How it works
+
+sshfc builds a strict parser from the policy and:
+
+1. Splits the requested command line using shell rules (`shlex`). Nothing is passed to a shell.
+2. Parses it against the allowed commands. Unknown commands, subcommands, options and arguments are rejected.
+   Abbreviated options are rejected too, so `--for` is not treated as `--format`.
+3. Runs every option and positional value through a validator, such as a name pattern or a restricted Go template.
+4. **Rebuilds** the argv from the parsed result, not from the original string. The argv is the absolute path of the
+   program, then the subcommand path, then the options in canonical form, then `--` and the positionals.
+
+Because of step 4, sshfc runs exactly what it validated. A positional value can never be read as an option by the
+target program, and a user can't add arguments the policy doesn't allow.
+
+sshfc also never adds arguments the user didn't type. What runs is what they asked for, in canonical form, so
+commands behave the way users of the real tool expect. When a flag must always be present, the policy makes it
+**required** and the user types it (see `podman stats --no-stream` below).
+
+## What SSH users see
+
+With sshfc deployed with `--dry-run` and the sample policies:
+
+```console
+$ ssh host "podman ps --format '{{ .ID }}  {{.Image}}'"
+Would run: /usr/bin/podman ps --format '{{.ID}}  {{.Image}}'
+
+$ ssh host
+SSH command rejected: the following arguments are required: command (choose from hostname, podman, pwd, whoami)
+
+$ ssh host podman pod
+SSH command rejected: podman pod -- the following arguments are required: subcommand (choose from inspect, ps)
+
+$ ssh host "podman stop 'web;id'"
+SSH command rejected: podman stop -- argument container: invalid value: 'web;id' (expected a container, image, or pod name or ID)
+
+$ ssh host "podman ps --format '{{.Command}}'"
+SSH command rejected: podman ps -- argument --format: field not allowed: 'Command' (choose from CreatedAt, ...)
+```
+
+Without `--dry-run`, an accepted command's output and exit status are the program's own.
+
+Every rejection starts with `SSH command rejected:`, followed by the subcommand path where the error happened, and
+exits with status 1. `-h`/`--help` works at every level and shows the available subcommands and options.
+
+## Writing a policy
+
+A policy file has one `[commands."<path>"]` table per command, keyed by the full command path, so even deep trees
+stay flat:
+
+```toml
+# podman-readonly.toml (excerpt)
+[commands.podman]
+help = "Manage pods, containers and images."
+run = "/usr/bin/podman"
+reject = ["podman rm web-1"]
+
+[commands."podman stop"]
+help = "Stop a container."
+positionals = [{ name = "container", help = "Container name or ID.", validator = "container_name" }]
+accept = [{ command = "podman stop web-1", argv = "/usr/bin/podman stop -- web-1" }]
+
+[commands."podman stats"]
+help = "Display container resource usage statistics."
+flags."--no-stream" = { help = "Print one snapshot instead of a live stream (required).", required = true }
+
+[commands."podman ps".options."--format"]
+help = "Go template using only {{.Field}} placeholders."
+go_template = ["ID", "Image", "Names", "Status"]
+```
+
+Run `sshfc --samples podman-readonly` for the complete file. After any change, run `sshfc --check`.
+
+### Several files in one directory
+
+- **Which files are read:** only `*.toml` files whose names don't start with `.`, in sorted order. Editor backups
+  (`*~`) and package-manager leftovers (`.rpmnew`, `.dpkg-old`) are ignored.
+- **No overrides:** each command path is defined by one file. The same path may appear in several files only if
+  every definition is identical, which is how independent files share a parent such as `podman`. A difference is an
+  error naming both files. Because nothing overrides anything, the merged policy doesn't depend on file order, and a
+  later file can't quietly change a definition reviewed in another.
+- **Examples are combined:** `accept`/`reject` examples aren't part of the definition. They're combined, and
+  `sshfc --check` runs them all against the **merged** policy. If one file allows something another file's `reject`
+  examples expect to be rejected, the check fails.
+- **Commands are listed alphabetically** at each level in help and error messages.
+
+### Command fields
+
+| Field | Meaning |
+|---|---|
+| `help` | One-line description shown in help output and error messages. Required. |
+| `run` | Absolute path of the program. Subcommands inherit it and their names are added to the argv, so `run = "/usr/bin/podman"` on `podman` makes `podman pod ps` run `/usr/bin/podman pod ps`. Every leaf command needs a `run` on itself or an ancestor. |
+| `options` | Options that take a value: `options."--name" = { help = "...", <validator> }`. Rendered as `--name VALUE`, if given. Add `required = true` to make the user type it. |
+| `flags` | Options without a value: `flags."--all" = { help = "..." }`. Rendered as `--all`, if given. Add `required = true` to make the user type it. |
+| `positionals` | Required positional arguments, in order: `[{ name = "...", help = "...", <validator> }]`. Rendered after `--`. |
+| `end_of_options` | Put `--` before positionals (default `true`). Turn it off only for programs that don't understand `--`. |
+| `accept` | Full example command lines that must be accepted. Use `{ command = "...", argv = "..." }` to also check what would run. |
+| `reject` | Full example command lines that must be rejected. |
+
+Only leaf commands (commands without subcommands) can have `options`, `flags` or `positionals`. A command with
+subcommands requires the user to choose one. Unknown keys are errors, so a typo can't be silently ignored.
+
+Options and flags are always rendered in the order the policy lists them, whatever order the user typed them in.
+
+A **required** option or flag must be typed. If it's missing, the error names it
+(`SSH command rejected: podman stats -- the following arguments are required: --no-stream`), and `-h` shows its help.
+Use it when a command is only safe or useful with a particular argument. For example, without `--no-stream`,
+`podman stats` streams forever and the SSH session never ends. Put the reason in the help text, since that's what the
+user sees.
+
+### Validators
+
+Every option and positional needs exactly one validator. There is no "any string" default.
+
+| Validator | Accepts |
+|---|---|
+| `validator = "container_name"` | A plain container, image or pod name or ID. Tags, digests, registry paths, and anything starting with `-` or `.` are rejected. |
+| `pattern = "<regex>"`, `description = "..."` | Values that **fully** match the regex. `description` is shown to the user when a value is rejected. |
+| `go_template = ["Field", ...]` | A restricted Go template for `--format`-style options (details below). The fields are added to the help text. |
+
+`go_template` accepts:
+
+- `{{.Field}}` placeholders, where `Field` must be in the list;
+- literal text made of letters, digits, spaces, tabs and `:|,;=/._-`;
+- an optional leading `table` keyword.
+
+It rejects functions (`json`, `printf`), pipelines, nested fields, `range`/`if`, variables, comments and stray braces,
+and enforces limits on length and placeholder count. The template sshfc runs is rebuilt from the parsed pieces, not
+copied from the input.
+
+When choosing which fields or values to allow, think about what they reveal. For example, the podman sample omits
+`.Command` because container arguments often contain credentials.
+
+### Python API
+
+The policy loader produces `sshfc.core.Command` specs, and `sshfc.core` can also be used directly to build, check
+and parse specs in Python. See `src/sshfc/core/spec.py`.
+
+## Development
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```console
+make dep      # install dependencies
+make check    # format, lint (ruff), type-check (mypy --strict), and test (pytest)
+make build    # build the wheel
+make install  # editable install into the active virtual environment
+make help     # list all targets
+```
+
+Try the samples from a checkout (they aren't root-owned there, hence `--insecure-config`):
+
+```console
+uv run sshfc --check --insecure-config --config src/sshfc/samples
+uv run sshfc --dry-run --insecure-config --config src/sshfc/samples -c "podman ps --format '{{.ID}}'"
+```
+
+### Project layout
+
+```
+src/sshfc/
+  cli.py             entry point: modes, input source, auditing
+  core/              infrastructure (public API: sshfc.core)
+    spec.py          Command, Option, Flag, Positional
+    config.py        TOML policy loading, merging, ownership checks
+    check.py         sshfc --check: load the policy, run every example against it
+    parser.py        strict parser built from specs; spec checks; argv rendering
+    validators.py    Pattern, CONTAINER_NAME, GoTemplateFormat, and the named validators
+    executor.py      runs the rendered argv: no shell, minimal environment
+    audit.py         JSON audit records to syslog
+  samples/           sample policy files, shipped in the package (sshfc --samples)
+tests/
+  test_parser.py     parser, using made-up specs
+  test_config.py     policy loading, merge rules, schema errors, ownership checks
+  test_check.py      example checks, including one file widening another
+  test_samples.py    every sample, alone and all together
+  test_validators.py validators
+  test_executor.py   executor: environment, exit statuses, failures to start
+  test_audit.py      audit record format and log-injection safety
+  test_cli.py        modes, input source, config errors, and what gets audited
+```
+
+## License
+
+MIT

sshfc-0.1.0/README.md

@@ -0,0 +1,294 @@
+# sshfc
+
+A command validator for SSH's `ForceCommand`. sshfc lets an SSH user (a person or an agent) run only an explicit
+allowlist of commands, each with an explicit allowlist of arguments. Anything else is rejected with a short message
+explaining why and what is allowed.
+
+The allowlist is a **policy**: one or more TOML files in a directory, `/etc/sshfc/commands.d/` by default. sshfc ships
+sample policy files you can drop in as they are or adapt.
+
+> **Status: proof of concept.** Try a deployment with `--dry-run` first (see [Deploying](#deploying)).
+
+## Quick start
+
+```console
+$ sshfc --samples                          # list the shipped sample policy files
+$ sudo install -d -m 755 /etc/sshfc/commands.d
+$ sshfc --samples podman-readonly | sudo tee /etc/sshfc/commands.d/podman-readonly.toml >/dev/null
+$ sudo sshfc --check                       # check the policy and run its examples
+$ sshfc --dry-run -c 'podman ps'           # see what a command would run
+Would run: /usr/bin/podman ps
+```
+
+Then point an SSH key at sshfc (see [Deploying](#deploying)).
+
+## Running sshfc
+
+```
+sshfc [--config PATH] [--dry-run] [-c COMMAND] [--key-id LABEL] [--insecure-config]
+sshfc --check [--config PATH] [--insecure-config]
+sshfc --samples [NAME]
+```
+
+| Invocation | Command comes from | Action |
+|---|---|---|
+| `sshfc` | `$SSH_ORIGINAL_COMMAND` | Run it. This is the production mode. |
+| `sshfc --dry-run` | `$SSH_ORIGINAL_COMMAND` | Print `Would run: ...` and run nothing. |
+| `sshfc -c 'podman ps'` | `-c` | Run it. For local testing. |
+| `sshfc --dry-run -c 'podman ps'` | `-c` | Print `Would run: ...` and run nothing. |
+| `sshfc --check` | | Check the policy, run every example, report problems, and exit 1 if there are any. |
+| `sshfc --samples [NAME]` | | List the sample policy files, or print one. |
+
+- **Your options are separate from the SSH user's input.** sshfc's own options come from `command="..."` in
+  `authorized_keys` (or `ForceCommand` in `sshd_config`), so the admin controls them, never the SSH user.
+- **`--config PATH`** is a policy directory or a single policy file. Different keys can use different policies.
+- **`-c` takes a single string,** the same form as `SSH_ORIGINAL_COMMAND`, so local tests take the same path as
+  production. If both are present, `-c` wins.
+- **A login with no command is rejected.** If neither is present, as with an interactive `ssh host`, sshfc rejects it
+  and lists the available commands.
+- **Commands run without a shell,** with stdin, stdout and stderr passed through. sshfc exits with the program's
+  status, `128 + N` if it was killed by signal N, or 127/126 if the program can't be found or run.
+- **The environment is minimal.** `PATH` is fixed to `/usr/bin:/bin`. `HOME`, `USER` and `LOGNAME` come from the
+  passwd entry. Only `LANG`, `LC_ALL`, `TERM` and `XDG_RUNTIME_DIR` (needed by rootless podman) are passed through.
+
+### Policy security
+
+- **Ownership:** the policy directory, every policy file, the target of any symlink, and every directory above them
+  must be owned by root and not writable by group or others. A world-writable ancestor is allowed only if it has the
+  sticky bit, like `/tmp`. Otherwise the SSH account could change its own policy.
+- **`--insecure-config`** skips these checks so you can try a policy from a checkout. It's accepted only with
+  `--dry-run` or `--check`, so nothing can run under an unchecked policy.
+- **Fail closed:** if the policy is missing, insecure or malformed, every command is rejected. The SSH user sees only
+  `SSH command rejected: sshfc is misconfigured; contact the administrator`. The details go to the audit log as a
+  `config_error` record. Run `sshfc --check` to see them.
+
+### Deploying
+
+1. Create a dedicated, low-privilege account.
+2. Install a policy in `/etc/sshfc/commands.d/` (see [Quick start](#quick-start)), and run `sudo sshfc --check`.
+3. In the account's `~/.ssh/authorized_keys`, prefix each key with:
+
+   ```
+   command="/path/to/sshfc --dry-run",restrict ssh-ed25519 AAAA... user@example
+   ```
+
+4. Try commands through real SSH (`ssh host podman ps`) and check the `Would run:` output.
+5. Remove `--dry-run`.
+
+`restrict` turns off port, agent and X11 forwarding, PTY allocation, and `~/.ssh/rc`.
+
+If several people's keys share the account, give each key its own label so audit records show whose key was used. A
+key can also get its own policy:
+
+```
+command="/path/to/sshfc --key-id alice",restrict ssh-ed25519 AAAA... alice@example
+command="/path/to/sshfc --key-id ci --config /etc/sshfc/ci.d",restrict ssh-ed25519 AAAA... ci@example
+```
+
+### Audit log
+
+Every invocation is logged to syslog with the ident `sshfc`, under facility `authpriv` (`auth` where `authpriv`
+isn't available). That puts the records next to sshd's own: `/var/log/auth.log` or `/var/log/secure`, or
+`journalctl -t sshfc`. Each record is one JSON line:
+
+| Event | When | Priority | Fields (besides `user`, `key_id`, `client`) |
+|---|---|---|---|
+| `rejected` | The command isn't allowed. A login with no command has `source` `none`. | warning | `source`, `command`, `reason`, `dry_run` |
+| `accepted` | Before the command runs, so there's a record even if it never finishes. Also logged for dry runs. | info | `source`, `command`, `argv`, `policy`, `dry_run` |
+| `exited` | After the command finishes. | info | `argv`, `status`, `duration_s` |
+| `config_error` | The policy couldn't be loaded, so the command was rejected without being checked. | error | `source`, `command`, `error`, `dry_run` |
+
+```json
+{"event":"accepted","user":"svc","key_id":"alice","client":"192.0.2.7 51234","source":"SSH_ORIGINAL_COMMAND","command":"podman ps --format='{{ .ID }}'","argv":["/usr/bin/podman","ps","--format","{{.ID}}"],"policy":"podman-readonly.toml","dry_run":false}
+```
+
+- **`command` vs `argv`:** `command` is exactly what the SSH user sent, and `argv` is what sshfc ran.
+- **`policy`:** the policy file (or files) that define the matched command.
+- **`client`:** the client address and port from `SSH_CONNECTION`.
+- **Log injection:** records are JSON with every non-ASCII and control character escaped, so a crafted command can't
+  split a record or forge a new one.
+
+## How it works
+
+sshfc builds a strict parser from the policy and:
+
+1. Splits the requested command line using shell rules (`shlex`). Nothing is passed to a shell.
+2. Parses it against the allowed commands. Unknown commands, subcommands, options and arguments are rejected.
+   Abbreviated options are rejected too, so `--for` is not treated as `--format`.
+3. Runs every option and positional value through a validator, such as a name pattern or a restricted Go template.
+4. **Rebuilds** the argv from the parsed result, not from the original string. The argv is the absolute path of the
+   program, then the subcommand path, then the options in canonical form, then `--` and the positionals.
+
+Because of step 4, sshfc runs exactly what it validated. A positional value can never be read as an option by the
+target program, and a user can't add arguments the policy doesn't allow.
+
+sshfc also never adds arguments the user didn't type. What runs is what they asked for, in canonical form, so
+commands behave the way users of the real tool expect. When a flag must always be present, the policy makes it
+**required** and the user types it (see `podman stats --no-stream` below).
+
+## What SSH users see
+
+With sshfc deployed with `--dry-run` and the sample policies:
+
+```console
+$ ssh host "podman ps --format '{{ .ID }}  {{.Image}}'"
+Would run: /usr/bin/podman ps --format '{{.ID}}  {{.Image}}'
+
+$ ssh host
+SSH command rejected: the following arguments are required: command (choose from hostname, podman, pwd, whoami)
+
+$ ssh host podman pod
+SSH command rejected: podman pod -- the following arguments are required: subcommand (choose from inspect, ps)
+
+$ ssh host "podman stop 'web;id'"
+SSH command rejected: podman stop -- argument container: invalid value: 'web;id' (expected a container, image, or pod name or ID)
+
+$ ssh host "podman ps --format '{{.Command}}'"
+SSH command rejected: podman ps -- argument --format: field not allowed: 'Command' (choose from CreatedAt, ...)
+```
+
+Without `--dry-run`, an accepted command's output and exit status are the program's own.
+
+Every rejection starts with `SSH command rejected:`, followed by the subcommand path where the error happened, and
+exits with status 1. `-h`/`--help` works at every level and shows the available subcommands and options.
+
+## Writing a policy
+
+A policy file has one `[commands."<path>"]` table per command, keyed by the full command path, so even deep trees
+stay flat:
+
+```toml
+# podman-readonly.toml (excerpt)
+[commands.podman]
+help = "Manage pods, containers and images."
+run = "/usr/bin/podman"
+reject = ["podman rm web-1"]
+
+[commands."podman stop"]
+help = "Stop a container."
+positionals = [{ name = "container", help = "Container name or ID.", validator = "container_name" }]
+accept = [{ command = "podman stop web-1", argv = "/usr/bin/podman stop -- web-1" }]
+
+[commands."podman stats"]
+help = "Display container resource usage statistics."
+flags."--no-stream" = { help = "Print one snapshot instead of a live stream (required).", required = true }
+
+[commands."podman ps".options."--format"]
+help = "Go template using only {{.Field}} placeholders."
+go_template = ["ID", "Image", "Names", "Status"]
+```
+
+Run `sshfc --samples podman-readonly` for the complete file. After any change, run `sshfc --check`.
+
+### Several files in one directory
+
+- **Which files are read:** only `*.toml` files whose names don't start with `.`, in sorted order. Editor backups
+  (`*~`) and package-manager leftovers (`.rpmnew`, `.dpkg-old`) are ignored.
+- **No overrides:** each command path is defined by one file. The same path may appear in several files only if
+  every definition is identical, which is how independent files share a parent such as `podman`. A difference is an
+  error naming both files. Because nothing overrides anything, the merged policy doesn't depend on file order, and a
+  later file can't quietly change a definition reviewed in another.
+- **Examples are combined:** `accept`/`reject` examples aren't part of the definition. They're combined, and
+  `sshfc --check` runs them all against the **merged** policy. If one file allows something another file's `reject`
+  examples expect to be rejected, the check fails.
+- **Commands are listed alphabetically** at each level in help and error messages.
+
+### Command fields
+
+| Field | Meaning |
+|---|---|
+| `help` | One-line description shown in help output and error messages. Required. |
+| `run` | Absolute path of the program. Subcommands inherit it and their names are added to the argv, so `run = "/usr/bin/podman"` on `podman` makes `podman pod ps` run `/usr/bin/podman pod ps`. Every leaf command needs a `run` on itself or an ancestor. |
+| `options` | Options that take a value: `options."--name" = { help = "...", <validator> }`. Rendered as `--name VALUE`, if given. Add `required = true` to make the user type it. |
+| `flags` | Options without a value: `flags."--all" = { help = "..." }`. Rendered as `--all`, if given. Add `required = true` to make the user type it. |
+| `positionals` | Required positional arguments, in order: `[{ name = "...", help = "...", <validator> }]`. Rendered after `--`. |
+| `end_of_options` | Put `--` before positionals (default `true`). Turn it off only for programs that don't understand `--`. |
+| `accept` | Full example command lines that must be accepted. Use `{ command = "...", argv = "..." }` to also check what would run. |
+| `reject` | Full example command lines that must be rejected. |
+
+Only leaf commands (commands without subcommands) can have `options`, `flags` or `positionals`. A command with
+subcommands requires the user to choose one. Unknown keys are errors, so a typo can't be silently ignored.
+
+Options and flags are always rendered in the order the policy lists them, whatever order the user typed them in.
+
+A **required** option or flag must be typed. If it's missing, the error names it
+(`SSH command rejected: podman stats -- the following arguments are required: --no-stream`), and `-h` shows its help.
+Use it when a command is only safe or useful with a particular argument. For example, without `--no-stream`,
+`podman stats` streams forever and the SSH session never ends. Put the reason in the help text, since that's what the
+user sees.
+
+### Validators
+
+Every option and positional needs exactly one validator. There is no "any string" default.
+
+| Validator | Accepts |
+|---|---|
+| `validator = "container_name"` | A plain container, image or pod name or ID. Tags, digests, registry paths, and anything starting with `-` or `.` are rejected. |
+| `pattern = "<regex>"`, `description = "..."` | Values that **fully** match the regex. `description` is shown to the user when a value is rejected. |
+| `go_template = ["Field", ...]` | A restricted Go template for `--format`-style options (details below). The fields are added to the help text. |
+
+`go_template` accepts:
+
+- `{{.Field}}` placeholders, where `Field` must be in the list;
+- literal text made of letters, digits, spaces, tabs and `:|,;=/._-`;
+- an optional leading `table` keyword.
+
+It rejects functions (`json`, `printf`), pipelines, nested fields, `range`/`if`, variables, comments and stray braces,
+and enforces limits on length and placeholder count. The template sshfc runs is rebuilt from the parsed pieces, not
+copied from the input.
+
+When choosing which fields or values to allow, think about what they reveal. For example, the podman sample omits
+`.Command` because container arguments often contain credentials.
+
+### Python API
+
+The policy loader produces `sshfc.core.Command` specs, and `sshfc.core` can also be used directly to build, check
+and parse specs in Python. See `src/sshfc/core/spec.py`.
+
+## Development
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```console
+make dep      # install dependencies
+make check    # format, lint (ruff), type-check (mypy --strict), and test (pytest)
+make build    # build the wheel
+make install  # editable install into the active virtual environment
+make help     # list all targets
+```
+
+Try the samples from a checkout (they aren't root-owned there, hence `--insecure-config`):
+
+```console
+uv run sshfc --check --insecure-config --config src/sshfc/samples
+uv run sshfc --dry-run --insecure-config --config src/sshfc/samples -c "podman ps --format '{{.ID}}'"
+```
+
+### Project layout
+
+```
+src/sshfc/
+  cli.py             entry point: modes, input source, auditing
+  core/              infrastructure (public API: sshfc.core)
+    spec.py          Command, Option, Flag, Positional
+    config.py        TOML policy loading, merging, ownership checks
+    check.py         sshfc --check: load the policy, run every example against it
+    parser.py        strict parser built from specs; spec checks; argv rendering
+    validators.py    Pattern, CONTAINER_NAME, GoTemplateFormat, and the named validators
+    executor.py      runs the rendered argv: no shell, minimal environment
+    audit.py         JSON audit records to syslog
+  samples/           sample policy files, shipped in the package (sshfc --samples)
+tests/
+  test_parser.py     parser, using made-up specs
+  test_config.py     policy loading, merge rules, schema errors, ownership checks
+  test_check.py      example checks, including one file widening another
+  test_samples.py    every sample, alone and all together
+  test_validators.py validators
+  test_executor.py   executor: environment, exit statuses, failures to start
+  test_audit.py      audit record format and log-injection safety
+  test_cli.py        modes, input source, config errors, and what gets audited
+```
+
+## License
+
+MIT