README
¶
hallpass
Documentation: alban.github.io/hallpass
Run a program in your shell, and get asked before it writes outside your project. hallpass was built for AI coding agents, and is useful for any program you don't fully trust: installers, package hooks, unfamiliar builds.
$ cd ~/src/myproject
$ hallpass --allow-path ~/.copilot --allow-path ~/.cache/copilot -- copilot
Agents keep their own state (sessions, logs, caches) outside the project: the -allow flags let copilot write it without asking. They are optional: without them, hallpass asks you when copilot writes there, which is a good way to see what an agent touches. Other agents (claude, codex, gemini, agy, aider, ...) work the same, with their own directories; plain hallpass starts a shell.
Everything the program starts (shells, compilers, git, npm, scripts) inherits the sandbox. Writes inside the project directory go through without asking. Writes anywhere else make hallpass pause the process and ask you in a bar drawn over the bottom of your terminal, like a tmux status line:
hallpass: node (pid 41237) wants to write
/home/me/.npm/_cacache/tmp/x
by: npm install ← bash ← copilot
[t] and [a] allow: /home/me/.npm/_cacache
[o] allow once [t] for 5m0s [a] always [d] deny [n] never [Esc] dismiss
Without a terminal, hallpass asks with a desktop notification, or from another terminal or a browser. See Answers and rules for what each answer does.
Status: proof of concept. It catches honest mistakes; it does not contain a hostile program yet. See the security model.
Why
Any program you run can write wherever your user can. Some have their own permission prompts and sandboxes, such as AI agent CLIs, but those are enforced by the program itself and configured by files it can often write. hallpass is enforced by the kernel, from outside the program, so it does not depend on the program being well-behaved. It complements the program's own controls rather than replacing them.
How it works
hallpass combines two kernel mechanisms:
- seccomp user notification (lite mode, the default, unprivileged): a seccomp filter pauses the syscalls that modify the filesystem and hands them to hallpass, which resolves the path, applies the policy and, if needed, asks you.
- BPF-LSM (strict mode,
--mode=strict, root needed only to load it): it still asks like lite mode, and enforces your answers in the kernel on the real file, so a process cannot race the check or hide the target behind symlinks, bind mounts or other mount namespaces.
With --mediate=write,exec,connect (experimental), hallpass also asks before connections and sends to IP addresses and unix sockets.
Get started
Requires Linux 5.9 or later (strict mode: 6.12), amd64 or arm64.
go build ./cmd/hallpass
./hallpass -- copilot # or any command; no command: a shell
Documentation
- Install, Usage (default policy, agent CLIs, over ssh), Agents (asking in advance with
hallpass-request), CLI reference (flags), Strict mode, Use cases (audit, CI, checking a tool's declared paths) - Kubernetes: sandbox pods with a node agent and answer from Headlamp
- Answers and rules, Web UI, Write a client for the session API
- How it works: design, security model and limitations
Developer notes are in docs/devel/.
License
The hallpass user-space components are licensed under the Apache License, Version 2.0. The BPF programs in bpf/ are dual-licensed GPL-2.0-only OR BSD-2-Clause: the kernel requires a GPL-compatible license to load LSM programs, while the BSD option keeps them reusable.
Documentation
¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
session/v1
Package sessionpb is the generated code of the session API (session.proto).
|
Package sessionpb is the generated code of the session API (session.proto). |
|
cmd
|
|
|
hallpass
command
Command hallpass runs a command (typically an AI agent CLI) so that writes outside its project directory need the user's approval.
|
Command hallpass runs a command (typically an AI agent CLI) so that writes outside its project directory need the user's approval. |
|
hallpass-node
command
Command hallpass-node is the hallpass Kubernetes node agent (a DaemonSet): an NRI plugin that adds a seccomp profile to the containers of opted-in pods, the seccomp agent runc hands their listeners to, and one session API for all of them.
|
Command hallpass-node is the hallpass Kubernetes node agent (a DaemonSet): an NRI plugin that adds a seccomp profile to the containers of opted-in pods, the seccomp agent runc hands their listeners to, and one session API for all of them. |
|
headlamp-wasm
command
|
|
|
demos
|
|
|
strict/race
command
Command race races hallpass's check of an open(2) path, for the strict demo (demos/strict).
|
Command race races hallpass's check of an open(2) path, for the strict demo (demos/strict). |
|
internal
|
|
|
answer
Package answer maps a prompt answer (once, temp, always, group, deny, never; grant for a request made in advance) to a monitor decision with a session's policy, and describes a request the way prompts show it.
|
Package answer maps a prompt answer (once, temp, always, group, deny, never; grant for a request made in advance) to a monitor decision with a session's policy, and describes a request the way prompts show it. |
|
config
Package config reads and writes hallpass's settings file, a list of "key = value" lines ('#' starts a comment).
|
Package config reads and writes hallpass's settings file, a list of "key = value" lines ('#' starts a comment). |
|
defaults
Package defaults is hallpass's policy, as monitor rules: the project directory, $TMPDIR, harmless devices and --allow-path are writable, --deny-path is denied, --ask-path is asked even inside them, and anything else is asked.
|
Package defaults is hallpass's policy, as monitor rules: the project directory, $TMPDIR, harmless devices and --allow-path are writable, --deny-path is denied, --ask-path is asked even inside them, and anything else is asked. |
|
dnsnames
Package dnsnames names the network destinations of a session: the host names its processes asked their DNS servers about, mapped to the addresses those names have.
|
Package dnsnames names the network destinations of a session: the host names its processes asked their DNS servers about, mapped to the addresses those names have. |
|
fdstore
Package fdstore keeps file descriptors for another process, so that they survive its crash or upgrade: the hallpass node agent stores there the seccomp listeners it mediates and their journals, and takes them back when it starts.
|
Package fdstore keeps file descriptors for another process, so that they survive its crash or upgrade: the hallpass node agent stores there the seccomp listeners it mediates and their journals, and takes them back when it starts. |
|
launch
Package launch is hallpass's local launcher: it starts a command with the seccomp filter installed, paused before its exec until the caller has attached the filter's listener to a monitor.
|
Package launch is hallpass's local launcher: it starts a command with the seccomp filter installed, paused before its exec until the caller has attached the filter's listener to a monitor. |
|
lsm
Package lsm is strict mode's enforcement: BPF-LSM programs that check every write of the sandbox against the session's rules in the kernel, on the object being modified, so path races and bind mounts cannot get around the decisions taken by the seccomp supervisor.
|
Package lsm is strict mode's enforcement: BPF-LSM programs that check every write of the sandbox against the session's rules in the kernel, on the object being modified, so path races and bind mounts cannot get around the decisions taken by the seccomp supervisor. |
|
monitor
Package monitor is the mechanism of hallpass, a reference monitor for one workload: it mediates the workload's writes with seccomp user notification (lite) and BPF-LSM (strict), applies rules and verdicts, and reports what it cannot decide.
|
Package monitor is the mechanism of hallpass, a reference monitor for one workload: it mediates the workload's writes with seccomp user notification (lite) and BPF-LSM (strict), applies rules and verdicts, and reports what it cannot decide. |
|
netdiag
Package netdiag lists listening sockets with NETLINK_SOCK_DIAG, and finds which processes hold them, so lite mode can tell a listener started inside the sandbox from one outside.
|
Package netdiag lists listening sockets with NETLINK_SOCK_DIAG, and finds which processes hold them, so lite mode can tell a listener started inside the sandbox from one outside. |
|
nodeclient
Package nodeclient is a client of the node agent's session API (a sessionapi.Node).
|
Package nodeclient is a client of the node agent's session API (a sessionapi.Node). |
|
ociseccomp
Package ociseccomp turns the hallpass rule table (internal/seccomp) into an OCI seccomp profile, merged into the profile a container already has, so that a container runtime (runc) installs the filter and hands its listener to the hallpass node agent.
|
Package ociseccomp turns the hallpass rule table (internal/seccomp) into an OCI seccomp profile, merged into the profile a container already has, so that a container runtime (runc) installs the filter and hands its listener to the hallpass node agent. |
|
policy
Package policy is a sandbox's policy as people write it: with the flags of hallpass, in a HallpassPolicy, or in a policy file.
|
Package policy is a sandbox's policy as people write it: with the flags of hallpass, in a HallpassPolicy, or in a policy file. |
|
privsep
Package privsep gets strict mode's BPF programs loaded without running hallpass as root: a short-lived helper (hallpass itself, started through sudo, pkexec, ..., or by the user as root with --escalate=manual) loads and attaches them, hands the map and link fds to the unprivileged supervisor, and exits.
|
Package privsep gets strict mode's BPF programs loaded without running hallpass as root: a short-lived helper (hallpass itself, started through sudo, pkexec, ..., or by the user as root with --escalate=manual) loads and attaches them, hands the map and link fds to the unprivileged supervisor, and exits. |
|
procfs
Package procfs resolves a target process's syscall arguments (dirfd + path string) into an absolute, symlink-free path, by reading /proc/<pid>/{cwd,fd,mem}: a host path, or a path below a root directory such as /proc/<pid>/root for a process in a container.
|
Package procfs resolves a target process's syscall arguments (dirfd + path string) into an absolute, symlink-free path, by reading /proc/<pid>/{cwd,fd,mem}: a host path, or a path below a root directory such as /proc/<pid>/root for a process in a container. |
|
programs
Package programs names groups of programs (@shells, @coreutils...) and finds programs as the sandbox does: by name in $PATH, symlinks resolved, on the host or in a container's root.
|
Package programs names groups of programs (@shells, @coreutils...) and finds programs as the sandbox does: by name in $PATH, symlinks resolved, on the host or in a container's root. |
|
rulepb
Package rulepb converts rules to and from the session API messages.
|
Package rulepb converts rules to and from the session API messages. |
|
rules
Package rules holds the monitor's rule model and its evaluation.
|
Package rules holds the monitor's rule model and its evaluation. |
|
sessionapi
Package sessionapi serves a hallpass session's API (package sessionpb) on its unix socket, and connects to it.
|
Package sessionapi serves a hallpass session's API (package sessionpb) on its unix socket, and connects to it. |
|
tty
Package tty runs the sandboxed program on a pseudo-terminal that hallpass relays to the user's terminal, like script(1) or tmux, so hallpass can ask questions in an overlay without the program seeing or answering them.
|
Package tty runs the sandboxed program on a pseudo-terminal that hallpass relays to the user's terminal, like script(1) or tmux, so hallpass can ask questions in an overlay without the program seeing or answering them. |
|
ui
Package ui presents access prompts to the user and returns their answer.
|
Package ui presents access prompts to the user and returns their answer. |
|
web
Package web serves a browser UI to follow hallpass sessions and answer their requests: `hallpass web` for all sessions, or a session for itself (NewSession).
|
Package web serves a browser UI to follow hallpass sessions and answer their requests: `hallpass web` for all sessions, or a session for itself (NewSession). |
Click to show internal directories.
Click to hide internal directories.