Permissions, sandbox and audit
What decides whether one of oklm agent's tool calls
runs: the permission rules and modes, the calls that always ask, the
audit log of every decision, and the sandbox that confines commands.
Part of the agent harness (harness.md); the
settings files that hold the rules are in agent-settings.md.
Status: implemented.
Permissions
include/oklm/harness/permissions.h,
src/harness/permissions.c; the decisions of adr/0010-permission-rules.md.
oklm_perms* p;
oklm_perm_result r;
oklm_perms_new(".", &p); /* the project root */
oklm_perms_load_standard(p); /* managed, project local, project, user settings */
oklm_perms_add_rule(p, OKLM_SRC_CLI, OKLM_PERM_ALLOW, "Bash(make:*)");
oklm_perms_check(p, "Bash", "make test && git log", &r);
/* r.decision, r.rule, r.source, r.reason */- Rules are
ToolorTool(pattern)inallow,askanddenylists.denybeatsask, which beatsallow, whatever the source; the result names the strongest rule of the winning decision. - On the command line
oklm agenttakes rules for the session, beside those of the settings files:--allow RULE,--ask RULEand--deny RULE, one rule each, and--allowedTools RULES/--disallowedTools RULES(--allowed-tools/--disallowed-tools), a list of allow or deny rules separated by commas or blanks (--allowedTools "Read Bash(git log:*)"). They are not written to any file. - Bash: the command line is split into simple
commands at
;,&&,||,|,|&,&and newlines outside quotes; quotes and backslashes are removed, whitespace collapsed, comments dropped, line continuations joined. Every command must match an allow rule for the call to be allowed; any command matching a deny rule denies it.prefix:*(orprefix *, the same) matches the prefix followed by a space or the end. Command or process substitution, parentheses and unbalanced quotes make the line unparsable: it then matches no allow pattern (deny and ask rules still apply to the whole line), and the call asks. - Paths (
Read,Write,Edit,Readrules also forGlobandGrep,Editrules also forMultiEditandNotebookEdit): the argument is made absolute from the project root (~/from the home directory),.and..resolved, symbolic links of the longest existing prefix followed; the rule's glob is normalized the same way (its fixed part resolved). Globs follow gitignore:*and?in one segment,**across segments, classes; a glob naming a directory covers what is under it. SoRead(./secrets/**)also deniessrc/../secrets/keyandlink/keywhenlinkpoints tosecrets. - Domains:
WebFetch(domain:example.com)matches the URL's host and its subdomains, notexample.com.evil.netor a host named in the query. - Other tools match their main argument exactly or by
prefix*; a tool name ending in*matches tools by prefix (mcp__server__*). - Tools denied whatever the arguments (a deny rule
without a pattern:
Bash,WebFetch,mcp__serverfor all that server's tools, a prefix ending in*, or--disallowedToolsnaming one) are left out of what the model is offered: the system prompt's tool definitions, the deferred list, ToolSearch and the tool-call grammar, so a small model does not spend turns calling them; a call written anyway is still refused. A rule with a pattern (Bash(rm:*),Read(./secrets/**)) keeps the tool. - Modes decide calls no rule matches:
default(reads inside the project and its added directories run, the rest asks),acceptEdits(edits inside run too),plan(reads inside run, web fetches ask, everything else is denied, allow rules notwithstanding, until the user accepts the plan),bypassPermissions(everything runs; refused without the sandbox or when managed settings disable it; deny rules and dangerous calls still apply, and the terminal shows a warning banner). On the terminal Shift+Tab cycles them: default, acceptEdits, plan, then bypassPermissions when available;--dangerously-skip-permissionsstarts in bypassPermissions.
Dangerous calls
A pass after the rules and the mode turns an allow into an ask for
calls on the dangerous-pattern list, whatever allowed them (a rule,
acceptEdits, bypassPermissions); a deny stays a deny, plan mode still
refuses. The result says why (r.dangerous,
r.reason), and the question offers no "always". Built
in:
| Kind | Entries |
|---|---|
| Trees and disks | rm -r of /, the home directory,
., * or a system directory;
rm --no-preserve-root;
chmod/chown/chgrp -R of the same;
mkfs*, mkswap, wipefs,
fdisk, parted...; dd of=/dev/*;
shred |
| The machine | sudo, su, doas,
pkexec; shutdown, reboot...;
kill -1; crontab -r; a fork bomb; a download
(curl, wget) piped into a shell or an
interpreter, or substituted into one |
| Git and forges | push --force (-f,
--force-with-lease, --mirror,
+ref), push --delete (:ref),
reset --hard, checkout -- .,
restore ., clean -f, branch -D,
tag -d, stash drop/clear,
--no-verify, --no-gpg-sign,
core.hooksPath=, commit -n,
filter-branch, filter-repo,
update-ref, reflog expire,
gc --prune=now; gh pr merge/close,
gh release create/delete,
gh repo delete/archive, gh api with a method
or fields;
npm/pnpm/yarn/cargo publish,
gem push, twine upload |
| Integrations | docker/podman system prune,
volume rm, run --privileged,
-v /:..., -v /var/run/docker.sock:...;
kubectl delete, helm uninstall,
kind/minikube/multipass delete,
vagrant destroy, simctl erase,
adb uninstall off emulators;
terraform/tofu apply/destroy,
pulumi up/destroy,
aws/gcloud/az deletions;
ngrok, cloudflared tunnel,
ssh -R |
| Files written | /etc, /boot, /usr,
/bin, /sbin, /lib,
/dev/sd*, /dev/nvme*, ~/.ssh,
~/.gnupg, the shell's startup files,
~/.gitconfig, ~/.config/git,
~/.config/oklm, .oklm/settings*.json,
.git/hooks, .git/config: by Write, Edit,
MultiEdit, and by a command's redirections, tee,
cp/mv/install/ln/rsync
destination, sed -i/perl -i |
Commands are matched after variable assignments and wrappers
(env, nohup, timeout,
nice, xargs...), each simple command of the
line, and in a line with substitutions every word as a possible command.
The git entries needing the repository's state (a push to the default
branch, amending or rebasing pushed commits, git config
writes) come with git's own classifier (git_spec.md G2).
oklm_perms_add_danger(p, rule, why) adds entries, as
integrations do: Bash(head token...) where the head's
alternatives (a|b, wildcards) match the command's name and
each token must match a later word (-x a cluster of short
options holding x, --long alone or with
=value, =text literally, other text as a
wildcard pattern, !token none), or Edit(glob)
/ Write(glob) for paths.
Audit log
include/oklm/harness/audit.h,
src/harness/audit.c. Each decision is appended to the
session's log, .oklm/audit/<session>.jsonl, and
flushed before the tool runs: time (UTC),
session, tool, args (registered
secrets replaced by ***), decision,
by (rule or mode),
source, rule, reason,
answer (the user's answer to an ask).
oklm audit [--tool T] [--decision D] [--session S] [log.jsonl ...]
lists them.
Sandbox
include/oklm/harness/sandbox.h,
src/harness/sandbox.c; the decisions of adr/0011-sandbox.md. With a sandbox in
the tool context, every Bash command and background job runs, on Linux,
in new user, mount, process-id and IPC namespaces, and a new network
namespace (only an empty loopback) unless network access is allowed:
- every mount is remounted read-only (keeping the flags a user
namespace may not drop), after the writable directories (the project,
its added directories) were bound over themselves;
/tmpis a private tmpfs (unless a writable directory lies under it); - the paths the Read deny rules name are hidden: an empty read-only
tmpfs over a directory,
/dev/nullover a file (it reads empty, writes go nowhere); the paths the Write and Edit deny rules name are bound read-only, even inside the project. The list is taken from the rules when each command starts: a rule without wildcard gives its path, a rule with wildcards is expanded by walking the directory before its first wildcard (symbolic links and.gitnot entered, at most 100000 entries); a file created during the command is not covered; - the command is process 1 of its process-id namespace, with its own
/proc: it sees and signals only what it started, and whatever it left running dies with it. The forked child waits for it and exits with its status; - resource limits (
setrlimit): CPU time, address space, file size, open files and processes, each lowered, never raised; the process count is per user namespace (Linux 5.14 and later); and no core files, so a command killed by a limit leaves no dump behind; - the user's id is mapped to itself, so files written in the project are the user's;
no_new_privs, then a seccomp filter: calls of another architecture kill the process, x32 calls and mount, umount, the new mount API, unshare, setns, pivot_root, chroot, ptrace, bpf, keyctl and module loading fail with EPERM;- the network filtered by domain
(
proxy.h,proxy.c): without the network, whensandbox.allowedDomainsor aWebFetch(domain:...)allow rule names a domain, a proxy thread listens on a Unix socket ($XDG_RUNTIME_DIR/oklm-proxy-PID.sock, else the project's.oklm). Inside the command's network namespace loopback is brought up, a relay process listens on127.0.0.1:3128and passes each connection to the socket. The relay works in the socket's directory, held by a descriptor opened before the mounts: the socket is reached whatever covers its path in the command's view (the private/tmp, a hidden directory), and a path of any length works (only the file name has to fit a Unix socket address's 108 bytes; the proxy binds a longer path through/proc/self/fd). The command getsHTTP_PROXY,HTTPS_PROXY,ALL_PROXY(and their lower-case forms;NO_PROXYfor loopback). The proxy readsCONNECT host:port(https and any TCP) or an absolutehttp://request, checks the host (hostexactly,*.domainfor it and every name under it,*for all;sandbox.deniedDomainsand WebFetch deny rules win), connects and relays, else answers 403. The hosts it refused during a Bash call are added to the call's result for the model. A tool that ignores the proxy variables reaches nothing. The rules are read again before each request; an allowed name resolves on the host, so a domain pointing at a local address reaches it (allow domains you trust)./sandboxand the session's first line say which network the commands have; - the plan (mount table, flags, maps, filter) is prepared in the harness; the forked child only makes system calls, as fork() in a multithreaded process requires. A command that cannot be confined is not run (exit code 125).
oklm_sandbox_available() tries the namespaces once in a
child. oklm agent confines commands whenever it can
(--no-sandbox turns it off, --allow-network
keeps the network), which also makes the bypassPermissions
mode available; without the sandbox, bypass is refused and commands keep
asking. --limit NAME=VALUE sets a limit (cpu
seconds, memory, file bytes with an optional
K, M, G or T, files, procs; 0 unsets);
procs=4096 by default. Unconfined, the limits still apply
but for the process count, which RLIMIT_NPROC would take
over all the user's processes. Windows runs commands in a Job Object
carrying the memory, process and CPU-time limits (a job's own memory and
CPU limits too: § Declared
services; cross-compiled, untested on Windows), without file or
network confinement, and refuses to run a command asked to be confined;
its output's CR LF line ends become LF.
In bypass mode, Qwen3-4B asked to run
echo hi > ../escape.txt:
sh: 1: cannot create ../escape.txt: Read-only file system,
and it says the write failed.