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
| Componente | Rol |
|---|---|
| ShieldRuntime | intercepta y decide block/confirm/allow |
| GenericToolCall | formato interno neutro |
| LocalSignalBus | bus compartido de señales |
| los 5 sensores | evaluación por especialidad |
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 (3)
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.
Thanks for the detailed explanation. I actually like that you explicitly distinguish between “not implemented yet” and “intentional design”—that’s something many security projects gloss over. One question that came to mind is cancellation. If an early sensor already returns block, do you plan to immediately cancel the remaining sensor evaluations, or let them finish for audit and telemetry purposes? It feels like there’s an interesting trade-off between minimizing latency and collecting enough evidence for post-incident analysis. I’m curious which direction you’re leaning toward.