REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated Cargo.lock; project.marqdo is enforced against the running core with package.marqdo_range_invalid/package.marqdo_incompatible fail-closed diagnostics; Tool SemVer prerelease negotiation tests; init template and examples use the beta range. Verify init derives the project name from the target directory instead of falling back to 'example'. REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for the release evidence. REL-03: deterministic release packaging (tools/release/package.py) ships the CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json, known-limitations, specs, developer docs, examples incl. built plugin/provider artifacts and consumers; tools/release/smoke.py cold-install tests the archive. REL-04: docs/developers entry pages; corrected and self-contained third-party integration handbook; stale Proposed/native-only/informational spec claims fixed; release/status/compatibility/changelog/releasing docs updated. REL-05: release_evidence.py gains an explicit beta profile (BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build step now packages and smoke-tests the archive on every pipeline. Adds a runnable Resource Provider v2 example and corrects check --emit to Analysis v2.
26 KiB
Marqdo Security Model (implemented status)
Status: describes the 3.0.0-beta.1 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 |
| Trusted capability handlers | crates/marqdo-host/src/capability.rs (CapabilityBroker, CapabilityHandler, FsReadHandler; ADR-0057) |
| 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-net, --allow-env, --allow-process, --allow-random, --allow-foreign, --allow-plugin add grants. resource.open supports stdin read, separate stdout/stderr write, granted project-file read/write (ADR-0025/0026/0040), granted in-process provider kinds (ADR-0033) and granted TCP/UDP/listener/TLS streams, including DNS names after an exact host grant (ADR-0034/0047/0048); process/device remain unsupported. Sandboxing is cooperative (in-process checks), not OS isolation; in-process providers are trusted, not sandboxed. |
strict |
Untrusted documents under real OS isolation. | Linux: enforced when the runtime probe passes (ADR-0021). resource.open is refused in strict except for the existing stdio/stdout console channel (console grant); stdin/stderr, file/TCP/provider/process resources remain refused until a provider passes the isolation lane (CM-A11, ADR-0030/0034/0040). PlatformCapabilities::detect() runs a real Bubblewrap smoke test; success reports Available { mechanism }, failure reports Unavailable { reason }. Strict L1 supports the interpreter, console, native Math and the read-only bundled stdlib (published at /run/marqdo-stdlib for the Compat-C print chain); --allow-read/--allow-write/--allow-net/--allow-env/--allow-process/--allow-random/--allow-foreign/--allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file are rejected with exit 2. macOS/Windows and Linux hosts without the mechanisms remain Unavailable; there is no fallback to an unrestricted process. |
marqdo inspect <file> --platform prints the detection report, for example:
{
"os": "linux",
"arch": "x86_64",
"strict": {"state": "available",
"mechanism": "bubblewrap 0.11.1 (user/mount/PID/net/UTS/IPC namespaces + no-new-privs + rlimits)"},
"worker_processes": true
}
On a host that cannot create the namespaces the same block is
{"state": "unavailable", "reason": "..."} and strict refuses. Design rule
(blueprint §9): a cooperative in-process check is not a sandbox. See ADR-0021
for the Linux construction, L1 scope and non-goals; ADR-0019 still governs
every other platform.
1.1 @exec is not a grant
The @exec heading mode introduced by RFC-LANG-0002 is a compile-time
projection, not an authorization. A payload in @exec still passes the same
CapabilityHost checks, budgets and sandbox rules; a payload in @knowledge
produces no IR and therefore cannot cause a host effect at all. No heading
annotation, keyword or Markdown container can grant a file/network/process
capability, and permission flags never change the AST→IR result.
1.2 Strict failure and --json contract
Strict execution is a two-phase operation: detect, then launch. Availability
observed by inspect --platform is a snapshot, not a permanent promise. The
runtime therefore re-probes before launching; a failure after a successful
probe is a refusal, never a fallback.
--json consumers must receive exactly one JSON document on stdout for
every outcome:
- a verified child in
--jsonmode produces that document itself and its bytes and exit code are forwarded unchanged; - a control-plane failure (probe, supervisor spawn, namespace construction,
timeout, capture) produces one CLI error document
{"command": ..., "success": false, "error": ..., "code": ...}; - output that is empty or is not exactly one JSON document is rejected as
strict.child_invalid; raw supervisor text is never forwarded as program stdout.
The stable codes are strict.probe_unavailable, strict.spawn_failed,
strict.namespace_failure, strict.timeout, strict.resource_limit,
strict.child_invalid, strict.identity_invalid and
strict.unsupported_grant (ADR-0053). A marker alone never authorizes strict
execution: Linux verifies the namespace/privilege identity, and every other
platform rejects MARQDO_STRICT_ACTIVE outright (ADR-0053).
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 |
resource.open("stdio","stdin",["read"]), resource.open("stdio","stdout"/"stderr",["write"]) and the stdlib console chain; a missing grant is permission.denied and stdout/stderr are also bounded by the output budget |
math: bool |
true |
math.* host ops |
fs_read: Vec<String> |
empty | fs.read and project resource.open("file", path, ["read"]) |
fs_write: Vec<String> |
empty | fs.write and project resource.open("file", path, ["write"]) |
net_hosts: Vec<String> |
empty | exact host/IP grants for `resource.open("tcp" |
env: Vec<String> |
empty | exact-name grants for resource.request("env.get", [name]); no glob and no env.list; --allow-env <NAME> adds a grant (ADR-0043) |
process_programs: Vec<String> |
empty | exact program paths for resource.request("process.run", [program, args]); no shell, env_clear, project root cwd, 5 s timeout, 1 MiB stdout/stderr cap; --allow-process <PROGRAM> adds a grant (ADR-0044); not an OS sandbox |
random: bool |
false |
OS entropy for resource.request("random.bytes", [count]); --allow-random enables it; project mode only (ADR-0046) |
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 |
resource_providers: Vec<String> |
empty | registered in-process/worker/C-ABI ResourceProvider kinds; project mode only; helper processes and native libraries are trusted, not sandboxed (ADR-0033/0035/0036); local manifests are host-installed, unsigned (ADR-0037); the C worker helper is a trusted process boundary, not a sandbox (ADR-0038) |
Requests versus grants:
marqdo.yamlcapabilities: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.yamlplugins: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-net <HOST>(repeatable, exact host name or IP literal, project mode only, ADR-0034/0047);--allow-env <NAME>(repeatable, exact environment variable name, project mode only, ADR-0043);--allow-process <PROGRAM>(repeatable, exact program path, project mode only, ADR-0044; the child is not sandboxed);--allow-random(project mode only; OS entropy, ADR-0046);--allow-foreign(project mode only; setsforeign = trueandprocess = true);--allow-plugin <PACKAGE-NAME>(repeatable, project mode only; matches the manifestplugin.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 plugin-worker flag in this build. Network and environment grants are exact and project-mode only.
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 withpermission.denied; .components are dropped; the normalized relative string uses/;- the capability patterns are matched with the
globcrate against that normalized relative path; a leading./is stripped on both sides, so--allow-read ./data/**matchesdata/a.csvand does not matchsecrets/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)thenProjectFs::read;resource.request("fs.*")→check_read/check_writebefore path resolution;resource.request("env.get")→capabilities.check_env(name)beforestd::env::var;resource.request("process.run")→capabilities.check_process(program)beforeCommand::spawn;resource.request("random.bytes")→capabilities.check_randombeforegetrandom::fill;fs.write→check_writethenProjectFs::write;- math ops →
capabilities.math(incrates/marqdo-host/src/kernels.rs); - foreign ops →
capabilities.check_foreign(requiresforeign && process); - plugin invoke → the complete export name must be registered, then
capabilities.check_plugin(package)on every call; loading also checks the same grant once; - plugin host-capability requests →
CapabilityBrokerruns a fixed chain:decide(package, effective grants, trusted vendor policy, payload shape) → a trustedCapabilityHandlermust be installed for the exact capability name → a package-bound handler must own the trusted package identity → the handler executes under the broker budget and reply limit → one audit entry. Grantedfs.readexecutes throughFsReadHandler, which resolves the path withProjectFsand re-checks the read grant on the normalized project-relative path before returning the real file bytes. Every capability without an installed handler — other core capabilities (fs.write,net.request,process, console/math/log/clock/random/artifact.record) and vendor capabilities without a trusted executor — returnscapability.unavailable; it never pretends an empty reply is success. A vendor name with no trusted policy entry ispermission.denied(ADR-0011, ADR-0057); - 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.
2.3 Executable capabilities need an installed trusted handler
CapabilityBroker (crates/marqdo-host/src/capability.rs, ADR-0057) separates
being authorized from being executable:
| Question | Registry | Failure |
|---|---|---|
| Is this capability granted for this trusted package? | Capabilities / vendor_policy |
permission.denied |
| Is a trusted executor installed for this exact name? | handlers: BTreeMap<String, HandlerEntry> |
capability.unavailable |
| Does a package-bound handler own the claimed package? | HandlerEntry.package |
permission.denied |
Execution order is fixed: decide → handler installed → package binding →
handler execution under the broker Budget and reply limit → audit. A name in
vendor_policy is policy only; it does not install anything, and it cannot
turn into an executor. A core capability granted by Capabilities but missing
a handler is capability.unavailable, never an empty Ok.
- Registration is host-only.
register_handler(handler)/register_package_handler(package, handler)are called by the trusted host / embedder composition root; no manifest, plugin or wire message can reach the registry. The registry key ishandler.name(), so a handler cannot be registered under a name it does not declare. - Rejected names (stable codes): empty/whitespace/malformed names are
capability.handler_invalid; names under the reserved host prefixesmarqdo./host.arecapability.handler_reserved; an already registered name (including the built-infs.read) iscapability.handler_conflict. A rejected handler is not installed. fs.readis the first migrated standard handler (FsReadHandler), installed byCapabilityBroker::with_fs(fs). It keeps theProjectFsroot, traversal/absolute-path rejection, regular-file/UTF-8/8 MiB limits and the glob grant, and it re-checks the grant against the normalized path at the execution point. The broker reply limit (MAX_CAPABILITY_REPLY_BYTESby default) bounds the returned bytes; an oversize reply isresource.exhausted.- Audit: every decision records package, capability,
granted/denied/unavailable, a reason andduration_micros. Payloads and file contents are never recorded, so ordinary secrets do not appear in the audit log. - Budgets: handlers receive
&mut Budgetand can charge fuel/output; the broker also enforces the reply byte limit. Native handlers still run in-process and are trusted code, not a sandbox.
Known gaps in this build: the broker trace_id is settable
(with_trace_id) but host.rs does not supply it yet; and a broker-level
resource.exhausted reply keeps its stable code but the host plugin-error
mapping currently collapses PluginError kind capability to the
permission.denied runtime category (changing that mapping is a follow-up).
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, stdio/stdout and stdio/stderr output plus 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. |
| addressable memory | 64 MiB committed total, 16 MiB per region, 64 KiB pages; --max-memory / --max-region-memory override |
Runtime-owned MemoryStore (ADR-0022); create/grow checks both budgets before allocation and failed growth is atomic → resource.exhausted. Memory is pure computation and needs no capability grant in any mode. |
| resource streams | stdin reads over a shared run cursor; stdout/stderr writes charged to the existing output budget; file reads and writer buffers bounded by the 8 MiB per-file limit | Host-owned resource table (ADR-0025/0026/0040); output budget is checked before a stdout/stderr write is buffered; a failed check produces no bytes; writer buffers flush only on close. No separate I/O byte budget yet. |
CLI overrides (run/call): --fuel, --stack, --max-output,
--timeout. Additional fixed limits:
- foreign kernel:
StdHost.foreign_timeout = 10sandforeign_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:
{"op":"print","module":"hello.mq.md","span":{"start":43,"end":57},
"duration_micros":3,"result":"ok"}
opis the stableHostOp::name()(print,math.eval,foreign.call,fs.write,plugin.invoke, ...);moduleis the initiating module id;spanis the call site when known;resultis"ok"or the failure code (for examplepermission.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 atracearray next to separate programstdout/stderrstrings. Program output is always separate from diagnostics/trace, andstdio/stderrnever shares thestdoutbuffer.
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
argvexec (no shell, no interpolation); stdin carries the versioned request envelope; stdout/stderr are always piped and captured; - the environment is cleared except
PATH; - on Unix the child is a process-group leader (
setpgid) and the wall-clock deadline/output overflow kills the whole group, including grandchildren; a 2-second reader grace prevents a surviving pipe holder from hanging the host. Non-Unix targets only kill the direct child; - a non-zero exit is data (
RunStatus::Failed, stderr preserved); a timeout isTimedOutforrunand an error for the typedcall.
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 L1 rejects Foreign execution before any sandbox starts, so foreign
execution is only reachable in project mode with --allow-foreign. L2
inheritance is future work (ADR-0021).
6. Plugins: in-process native trust boundary
- The only plugin transport implemented in this build is in-process native
loading (
libloading) aftermanifest.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:
--plugin <manifest-or-dir>names the plugin;--trust-native-pluginis an explicit unsafe trust decision;- the manifest package name is granted with
--allow-plugin <name>(checked again on every invocation). Without trust,StdHost::load_pluginreturnspermission.deniedwith 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-pluginmust be treated as equivalent to running the plugin's code as the host user. - Every export is registered by its complete dotted name; a plugin may export
several prefixes, and a conflicting name rejects the whole load atomically.
check --plugin <manifest>(orrun/call --plugin) validates export signatures statically without loading a shared library. - Plugin call sites are written as
<export>(...)in a function body (for examplesolver.add(a=20, b=22)). The namespace is derived from the first manifest export prefix. Calls are made throughHostOp::PluginInvokewith a typedwire_version1 request; the plugin's typed response becomes a Marqdo value (Unitwhen absent). Named arguments are required in this build; positional plugin arguments areruntime.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 issymbol.unknown. - The plugin's host-capability requests are denied by default: the CLI loads
plugins with
LoadOptions::default(), i.e. no capability handler, so everyrequest_capabilitycall fails. Therequires:list inplugin.yamlis only a declaration. marqdo plugin inspectnever 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.yamlgrants 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:
checkparses, 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.inspectwith--ast,--units,--signature,--ir,--refsor--platformdoes the same static work and prints metadata.--refsmay read other project source files on demand to resolve link targets, but only parses/analyzes them; nothing is executed or written.plugin inspectreadsplugin.yaml, validates it, resolves the artifact for the host target and computes/compares its sha256. It does notdlopen, instantiate or call the plugin ("loaded": falsein JSON output).run/callfirst perform the same static load; if any diagnostic has error severity, execution is refused before the host or any kernel is touched.fmtonly normalizes line endings/trailing newlines and writes the document when not in--checkmode; it does not execute anything.
8. Open security items
- Strict L1 is implemented and VM-verified on Linux (ADR-0021); strict L2 (Worker/Foreign inheritance) is not implemented, so those surfaces are refused in strict.
consolecapability is not enforced; print is always allowed.- Network capability exists in the model but no host operation uses it; there
is no
--allow-netflag. - Write-path symlink TOCTOU (see §2.1).
- Plugin worker crash isolation and the worker capability bridge are
implemented (not usable in strict L1): both native and worker plugins can
reach the broker's
fs.readhandler when granted (ADR-0057). Onlyfs.readhas a registered handler; every other core capability and every vendor capability without an explicitly registered trusted handler remainscapability.unavailable, and there is no API to register one from a plugin, manifest or CLI flag. Broker execution is a cooperative API contract, not an OS sandbox; a worker and a native plugin can still issue direct syscalls. Follow-ups: wire the runtrace_idinto the broker audit and teach the host plugin-error mapping to reportresource.exhaustedas a resource category rather thanpermission.denied. plugin_handlewire values are structurally reconstructable, but host authority comes only from thePluginHandleTableowner/run/generation check; untrusted plugin/foreign output containing a handle is rejected (ADR-0014,value-wire.md§4.1).- Budgets do not cover all allocation paths (for example list/table growth inside the interpreter is bounded only by fuel and memory).
--jsonrun 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.