diff --git a/crates/cli/src/commands.rs b/crates/cli/src/commands.rs index f87e5fe..277b238 100644 --- a/crates/cli/src/commands.rs +++ b/crates/cli/src/commands.rs @@ -26,6 +26,8 @@ pub struct SandboxSettings { pub allow_net: Vec, /// Environment variable grants (ADR-0043). pub allow_env: Vec, + /// Process program grants (ADR-0044). + pub allow_process: Vec, /// Foreign execution grant. pub allow_foreign: bool, /// Plugin grants. @@ -77,6 +79,7 @@ impl SandboxSettings { || !self.allow_net.is_empty() || !self.allow_write.is_empty() || !self.allow_env.is_empty() + || !self.allow_process.is_empty() || !self.allow_plugin.is_empty() || !self.plugins.is_empty() || self.trust_native_plugin @@ -85,9 +88,9 @@ impl SandboxSettings { if requested { return Err( "strict mode currently supports pure Marqdo and native Math only; \ - --allow-read/--allow-write/--allow-env/--allow-foreign/--allow-plugin/\ - --plugin/--trust-native-plugin/--kernel/--trace-file are rejected. Use \ - --mode project for those capabilities." + --allow-read/--allow-write/--allow-env/--allow-process/--allow-foreign/\ + --allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file are + rejected. Use --mode project for those capabilities." .to_string(), ); } @@ -103,6 +106,7 @@ impl SandboxSettings { || !self.allow_net.is_empty() || !self.allow_write.is_empty() || !self.allow_env.is_empty() + || !self.allow_process.is_empty() || self.allow_foreign || !self.allow_plugin.is_empty() { @@ -126,6 +130,9 @@ impl SandboxSettings { for name in &self.allow_env { capabilities = capabilities.allow_env(name.clone()); } + for program in &self.allow_process { + capabilities = capabilities.allow_process(program.clone()); + } if self.allow_foreign { capabilities = capabilities.allow_foreign(); } diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 93f51f2..a7f377c 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -95,6 +95,9 @@ struct SandboxArgs { /// Grant read access to an environment variable (repeatable, ADR-0043). #[arg(long = "allow-env", value_name = "NAME")] allow_env: Vec, + /// Grant execution of an exact program path (repeatable, ADR-0044). + #[arg(long = "allow-process", value_name = "PROGRAM")] + allow_process: Vec, /// Grant explicit foreign kernel execution. #[arg(long = "allow-foreign")] allow_foreign: bool, @@ -147,6 +150,7 @@ impl SandboxArgs { allow_net: self.allow_net.clone(), allow_write: self.allow_write.clone(), allow_env: self.allow_env.clone(), + allow_process: self.allow_process.clone(), allow_foreign: self.allow_foreign, allow_plugin: self.allow_plugin.clone(), fuel: self.fuel, diff --git a/crates/cli/tests/stdlib_product.rs b/crates/cli/tests/stdlib_product.rs index 5233972..2129364 100644 --- a/crates/cli/tests/stdlib_product.rs +++ b/crates/cli/tests/stdlib_product.rs @@ -81,6 +81,8 @@ fn product_tests() -> Vec { "--allow-env", "MARQDO_MISSING_ENV", ][..] + } else if name == "process.mq.md" { + &["--allow-process", "/bin/echo"][..] } else { &[][..] }; @@ -155,6 +157,7 @@ fn every_public_stdlib_module_has_a_product_test() { "io.mq.md", "json.mq.md", "path.mq.md", + "process.mq.md", "regex.mq.md", "stream.mq.md", "table.mq.md", @@ -344,6 +347,21 @@ fn env_test_reads_only_granted_names() { assert_eq!(items[5]["value"], "env.not_found"); } +#[test] +fn process_test_runs_an_explicitly_granted_program() { + let report = run_product_test( + product_tests() + .iter() + .find(|file| file.name == "process.mq.md") + .expect("process test"), + ); + let items = report["value"]["items"].as_array().expect("list"); + assert_eq!(items[0]["value"], true); + assert_eq!(items[1]["decimal"], "0"); + assert_eq!(items[2]["value"], "hello\n"); + assert_eq!(items[3]["value"], ""); +} + #[test] fn format_test_pins_value_semantics_and_handle_observation() { let report = run_product_test( diff --git a/crates/marqdo-host/src/capability.rs b/crates/marqdo-host/src/capability.rs index a301508..02ab94b 100644 --- a/crates/marqdo-host/src/capability.rs +++ b/crates/marqdo-host/src/capability.rs @@ -319,6 +319,8 @@ pub struct Capabilities { pub net_hosts: Vec, /// Allowed environment variable names (empty = no environment). pub env: Vec, + /// Allowed process program paths (empty = no process execution). + pub process_programs: Vec, /// May spawn processes (foreign kernels). pub process: bool, /// May run foreign kernels (Python/Node). @@ -339,6 +341,7 @@ impl Capabilities { fs_write: Vec::new(), net_hosts: Vec::new(), env: Vec::new(), + process_programs: Vec::new(), process: false, foreign: false, plugins: Vec::new(), @@ -383,6 +386,29 @@ impl Capabilities { } } + /// Grant execution of one exact program path (ADR-0044). + pub fn allow_process(mut self, program: impl Into) -> Self { + self.process_programs.push(program.into()); + self + } + + /// Check an exact process-program grant. + pub fn check_process(&self, program: &str, span: Option) -> Result<(), RuntimeError> { + if self + .process_programs + .iter() + .any(|allowed| allowed == program) + { + Ok(()) + } else { + Err(denied( + span, + format!("process `{program}` was not granted"), + format!("grant it with --allow-process {program}"), + )) + } + } + /// Grant foreign kernel execution. pub fn allow_foreign(mut self) -> Self { self.foreign = true; diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index bf36b35..e226e54 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -6,6 +6,7 @@ use std::collections::{BTreeMap, BTreeSet}; use std::net::{SocketAddr, TcpStream}; +use std::process::{Command, Stdio}; use std::sync::{Arc, Mutex}; use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; @@ -943,6 +944,121 @@ impl StdHost { } } +fn process_error(code: &str, message: &str) -> Value { + let mut map = BTreeMap::new(); + map.insert("ok".to_string(), Value::Bool(false)); + map.insert("code".to_string(), Value::text(code)); + map.insert("message".to_string(), Value::text(message)); + Value::Map(map) +} + +fn run_process( + root: &std::path::Path, + program: &str, + args: &[String], + ctx: &ExecutionContext, +) -> Result { + const LIMIT: usize = 1024 * 1024; + let child = Command::new(program) + .args(args) + .current_dir(root) + .env_clear() + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn(); + let child = match child { + Ok(child) => child, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Ok(process_error( + "process.not_found", + &format!("program `{program}` was not found"), + )) + } + Err(error) if error.kind() == std::io::ErrorKind::PermissionDenied => { + return Err(RuntimeError::new( + ErrorCategory::PermissionDenied, + ctx.span, + format!("cannot execute `{program}`: {error}"), + )) + } + Err(error) => { + return Err(RuntimeError::new( + ErrorCategory::HostError, + ctx.span, + format!("cannot start `{program}`: {error}"), + )) + } + }; + let mut child = child; + let deadline = Instant::now() + Duration::from_secs(5); + let mut timed_out = false; + loop { + match child.try_wait() { + Ok(Some(_)) => break, + Ok(None) if Instant::now() < deadline => { + std::thread::sleep(Duration::from_millis(10)); + } + Ok(None) => { + timed_out = true; + let _ = child.kill(); + break; + } + Err(error) => { + return Err(RuntimeError::new( + ErrorCategory::HostError, + ctx.span, + format!("cannot wait for `{program}`: {error}"), + )) + } + } + } + let output = child.wait_with_output().map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + ctx.span, + format!("cannot collect `{program}` output: {error}"), + ) + })?; + if timed_out { + return Ok(process_error( + "process.timeout", + &format!("program `{program}` exceeded the 5 second limit"), + )); + } + if output.stdout.len() > LIMIT || output.stderr.len() > LIMIT { + return Ok(process_error( + "process.output_too_large", + &format!("program `{program}` exceeded the {LIMIT} byte output limit"), + )); + } + let stdout = String::from_utf8(output.stdout).map_err(|_| { + RuntimeError::new( + ErrorCategory::Type, + ctx.span, + format!("program `{program}` stdout is not valid UTF-8"), + ) + })?; + let stderr = String::from_utf8(output.stderr).map_err(|_| { + RuntimeError::new( + ErrorCategory::Type, + ctx.span, + format!("program `{program}` stderr is not valid UTF-8"), + ) + })?; + let mut value = BTreeMap::new(); + value.insert( + "status".to_string(), + Value::int(output.status.code().unwrap_or(-1) as i64), + ); + value.insert("stdout".to_string(), Value::text(stdout)); + value.insert("stderr".to_string(), Value::text(stderr)); + let mut map = BTreeMap::new(); + map.insert("ok".to_string(), Value::Bool(true)); + map.insert("value".to_string(), Value::Map(value)); + Ok(Value::Map(map)) +} + impl Host for StdHost { fn invoke( &mut self, @@ -1127,6 +1243,58 @@ impl Host for StdHost { "resource operations accept only Text path arguments", )); } + if operation == "process.run" { + if args.len() != 2 { + return Err(RuntimeError::new( + ErrorCategory::Arity, + ctx.span, + format!( + "resource operation `process.run` expects 2 arguments, got {}", + args.len() + ), + )); + } + let program_type = args[0].type_name(); + let Value::Text(program) = args[0].clone() else { + return Err(RuntimeError::type_error( + ctx.span, + format!( + "resource operation `process.run` expects a Text program, got {program_type}" + ), + )); + }; + let args_type = args[1].type_name(); + let Value::List(values) = args[1].clone() else { + return Err(RuntimeError::type_error( + ctx.span, + format!( + "resource operation `process.run` expects a List of Text arguments, got {args_type}" + ), + )); + }; + let mut program_args = Vec::with_capacity(values.len()); + for value in values { + let value_type = value.type_name(); + let Value::Text(value) = value else { + return Err(RuntimeError::type_error( + ctx.span, + format!("process arguments must be Text, got {value_type}"), + )); + }; + program_args.push(value); + } + self.capabilities.check_process(&program, ctx.span)?; + let result = run_process(self.fs.root(), &program, &program_args, ctx)?; + self.record_semantic( + "resource.request", + None, + Some(&ctx.module_id), + ctx.span, + Some("op=process.run"), + ); + self.record_resource_effect("resource.request", ctx, started, "process.run"); + return Ok(result); + } if operation == "env.get" { if args.len() != 1 { return Err(RuntimeError::new( diff --git a/crates/marqdo-host/tests/resource_streams.rs b/crates/marqdo-host/tests/resource_streams.rs index c5c3e51..3778034 100644 --- a/crates/marqdo-host/tests/resource_streams.rs +++ b/crates/marqdo-host/tests/resource_streams.rs @@ -682,3 +682,65 @@ fn env_get_requires_an_exact_grant_and_reports_missing_names() { .unwrap_err(); assert_eq!(error.category, ErrorCategory::Arity); } + +#[cfg(unix)] +#[test] +fn process_run_requires_an_exact_program_grant() { + let dir = tempfile::tempdir().unwrap(); + let ctx = context(); + let mut denied = StdHost::new(SandboxMode::Project, Capabilities::project(), dir.path()); + let error = denied + .resource_request( + "process.run", + vec![ + Value::text("/bin/echo"), + Value::List(vec![Value::text("x")]), + ], + &ctx, + ) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::PermissionDenied); + + let mut pure = StdHost::new(SandboxMode::Pure, Capabilities::pure(), dir.path()); + let error = pure + .resource_request( + "process.run", + vec![ + Value::text("/bin/echo"), + Value::List(vec![Value::text("x")]), + ], + &ctx, + ) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::PermissionDenied); + + let capabilities = Capabilities::project().allow_process("/bin/echo"); + let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path()); + let result = host + .resource_request( + "process.run", + vec![ + Value::text("/bin/echo"), + Value::List(vec![Value::text("hello")]), + ], + &ctx, + ) + .unwrap(); + assert_eq!(field(&result, "ok"), &Value::Bool(true)); + let value = field(&result, "value"); + assert_eq!(field(value, "status"), &Value::int(0)); + assert_eq!(field(value, "stdout"), &Value::text("hello\n")); + assert_eq!(field(value, "stderr"), &Value::text("")); + + let missing = host + .resource_request( + "process.run", + vec![ + Value::text("/bin/definitely-not-a-program"), + Value::List(Vec::new()), + ], + &ctx, + ) + .unwrap_err(); + assert_eq!(missing.category, ErrorCategory::PermissionDenied); +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 7ee4258..7d9a354 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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: diff --git a/docs/adr/0044-process-resource-operation.md b/docs/adr/0044-process-resource-operation.md new file mode 100644 index 0000000..9cbc4f6 --- /dev/null +++ b/docs/adr/0044-process-resource-operation.md @@ -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` 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. diff --git a/docs/architecture/CURRENT.md b/docs/architecture/CURRENT.md index e55061d..02d853c 100644 --- a/docs/architecture/CURRENT.md +++ b/docs/architecture/CURRENT.md @@ -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. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 6654f19..0981bdb 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -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 diff --git a/docs/evidence/2026-11-21-process-product.md b/docs/evidence/2026-11-21-process-product.md new file mode 100644 index 0000000..fcabae3 --- /dev/null +++ b/docs/evidence/2026-11-21-process-product.md @@ -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. diff --git a/spec/evaluation.md b/spec/evaluation.md index 14135e9..6b7fe1e 100644 --- a/spec/evaluation.md +++ b/spec/evaluation.md @@ -207,6 +207,7 @@ resource.request("fs.remove", [path]) -> {ok:true, value:None} resource.request("fs.rename", [from, to]) -> {ok:true, value:None} resource.request("clock.now", []) -> {ok:true, value:UnixMillis} resource.request("env.get", [name]) -> {ok:true, value:Text} +resource.request("process.run", [program, args])-> {ok:true, value:{status, stdout, stderr}} ``` * Arguments are `Text` paths only. `Memory`/`Resource` values are rejected. @@ -231,6 +232,11 @@ resource.request("env.get", [name]) -> {ok:true, value:Text} * `env.get` takes one exact variable name and requires an `--allow-env NAME` grant; un-granted names are `permission.denied`, missing names are recoverable `env.not_found` and non-UTF-8 values are `env.not_unicode` (ADR-0043). +* `process.run` takes an exact program path and a List of Text arguments, + requires an `--allow-process PROGRAM` grant, runs without a shell with a + cleared environment in the project root, and enforces a 5 second timeout and + 1 MiB stdout/stderr caps. It is project-mode only and is **not** an OS + sandbox (ADR-0044). ## 4. Errors @@ -326,7 +332,7 @@ host boundary. Names are stable; adding one requires a spec update. | `resource.read` | `(handle, memory: Memory, offset: Int, max_bytes: Int) -> Result` | bounded chunk read into Memory; `{count,eof}` | | `resource.write` | `(handle, memory: Memory, offset: Int, length: Int) -> Result` | bounded byte write; `{count}` | | `resource.close` | `(handle) -> Result` | releases the host slot | -| `resource.request` | `(operation: Text, arguments: List) -> Result` | non-streaming `fs.*` operations (ADR-0041) `clock.now` (ADR-0042) and `env.get` (ADR-0043); project-mode and grant-checked | +| `resource.request` | `(operation: Text, arguments: List) -> Result` | non-streaming `fs.*` operations (ADR-0041) `clock.now` (ADR-0042), `env.get` (ADR-0043) and `process.run` (ADR-0044); project-mode and grant-checked | | `math.parse/eval/substitute` | see `spec/math.md` | P5; `math.simplify`/`math.differentiate` are declared but return `math.unsupported` in this build | | `foreign.run/call` | see `spec/foreign.md` | P5, capability-gated | | `fs.read/write` | see `spec/security.md` | capability-gated | diff --git a/spec/security.md b/spec/security.md index d09c936..2e8d233 100644 --- a/spec/security.md +++ b/spec/security.md @@ -27,8 +27,8 @@ Normative implementation: | 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-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 IP-literal TCP streams (ADR-0034); 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-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. | +| `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-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 IP-literal TCP streams (ADR-0034); 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-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 --platform` prints the detection report, for example: @@ -61,6 +61,7 @@ set for one run: | `fs_write: Vec` | empty | `fs.write` and project `resource.open("file", path, ["write"])` | | `net_hosts: Vec` | empty | exact IP-literal grants for `resource.open("tcp", ":", ["read","write"])`; DNS is not resolved; `--allow-net ` adds a grant (ADR-0034) | | `env: Vec` | empty | exact-name grants for `resource.request("env.get", [name])`; no glob and no `env.list`; `--allow-env ` adds a grant (ADR-0043) | +| `process_programs: Vec` | 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 ` adds a grant (ADR-0044); not an OS sandbox | | `process: bool` | `false` | required together with `foreign` for `foreign.run`/`foreign.call` | | `foreign: bool` | `false` | foreign kernels | | `plugins: Vec` | empty | `plugin.invoke` and `StdHost::load_plugin` | @@ -81,6 +82,8 @@ Requests versus grants: ADR-0034); * `--allow-env ` (repeatable, exact environment variable name, project mode only, ADR-0043); + * `--allow-process ` (repeatable, exact program path, project mode + only, ADR-0044; the child is not sandboxed); * `--allow-foreign` (project mode only; sets `foreign = true` and `process = true`); * `--allow-plugin ` (repeatable, project mode only; matches the @@ -125,6 +128,8 @@ before reading. Full symlink/race hardening is an open P4 item. * `resource.request("fs.*")` → `check_read`/`check_write` before path resolution; * `resource.request("env.get")` → `capabilities.check_env(name)` before `std::env::var`; +* `resource.request("process.run")` → `capabilities.check_process(program)` + before `Command::spawn`; * `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`); diff --git a/stdlib/README.md b/stdlib/README.md index f7c312b..12db1e8 100644 --- a/stdlib/README.md +++ b/stdlib/README.md @@ -16,6 +16,7 @@ module; a mismatch is a hard error. - `data/csv.mq.md` — quoted single-row CSV parser and formatter - `data/table.mq.md` — value-returning table select/filter/sort/append/set/join/group/GFM - `env.mq.md` — explicitly granted `env.get` names over `resource.request` +- `process.mq.md` — explicitly granted `process.run` with timeout/output caps - `datetime.mq.md` — UTC ISO-8601 format/parse over Unix milliseconds (pure) - `clock.mq.md` — project-mode `clock.now` over `resource.request` - `path.mq.md` — lexical join/basename/dirname/extension/normalize (no I/O) diff --git a/stdlib/process.mq.md b/stdlib/process.mq.md new file mode 100644 index 0000000..a542d81 --- /dev/null +++ b/stdlib/process.mq.md @@ -0,0 +1,10 @@ +## 运行 + +`(程序, 参数列表)` + +在项目模式下运行一个显式授权的可执行文件。程序路径必须与 +`--allow-process PROGRAM` 精确匹配;不经过 shell,清空环境变量, +工作目录是项目根,stdin 为空。5 秒超时、1 MiB stdout/stderr 上限, +结果形状为 `{status, stdout, stderr}`。 + +*resource.request("process.run", [程序, 参数列表])* diff --git a/stdlib/stdlib.json b/stdlib/stdlib.json index c85cdf9..f35d663 100644 --- a/stdlib/stdlib.json +++ b/stdlib/stdlib.json @@ -1,5 +1,5 @@ { "name": "marqdo-stdlib", "version": "0.1.0", - "digest": "sha256:9ec0ba1a50db6bd8423ce3485ad5433fb3b8140032f61c6b4a6dd9bc97416f47" + "digest": "sha256:c7208520e3eef1fdc98327055092f9d52081851f652dd970d4f602e30e58e75f" } diff --git a/stdlib/tests/process.mq.md b/stdlib/tests/process.mq.md new file mode 100644 index 0000000..674fa32 --- /dev/null +++ b/stdlib/tests/process.mq.md @@ -0,0 +1,10 @@ +--- +import: + process: "std:process" +--- + +## main + +**结果 = process.运行("/bin/echo", ["hello"])** + +*[结果.ok, 结果.value.status, 结果.value.stdout, 结果.value.stderr]*