cli-mcp examples/composition-with-guard

NAME

guarded - MCP server with cli-guard audit + argv validation

SYNOPSIS

guarded

DESCRIPTION

guarded is the headline value proposition of the cli-* family: cli-mcp + cli-guard composed in front of the same tree. Every MCP tool call goes through cli-guard's verb.Wrap pipeline before the Action body runs:

1. policy.ValidateArg rejects shell metacharacters in any
   user-supplied string. Hostile inputs never reach the Action.
2. Action execution.
3. Audit row: one JSONL record per call appended to
   $TMPDIR/cli-mcp-composition.jsonl with timestamp, full argv,
   cwd, exit code.

The MCP layer is unaware of any of this. From the agent's view it is just a tool. From the host's view, every call produces an auditable record and every input is gate-checked.

Why this composition matters:

- An MCP server exposed to an agent is a credentialed endpoint.
  The agent acts as a confused deputy: it has the credentials
  of the host, plus a remote LLM that may be jailbroken.
- Without verb.Wrap, an agent that gets prompt-injected into
  calling `echo 'hello; rm -rf /'` would forward that argv to
  the wrapped tool. With verb.Wrap, the gate rejects the
  semicolon before execve.
- Without the audit row, "what did the agent run" is
  reconstructable only from the agent's own logs (which the
  agent may have been induced to falsify). The audit row is
  written by cli-guard, not by the agent, and lives outside
  the agent's reach.

Operating model for an agent calling tools served by a guarded cli-mcp binary:

- Rejection (exitcode.PolicyDenied) is non-retryable. Surface
  the rejection to the operator. Do not escape and retry.
- The audit log is the source of truth for "what ran". An
  agent reading its own logs should also be able to read the
  audit log via a separate tool, not by parsing its own
  transcript.
- This is not a sandbox. A malicious tool body or a deny-rule
  gap still lets bad things happen. The composition raises
  the cost of attack and produces forensic evidence; it does
  not make a hostile agent harmless.

Usage:

guarded [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]

COMMANDS

echo

echo a message (audited, argv-validated)

whoami

audited diagnostic