feat(m0.6-r3): generic external CLI Tool Protocol v1

- add tool install/list/remove and unknown-command dispatch without hardcoded
  tool names or clap variants
- validate and copy local tool packages atomically, reject entrypoint escapes
  and symlinks, record and re-verify SHA-256
- forward OsString args, stdio, cwd and exit status without a shell; never
  execute PATH programs implicitly
- add black-box tests for arbitrary names, Unicode args, built-in conflicts,
  traversal, version mismatch, tampering and PATH hijacking
- add ADR-0013 and mark R3 complete
This commit is contained in:
cflmy committed 2026-11-20 11:44:20 +08:00
1 parent 7797d78d86
commit 25a1faa6ef
7 files changed
+859 -3

No files matched your search

+1 -1
View File
@@ -179,7 +179,7 @@ tests/ conformance/negative corpus (see tests/README.md)
* [`docs/adr/`](docs/adr/) — accepted decisions (crate graph, inert executables,
`ref` ambiguity, strict refusal, AST normalization, CLI contract, BigInt/wire,
package identity, callable resolution, plugin export routing, capability
broker, kernel providers).
broker, kernel providers, generic CLI tools, plugin-handle authority).
* Specs: [`markdown-profile.md`](spec/markdown-profile.md),
[`mapping.md`](spec/mapping.md), [`expression.ebnf`](spec/expression.ebnf),
[`evaluation.md`](spec/evaluation.md), [`references.md`](spec/references.md),
+54
View File
@@ -8,7 +8,9 @@ mod args;
mod commands;
mod loader;
mod output;
mod tool;
use std::ffi::OsString;
use std::path::PathBuf;
use clap::{Args, Parser, Subcommand};
@@ -49,6 +51,11 @@ enum Command {
Lock(LockArgs),
/// Verify that path dependencies match the lockfile.
Sync(SyncArgs),
/// Manage and dispatch generic external CLI tools.
Tool(ToolArgs),
/// Unknown top-level command: dispatch to a registered external tool.
#[command(external_subcommand)]
External(Vec<OsString>),
}
#[derive(Args)]
@@ -251,6 +258,47 @@ struct LockArgs {
json: bool,
}
#[derive(Args)]
struct ToolArgs {
#[command(subcommand)]
command: ToolCommand,
}
#[derive(Subcommand)]
enum ToolCommand {
/// Install a tool from a local tool.json (or its directory).
Install(ToolInstallArgs),
/// List installed external tools.
List(ToolListArgs),
/// Remove an installed external tool.
Remove(ToolRemoveArgs),
}
#[derive(Args)]
struct ToolInstallArgs {
/// Path to tool.json or the tool package directory.
manifest: PathBuf,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
#[derive(Args)]
struct ToolListArgs {
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
#[derive(Args)]
struct ToolRemoveArgs {
/// Tool command to remove.
command: String,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
#[derive(Args)]
struct SyncArgs {
/// Fail instead of silently updating when the lockfile is stale.
@@ -315,6 +363,12 @@ fn main() {
Command::Remove(args) => commands::remove(&args.name, args.json),
Command::Lock(args) => commands::lock(args.json),
Command::Sync(args) => commands::sync(args.locked, args.json),
Command::Tool(args) => match args.command {
ToolCommand::Install(args) => tool::install(&args.manifest, args.json),
ToolCommand::List(args) => tool::list(args.json),
ToolCommand::Remove(args) => tool::remove(&args.command, args.json),
},
Command::External(args) => tool::dispatch(&args),
};
std::process::exit(code);
}
+543
View File
@@ -0,0 +1,543 @@
//! Generic external CLI tool protocol (spec/tool-v1.md).
//!
//! The core never knows a tool's name. It validates a user-supplied
//! `tool.json`, copies the package into a controlled user directory, and
//! dispatches unknown top-level commands to the registered executable. This is
//! deliberately separate from C ABI plugins and foreign kernels.
use std::collections::BTreeMap;
use std::ffi::OsString;
use std::path::{Component, Path, PathBuf};
use std::process::Command as ProcessCommand;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
const SCHEMA: &str = "marqdo.cli-tool";
const PROTOCOL_VERSION: u32 = 1;
const BUILTIN_COMMANDS: &[&str] = &[
"init", "run", "call", "check", "inspect", "fmt", "plugin", "add", "remove", "lock", "sync",
"tool", "help",
];
#[derive(Debug, Clone, Deserialize)]
struct ToolManifest {
schema: String,
schema_version: u32,
name: String,
version: String,
command: String,
entrypoint: PathBuf,
#[serde(default)]
compatibility: Compatibility,
}
#[derive(Debug, Clone, Default, Deserialize)]
struct Compatibility {
#[serde(default)]
marqdo: Option<String>,
#[serde(default)]
analysis: Option<Vec<u32>>,
#[serde(default)]
trace: Option<Vec<u32>>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
struct ToolRecord {
command: String,
name: String,
version: String,
entrypoint: PathBuf,
sha256: String,
source: String,
schema_version: u32,
#[serde(default)]
compatibility: RecordedCompatibility,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
struct RecordedCompatibility {
#[serde(default, skip_serializing_if = "Option::is_none")]
marqdo: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
analysis: Option<Vec<u32>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
trace: Option<Vec<u32>>,
}
/// `marqdo tool install <manifest-or-directory>`.
pub fn install(manifest_path: &Path, json: bool) -> i32 {
match install_inner(manifest_path) {
Ok(record) => {
if json {
println!(
"{}",
serde_json::json!({
"command": "tool.install",
"success": true,
"tool": record.command,
"version": record.version,
})
);
} else {
println!(
"installed tool `{}` version {} ({})",
record.command, record.version, record.name
);
}
0
}
Err(error) => {
if json {
println!(
"{}",
serde_json::json!({"command":"tool.install","success":false,"error":error})
);
} else {
eprintln!("error: {error}");
}
1
}
}
}
fn install_inner(manifest_path: &Path) -> Result<ToolRecord, String> {
let manifest_file = if manifest_path.is_dir() {
manifest_path.join("tool.json")
} else {
manifest_path.to_path_buf()
};
let package_dir = manifest_file
.parent()
.ok_or_else(|| "manifest has no parent directory".to_string())?
.canonicalize()
.map_err(|error| format!("cannot open `{}`: {error}", manifest_file.display()))?;
let manifest = ToolManifest::from_path(&manifest_file)?;
validate_manifest(&manifest)?;
let entrypoint = safe_entrypoint(&package_dir, &manifest.entrypoint)?;
let sha256 = hash_file(&entrypoint)?;
let home = tool_home()?;
std::fs::create_dir_all(&home)
.map_err(|error| format!("cannot create tool home `{}`: {error}", home.display()))?;
let target = home.join(&manifest.command);
if target.exists() {
return Err(format!(
"tool command `{}` is already installed; remove it first",
manifest.command
));
}
let staging = home.join(format!(
".staging-{}-{}",
std::process::id(),
unique_suffix()
));
if staging.exists() {
let _ = std::fs::remove_dir_all(&staging);
}
std::fs::create_dir_all(&staging)
.map_err(|error| format!("cannot create staging directory: {error}"))?;
let result = (|| -> Result<(), String> {
copy_package(&package_dir, &staging)?;
let relative = manifest.entrypoint.clone();
let record = ToolRecord {
command: manifest.command.clone(),
name: manifest.name.clone(),
version: manifest.version.clone(),
entrypoint: relative.clone(),
sha256: sha256.clone(),
source: manifest_file.display().to_string(),
schema_version: PROTOCOL_VERSION,
compatibility: RecordedCompatibility {
marqdo: manifest.compatibility.marqdo.clone(),
analysis: manifest.compatibility.analysis.clone(),
trace: manifest.compatibility.trace.clone(),
},
};
let record_path = staging.join("record.json");
let record_json = serde_json::to_string_pretty(&record)
.map_err(|error| format!("cannot serialize record: {error}"))?;
std::fs::write(&record_path, record_json)
.map_err(|error| format!("cannot write record: {error}"))?;
// Re-verify the copied entrypoint before publishing.
let copied = staging.join(&relative);
if hash_file(&copied)? != sha256 {
return Err("copied tool entrypoint hash mismatch".to_string());
}
std::fs::rename(&staging, &target)
.map_err(|error| format!("cannot publish tool installation: {error}"))?;
Ok(())
})();
if result.is_err() {
let _ = std::fs::remove_dir_all(&staging);
}
result.and_then(|()| load_record(&target))
}
impl ToolManifest {
fn from_path(path: &Path) -> Result<Self, String> {
let text = std::fs::read_to_string(path)
.map_err(|error| format!("cannot read `{}`: {error}", path.display()))?;
let manifest: Self =
serde_json::from_str(&text).map_err(|error| format!("invalid tool.json: {error}"))?;
Ok(manifest)
}
}
fn validate_manifest(manifest: &ToolManifest) -> Result<(), String> {
if manifest.schema != SCHEMA {
return Err(format!("unsupported tool schema `{}`", manifest.schema));
}
if manifest.schema_version != PROTOCOL_VERSION {
return Err(format!(
"unsupported tool schema_version {} (expected {PROTOCOL_VERSION})",
manifest.schema_version
));
}
if !is_valid_command(&manifest.command) {
return Err(format!(
"tool command `{}` must match ^[a-z][a-z0-9-]*$",
manifest.command
));
}
if BUILTIN_COMMANDS.contains(&manifest.command.as_str()) {
return Err(format!(
"tool command `{}` conflicts with a built-in command",
manifest.command
));
}
if manifest.name.trim().is_empty() || manifest.version.trim().is_empty() {
return Err("tool name and version must not be empty".to_string());
}
if let Some(range) = &manifest.compatibility.marqdo {
if !version_matches(env!("CARGO_PKG_VERSION"), range) {
return Err(format!(
"tool requires marqdo `{range}`, this core is {}",
env!("CARGO_PKG_VERSION")
));
}
}
Ok(())
}
fn is_valid_command(command: &str) -> bool {
let mut bytes = command.bytes();
matches!(bytes.next(), Some(byte) if byte.is_ascii_lowercase())
&& bytes.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
}
fn safe_entrypoint(package_dir: &Path, entrypoint: &Path) -> Result<PathBuf, String> {
if entrypoint.is_absolute() {
return Err("tool entrypoint must be package-relative".to_string());
}
for component in entrypoint.components() {
match component {
Component::Normal(_) => {}
Component::CurDir => {}
_ => return Err("tool entrypoint must not escape the package".to_string()),
}
}
let candidate = package_dir.join(entrypoint);
let canonical = candidate.canonicalize().map_err(|error| {
format!(
"tool entrypoint `{}` cannot be opened: {error}",
candidate.display()
)
})?;
if !canonical.starts_with(package_dir) {
return Err("tool entrypoint resolves outside the package".to_string());
}
if !canonical.is_file() {
return Err("tool entrypoint is not a file".to_string());
}
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
if std::fs::metadata(&canonical)
.map(|metadata| metadata.permissions().mode() & 0o111 == 0)
.unwrap_or(true)
{
return Err("tool entrypoint is not executable".to_string());
}
}
Ok(canonical)
}
fn copy_package(source: &Path, target: &Path) -> Result<(), String> {
for entry in walkdir::WalkDir::new(source).follow_links(false) {
let entry = entry.map_err(|error| format!("cannot walk tool package: {error}"))?;
let relative = entry
.path()
.strip_prefix(source)
.map_err(|_| "tool package path escaped its root".to_string())?;
let destination = target.join(relative);
if entry.file_type().is_symlink() {
return Err(format!(
"tool package contains a symlink `{}`; symlinks are not installed",
entry.path().display()
));
}
if entry.file_type().is_dir() {
std::fs::create_dir_all(&destination)
.map_err(|error| format!("cannot create `{}`: {error}", destination.display()))?;
} else if entry.file_type().is_file() {
if let Some(parent) = destination.parent() {
std::fs::create_dir_all(parent)
.map_err(|error| format!("cannot create `{}`: {error}", parent.display()))?;
}
std::fs::copy(entry.path(), &destination).map_err(|error| {
format!(
"cannot copy `{}` to `{}`: {error}",
entry.path().display(),
destination.display()
)
})?;
}
}
Ok(())
}
/// `marqdo tool list`.
pub fn list(json: bool) -> i32 {
match installed_records() {
Ok(records) => {
if json {
println!(
"{}",
serde_json::json!({"command":"tool.list","success":true,"tools":records})
);
} else if records.is_empty() {
println!("no tools installed");
} else {
for record in records {
println!("{} {} ({})", record.command, record.version, record.name);
}
}
0
}
Err(error) => {
eprintln!("error: {error}");
1
}
}
}
/// `marqdo tool remove <command>`.
pub fn remove(command: &str, json: bool) -> i32 {
let result = (|| -> Result<(), String> {
if !is_valid_command(command) {
return Err(format!("invalid tool command `{command}`"));
}
let home = tool_home()?;
let target = home.join(command);
if !target.is_dir() {
return Err(format!("tool `{command}` is not installed"));
}
// The target must be a direct child of the controlled home.
let canonical_home = home
.canonicalize()
.map_err(|error| format!("cannot open tool home: {error}"))?;
let canonical_target = target
.canonicalize()
.map_err(|error| format!("cannot open tool installation: {error}"))?;
if canonical_target.parent() != Some(canonical_home.as_path()) {
return Err("refusing to remove a path outside the tool home".to_string());
}
std::fs::remove_dir_all(&canonical_target)
.map_err(|error| format!("cannot remove tool `{command}`: {error}"))?;
Ok(())
})();
match result {
Ok(()) => {
if json {
println!(
"{}",
serde_json::json!({"command":"tool.remove","success":true,"tool":command})
);
} else {
println!("removed tool `{command}`");
}
0
}
Err(error) => {
if json {
println!(
"{}",
serde_json::json!({"command":"tool.remove","success":false,"error":error})
);
} else {
eprintln!("error: {error}");
}
1
}
}
}
/// Dispatch an unknown top-level command to a registered tool.
pub fn dispatch(args: &[OsString]) -> i32 {
let Some(first) = args.first() else {
eprintln!("error: missing command");
return 2;
};
let command = first.to_string_lossy();
if BUILTIN_COMMANDS.contains(&command.as_ref()) {
eprintln!("error: internal dispatch error for built-in command `{command}`");
return 2;
}
let home = match tool_home() {
Ok(home) => home,
Err(error) => {
eprintln!("error: {error}");
return 2;
}
};
let dir = home.join(command.as_ref());
let record = match load_record(&dir) {
Ok(record) => record,
Err(_) => {
eprintln!(
"error: unknown command `{command}`; install a tool with `marqdo tool install <tool.json>`"
);
return 2;
}
};
let entrypoint = dir.join(&record.entrypoint);
if !entrypoint.starts_with(&dir) {
eprintln!("error: tool entrypoint escapes its installation");
return 1;
}
let actual = match hash_file(&entrypoint) {
Ok(hash) => hash,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
if actual != record.sha256 {
eprintln!("error: tool `{command}` executable hash mismatch; reinstall it");
return 1;
}
let mut process = ProcessCommand::new(&entrypoint);
process.args(&args[1..]);
if let Ok(bin) = std::env::current_exe() {
process.env("MARQDO_BIN", bin);
}
process.env("MARQDO_TOOL_PROTOCOL", "1");
match process.status() {
Ok(status) => status.code().unwrap_or(1),
Err(error) => {
eprintln!("error: cannot start tool `{command}`: {error}");
1
}
}
}
fn installed_records() -> Result<Vec<ToolRecord>, String> {
let home = tool_home()?;
if !home.is_dir() {
return Ok(Vec::new());
}
let mut records = BTreeMap::new();
let entries = std::fs::read_dir(&home)
.map_err(|error| format!("cannot read tool home `{}`: {error}", home.display()))?;
for entry in entries {
let entry = entry.map_err(|error| format!("cannot read tool entry: {error}"))?;
if !entry.file_type().map(|kind| kind.is_dir()).unwrap_or(false) {
continue;
}
if entry.file_name().to_string_lossy().starts_with('.') {
continue;
}
if let Ok(record) = load_record(&entry.path()) {
records.insert(record.command.clone(), record);
}
}
Ok(records.into_values().collect())
}
fn load_record(dir: &Path) -> Result<ToolRecord, String> {
let text = std::fs::read_to_string(dir.join("record.json"))
.map_err(|error| format!("tool record is missing: {error}"))?;
serde_json::from_str(&text).map_err(|error| format!("invalid tool record: {error}"))
}
fn tool_home() -> Result<PathBuf, String> {
if let Some(path) = std::env::var_os("MARQDO_TOOL_HOME") {
return Ok(PathBuf::from(path));
}
let base = if cfg!(windows) {
std::env::var_os("APPDATA")
.map(PathBuf::from)
.ok_or_else(|| "APPDATA is not set; set MARQDO_TOOL_HOME".to_string())?
} else {
std::env::var_os("XDG_CONFIG_HOME")
.map(PathBuf::from)
.or_else(|| std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".config")))
.ok_or_else(|| "HOME is not set; set MARQDO_TOOL_HOME".to_string())?
};
Ok(base.join("marqdo").join("tools"))
}
fn hash_file(path: &Path) -> Result<String, String> {
let bytes = std::fs::read(path)
.map_err(|error| format!("cannot read `{}`: {error}", path.display()))?;
let mut hasher = Sha256::new();
hasher.update(&bytes);
Ok(hex::encode(hasher.finalize()))
}
fn unique_suffix() -> u128 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|duration| duration.as_nanos())
.unwrap_or(0)
}
/// Minimal version/range check for the `compatibility.marqdo` field.
fn version_matches(version: &str, range: &str) -> bool {
let Some(parsed) = parse_version(version) else {
return false;
};
range.split(',').all(|part| {
let part = part.trim();
if part.is_empty() {
return true;
}
let (op, raw) = if let Some(rest) = part.strip_prefix(">=") {
(">=", rest)
} else if let Some(rest) = part.strip_prefix("<=") {
("<=", rest)
} else if let Some(rest) = part.strip_prefix('>') {
(">", rest)
} else if let Some(rest) = part.strip_prefix('<') {
("<", rest)
} else if let Some(rest) = part.strip_prefix('=') {
("=", rest)
} else {
("=", part)
};
let Some(expected) = parse_version(raw.trim()) else {
return false;
};
match op {
">=" => parsed >= expected,
"<=" => parsed <= expected,
">" => parsed > expected,
"<" => parsed < expected,
_ => parsed == expected,
}
})
}
fn parse_version(value: &str) -> Option<(u64, u64, u64)> {
let mut parts = value.split('.');
let major = parts.next()?.parse().ok()?;
let minor = parts.next().unwrap_or("0").parse().ok()?;
let patch = parts
.next()
.unwrap_or("0")
.split('-')
.next()?
.parse()
.ok()?;
Some((major, minor, patch))
}
+184
View File
@@ -0,0 +1,184 @@
//! External CLI Tool Protocol v1 black-box tests (spec/tool-v1.md).
#![cfg(unix)]
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU32, Ordering};
static COUNTER: AtomicU32 = AtomicU32::new(0);
struct TempDir(PathBuf);
impl TempDir {
fn new(tag: &str) -> Self {
let id = COUNTER.fetch_add(1, Ordering::Relaxed);
let path = std::env::temp_dir().join(format!(
"marqdo-tool-test-{}-{id}-{tag}",
std::process::id()
));
std::fs::create_dir_all(&path).unwrap();
Self(path)
}
fn path(&self) -> &Path {
&self.0
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
fn binary() -> &'static str {
env!("CARGO_BIN_EXE_marqdo")
}
fn cli(home: &Path, args: &[&str]) -> Output {
Command::new(binary())
.args(args)
.env("MARQDO_TOOL_HOME", home)
.output()
.expect("run marqdo")
}
fn write_tool(dir: &Path, command: &str, script: &str) -> PathBuf {
let package = dir.join(format!("{command}-pkg"));
std::fs::create_dir_all(package.join("bin")).unwrap();
let entry = package.join("bin").join(command);
std::fs::write(&entry, script).unwrap();
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let mut permissions = std::fs::metadata(&entry).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&entry, permissions).unwrap();
}
let manifest = package.join("tool.json");
std::fs::write(
&manifest,
format!(
r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"bin/{command}","compatibility":{{"marqdo":">=0.1,<1"}}}}"#
),
)
.unwrap();
manifest
}
fn stderr(output: &Output) -> String {
String::from_utf8_lossy(&output.stderr).to_string()
}
fn stdout(output: &Output) -> String {
String::from_utf8_lossy(&output.stdout).to_string()
}
#[test]
fn install_dispatch_list_remove_without_core_knowledge_of_the_name() {
let dir = TempDir::new("roundtrip");
let home = dir.path().join("home");
let manifest = write_tool(
dir.path(),
"benchmark",
"#!/bin/sh\nfor a in \"$@\"; do printf 'arg=%s\\n' \"$a\"; done\nprintf 'protocol=%s\\n' \"$MARQDO_TOOL_PROTOCOL\"\nexit 7\n",
);
let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(install.status.code(), Some(0), "{}", stderr(&install));
let listed = cli(&home, &["tool", "list"]);
assert!(stdout(&listed).contains("benchmark 0.1.0"));
let output = cli(&home, &["benchmark", "run", ".", "空格"]);
assert_eq!(output.status.code(), Some(7));
let text = stdout(&output);
assert!(text.contains("arg=run"));
assert!(text.contains("arg=."));
assert!(text.contains("arg=空格"));
assert!(text.contains("protocol=1"));
let removed = cli(&home, &["tool", "remove", "benchmark"]);
assert_eq!(removed.status.code(), Some(0));
let unknown = cli(&home, &["benchmark"]);
assert_eq!(unknown.status.code(), Some(2));
assert!(stderr(&unknown).contains("unknown command"));
}
#[test]
fn invalid_manifests_and_path_escapes_are_rejected() {
let dir = TempDir::new("invalid");
let home = dir.path().join("home");
let manifest = write_tool(dir.path(), "lintx", "#!/bin/sh\nexit 0\n");
let builtin = std::fs::read_to_string(&manifest)
.unwrap()
.replace("\"command\":\"lintx\"", "\"command\":\"run\"");
let builtin_manifest = dir.path().join("builtin.json");
std::fs::write(&builtin_manifest, builtin).unwrap();
let output = cli(
&home,
&["tool", "install", builtin_manifest.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
assert!(stderr(&output).contains("built-in"));
let traversal = std::fs::read_to_string(&manifest)
.unwrap()
.replace("bin/lintx", "../outside");
let traversal_manifest = dir.path().join("traversal.json");
std::fs::write(&traversal_manifest, traversal).unwrap();
let output = cli(
&home,
&["tool", "install", traversal_manifest.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
let incompatible = std::fs::read_to_string(&manifest)
.unwrap()
.replace(">=0.1,<1", ">=99.0");
let incompatible_manifest = dir.path().join("incompatible.json");
std::fs::write(&incompatible_manifest, incompatible).unwrap();
let output = cli(
&home,
&["tool", "install", incompatible_manifest.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
assert!(stderr(&output).contains("requires marqdo"));
}
#[test]
fn tampered_binary_and_path_hijack_are_not_executed() {
let dir = TempDir::new("security");
let home = dir.path().join("home");
let manifest = write_tool(dir.path(), "custom-abc", "#!/bin/sh\nexit 0\n");
assert_eq!(
cli(&home, &["tool", "install", manifest.to_str().unwrap()])
.status
.code(),
Some(0)
);
let installed = home.join("custom-abc").join("bin").join("custom-abc");
std::fs::write(&installed, "#!/bin/sh\nexit 99\n").unwrap();
let tampered = cli(&home, &["custom-abc"]);
assert_eq!(tampered.status.code(), Some(1));
assert!(stderr(&tampered).contains("hash mismatch"));
// A PATH program with the marqdo prefix is not implicitly a tool.
let path_dir = dir.path().join("path");
std::fs::create_dir_all(&path_dir).unwrap();
let hijack = path_dir.join("marqdo-hijack");
std::fs::write(&hijack, "#!/bin/sh\nexit 42\n").unwrap();
use std::os::unix::fs::PermissionsExt;
let mut permissions = std::fs::metadata(&hijack).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&hijack, permissions).unwrap();
let output = Command::new(binary())
.arg("hijack")
.env("MARQDO_TOOL_HOME", &home)
.env("PATH", &path_dir)
.output()
.unwrap();
assert_eq!(output.status.code(), Some(2));
assert!(stderr(&output).contains("unknown command"));
}
+1 -1
View File
@@ -42,7 +42,7 @@ providers).
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **In progress** | `KernelRegistry` external providers; complete-name plugin export routing; `CapabilityBroker` with vendor policy; static `check --plugin` signatures; multi-export C test; provider tests. Isolated worker and handle table still pending |
| R3 Tool Protocol | Not started | — |
| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking |
| R4 Analysis/Trace v1 | Not started | — |
| R5 environment/isolation | Not started | — |
| R6 release/consumers | Not started | — |
@@ -0,0 +1,75 @@
# ADR-0013: Generic external CLI Tool Protocol v1
Status: **Accepted**
Date: 2026-11-20
## Context
M0.6 must let external tools (`view`, `knowledge`, `prove`, or arbitrary
third-party programs) become `marqdo <command>` entries without changing the
core source or command enum. The CLI currently has a closed `clap` enum and no
generic distribution path. C ABI plugins and foreign kernels are unrelated
trust models: a Tool is a user-invoked native process.
## Decision
`spec/tool-v1.md` is implemented as follows:
* new top-level commands are limited to
`tool install/list/remove` plus fallback for unknown top-level commands;
* `tool.json` (schema `marqdo.cli-tool`, schema_version 1) declares
`name`, `version`, `command`, `entrypoint` and optional compatibility; the
core does not contain any tool name, download URL or business argument;
* install requires a local manifest, validates the command (lowercase ASCII,
no built-in conflict), rejects absolute/`..`/symlink-escaping entrypoints,
copies the package without following symlinks into a user-controlled tool
home, re-verifies the executable SHA-256, writes a registry record, and
publishes atomically via rename;
* dispatch checks the registry record, re-verifies the executable hash, starts
the entrypoint directly with `OsString` arguments (no shell), inherits
stdin/stdout/stderr and cwd, sets `MARQDO_BIN`/`MARQDO_TOOL_PROTOCOL=1`, and
propagates the exit code;
* a missing registration is an unknown command; a `marqdo-<name>` on PATH is
never executed implicitly;
* uninstall removes only the exact controlled installation directory.
The tool home defaults to the platform config directory and can be redirected
with `MARQDO_TOOL_HOME` for tests/enterprise deployment.
## Alternatives
1. Add a `clap` variant per known tool. Rejected by the audit (E01/E12).
2. Auto-discover `marqdo-*` from PATH (Cargo-style). Rejected: implicit
execution and PATH hijacking; M0.6 requires explicit installation.
3. Use the C ABI plugin registry. Rejected: different lifecycle, protocol and
security boundary.
4. Implement a remote registry first. Rejected: local manifest installation is
the required closed loop; name-based installs are a future optional index.
## Compatibility
This adds one new top-level command (`tool`) and an unknown-command fallback.
Built-in commands always win. Future core commands that collide with an
installed tool are a breaking change and need an ADR/migration policy. The
manifest is versioned; unknown optional fields are ignored in v1 but never
imply authorization.
## Security
A Tool is a normal process run as the user, not inside the `.mq.md` sandbox.
It does not automatically receive Marqdo capabilities, secrets or plugin
handles. Install never runs the tool. The executable hash detects post-install
tampering, not a malicious publisher; local source selection is the trust
decision. Symlinks are rejected during package copy.
## Testing
`crates/cli/tests/tool_protocol.rs` covers arbitrary command names,
install/list/remove, argument/exit-code forwarding, Unicode args, built-in
conflict, traversal, version mismatch, binary tampering and PATH hijacking.
`spec/tool-v1.md` lists the full black-box matrix.
## Migration & rollout
R3 adds the command surface. R4 can expose Analysis/Trace compatibility through
the manifest's optional fields; no tool business logic enters the core.
+1 -1
View File
@@ -18,7 +18,7 @@ marqdo-cli/
│ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6
│ ├── STATUS.md implementation matrix (P0–P7)
│ ├── contributor-guide.md this file
│ └── adr/0001..0012-*.md accepted decisions
│ └── adr/0001..0014-*.md accepted decisions
├── spec/
│ ├── markdown-profile.md frozen parser profile `marqdo.md.v1`
│ ├── mapping.md AST → program roles