shell.exec está bien hasta que el comando es
rm -rf, db.query está bien hasta que golpea prod. Esa distinción es lo
que expresa una cláusula de argumentos: un predicado de
argumento de herramienta con jsonpath
que coincide sobre los valores que un agente pasa, así que el veredicto se
dispara solo en la llamada peligrosa y deja el resto en paz.
Esta página es un recetario — un puñado de recetas args_match_json de
copiar y pegar para los casos que surgen con más frecuencia. Para la
gramática de cláusulas completa, la tabla de operadores y la semántica de
fallo cerrado, ver
Validar argumentos y la
referencia de Esquema de regla.
1. Cómo funciona una cláusula de argumento de herramienta con jsonpath
Elargs_match_json de una regla es un string codificado en JSON que
lleva un conjunto de cláusulas, todas conjugadas con AND. El valor
decodificado es un objeto, {"clauses": [ … ]}, donde cada cláusula es un
triple { path, op, value }:
path— un pequeño subconjunto de JSONPath sobre el objeto de argumentos de la herramienta:$.command,$.foo.bar,$.items[0], o$para el objeto completo. Sin comodines, filtros, slices ni descenso recursivo.op— uno de un conjunto cerrado:eq,contains,regex,in,cidr_match,gt,lt.value— el literal con el que comparar (un string, número, bool, o — parain— un array JSON).
tool_name_glob de la regla: la
regla se dispara solo cuando el nombre de la herramienta coincide y cada
cláusula se cumple. Omite args_match_json por completo (o déjalo un "{}"
vacío) y la regla coincide solo sobre el glob.
Las cláusulas fallan cerradas — la regla, no la solicitud. Si un path no
resuelve, los argumentos están malformados, o un valor es del tipo
equivocado, la cláusula evalúa falso y la regla simplemente no se
dispara — la llamada cae a la siguiente regla o al veredicto por defecto. Una
cláusula rota nunca auto-deniega. Escribe tu respaldo duro como un
deny de
glob simple, no como una cláusula en la que te apoyas para fallar de cierta
forma.2. Receta: bloquear un comando destructivo
El caso canónico. Permiteshell.exec en general, deniégalo solo cuando el
comando se ve destructivo. Una cláusula regex sobre $.command lo logra:
$.command no string (o uno ausente) nunca coincide, así que una llamada
malformada cae en vez de ser bloqueada erróneamente.
3. Receta: denegar una herramienta contra un entorno nombrado
Deja quedb.query se ejecute, pero solo contra conexiones seguras —
deniégalo cuando el objetivo es prod o una replica. El operador in
coincide el valor resuelto contra cualquier elemento de un array JSON:
in debe ser un array JSON — un no-array se rechaza cuando
guardas la regla. Los elementos comparan con igualdad escalar, así que los
números y los strings coinciden cada uno con su propio tipo.
4. Receta: denegar un destino de IP privada o metadatos
Cuando una herramienta toma una IP objetivo como argumento,cidr_match
prueba si cae dentro de un CIDR — la forma SSRF de “un agente recuperando
10.x o la dirección de metadatos de nube”:
5. Receta: limitar un argumento numérico
gt y lt comparan números. Úsalos para rechazar un tamaño de lote
absurdo, un límite sobredimensionado o cualquier conteo descontrolado — aquí,
denegar un borrado masivo que apunta a más de 100 filas:
"500" es una discordancia de tipo y no coincide, así que la regla no se
disparará sobre un argumento tipado como string. Mantén el argumento
numérico, o normalízalo antes de que la herramienta lo vea.
6. Receta: combinar cláusulas (AND)
Todas las cláusulas en una regla se conjugan con AND, así que puedes estrechar un veredicto a una llamada muy específica — por ejemplo, denegarshell.exec solo cuando es un comando destructivo y apunta a un host
prod:
args_match_json — autora dos reglas (o dos globs) en prioridades
diferentes. El motor recorre las reglas en orden de prioridad y gana la
primera coincidencia, así que pon las reglas estrechas primero. Ver
Prioridad de reglas.
7. Elige el veredicto para la forma coincidente
Una cláusula decide qué llamadas coinciden; elverdict de la regla decide
qué pasa. deny es el valor por defecto del recetario, pero la misma
cláusula puede llevar un veredicto más suave:
sanitize — redacta un secreto en un argumento
sanitize — redacta un secreto en un argumento
Cuando el argumento coincidente lleva un secreto o PII en vez de una
instrucción peligrosa,
sanitize redacta las subcadenas coincidentes de
los argumentos de la herramienta y reenvía la llamada limpia. Redacta
solo argumentos — nunca el contenido que una herramienta devuelve. Ver
Sanear respuestas.pending_approval — retén la llamada coincidente para un humano
pending_approval — retén la llamada coincidente para un humano
Retén exactamente la forma arriesgada para revisión en vez de bloquearla
de plano: un revisor aprueba o rechaza fuera de banda, y el agente
reenvía la llamada aprobada una vez. Ver
Aprobaciones.
audit — solo verla, por ahora
audit — solo verla, por ahora
Establece el veredicto a
audit para registrar la llamada coincidente
sin bloquear mientras afinas la cláusula. Combina con
modo shadow para medir un deny
contra tráfico en vivo antes de que cambie nada.8. Prueba la cláusula antes de depender de ella
La pestaña Test de la consola ejecuta en seco una política contra una llamada a herramienta de muestra y devuelve el veredicto, la regla coincidente y la razón — nada se despacha, nada se persiste. Pega un objeto de argumentos realista y confirma que la cláusula se dispara en las llamadas que pretendes y solo esas, ya que una cláusula que no puede resolver un valor silenciosamente no se dispara. Ver Probar reglas.Las cláusulas se validan estrictamente al guardar — operadores
desconocidos, paths malos, un valor
in que no es array, un regex no
compilable y CIDRs inválidos se rechazan todos, así que una cláusula
malformada no se puede persistir en primer lugar.9. Quién puede autorar cláusulas de argumentos
Todo esto se ejecuta en la consola bajo tu sesión (/api/workspace/firewall/*):
| Acción | Rol |
|---|---|
| Leer políticas, presets, herramientas descubiertas | Member |
| Crear / editar / eliminar reglas | Developer+ |
| Sandbox de Test (ejecutar en seco una política) | Developer+ |
| Leer eventos y agregados de ejecuciones | Developer+ |
Relacionado
Validar argumentos
El caso de uso de coincidencia de argumentos completo.
Bloquear herramientas
Deniega una herramienta entera por nombre — sin cláusula necesaria.
Control de egress
Gobierna destinos salientes de host / IP / CIDR.
Esquema de regla
Cada campo que una regla puede llevar.
Prioridad de reglas
Gana la primera coincidencia — ordena estrecho antes que amplio.
Llamadas a herramienta peligrosas
La amenaza que abordan estas recetas.