security: sanitize DOM content in LLM prompts to mitigate indirect prompt injection

[johnpippett]

Summary

Fixes a Critical security finding: indirect prompt injection via unsanitized DOM content being fed directly into LLM prompts.

Changes

• Adds sanitizeDomForPrompt() helper in packages/core/lib/prompt.ts that wraps raw DOM/webpage content in clear <<<<STAGEHAND_DOM_BEGIN>>>> / <<<<STAGEHAND_DOM_END>>>> boundaries and escapes any embedded end-marker sequences to prevent boundary breakout.
• Applies sanitization at all DOM-to-prompt injection points:
  • buildExtractUserPrompt (extract inference)
  • buildObserveUserMessage (observe / act inference)
  • ariaTree tool toModelOutput (agent tool output)
• Adds unit tests covering boundary wrapping, marker escaping, and prompt builder integration.

Test Results

• New tests: 5 passed (prompt-sanitize-dom.test.ts)
• Existing related tests: 55 passed (prompt-observe-variables, snapshot-a11y-tree-utils, snapshot-capture-orchestration, agent-execution-model, llm-middleware)

Audit Reference

• Source: 31.08 AI Tooling Security Audit Findings — browserbase/stagehand
• Finding: [Critical / Trivial / Single-user] — Indirect prompt injection via unsanitized DOM content (packages/core/lib/prompt.ts, packages/core/lib/v3/agent/tools/ariaTree.ts, packages/core/lib/v3/handlers/actHandler.ts)

Files Changed

• packages/core/lib/prompt.ts
• packages/core/lib/v3/agent/tools/ariaTree.ts
• packages/core/tests/unit/prompt-sanitize-dom.test.ts

---

Summary by cubic

Fixes a critical security issue: sanitizes DOM content before it enters LLM prompts to prevent indirect prompt injection. Adds clear start/end boundaries and escapes embedded markers; applied across extract, observe, and ariaTree tool flows.

• Bug Fixes
  • Added sanitizeDomForPrompt() in packages/core/lib/prompt.ts to wrap DOM with <<<<STAGEHAND_DOM_BEGIN>>>> / <<<<STAGEHAND_DOM_END>>>> and escape nested end markers.
  • Applied sanitization in buildExtractUserPrompt, buildObserveUserMessage, and packages/core/lib/v3/agent/tools/ariaTree.ts output.
  • Added unit tests for boundary wrapping, marker escaping, and prompt builder integration.

^{Written for commit 26a5b7d. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 26a5b7d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Agent as Agent / Orchestrator
    participant Browser as Browser Instance
    participant PromptLib as Prompt Library
    participant AriaTool as AriaTree Tool
    participant LLM as LLM Provider

    Note over Agent,LLM: DOM Extraction & Sanitization Flow

    rect rgb(240, 248, 255)
    Note right of Agent: Extraction / Observation Flow
    Agent->>Browser: Get Page DOM / Accessibility Tree
    Browser-->>Agent: Raw DOM String
    
    Agent->>PromptLib: buildExtractUserPrompt(instruction, rawDom)
    
    PromptLib->>PromptLib: NEW: sanitizeDomForPrompt(rawDom)
    Note right of PromptLib: Escapes end-markers &<br/>wraps in <<<<STAGEHAND_DOM_BEGIN>>>>
    
    PromptLib-->>Agent: ChatMessage (Sanitized)
    Agent->>LLM: POST /chat/completions
    end

    rect rgb(255, 240, 245)
    Note right of Agent: Tool Execution Flow (ariaTree)
    LLM-->>Agent: Tool Call: ariaTree()
    Agent->>AriaTool: execute()
    
    AriaTool->>Browser: Capture Accessibility Tree
    Browser-->>AriaTool: Tree Content
    
    AriaTool->>PromptLib: NEW: sanitizeDomForPrompt(content)
    PromptLib-->>AriaTool: Sanitized Content
    
    AriaTool-->>Agent: Tool Output (Sanitized)
    Agent->>LLM: Submit Tool Results
    end

    Note over PromptLib: Security Detail: sanitizeDomForPrompt()<br/>1. Replace "<<<<STAGEHAND_DOM_END>>>>" with escaped version<br/>2. Wrap content in STAGEHAND_DOM boundaries

Loading