feat(security): XPIA content wrapping at the tool boundary

[Brandon Werner (brandwe)]

Summary

Wraps every read-tool return in a machine-checkable <external_content> envelope so the LLM treats external content as data, not instructions. Closes the passive-injection gap for Teams messages, email bodies, files, and A365 documents.

Best Short Term Feature #1 from the Entrabot New Features master plan (see PR #99 for the design docs). Sibling to Learning #67 (attacker-controllable tool arguments) and Learning #69 (identity by UPN) — same principle applied to tool returns.

What's in the envelope

<external_content source="teams:19:..." sender="alice@example.com" received_at="2026-07-09T18:05:36Z">
body text
</external_content>

• Attributes escape <, >, &.
• Body escape-on-collision on literal </external_content> (case- and whitespace-tolerant).
• Idempotent (double-wrap is a no-op).
• Application-generated metadata (message ids, sender IDs, timestamps, counts) stays outside the envelope so downstream tools and the model can still filter and count without ingesting body content.

Where it wires in

Tool	Envelope source
read_teams_messages	teams:<chat_id>
read_email	email:<message_id>
read_file	file:<web_url>
read_word_document	file:<url>#word
read_a365_text_file	a365:<file_id>
read_interactions inbound entries	teams:<chat_id>

Binary A365 reads are left unwrapped.

Deviations from spec

• hypothesis fuzz replaced with a parametrized adversarial + Unicode corpus (13 inputs). Same regression surface without a new dev-dep.
• read_interactions adds a new content_wrapped field rather than mutating summary (which is a stable 120-char preview relied on by existing tests).
• Deny-list regex broadened from add_(?:member|comment) to add_ so the shipped add_teams_member / add_file_comment / add_word_comment / add_promise tools actually match.
• Case-preserving escape so unwrap roundtrips byte-for-byte on adversarial variants like </EXTERNAL_CONTENT>.

Rollback

• Set ENTRABOT_XPIA_WRAP_ENABLE=false and restart. Wrappers become identity functions.
• Full revert: git revert <sha>.

Test plan

• Full suite: 1567 → 1652 (+85). Ruff clean.
• tests/security/test_xpia_wrap.py — 28 tests: envelope shape, escape-on-collision (case-insensitive), attribute escaping, idempotency, byte-for-byte roundtrip on adversarial + Unicode corpus, env-flag disables wrap.
• tests/tools/test_dispatch.py — 37 tests pinning the deny-list against every shipped tool name.
• Extensions to Teams, email, files, Word, A365 text, and interaction-log tool tests confirming wrapped bodies + unwrapped metadata.
• Restart entrabot MCP after landing (body-prompt change is loaded at boot).

Notes

• Design doc docs/architecture/PLAN-xpia-content-wrapping.md lands in docs: master plan for new features + XPIA wrapping and skills layer designs #99 (Entrabot New Features master plan + XPIA + Skills designs). This PR references that file by path; the path will exist after docs: master plan for new features + XPIA wrapping and skills layer designs #99 merges.
• Depends on nothing runtime-wise; can land before or after fix(teams): identify self-authored messages by UPN, not display name #98 and docs: master plan for new features + XPIA wrapping and skills layer designs #99.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements boundary-enforced “XPIA” wrapping for attacker-controllable tool returns by enclosing external bodies (Teams messages, email bodies, file text, A365 Word/ODSP text, and inbound interaction-log summaries) in a machine-checkable <external_content ...>...</external_content> envelope, and updates the body prompt/docs to instruct the model to treat the envelope contents as data (not instructions). This aims to close passive instruction-injection via tool returns.

Changes:

• Add entrabot.security.xpia with wrap_external / unwrap_external implementing idempotent wrapping, attribute escaping, and escape-on-collision for embedded </external_content> variants.
• Wire wrapping into read paths (read_teams_messages, read_email, read_file, A365 Word/ODSP reads) and add an inbound-only content_wrapped field for read_interactions.
• Add deny-list “write-shaped tool name” recognizer (entrabot.tools.dispatch) plus extensive unit/regression tests and supporting doc/status updates.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
TODOS.md	Notes status update for read-tool content wrapping work item.
tests/tools/test_watch.py	Adjusts watch replies assertions for wrapped Teams content.
tests/tools/test_teams.py	Updates Teams read tests and adds dedicated XPIA wrapping tests.
tests/tools/test_read_interactions.py	Adds tests for new content_wrapped on inbound interaction entries.
tests/tools/test_read_email.py	Updates email tests to assert wrapped bodies + adds hostile-tag/env-flag cases.
tests/tools/test_files.py	Updates file-read tests to assert wrapped text + unwrap-based truncation checks.
tests/tools/test_dispatch.py	New tests pinning write-shaped tool-name recognizer behavior.
tests/test_config.py	Adds tests for ENTRABOT_XPIA_WRAP_ENABLE parsing in config.
tests/security/test_xpia_wrap.py	New unit tests for envelope correctness, escaping, idempotency, round-trip, env flag.
tests/security/init.py	Initializes tests.security package.
tests/a365/test_word.py	Updates Word content tests for wrapped content_html + hostile-tag/env-flag cases.
tests/a365/test_odsp.py	Updates ODSP small-text tests for wrapped content + hostile-tag/env-flag cases.
src/entrabot/tools/teams.py	Wraps Teams message bodies at the tool boundary; keeps metadata outside envelope.
src/entrabot/tools/read_interactions.py	Adds inbound-only content_wrapped via _annotate_inbound_with_xpia_wrap.
src/entrabot/tools/files.py	Wraps extracted file text after truncation; sets envelope source from webUrl or drive/item.
src/entrabot/tools/email.py	Wraps email body content in envelope while preserving other metadata.
src/entrabot/tools/dispatch.py	New write-shaped tool-name recognizer + debug registration helper.
src/entrabot/security/xpia.py	New core XPIA envelope implementation (wrap/unwrap + collision escaping).
src/entrabot/security/init.py	New security package marker + rationale docstring.
src/entrabot/config.py	Adds xpia_wrap_enable env parsing to config.
src/entrabot/a365/word.py	Wraps Word document HTML content returned from Work IQ boundary.
src/entrabot/a365/odsp.py	Wraps ODSP small text file content returned from Work IQ boundary.
prompts/anatomy/security.md	Adds body-prompt rule: treat <external_content> contents as data, refuse directives inside.
docs/runbooks/hard-won-learnings.md	Adds Learning #70 documenting the XPIA wrapping defense and rationale.
docs/engineering-status.md	Updates overall status and recent-changes list to include XPIA wrapping work.