Permisos, Reglas de Seguridad y Colaboración Multi-Agente
Implementa reglas de permiso, control de acceso, restricciones de archivo, delegación de agentes, registro de auditoría y flujos de trabajo multi-agente.
Permisos, Reglas de Seguridad y Colaboración Multi-Agente
Reglas de Permiso en opencode.json
Los permisos definen qué acciones pueden realizar los agentes. Están estructurados como reglas allow/deny aplicadas a herramientas específicas o servidores MCP.
{
"permissions": [
{
"tool": "bash",
"allow": ["npm *", "git *", "pip *", "cargo *"],
"deny": ["rm -rf *", "sudo *", "chmod *", "> *", "| *"]
},
{
"tool": "write",
"allow": ["src/**", "docs/**", "tests/**"],
"deny": [".env", "*.key", "node_modules/**"]
}
]
}Las reglas de permiso se evalúan en tiempo de ejecución para cada invocación de herramienta. Las reglas deny se verifican primero — si un comando coincide con cualquier patrón deny, se rechaza inmediatamente independientemente de si también coincide con un patrón allow. Este diseño a prueba de fallos previene desvíos accidentales.
Lógica de Evaluación de Permisos
Comprender el orden exacto de evaluación es crítico para escribir reglas de permiso seguras.
El comportamiento predeterminado para herramientas sin reglas de permiso depende del tipo de herramienta. Las herramientas de solo lectura (read, grep, glob) están permitidas por defecto. Las herramientas de escritura y ejecución (bash, write, edit, task) están denegadas por defecto a menos que se permitan explícitamente.
Patrones Allow/Deny
Los patrones admiten comodines estilo glob para coincidencia flexible de reglas:
| Patrón | Coincide con | Ejemplo de Coincidencia |
|---|---|---|
src/** | Todos los archivos bajo src/ | src/components/button.tsx |
*.env | Cualquier archivo .env en cualquier nivel | /project/.env |
**/secrets/* | Cualquier archivo dentro de secrets/ | config/secrets/keys.json |
npm * | Cualquier comando que comience con npm | npm install express |
git * | Cualquier comando que comience con git | git push origin main |
rm -rf * | Eliminación recursiva forzada | rm -rf node_modules |
Los patrones glob distinguen entre mayúsculas y minúsculas en Linux y no los distinguen en macOS por defecto. Ten cuidado con las extensiones de archivo — *.KEY NO coincidirá con secret.key en Linux. Usa patrones en minúsculas para compatibilidad entre plataformas.
Control de Acceso a Herramientas
Cada herramienta puede tener reglas de acceso granulares:
{
"permissions": [
{
"tool": "read",
"allow": ["*"],
"description": "La lectura está permitida en todas partes"
},
{
"tool": "edit",
"allow": ["src/**/*.ts", "src/**/*.tsx"],
"deny": ["src/generated/**"],
"requireApproval": true
},
{
"tool": "bash",
"deny": ["curl *", "wget *", "ssh *"],
"requireApproval": "always"
}
]
}Usa requireApproval: true para operaciones destructivas o sensibles. Esto crea una compuerta humano-en-el-bucle que evita que agentes automatizados realicen acciones irreversibles como despliegues, eliminación de datos o cambios de configuración sin confirmación explícita del usuario.
Restricciones de Ruta de Archivo
Las restricciones de ruta limitan qué archivos pueden acceder los agentes:
{
"permissions": [
{
"tool": "bash",
"allow": [
"/home/usuario/proyectos/*",
"/tmp/*"
],
"deny": [
"/etc/**",
"/home/usuario/.ssh/**",
"/home/usuario/proyectos/repo-secreto/**"
]
}
]
}Las restricciones de ruta de archivo solo se aplican cuando la herramienta se invoca a través del registro de herramientas de OpenCode. El acceso directo al shell evita estas restricciones — siempre combínalas con reglas allow/deny de comando bash. Un agente con permiso para ejecutar bash pero sin restricciones de ruta podría acceder a cualquier archivo ejecutando comandos shell directamente.
Flujos de Trabajo Multi-Agente
Los flujos de trabajo multi-agente permiten descomposición compleja de tareas:
En flujos de trabajo multi-agente, comienza con un patrón simple de orquestador más especialistas. Cada especialista debe tener una descripción de alcance estrecho y permisos restringidos. El orquestador descompone solicitudes de alto nivel en subtareas y delega al especialista apropiado.
{
"agents": {
"default": {
"model": "gpt-4o",
"description": "Orquestador — descompone tareas y delega a especialistas"
},
"code-agent": {
"model": "gpt-4o",
"description": "Implementa código de funcionalidades siguiendo patrones del proyecto",
"constraints": {
"allowedTools": ["read", "write", "edit", "glob", "bash"]
}
},
"review-agent": {
"model": "claude-sonnet-4-20250514",
"description": "Revisa código por seguridad, rendimiento y estilo",
"constraints": {
"allowedTools": ["read", "grep", "glob"],
"deniedTools": ["write", "edit", "bash"]
}
},
"test-agent": {
"model": "gpt-4o",
"description": "Escribe pruebas unitarias y de integración",
"constraints": {
"maxTokens": 4096
}
},
"deploy-agent": {
"model": "gpt-4o-mini",
"description": "Gestiona pipelines de despliegue con compuertas de aprobación",
"constraints": {
"allowedTools": ["bash", "read", "glob"]
}
}
}
}Delegación Agente-a-Agente
Los agentes pueden delegar subtareas a otros agentes. La delegación respeta los permisos y restricciones del agente destino.
Cuando un orquestador delega a un especialista, el especialista opera bajo su propio ámbito de permisos. Esto significa que un especialista puede tener restricciones más estrictas que el orquestador, proporcionando defensa en profundidad. Siempre diseña cadenas de delegación para que cada agente tenga los permisos mínimos necesarios para su rol.
{
"agentRouting": {
"mode": "delegation",
"delegationRules": [
{
"sourceAgent": "default",
"targetAgent": "review-agent",
"trigger": "después de cambios de código",
"conditions": {
"filePattern": "src/**/*.ts"
}
},
{
"sourceAgent": "default",
"targetAgent": "test-agent",
"trigger": "después de implementación",
"conditions": {
"required": true
}
}
]
}
}Registro de Auditoría
El registro de auditoría rastrea todas las acciones de los agentes para seguridad y depuración:
{
"audit": {
"enabled": true,
"logPath": ".opencode/audit.log",
"events": [
"tool.call",
"tool.call.result",
"agent.delegation",
"permission.denied",
"permission.approved"
],
"retention": "30d"
}
}Los registros de auditoría son críticos para la respuesta a incidentes y el cumplimiento normativo. Si ocurre una violación de seguridad, el registro de auditoría es tu principal fuente de verdad para reconstruir lo que sucedió. Establece períodos de retención apropiados basados en tus requisitos de cumplimiento (SOX, HIPAA, SOC2 típicamente requieren 90 días a 7 años).
# Analizar registros de auditoría para información de seguridad
# Contar permisos denegados por herramienta
grep "permission.denied" .opencode/audit.log | \
jq -r '.data.tool' | sort | uniq -c | sort -rn
# Encontrar todos los eventos de delegación con marcas de tiempo
grep "agent.delegation" .opencode/audit.log | \
jq -r '[.timestamp, .data.source, .data.target] | @tsv'
# Rastrear actividad de compuerta de aprobación
grep "permission.approved\|permission.denied" .opencode/audit.log | \
jq -r '[.timestamp, .event, .data.tool, .data.command] | @tsv'Comparación: Tipos de Regla de Permiso
| Tipo de Regla | Ámbito | Ejemplo | Caso de Uso |
|---|---|---|---|
| Tool allow/deny | Nivel herramienta | "allow": ["npm *"] | Restricciones seguras de comando |
| Path allow/deny | Acceso archivo | "allow": ["src/**"] | Restringir modificaciones de archivo |
| Regla MCP server | Nivel servidor | "mcpServer": "github" | Control de acceso externo |
| Requerir aprobación | Nivel acción | "requireApproval": true | Compuerta de operaciones sensibles |
| Restricción agente | Nivel agente | "deniedTools": ["bash"] | Límites de capacidad por agente |
| Ámbito subagente | Herencia | Heredado del padre por defecto | Límites jerárquicos de permisos |
| Filtro evento audit | Nivel registro | "events": ["tool.call", "permission.denied"] | Captura selectiva de registro |
Sigue el principio de mínimo privilegio: comienza sin permisos y concede solo lo que cada agente necesita. Usa restricciones de nivel de agente para límites amplios de capacidad, allow/deny de nivel de herramienta para control específico de comandos, y reglas de servidor MCP para acceso a servicios externos. Capas para defensa en profundidad.
Preguntas de Práctica
Un ingeniero de seguridad está escribiendo una regla de permiso. ¿Qué tres componentes debe especificar toda regla de permiso?
¿Cuál es la diferencia práctica entre una regla de nivel de herramienta `deny: ['rm -rf *']` y una restricción de nivel de agente `deniedTools: ['bash']`?
En un flujo de trabajo multi-agente con un orquestador y agentes especialistas, ¿cómo decide el orquestador qué agente debe manejar una subtarea?
Un equipo de seguridad quiere auditar cada invocación de herramienta, delegación y decisión de permiso en OpenCode. ¿Qué conjunto de eventos de auditoría deberían habilitar?
Un administrador configuró restricciones de ruta de archivo para bloquear el acceso a `/etc/` pero no agregó ninguna regla allow/deny de bash. ¿Por qué esta configuración está incompleta?
- Las reglas de permiso usan patrones allow/deny con comodines estilo glob para control de acceso flexible
- Las reglas deny se evalúan primero y tienen prioridad sobre las reglas allow
- Las reglas de nivel de herramienta controlan qué comandos y operaciones de archivo pueden ejecutar los agentes
- Las restricciones de ruta de archivo deben combinarse con reglas de comando bash para evitar elusión
- Los flujos de trabajo multi-agente descomponen tareas complejas mediante delegación orquestador-especialista
- La delegación agente-a-agente respeta el ámbito de permisos independiente de cada agente destino
- El registro de auditoría captura llamadas de herramienta, delegaciones y eventos de permiso para revisión de seguridad
- Las compuertas de aprobación añaden un humano-en-el-bucle para operaciones sensibles como despliegues
- La lógica de evaluación de permisos sigue un flujo estructurado: verificación de herramienta, verificación deny, verificación allow, compuerta de aprobación
- Principio de mínimo privilegio: comienza sin permisos y concede solo lo que cada agente necesita