Leash help & setup guide

Leash attaches to one host user (the leashed account). The agent runs as that user; Leash runs privileged (root) so the agent can't bypass it. Every decision is keyed to that user's UID and is a hard allow or block — v1 has no approval loop (that arrives with Sentinel).

• Four surfaces: network (domains/IPs/ports), filesystem (paths), commands (binaries), tools (names + input inspection).
• Each surface has a mode: follow-whitelist (default-deny, only approved) or follow-blacklist (default-allow, everything but).
• Network and filesystem/commands are kernel-enforced for the leashed UID; tools is cooperative (the harness calls Leash).
• Linux only.

Run the installer from the v1 directory on a root-capable Linux host. It attaches to (or creates) the leashed user, installs the source tree, a default config, and a systemd unit.

# leash the user 'fido' (created if absent)
sudo LEASH_USER=fido bash install.sh
sudo systemctl daemon-reload
sudo systemctl enable --now leash
systemctl status leash

• Install tree: /opt/leash/v1 · Config: /etc/leash/leash.yaml · Unit: /etc/systemd/system/leash.service · Log: /var/log/leash/decisions.jsonl · CLI: /usr/local/bin/leash.
• Reinstalling preserves an existing config (defaults are written to <config>.example instead).

Leash is driven by /etc/leash/leash.yaml — the leashed user, fail_mode, and one block per surface (mode + allow + deny). Edit it directly or with the leash CLI.

user: fido               # the leashed account
fail_mode: closed        # block if an enforcer errors (or: open)
network:    { mode: whitelist, allow: ["github.com:443", "10.0.0.0/8"] }
filesystem: { mode: whitelist, allow: ["/home/fido/work"] }
commands:   { mode: blacklist, deny: ["rm", "ssh"] }
tools:      { mode: whitelist, allow: ["search"],
              inspect: { secrets: block, pii: block } }
logging:    { decisions: /var/log/leash/decisions.jsonl }
enforcers:  { network: true, filesystem: true, tools: true }

• whitelist = only listed entries allowed; blacklist = everything but the listed entries.
• Network entries can pin a port (github.com:443) or match any port (github.com); IPs use CIDR (10.0.0.0/8).

The installer puts a leash command on PATH. List/mode edits rewrite the config and restart the service; check and logs are read-only. The config path comes from --config/-c or the LEASH_CONFIG env var (default /etc/leash/leash.yaml).

leash init --user fido          # set the leashed user
leash status                    # user, per-surface modes, enforcer state
leash validate                  # check the config

leash check network github.com:443
leash check network evil.com:443
leash check filesystem /home/fido/work/a.txt
leash check commands /usr/bin/ssh

leash network mode whitelist
leash network allow github.com:443
leash filesystem allow /home/fido/work
leash commands mode blacklist
leash commands deny rm
leash tools allow search

leash logs --follow --tail 50   # tail the decision log
leash restart

• Surface names accept aliases: filesystem/fs, commands/cmd, tools/tool.
• A blocked action returns a hard error (connection reset / EPERM) plus a log line with the reason.

The uninstaller removes the install tree, config, logs, unit, and CLI wrapper. It leaves the leashed host user in place.

sudo bash uninstall.sh