AWS Bedrock AgentCore Gateway con Policy Engine

Sistema de automatización DevOps con control de acceso basado en políticas Cedar usando AWS Bedrock AgentCore.

⚠️ IMPORTANTE: Este es código de demostración para el artículo Controlando Agentes de IA con Políticas Cedar en AWS Bedrock AgentCore. NO está diseñado para uso en producción. El propósito es ilustrar los conceptos y capacidades de AgentCore Policy Engine de forma educativa.

Descripción

Este proyecto implementa un Gateway de AgentCore con Policy Engine que controla el acceso a herramientas de automatización DevOps mediante políticas de seguridad determinísticas. Las políticas están escritas en Cedar, el lenguaje de políticas de código abierto de AWS.

Casos de uso ilustrados:

Control de acceso basado en entorno (staging vs production)
Políticas condicionales basadas en parámetros de entrada
Enforcement de reglas de negocio mediante Cedar
Observability completa con CloudWatch Logs y X-Ray

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                    AWS Bedrock AgentCore                     │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐      ┌─────────────────┐                 │
│  │   Gateway    │◄─────┤ Policy Engine   │                 │
│  │   (OAuth)    │      │  (Cedar Rules)  │                 │
│  └──────┬───────┘      └─────────────────┘                 │
│         │                                                    │
│         ├──► Lambda: restart_service                        │
│         ├──► Lambda: terminate_instance                     │
│         ├──► Lambda: clean_logs                             │
│         └──► Lambda: get_metrics                            │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Componentes

Infraestructura (Terraform)

Gateway: Endpoint MCP con autenticación OAuth (Cognito)
4 Lambda Functions: Herramientas de automatización DevOps
Cognito User Pool: Autenticación OAuth 2.0
IAM Roles: Permisos para Gateway y Lambdas

Políticas de Seguridad (Cedar)

allow_restart_staging_dev: Permite reiniciar servicios solo en staging/dev
allow_terminate_non_production: Permite terminar instancias solo en staging/dev
allow_clean_logs_always: Permite limpiar logs cuando se especifica log_group
allow_get_metrics_always: Permite obtener métricas cuando se especifica service_name

Scripts de Gestión

setup_agentcore.py: Crea Policy Engine y políticas Cedar
verify_setup.py: Verifica que todos los componentes estén configurados
test_with_toolkit.py: Ejecuta tests de políticas
enable_enforce_mode.py: Cambia Policy Engine a modo ENFORCE
cleanup_policies.py: Limpia políticas huérfanas
configure_gateway_logs.py: Configura log delivery a CloudWatch

Requisitos Previos

AWS CLI configurado con credenciales
Terraform >= 1.0
Python 3.10+
Permisos IAM para:
- Bedrock AgentCore
- Lambda
- Cognito
- IAM

Instalación

1. Instalar dependencias Python

pip install -r requirements.txt

2. Desplegar infraestructura con Terraform

cd terraform
terraform init
terraform plan
terraform apply

Esto crea:

Gateway con OAuth
4 Lambda functions
Cognito User Pool y Client
IAM roles y políticas

3. Configurar Policy Engine y políticas

cd ../scripts
python setup_agentcore.py

Esto crea:

Policy Engine
4 políticas Cedar
Asocia el Policy Engine al Gateway en modo LOG_ONLY

4. Verificar configuración

python verify_setup.py

5. Configurar Observability (Recomendado)

# Obtener Gateway ID y ARN
cd terraform
terraform output gateway_id
terraform output gateway_arn

# Configurar log delivery a CloudWatch y X-Ray
cd ../scripts
python configure_gateway_logs.py <GATEWAY_ID> <GATEWAY_ARN>

Esto configura:

Log delivery a CloudWatch Logs
Trace delivery a X-Ray
Permite ver decisiones de políticas y debugging en tiempo real

Uso

Configurar Observability (Logs y Traces)

Después de desplegar la infraestructura, configura log delivery para CloudWatch y X-Ray:

# Obtener Gateway ID y ARN
cd terraform
terraform output gateway_id
terraform output gateway_arn

# Configurar log delivery
cd ../scripts
python configure_gateway_logs.py <GATEWAY_ID> <GATEWAY_ARN>

Esto configura:

Log delivery a CloudWatch Logs (APPLICATION_LOGS)
Trace delivery a X-Ray (TRACES)
Permite ver decisiones de políticas en tiempo real

Verificar configuración:

# Ver log deliveries
aws logs describe-deliveries --region us-east-1 \
  --query "deliveries[?contains(deliverySourceName, '<GATEWAY_ID>')]"

# Ver log group
aws logs describe-log-groups --region us-east-1 \
  --log-group-name-prefix "/aws/vendedlogs/bedrock-agentcore/gateway"

Ver Logs de CloudWatch

Una vez configurado log delivery, puedes ver los logs en tiempo real:

# Ver logs en tiempo real
aws logs tail /aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<GATEWAY_ID> \
  --follow --region us-east-1

# Ver logs de los últimos 5 minutos
aws logs tail /aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<GATEWAY_ID> \
  --since 5m --region us-east-1

# Ver solo errores (policy denials)
aws logs tail /aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<GATEWAY_ID> \
  --since 5m --region us-east-1 | grep "ERROR"

Los logs muestran:

✅ Requests recibidos con request_id y trace_id
✅ Decisiones de políticas (ALLOW/DENY)
✅ Ejecución de tools y respuestas
✅ Errores y warnings con contexto completo

Ejemplo de log de request exitoso:

{
  "severityText": "INFO",
  "body": {
    "log": "Started processing request",
    "requestBody": "{method=tools/call, params={name=restart-service___restart_service, arguments={environment=staging}}}",
    "id": "test-1"
  },
  "trace_id": "697cd67513fa4ba619930242188e811a",
  "request_id": "e830a06a-6f52-41e6-9157-5dff470ad9e1",
  "account_id": "471112730907"
}

Ejemplo de log de policy denial:

{
  "severityText": "ERROR",
  "body": {
    "isError": true,
    "log": "Tool Execution Denied: Tool call not allowed due to policy enforcement [No policy applies to the request (denied by default).]",
    "id": "test-2"
  },
  "trace_id": "697cd6765cf48d9c49efc5fe09d8b104",
  "request_id": "53ba1743-0385-4bc8-a88b-07c645286347"
}

Consola web de X-Ray:

https://console.aws.amazon.com/xray/home?region=us-east-1#/traces

Los traces muestran:

Flujo completo de requests a través del Gateway
Latencia de cada componente
Invocaciones a Lambda functions
Correlación con logs usando trace_id

Ejecutar Tests de Políticas

# Obtener Gateway ID
cd terraform
terraform output gateway_id

# Ejecutar tests
cd ../scripts
python test_with_toolkit.py <GATEWAY_ID>

Ejemplo de salida:

======================================================================
TESTS CON AGENTCORE STARTER TOOLKIT
======================================================================
Gateway ID: devops-agent-gateway-ktnlm2in2t

Paso 1: Cargando configuracion...
OK Gateway: devops-agent-gateway-ktnlm2in2t
OK User Pool: us-east-1_3LMcjaSXD
OK Client ID: 11avu448k1bp98mu62f5lbh6p8

...

======================================================================
RESUMEN DE TESTS
======================================================================
Total:        7
[PASS] Passed:    7
[FAIL] Failed:    0
Success Rate: 100.0%

7 tests pasaron exitosamente!
Las politicas estan funcionando correctamente.

Cambiar a Modo ENFORCE

Por defecto, el Policy Engine está en modo LOG_ONLY (registra decisiones pero no bloquea).

Para activar el enforcement de políticas:

python enable_enforce_mode.py <GATEWAY_ID> <POLICY_ENGINE_ID>

Para obtener los IDs:

cd terraform
terraform output gateway_id
terraform output policy_engine_id

Volver a Modo LOG_ONLY

Si necesitas desactivar el enforcement temporalmente, actualiza el Gateway manualmente:

import boto3

bedrock = boto3.client('bedrock-agentcore-control', region_name='us-east-1')

bedrock.update_gateway(
    gatewayIdentifier='<GATEWAY_ID>',
    policyEngineConfiguration={
        'arn': '<POLICY_ENGINE_ARN>',
        'mode': 'LOG_ONLY'
    }
)

Políticas Cedar

Formato de Acción

Las acciones en Cedar usan el formato: TargetName___tool_name (triple underscore)

Ejemplo:

permit(
    principal,
    action == AgentCore::Action::"restart-service___restart_service",
    resource == AgentCore::Gateway::"<gateway-arn>"
)
when {
    context.input has environment &&
    (context.input.environment == "staging" || context.input.environment == "dev")
};

Semántica de Políticas

Default Deny: Por defecto, todas las acciones están denegadas
Explicit Permit: Debes crear políticas permit para permitir acciones
Forbid Wins: Si existe una política forbid, siempre gana sobre permit

Estructura del Proyecto

.
├── README.md
├── requirements.txt
├── lambda/
│   ├── restart_service/
│   │   └── lambda_function.py
│   ├── terminate_instance/
│   │   └── lambda_function.py
│   ├── clean_logs/
│   │   └── lambda_function.py
│   └── get_metrics/
│       └── lambda_function.py
├── scripts/
│   ├── setup_agentcore.py
│   ├── verify_setup.py
│   ├── test_with_toolkit.py
│   ├── enable_enforce_mode.py
│   ├── cleanup_policies.py
│   └── configure_gateway_logs.py
└── terraform/
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    ├── agentcore.tf
    ├── cognito.tf
    ├── iam.tf
    └── lambda.tf

Tests de Políticas

El script test_with_toolkit.py ejecuta 7 tests que validan las políticas en modo ENFORCE:

Test	Herramienta	Parámetros	Resultado Esperado	Resultado Real
1	restart_service	environment=staging	✅ ALLOW	✅ PASS
2	restart_service	environment=production	❌ DENY	✅ PASS
3	terminate_instance	environment=staging	✅ ALLOW	✅ PASS
4	terminate_instance	environment=production	❌ DENY	✅ PASS
5	clean_logs	log_group=/aws/lambda/...	✅ ALLOW	✅ PASS
6	get_metrics	service_name=api-gateway	✅ ALLOW	✅ PASS
7	restart_service	sin environment	❌ DENY	✅ PASS

Success Rate: 100% (7/7 tests)

Diferencias entre LOG_ONLY y ENFORCE

Modo	Comportamiento	Tests Pasados	Uso
LOG_ONLY	Evalúa políticas pero NO bloquea. Permite todo y solo registra decisiones.	4/7 (57.1%)	Testing y validación
ENFORCE	Evalúa y APLICA políticas. Bloquea acciones no permitidas activamente.	7/7 (100%)	Producción

En modo LOG_ONLY, los tests 2, 4 y 7 "fallan" porque las acciones son permitidas cuando deberían ser denegadas. Esto es esperado y útil para validar políticas antes de activar ENFORCE.

Troubleshooting

Error: "Insufficient Permissions for Policy Evaluation"

Causa: El Gateway role no tiene permisos completos de bedrock-agentcore.

Solución: El rol del Gateway debe tener la política:

{
  "Effect": "Allow",
  "Action": ["bedrock-agentcore:*"],
  "Resource": "*"
}

Esto ya está configurado en terraform/iam.tf. Si el error persiste, verifica que Terraform haya aplicado los cambios correctamente.

Error: "Invalid Bearer token"

Causa: El token OAuth no es válido o expiró.

Solución: Los tokens expiran después de 1 hora. El script test_with_toolkit.py obtiene un nuevo token automáticamente en cada ejecución.

Gateway no responde

Causa: DNS propagation delay.

Solución: Espera 30-60 segundos después de crear el Gateway.

No veo logs en CloudWatch

Causa: Log delivery no configurado o logs aún no propagados.

Solución:

Ejecuta python configure_gateway_logs.py <GATEWAY_ID> <GATEWAY_ARN>
Espera 1-2 minutos después de ejecutar tests

Verifica que el log group existe:

aws logs describe-log-groups --region us-east-1 \
  --log-group-name-prefix "/aws/vendedlogs/bedrock-agentcore/gateway"

No veo traces en X-Ray

Causa: Los traces tardan 5-10 minutos en aparecer en X-Ray.

Solución:

Verifica que trace delivery esté configurado:

aws logs describe-deliveries --region us-east-1 \
  --query "deliveries[?contains(deliverySourceName, '<GATEWAY_ID>')]"

Espera 5-10 minutos después de ejecutar tests
Los trace IDs están disponibles inmediatamente en los logs de CloudWatch

Limpieza

Eliminar log deliveries (opcional)

Si quieres eliminar la configuración de logs:

# Listar deliveries
aws logs describe-deliveries --region us-east-1 \
  --query "deliveries[?contains(deliverySourceName, '<GATEWAY_ID>')]"

# Eliminar delivery de logs
aws logs delete-delivery --id <DELIVERY_ID> --region us-east-1

# Eliminar delivery de traces
aws logs delete-delivery --id <DELIVERY_ID> --region us-east-1

# Eliminar log group
aws logs delete-log-group \
  --log-group-name "/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<GATEWAY_ID>" \
  --region us-east-1

Eliminar políticas huérfanas

cd scripts
python cleanup_policies.py <POLICY_ENGINE_ID>

Destruir infraestructura

cd terraform
terraform destroy

Nota: Debes eliminar manualmente el Policy Engine antes de destruir el Gateway:

aws bedrock-agentcore-control delete-policy-engine \
    --policy-engine-id <POLICY_ENGINE_ID> \
    --region us-east-1

Recursos

Advertencias para Uso en Producción

Este código es ilustrativo y educativo. Para uso en producción, considera:

Seguridad

Implementar políticas Cedar más granulares y específicas
Usar AWS Secrets Manager para credenciales de Cognito
Configurar VPC endpoints para servicios AWS
Implementar rate limiting y throttling
Configurar alertas de CloudWatch para policy denials

Infraestructura

Usar módulos de Terraform reutilizables
Implementar múltiples entornos (dev, staging, prod)
Configurar backup y disaster recovery
Implementar CI/CD para despliegues automatizados
Usar Terraform remote state

Observability

Configurar dashboards de CloudWatch personalizados
Implementar alertas basadas en métricas
Configurar retención de logs apropiada
Integrar con sistemas de monitoreo empresariales
Implementar distributed tracing completo

Compliance

Implementar auditoría completa de accesos
Configurar AWS CloudTrail
Documentar políticas de seguridad
Implementar controles de compliance (SOC2, HIPAA, etc.)

Licencia

Este proyecto es código de demostración para fines educativos. Disponible bajo licencia MIT.

Autor

Gerardo Arroyo - gerardo.dev

Proyecto de demostración para el artículo sobre AWS Bedrock AgentCore Policy Engine.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
lambda		lambda
scripts		scripts
terraform		terraform
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt

codecr/bedrock-policy

Folders and files

Latest commit

History

Repository files navigation