Security model
This page states what Luna's safety boundary guarantees and, just as important, what it
does not. It is a default-deny guard rail, not a sandbox. The reporting process is in
SECURITY.md at the repository root.
What the boundary protects, from whom, is in the Threat model; every control, with its code, test and CI job, is in Security controls; the rules a change to Luna follows are in the Secure development standard. What to do when something goes wrong is in Incident response.
The Security level control adjusts implemented firewall approval mechanisms,
with balanced as the migration default and off locked pending a verified container attestation
(tests/security-level-smoke.ts).
The layers
| Layer | Extension | Ships in | Enforces |
|---|---|---|---|
| Universal firewall and autonomy gate | tool-firewall |
every profile | Parses shell commands into effects, tiers every call (low, medium, high, critical) with session history, auto-allows routine work, judges medium actions in auto mode, denies critical ones, and audits every decision. See Autonomy gate. |
| Protected paths | protected-paths |
every profile | Blocks writes to agent-control files, including the firewall's policy, approvals and audit files and the unattended-run contract. |
| Delegation governance | delegation-guard, effort |
every profile | Every child agent is started only with the protections its parent has loaded, and verifies them itself before running a tool, failing closed. See Agent orchestration. |
| Secrets guard | secret-guard |
balanced and long-horizon; the other profiles record an exemption (tests/profile-protections-smoke.ts) |
A name- and pattern-based backstop: blocks writes to secret files and secret content, and shell commands that read, copy, encode or exfiltrate them. It also blocks every write to a path containing secret or credentials, which is why the other profiles go without it. Add it to another profile with extensions.add in overrides.json. |
| Tool I/O capture | tool-capture |
every profile | Lossless, rotating JSONL of every tool call and output, joined to the firewall audit by action hash; secrets flagged. See Tool I/O capture. |
| Domain governance | engagement-governance |
engagement |
Scope and rules-of-engagement enforcement, MCP-only mode, action-card approval, hash-chained audit for authorised engagements. |
| Web console | web-console and packages/web-ui |
most profiles | Token authentication, host and origin checks, an RPC allow-list. See Web console. |
| Remote control | remote-control and packages/web-ui/server/remote-host.ts |
most profiles | Phones linked by a one-time code plus approval at the terminal, keystore keys, a pinned TLS certificate, short-lived tokens. See Remote control. |
tool-firewall loads before engagement-governance in the engagement profile (enforced by
packages/core/profile-check.ts, which tests/docs-smoke.ts runs for the engagement profile), so the general gate runs first. Coding profiles carry no engagement gate;
the firewall runs there with the coding policy, and the engagement profile switches it to the
strict engagement policy (see Autonomy gate). The
firewall loads first in every profile and in every child, and pi hands it the very object that
will execute, after argument preparation and validation, with parallel calls executed only after
all are decided (tests/firewall-preauth-smoke.ts).
Tool identity policy precedes permission
Tool identities match exactly and case-sensitively. The pi 1.4.0 core tools are read,
bash, powershell, edit, write, grep, find and ls
(dist/core/tools/index.js in the installed pi package). Its bundled extensions also register
codemode and tool_search. Only these identities are implicitly known under the ask
default. Recognising an alias such as cat, view, read_file or apply_patch selects a
partial input adapter; it grants no authority. An exact policy entry or an operator decision
is still required (tests/firewall-shell-smoke.ts, tests/firewall-gate-smoke.ts).
A recognised adapter with missing required inputs, unknown fields or unsupported patch/multi-file
forms is high, needs the operator and cannot gain learned or model-similarity authority.
An exact allow cannot remove that finding or lower critical effects. The adapter covers legacy
single-file edits, pi 1.3's single-file batch replacements and the pinned readseek single-file
hashline operations; extra nested target fields remain incomplete. A null/undefined-valued
unknown key names no operation and does not make an adapter incomplete, while a known shape
field with null stays a type mismatch and a non-null unknown field stays incomplete
(tests/firewall-shell-smoke.ts, tests/firewall-gate-smoke.ts). Unattended runs refuse incomplete
inputs without asking or executing a marker (tests/firewall-unattended-smoke.ts).
codemode scripts require operator approval; they are opaque code, not shell text. tool_search
only discovers and activates tools. Calls carrying pi's parentToolCallId and <parent>/<n> id
are judged using their own identity and input. Parent approval or discovery grants no authority
to a child call (tests/firewall-gate-smoke.ts models these events; it does not run the real
codemode worker). The shipped policy explicitly allows reviewed kit bookkeeping, delegation and
companion read helpers; multi-target companion mutation/code-execution tools (ast_grep_replace,
lsp_navigation, pilens_lsp_navigation, rename) explicitly ask. Ordinary helper calls are pinned by
tests/tool-firewall-smoke.ts; policy decisions and critical-effect precedence by
tests/firewall-shell-smoke.ts.
An invalid policy file, malformed individual rule or unrecognised policy field invalidates the
whole policy: every call is denied until repair, including normally trusted core tools.
Warnings reach the UI and stderr, and the audit records policy problems. Stateful regex flags
g/y are instead removed with a warning while the rule remains enforced. The cache keys on a
SHA-256 content digest and path, so preserving the mtime cannot hide a revision. A pending
select, confirm, console or judge approval is re-evaluated under a changed policy before it can
allow the call or save an operator grant. These cases are pinned by
tests/firewall-policy-warnings-smoke.ts and tests/firewall-gate-smoke.ts.
MCP-only mode and PI_ALLOW_DIRECT_TOOLS
engagement-governance's MCP-only mode forces target-touching direct tools
(write, edit, bash) through the audited governance MCP path. It loads only in the engagement
profile, and even there it is not unconditionally on: by default it activates only once a real
engagement is configured (both engagement/scope.yaml and engagement/roe.yaml present and
complete). Set PI_ALLOW_DIRECT_TOOLS=1 to force-allow direct tools mid-engagement (operator
override, still audited), or =0 to force MCP-only lockdown without a configured engagement.
Luna's own first-party bookkeeping tools (todo, subagent, dual_review, the task_*,
record_verdict, verdict_status, memory_*, mem0_*, skill_* and branch_* tools, plus
workflow_status and the pause and stop actions of workflow_control) are exempt from MCP-only
mode: they do not touch an engagement target and are already gated by tool-firewall. The resume and
skip actions let a run go on, so they stay blocked.
Engagement commands
Two extensions register engagement commands. conductor registers /engagement, which manages the
engagement's lifecycle:
| Command | What it does |
|---|---|
/engagement start |
Starts the engagement at phase intake; refuses when one is already started. |
/engagement status |
Prints the lifecycle phase, when it started, the history length, the recursion budget and whether verification gates the next phase. |
/engagement phase <name> |
Moves the phase forward (never back) when verification allows it. |
/engagement status is the lifecycle; /engagement:status below is the governance gate's data root and
scope check. They report different things and neither replaces the other
(tests/conductor-engagement-smoke.ts pins /engagement).
engagement-governance registers three more operator commands, none of which takes arguments:
| Command | What it does |
|---|---|
/engagement:status |
Creates the data directories if they are missing, then prints the engagement data root (PENTEST_DATA_ROOT, default .pi/engagement in the working directory) and any scope or rules-of-engagement errors (scope_errors=none when both files are valid). |
/engagement:actions |
Prints the path of the audit log that records every action-card approval (<data root>/audit/audit.jsonl). |
/engagement:reload-policy |
Clears the cached policy metadata and scope and rules of engagement, so the next action reads engagement/scope.yaml, engagement/roe.yaml and the tool policy from disk again: an edited engagement takes effect without a restart. |
An engagement whose audit chain is still under the old .pi/pentest data root keeps using it (with a
notice at session start) until that directory is moved to .pi/engagement; both roots are protected paths
(tests/governance-smoke.ts). Nothing tests these three commands directly; the scope and rules-of-engagement checks they report
are pinned by tests/governance-smoke.ts.
What the boundary guarantees
- No silent allow-all. A fresh session loads the shipped starter policy
(
packages/extensions/src/tool-firewall/default-policy.json), whose unknown-tool default isask: nobody answering the bounded operator request means deny. See Tool identity policy precedes permission for the exact identity, adapter and approval rules. Fresh-session loading and no-marker-execution cases are pinned bytests/tool-firewall-smoke.ts,tests/firewall-gate-smoke.tsandtests/firewall-unattended-smoke.ts. - Destructive shell commands never run automatically. The shell parser classifies each
command by effect and target rather than by a regex over the text. Deleting
/,~or system roots,mkfs, writes to raw block devices, fork bombs, and secret egress (a credential read and a network send in one command) are critical and denied in every profile and mode. Deletions outside the workspace, force-pushes, history rewrites and persistence are high and need an operator. Obfuscation (r''m,r\m,$'\x72m', variable-built commands) is normalised before classification, and unparseable input is never auto-allowed. Authorisation precedes execution on every shell form tested, including wrappers such asxargs,sudo,env,find -execand command substitution (tests/firewall-noeffect-smoke.ts: the marker file is never created and the tool never runs before an answer). - Approvals are never broader than what you chose. An "allow" you give
is bound to the exact action, the workspace, the directory and the session, and expires
(24 hours for a session allow, 30 days for a learned one). Approvals are stored in one file,
<agent dir>/pi-kit/firewall-approvals.json(mode 0600), and/firewall listshows each with its scope, who granted it and how;/firewall revoke <id>,revoke session,revoke workspaceorrevoke allremoves them, effective from the next call. A malformed approvals file is ignored, never treated as an allow, and reported. A precedent learned in one workspace does not run unasked in another. The workspace is the nearest directory at or above the working directory that holds a.git. It is never your home directory,/, or a shared temp root such as/tmp, because a stray.gitthere would widen it to everything below (tests/workspace-root-smoke.ts). - Every refusal is labelled once, as
[HARD DENY],[UNCERTAIN ...],[OPERATOR DECISION: denied]or[AUTO-MODE BLOCK], in the text the agent sees, on the approval card and in the audit record. A hard deny cannot be overridden by an approval or the judge. - Auto mode cannot approve anything critical, or any new kind of high action, on a model's say-so. A high action runs without the operator only as an exact repeat of an approval you gave. A judge block whose confidence is not high goes to the operator rather than being final, and an unsure judge never becomes an allow.
- Nothing waits forever unattended. An approval card, the human console and the judge all
have timeouts (15 minutes, 15 minutes and 15 seconds by default); an unanswered wait ends as
UNCERTAINand nothing runs. While an overlay you opened (the hub or the workflow panel) is open, every prompt an agent can raise on its own waits for you to close it, with one notice: a firewall approval, session or brokered; an engagement action approval; anask_humanquestion; the trust prompts for project-local agents, specialists and project workflows; the resume prompt for interrupted writer steps; the reduced-sandbox prompt; the wake-chain question; and the question that resumes a paused workflow run. The wait and the card share one timeout, so an overlay left open ends the request as an unanswered card would, and a card shown after a wait gets only the time left, which pi uses to dismiss it. A brokered child request is deferred and keeps its console timeout, so it can expire behind the overlay and fail closed. The console itself holds input while a non-run card is open, so two child requests that arrive in one poll are shown one at a time: the sibling waits for the next poll. A workflow-run approval card does not take that hold, because the run broker deliberately allows two outstanding prompts per run; non-run approval cards and child requests still wait behind those open run cards. The resume question and an attendedask_humanquestion also wait for every open run card to close, within their own timeout: a run card still open at the deadline leaves the run paused, or the question timed out, and an aborted turn ends the wait. Anask_humanquestion then holds input while its own card is open. Aborting a turn ends that turn's wait, and an engagement action asks scope and RoE again after the wait and after your Yes. A reload or the end of a session drops the hold, because pi removes an overlay without settling it (tests/firewall-overlay-queue-smoke.ts,tests/firewall-workflow-approvals-smoke.ts,tests/governance-smoke.ts,tests/effort-standing-smoke.ts,tests/conductor-recursion-smoke.ts,tests/workflow-control-smoke.ts). Four kinds of prompt are not held, and no test pins that: the prompts of a command you typed, which you start from the editor rather than an overlay (/update,/profile,/effortand the like); the checks pi runs on your own/new,/resumeand/fork(uncommitted files, restoring a checkpoint);/remote pair, whose card follows the waiting dialog you opened and whose approval needs four typed characters; and the "tell the agent why" note, which follows a card you have just answered and approves nothing. - Every child agent is at least as protected as its parent.
delegation-guardstarts a child only with the protections the parent registered; inside the child it checks that they loaded and otherwise blocks every tool and exits with code 78. This applies to grandchildren and to every launch path (thesubagenttool, workflows, verification reviewers, validators, thedual_reviewtool and/review). Extensions are added to a child by kit name only, never by path, and a scan test fails when a launcher ofpichildren does not ask the guard (tests/delegation-guard-smoke.ts). - Unattended mode needs what the supervisor builds, and a contract an agent cannot fake. It
is active only when the process environment and a contract file say so and agree, and the
contract is not in the workspace, the working directory or the agent directory and sits on a
read-only mount (the runner mounts
/runread-only) or is owned by another user and unwritable by this process. A file the same user wrote and then made read-only is refused, root included. Any inconsistency means the normal rules apply. Starting a child with the variables from an agent's shell (an env prefix,export,env, or an interpreter's inline code that names them) is a safety-setting override: asked, and hard-denied inside a worker. A script the agent wrote earlier that sets them is not visible to the classifier; the provenance rule is what stops it. See Autonomous runs. Pinned bytests/firewall-unattended-smoke.ts. - Every firewall decision is audited to
.pi/tool-firewall-audit.jsonl(tier, effects, reason codes, redacted command, action hash, and the decider: analyser, policy, learned precedent, judge or human). Every tool call and output is also captured bytool-capture. The capture log holds exact values, secrets included, so it is private (0700and0600), write-protected against the agent, and reading it is a credential read for the firewall. secret-guard, when enabled, blocks the obvious secret paths. It blocks writing key material or tokens to any file, andcat,cp,mv,base64,curl -F @fileand PowerShell style reads of.env,*.pem,*.key,id_rsaand protected engagement paths, including glob-, bracket-class-, brace- and quote-obscured references (.en[v],[.]env,.e{n,x}v; pinned bytests/secret-guard-smoke.ts). In a plain leadingrgor grep-family command, it treats a recognised search pattern as text while still scanning pattern files and file operands; ambiguous options, substitutions, malformed quoting and an unquoted glob, brace or tilde pattern (which the shell expands) retain the full scan (tests/secret-guard-smoke.ts,tests/firewall-benign-corpus.ts). Source files below a directory whose name merely containssecret(such aspackages/extensions/src/secret-guard/) stay readable, while an exactsecret,secretsorcredentialspath segment still counts as a secret reference (tests/secret-guard-smoke.ts). The firewall separately classifies credential files as credential reads whether or notsecret-guardis loaded. For a tool the policy allows, it checks every path the call names in apath,file_path,filePath,file,files,paths,cwd,dir,directory,root,analysisRoot,newFilePath,scriptPathortrace_pathfield (tests/firewall-shell-smoke.ts);tests/firewall-path-fields-smoke.tsfails when a kit or pi tool declares a path-like parameter outside that list.- The project's
.picontrol directory needs an operator.<workspace>/.piand<cwd>/.pihold the audit trail, verdicts and auto-mode switch, so renaming, replacing, linking over or deleting the directory itself is a high safety-control change, and so is moving a directory that holds it (the workspace included) orrsync --remove-source-files(or its alias--remove-sent-files) from one. A source operand ofmvor of thosersyncoptions that is an unexpanded glob (*,?,[...]) counts when it could match the directory or one that holds it (mv .p* /tmp), following bash's default rule that*does not match a leading dot; a bracket expression with a POSIX class, collating symbol or equivalence class ([[:alpha:]]) is taken to match any one character. Brace expansion ({a,b},{x..y}) is applied tomv,cp,scpandrsyncoperands before they are classified (mv .pi{,.bak}moves.pi), and any other path that contains a brace group is a safety control when one of its expansions is; a word that would expand to more than 64 words is treated as a safety control. Quoting is not tracked here, so a quoted'{a,b}'is expanded too. The same goes for the files pi loads into the next session (.pi/settings.json,.pi/mcp.json,.pi/mcp-adapter.json(pi-mcp-adapter's project file),.pi/SYSTEM.md,.pi/APPEND_SYSTEM.mdand anything under.pi/extensions/,.pi/skills/,.pi/prompts/and.pi/themes/) and for.pi/GOAL.yaml, which the judge and the system prompt read as your goal.mkdir -p .pi, reading or copying the directory out, and other.pifiles stay ordinary work (tests/firewall-shell-smoke.ts).protected-pathsalso blocks tool writes to.pi/GOAL.yamloutright, while the/goalcommand still sets, shows and clears it, and to.pi/mcp-adapter.json(tests/protected-paths-smoke.ts,tests/protected-paths-corpus-smoke.ts). - What pi loads with no trust prompt, and the operator-authority files, need an operator.
Writing anything pi loads from the agent directory (extensions, skills, prompts, themes, the
installed
npm/andgit/packages,SYSTEM.md,APPEND_SYSTEM.md, the global context files,settings.json,trust.json),~/.agents/skills, a project's.agents/skills, or the kit's install marker.pi-kit.jsonis a high safety-control change, and so is agit cloneorgit worktree addinto one, or a git command that rewrites the working tree (pull,checkout,reset,merge, …) of a repository that is one, named bygit -Cor reached bycd(tests/firewall-autoload-smoke.tsreads pi's sources and fails on a location the firewall misses;tests/firewall-shell-smoke.tspins the git rows). The operator-authority files are one list in the classifier (OPERATOR_AUTHORITY_FILES): the web console token; the remote host'scontrol.json,identity.json,tls-key.pem,devices.jsonandaudit.jsonlinPI_REMOTE_STATE_DIRor<agent dir>/remote-control; pi'sauth.jsonandmodels.json; and the remembered approvals. Reading a secret one is a credential read and writing any is high; the same test checks each entry against the code that writes it and fails on an unclassified secret-looking file name in kit source. A path that reaches a secret without naming it exactly is classified as that secret: a glob that can expand to one or to a directory holding one (remote-control/*,auth.js*), and a directory that holds one (the state directory, the agent directory,~/.pi) when it is read recursively, archived, copied or given to a tool such asgrep(tests/firewall-autoload-smoke.ts). Inline interpreter code that names any credential or operator-authority path as a string literal is a credential read, whichever call reads it. A write to a path built at runtime whose literal tail names one of these files is high too, and so is a hard or symbolic link to one (ln,cp -l,cp -s, or a link call in inline code). Inline interpreter code (Python, Node, Deno, Bun, Ruby, PHP, Perl) that has a write-capable call (openwith a write mode,os.openwith write flags, pathlibwrite_text/write_bytes/open,shutilcopies and moves, Nodefswriters, copies and renames,Bun.write, Deno writers, RubyFile/FileUtils, Perlopenfor writing) and names one of these files is high (inline_control_write,tests/firewall-shell-smoke.ts) when the name is spelt in one of the forms the shared corpus tests: a literal path, a literal wrapped inexpanduser, or the home directory joined to literal segments in the common spellings the corpus lists (Path.home()/".pi/agent/…",os.path.join(os.environ["HOME"], ".pi", …),homedir() + "/.pi/…", a home-interpolated string, a relative literal afterchdir). Reading such a file the same way stays a read.protected-pathsblocks the same writes, including through~,$HOME,$PI_CODING_AGENT_DIR, a relative target aftercd, clone, pull and checkout targets,tar -C,unzip -dandrsyncdestinations, links, plain shell commands that create, empty, delete or re-permission a protected file (touch,truncate,rm,unlink,chmod,chown,chgrp) as well as redirection,teeandcp/mvdestinations, every file a patch applied withgit apply,git amorpatchnames (rename and copy lines included, at any strip level; a patch it cannot read is refused), and the literal and listed inline spellings above;tests/protected-paths-corpus-smoke.tsruns one corpus against both. On top of those spellings, both layers apply one coarse, fail-closed rule, kept as generated, byte-checked copies ofpackages/core/shared/inline-guard.ts. It applies when a command runs an interpreter on inline code. The interpreter families are Python, PyPy, Node and its TypeScript and loader aliases (tsx,ts-node,esno,esr,vite-node,babel-node,sucrase-node,jiti,iojs), Deno, Bun, Perl, Ruby, PHP, Lua, awk,osascript,pwsh,tclsh, R andRscript, Julia, Groovy,jshell, Swift, Kotlin, Scala, Elixir, Erlang (erl,escript), Racket, Guile and SBCL, with any version suffix. Inline code is any option before the script operand, a heredoc, piped or redirected input, no script file operand at all, or a Deno or Bun subcommand that runs code from the command line or stdin (deno eval,deno run -,bun eval,bun -e/-p). The interpreter is found behind leading assignments and the wrappersenv(includingenv -S),sudo,doas,nice,nohup,timeout,stdbuf,xargs,command,builtin,exec,time,ionice,chrt,setsid,taskset,busybox,npx,bunx,bun x,npm exec,pnpm exec/dlx,yarn dlx/exec,uvx,uv run,uv tool runandpipx run, skipping their option values, including a value taken by the last letter of a combined short-option cluster (sudo -u root,sudo -iu root,env -iu X,timeout 5). Redirect words (<file,<<WORD,<<<word,2>&1,>out, also written with no space after the command word, as inpython3<<<'…') are dropped before the command is resolved, and the reserved words and grouping{,},!,if,then,do,else,elif,while,untilandcoprocbefore the command word are skipped;|&is read as a pipe. A wrapper whose target is missing or not a literal name (sudo "$PY"), and a command word that is itself a variable, a substitution ($PY,"$PY",${PY},$(…), backticks) or a glob (pytho?,python[3]), count as inline code. The command lines ofsh,bash,zsh,dash,ksh,mksh,fish,ash,yashandbusybox sh(-c, or a here-string fed to the shell) and of theevalbuiltin are read the same way, up to four levels deep; deeper nesting counts as inline code. A shell left with no script operand once its redirects are dropped (or given-s) counts as inline code when it has piped input or any redirect, heredoc or here-string. The rule fires when, in addition, the command text mentions an agent-configuration segment (.pinext toagent,settings,extensions,auth,remote-control,devices,audit,mcp-adapter,.pi-kitorconsole;.pi-kit,mcp-adapterorPI_CODING_AGENT_DIRalone; or, without.pi, one of the tailsagent/settings.json,agent/extensions,remote-control/devices.json,remote-control/audit.jsonl,mcp-adapter.json,pi-kit.jsonorauth.json; all compared after quotes, whitespace, the concatenation operators between literals and, for the tails, path separators are removed), and the code has any write- or exec-capable call (an identifier containingwritesuch ascreateWriteStream, a copy,cpSync, move, rename, remove,rmdir,rmtree, link,mkfifo,mknod,utime,setxattr,makedirs, permission or ownership call,openwith a write mode, a print redirect,system/exec/spawn/popen/subprocess,shutil,FileUtils,fs.,Deno.,Bun., backticks). Then the firewall rates it at least high (inline_agent_config) andprotected-pathsblocks it, whichever of those spellings builds the path (tests/protected-paths-corpus-smoke.ts). Because that parser is a coarse tokenizer, a parse-free backstop also runs over the raw command line: when the whole command mentions an agent-configuration segment, has a write- or exec-capable word, and names any of the interpreters, shells or wrappers above (oreval) as a whole word, the same rating and block apply. The name may sit next to a shell metacharacter (python3<<<,{python3,|&bash), and it is also looked for with the glob characters[ ] ? *removed, with quotes and backslashes removed, and as any globbed word that could expand to one of the names (pytho?,/usr/bin/python[3]). The backstop over-blocks by design: any one command line that combines an interpreter name, agent-configuration text and a write word is blocked, even when the interpreter runs a script file (python3 scripts/write_settings.py ~/.pi/agent/settings.json) or the three only meet in a commit message; split such a command or reword the message. The corpus pins both over-blocks. The rule only ever raises a rating. It over-blocks by design: inline code that merely mentions agent configuration next to such a call is caught too; run it from a script file instead. Inline code with no write- or exec-capable call (reading a protected file) keeps the behaviour above. Its remaining limits are a path computed entirely at runtime with no distinctive segment or tail in the command text (character codes, decoded strings, a value read from a file or the environment other thanPI_CODING_AGENT_DIR), an interpreter or wrapper not listed above whose name never appears in the command text, and code run from a script file, which neither layer reads (see "Inline interpreter code" under What the boundary does NOT guarantee). A path built at runtime whose tail is a single segment ($OUT/settings.json,os.path.join(d, "devices.json")) is not resolved by either, nor is a path assembled from computed pieces with no literal naming the file (character codes, decoded strings), andprotected-pathsreads shell text with patterns rather than a parser, so it does not follow acdinside a subshell or a function. A content read, archive or copy of the home directory itself, or of a directory above it (grep -r … ~,tar czf … ~), is a credential read too; listing it (ls,du) is not (tests/firewall-shell-smoke.ts).
What the boundary does NOT guarantee
- It is not a sandbox. A tool call that is allowed runs with the agent's full operating system privileges. The firewall decides whether a tool runs, not what it can reach once running. For containment use the autonomous runner's container or your own.
- Inline interpreter code is matched coarsely, not understood. The firewall and
protected-pathsrecognise a protected path inpython -c,node -eand similar one-liners in the literal and common home-relative spellings thattests/protected-paths-corpus-smoke.tstests, and both fail closed on inline code that mentions an agent-configuration segment next to any write- or exec-capable call (item 12). A path computed entirely at runtime with no distinctive segment in the command text (character codes, decoded strings, a value read from a file), and code run from a script file, are not recognised, and a write to a control file made that way can be rated low or medium and not blocked. The agent's normal approval prompts and the sandbox and container profiles remain the boundary there. - Content detection is heuristic. A novel secret format, a secret split across writes, or one
encrypted or obfuscated before writing can evade
secret-guard. Treat it as defence in depth. - Command classification is static. The parser sees the command text, not what a script
does at run time:
./build.shorpython tool.pyis judged by name and context. A wrapper script the agent wrote earlier can hide an effect. Session history (download then execute, secret then send) and the headless fail-closed behaviour are the backstop. - An approval binds the command as written, in one workspace, directory and session, not what it
will do.
git push origin mainapproved once runs again unasked in the same place even iforiginnow points somewhere else, and an approved script runs again after it has been edited. Approvals expire (24 hours for a session allow, 30 days for a learned one) and/firewall revokewithdraws them, but the next repeat is judged by its text. - The approvals file and the effort ledger are files. Writes to the approvals file hold a lock and fail (nothing is remembered, a revoke says nothing changed) rather than go ahead without it; both locks recover from a crashed holder. A process running as your user can still edit either file; the firewall protects them from the agent's tools, not from you or from another process.
- Low-tier actions run unasked in every mode. That includes reads through exact built-in
adapters, explicitly allowed external APIs and plain shell network GETs.
/firewall statusprints this. An exact policy allow is an operator trust decision about a tool's implementation; the firewall cannot authenticate a plugin or prove that its implementation matches its name. Exact names do not bind code: replacement code registeringread, or any explicitly allowed name, inherits that identity's policy. In-process extension code can also perform I/O directly, outside tool-call interception. Plugins themselves are not isolated; no test establishes an implementation-binding or in-process isolation boundary. - It does not police network egress by itself. A network send is medium (judged in auto mode, asked in manual) and becomes high or critical after a secret read. Destination allow-listing is the engagement governance layer's job (scope and rules of engagement), and in unattended runs the container's network is the stop, because package-manager and opaque-tool traffic cannot be attributed to a host.
- Luna's own sources are ordinary files in a kit checkout. When the workspace is a source
checkout of Luna (for example the one a live install was made from), an agent edit to
packages/extensions/src/tool-firewall/,packages/extensions/third_party/protected-paths/orpackages/extensions/src/secret-guard/is classed like any other source edit (low); onlytool-firewall/default-policy.jsonis a safety control among them (tests/firewall-shell-smoke.ts). If pi loads the extensions from that checkout, review such diffs before the next session. - Companion tools outside Luna's classification. A pi package that registers its own shell
or edit tools (for example the optional
pi-lean-ctx) needs an exact policy entry or operator approval. Shell-looking fields are also analysed, but cannot authorise an unknown tool's other effects.secret-guardmatches the built-in tool names. An explicitly allowed external tool withrisk_class: "network_read"uses the URL/egress adapter and marks its result untrusted; other external API semantics remain the operator's responsibility. Withdefaults.unknown: "deny", every tool needs an explicit policy entry, including built-in adapters. These cases are pinned bytests/firewall-shell-smoke.ts,tests/tool-firewall-smoke.ts,tests/firewall-gate-smoke.tsandtests/firewall-unattended-smoke.ts. - Effort is not a boundary. It budgets delegation and shapes behaviour; the ledger and its environment are owned by your user. A hostile process could edit them. See Effort.
- Unattended mode trusts the supervisor's claim of a boundary. The firewall checks the
environment, the contract and where it lives (a read-only mount, or another user's file), and
counts either proof only from the initial user namespace, so namespaces a user can create
without root prove nothing (
tests/firewall-unattended-smoke.ts). It cannot verify that the container the supervisor describes exists. Someone who can run code inside the pi process, or root on the host, can still present a contract. The container, not this check, is the boundary. - For an untrusted repository, use the strict security level or a container. The classifier is static, and an injected agent that is determined to find an unmodelled construct is the case Autonomy gate lists as not covered.
- A custom policy can widen the boundary.
PI_KIT_FIREWALL_POLICYpointing at a permissive file (for example{ "defaults": { "unknown": "allow" } }) re-opens the gate.verify.tsonly guarantees the shipped policy is default-deny. Such overrides, andPI_KIT_UNATTENDED*, are safety-setting overrides. - Interactive approval is only as careful as the person answering it. Cards show the action, its tier and the reasons; a remembered approval is scoped, but you still decide.
Workspace file writes
A cloned repository is untrusted content, and git stores symbolic links, so any path Luna
writes under a workspace (<workspace>/.pi/..., AGENTS.md, TODO.md) may be a committed link to
a file elsewhere. Luna's own state writes go through one helper, packages/core/shared/safe-fs.ts,
copied into each extension that writes (npm run gen:shared; npm run verify fails when a copy
differs). For a write under the workspace it:
- refuses a target outside the workspace root (a
path.relativecheck, not a string prefix), and checks every directory from the root down withlstat, refusing a symbolic link or a non-directory and creating a missing one with mode 0700; - opens the file itself with
O_NOFOLLOWand requires a regular file owned by the current user with a single hard link; - replaces a whole file through a new temporary file created exclusively (
O_EXCL) beside it and renamed over it, keeping the old file's mode, and creates new files with mode 0600.
The writers that use it include the trace ledger, the firewall audit log, /auto, goal-core,
task-graph, verifier-board and verify-gate, recovery-orchestrator, self-improvement's AGENTS.md edits,
/save, todo, the conductor, context-sieve, the workflow run files and the caveman and plan-mode
contributions. tests/workspace-symlink-smoke.ts plants a link at each state file, and .pi as a
link to a directory, drives those writers through their real entry points, and checks that nothing
outside the workspace changed; it also checks the helper's refusals and modes directly. ESLint
(eslint.config.ts) rejects a raw writeFileSync, appendFileSync, createWriteStream or
write-mode openSync in an extension unless the file is on a reviewed allowlist with its reason.
The engagement governance extension also files human-console approval requests through the helper;
tests/governance-smoke.ts checks that a linked console directory cannot redirect a request and
that a signed answer still approves a request filed inside the workspace. Its data directories and
audit ledger are bounded by the data root: an operator-set PENTEST_DATA_ROOT is trusted as given
(it may itself be a link the operator made), but a link below it is refused, as is one below the
default .pi/engagement (tests/governance-smoke.ts). An operator-set PI_KIT_HUMAN_CONSOLE_DIR is
trusted as given in the same way, and nothing pins what happens when it is itself a committed link
(see Future work).
Profile restores (/profile rollback and the installer's --settings-only rollback) write
through an exclusive temporary file created 0600 before it is given the snapshot's mode, so a
restored .env is never world-readable, even briefly (tests/profile-transaction-smoke.ts).
branch-lab keeps its worktrees under a per-user <temp>/pi-kit-<uid> directory (mode 0700, owned by
you; a link or another user's directory there is refused) (tests/branch-lab-smoke.ts). The
autonomy gate copies its held-out overlay over the worker's clone without following a link the
worker committed, and refuses a check whose working directory passes through one
(tests/autonomy-gate-overlay-smoke.ts).
Not covered:
- A local process that races the checks (between the
lstatof a directory and the open below it) can still redirect a write. The threat addressed is content committed to a repository, which cannot race. - On Windows
O_NOFOLLOWand the owner check do not exist; thelstatchecks still run. - A path the operator sets (for example
PI_KIT_FIREWALL_AUDIT_LOGorPI_KIT_BRANCH_LEASES_FILE) is trusted: only its final name is checked.
The Luna installer and install markers
/profile and the first-run auto-profile run Luna's installer
(node <kit root>/packages/core/install.ts). A project install keeps its marker in
.pi/.pi-kit.json, which a cloned repository can commit, so the marker never chooses where that
installer comes from. The kit root is PI_KIT_ROOT when set, otherwise the marker's kitSource
only when it is an absolute path that resolves, through any symbolic links, outside the workspace
(the enclosing git work tree, else the session directory) and whose package.json names the kit;
otherwise it is the package the extension was loaded from. A path kitSource that fails a check
is ignored with a warning, once per session, and the installed kit is used. The marker's other
fields (profile, scope, mode, channel) are still read as data. tests/kit-root-trust-smoke.ts
plants a complete kit inside a fixture repository and points a committed marker at it by a
relative path, an absolute path, from a subdirectory of the work tree and through a link from
outside, and checks that neither the auto-profile nor /profile hands the repository's installer
to pi.exec, and that the installed kit and an absolute checkout outside the workspace still
resolve.
/console (web-console) and the remote-control host start make the same choice for the web UI
server they spawn (<kit>/packages/web-ui/server/server.ts and remote-host.ts) when no web UI
sits beside the extension, and apply the same check: one helper, packages/core/shared/kit-source.ts,
copied into each of the three extensions (npm run gen:shared). A refused kitSource is reported
and the command says it could not find the web UI instead of running the repository's server. The
same smoke loads detached copies of both modules against the same fixtures.
Not covered: PI_KIT_ROOT is an operator setting and is trusted as given. The package name is a
consistency check, not an integrity check: an absolute directory outside the workspace that the
operator's own marker names is trusted.
Redaction
Text Luna stores or sends to a memory service passes through one secret-redaction table,
packages/core/shared/redact.ts, copied byte for byte into each consumer: the memory vault,
/save snapshots, the firewall's feedback records, autonomy notebooks, workflow run files (on top
of their own rules), role-runner telemetry and memories sent to mem0. It replaces private keys,
authorisation headers and bearer tokens, credentials in URLs, common provider token shapes, and
KEY=value, "key": "value", --password value, mysql -p… and curl -u user:… values with
[REDACTED], keeping the key name or header.
tests/redaction-corpus-smoke.ts runs the source, every copy and every consumer over the synthetic
corpus in tests/fixtures/secret-corpus.json and fails on any value left in the output; it also
checks that text without a secret is unchanged, that a second pass changes nothing, and that
adversarial inputs at 4x the size grow sub-quadratically (so host load cannot turn the check red).
Every rule is bounded, and an unterminated
private key is redacted to the end of the text rather than re-scanned.
Redaction is best-effort hygiene, not a detection boundary: a secret in a shape the table does not know, or split across records, is kept as written. Treat stored logs as sensitive regardless.
Untrusted regular expressions
A project skill's re: trigger and a workflow step's output pattern come from the opened
repository. Both are compiled only when packages/core/shared/safe-regex.ts accepts them (no
quantified group that holds a quantifier or an alternation, no backreference, a length and choice
cap); a refused gate pattern fails its gate (tests/workflow-smoke.ts). A skill trigger is also
tested under a 50 ms CPU-time budget, and one that exceeds it is switched off for the rest of the
pi process (tests/skill-routing-smoke.ts). The wall-clock cap that interrupts a runaway match sits
well above the budget (and a descheduled fast regex gets one retry), so a busy host does not switch
off a trigger that used little CPU. ESLint rejects a new RegExp built
from a non-literal pattern outside a reviewed allowlist. The syntactic check does not catch every
slow pattern (adjacent overlapping runs are polynomial); the time limit is what stops those for
skill triggers.
Decisions and their compensating controls
Some behaviour is an operator decision rather than a default Luna would otherwise choose. Each is recorded with its risk and the controls that compensate for it.
| Decision | Risk | Compensating controls | Record |
|---|---|---|---|
| SEC-5: approval prompts are Yes-first. The firewall's approval card lists Allow once first, and the phone-pairing prompt lists Approve first | A reflexive Enter approves | Pairing: the typed device-ID suffix, the second-claim refusal, the out-of-range address warning, the terminal check on who decides, suspension of unaudited devices. Cards: the tier, reasons and history on every card, headless asks resolving to deny, and every phone answer audited with its device and tier | Remote control |
| The remote host listens on every interface by default | Anyone who can reach the port can try to link or sign in | One-time codes with a try limit, rate limits and lockout, a warning at start, recommended tailscale or loopback binds |
Remote control |
The default firewall audit log stays in the workspace (.pi/tool-firewall-audit.jsonl) |
A repository could commit a link there | It is written no-follow through the safe-write helper, like every workspace state file (Workspace file writes) | Autonomy gate |
Overriding and tightening
PI_KIT_FIREWALL_POLICY=/path/to/policy.jsonreplaces the shipped policy./profile engagementorPI_KIT_FIREWALL_PROFILE=engagementselects the strict policy. Profiles set the firewall mode and policy only; they never turn on unattended mode./auto offorPI_KIT_AUTO_MODE=0asks for every medium and high action;/auto learn offstops applying learned precedents./firewall statusshows the policy, mode, judge, rule counts and session state;/firewall listand/firewall revokemanage approvals;/firewall reloadre-reads the policy file.- Tighten by adding
command_rules.denyentries, or settingtools.<name>.decisiontodeny.
Tests that pin this
npm run test:security runs the firewall, shell parser, approvals, outcomes, no-side-effect,
pre-authorisation, unattended-mode, protections-registry, delegation-guard, web-console and
remote-control suites, plus secret-guard. verify.ts fails the build if the shipped policy stops being default-deny or
its destructive patterns stop being a superset of engagement-governance's. As with any
pattern-based boundary, this is the current state of an ongoing effort, not a permanent guarantee.