# Threat model
What `apexe` stops, how it stops it, and — the longer half of this document —
what it does not stop.
Read this before you rely on it for anything. A governance tool that overstates
its reach is worse than none, because it moves work from "I am careful here" to
"the tool handles it".
---
## 1. Position
`apexe` is **not a sandbox.** It does not isolate the filesystem, restrict
network access, drop capabilities, or filter syscalls. A wrapped tool that is
permitted to run, runs with the full privileges of the `apexe` process.
`apexe` is an **execution boundary**: a place where a call must present a
declared contract before the subprocess is spawned, and where the decision to
permit or refuse it is recorded.
The two are complementary and you should want both. The recommended deployment
is `apexe` **inside** a sandbox (`sandbox-runtime`, `bubblewrap`, a container):
the sandbox bounds what any escape can reach, `apexe` decides what should be
attempted and leaves the evidence. Neither substitutes for the other — a sandbox
cannot tell an authorised deletion from a catastrophic one, and an execution
boundary cannot contain a process that has already been permitted to run.
---
## 2. The problem being addressed
An agent asked to do ordinary work reaches for ordinary tools. The failure mode
that has been repeatedly documented in the field is not exotic: the agent takes
an irreversible action it was instructed not to take.
The instructive detail from the PocketOS incident (April 2026) is the
post-mortem finding that the agent acknowledged violating the destructive-command
rule in its own system prompt.
That generalises to a design premise:
> A constraint expressed in an instruction is a **request**. Only a constraint
> enforced at the point of execution is a **fact**.
Everything below follows from taking that literally.
---
## 3. Why command-string matching is the wrong enforcement layer
The common enforcement design is a pattern list over command strings: allow
`git status`, deny `rm -rf`. It fails as a category, not as an implementation,
because the set of strings that produce a given effect is open.
Four shapes of this have been reported publicly against various agent hosts. They
are listed as *classes of problem inherent to string matching*, not as defects of
any particular product — every one of them was fixed or mitigated where reported:
| **Compound commands** | The matcher evaluates the first token; `a && b` presents `a` and runs both ([claude-code#36637](https://github.com/anthropics/claude-code/issues/36637)) |
| **Delegation** | A sub-agent or channel-served session is spawned on a path that skips the policy filter ([claude-code#40343](https://github.com/anthropics/claude-code/issues/40343), [zeroclaw#7063](https://github.com/zeroclaw-labs/zeroclaw/issues/7063)) |
| **Path aliasing** | `/proc/self/root/usr/bin/npx` resolves to the same binary and matches no deny pattern |
| **Approval fatigue** | Hundreds of prompts per session make review nominal, and the documented response is to disable prompting entirely |
The first three share a root cause: the policy is written against a *rendering*
of the intent rather than the intent. The fourth is a UX consequence of the same
thing — when a rule cannot distinguish `git status` from `rm -rf /`, it must ask
about both.
`apexe`'s response is to never be in that position: **it does not parse a command
line.** There is no string for a caller to vary.
---
## 4. What apexe actually enforces
Each row is implemented and test-covered. Source locations are given so the claim
can be checked rather than believed.
### 4.1 No shell on the execution path
`src/module/executor.rs` builds a `tokio::process::Command` and passes argv
straight to `execve`. No shell is spawned anywhere on the execution path. The
single `sh`/`zsh` invocation in the crate lives in `scanner::completion` and runs
a hardcoded constant script with no interpolation.
The consequence is structural: `;`, `|`, `&`, `$`, backtick and quotes are
ordinary bytes in an argument. They cannot start a command, open a pipe, or
expand a variable, because nothing is there to interpret them. Compound-command
injection is not mitigated — **it has no mechanism to exist**.
This is why `apexe` deliberately does *not* reject shell metacharacters in
argument values: doing so bought no safety and broke real use (`curl` could not
send a JSON body, no `jq` filter containing `|` could be passed). See the
`CONTROL_CHARS` documentation in `executor.rs` for the full reasoning, and
`test_build_arguments_allows_shell_metacharacters` for the guarantee.
### 4.2 The injection that does exist on an execve path
A value that reaches argv is read *positionally* by the wrapped tool's own
parser. A value of `--output=/etc/passwd` is indistinguishable from an option the
caller was never granted. This — not shell metacharacters — is the real injection
on this path.
`validate_argument_value` therefore rejects any value starting with `-`.
Two documented exemptions, both narrow:
- **`numeric`** — a value that arrived as a JSON *number*, so legitimate negative
numbers work. A *string* `"-1"` is still rejected.
- **`separator_available`** — set only for a tool whose overlay states it honours
the `--` end-of-options separator. After `--` the wrapped parser *cannot* read
the value as an option, which is a stronger guarantee than refusing values that
merely look like one.
### 4.3 Control characters that would corrupt the audit trail
`\0`, `\n`, `\r`, U+2028, U+2029 and U+0085 are rejected in any value. The
argument is log integrity, not execve safety: a caller who can plant one of these
decides where a log reader sees a line boundary. Tab, VT, FF and ESC are
deliberately *not* rejected — they are already neutralised on output by `tracing`'s
`Debug` rendering, and rejecting them would cost real values.
### 4.4 Fail-closed ACL — when one is loaded
`apexe scan` writes `~/.apexe/acl.yaml` with `default_effect: "deny"`. Modules
annotated `readonly` get an explicit allow rule; modules annotated `destructive`
get an explicit deny rule. Everything else — including everything the scanner
could not classify — falls through to deny.
The direction of that failure mode matters: an unclassified command is
**refused**, not permitted. See §5.2 for the case where it does not hold.
**"Fail-closed" describes the loaded policy, not apexe's default state.**
`install_acl` returns early when no `--acl` path is given, so a server started
without the flag enforces no access control at all. What *is* fail-closed about
the flag itself: passing `--acl` with a path that does not exist refuses to
start rather than continuing unguarded. See §5.3.
### 4.5 Environment scrubbing
Every subprocess runs with `env_clear()` and a base allowlist plus `LC_*` locale
variables. Secrets in the parent environment do not reach wrapped tools.
### 4.6 Resource bounds
Output is capped at 64 MiB per stream (`DEFAULT_MAX_OUTPUT_BYTES`). A timeout is
enforced with `kill_on_drop(true)`, so an expired timeout actually kills the
child rather than merely returning an error to the caller — covered by
`test_execute_subprocess_kills_the_child_when_the_timeout_elapses`.
### 4.7 Audit trail
`audit.jsonl` (mode `0600`) records executions, refusals, **and** ACL allow/deny
decisions, each carrying `caller_id` (the authenticated principal) and `trace_id`
in one timestamp format, so an allow-decision can be joined to the execution it
permitted.
It deliberately holds **no argument values**, hashed or otherwise. See §5.5 for
what that costs.
### 4.8 Path guard on path-valued arguments
`--acl` decides *whether a module may be called*. It cannot decide *what a call
may touch*: apcore's ACL matches on `callers` and `targets` (module ids), and
its condition keys — `identity_types`, `roles`, `max_call_depth`, `$or`, `$not`
— are all facts about the principal, never about an argument. So an ACL can say
"`cli.rm` is allowed" or "`cli.rm` is denied", and nothing in between.
The realistic policy is in between. `rm` is not a command to forbid outright;
`rm /etc` is a command to forbid. `src/governance/path_guard.rs` closes that
gap: every argument the input schema types as a filesystem path
(`x-apexe-path`, emitted by the schema builder for `ValueType::Path`) is
resolved and checked before it becomes argv.
**Two baselines, because reading and writing are different risks.** A single
list forced one answer onto two unrelated questions and got both wrong:
`cat /etc/hosts` was refused, which buys nothing — the file is world-readable
and the agent's own file-reading tool reaches it anyway (§5.7) — while
`cat ~/.ssh/id_rsa` and `rm -rf /etc` were refused for the same stated reason
despite being nothing alike. The split follows the risk:
| Module annotated `readonly` | allowed | **refused** |
| Everything else | **refused** | **refused** |
- **System paths** — `/bin`, `/boot`, `/dev`, `/etc`, `/lib`, `/lib32`,
`/lib64`, `/proc`, `/run`, `/sbin`, `/sys`, `/usr`, `/var`, plus `/System`,
`/Library`, `/Applications`, `/private/etc`, `/private/var` on macOS.
Destruction is the risk here; legibility is not, and refusing `ls /usr/bin`
bought friction rather than safety.
- **Credential paths** — `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.docker`
and `~/.apexe` under the invoking user's home, plus the token stores that do
not sit at the top level: `~/.config/gh`, `~/.config/gcloud`,
`~/.config/apcore`, `~/.git-credentials` and `~/.netrc`. All are refused to
readers and writers alike. `~/.config/apcore` is listed ahead of anything
writing there: it is the normative location for the OAuth tokens
apcore-toolkit's device-authorization flow persists, and a baseline entry for
a path nothing has created yet costs nothing, while adding it afterwards
leaves a window in which apexe wraps tools able to read a credential apexe
does not know exists. Deleting a private key announces itself the next time the key is used;
copying one into a model context leaves no trace at all, so the stricter
treatment goes to the risk that is harder to notice. `~/.apexe` is on this
list rather than the other because it holds the ACL and the audit trail
governing the very call being made — a wrapped tool that can read the policy
can plan around it.
The mode comes from the module's `readonly` annotation, and an unannotated
module is treated as a writer. That inherits §5.2's caveat: a **false
readonly** — a command whose name matches a readonly pattern but which
writes — gets the weaker of the two treatments here as well as an explicit
allow rule in the ACL. Both point at the same remedy, which is to correct the
classification with an overlay.
`config.yaml`'s `additional_denied_paths` appends to the **credential** list,
so a configured path binds readers too: an operator naming a path explicitly is
asserting it is sensitive, and the stronger of the two readings is the one that
cannot be wrong in the dangerous direction.
`allowed_paths` is the one setting that goes the other way, and it is **empty
unless an operator writes it**. It exists because the alternative was worse:
an agent that legitimately has to write `/etc/nginx/conf.d` otherwise had to be
handed that tooling outside apexe altogether, which drops the audit trail and
the ACL along with the path check — §5.1 in miniature, reached by way of a
control that was too rigid to use. A narrow declared carve-out keeps the call
inside the governed path.
Nothing validates that a carve-out is *wise*. Naming `/etc`, or a credential
directory, is honoured — overruling an explicit instruction would put the guard
in the business of second-guessing the person who deployed it, and an operator
staring at a config file that appears to do nothing is its own failure mode.
What the guard does instead is refuse to be quiet: every carve-out is logged at
startup, and one that opens a whole system location or exposes credentials is
logged at `warn`. **Two properties are worth stating plainly**: a carve-out
grants everything beneath it, and a carve-out over a service's configuration
directory grants that service's behaviour — write access to
`/etc/nginx/conf.d` is enough to add a `proxy_pass` and redirect traffic,
without touching anything else under `/etc`.
Carve-outs and denials share one specificity ladder, so a subtree can be opened
and part of it fenced off again. An exact tie is broken by whose carve-out it
is: a configured `allowed_paths` entry wins, because it is an instruction; the
derived temp-directory exemption loses, because nobody asked for it and an
exact overlap there is a coincidence — which is what stops a `TMPDIR` pointed
at `~/.ssh` from reading a key out.
**Comparison happens on the resolved path, never the supplied string.** Three
transformations sit between what a caller sends and what the kernel acts on,
and skipping any one makes the guard decorative:
1. **Relative paths** are joined to the guard's root — which is also what
`Command::current_dir` is set to, so the guard and the child cannot disagree
about where `../../etc/passwd` lands. Before this, the child inherited
apexe's own working directory, and the meaning of every relative argument
depended on where the operator happened to launch `apexe serve` from.
2. **Symlinks** are followed. `/tmp/x -> /etc` makes `rm -rf /tmp/x/` a request
to delete `/etc`, and no string comparison on `/tmp/x` sees it. The longest
existing prefix is canonicalized, so a destination that does not exist yet
(a `mkdir -p` target, a `cp` destination) is still judged.
3. **`..` components** are folded — but only across the non-existent tail, and
only *after* the symlinks ahead of them are resolved. `std::path::absolute`
preserves `..` because POSIX requires it, and collapsing it lexically first
is wrong: `/tmp/link/..` is the parent of link's target, not `/tmp`.
**A guarded location that is itself a symlink is held in both spellings.** The
resolution above is deliberately partial — only the part of a path that exists
gets canonicalized — so the same location can reach the comparison spelled two
ways. On macOS `/etc` and `/var` are links into `/private`, and a baseline
canonicalized once would contain only `/private/etc`; a `..` climb through a
directory that does not exist folds lexically and arrives as the literal
`/etc/passwd`, which matches neither. Every denied entry — the compiled-in
baselines and `additional_denied_paths` alike — therefore stores its literal and
its canonical form. Carve-outs (`allowed_paths`) deliberately do not: a second
spelling can only match more paths, which is the right direction for a refusal
and the wrong one for an exemption.
**The check runs in both directions, and only one of them binds a reader.**
*Containment* — the path sits inside a protected location, `/etc/passwd` under
`/etc` — applies to both modes, and is what refuses `cat ~/.ssh/id_rsa`.
*Ancestry* — the path sits above one — applies to writers only, because it
exists for the recursive operation that takes the protected directory with it:
`rm -rf /` never names `/etc` and destroys it regardless. Holding a reader to
it would refuse `ls ~` and `ls /` on the grounds that a home directory contains
`.ssh`, which is most of what a reader legitimately does; the resulting gap is
§5.8's third bullet. Matching is by whole path component either way, so
`/etcetera` does not collide with `/etc`.
**One carve-out exists, and it is compiled in.** On macOS the per-user
temporary directory *is* `/var/folders/<x>/<y>/T`, so guarding `/var` would
otherwise refuse every use of the directory whose purpose is being written to.
`config.yaml` cannot extend the carve-out list, and a `TMPDIR` that equals or
contains a *system* location is discarded rather than honoured. The credential
list is deliberately not weighed there: a home directory under `$TMPDIR` is
ordinary in a sandbox, and counting it would void the carve-out and re-arm
`/var` across the whole temp directory. Specificity already refuses a
credential path nested inside a carve-out. Where a denied
entry and the carve-out both cover a path, the more specific one decides; a tie
is a refusal.
A refusal is `ACL_DENIED`, carrying the requested path, the resolved path and
the protected location that matched. The resolved path is in the message
because the requested one frequently does not look protected — that is the
whole point of resolving — and a caller told only "denied" cannot tell a
mistake from a misconfiguration. Being a governance code rather than an input
code also keeps it out of circuit-breaker health (`breaker.rs` excludes
governance refusals), so a caller repeatedly probing `/etc` cannot open a
circuit and deny `cli.rm` to everyone else.
Unlike `--acl` and `--enable-approval`, this is **on by default and has no
off switch** (§5.3 does not apply to it).
**The boundary is inspectable without running a server.** `apexe policy` prints
the guard as installed — both compiled-in baselines, whatever
`additional_denied_paths` added, the `allowed_paths` carve-outs, and the derived
temp-directory exemption — read off the live guard rather than re-derived from
`config.yaml`, so it cannot describe a policy other than the one in force.
`apexe policy --path <p> --mode read|write` calls the guard's own `check`, the
same call a wrapped tool's argument goes through:
```bash
apexe policy # the whole boundary
apexe policy --path /etc/passwd # refused to a writer
apexe policy --path /etc/passwd --mode read # allowed to a readonly module
apexe policy --path ~/.ssh/id_rsa --mode read # refused: credentials bind readers
```
This matters for review rather than enforcement: §5.2's remedy is "check the
classification", and until now checking what a given module could actually reach
meant standing up `apexe serve` and driving it with an MCP client.
### 4.9 Flag-level risk, for the two things a scan cannot infer
Help text does not distinguish `git --exec-path=<path>`, which sets a search
path, from `git --upload-pack=<cmd>`, which runs one. Both read as "takes a
value" to every parser apexe has, so guessing would produce exactly the
plausible-but-wrong assertion this project exists to avoid. A curated overlay
states it instead, and the field defaults to absent.
| `escalates` | The call goes to the approval gate — **only when the flag is actually sent** (§5.2's approval-fatigue argument: marking the *command* would prompt on every `git push`) | `x-apexe-escalates: true` |
| `executes` | The call is **refused** with `ACL_DENIED`, before anything spawns | `x-apexe-exec: true` |
| `benign` | Suppresses the name-list escalation for this one flag (`bsdtar -y` is bzip2, not "assume yes") | `x-apexe-escalates: false` |
`executes` is a different claim from `escalates`, not a louder one. §4.1's
guarantee is that argv reaches `execve` with no shell on the path; a flag whose
value *becomes* a command hands that guarantee straight back, and no JSON Schema
constrains what the string becomes. It is refused rather than gated because an
approval prompt would ask a human to predict what an arbitrary string will do —
the judgement least likely to be made correctly under a stream of prompts, which
is the same reasoning §5.9 applies to the exec wrappers. There is no
per-parameter carve-out: an operator who needs one runs the tool outside apexe,
which is at least a visible decision.
Enforced in `executor::reject_exec_parameters`, which checks *effective* values
only — `{"upload_pack": false}` renders no flag, so it is not sending one.
Escalation is enforced in `ApprovalGate`, which reads the properties recorded at
scan time against the arguments a call carries.
**This is a floor and it is small.** `executes` is set today on the flags a
human has checked, not on every flag that has the property. An unmarked flag of
this class in an un-overlaid tool is not caught — `docs/overlays.md` lists the
known members and requires verification against a real installation before
asserting one.
---
## 5. What apexe does not stop
This section is the reason the document exists.
### 5.1 An agent that has a shell does not need apexe
`apexe` governs the tools it exposes. If the same agent host also offers a
general `Bash`/`Shell`/`Terminal` tool, the agent can bypass every control here
by simply not using the governed path.
**`apexe` raises the floor only if the ungoverned floor is removed.** Wrapping
`git` while leaving a shell tool enabled buys you an audit trail of the calls the
agent chose to make politely. Deploy it together with host-level restriction of
raw shell access, or inside a sandbox where raw execution is unavailable.
This is the single most important limitation on this page.
### 5.2 Annotations are name-based heuristics, and can be wrong
`src/adapter/annotations.rs` classifies commands by matching their names against
fixed pattern lists (`READONLY_PATTERNS`, `DESTRUCTIVE_PATTERNS`), with flag
escalation (`APPROVAL_FLAGS`: `--force`, `-f`, `--hard`, `--recursive`, …).
The two error directions are not symmetric:
- **Missed destructive** (a destructive command whose name matches nothing) →
falls through to `default_effect: deny`. Safe direction.
- **False readonly** (a command whose name matches a readonly pattern but which
has side effects) → gets an **explicit allow rule**. **Unsafe direction.**
Concrete example: `find` matches `READONLY_PATTERNS`, but `find … -delete` is
destructive. Any tool whose subcommand name understates its effect is in this
class. (The shipped `find` overlay corrects it to `destructive: true`, which is
what overlays are for.) The sharpest instance is §5.9: `env` matched the same
list while being a general-purpose command executor.
The classification also feeds §4.8. A false readonly gets the *weaker* of the
path guard's two treatments as well as an ACL allow, so one wrong annotation
now moves two boundaries.
**Review the generated ACL before serving it.** It is a starting point produced
by a heuristic, not a policy you have approved. Use overlays to correct
classifications for tools you rely on.
### 5.3 Access control and approval are both opt-in
Neither `--acl` nor `--enable-approval` is on by default. A bare `apexe serve`
gives you the contract (schema validation), the isolation (§4.1, §4.2, §4.5,
§4.6) and the audit trail — and **no policy**: every registered module is
callable by every caller.
This is the gap most likely to produce a false sense of safety, because the scan
*does* generate a deny-by-default ACL and then does not apply it for you. Wire
both flags in explicitly:
```bash
apexe serve --acl ~/.apexe/acl.yaml --enable-approval
```
### 5.3.1 The approval gate additionally needs client support
Without `--enable-approval`, `requires_approval` annotations are recorded but
never enforced by a human decision.
With it, the prompt is delivered as an MCP **elicitation**, so a client that
declared no elicitation support cannot be prompted and the call is refused. This
is deliberate (refusing beats silently proceeding) but means the gate's behaviour
depends on the connected client.
There is **no approval gate on the A2A surface at all** — A2A has no elicitation
channel, and `apexe a2a` rejects the flag rather than accepting it and doing
nothing.
For a boundary that needs no human and works on every surface, use `--acl`.
### 5.4 Approval is not an ACL condition
`require_approval` is not a registered apcore ACL condition key. Approval gating
happens in the Executor's `ApprovalHandler`, not in ACL evaluation. Writing it as
an ACL condition would silently never match — the rule would fall through rather
than deny. Do not attempt it in a hand-written policy file.
### 5.5 The audit trail cannot tell you what was deleted
Because no argument values are recorded, `audit.jsonl` answers "which principal
invoked which module, when, with what outcome" — and not "which file did it
remove". This is a privacy-and-tamper tradeoff, taken deliberately. If your
forensic requirement is the latter, `apexe`'s log alone will not meet it.
### 5.6 Scan quality is bounded by the tool's own help output
Schemas are derived deterministically from `--help`, man pages and shell
completions. A tool with incomplete, inconsistent or absent help produces an
incomplete schema. Nothing here infers intent — that is the point, but it means
coverage varies by tool. Curated overlays exist for this reason.
### 5.7 Not covered at all
- Anything the agent does **without** invoking a wrapped tool: direct HTTP calls,
file writes through its own edit tool, code it executes in a sandbox
- Prompt injection reaching the agent through tool *output* (`apexe` bounds size,
not content)
- Compromise of the `apexe` binary, its binding files, or its ACL file. Binding
files are checked against `BINDING_INJECTION_CHARS` as a tamper signal, which
is a signal and not a defence
- Anything that happens after the wrapped tool starts running
### 5.8 The path guard sees types, not intent
The guard checks the arguments the input schema types as paths, at the strength
the module's `readonly` annotation selects. Five limits follow directly, and
none of them is a bug to be fixed later:
- **A schema that does not mark a value as a path leaves it unchecked.** The
marker comes from the scanner's `ValueType::Path` inference or from an
overlay's `"type": "path"`. A tool whose help text does not reveal that an
option takes a filename yields an unmarked value, and the guard has nothing
to act on. Guessing is not the alternative — treating every string as a path
would refuse `grep /etc/hosts logfile`, whose first argument is a pattern.
- **It bounds arguments, not what the tool does with them.** `find . -delete`,
a config file that names a target, a tool that reads paths from stdin, and
any shell-out the wrapped tool performs itself are all past the boundary.
The last bullet of §5.7 — nothing after the wrapped tool starts running —
still holds in full.
- **The mode is per module, not per argument.** `cp /etc/hosts ~/backup` is
refused even though `/etc/hosts` is only being *read*, because `cp` is not a
`readonly` module and both its operands are judged at the module's strength.
Distinguishing a source operand from a destination would need a
per-argument direction the scanner cannot infer and no overlay declares. The
failure direction is a refusal rather than a permit, so this is friction
rather than exposure.
- **A recursive read rooted above a credential directory is not caught.**
Ancestry binds writers only (§4.8), so `grep -r … /` and `ls -R ~` pass the
guard even though a recursive read can reach `~/.ssh`. The alternative was
refusing `ls ~` outright, which is most of what a read-only tool is for. The
guard sees paths, not the `-r` that changes what a path means — closing this
needs flag semantics it does not have.
- **Glob expansion never happens** (§4.1: no shell), so `rm /etc/*` reaches the
guard as a single literal path and is refused. That is the safe direction,
but it is a consequence of having no shell, not something the guard verifies.
The guard raises the floor for the case that actually recurs — an agent
pointing a legitimate destructive command at a system directory. It is not a
sandbox, and §5.1 and §6 still apply in full.
### 5.9 A tool that runs other tools defeats every name-based control
`env`, `xargs`, `nice`, `timeout`, `nohup`, `chroot`, `sudo` and their kin do
not merely *have* dangerous options — running a caller-supplied command **is**
their interface. Everything apexe decides from a command's name is therefore
decided about the wrapper rather than about what it will run.
This was live, and it is worth stating exactly because the shape recurs:
- `env`'s name is in `READONLY_PATTERNS`, so the generated ACL gave it an
explicit **allow** (§5.2's "false readonly", reached by the worst possible
name).
- BSD `env` takes `-S <string>`, which splits the string into argv and executes
it. `-S` is typed `string`, not `path`, so §4.8's guard never inspected it —
correctly, by its own contract, since nothing there is a path.
- `cli.env` with `{"S": "rm -rf /etc"}` therefore passed both controls.
`EXEC_WRAPPER_TOOLS` in `src/adapter/annotations.rs` now classifies these as
`destructive`, which flips the generated ACL from allow to deny and makes the
path guard judge their arguments as a writer's. Two overlays that carried
`destructive: false` for `xargs` were corrected in the same change, since a
curated overlay replaces the scan result and would otherwise have overridden
the classification silently.
**That fix is a floor, not a solution.** No static analysis can decide what
argv a caller-supplied string will become, so the guard cannot inspect the
command inside `-S` or the one after `xargs`. Treat these tools as equivalent
to handing the agent a shell (§5.1):
```yaml
# In your ACL, ahead of any broad allow rule:
- callers: ["*"]
targets: ["cli.env", "cli.xargs", "cli.sudo", "cli.timeout", "cli.nice"]
effect: deny
description: "Command executors — argv is caller-controlled"
```
Better still, do not scan them into the registry at all. A wrapped `env` buys
nothing that wrapping the underlying tool directly does not, and it costs every
control in §4.
### 5.10 A binding older than the control it feeds turns that control off
Three of the controls in §4 read the schema rather than the command: the path
guard acts on values typed `x-apexe-path` (§4.8), the approval gate on
`x-apexe-escalates` and `x-apexe-approval-basis` (§4.9), and log redaction on
`x-sensitive`. A binding file written before a keyword existed does not carry
it, so for that module the control **has nothing to act on and enforces
nothing**. Nothing fails; the call simply is not checked.
This is a different limitation from §5.8's first bullet, and the difference is
the remedy. There, the scanner could not tell that an option takes a filename,
and no rescan changes that. Here the scanner infers it perfectly well and the
file on disk merely predates it — **a rescan fixes it completely**. Reading
§5.8 as covering both would leave an operator concluding there is nothing to
do.
It is not a hypothetical. 0.7.0 introduced all three keywords; on the
development machine where this was found, 166 of 166 binding files had been
written by an earlier release, so all three controls were inert across the
entire registry and no mechanism existed to say so.
Two things narrow it as of 0.8.0, neither of which closes it:
- Every binding now records `metadata.generated_by` (`apexe <version>`). Nothing
reads it yet — it is the half that has to exist before a later release can
compare it against its own and refuse to serve, or warn, on a mismatch.
- `bindings.dir` moved the default directory, so the upgrade to 0.8.0 forces a
rescan and clears the backlog once. That is luck, not a mechanism: the next
release to add a keyword has no such move behind it.
**Until a version check ships, re-run `apexe scan` after every apexe upgrade.**
§6 states this as a deployment step.
### 5.11 Reserved: four limitations that arrive with local execution
Not limitations of apexe today — the surface they describe does not exist yet.
They are recorded here so they land *with* the feature rather than after it.
[`docs/features/v2-f8-local-execution.md`](features/v2-f8-local-execution.md) §8
makes each a release condition for its Stage 2, and each becomes a numbered
subsection of this section when that ships:
- **stdin would be an ungoverned input channel.** Every control in §4 acts on
argv. An inherited stdin is not schema-validated, not path-checked and not
recorded — and for any tool that reads a program from stdin (`python -`,
`awk`, `sh -s`, `sed -f -`) that is a complete bypass by a different route
than §5.9's. F8 requires an allowlist (`streaming_stdin_safe`, a human
assertion per module), never a denylist.
- **Shim coverage would be partial, and the gap silent.** Shell builtins —
`cd`, `echo`, `test`, and in most shells `kill` — are resolved without
consulting `PATH`, so no shim can sit in front of them and nothing at the
point of use distinguishes a governed command from an ungoverned one.
- **A shim would be bypassable by absolute path.** `/bin/ls` is not a `PATH`
lookup. This is §5.1 applied locally: against a human the shim is an audit
trail, not enforcement; it is a real boundary only where `PATH` and the
filesystem are controlled externally (a container, a CI runner image).
- **`--as` asserts a principal, it does not authenticate one.** F8 constrains it
to `--dry-run` for that reason, and audit records from a preflight mark the
principal as asserted.
---
## 6. Recommended deployment
1. Run `apexe` inside a sandbox. It governs; the sandbox contains.
2. Remove or restrict raw shell tools in the agent host (§5.1) — otherwise the
governed path is optional, and optional controls are decorative.
3. Review the generated ACL (§5.2) — especially every rule in the readonly allow
list — and then **pass it explicitly**. It is not applied for you (§5.3):
```bash
apexe serve --acl ~/.apexe/acl.yaml --enable-approval
```
4. Confirm your MCP client supports elicitation, or the approval gate refuses
rather than prompts (§5.3.1). On A2A there is no gate at all — use the ACL.
The path guard (§4.8) needs no wiring: it is on by default on every surface.
Extend it with `additional_denied_paths` if this deployment has data
directories worth the same protection.
5. Keep `--auth` at its default on HTTP transports. A non-loopback bind with no
credential refuses to start unless explicitly acknowledged; do not acknowledge
it casually.
6. Ship `audit.jsonl` somewhere the agent cannot write, and know what it does and
does not contain (§5.5).
7. Re-review the ACL after every `apexe scan`. A rescan merges freshly generated
rules into the existing file, so new commands arrive with heuristic
classifications you have not read yet (§5.2).
8. **Re-run `apexe scan` after every apexe upgrade**, before trusting the path
guard, the approval gate or log redaction on that host. All three read
keywords out of the binding file, so a binding written by an earlier release
silently carries none of them and the control enforces nothing (§5.10). A
rescan fixes it completely; nothing else does, and as of 0.8.0 nothing
detects it.
9. Do not wrap command executors — `env`, `xargs`, `sudo`, `timeout`, `nice`
and their kin (§5.9). They are classified `destructive` so the generated ACL
denies them, but the durable fix is to keep them out of the registry: argv
is caller-controlled there, and no control in §4 can see inside it.
---
## 7. Reporting
Report security issues privately — see [SECURITY.md](../SECURITY.md), which
turns §4 and §5 of this document into an explicit in-scope / out-of-scope list.
The short version: if you find a way to reach `execve` with argv the contract did
not authorise, that is a vulnerability and we want it. If you find that a
heuristic misclassified a command, that is §5.2 working as documented — an
overlay fix, not a vulnerability.