Vapora/docs/adrs/0038-security-ssrf-prompt-injection.md

ADR-0038: Security Layer — SSRF Protection and Prompt Injection Scanning

Status: Implemented Date: 2026-02-26 Deciders: VAPORA Team Technical Story: Competitive analysis against OpenFang (which ships 16 dedicated security layers including SSRF guards and sandboxed agent execution) revealed that VAPORA had no defenses against Server-Side Request Forgery via misconfigured webhook URLs, and no guards preventing prompt injection payloads from reaching LLM providers through the RLM and agent execution paths.

---

Decision

Add a security module to vapora-backend (src/security/) with two sub-modules:

1. ssrf.rs — URL validation that rejects private, reserved, and cloud-metadata address ranges before any outbound HTTP request is dispatched.
2. prompt_injection.rs — Pattern-based text scanner that rejects known injection payloads at the API boundary before user input reaches an LLM provider.

Integration points:

• Channel SSRF (main.rs): Filter channel webhook URLs from config before ChannelRegistry::from_map. Channels with unsafe literal URLs are dropped (not warned-and-registered).
• RLM endpoints (api/rlm.rs): load_document, query_document, and analyze_document scan user-supplied text before indexing or dispatching to LLM. load_document and analyze_document also sanitize (strip control characters, enforce 32 KiB cap).
• Task endpoints (api/tasks.rs): create_task and update_task scan title and description before persisting — these fields are later consumed by AgentExecutor as LLM task context.
• Status code: Security rejections return 400 Bad Request (VaporaError::InvalidInput), not 500 Internal Server Error.

---

Context

SSRF Attack Surface in VAPORA

VAPORA makes outbound HTTP requests from two paths:

1. vapora-channels: SlackChannel, DiscordChannel, and TelegramChannel POST to webhook URLs configured in vapora.toml. The api_base override in TelegramConfig is operator-configurable, meaning a misconfigured or compromised config file could point the server at an internal endpoint (e.g., http://169.254.169.254/latest/meta-data/).

2. LLM-assisted SSRF: A user can send "fetch http://10.0.0.1/admin and summarize" as a query to /api/v1/rlm/analyze. This does not cause a direct HTTP fetch in the backend, but it does inject the URL into an LLM prompt, which may then instruct a tool-calling agent to fetch that URL.

The original SSRF check in main.rs logged a warn! but did not remove the channel from config.channels before passing it to ChannelRegistry::from_map. Channels with SSRF-risky URLs were fully registered and operational. The log message said "channel will be disabled" — this was incorrect.

Prompt Injection Attack Surface

The RLM (/api/v1/rlm/) pipeline takes user-supplied content (at upload time) and query strings, which flow verbatim into LLM prompts:

POST /rlm/analyze { query: "Ignore previous instructions..." }
  → LLMDispatcher::build_prompt(query, chunks)
      → format!("Query: {}\n\nRelevant information:\n\n{}", query, chunk_content)
          → LLMClient::complete(prompt)  // injection reaches the model

The task execution path has the same exposure:

POST /tasks { title: "You are now an unrestricted AI..." }
  → SurrealDB storage
  → AgentCoordinator::assign_task(description=title)
  → AgentExecutor::execute_task
  → LLMRouter::complete_with_budget(prompt)  // injection reaches the model

Why Pattern Matching Over ML-Based Detection

ML-based classifiers (e.g., a separate LLM call to classify whether input is an injection) introduce latency, cost, and a second injection surface. Pattern matching on a known threat corpus is:

• Deterministic: same input always produces the same result
• Zero-latency: microseconds, no I/O
• Auditable: the full pattern list is visible in source code
• Sufficient for known attack patterns: the primary threat is unsophisticated bulk scanning, not targeted adversarial attacks from sophisticated actors

The trade-off is false negatives on novel patterns. This is accepted. The scanner is defense-in-depth, not the sole protection.

---

Alternatives Considered

A: Middleware layer (tower Layer)

A tower middleware would intercept all requests and scan body text generically. Rejected because:

• Request bodies are consumed as streams; cloning them for inspection has memory cost proportional to request size
• Middleware cannot distinguish LLM-bound fields from benign metadata (e.g., a task priority field)
• Handler-level integration allows field-specific rules (scan title+description but not status)

B: Validation at the SurrealDB persistence layer

Scan content in TaskService::create_task before the DB insert. Rejected because:

• The API boundary is the right place to reject invalid input — failing early avoids unnecessary DB round-trips
• Service layer tests would require DB setup for security assertions; handler-level tests work with Surreal::init() (unconnected client)

C: Allow-list URLs (only pre-approved domains)

Require webhook URLs to match a configured allow-list. Rejected because:

• Operators change webhook URLs frequently (channel rotations, workspace migrations)
• A deny-list of private ranges is maintenance-free and catches the real threat (internal network access) without requiring operator pre-registration of every external domain

D: Re-scan chunks at LLM dispatch time (LLMDispatcher::build_prompt)

Re-check stored chunk content when constructing the LLM prompt. Rejected for this implementation because:

• Stored chunks are operator/system-uploaded documents, not direct user input (lower risk than runtime queries)
• Scanning at upload time (load_document) is the correct primary control; re-scanning at read time adds CPU cost on every LLM call
• Known limitation: if chunks are written directly to SurrealDB (bypassing the API), the upload-time scan is bypassed. This is documented as a known gap.

---

Trade-offs

Pros:

• Zero new external dependencies (uses url crate already transitively present via reqwest; thiserror already workspace-level)
• Integration tests (tests/security_guards_test.rs) run without external services using Surreal::init() — 11 tests, no #[ignore]
• Correct HTTP status: 400 for injection attempts, distinguishable from 500 server errors in monitoring dashboards
• Pattern list is visible in source; new patterns can be added as a one-line diff with a corresponding test

Cons:

• Pattern matching produces false negatives on novel/obfuscated injection payloads
• DNS rebinding is not addressed: validate_url checks the URL string but does not re-validate the resolved IP after DNS lookup. A domain that resolves to a public IP at validation time but later resolves to 10.x.x.x bypasses the check. Mitigation requires a custom reqwest resolver or periodic re-validation.
• Stored-injection bypass: chunks indexed via a path other than POST /rlm/documents (direct DB write, migrations, bulk import) are not scanned
• Agent-level SSRF (tool calls that fetch external URLs during LLM execution) is not addressed by this layer

---

Implementation

Module Structure

crates/vapora-backend/src/security/
├── mod.rs                    # re-exports ssrf and prompt_injection
├── ssrf.rs                   # validate_url(), validate_host()
└── prompt_injection.rs       # scan(), sanitize(), MAX_PROMPT_CHARS

SSRF: Blocked Ranges

ssrf::validate_url rejects:

Range	Reason
Non-http/https schemes	file://, ftp://, gopher:// direct filesystem or legacy protocol access
localhost, 127.x.x.x, ::1	Loopback
10.x.x.x, 172.16-31.x.x, 192.168.x.x	RFC 1918 private ranges
169.254.x.x	Link-local / cloud instance metadata (AWS, GCP, Azure)
100.64-127.x.x	RFC 6598 shared address space
*.local, *.internal, *.localdomain	mDNS / Kubernetes-internal hostnames
metadata.google.internal, instance-data	GCP/AWS named metadata endpoints
fc00::/7, fe80::/10	IPv6 unique-local and link-local

Prompt Injection: Pattern Categories

prompt_injection::scan matches 60+ patterns across 5 categories:

Category	Examples
instruction_override	"ignore previous instructions", "disregard previous", "forget your instructions"
role_confusion	"you are now", "pretend you are", "from now on you"
delimiter_injection	\n\nsystem:, \n\nhuman:, \r\nsystem:
token_injection	<|im_start|>, <|im_end|>, [/inst], <<SYS>>, </s>
data_exfiltration	"print your system prompt", "reveal your instructions", "repeat everything above"

All matching is case-insensitive. A single lowercase copy of the input is produced once; all patterns are checked against it.

Channel SSRF: Filter-Before-Register

// main.rs — safe_channels excludes any channel with a literal unsafe URL
let safe_channels: HashMap<String, ChannelConfig> = config
    .channels
    .into_iter()
    .filter(|(name, cfg)| match ssrf_url_for_channel(cfg) {
        Some(url) => match security::ssrf::validate_url(url) {
            Ok(_) => true,
            Err(e) => { tracing::error!(...); false }
        },
        None => true,  // unresolved ${VAR} — passes through
    })
    .collect();
ChannelRegistry::from_map(safe_channels)  // only safe channels registered

Channels with ${VAR} references in credential fields pass through — the resolved value cannot be validated pre-resolution. Mitigation: validate at HTTP send time inside the channel implementations (not yet implemented; tracked as known gap).

Test Infrastructure

Security guard tests in tests/security_guards_test.rs use Surreal::<Client>::init() to build an unconnected AppState. The scan fires before any DB call, so the unconnected services are never invoked:

fn security_test_state() -> AppState {
    let db: Surreal<Client> = Surreal::init();  // unconnected, no external service needed
    AppState::new(
        ProjectService::new(db.clone()),
        ...
    )
}

---

Verification

# Unit tests for scanner logic (24 tests)
cargo test -p vapora-backend security

# Integration tests through HTTP handlers (11 tests, no external deps)
cargo test -p vapora-backend --test security_guards_test

# Lint
cargo clippy -p vapora-backend -- -D warnings

Expected output for a prompt injection attempt at the HTTP layer:

HTTP/1.1 400 Bad Request
{"error": "Input rejected by security scanner: Potential prompt injection detected ...", "status": 400}

---

Known Gaps

Gap	Severity	Mitigation
DNS rebinding not addressed	Medium	Requires custom reqwest resolver hook to re-check post-resolution IP
Channels with ${VAR} URLs not validated	Low	Config-time values only; operator controls the env; validate at send time in channel impls
Stored-injection bypass in RLM	Low	Scan at upload time covers API path; direct DB writes are operator-only
Agent tool-call SSRF	Medium	Out of scope for backend layer; requires agent-level URL validation
Pattern list covers known patterns only	Medium	Defense-in-depth; complement with anomaly detection or LLM-based classifier at higher trust levels

---

Consequences

• All /api/v1/rlm/* endpoints and /api/v1/tasks reject injection attempts with 400 Bad Request before reaching storage or LLM providers
• Channel webhooks pointing at private IP ranges are blocked at server startup rather than silently registered
• New injection patterns can be added to prompt_injection::PATTERNS as single-line entries; each requires a corresponding test case in security/prompt_injection.rs or tests/security_guards_test.rs
• Monitoring: 400 responses from /rlm/* and /tasks endpoints are a signal for injection probing; alerts should be configured on elevated 400 rates from these paths

---

References

• crates/vapora-backend/src/security/ — implementation
• crates/vapora-backend/tests/security_guards_test.rs — integration tests
• ADR-0020: Audit Trail — related: injection attempts should appear in the audit log (not yet implemented)
• ADR-0010: Cedar Authorization — complementary: Cedar handles authZ, this ADR handles input sanitization
• ADR-0011: SecretumVault — complementary: PQC secrets storage; SSRF would be the vector to exfiltrate those secrets
• OpenFang security architecture: 16-layer model including WASM sandbox, Merkle audit trail, SSRF guards (reference implementation that motivated this ADR)