Skip to content

Releases

v0.6.2 — the teaching channel, hardened

Choose a tag to compare

@xezpeleta xezpeleta released this 05 Oct 19:41

v0.6.2 — the teaching channel, hardened

Every change in this revision came from watching the channel fail
to explain itself, and fixing the explanation. Same rule as ever:
argv is the unit of trust, and every refusal teaches.

sysh (host)

Script and console lines no longer collide on one scope unit

A session is one process, so every line of a script — or a console
session — derived the same transient scope name; systemd refuses
to load a unit that already exists, and lines failed with exit 1 in
an alternating pattern. Every exec now gets a unique unit
(sysh-<key>-<nanotime>-<seq>), and the journal pair per line is
stable.

help says the shebang precisely

The script section ended its sentence with a semicolon glued to the
shebang, and clients that read literally copied #!/usr/bin/sysh;
into their uploads. The shebang is now quoted:
first line "#!/usr/bin/sysh".

A refused interpreter points at the shebang

In traced mode, an exec that names a denylisted interpreter — the
#!/usr/bin/env bash habit resolving through env — now says so:
interpreters are named in the script's shebang, not exec'd as
commands. Before, it was a bare "no rule allows this argv".

The allow path teaches too

In root and permissive modes, confusing commands run — so one
stderr note beats a cryptic child error: a literal &&, 2>&1 or
; in argv gets a single explanation before the child runs (one
note, first offending word, never a wall).

help is the survival guide

help gained the exit-code block (0 ok, 30 approval parked with TTL
and single-use semantics, 125 denied, 124 timeout, 3 malformed),
and every failure surface now points at it: generic denies,
no-input detail, bare-name hints.

sy watch

  • Expired approval requests keep their teaching line for a
    three-minute grace, then the pending panel hides itself — the
    wall log keeps the story.
  • Host cards say more with less: non-zero rule counts only, colored
    policy-mode chips (root = red), the agent-scripts mode as its own
    chip, no :22, digest in mono.
  • A host with no policy answer (down, or an older sysh) no longer
    breaks the whole grid.
  • Hosts fill within seconds of opening the page — the poller
    settles before its first round and logs fetch failures.
  • The priv badge explains itself on hover: this exact argv ran as
    root under an operator-authorized sudoers grant.

docs

The bash-compatibility spectrum is now a table — direct exec,
console, lines script, traced script, root mode — stating for each:
what the agent sends, what shell features it gets, what the policy
checks, what the journal sees, and what a refusal looks like. Up
the rows the agent gains shell and the operator loses sight of the
how — never of the what, until root mode. usage.html STEP 6 adds a
per-mode guide: what each level gives the operator, and the agent.

v0.6.1 — the operator's blind spots, found by unbriefed agents

Choose a tag to compare

@xezpeleta xezpeleta released this 05 Oct 18:20

v0.6.1 — the operator's blind spots, found by unbriefed agents

Every fix in this revision came out of a live blind test: real
agents with no briefing, a real enforcing host, and an operator
who could only watch. The agents behaved — the tools around them
had the blind spots.

sysh (host)

sysh-result says WHICH no-result it is

"pending, expired, or never approved" was one message for three
different situations. An agent that cannot tell pending from
expired waits out the full TTL for a request that is already
dead. The builtin now asks the drop box and answers precisely:
pending says "wait and re-check"; expired says "re-run the
command to file a fresh request"; a bad id says so. The audit
event carries the same classification, so the operator's wall
reads it too.

Live result: an unbriefed agent, told its request had expired,
re-filed unprompted and completed the task on the next approval.

doctor: PermitTTY is a choice, not drift

doctor demanded permittty no while the shipped sshd drop-in
sets yes for the argv console — a fresh 0.6.0 install failed
its own doctor. Both values are legitimate (yes = console,
no = -c only); doctor accepts either and fails on anything
else.

sy watch (operator)

Expired requests leave; every row counts down

The waiting panel kept expired rows around, faded, with buttons
that answered nothing. Expired rows now leave the moment they
expire (a countdown shows the TTL — m:ss, amber in the last two
minutes, red in the last one) and one quiet line says how many
went that way. Refuse-by-default, visible by default.

The ceremony tells you what to type, and recovers from a miss

The typed-argument challenge highlights the exact argv element
to type — the proof is reading the argv, never guessing. A
mistyped attempt used to consume the ceremony and leave a dead
modal; it now fetches a fresh one immediately. An expired
request can no longer open a ceremony at all.

Agent state: is it waiting for me? did it get the answer?

New per-request correlation of journal events (filed, every
sysh-result poll with its classification, the approval, the
fetch): each pending row reads like "agent waiting · 6 polls ·
last check 12s ago", and answered requests are listed with
their outcome. /api/agents exposes the same table.

The answer lands everywhere at once

Approving used to clear the modal instantly but leave the
waiting row for the next poll cycle (~10s with a down host).
The row is now answered the moment the ceremony returns, the
approvals poller skips hosts the follower reports down, the
root channel runs with ConnectTimeout everywhere, and static
assets ship Cache-Control: no-store (a stale cached UI is a
support case wearing a disguise).

Upgrade

Same package, same config, no contract change — argv rules,
exits, and the approval ceremony are untouched.

sudo apt install ./sysh_0.6.1_amd64.deb

Verify with sysh doctor (now clean on fresh installs) and
sysh approvals as root.

v0.6.0 — agent scripts, traced mode, the console, teaching denies

Choose a tag to compare

@xezpeleta xezpeleta released this 05 Oct 11:02

v0.6.0 — agent scripts, traced mode, the console, teaching denies

New

Agent scripts — batch work, still one argv at a time

agent_scripts = "/var/lib/sysh/agent-scripts" turns a root-owned
directory into runnable scripts: first line #!/usr/bin/sysh, one
command per line, and every line is policy-checked and journaled
like a direct exec
. No shell features inside — each line is an
argv, nothing more. The upload path is an operator-acknowledged
rsync rule scoped to that directory; the linter teaches the shape
when the agent tries to improvise one.

Traced mode — real interpreters, argv enforcement in the tree

agent_scripts_mode = "traced": any shebang — bash, python,
node, whatever the operator allows installed — runs as the
unprivileged gateway user while a ptrace tracer intercepts every
execve in the process tree
. The argv is read from the stopped
child at syscall entry, checked by the same Match as a direct
exec, and a refusal fails the syscall itself (-EPERM): the
interpreter sees "Operation not permitted", the journal sees the
full argv, and the script's own logic decides whether to continue.
Pipes and redirections inside a script are the interpreter's
plumbing — but each side of a pipe is still a checked exec.
Honest limits, stated in the lint and the docs: only execve is
inspected (what the interpreter does with builtins is not
argv-visible), it is argv enforcement and not sandboxing, it is
amd64-only (build-tagged), and sudo touch /run/sysh/traced-off
is a kill switch that refuses every traced run instantly.

The interactive console

ssh sy@host with a TTY attached now opens a small console: the
contract as a banner, help, cd as navigation state (not an
exec), and every line through the same decision pipeline as a
-c exec — checked, journaled, refused where the policy refuses.

Teaching denies — measured against an unbriefed agent

Denials answer now. A bare uptime gets the absolute path to try;
cmd | grep x gets "no shell operators here: send one command per
exec"; an improvised rsync gets "ask your operator"; escape-hatch
binaries (env, find, shells…) explain exactly what they would
bypass. Measured live: an unbriefed agent, told only to "figure out
how to run commands on this host", corrected course on denial
detail alone — no operator intervention.

The channel contract, stated everywhere

The child's stdout streams to the session stdout untouched;
the JSON result envelope goes to stderr. Agents parse data from
stdout and outcomes from stderr — and help now states this
in-band, because it is the contract they script against.

Worked example policies

Three installable examples with READMEs, all validated on a real
host before shipping: examples/diagnostic/ (read-only agent —
observe by allowlist, read-only-ness by omission: no mutating tool
has a rule), examples/operational/ (diagnose freely, act only
through the approval channel — the full ceremony documented step
by step), and the existing examples/webserver/.

Changed

  • help and the console banner describe traced-mode semantics
    (any shebang, every exec checked, pipes' sides checked, bare
    argv[0] names inside scripts) instead of line-mode-only text.
  • Docs: the stdout/stderr channel contract (PROJECT.md §6.4),
    pipes and bare argv[0] inside traced trees (§6.13), and a
    worked-examples index (§7).
  • The policy linter emits honest-limits infos for
    agent_scripts modes and warns when a mode is set without a
    directory.

Install

curl -LO https://github.com/xezpeleta/sysh/releases/download/v0.6.0/sysh_0.6.0_amd64.deb
sudo apt install ./sysh_0.6.0_amd64.deb

Or build from source: go build ./cmd/sysh && go build ./cmd/sy.
Docs: https://xezpeleta.github.io/sysh/

v0.5.0 — agent key hygiene, root mode, GPLv3

Choose a tag to compare

@xezpeleta xezpeleta released this 04 Oct 22:50

v0.5.0 — agent key hygiene, root mode, GPLv3

New

Agent keys expire (hygiene without a CA)

keys.map entries take an optional third field — expires: in
RFC3339. The gateway refuses an expired key before argv is even
parsed, with a denial that names the key and says how to fix it:

sysh auth add --ttl 7d sy/engagement-2025-06-12 ~/.ssh/id_ed25519.pub
sysh auth rotate sy/old --ttl 30d
sysh auth list            # shows expiry, flags EXPIRED
sysh doctor               # warns on expired + expiring-soon keys

No certificate authority to run or protect: expiry is root-owned
host data, checked where every other decision is checked. Rotation
adds the new key before removing the old one, and refuses to
"rotate" to the same key material.

Root mode — the explicit opt-out

mode = "root" (with a required timeout) is for a custom host you
consider disposable: deny rules still hold, everything else runs as
root through one wildcard sudoers grant sysh policy install
generates. Every exec keeps its PATH resolution, argv checks,
timeout, and pre/post journal events with PRIV=1.

Honest by construction: allow/approval rules in root mode are lint
errors (they gate nothing), install requires sudo and active auditd
rules, sysh doctor warns about root mode on every run. After the
first root exec the agent can mint access the journal never sees —
the docs say so everywhere the mode is named.

Browser alerts in sy watch (BETA)

Click the bell in the header; the browser asks for notification
permission and you answer. New approval requests then pop as native
alerts — argv, key, host — like calendar invites, click to focus the
pending panel. The ceremony never leaves the server.

Beta: not yet battle-tested. The pending banner and the terminal
ceremony remain the reliable channels.

Changed

  • Relicensed MIT → GPLv3. The vendored Apache-2.0 pi-replay.js
    keeps its notice (one-way compatible).
  • Docs: the "not root-without-approval" claim now names the
    mechanism — exact-argv sudoers grants generated by the operator's
    own sysh policy install; the agent invoking sudo itself is
    denied like any other argv.

Install

curl -LO https://github.com/xezpeleta/sysh/releases/download/v0.5.0/sysh_0.5.0_amd64.deb
sudo apt install ./sysh_0.5.0_amd64.deb

Or build from source: go build ./cmd/sysh && go build ./cmd/sy.
Docs: https://xezpeleta.github.io/sysh/

v0.4.0 — signed approvals + sy mcp

Choose a tag to compare

@xezpeleta xezpeleta released this 04 Oct 16:25

Transport B and the laptop side — approval power moves to keys; agents get a protocol.

The approval channel of v0.3.0 answered from a root shell. Now approval power is bound to a registered approver key, and the agent's toolkit speaks MCP over plain SSH.

  • Signed approvals: sysh approver add/list/remove registers approver public keys (recommended sk-* — hardware-backed: no signature without a physical touch). sysh approve <id> --show prints the exact request bytes; sign anywhere with stock tooling (ssh-keygen -Y sign -n sysh-approve) and submit with --sig. Verification is in-process (golang.org/x/crypto/ssh — no ssh-keygen on the verify path): the signature must cover the request's exact bytes, under the sysh-approve namespace, by a key byte-identical to a registered approver. Requests stay TTL'd, single-use, content-bound — a captured signature approves nothing else.
  • sy mcp — a stdio MCP server for agent harnesses: sy_exec, sy_docs, sy_policy over plain SSH as the unprivileged sy user, strict known_hosts, operator-edited host registry (~/.config/sy/hosts.toml). An approval-required exec surfaces the request id (isError: false, "do not retry") — no approval power of any kind in tool space.
  • sy approve / sy approvals (operator side, same deb): the approval ceremony in one command — fetch the request bytes over your root SSH channel, display the server-recorded argv, recompute the request id locally before anything reaches the signing gesture, then sign and submit. For sk-* keys: an insert-your-YubiKey loop, PIN and touch inside ssh-keygen. A TTY-only confirmation prompt sits between the display and the signature; piped stdin is refused.

The trust argument, once: the FIDO2 PIN and touch prompts are blind — they authorize whatever bytes the invoking process signs. So the argv display must come from the server over a channel the agent cannot write to, which is why the ceremony is operator-run and absent from MCP tool space.

Verified live on a test host: full signed cycle (touch request → --show → sign → --sig → executed as root), all refusal paths live (stranger key, wrong namespace, cross-request signature, replayed signature), the MCP toolset end-to-end over real SSH, and the one-command ceremony driven from an agent session.

Deferred (v0.5 candidates, documented in PROJECT.md §9): sy approver-init setup wizard, phone-passkey approval transport (WebAuthn research note included), Telegram transport, seccomp read-only profile.

curl -LO https://github.com/xezpeleta/sysh/releases/download/v0.4.0/sysh_0.4.0_amd64.deb
apt install ./sysh_0.4.0_amd64.deb
sysh doctor

v0.3.0 — phase 2: the approval channel

Choose a tag to compare

@xezpeleta xezpeleta released this 04 Oct 14:40

Phase 2: the approval channel — root the agent can only ask for.

Between "never root" and "pre-authorized root" there is now a middle way: rules with approval = true. The agent's exec exits 30 with a request id and executes nothing; a human answers from any root SSH session; the agent fetches the outcome read-only.

  • Gateway request flow: deterministic request ids (identical live requests dedupe), a drop box with strict grammar, O_NOFOLLOW/O_NONBLOCK reads, TTLs (requests 10 min, results 1 h), approval-fatigue bound (max 5 live requests)
  • sysh approvals / approve / deny (root, real TTY required): every approval re-checks the argv against the installed policy — an operator cannot approve what policy forbids; pattern-chosen arguments must be typed by hand at the prompt; execution runs in a one-shot systemd-run scope (TasksMax, MemoryMax, timeout, output caps); results land root:sy 0640
  • Exclusive claim: concurrent approvals of the same request cannot double-execute (O_EXCL marker, released on every exit path; stranded markers stealable after the request TTL). The race was found and closed live before release
  • Tamper resistance: request ids are bound to their content — a body rewritten under a valid-looking name is refused before any human or policy sees it; the drop box is sticky (1730) so sy cannot remove root's claim markers
  • Exit codes: 30 approval required, 31 result unavailable
  • policy.Parse now refuses unknown TOML fields — a typo is policy, not a silent default
  • examples/webserver: the apache2 restart moved to the approval channel (reload is the routine; restart drops connections — the agent can only request it); usage docs cover the full approve cycle

Verified end-to-end on a live host: full approve/fetch cycle, typed-argument challenge (and its wrong-answer abort), deny, dedupe, the concurrent-approval race, and symlink/FIFO/tampered-request probes.

Deferred (frontends and adjacent, not blockers): FIDO2/Telegram approval transports, seccomp read-only profile, sysh-mcp distribution.

curl -LO https://github.com/xezpeleta/sysh/releases/download/v0.3.0/sysh_0.3.0_amd64.deb
apt install ./sysh_0.3.0_amd64.deb
sysh doctor

v0.2.0 — phase 1.5: privileged rules

Choose a tag to compare

@xezpeleta xezpeleta released this 04 Oct 14:28

Phase 1.5: pre-authorized root verbs — the routine you'd automate anyway (enumerated write, validate, reload) runs unattended, root included, but only through exact actions the operator wrote down.

  • Privileged rules execute as root via exact-argv sudo grants written and validated by sysh policy install: no wildcards, no ALL, no NOPASSWD: beyond the enumerated argv; no_new_privs stays on; execution happens in per-exec systemd scopes with journald + auditd events carrying PRIV=true — the record exists on both sides of the elevation
  • Privileged timeouts via sudoers TIMEOUT plus a gateway grace kill, so a hanging root verb dies at the boundary the operator set
  • sysh doctor gains the --allow-groups opt-in check (secondary groups for the sy user), and a Wazuh agent ruleset profile is documented for SIEM shipping
  • examples/webserver: a worked agent-maintained web server — Apache and fail2ban config, logs, validate, reload — with the OS-side setup and the honest limits spelled out
  • Project website with emulated session replays (an agent session and a plain-ssh session, same bounds and same record)

Honest limits: per-exec approvals still deferred (privileged-adjacent argv without a grant refuses at exit 126); no seccomp yet; amd64 only. The approval channel — root the agent can only ask for — is in main for v0.3.0.

curl -LO https://github.com/xezpeleta/sysh/releases/download/v0.2.0/sysh_0.2.0_amd64.deb
apt install ./sysh_0.2.0_amd64.deb
sysh doctor

v0.1.0 — phase 1

Choose a tag to compare

@xezpeleta xezpeleta released this 03 Oct 09:56

First tagged release: the complete phase-1 control layer.

What it is: agents connect as the unprivileged sy user over SSH; the login shell (/usr/bin/sysh) enforces an operator-written argv policy with no shell semantics, and records everything server-side (journald + auditd, kernel-attested).

  • Gateway: printable-ASCII argv split, exact-length matching, opt-in rest patterns, deny rules with prefix semantics, per-rule timeouts with process-group kill backstop, 1 MiB output cap
  • Containment: NoNewPrivs, systemd scope execution (no-scope fallback), ptrace_scope=1, root-only policy tree
  • Observability: journald events with key attribution (fingerprint, key id), policy hash, pre/post phases; auditd keys sysh_exec / sysh_policy / sysh_lockdown
  • Operator channel: sysh auth add/list/remove (option allowlist, canonical lines), sysh policy install/lint (denylist, warn-ack, permissive gated on auditd), sysh doctor (22 checks), sysh lockdown, sysh journal-group
  • One static Go binary, one .deb that does all host-local setup; snapshot-tested on Debian 12 (deployed and cold-reboot verified)

Honest limits: no seccomp yet (phase 2), approvals deferred (privileged rules refuse at exit 126), amd64 only.

curl -LO https://github.com/xezpeleta/sysh/releases/download/v0.1.0/sysh_0.1.0_amd64.deb
apt install ./sysh_0.1.0_amd64.deb
sysh doctor