π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr): add ADR-377 β AgentDB Retrieval Security Layer (#2872)
rUve3a403e9f413
diff --git a/v3/docs/adr/ADR-377-agentdb-retrieval-security.md b/v3/docs/adr/ADR-377-agentdb-retrieval-security.mdnew file mode 100644index 0000000000..537067e37f--- /dev/null+++ b/v3/docs/adr/ADR-377-agentdb-retrieval-security.md@@ -0,0 +1,153 @@+# ADR-377: AgentDB Retrieval Security Layer++**ID**: ADR-377+**Status**: Proposed+**Date**: 2026-07-01+**Authors**: claude (dream-cycle agent, 2026-07-01)+**Branch**: dream/2026-07-01-security+**Related ADRs**:+- ADR-006 (Unified Memory Service)+- ADR-131 (ToolOutputGuardrail β ASI01 content-boundary screening)+- ADR-144 (AgentAuthorizationPropagator β per-action scope checks)+- ADR-145 (PluginIntegrityVerifier β Ed25519 plugin signing)+- ADR-165 (Security CVE Posture Review)++---++## Context++Six 2026 Grade A arXiv papers establish that AgentDB's read and write paths are high-confidence attack surfaces with no certified defenses:++- **SMSR** (arXiv:2606.12703, Jun 2026): First certified defense for multi-session RAG agents; without it, poisoning ASR is 93β100% across all unsigned memory variants. SMSR reduces to 0%.+- **Forensic Trajectory Signatures** (arXiv:2606.30566, Jun 2026): Behavioral forensics on agent write sequences achieves AUC=0.9904 overall and AUC=1.000 on 6/9 cross-model hold-out splits, generalizing across frontier models without retraining.+- **Indirect Prompt Injection in the Wild** (arXiv:2601.07072, Jan 2026): Attacker-controlled content decomposes into retrieval-guaranteed fragments; near-100% retrieval success across 11 benchmarks β meaning any poisoned AgentDB entry has near-certain retrieval into context.+- **Capability Gates Are Not Authorization** (arXiv:2606.28679, Jun 2026): All three major frameworks (LangChain, LlamaIndex, Stripe Agent Toolkit) conflate tool exposure with authorization; no fail-closed per-call gate exists. Ruflo's `SafeExecutor` has the same structural gap.+- **MCP Caller Identity Confusion** (arXiv:2603.07473, Mar 2026): MCP servers carry no caller authentication; authorization state persists across callers without re-verification.+- **HCP MCP Runtime** (arXiv:2606.29073, Jun 2026): A Hardened Capability Protocol (HCP) blocks all 10/10 tested attack cases; naive baseline fails all 10/10.++**OWASP LLM Top 10 (2025)** added two directly relevant categories:+- **LLM07**: System Prompt Leakage β no guardrail in Ruflo on prompt exfiltration via tool outputs+- **LLM08**: Vector and Embedding Weaknesses β no retrieval-layer injection filter in AgentDB++ADR-165 (June 2026) closed CVE-1β5 at the input validation and plugin signing layers. It does not address the retrieval path, the write-path authenticity problem, or MCP caller identity.++All four major competitors (LangGraph, AutoGen, CrewAI, OpenAI Swarm) share these gaps as of July 2026. Ruflo is uniquely positioned to lead with an extensible `post-retrieve`/`pre-context-inject` hook pair β but these hooks do not yet exist.++---++## Decision++Implement the **AgentDB Retrieval Security Layer** across three phases:++### Phase 1 β `AgentDbRetrievalGuard` (retrieval path, 2 sprint estimate)++Add a guard at the HNSW top-K retrieval boundary before chunks are injected into agent context:++```typescript+// v3/@claude-flow/memory/src/agentdb/retrieval-guard.ts+export interface RetrievalGuardConfig {+ maxPayloadBytes: number; // default: 8192 β hard cap per chunk+ injectionPatterns: RegExp[]; // compiled from OWASP LLM01 pattern set+ semanticBoundaryCheck: boolean; // default: true β checks for instruction override tokens+ blockOnSuspicion: boolean; // default: true in prod, false in test+}++export class AgentDbRetrievalGuard {+ async filter(chunks: MemoryChunk[]): Promise<FilteredChunks> {+ // 1. Size gate β reject oversized chunks (injection padding mitigation)+ // 2. Pattern scan β OWASP LLM01/LLM08 pattern set+ // 3. Semantic boundary check β detect role/instruction override patterns+ // 4. Log all rejections to audit trail+ }+}+```++Insert between `HnswIndex.query()` and context assembly in `AgentDbClient.retrieve()`. Expose via:+```bash+CLAUDE_FLOW_RETRIEVAL_GUARD=true # default: false (off until benchmarked)+CLAUDE_FLOW_RETRIEVAL_GUARD_STRICT=false # set true for prod deployments+```++### Phase 2 β `MemoryPoisonForensics` background worker (write path, 3 sprint estimate)++Add a 13th background worker (priority: `critical`, after `audit`) that monitors AgentDB write sequences for anomalous behavioral trajectories:++```typescript+// v3/@claude-flow/hooks/src/workers/memory-poison-forensics.ts+export class MemoryPoisonForensicsWorker implements BackgroundWorker {+ name = 'memory-poison-forensics';+ priority = 'critical';++ async run(context: WorkerContext): Promise<void> {+ // 1. Collect write-sequence features: timing delta, namespace, agent_id, content_hash_delta+ // 2. Compute trust-change score vs rolling 50-write baseline+ // 3. Flag anomalies at 2Ο threshold+ // 4. Emit alert to hooks.notify() channel; quarantine flagged writes if STRICT mode+ }+}+```++Target metric: match arXiv:2606.30566 AUC=0.9904 on an internal eval set of 100 synthetic poisoning trajectories before enabling by default.++### Phase 3 β MCP Caller-Identity Binding (tool dispatch, 1 sprint estimate)++Extend `SafeExecutor` with invocation-bound capability tokens following the AIP pattern (arXiv:2603.24775):++```typescript+// v3/@claude-flow/security/src/mcp-caller-identity.ts+export interface InvocationToken {+ callerId: string; // agent_id of the caller+ toolName: string; // bound at creation β cannot be reused for different tool+ issuedAt: number; // Unix ms+ expiresAt: number; // issuedAt + 30_000 (30s TTL)+ nonce: string; // crypto.randomBytes(16).toString('hex')+ signature: string; // Ed25519 signature over {callerId, toolName, issuedAt, nonce}+}+```++`SafeExecutor.execute()` rejects calls missing a valid `InvocationToken`. Default: gated behind `CLAUDE_FLOW_MCP_CALLER_AUTH=false` until key distribution is solved in a follow-on ADR.++---++## Consequences++### Positive+- Reduces retrieval-layer ASR from ~100% (current) toward SMSR's 0% certified bound+- Adds the first behavioral anomaly detector in AgentDB (AUC=0.9904 is the target)+- Closes OWASP LLM07 + LLM08 gaps not addressed by ADR-165+- Positions Ruflo ahead of LangGraph, AutoGen, CrewAI, and OpenAI Swarm on retrieval security++### Negative / Trade-offs+- `AgentDbRetrievalGuard` adds ~2ms latency per retrieval call (estimated; must benchmark)+- `MemoryPoisonForensics` requires the 13th background worker slot (currently 12 workers)+- Phase 3 MCP caller-identity tokens require key distribution infrastructure (see Phase 3 caveat)++### Neutral+- All three phases are gated behind feature flags; default behavior unchanged until benchmarked+- No breaking changes to existing AgentDB API surface++---++## Implementation Plan++| Phase | File(s) | Sprint | Feature Flag |+|-------|---------|--------|--------------|+| 1 | `v3/@claude-flow/memory/src/agentdb/retrieval-guard.ts` | 1β2 | `CLAUDE_FLOW_RETRIEVAL_GUARD` |+| 2 | `v3/@claude-flow/hooks/src/workers/memory-poison-forensics.ts` | 3β5 | `CLAUDE_FLOW_POISON_FORENSICS` |+| 3 | `v3/@claude-flow/security/src/mcp-caller-identity.ts` | 6 | `CLAUDE_FLOW_MCP_CALLER_AUTH` |++Benchmark gate before each phase ships to `main`: reproduce the respective Grade A paper metric on an internal eval set (SMSR 0% ASR, AUCβ₯0.99, 10/10 blocks).++---++## References++- arXiv:2606.12703 β SMSR: Certified Defense Against Multi-Session RAG Poisoning+- arXiv:2606.30566 β Forensic Trajectory Signatures for Agent Memory Poisoning Detection+- arXiv:2606.26793 β MIRROR: MCTS Red-Teaming for Agentic RAG (ART-SafeBench)+- arXiv:2606.28679 β Capability Gates Are Not Authorization+- arXiv:2606.29073 β Benchmarking Security Invariants in MCP-Style Agent Runtimes+- arXiv:2603.07473 β Caller Identity Confusion in MCP+- arXiv:2601.07072 β Indirect Prompt Injection in the Wild+- arXiv:2603.24775 β AIP: Agent Identity Protocol+- OWASP LLM Top 10 2025 (LLM07, LLM08)diff --git a/v3/docs/adr/README.md b/v3/docs/adr/README.mdindex a78cec92c8..9e7cad5a44 100644--- a/v3/docs/adr/README.md+++ b/v3/docs/adr/README.md@@ -94,6 +94,7 @@ All ADRs are located in [`/v3/implementation/adrs/`](../../implementation/adrs/)| [ADR-374](ADR-374-dream-cycle-swarm-subagent-permission-delegate.md) | SubagentPermissionDelegate: Workspace-Scoped Privilege Delegation for Swarm Agents | Proposed || [ADR-375](ADR-375-dream-cycle-performance-agentperf-benchmark-mixture-of-agents.md) | Agentic Inference Benchmarking Standard + Mixture-of-Agents Test-Time Scaling | Proposed || [ADR-376](ADR-376-dream-cycle-intelligence-heterogeneous-ensemble-api.md) | Heterogeneous Agent Ensemble Composition API | Proposed |+| [ADR-377](ADR-377-agentdb-retrieval-security.md) | AgentDB Retrieval Security Layer | Proposed |## Summary Documentsdiff --git a/v3/docs/dream-cycle/2026-07-01-security-sota.md b/v3/docs/dream-cycle/2026-07-01-security-sota.mdnew file mode 100644index 0000000000..054c809126--- /dev/null+++ b/v3/docs/dream-cycle/2026-07-01-security-sota.md@@ -0,0 +1,66 @@+# Security SOTA Report β 2026-07-01++**TL;DR**: Six 2026 Grade A papers prove Ruflo's AgentDB retrieval pipeline is a high-confidence attack surface: certified defenses cut agent memory poisoning from 93β100% ASR to 0%, but Ruflo has neither a retrieval-layer injection filter nor behavioral forensics β and MCP caller identity remains unauthenticated across all major frameworks.++## What's New in 2026++| Finding | Source | Confidence |+|---------|--------|------------|+| SMSR certified defense cuts multi-session RAG poisoning from 93β100% β 0% | arXiv:2606.12703 (Jun 2026) | A |+| Forensic Trajectory Signatures detect memory poisoning: AUC=0.9904, generalizes across frontier models without retraining | arXiv:2606.30566 (Jun 2026) | A |+| MIRROR: image poisoning ASR 76% vs 52% baseline; ships ART-SafeBench (41,000+ records) | arXiv:2606.26793 (Jun 2026) | A |+| Capability Gates Are Not Authorization: all 3 major frameworks (LangChain, LlamaIndex, Stripe Toolkit) conflate tool exposure with authorization; no fail-closed per-call gate by default | arXiv:2606.28679 (Jun 2026) | A |+| MCP Runtimes: naive baseline fails 10/10 attack cases; HCP mitigation blocks all 10 | arXiv:2606.29073 (Jun 2026) | A |+| MCP Caller Identity Confusion: authorization state persists across callers with no re-auth gate; large-scale audit finding | arXiv:2603.07473 (Mar 2026) | B |+| Indirect Prompt Injection in the Wild: decomposes payloads into retrieval-guaranteed fragments; near-100% retrieval success across 11 benchmarks | arXiv:2601.07072 (Jan 2026) | A |+| OWASP LLM Top 10 2025: two new categories β LLM07 (System Prompt Leakage), LLM08 (Vector and Embedding Weaknesses) | OWASP GenAI 2025 | B |++## Ruflo Current Capability++| Layer | Current State | Gap |+|-------|--------------|-----|+| AgentDB write path | Writes accepted from any swarm agent without content verification | No poison detection before commit |+| AgentDB retrieval path | HNSW retrieves top-K, injects directly into agent context | No injection filter; OWASP LLM08 not addressed |+| MCP caller identity | No caller authentication; `SafeExecutor` validates format/syntax only | Authorization persists without re-auth (arXiv:2603.07473 pattern) |+| Memory anomaly detection | None | No behavioral forensics; AUC=0.9904 detection proven feasible |+| System prompt leakage | No guardrail on prompt exfiltration via tool outputs | OWASP LLM07 not addressed |++## Competitor Comparison++| Framework | RAG/Memory Injection Defense | MCP Caller Auth | Behavioral Forensics | Latest Version |+|-----------|------------------------------|-----------------|----------------------|----------------|+| **LangGraph** | No retrieval-layer filter; only output bleaching | No native caller auth | No | 1.2.7 (Jun 2026) |+| **AutoGen / AG2** | Docker isolation (code only); no RAG layer defense | No | No | 0.12.x Beta |+| **CrewAI** | No documented defense | No | No | 1.14.2 (Apr 2026) |+| **OpenAI Swarm** (deprecated) | N/A β ephemeral context only | N/A | No | Oct 2024 |+| **Ruflo (current)** | None (ADR-165 closes CVE-1β5, not retrieval-layer) | None | None | 3.16.2 |++**All five frameworks share the RAG injection and caller-identity gaps. Ruflo is unique in having an extensible hook system (`post-retrieve`, `pre-context-inject`) that could be the insertion point β but the hooks do not exist yet.**++## Benchmarks++| Benchmark | Metric | Grade | Source |+|-----------|--------|-------|--------|+| SMSR certified defense β multi-session RAG agent | ASR: 93β100% (undefended) β 0% (SMSR, all unsigned variants) | **A** | arXiv:2606.12703, Jun 2026 |+| Forensic Trajectory Signatures β cross-model hold-out | AUC=0.9904 overall; AUC=1.000 on 6/9 frontier-model splits | **A** | arXiv:2606.30566, Jun 2026 |+| MIRROR multimodal RAG attack | Image poisoning ASR 76% vs 52% baseline | **A** | arXiv:2606.26793, Jun 2026 |+| Indirect injection retrieval (WILD) | Near-100% retrieval success across 11 benchmarks | **A** | arXiv:2601.07072, Jan 2026 |+| HCP MCP runtime mitigation | 10/10 attacks blocked (vs 0/10 naive baseline) | **A** | arXiv:2606.29073, Jun 2026 |++## SOTA Proof & Witness++| Field | Value |+|-------|-------|+| Session commit | `1a887969548b58e77f7853fedca922fc1cb5c6aa` |+| Report SHA-256 | `df009e8f56b505a827689066cf53ee1761b75360f21dc227427e939179837135` |+| Witness stamp | `aa9f66df228edde5ec6a529b6afb79cb490941d4aaf92395d0ff553b3b8f01a0` |++*Verifier: `printf '%s%s' 'df009e8f56b505a827689066cf53ee1761b75360f21dc227427e939179837135' '1a887969548b58e77f7853fedca922fc1cb5c6aa' | sha256sum` β must yield `aa9f66df228edde5ec6a529b6afb79cb490941d4aaf92395d0ff553b3b8f01a0`*++## Recommended Next Steps++1. **Add `AgentDbRetrievalGuard` to the read path** (`v3/@claude-flow/memory/src/agentdb/retrieval-guard.ts`): run each retrieved chunk through a lightweight injection detector (regex + semantic boundary check) before injecting into agent context. Target: reduce retrieval-layer ASR from ~100% (current) toward SMSR's 0% certified bound. Priority: **High** (ADR-180).++2. **Implement `MemoryPoisonForensics` background worker** (13th worker slot, priority: `critical`): record behavioral trajectory signatures on each AgentDB write sequence; flag anomalies where trust-change score exceeds 2Ο baseline. SOTA benchmark: AUC=0.9904 is achievable without retraining across frontier models (arXiv:2606.30566).++3. **Add MCP caller-identity binding to `SafeExecutor`**: every MCP tool invocation must carry an invocation-bound capability token (AIP-style, arXiv:2603.24775); `SafeExecutor` rejects calls without a fresh per-invocation token. This closes the caller-identity persistence gap (arXiv:2603.07473) and satisfies OWASP LLM07 (system prompt leakage via tool channel).