mirror of https://github.com/ruvnet/ruflo.git synced 2026-09-14 14:01:28 +08:00

Files

T

rUv 5f81112467 docs(adr): consolidate 49 stale dream-cycle proposals, renumber ADR-334..376 (#2871 )

The dream-cycle bot has opened a research proposal draft PR nightly since
2026-05-29. None had ever been merged (tracked in #2324), so each night's
run guessed ADR numbers against a stale view of main and collided
repeatedly — ADR-147 alone was independently claimed by 4 different
proposals (#2304, #2310, #2317, plus a README-only PR #2278), and ADR-179
by another 4 (#2617, #2624, #2631, #2656, plus README-only #2642).

This consolidates the SOTA research reports and ADR proposal text from
all 49 open dream-cycle drafts into a single reviewable change:
- 43 ADR proposals renumbered sequentially into ADR-334 through ADR-376
  (first-opened-first-numbered), with self-referencing ADR-N mentions
  inside each file updated to match
- 4 branches that contained only a SOTA report with no ADR proposal
  (#2368, #2382, #2430, #2607) carried over as-is
- 2 branches that only added a README index row for an ADR file they
  didn't otherwise include (#2278 for ADR-147, #2642 for ADR-179) are
  superseded by the real ADR-147/179 claimants above and dropped
- v3/docs/adr/README.md gets one clean set of index rows instead of 43
  individually conflicting ones

All ADRs land as Proposed — none of this is an implementation decision,
just clearing 2 months of unreviewed nightly research out of PR limbo so
it can actually be read. The original 49 PRs are closed with a pointer
to this commit.

Closes #2224, #2242, #2249, #2255, #2266, #2278, #2304, #2310, #2317, #2333, #2344, #2363, #2368, #2379, #2382, #2394, #2402, #2420, #2430, #2436, #2457, #2463, #2472, #2479, #2486, #2496, #2511, #2527, #2537, #2560, #2577, #2598, #2607, #2617, #2624, #2631, #2642, #2656, #2665, #2702, #2716, #2728, #2740, #2753, #2761, #2764, #2769, #2779, #2793

2026-07-30 13:12:32 -04:00

5.3 KiB

Raw Permalink Blame History

ADR-346: Multi-Layer Agent Security Stack

Status: Proposed
Date: 2026-06-16
Authors: claude (dream-cycle agent, 2026-06-16)
Supersedes: Partially extends ADR-012 (MCP Security), ADR-144 (Agent Authorization), ADR-145 (Plugin Supply Chain), ADR-146 (Tool Output Guardrails)

Context

Nightly dream-cycle research (2026-06-16, SLOT=1, DEEP=security) surfaced three Grade A benchmarks establishing a critical gap:

ClawSafety (arXiv:2604.01438): Agent attack success rate (ASR) 40–75% across 5 frontier models in 2,520 sandboxed trials. Safety is determined by the full deployment stack, not just the backbone model. Skill-instruction injection (matching Ruflo's hooks/plugins) is the highest-trust, highest-risk vector.
MCP Threat Coverage (arXiv:2604.05969): 7 threat categories, 23 distinct attack vectors across 177K+ deployed MCP tools. No single defense covers more than 34% of the threat landscape. An integrated MCPSHIELD approach (capability-based access control + cryptographic attestation + information flow tracking + runtime policy) achieves 91% coverage.
OWASP Top 10 for Agentic Applications 2026 (published Dec 2025): ASI01 = Agent Goal Hijacking is ranked #1. ASI02 = Unauthorized Capability Escalation. These risks are unmitigated in Ruflo's current stack.

Ruflo's existing security layers (InputValidator, PathValidator, SafeExecutor, ADR-144/145/146) provide single-layer boundary validation estimated at ~34% threat coverage — the floor identified for isolated defenses. Ruflo exposes 314 registered MCP tools and 60+ hooks/skills that are currently unattestad against injection via tool environment.

Decision

Implement a multi-layer agent security stack in @claude-flow/security comprising three coordinated layers:

Layer 1 — MCP Tool Attestation

Cryptographic signing of tool manifests at registration time
Signature verification at every tool invocation in the MCP server
Capability-based access control: tools declare required capabilities; agents are granted minimum necessary
Revocation list for compromised tools
Target: covers threat categories TC-1 (tool spoofing), TC-2 (capability escalation), TC-5 (protocol tampering)

Layer 2 — Indirect Prompt Injection Monitoring

Content sanitization pipeline at hook chokepoints: pre-task, post-edit, pre-command
Pattern detection for instruction-injection signatures in tool outputs, environment variables, and skill payloads
Quarantine mode: flag suspicious payloads for human review before agent execution
Integrates into existing SafeExecutor in @claude-flow/security
Target: addresses ClawSafety's highest-risk vector (skill-instruction injection)

Layer 3 — Agent Action Audit Trail with Checkpointing

Append-only audit log of every agent action (tool call, memory write, file operation, hook execution)
Checkpoint state snapshot per task boundary, stored in AgentDB
Rollback trigger: detected Goal Hijacking (ASI01) signals halt + restore from last clean checkpoint
Expose audit trail via @claude-flow/cli security audit command
Target: closes the LangGraph 0.4 feature gap; enables post-hoc forensics and OWASP compliance evidence

Consequences

Positive

Raises estimated threat coverage from ~34% to ≥80% (target 91% with full MCPSHIELD alignment)
Closes OWASP Agentic ASI01 and ASI02 gaps
Makes Ruflo the first open-source agent framework with MCP-native tool attestation
Enables enterprise compliance evidence for agentic AI security audits
Competitive differentiation: LangGraph, CrewAI, AutoGen, OpenAI Swarm have no MCP tool attestation

Negative

Attestation adds latency to tool registration and invocation (~1-5ms per call, within <100ms MCP target)
Audit trail increases AgentDB write volume; requires TTL/rotation policy
Breaking change for unregistered or externally-sourced MCP tools (migration guide required)

Neutral

Layer 2 sanitization may produce false positives on legitimate complex tool outputs; tunable threshold
Checkpoint storage in AgentDB uses existing HNSW backend with new audit namespace

Implementation Plan

@claude-flow/security: Add ToolAttestation class (Layer 1) — key pair generation, manifest signing, verification middleware
@claude-flow/security: Extend SafeExecutor with injection pattern detection (Layer 2)
@claude-flow/memory: Add audit namespace with append-only writes and TTL (Layer 3)
@claude-flow/cli: Add security audit and security attestation subcommands
Migration: npx claude-flow@latest security attestation --init to sign all registered MCP tools
Tests: TDD London School — mock tool registry + inject adversarial payloads; verify quarantine triggers

References

arXiv:2604.01438 — ClawSafety: "Safe" LLMs, Unsafe Agents
arXiv:2604.05969 — Formal Security Framework for MCP-Based AI Agents
arXiv:2506.23260 — From Prompt Injections to Protocol Exploits: Threats in LLM-Powered AI Agents Workflows
arXiv:2603.15408 — TrinityGuard: A Unified Framework for Safeguarding Multi-Agent Systems
OWASP Top 10 for Agentic Applications 2026 — https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/
Dream-cycle research gist: v3/docs/dream/2026-06-16-security-report.md

5.3 KiB Raw Permalink Blame History Unescape Escape