Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Dependency update pull requests: Go modules (and the toolchain line of
# go.mod) and the GitHub Actions, which the workflows pin by full commit
# SHA. One grouped pull request per ecosystem per week.
version: 2
updates:
- package-ecosystem: gomod
directory: /
schedule:
interval: weekly
groups:
go-modules:
patterns: ["*"]
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
groups:
actions:
patterns: ["*"]
commit-message:
prefix: ci
9 changes: 7 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,13 @@ jobs:
env:
CGO_ENABLED: "0"
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
# Actions are pinned by commit SHA; Dependabot keeps them current.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# go-version-file installs exactly the go line of go.mod, so that
# line names the patch release the binaries are built with.
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
- name: gofmt, vet, unit tests
Expand Down
25 changes: 25 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,31 @@

## Unreleased

- Build: go.mod names Go 1.27.4 (CI builds with that line); the CI
actions are pinned by commit SHA, and Dependabot proposes Go module
and action updates weekly.
- `cotty agent` refuses a kernel without Landlock (ABI 0) unless given
`--allow-no-landlock`; it used to start the agent without Landlock and
the session still reported it `confined`. Sessions now report every
agent `weak` on such a kernel, and `cotty doctor` says so.
- Assurance: an agent is `confined` only when the broker sees that the
trusted cotty binary built its confinement (pid 1 of its pid namespace
runs cotty agent's init stage, and the agent is in that namespace's
user namespace and mount view with no_new_privs and seccomp). Its own
user namespace (`unshare -U`), a `cotty-agent*` cgroup or a guard tag
no longer raise the level, so they no longer pass `--require-confined`
or hide the red warning. Agents under the guard without layer 2, peers
whose pid the broker cannot see, and every agent while the cotty binary
is writable by the user now read `weak`.
- Confirm policy: agents may no longer press Tab or BTab (completion ran
project files such as `./configure --help` and Makefile `$(shell ...)`
in your shell before any approval), Up, Down, PgUp or PgDn (they
recalled commands typed in private mode), nor type tabs, history
expansion (`!`, `^`) or, outside a UTF-8 locale, bytes above 0x7f
(Meta keys for readline). Left: text, held Enter, Backspace, Delete,
Space, Left, Right, Home, End and C-c (docs/broker.md, Confirm policy).
- Docs: private mode does not keep a command out of the shell's history;
README and docs/broker.md say so where private mode is described.
- The pts exception list lapses with cotty-guard's daemon: a clean stop
empties it in the kernel, and the programs stop honouring it once the
daemon's heartbeat is 90 s old, so a listed pinentry is refused while
Expand Down
26 changes: 19 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,14 @@ channels are opt-in.
`cat ~/.config/x/token` prints a secret cotty does not know about.
- Not a guard for secrets typed with echo on. `export TOKEN=...` is visible
to the agent unless you turned on private mode first or the value is on
the masking list.
the masking list. Private mode hides the rows, not the shell's history:
once it is off, an agent can draw the command again (Up, `history`,
`!!`, a zsh autosuggestion) and read it. Under `--policy confirm` the
keys and characters that recall history are refused to agents in bash
and zsh; under the default policy nothing stops it. Start such a command
with a space and have the shell skip it (bash
`HISTCONTROL=ignorespace`, zsh `setopt HIST_IGNORE_SPACE`), or put the
value on the masking list.
- Not a defence against a malicious kernel or root.
- Not a network filter. A confined agent can reach any TCP or UDP service
you can, including services on localhost.
Expand Down Expand Up @@ -63,11 +70,15 @@ weakest one in the status line:
| Level | Meaning |
| --- | --- |
| `strong` | the guard is loaded and confirms the session pts protection, and the agent runs under `cotty agent` and is tagged by the guard |
| `confined` | the agent runs under `cotty agent`, no guard (or the guard without `cotty agent`) |
| `weak` | no confinement evidence: an agent CLI started without `cotty agent`, or any other program of yours |
| `confined` | the agent runs under `cotty agent` (the broker checks that the agent's namespaces were built by the installed cotty binary), no guard |
| `weak` | no confinement evidence: an agent CLI started without `cotty agent`, a program in namespaces it made itself or tagged by the guard on its own request, or any other program of yours |
| `insecure` | broker started with `--dev-insecure` (development only) |

What each level stops, case by case, is in docs/security.md.
The level describes the agent's MCP server, the process that connects to
the session. It keeps out agents that did not go through `cotty agent`;
it is not proof against a program that already runs with all your rights,
which can start a confined MCP server for itself. What each level stops,
case by case, is in docs/security.md.

## Requirements

Expand Down Expand Up @@ -138,9 +149,10 @@ without `.git` (its hooks and config are then the agent's),
`--allow-git-links` accepts a project whose `.git`, git config or hooks
are symbolic links, and `--allow-abstract-sockets` starts on kernels
below Landlock ABI 6 even though a display or session bus is reachable
through abstract sockets there. `--show-hidden` leaves a profile's
hidden directories visible (for Claude Code, `~/.claude/ide`, whose lock
files hold your IDE's auth token).
through abstract sockets there. `--allow-no-landlock` starts on a kernel
without Landlock, where sessions then report the agent `weak`.
`--show-hidden` leaves a profile's hidden directories visible (for Claude
Code, `~/.claude/ide`, whose lock files hold your IDE's auth token).

The lock does not light for a password prompt inside a program that
relays the terminal in raw mode (`sudo -i`, `ssh`, `tmux`, `screen`):
Expand Down
1 change: 1 addition & 0 deletions cmd/cotty/cmd_agent.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ func runAgent(args []string) int {
fs.BoolVar(&opts.Quiet, "quiet", false, "no banner (gaps are printed anyway)")
fs.BoolVar(&opts.AllowGitInit, "allow-git-init", false, "in a project without .git, let the agent create one (its hooks and config would run with your rights when you use git there)")
fs.BoolVar(&opts.AllowAbstractSockets, "allow-abstract-sockets", false, "start on Landlock ABI < 6 even when X11 or D-Bus listen on abstract sockets the agent could reach")
fs.BoolVar(&opts.AllowNoLandlock, "allow-no-landlock", false, "start on a kernel without Landlock, where only the mount view limits the agent's files (sessions report the agent weak)")
fs.BoolVar(&opts.AllowGitLinks, "allow-git-links", false, "start even when a git file cotty protects (.git, its config or hooks, core.hooksPath) is a symbolic link the agent could replace")
fs.BoolVar(&opts.ShowHidden, "show-hidden", false, "leave the profile's hidden directories visible (claude: ~/.claude/ide, whose lock files hold your IDE's auth token; needed when the agent should talk to your IDE)")
fs.BoolVar(&list, "list-profiles", false, "list the profiles and exit")
Expand Down
2 changes: 2 additions & 0 deletions cmd/cotty/cmd_doctor.go
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,8 @@ func sessionsSummary(layer2 string, checks []confine.Check) (string, string) {
return "unavailable (cotty agent cannot start here)", ""
case status["binary"] == "warn":
return "weak (the cotty binary can be replaced by your user)", "Sessions report weak until cotty is installed root-owned (see the binary line above)."
case status["landlock"] == "fail":
return "weak (no Landlock: agents cannot be confined here)", "Sessions report every agent weak on a kernel without Landlock (see the landlock line above)."
case guardRunning:
return "strong available for new sessions (cotty-guard running)",
"Sessions created before cotty-guard started stay at their level (confined); start a new session to get strong."
Expand Down
1 change: 1 addition & 0 deletions cmd/cotty/doctor_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ func TestSessionsSummary(t *testing.T) {
{"guard not running", "confined", []confine.Check{check("binary", "ok"), check("guard", "info")}, "confined (cotty-guard not running)", "before cotty-guard starts stay confined"},
{"guard not answering", "confined", []confine.Check{check("binary", "ok"), check("guard", "warn")}, "confined (cotty-guard not answering)", ""},
{"untrusted binary", "confined", []confine.Check{check("binary", "warn"), check("guard", "ok")}, "weak", ""},
{"no landlock", "partial", []confine.Check{check("binary", "ok"), check("landlock", "fail"), check("guard", "ok")}, "weak (no Landlock", "every agent weak"},
{"no namespaces", "unavailable", []confine.Check{check("binary", "ok"), check("guard", "ok")}, "unavailable", ""},
} {
got, note := sessionsSummary(tc.layer2, tc.checks)
Expand Down
9 changes: 5 additions & 4 deletions docs/PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,10 +114,11 @@ knows it reached the session's broker (docs/protocol.md section 7).

The resulting assurance is reported, like basalt-shell's modes: `strong`
(guard loaded, the session's pts protection confirmed by the guard, and
the agent tagged by it and under layer 2), `confined` (layer 2 active, no
guard; or the guard without layer 2), `weak` (agent not started through
`cotty agent`; the docs say what that means), `insecure` (development
only).
the agent tagged by it and under layer 2), `confined` (layer 2 active and
built by the trusted cotty binary, no guard), `weak` (agent not started
through `cotty agent`, including one under the guard without layer 2: a
tag or namespaces a process can give itself raise nothing; the docs say
what that means), `insecure` (development only).

## 4. Enforcement layers

Expand Down
62 changes: 61 additions & 1 deletion docs/broker.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,13 @@ attaching and prints the reattach code.

`--require-confined` (off by default) refuses agent connections whose
assurance is `weak`: agents started without `cotty agent`, or any program
of yours that speaks the protocol. They get `confinement_required`, the
of yours that speaks the protocol, including one in namespaces it made
itself (`unshare -U`) or tagged by the guard at its own request. The
broker accepts a confinement only when the trusted cotty binary built it
(docs/security.md, Assurance levels); a program that already has your
rights can still start a confined MCP server for itself, so this keeps
out agents that skipped `cotty agent`, not a program that is out to
deceive you. They get `confinement_required`, the
audit log records the refusal and the status line counts it. Without the
option such agents are accepted and the status line shows them in red
("1 unconfined agent"), so you always know when an agent could reach more
Expand All @@ -32,6 +38,41 @@ for a running session (and closes the weak agents already connected);
`--require-confined=false` turns it off; plain `cotty share` keeps the
setting.

## Confirm policy

`--policy confirm` holds every Enter an agent types until you accept the
line (`^] y`) or reject it (`^] n`). What the agent types before the Enter
reaches the shell at once, so under this policy agents are refused
(`policy_denied`) every key and character that makes the line editor act
on its own:

- Tab and BTab. Completion runs programs: bash-completion runs
`./configure --help` to list its options and `make -npq`, which
evaluates `$(shell ...)` in a Makefile, and zsh's completion does the
same. A file the agent wrote in the project would run with your rights
before you were asked anything.
- Up, Down, PgUp and PgDn: they recall the shell's history, commands
typed in private mode included (see Private mode below).
- Esc, Insert, F1 to F12 and every Ctrl and Meta key except C-c: among
them C-p, C-r, M-. and M-< recall history, and C-x C-e, M-C-e
(shell-expand-line) and C-o run or submit the line.
- In text: tabs, control characters other than Enter, Backspace and C-c,
escape sequences, history expansion (`!` followed by anything but a
blank, `=` or `(`, and `^`), and, when the shell's locale is not UTF-8,
bytes above 0x7f. Space bound to magic-space (oh-my-zsh does that)
expands `!!` or `^old^new` on the screen without an Enter, and after an
Enter the expanded line, not the one you approved, would run. In a C or
POSIX locale readline reads bytes above 0x7f as Meta keys, and M-C-e
runs the command substitutions of the line.

Left are text, Enter (held), Backspace, Delete, Space, Left, Right, Home,
End and C-c. These decisions follow the default bindings of bash
(readline) and zsh (zle), in emacs and vi mode. A binding of your own that
makes one of the keys left run something (a widget on Space or End) is not
known to cotty, and neither is readline's `convert-meta` turned on in a
UTF-8 locale. Under the default policy (`auto`) an agent types and runs
whatever it wants.

## The session's shell

The shell runs with `HISTFILE` set to
Expand Down Expand Up @@ -94,6 +135,25 @@ Hotkeys: `Ctrl-]` then
| ? | help |
| Ctrl-] | send a literal Ctrl-] |

## Private mode

`^] p` turns private mode on: agent input is refused with
`private_mode`, and what agents read is frozen at the moment it started;
rows written meanwhile read `[private]` afterwards. Private mode hides
rows, not what the shell keeps. A command line you type in private mode
stays in the shell's history, and once private mode is off an agent can
draw it on the screen again and read it: with Up or `!!`, with `history`
or `fc -l`, or through a zsh autosuggestion that shows history while it
types. Under `--policy confirm` the history keys and history expansion
are refused to agents (Confirm policy above), which covers bash and zsh
with their default bindings, but a `history` you approve still prints the
line, and autosuggestions still show it. Under the default policy nothing
stops it. cotty cannot keep a line out of every shell's history, so for a
secret typed with echo on: start the command with a space and set
`HISTCONTROL=ignorespace` (bash) or `setopt HIST_IGNORE_SPACE` (zsh, which
still keeps the line until the next command runs: run any command right
after it), or put the value on the masking list (`cotty secrets add`).

## The lock

A secret prompt is ECHO off with ICANON on in the PTY's termios (sudo, su,
Expand Down
16 changes: 14 additions & 2 deletions docs/confinement.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ optional, see [guard.md](guard.md).

```
cotty agent [--profile P] [--project DIR] [--ro PATH] [--rw PATH] [--agent-dir DIR] [--no-mcp]
[--allow-git-init] [--allow-git-links] [--allow-abstract-sockets] [--quiet] [--] CMD [ARGS...]
[--allow-git-init] [--allow-git-links] [--allow-abstract-sockets] [--allow-no-landlock] [--quiet] [--] CMD [ARGS...]
cotty agent --profile claude # runs the profile's own command
cotty agent --list-profiles
cotty agent --dry-run -- claude -p hi # print the computed plan as JSON
Expand Down Expand Up @@ -279,6 +279,15 @@ count. `--allow-abstract-sockets` accepts the risk. The exec stage refuses a ker
launcher made that decision, so Landlock's best-effort mode never drops
the scoping silently.

A kernel without Landlock at all (ABI 0: not built in, or not in the
`lsm=` boot list, as on some older enterprise kernels and cloud images) is
refused too: only the mount view would limit the agent's files, and
abstract sockets and signals would not be scoped. `--allow-no-landlock`
starts the agent anyway; the exec stage then goes on without Landlock
only because the launcher recorded that decision, and sessions report
the agent `weak`, since what it can reach is no longer what `confined`
means (review COT-4).

### Seccomp

A classic BPF filter written in Go (`internal/confine/seccomp_linux.go`),
Expand Down Expand Up @@ -405,7 +414,10 @@ included):

`cotty agent` prints the level when it starts and passes it to the agent
as `COTTY_ASSURANCE`. The broker's own assurance levels (`strong`,
`confined`, `weak`, `insecure`, PLAN section 3) build on this.
`confined`, `weak`, `insecure`, PLAN section 3) build on this: the broker
does not read `COTTY_ASSURANCE` (the agent could change it) but checks
that pid 1 of the agent's pid namespace is the trusted cotty binary
running the init stage (docs/security.md, Assurance levels).

`cotty doctor` then names the level a session created now can reach:
`strong available for new sessions (cotty-guard running)`, `confined
Expand Down
2 changes: 1 addition & 1 deletion docs/guard.md
Original file line number Diff line number Diff line change
Expand Up @@ -337,7 +337,7 @@ from `SO_PEERCRED` and `SO_PEERPIDFD` (Linux 6.5), never from the message:
| Request | Who | What |
| --- | --- | --- |
| `register` (+ socket and directory fds) | a process that is not an agent, in a cgroup whose name starts with `cotty-agent` and which it owns (at most 1024 per user) | its own cgroup becomes an agent cgroup; the sockets go on that agent's allowlist; the directories are guarded, the last `guard` of them without connect rights |
| `tag-self` | anyone | the caller is tagged (it only restricts) |
| `tag-self` | anyone | the caller is tagged (it only restricts; the broker never counts a tag as confinement, so a self-tag cannot raise an agent's assurance) |
| `protect-pts` (+ terminal fd, `O_PATH` is enough, and its master) | a registered broker that holds the terminal's master, when no other live process protects it (at most 1024 per user) | while the caller runs, the terminal opens only for the caller and for the processes whose controlling terminal it is, never for an agent |
| `check-pts`, `release-pts` (+ terminal fd) | the process that protected it | whether the protection is in place for the caller; end it |
| `register-broker` (+ session name, the runtime directory and its agent directory) | a broker: the installed cotty binary (root-owned, at a configured path, in root-owned directories, none writable by group or others) running `__broker` without `-dev-insecure`, not dumpable, not traced, not an agent; a session name no other live broker of the user holds (at most 256 per user) | the caller becomes the registered broker of that session name (by pid and start time, until it exits; the first registrant keeps the name); the directories (its user's, mode 0700) become cotty runtime directories |
Expand Down
4 changes: 3 additions & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,9 @@ error. The result ends with the bottom 20 rows of the screen.
asterisks) reads `[private]` afterwards.
- Private mode hides rows, not what programs keep: after it ends, shell
history, a redraw or a pager can print the text again as ordinary
output (docs/security.md, Known limits).
output (docs/broker.md, Private mode; docs/security.md, Known limits).
Under the confirm policy agents cannot press Up, Down or Tab, nor type
history expansion.
- Before a read the broker waits for the output to pause (80 ms quiet,
at most 400 ms) so a value is not caught half printed. This is best
effort: a value that arrives in pieces more than 80 ms apart can show
Expand Down
Loading
Loading