A2A Core Defense

Capa de defensa empaquetada para el ecosistema Agent2Agent (A2A) y los protocolos de comercio agentico (AP2/ACP). Protege despliegues multi-agentes frente a las clases de ataque que la investigación de 2025-2026 ya ha cuantificado y que el SDK de referencia oficial (a2aproject/a2a-python) aún no cierra por defecto.

Alcance honesto (post-auditoría): este shield mitiga las superficies de ataque listadas abajo; no las elimina por sí solo. El server A2A debe usarlo como capa de validación delante de sus operaciones. No es un fork del SDK oficial ni un reemplazo de la autenticación de transporte (TLS/mTLS/OAuth).

Por qué existe (gap real, no teórico)

• a2aproject/a2a-python issue #786 (OPEN, 2026): SSRF en webhooks de push notification y ausencia de autorización por operación. El mantenedor confirma el gap; el fix de SSRF sigue pendiente (#1023).
• arXiv:2608.23858 — Beyond the Mandate: Security Analysis of AP2 (Google).
• arXiv:2608.24069 — Poisoning Agentic Alpha: vulnerabilidades adversariales en comunicación inter-agentes de trading multi-agent.
• arXiv:2608.02698 / 2604.01151 — colusión encubierta en poblaciones de agentes.

Qué hace (7 fases)

1. Parseo del envelope contra el esquema oficial.
2. Auth de conexión (asume TLS/OAuth aguas afuera).
3. Capability tokens con scope por operación (Ed25519): sub/resource/actions/jti. Si no se provee card_public_key, los tokens NO se verifican por firma (degradación documentada; úsalo solo en dev).
4. SSRF guard en webhooks: bloquea file:///gopher://, IPs loopback/privadas, metadata cloud (169.254.169.254), con DNS-rebinding protection y IP pinning en el envío real (anti-TOCTOU). El server debe usar send_push_notification() para disparar el webhook.
5. Agent Card firmada: canonicalización RFC 8785 (evita bug #1174) + verificación.
6. Detección de colusión encubierta black-box en mensajes inter-agentes.
7. Traza forense hash-encadenada para attribution. Vive en memoria del proceso; no persiste a disco (limitación conocida, ver SPEC §7).

Instalación

python -m venv .venv && . .venv/bin/activate
pip install -e .

Uso

# Auditar un endpoint remoto (hace fetch real del Agent Card) o un snippet local
a2a-defend audit https://tu-agente.example.com/.well-known/agent.json

# Proxy inspector delante del server A2A. Extrae el principal del request
# (Bearer sub / X-A2A-Caller). Con --card-public-key verifica firma de tokens.
a2a-defend serve --listen 127.0.0.1:8080 --upstream https://tu-agente.example.com \
    --card-public-key pub.pem [--strict]

# Emitir un capability token de prueba
a2a-defend token --sub agent-a --resource 'a2a://server/*' --actions a2a.send,a2a.get

Como biblioteca:

from a2a_core_defense import DefensePipeline, PipelineConfig
from a2a_core_defense.phases.ssrf_guard import send_push_notification

pipe = DefensePipeline(PipelineConfig(strict_card=True, card_public_key=pub_key))
verdict = pipe.inspect(raw_envelope, caller="agent-a", capability_token_raw=token_raw)
# Para disparar un webhook de forma segura (IP fijada):
await send_push_notification(url, payload)

Limitaciones conocidas

• serve extrae el principal del request (header Authorization: Bearer sub o X-A2A-Caller). Ese principal es identidad AUTO-DECLARADA: el proxy no verifica la firma del JWT ni de otro token; si el proxy es el borde de red sin firma verificada aguas arriba, es falsificable. En modo no-estricto (por defecto) una operación sensible sin principal se marca WARN y se deja pasar; con --strict se DENIEGA.
• Sin card_public_key, los capability tokens se aceptan sin verificar firma (degradación documentada para dev). Proporcionar --card-public-key en producción.
• La traza forense (Fase 7) no persiste entre reinicios.
• El pinning anti-TOCTOU del webhook (Fase 4) usa request.extensions["sni_hostname"]: la conexión TCP va a la IP ya validada y el cert TLS se verifica contra el host real, así que webhooks HTTPS estándar funcionan. Solo se aplica si el server usa send_push_notification() para disparar el webhook, no con httpx.post crudo.
• El fetch remoto de audit pasa por el validador SSRF antes de httpx.get.
• No cubre RAG poisoning (véase nicho independiente).

Licencia

AGPL-3.0-or-later — Copyright (C) 2026 Pedro Sordo Martínez — amurlaniakea@gmail.com

Ver LICENSE.