Repository navigation
Releases
v0.6.2 — the teaching channel, hardened
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
privbadge 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
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
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
helpand 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_scriptsmodes 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
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
ownsysh policy install; the agent invokingsudoitself 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
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/removeregisters approver public keys (recommendedsk-*— hardware-backed: no signature without a physical touch).sysh approve <id> --showprints 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 thesysh-approvenamespace, 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_policyover plain SSH as the unprivilegedsyuser, 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. Forsk-*keys: an insert-your-YubiKey loop, PIN and touch insidessh-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
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_NONBLOCKreads, 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-shotsystemd-runscope (TasksMax, MemoryMax, timeout, output caps); results landroot: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) sosycannot remove root's claim markers - Exit codes:
30approval required,31result unavailable policy.Parsenow refuses unknown TOML fields — a typo is policy, not a silent defaultexamples/webserver: the apache2 restart moved to the approval channel (reload is the routine; restart drops connections — the agent can only request it);usagedocs 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
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, noALL, noNOPASSWD:beyond the enumerated argv;no_new_privsstays on; execution happens in per-exec systemd scopes with journald + auditd events carryingPRIV=true— the record exists on both sides of the elevation - Privileged timeouts via sudoers
TIMEOUTplus a gateway grace kill, so a hanging root verb dies at the boundary the operator set sysh doctorgains the--allow-groupsopt-in check (secondary groups for thesyuser), and a Wazuh agent ruleset profile is documented for SIEM shippingexamples/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-
sshsession, 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
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
restpatterns, 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