Skip to content

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

Choose a tag to compare

@xezpeleta xezpeleta released this 05 Oct 11:02
· 23 commits to main since this release

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/