feat(process): add explicitly granted process API

This commit is contained in:
Marqdo Agent committed 2026-11-21 08:46:02 +08:00
1 parent 9922bfae98
commit 3ef18fb496
17 files changed
+433 -15

No files matched your search

+8 -6
View File
@@ -58,7 +58,7 @@ byte-identical).
cargo fmt --all -- --check PASS
cargo clippy --workspace --all-targets -- -D warnings PASS
cargo test --workspace --locked PASS
476 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
478 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
```
The documentation and test migration is local work; re-run this block after it
@@ -204,11 +204,13 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
provide recursive JSON and quoted single-row CSV product parsers; `path` and a
`regex` subset are pure `.mq.md`; `datetime` is pure UTC ISO-8601 and
`clock.现在` reads `clock.now` in project mode (ADR-0042); `env.读取` reads
only exact `--allow-env NAME` grants in project mode (ADR-0043). Append/seek/
watch, recursive walk, streaming JSON/CSV, a JSON depth bound, regex groups/
alternation and `process` remain open.
only exact `--allow-env NAME` grants in project mode (ADR-0043); `process.运行`
runs an exact `--allow-process PROGRAM` grant with 5 s timeout and 1 MiB caps
(ADR-0044, not an OS sandbox). Append/seek/watch, recursive walk, streaming
JSON/CSV, a JSON depth bound, regex groups/alternation, secure random and
compression remain open.
- Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships
`format`/`text`/`io`/`fs`/`data`/`path`/`regex`/`datetime`/`clock`/`env`; explicit `std:` imports resolve only inside the bundle;
`format`/`text`/`io`/`fs`/`data`/`path`/`regex`/`datetime`/`clock`/`env`/`process`; explicit `std:` imports resolve only inside the bundle;
a SHA-256 digest over `*.mq.md` is verified before loading; Analysis records
`project.stdlib`; a frozen-binary test asserts the CLI hash is unchanged after
running a `std:io` project and that tampering is rejected. `打印/print` is
@@ -234,7 +236,7 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
status/index links and SHA-pinned evidence; `crates/cli/tests/architecture_boundaries.rs`
pins the workspace graph, `marqdo-runtime -> marqdo-host`, the bundled stdlib
digest and the stdio/file/TCP endpoints; `crates/cli/tests/stdlib_product.rs`
runs every public stdlib module (`clock/console/csv/datetime/demo/env/format/fs/http/io/json/path/regex/stream/table/text/utf8`)
runs every public stdlib module (`clock/console/csv/datetime/demo/env/format/fs/http/io/json/path/process/regex/stream/table/text/utf8`)
through `std:` imports over `stdlib/tests/*.mq.md`. `tools/pack-stdlib.py`
now sorts `.mq.md` by the same relative path key as the CLI. Source/test baseline
`0d40de7`; later docs-only commits keep code/test bytes identical. Evidence:
@@ -0,0 +1,52 @@
# ADR-0044: Explicitly granted `process.run` resource operation
Status: **Accepted**
Date: 2026-11-21
Relates to: ADR-0041, ADR-0042, ADR-0043
Specs: `spec/security.md`, `spec/evaluation.md`
Evidence: `docs/evidence/2026-11-21-process-product.md`
## Context
The audit RFC lists a `std:process` product module. Spawning a process is the
most privileged OS operation in the runtime and is **not** contained by the
in-process host checks. Without an explicit contract it would silently turn
the CLI into an unrestricted command runner.
## Decision
Add a project-mode-only `resource.request` operation:
```text
resource.request("process.run", [program, args]) -> {ok:true, value:{status, stdout, stderr}}
| {ok:false, code:"process.not_found"}
| {ok:false, code:"process.timeout"}
| {ok:false, code:"process.output_too_large"}
```
* `program` is an exact Text path; `args` is a List of Text values. Wrong
arity/types are fatal. There is no shell expansion, no glob and no implicit
`PATH` lookup.
* A new exact `Capabilities::process_programs: Vec<String>` grant is required
(`--allow-process PROGRAM`). Un-granted programs return
`permission.denied` before spawning.
* The child runs with `env_clear`, stdin `null`, the project root as its
working directory, and a 5 second wall-clock limit. On timeout it is killed
and the call returns recoverable `process.timeout`.
* `stdout`/`stderr` are captured separately, require valid UTF-8 (otherwise
fatal type error), and are capped at 1 MiB each; exceeding the cap is
recoverable `process.output_too_large`.
* `pure`/`strict` refuse the operation. This does **not** make the child an OS
sandbox: the in-process host check is cooperative and the child inherits the
CLI user's OS privileges.
* `stdlib/process.mq.md` is a thin `.mq.md` facade; no Rust builtin or
`HostOp` is added.
## Consequences
* Process execution is opt-in per exact program path and remains project-mode
only.
* The operation is not a sandbox. A future strict-mode process provider needs
OS isolation evidence and a separate ADR.
* `--allow-process` is rejected by strict preflight, like the other external
grants.
+4 -2
View File
@@ -18,7 +18,7 @@ platform".
| Dimension | Current state | Source |
|---|---|---|
| Implemented | Rust workspace `0.1.0`: Markdown/frontend/IR, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` |
| Tested locally | `cargo test --workspace --locked`: **476 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 |
| Tested locally | `cargo test --workspace --locked`: **478 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 |
| Bundled stdlib released | In-repo bundle `marqdo-stdlib@0.1.0`, SHA-256 digest verified before loading; it is **not** an external registry package | `stdlib/stdlib.json`, `stdlib/README.md` |
| Multi-platform verified | Linux local gate is the only executed lane here; Windows/macOS native lanes are **UNVERIFIED**, and the GitHub security lane remains a **VM-only** gate | `docs/STATUS.md` §1, §4 |
@@ -95,6 +95,7 @@ review RFC, not a new crate per provider.
| `std:datetime` | `datetime.格式化(毫秒)` / `datetime.解析(文本)`; UTC ISO-8601, pre-1970 supported | implemented (pure) | `stdlib_product` |
| `std:clock` | `clock.现在()` -> `resource.request("clock.now", [])` | implemented (project mode; pure/strict denied) | `resource_streams`, `stdlib_product` |
| `std:env` | `env.读取/存在` -> `resource.request("env.get", [name])`; exact `--allow-env` grant | implemented (project mode; no `env.list`) | `resource_streams`, `stdlib_product` |
| `std:process` | `process.运行(程序, 参数列表)` -> `resource.request("process.run", ...)`; exact `--allow-process` grant, 5 s timeout, 1 MiB caps | implemented (project mode; not an OS sandbox) | `resource_streams`, `stdlib_product` |
| file metadata / directory / rename / remove / mkdir | not part of the current Resource contract | **not implemented**; needs a separate Resource Operation ADR | — |
| TCP | `resource.open("tcp", ip:port, ["read","write"])`; exact IP grant, 5 s timeout | implemented; no DNS/TLS/server socket/UDP | `tcp_endpoint`, `http_over_tcp` |
| HTTP/1.1 | `stdlib/net/http.mq.md`: status/header/chunked-byte parse, request build | implemented over an already-authorized TCP stream; not a DNS/TLS client | `stdlib_http`, `http_over_tcp`, `stdlib_product` |
@@ -126,7 +127,7 @@ that a phase is complete.
| P1 | `crates/cli/src/commands.rs` and `crates/marqdo-host/src/host.rs` still mix multiple responsibilities | open refactor, behavior-preserving |
| P2 | HTTP parsing is Unicode-codepoint oriented; a general byte body is not the only path | open; convert before a general network release |
| P2 | No DNS, TLS, listener or UDP provider | open |
| P2 | `std:path`, a regex subset, `std:datetime`, `std:clock` and `std:env` are implemented; no `std:process`, secure random or compression | open |
| P2 | `std:path`, a regex subset, `std:datetime`, `std:clock`, `std:env` and `std:process` are implemented; no secure random or compression | open |
| P2 | Memory limits: 16 MiB per region, 64 MiB per run | current budget, not a product limit |
| P3 | No concurrency tasks, atomics or cancellable long-running scheduling | open; separate ADR |
| P3 | No native optimizer/JIT or columnar numeric backend | open; benchmark-first |
@@ -159,5 +160,6 @@ that a phase is complete.
- [ADR-0041: non-streaming resource operations](../adr/0041-resource-operation-fs.md) — accepted `resource.request` `fs.*` contract.
- [ADR-0042: `clock.now` resource operation](../adr/0042-clock-resource-operation.md) — accepted project-mode Unix-millis clock.
- [ADR-0043: `env.get` resource operation](../adr/0043-env-resource-operation.md) — accepted exact-name environment grants.
- [ADR-0044: `process.run` resource operation](../adr/0044-process-resource-operation.md) — accepted exact-path process grant; not a sandbox.
- [Compute-machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) and [core/stdlib RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) — design input.
- [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) — review input for this migration.
+1
View File
@@ -48,6 +48,7 @@ The implemented first slices of these RFCs are recorded in `CURRENT.md` and
| Non-streaming `resource.request` `fs.*` operations | [0041](../adr/0041-resource-operation-fs.md) | Accepted (project mode, grant-checked, recoverable fs Result) |
| `clock.now` resource operation | [0042](../adr/0042-clock-resource-operation.md) | Accepted (project mode, Unix millis) |
| `env.get` resource operation | [0043](../adr/0043-env-resource-operation.md) | Accepted (exact-name project grant) |
| `process.run` resource operation | [0044](../adr/0044-process-resource-operation.md) | Accepted (exact program grant, project only, not a sandbox) |
| Table physical storage (T1/T2/T3), strict stdin/stderr/file/network resources | — | **Not decided**; do not implement by implication |
## Evidence and status
@@ -0,0 +1,44 @@
# Evidence: `std:process` and the `process.run` grant
Date: 2026-11-21 (Asia/Shanghai)
Source baseline: `9922bfae98d72f7dbad26f802fd3cc9478272b8e`
Repository: `marqdo-cli`
Decision record: [ADR-0044](../adr/0044-process-resource-operation.md)
RFC item: P2 process product API
## Implemented
`resource.request("process.run", [program, args])` is project-mode only:
- exact Text program path and List-of-Text arguments; no shell/PATH/glob;
- exact `--allow-process PROGRAM` grant checked before spawn;
- child has `env_clear`, stdin null, project-root cwd, 5 s timeout (kill) and
separate 1 MiB stdout/stderr caps;
- recoverable `process.not_found`, `process.timeout`,
`process.output_too_large`; un-granted programs are `permission.denied`;
non-UTF-8 output is a fatal type error.
`stdlib/process.mq.md` is a thin `.mq.md` facade: `运行(程序, 参数列表)`.
The child is **not** an OS sandbox and inherits the CLI user's privileges.
## Tests
`stdlib/tests/process.mq.md` runs `/bin/echo hello` with
`--allow-process /bin/echo`. `crates/marqdo-host/tests/resource_streams.rs`
pins grant denial, pure-mode refusal, exit status/stdout/stderr and the
missing-program grant check.
```text
cargo fmt --all -- --check PASS
cargo clippy --workspace --all-targets -- -D warnings PASS
cargo test --workspace 478 passed, 0 failed, 2 ignored
cargo test -p marqdo-host --test resource_streams 23 passed
cargo test -p marqdo-cli --test stdlib_product 14 passed
python3 tools/pack-stdlib.py PASS
```
## Not covered
Not a sandbox; no strict-mode process provider, no stdin, no shell operators,
no environment selection, no per-run user/namespace isolation, no output
streaming. A sandboxed process provider needs its own ADR and OS evidence.