Complete the documentation set for the M0.5 toolchain, grounded in the code: - spec/references.md: import/reference/call edges, identities, loader rules, anchors, `ref` resolution/ambiguity, `check --refs` validation. - spec/value-wire.md: exact wire_version 1 typed encoding, integer-as-decimal string rule, special floats, limits and exact float round-trip. - spec/security.md: modes (strict refuses without OS isolation), capabilities, path rules, budgets, tracing, foreign process caveats, plugin trust. - spec/package-format.md: marqdo.yaml/lock formats, validation, lock/sync, unsupported registry/git/environment work. - spec/plugin-abi.md: ABI v1 layout/ownership/negotiation, manifest/artifact rules, wire envelopes, loader lifecycle, trust boundary, SDK/C demo, and the implemented CLI plugin-invocation flow with its limitations. - spec/math.md and spec/foreign.md: the implemented math subset and the foreign request/response/timeout/capability contract. - docs/adr/0001..0007: accepted decisions for the span foundation, inert executables outside function bodies, ref ambiguity (S-07), strict refusal, AST normalization, CLI contract and BigInt/typed wire (S-08). - docs/contributor-guide.md: repo map, workflow, fixture/golden updates, quality gate, ADR/commit policy. - docs/STATUS.md: P0-P7 matrix with evidence, open items and the blueprint §18 Alpha checklist (conclusion: not yet Alpha-complete), including known divergences rather than overclaims. - README.md rewritten from "design-only starter" to the working implementation with quickstart, implemented phases, deliberate limits and doc index. - AGENTS.md: updated pointers/workflow only; architectural rules unchanged. - Consistency fixes in spec/mapping.md/evaluation.md (inert emph outside functions, unsupported math.simplify/differentiate).
277 lines
15 KiB
Markdown
277 lines
15 KiB
Markdown
# Marqdo Security Model (implemented status)
|
|
|
|
Status: **describes the M0.5 implementation, including honest gaps.** This is
|
|
not a security audit; it documents what the code actually enforces.
|
|
|
|
Normative implementation:
|
|
|
|
| Concern | Code |
|
|
|---|---|
|
|
| Sandbox modes, strict refusal | `crates/marqdo-sandbox/src/lib.rs` |
|
|
| Capability sets and checks | `crates/marqdo-host/src/capability.rs` |
|
|
| Host dispatch and per-op checks | `crates/marqdo-host/src/host.rs` |
|
|
| Project-rooted filesystem | `crates/marqdo-host/src/fs.rs` |
|
|
| Budgets | `crates/marqdo-host/src/budget.rs` |
|
|
| Effect tracing | `crates/marqdo-host/src/trace.rs` |
|
|
| Math/foreign adapters | `crates/marqdo-host/src/kernels.rs` |
|
|
| Foreign child processes | `crates/marqdo-foreign/src/lib.rs` |
|
|
| Plugin loading / in-process plugin calls | `crates/marqdo-host/src/host.rs` (`load_plugin`, `op_plugin_invoke`), `crates/marqdo-plugin-abi/src/loader.rs` |
|
|
| CLI flags and capability construction | `crates/cli/src/main.rs`, `crates/cli/src/commands.rs` |
|
|
|
|
## 1. Modes
|
|
|
|
`SandboxMode` has three values (`pure`, `project`, `strict`), parsed by
|
|
`SandboxMode::parse` and selectable on `run`/`call` with
|
|
`--mode <pure|project|strict>` (default: `project`).
|
|
|
|
| Mode | Intended guarantee | Actual status in this build |
|
|
|---|---|---|
|
|
| `pure` | No external I/O; memory computation and budgets only. | **Enforced.** `Capabilities::pure()` = `console`, `math` only; every FS/foreign/plugin grant flag makes the CLI exit 2 with "pure mode prohibits external I/O grants". |
|
|
| `project` | Operator-approved project resources under `CapabilityHost` + bounded resources. | **Enforced for the implemented operations.** Defaults equal `pure`; `--allow-read`, `--allow-write`, `--allow-foreign`, `--allow-plugin` add grants. Sandboxing is cooperative (in-process checks), not OS isolation. |
|
|
| `strict` | Untrusted documents/code/plugins under real OS isolation. | **Refused.** `PlatformCapabilities::detect()` always reports `strict: Unavailable` in this build because no OS isolation adapter (namespaces/seccomp/cgroups, Job Object, macOS sandbox) is implemented, and `worker_processes: false`. `marqdo_sandbox::enforce` returns `StrictUnavailable`; `run`/`call` print the reason and exit 1. There is **no fallback** to an unrestricted process. |
|
|
|
|
`marqdo inspect <file> --platform` prints the detection report, for example:
|
|
|
|
```json
|
|
{
|
|
"os": "linux",
|
|
"arch": "x86_64",
|
|
"strict": {"state": "unavailable",
|
|
"reason": "no OS isolation adapter (namespaces/seccomp/cgroups) is implemented in this build"},
|
|
"worker_processes": false
|
|
}
|
|
```
|
|
|
|
Design rule (blueprint §9): a cooperative in-process check is not a sandbox.
|
|
Strict mode will remain refused until a platform isolation adapter exists; see
|
|
ADR-0004.
|
|
|
|
## 2. Capability grants
|
|
|
|
`Capabilities` (`crates/marqdo-host/src/capability.rs`) is the effective grant
|
|
set for one run:
|
|
|
|
| Field | Default (`pure`/`project`) | Used by |
|
|
|---|---|---|
|
|
| `console: bool` | `true` | currently **not checked** by `op_print`; print is always allowed and only bounded by the output budget (open item) |
|
|
| `math: bool` | `true` | `math.*` host ops |
|
|
| `fs_read: Vec<String>` | empty | `fs.read` |
|
|
| `fs_write: Vec<String>` | empty | `fs.write` |
|
|
| `net_hosts: Vec<String>` | empty | `Capabilities::check_net` exists, but no host op or builtin performs network access in this build |
|
|
| `process: bool` | `false` | required together with `foreign` for `foreign.run`/`foreign.call` |
|
|
| `foreign: bool` | `false` | foreign kernels |
|
|
| `plugins: Vec<String>` | empty | `plugin.invoke` and `StdHost::load_plugin` |
|
|
|
|
Requests versus grants:
|
|
|
|
* `marqdo.yaml` `capabilities:` is a **request**. It is parsed and validated
|
|
(`crates/marqdo-package/src/lib.rs`) but is not consulted when building the
|
|
host capability set: only CLI flags/grant APIs produce grants. Declaring a
|
|
capability never grants it.
|
|
* `marqdo.yaml` `plugins:` likewise declares requirements only; it does not
|
|
install, load or authorize a plugin.
|
|
* CLI grant flags (`crates/cli/src/main.rs::SandboxArgs`):
|
|
* `--allow-read <GLOB>` and `--allow-write <GLOB>` (repeatable, project mode
|
|
only);
|
|
* `--allow-foreign` (project mode only; sets `foreign = true` and
|
|
`process = true`);
|
|
* `--allow-plugin <PACKAGE-NAME>` (repeatable, project mode only; matches the
|
|
manifest `plugin.name`, not the call namespace);
|
|
* `--plugin <PATH>` (repeatable, loads a plugin after the trust check);
|
|
* `--trust-native-plugin` (explicit in-process native trust decision).
|
|
* There is no network grant flag and no plugin-worker flag in this build.
|
|
|
|
### 2.1 Filesystem grants are project-relative globs
|
|
|
|
`fs.read`/`fs.write` paths go through `ProjectFs::resolve` **before** the
|
|
capability check:
|
|
|
|
* empty paths, absolute paths, `..` components and root/prefix components are
|
|
rejected with `permission.denied`;
|
|
* `.` components are dropped; the normalized relative string uses `/`;
|
|
* the capability patterns are matched with the `glob` crate against that
|
|
normalized relative path; a leading `./` is stripped on both sides, so
|
|
`--allow-read ./data/**` matches `data/a.csv` and does not match
|
|
`secrets/key`; `--allow-write output/**` does not grant reads;
|
|
* an invalid glob pattern is treated as non-matching (`Pattern::new(...).
|
|
unwrap_or(false)`), so it silently grants nothing (there is no diagnostic).
|
|
|
|
Additional FS limits (`crates/marqdo-host/src/fs.rs`):
|
|
|
|
* reads are capped at `MAX_READ_BYTES = 8 MiB`, must be regular files, must be
|
|
UTF-8, and the canonicalized path must stay inside the project root;
|
|
* writes create parent directories; before writing, the **closest existing
|
|
ancestor** is canonicalized and must stay inside the project root.
|
|
|
|
Known caveat: for writes, only the closest existing ancestor is checked and the
|
|
final write uses the non-canonical path. A symlink created between the check
|
|
and the write (TOCTOU) could escape the root. Reads canonicalize the final path
|
|
before reading. Full symlink/race hardening is an open P4 item.
|
|
|
|
### 2.2 Checks happen at execution points, not only at parse time
|
|
|
|
`Host::invoke` is the only path to effects. `StdHost::dispatch` routes every
|
|
`HostOp` and the checks run immediately before the effect:
|
|
|
|
* `fs.read` → `capabilities.check_read(path)` then `ProjectFs::read`;
|
|
* `fs.write` → `check_write` then `ProjectFs::write`;
|
|
* math ops → `capabilities.math` (in `crates/marqdo-host/src/kernels.rs`);
|
|
* foreign ops → `capabilities.check_foreign` (requires `foreign && process`);
|
|
* plugin invoke → the namespace must be loaded, then
|
|
`capabilities.check_plugin(package)` on **every call**; loading also checks
|
|
the same grant once;
|
|
* print → output budget only.
|
|
|
|
Static analysis may warn, but it never replaces these runtime checks. There is
|
|
no host bypass for tests: tests use the same `StdHost`/`Capabilities` types.
|
|
|
|
## 3. Resource budgets
|
|
|
|
`Budget` (`crates/marqdo-host/src/budget.rs`) is per run:
|
|
|
|
| Limit | Default | Enforcement |
|
|
|---|---|---|
|
|
| evaluation fuel | `DEFAULT_FUEL = 5_000_000` | 1 unit per statement, 1 per expression node, 1 per branch condition, 1 per loop iteration; exhaustion → `resource.exhausted` |
|
|
| call stack depth | `DEFAULT_STACK_LIMIT = 256` | checked before every function call → `resource.exhausted` |
|
|
| program output bytes | `DEFAULT_OUTPUT_BYTES = 1 MiB` | `print` output and `fs.read` contents are charged; overflow → `resource.exhausted` |
|
|
| wall clock | none by default | `--timeout <seconds>` sets a deadline; checked between statements/iterations and before loop conditions → `resource.exhausted`. It does **not** preempt a running host call. |
|
|
|
|
CLI overrides (`run`/`call`): `--fuel`, `--stack`, `--max-output`,
|
|
`--timeout`. Additional fixed limits:
|
|
|
|
* foreign kernel: `StdHost.foreign_timeout = 10s` and
|
|
`foreign_output_limit = 1 MiB` (stdout+stderr combined) per call.
|
|
These are not configurable from the CLI in this build;
|
|
* plugin wire: request ≤ 16 MiB, result ≤ 64 MiB, error ≤ 1 MiB, metadata
|
|
≤ 64 KiB (see `include/marqdo_plugin_abi_v1.h`);
|
|
* math kernel: 1 MB source, 256 parse depth, 512 AST nodes, exponent ≤ 10,000,
|
|
exact-result ≤ 1,000,000 bits (`crates/marqdo-math`).
|
|
|
|
These are cooperative budgets in the interpreter and the supervisor. Only
|
|
foreign child processes are terminated by the host (kill on timeout/output
|
|
overflow). In-process math and native plugins are not OS-limited.
|
|
|
|
## 4. Effect tracing
|
|
|
|
`EffectTrace` records one entry per `Host::invoke` when enabled
|
|
(`--trace`, or implicitly `--json` for `run`/`call`). Entry fields:
|
|
|
|
```json
|
|
{"op":"print","module":"hello.mq.md","span":{"start":43,"end":57},
|
|
"duration_micros":3,"result":"ok"}
|
|
```
|
|
|
|
* `op` is the stable `HostOp::name()` (`print`, `math.eval`, `foreign.call`,
|
|
`fs.write`, `plugin.invoke`, ...);
|
|
* `module` is the initiating module id; `span` is the call site when known;
|
|
* `result` is `"ok"` or the failure code (for example
|
|
`permission.denied`);
|
|
* argument values and file contents are **not** recorded, so ordinary secrets
|
|
do not leak into traces by design. Paths are also not recorded today.
|
|
* In text mode trace entries are printed to stderr (`trace: ...`); in JSON
|
|
mode they are a `trace` array next to the program stdout string. Program
|
|
output is always separate from diagnostics/trace (stdout vs stderr).
|
|
|
|
## 5. Foreign kernels: process isolation, not a sandbox
|
|
|
|
`crates/marqdo-foreign/src/lib.rs` runs Python/Node one-shot:
|
|
|
|
* the program is written to a private temp file (mode 0600 on Unix), the child
|
|
runs with a fresh private temp directory (mode 0700) as cwd, and both are
|
|
removed on drop;
|
|
* direct `argv` exec (no shell, no interpolation); stdin carries the versioned
|
|
request envelope; stdout/stderr are always piped and captured;
|
|
* the environment is cleared except `PATH`;
|
|
* the wall-clock deadline is enforced by polling `try_wait` and killing the
|
|
direct child; output flooding kills the child once the combined byte budget
|
|
is exceeded; a 2-second reader grace prevents a grandchild holding the pipes
|
|
from hanging the host;
|
|
* a non-zero exit is data (`RunStatus::Failed`, stderr preserved); a timeout is
|
|
`TimedOut` for `run` and an error for the typed `call`.
|
|
|
|
What this is **not**: an OS sandbox. The child runs with the host user's
|
|
privileges, can open absolute paths, use the network and spawn further
|
|
processes. Clearing the environment and changing cwd are hygiene, not
|
|
confinement. Grandchildren are not killed when the direct child is killed.
|
|
Strict mode refuses to run at all, so foreign execution is only reachable in
|
|
`project` mode with `--allow-foreign`.
|
|
|
|
## 6. Plugins: in-process native trust boundary
|
|
|
|
* The only plugin transport implemented in this build is **in-process native
|
|
loading** (`libloading`) after `manifest.validate()`, exact target-triple
|
|
artifact resolution, sha256 verification, ABI negotiation and export
|
|
metadata cross-checking (`crates/marqdo-plugin-abi/src/loader.rs`).
|
|
* Loading requires **three** independent things:
|
|
1. `--plugin <manifest-or-dir>` names the plugin;
|
|
2. `--trust-native-plugin` is an explicit unsafe trust decision;
|
|
3. the manifest package name is granted with `--allow-plugin <name>` (checked
|
|
again on every invocation).
|
|
Without trust, `StdHost::load_plugin` returns `permission.denied` with the
|
|
hint that no isolated worker transport exists. There is no isolated worker,
|
|
Wasm component or out-of-process plugin path in this build.
|
|
* A native plugin runs in the host address space. It can read host memory,
|
|
call arbitrary syscalls, bypass the capability model entirely and crash or
|
|
corrupt the host process. **A C ABI is not a sandbox.** `--trust-native-plugin`
|
|
must be treated as equivalent to running the plugin's code as the host user.
|
|
* Plugin call sites are written as `<namespace>.<export>(...)` in a function
|
|
body (for example `solver.add(a=20, b=22)`). The namespace is derived from
|
|
the **first** manifest export prefix. Calls are made through
|
|
`HostOp::PluginInvoke` with a typed `wire_version` 1 request; the plugin's
|
|
typed response becomes a Marqdo value (`Unit` when absent). Named arguments
|
|
are required in this build; positional plugin arguments are `runtime.type`.
|
|
* Plugin errors map to structured runtime errors: ABI → `plugin.abi_mismatch`,
|
|
capability → `permission.denied`, wire/value → `runtime.type`, unsupported →
|
|
`kernel.unavailable`, everything else → `plugin.failure`. An unloaded
|
|
namespace is `symbol.unknown`.
|
|
* The plugin's host-capability requests are denied by default: the CLI loads
|
|
plugins with `LoadOptions::default()`, i.e. **no capability handler**, so
|
|
every `request_capability` call fails. The `requires:` list in `plugin.yaml`
|
|
is only a declaration.
|
|
* `marqdo plugin inspect` never loads code: it validates the manifest and
|
|
verifies the artifact hash only.
|
|
* Installation, inspection, loading and authorization are four separate
|
|
decisions. Copying a plugin into the project or declaring it in
|
|
`marqdo.yaml` grants nothing.
|
|
|
|
Known limitations: single namespace per plugin (derived from the first export),
|
|
no hot unload/reload, no plugin capability bridge from this CLI, native crash
|
|
is a host crash, `plugin.invoke` cannot be used in `pure`/`strict` mode.
|
|
|
|
## 7. `check` and `inspect` are side-effect free
|
|
|
|
Neither command executes project code. Specifically:
|
|
|
|
* `check` parses, indexes, maps to IR, runs static call validation and reports
|
|
diagnostics. It never calls a function, never spawns a foreign kernel, never
|
|
loads a native plugin and never writes files.
|
|
* `inspect` with `--ast`, `--units`, `--signature`, `--ir`, `--refs` or
|
|
`--platform` does the same static work and prints metadata. `--refs` may
|
|
**read** other project source files on demand to resolve link targets, but
|
|
only parses/analyzes them; nothing is executed or written.
|
|
* `plugin inspect` reads `plugin.yaml`, validates it, resolves the artifact for
|
|
the host target and computes/compares its sha256. It does not `dlopen`,
|
|
instantiate or call the plugin (`"loaded": false` in JSON output).
|
|
* `run`/`call` first perform the same static load; if any diagnostic has error
|
|
severity, execution is refused before the host or any kernel is touched.
|
|
* `fmt` only normalizes line endings/trailing newlines and writes the document
|
|
when not in `--check` mode; it does not execute anything.
|
|
|
|
## 8. Open security items
|
|
|
|
1. Strict mode: no OS isolation adapter (P4); worker processes report
|
|
`false`.
|
|
2. `console` capability is not enforced; print is always allowed.
|
|
3. Network capability exists in the model but no host operation uses it; there
|
|
is no `--allow-net` flag.
|
|
4. Write-path symlink TOCTOU (see §2.1).
|
|
5. Plugin worker isolation and a plugin capability bridge are unimplemented;
|
|
only trusted in-process native plugins are possible.
|
|
6. `plugin_handle` wire values are structurally reconstructable (see
|
|
`value-wire.md` §4.1); no unforgeable capability token.
|
|
7. Budgets do not cover all allocation paths (for example list/table growth
|
|
inside the interpreter is bounded only by fuel and memory).
|
|
8. `--json` run output includes the full program stdout string; that is the
|
|
program's own output, not a host secret, but it is embedded in the JSON
|
|
document consumers must parse.
|