AgentGuard

Seguridad de identidad para agentes de IA

AgentGuard es una capa de autorización consciente de la identidad para agentes de IA autónomos.

Otorga a cada agente su propia identidad de máquina, limita el acceso con ámbitos OAuth, evalúa políticas contextuales antes de que se ejecuten acciones sensibles e introduce un límite de aprobación humana autenticada por separado cuando la autoridad autónoma debe detenerse.

Producto en vivo:
https://agentguard-eight.vercel.app

Backend de autorización MCP:
https://github.com/haisamar/agentguard-mcp

El problema

Los agentes de IA se conectan cada vez más a sistemas reales:

• CRMs

• herramientas financieras

• plataformas de soporte

• APIs internas

• bases de datos

• servidores MCP

Pero conectar un agente a una herramienta plantea una pregunta de seguridad:

Solo porque un agente pueda autenticarse, ¿debería poder hacer todo lo que la herramienta admite?

Normalmente, no.

Un agente de ventas puede necesitar:

read CRM accounts
update opportunities
inspect support context

pero no debería poder automáticamente:

issue refunds
export customer data
modify security settings

E incluso un agente de finanzas que legítimamente tiene permisos de reembolso puede necesitar aprobación humana antes de emitir un reembolso de alto valor.

AgentGuard demuestra cómo la identidad, la autorización, la política contextual y el control humano pueden combinarse en capas en torno a la ejecución de agentes de IA.

Qué hace AgentGuard

AgentGuard separa la autorización en múltiples límites de seguridad:

AI Agent
   ↓
Machine Identity
   ↓
OAuth Scope Authorization
   ↓
Contextual Policy
   ↓
Human Approval if Required
   ↓
Controlled Execution
   ↓
Audit Trail

La autenticación por sí sola no implica autoridad ilimitada.

Demostración en vivo

La demostración pública se puede explorar sin autenticación:

https://agentguard-eight.vercel.app/demo

Contiene tres escenarios de autorización reales y persistidos.

Related MCP server: Oakallow MCP Server

Escenario 1 — Aprobado por humano

Un agente de finanzas solicita un reembolso de $750.

Finance Agent
      ↓
Authenticated machine identity
      ↓
finance:refund scope verified
      ↓
Refund exceeds $500 autonomous threshold
      ↓
APPROVAL_REQUIRED
      ↓
Authenticated human administrator approves
      ↓
Finance Agent executes approved refund
      ↓
ALLOW

Estado final:

EXECUTED

Escenario 2 — Denegado por humano

El mismo agente de finanzas solicita otro reembolso de $750.

El agente tiene el permiso OAuth correcto, por lo que la solicitud supera la verificación de ámbito.

Sin embargo, la política contextual requiere aprobación humana.

Finance Agent
      ↓
finance:refund ✓
      ↓
Refund > $500
      ↓
APPROVAL_REQUIRED
      ↓
Human Administrator
      ↓
DENY
      ↓
Finance Agent attempts execution
      ↓
DENY

Estado final:

DENIED

Esto demuestra que:

Estar autorizado para solicitar una acción no significa necesariamente que el agente esté autorizado para ejecutarla de forma autónoma.

Escenario 3 — Bloqueado por ámbito

Un agente de ventas intenta emitir un reembolso.

Su identidad contiene:

crm:read
crm:write
support:read

pero la herramienta protegida requiere:

finance:refund

AgentGuard bloquea la solicitud de inmediato.

Sales Agent
      ↓
Authenticated
      ↓
Missing finance:refund
      ↓
DENY

La política contextual nunca se evalúa.

La revisión humana nunca se alcanza.

La solicitud falla en el límite de autorización de privilegio mínimo.

Arquitectura

AgentGuard separa la autenticación de máquina, la autorización de privilegio mínimo, las decisiones de riesgo contextual y la aprobación humana para que un agente de IA autenticado nunca reciba automáticamente autoridad ilimitada.

flowchart LR
    AGENT["AI Agent<br/>Sales / Finance"]
    AUTH0M["Auth0<br/>Machine Identity"]
    TOKEN["OAuth Access Token<br/>Scoped Permissions"]
    MCP["AgentGuard MCP<br/>Protected Tools"]
    SCOPE{"Scope<br/>Authorized?"}
    POLICY{"Contextual<br/>Policy"}
    APPROVAL["Approval Request<br/>Persisted"]
    AUTH0H["Auth0<br/>Human Identity"]
    HUMAN{"Human<br/>Decision"}
    EXEC["Controlled<br/>Execution"]
    BLOCK["Execution<br/>Blocked"]
    DB[("Supabase<br/>Approvals + Audit")]

    AGENT --> AUTH0M
    AUTH0M --> TOKEN
    TOKEN --> MCP
    MCP --> SCOPE

    SCOPE -->|"Missing scope"| BLOCK
    SCOPE -->|"Authorized"| POLICY

    POLICY -->|"Low risk"| EXEC
    POLICY -->|"Forbidden"| BLOCK
    POLICY -->|"Sensitive"| APPROVAL

    APPROVAL --> DB
    APPROVAL --> AUTH0H
    AUTH0H --> HUMAN

    HUMAN -->|"Approve"| EXEC
    HUMAN -->|"Deny"| BLOCK

    EXEC --> DB
    BLOCK --> DB

Modelo de identidad

AgentGuard separa deliberadamente las identidades de máquina de las identidades humanas.

Identidades de máquina

Cada runtime de agente recibe una identidad Auth0 Machine-to-Machine separada.

La demostración contiene tres runtimes.

Esto evita que varios agentes compartan una única credencial con privilegios amplios.

Identidad humana

Las decisiones sensibles se revisan a través de un usuario de Auth0 autenticado por separado.

El administrador humano no es la misma identidad que la máquina solicitante.

Ejemplo:

Requested by
Finance Agent
Machine Identity

Reviewed by
Human Administrator
Human Identity

Esto crea una separación clara entre:

machine authority

y:

human approval authority

Modelo de autorización

AgentGuard utiliza autorización en capas.

1. Autenticación

Auth0 establece la identidad del agente que llama.

El servidor MCP recibe un token de acceso OAuth que contiene la identidad de la máquina.

2. Autorización por ámbito OAuth

Cada herramienta MCP protegida declara el permiso necesario para llamarla.

Ejemplo:

issue_refund
requires
finance:refund

Si el agente no tiene el ámbito requerido:

DENY

No se necesita evaluación de políticas ni escalamiento humano.

3. Política contextual

Superar una verificación de ámbito OAuth no garantiza automáticamente la ejecución.

AgentGuard evalúa el contexto de la acción solicitada.

Las reglas de demostración actuales incluyen:

Refund <= $500
→ ALLOW

Refund > $500
→ APPROVAL_REQUIRED

Customer data export
→ APPROVAL_REQUIRED

Customer deletion
→ DENY

Esto separa:

Can this identity request this type of operation?

de:

Should this exact operation execute autonomously?

4. Autorización con intervención humana

Las operaciones sensibles se pausan y se persisten.

El panel de administración protegido muestra la solicitud pendiente.

El humano autenticado puede entonces elegir:

Approve

o:

Deny

La decisión se persiste y se añade al registro de auditoría de seguridad.

5. Ejecución vinculada a aprobación

Una aprobación humana no ejecuta directamente la acción.

La identidad de máquina original regresa y solicita la ejecución.

AgentGuard entonces verifica:

Does the approval exist?

Is it APPROVED?

Does the approval belong to this agent?

Does it match this action?

Has it already been executed?

Solo entonces puede continuar la ejecución.

6. Protección contra reproducción

Las aprobaciones ejecutadas correctamente pasan a:

EXECUTED

Un segundo intento de ejecutar la misma aprobación se bloquea.

EXECUTED
      ↓
second execution attempt
      ↓
DENY

El intento de reproducción se registra como un evento de seguridad.

Consola de administración

El panel protegido está disponible en:

/dashboard

Requiere autenticación de Auth0.

La consola de administración proporciona:

• inventario de identidades de máquina

• ámbitos OAuth concedidos

• contexto de operador humano autenticado

• aprobaciones pendientes

• controles de aprobar / denegar

• explorador de trazas de autorización

• fuente de actividad de seguridad

• inspección detallada de eventos de auditoría

• historial de aprobaciones

• visualización de identidad de máquina vs. humana

La identidad sin procesar y el contexto de auditoría permanecen detrás de la autenticación.

Demostración pública

La demostración pública existe por separado en:

/demo

Es intencionalmente de solo lectura.

Antes de que los datos lleguen al navegador, se elimina la información de seguridad privada.

La demostración pública no expone:

Auth0 subject IDs
machine client IDs
administrator email addresses
OAuth access tokens
Supabase credentials
raw audit metadata
private approval identifiers

La interfaz pública recibe solo datos de escenario desinfectados.

Explorador de trazas de autorización

AgentGuard incluye un explorador de trazas interactivo que reconstruye escenarios de seguridad persistidos.

Los usuarios pueden cambiar entre:

Human Approved
Human Denied
Scope Blocked

Cada traza visualiza:

01 Agent Identity

02 Scope Check

03 Contextual Policy

04 Human Review

05 Execution

Esto hace que el ciclo de vida de la autorización sea comprensible sin necesidad de acceder al Inspector MCP, al panel de Auth0 ni a la base de datos.

Actividad de seguridad

Cada decisión de autorización importante se registra como un evento de auditoría.

Ejemplos de decisiones incluyen:

ALLOW
DENY
APPROVAL_REQUIRED
APPROVED

Seleccionar un evento abre un panel de seguridad detallado que contiene información como:

Identity
Identity Type
Decision
Action
Required Scope
Reason
Approval Reference
Timestamp
Event ID
Security Metadata

Ejemplo de fallo de autorización:

Sales Agent

Action
issue_refund

Decision
DENY

Required Scope
finance:refund

Granted Scopes
crm:read
crm:write
support:read

Missing Scope
finance:refund

Security Event
authorization_failure

Ciclo de vida de aprobación

Las acciones sensibles se representan mediante registros de aprobación persistidos.

Estados disponibles:

PENDING
APPROVED
DENIED
EXECUTED

Flujo exitoso:

PENDING
   ↓
APPROVED
   ↓
EXECUTED

Flujo denegado:

PENDING
   ↓
DENIED

AgentGuard también separa:

reviewed_by

de:

approved_by

para que una solicitud denegada pueda representar correctamente:

status      = DENIED
reviewed_by = Human Administrator
approved_by = null

Tecnología

AgentGuard está construido con:

Identidad y autorización

Auth0
OAuth 2.0
Machine-to-Machine Applications
Human Authentication
Scoped Access Tokens

Interfaz de agente

Model Context Protocol
FastMCP

Backend

Python
Starlette
Uvicorn

Aplicación

Next.js 16
React
TypeScript
Tailwind CSS

Persistencia

Supabase
PostgreSQL
Row Level Security

Despliegue

Vercel
GitHub

Estructura del repositorio

agentguard/
│
├── src/
│   ├── app/
│   │   ├── dashboard/
│   │   │   ├── ApprovalButtons.tsx
│   │   │   ├── SecurityActivity.tsx
│   │   │   ├── TraceExplorer.tsx
│   │   │   ├── actions.ts
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   │
│   │   ├── demo/
│   │   │   ├── PublicTraceExplorer.tsx
│   │   │   └── page.tsx
│   │   │
│   │   └── page.tsx
│   │
│   ├── lib/
│   │   ├── agentguard-data.ts
│   │   ├── auth0.ts
│   │   └── public-demo-data.ts
│   │
│   └── proxy.ts
│
├── package.json
└── README.md

El servidor de autorización MCP de Python se mantiene por separado:

https://github.com/haisamar/agentguard-mcp

Servidor MCP backend

El backend complementario implementa:

• validación de tokens de acceso de Auth0

• metadatos OAuth de recursos protegidos

• autorización de herramientas MCP

• aplicación de ámbito requerido

• evaluación de políticas contextuales

• creación de aprobaciones

• aplicación de aprobación humana

• ejecución vinculada a aprobación

• protección contra reproducción

• persistencia en Supabase

• registro de auditoría de seguridad

Repositorio del backend:

https://github.com/haisamar/agentguard-mcp

Herramientas MCP

El prototipo de seguridad actual incluye:

search_accounts
issue_refund
list_pending_approvals
approve_action
execute_approved_refund

Ejemplo:

Finance Agent
finance:refund
      ↓
issue_refund($100)
      ↓
ALLOW

versus:

Finance Agent
finance:refund
      ↓
issue_refund($750)
      ↓
APPROVAL_REQUIRED

versus:

Sales Agent
no finance:refund
      ↓
issue_refund($750)
      ↓
DENY

Seguridad de la base de datos

Los registros de aprobación y auditoría viven en Supabase/PostgreSQL.

La seguridad a nivel de fila está habilitada en las tablas subyacentes.

No se definen intencionalmente políticas públicas de navegador para los registros sensibles de AgentGuard.

Los componentes del lado del servidor utilizan credenciales de entorno protegidas.

La clave secreta de Supabase nunca se envía a JavaScript del lado del cliente.

La información de la demostración pública se desinfecta en el lado del servidor antes de pasarse a los componentes interactivos del cliente.

Desarrollo local

Requisitos

Node.js
Auth0 tenant
Supabase project
AgentGuard MCP backend

Clonar:

git clone https://github.com/haisamar/agentguard.git
cd agentguard

Instalar:

npm install

Crear:

.env.local

con tu propia configuración de entorno.

Variables de ejemplo:

SUPABASE_URL=
SUPABASE_SECRET_KEY=

AUTH0_DOMAIN=
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
AUTH0_SECRET=

APP_BASE_URL=http://localhost:3000

AGENTGUARD_ADMIN_EMAIL=

Nunca hagas commit de .env.local.

Ejecutar:

npm run dev

Luego abre:

http://localhost:3000

Modelo de rutas

/
Public product page

/demo
Public sanitized security demo

/dashboard
Auth0-protected administrator console

Esta separación permite que el proyecto siga siendo fácilmente revisable como proyecto de portafolio sin exponer funcionalidad administrativa privilegiada.

Producción

El frontend está desplegado en Vercel:

https://agentguard-eight.vercel.app

La autenticación de producción utiliza una aplicación web regular de Auth0 con URL de devolución de llamada, cierre de sesión y origen explícitas de producción.

Los secretos se almacenan como variables de entorno de Vercel y no se confirman en Git.

Límites de seguridad demostrados

AgentGuard demuestra varios conceptos de seguridad de identidad en un solo sistema:

Autenticación ≠ Autorización

Un agente autenticado aún puede ser denegado.

Privilegio mínimo

Los agentes reciben solo los ámbitos que su rol requiere.

Autorización consciente del contexto

La autorización puede depender de los detalles de la acción, no solo de la persona que llama.

Separación de funciones

Una máquina puede solicitar una acción mientras un humano la aprueba de forma independiente.

Control humano en el bucle

La ejecución autónoma puede detenerse en límites de riesgo definidos.

Ejecución vinculada a aprobación

La aprobación se asocia con la identidad solicitante y la acción.

Protección contra reproducción

Las aprobaciones previamente ejecutadas no se pueden reutilizar.

Auditabilidad

Las decisiones de autorización se persisten con identidad y contexto de decisión.

Separación pública / privada

Los visitantes del portafolio pueden explorar escenarios desinfectados sin obtener acceso a datos administrativos.

Lo que quería explorar

AgentGuard se construyó para explorar una pregunta:

¿Cómo se ve la seguridad de identidad cuando el usuario no siempre es un humano?

La seguridad de aplicaciones tradicional a menudo asume que las personas se autentican y luego interactúan con los sistemas directamente.

Los agentes de IA cambian ese modelo.

Los runtimes autónomos pueden:

call APIs
use tools
modify records
trigger workflows
take financial actions

Eso hace que la identidad y la autorización sean cada vez más importantes en la capa de agentes.

AgentGuard explora cómo conceptos familiares de IAM como:

machine identity
OAuth scopes
least privilege
separation of duties
human approval
auditability

pueden aplicarse a la ejecución de agentes de IA.

Alcance actual

AgentGuard es un prototipo de portafolio de seguridad, no un producto IAM de producción.

Algunos límites intencionales incluyen:

• las políticas contextuales se definen actualmente en código

• las identidades de máquina se asignan a roles de demostración

• la autorización de administrador humano actualmente usa una lista de permitidos a nivel de aplicación

• la gestión de políticas aún no tiene su propio plano de control

• los registros de auditoría de la base de datos no son criptográficamente inmutables

• el bloqueo distribuido de producción está fuera del alcance del prototipo

• el despliegue del backend MCP está diseñado para pruebas controladas

• la expiración de aprobaciones no está implementada actualmente

Estas limitaciones se documentan deliberadamente en lugar de ocultarse.

Posibles extensiones

Las versiones futuras podrían explorar:

Auth0 role-based administration
policy-as-code
policy versioning
agent identity registry
workload identity federation
delegated authorization
resource-level authorization
organization isolation
approval expiration
time-bound privileges
step-up authentication
signed audit events
SIEM integration
policy simulation
risk scoring
dynamic authorization
production MCP deployment

Repositorio relacionado

AgentGuard MCP

Servidor de autorización Python, motor de políticas, aplicación de aprobaciones y persistencia de auditoría:

https://github.com/haisamar/agentguard-mcp

Proyecto en vivo

AgentGuard

https://agentguard-eight.vercel.app

Demostración interactiva

https://agentguard-eight.vercel.app/demo

Consola de administrador

https://agentguard-eight.vercel.app/dashboard

Autenticación requerida.