Harden mdcode operations for untrusted Markdown and agent execution #7

Activity

1. adrianbrowning

   marked this as blocking 3 issues on Aug 8, 2026

   • Publish an agent integration guide and workflow examples #8
   • Expose mdcode as typed MCP tools for LLM agents #9
   • Add validation and duplicate-target protection before writes #15
2. adrianbrowning commented on Aug 8, 2026

   

   adrianbrowning

   on Aug 8, 2026

   OwnerAuthor

   More actions

   This was generated by AI during triage.

   Agent Brief

   Category: enhancement
   Summary: Enforce filesystem and shell-execution safety boundaries for untrusted Markdown.

   Current behavior:
   Extract and update join metadata file paths to their working paths without containment validation. Traversal can therefore escape the intended directory. Update logs failed source reads and transformer failures, then continues with stale content. Run executes a caller-provided shell command and prints global console output without a separate acknowledgement or structured CLI outcome.

   Desired behavior:
   Every metadata-derived file access stays below an explicit allowed base directory. Unsafe paths fail with an actionable error tied to the selected block. Source-read and transform failures stop the command by default. Shell execution remains available only through a clearly acknowledged privileged operation and produces structured per-block outcomes.

   Key interfaces:

   • Guarded path resolution module — resolve metadata paths against an allowed base and reject absolute paths, traversal escapes, and symlink escapes. Reuse this module for all metadata-derived reads and writes.
   • Allowed base — update defaults to the Markdown document directory; --base explicitly selects another base for repository layouts where sources live elsewhere.
   • Error policy — source-read and transform failures fail the command; --continue-on-error is the only supported opt-in to collecting failures and continuing.
   • Privileged run operation — require --allow-shell in addition to the caller-supplied command. Markdown metadata must never supply a command to execute.
   • Per-block results — return structured outcomes for success and failure using the JSON contract from issue Add a versioned machine-readable CLI contract for agents #5.

   Acceptance criteria:

   • Metadata-derived file paths cannot escape the selected base directory.
   • Absolute paths, traversal attempts, and symlink escapes fail before an unsafe read or write.
   • Errors identify the affected block name or location and rejected path.
   • Update defaults its base to the Markdown document directory and supports --base for an explicit alternate base.
   • Source-read and transform failures fail by default; --continue-on-error is explicit and reports every affected block.
   • Run requires --allow-shell and never executes a command supplied by Markdown metadata.
   • Run returns structured per-block outcomes without terminal formatting under JSON output.
   • Documentation states the trusted-input model and tests cover the containment and error-policy cases.

   Out of scope:

   • Sandboxing or otherwise trusting arbitrary commands explicitly supplied by the caller.
   • Type-checking or validating the code inside a Markdown block.
   • The shared JSON envelope itself, which is issue Add a versioned machine-readable CLI contract for agents #5.

   Verification status:
   Confirmed by code inspection: extract and update use unchecked path joining, while update and transforms log errors and continue. This issue is blocked by #5 for the structured result contract.
3. adrianbrowning

   added

   enhancementNew feature or requestNew feature or request

   ready-for-agentFully specified and ready for an AFK agentFully specified and ready for an AFK agent

   on Aug 8, 2026
4. adrianbrowning

   marked this as blocked on Oct 4, 2026

   • Add a versioned machine-readable CLI contract for agents #5
5. adrianbrowning

   marked this as blocking on Oct 4, 2026

   • Provide a CI example for validating runnable Markdown snippets #12
6. adrianbrowning

   added a commit that references this issue on Oct 4, 2026

   feat: keep metadata paths inside their base; fail fast; run needs --a…

   ...

   2898884
7. adrianbrowning

   closed this as completedin #35on Oct 4, 2026