agent-shield-runtime v0.1.0: hook de despliegue que conecta 5 sensores de defensa de agentes IA

agent-shield-runtime v0.1.0: hook de despliegue que conecta 5 sensores de defensa de agentes IA

Los sensores de defensa de un agente no sirven si nada los invoca. Este repo intercepta cada tool-call y lo evalúa contra 5 sensores antes de ejecutarlo.

El problema

En el ecosistema de defensa de agentes IA (scope-lib, adi-shield, wallet-guard, goal-anchor, trajectory-sentinel) los 5 sensores están implementados y auditados. Pero son librerías: nadie los invoca en un agente real. Con los paquetes instalados y sin un hook, el agente ejecuta sus tool-calls directos y los sensores se quedan en disco. La detección que demostramos en tests unitarios no ocurre en producción.

La solución

agent-shield-runtime es el sexto repositorio: un hook de despliegue que intercepta cada tool-call del agente y lo despacha a los 5 sensores en orden, antes de ejecutarlo:

• scope-lib - evaluación de alcance (3 criterios, fail-safe).
• adi-shield - detección de inyección de prompt (ADI) en 5 vectores.
• wallet-guard - guardrails de bucle y presupuesto.
• goal-anchor - integridad de objetivo (deriva brusca).
• trajectory-sentinel - correlación agregada de señales vía bus compartido.

Si cualquier sensor dice block, la acción NO se ejecuta. Si hay confirm, se pausa a humano. Solo si todos dicen allow se ejecuta el tool nativo.

Cómo funciona

El runtime envuelve el executor del agente. El núcleo solo conoce GenericToolCall; los adaptadores de framework (LangChain, AutoGen, loop propio) traducen el tool-call nativo a ese formato y viven aislados. Así el runtime es reutilizable sin acoplarse a ningún agente concreto, y los 5 sensores no cambian: este repo solo orquesta.

Resultados verificados

• 5 tests de integración end-to-end (tests/test_integration_e2e.py) contra los 5 sensores REALES instalados (sin mocks de sensor):
  • AC1 (deny bloquea y no ejecuta)
  • AC2 (inyección ADI bloquea)
  • AC3 (deriva brusca confirma)
  • AC5 (integración sin modificar los sensores)
• CI verde en GitHub Actions (ruff + pytest + bandit + gitleaks) en entorno limpio.
• Licencia AGPL-3.0-or-later (texto oficial FSF verbatim).

Lo que queda abierto (honestamente)

• WebTrap sutil no se cierra. El hook extiende la cobertura de despliegue, no la de detección. Los vectores de deriva sutil que preservan apariencia de alcance (T1/T2/T4) siguen sin detectarse en la Capa 1 de goal-anchor (benchmark corregido: TPR=0.25 real, FPR=0.0). Cerrarlos requiere semántica real, descartada por peso en esta fase.
• Adaptador de framework real pendiente. Hoy solo el adaptador genérico; el cableado al executor nativo de LangChain/AutoGen es el siguiente hito (H3).
• Auditoría independiente en curso. El repo se hizo público para que un auditor externo lo clone y verifique en fresco.

Pruébalo

git clone https://github.com/amurlaniakea/agent-shield-runtime.git
cd agent-shield-runtime
python -m venv .venv && . .venv/bin/activate
pip install -e .
pytest

Stack

Links

• Repo: https://github.com/amurlaniakea/agent-shield-runtime
• Sensores: scope-lib, adi-shield, wallet-guard, goal-anchor, trajectory-sentinel
• Licencia: AGPL-3.0-or-later · Autor: Pedro Sordo Martínez

Top comments (2)

I like that this project focuses on the deployment gap rather than inventing yet another detector. A security library that never sits on the execution path protects nothing, so introducing a runtime interception layer is a practical contribution. What I’d love to see next is more detail on the orchestration itself. Are the five sensors evaluated sequentially for policy reasons, or could independent checks run in parallel to reduce latency? How are conflicting decisions (allow, confirm, block) resolved, and what are the timeout or fail-open/fail-close semantics if a sensor becomes unavailable? I also think the upcoming LangChain/AutoGen adapters will be the real milestone. Once the runtime can sit transparently in front of a production agent framework, it will be much easier to evaluate the operational cost and the actual security benefit beyond unit and integration tests.

Thank you, and you are spot on regarding what is missing. Today, ShieldRuntime.execute evaluates the 5 sensors sequentially and in a blocking manner: scope → adi-shield → wallet-guard → goal-anchor → trajectory-sentinel. This is not due to a policy decision, but because it was the first verifiable version; in reality, scope, adi, and wallet are independent and could run in parallel to cut down latency, whereas goal-anchor and the correlator do depend on the previous state (the anchor and the bus). Conflict resolution follows a worst-verdict policy: any 'block' wins and the action is not executed; if there is a 'confirm' and no 'block', it pauses for human intervention (or blocks if block_on_confirm is set); only a unanimous 'allow' grants execution. The point where you are right and work is still needed: there is no timeout nor configurable fail-open/fail-close semantics. Today, if a sensor throws an exception, execute breaks and the tool does not run (implicit fail-closed, but it is neither an explicit nor a configurable decision, and if a sensor hangs, the agent freezes). This is noted as a risk in the SDD and is part of the next milestones, along with the framework adapters, which I agree are the real leap to measure operational cost and benefits beyond unit/integration tests. Thank you very much for your sharp observation, I am getting to work on it right away. Aloha.