13 publicaciones etiquetados con "seguridad"

+

La parte 6 puso required_scopes=["mcp:invoke"] en el verificador de JWT y dio por autorizado el servidor. Lo está, en el sentido de que quien llama sin autenticarse no obtiene nada. No lo está, en el sentido que importa: mcp:invoke abre todas las herramientas del servidor. El mismo token que deja a un agente ejecutar find_customer le deja ejecutar issue_refund.

Ese es todo el hueco. Un agente de solo lectura y un agente que emite reembolsos tienen credenciales idénticas, y lo único que se interpone entre "busca a Maria" y "reembolsa la factura 2" es que nadie lo pidió.

Este post lo cierra, primero mal y luego bien, porque el "mal" es lo que la mayoría despliega y la diferencia solo se nota en lo que el cliente puede hacer ante un rechazo.

Ambas versiones rechazan la misma llamada — un token de solo lectura pidiendo issue_refund. Se diferencian en dónde se comprueba el ámbito, y esa única decisión determina lo que recibe el cliente:

Requisitos previos​

Las partes 5 y 6, en concreto:

• Authentik emitiendo tokens de client-credentials a un proveedor agent-tools (parte 5)
• Un servidor FastMCP verificando esos tokens contra el endpoint JWKS (parte 6)
• ~/mcp-auth/token.sh, que recibe una cadena de ámbitos y devuelve un token de acceso

El servidor de la parte 6 se queda en :8770 todo el rato. Las dos versiones de abajo corren en :8771 y :8772 para que puedas comparar las tres sin parar nada.

Paso 1 — Dos ámbitos nuevos​

Los ámbitos son Property Mappings en Authentik. Customization → Property Mappings → New Property Mapping → Scope Mapping, dos veces:

Crearlos no basta. Un proveedor solo emitirá un ámbito que se le haya asignado, así que abre Applications → Providers → agent-tools → Edit y mueve ambos a Selected Scopes.

Fíjate en la línea bajo el selector: "Select which scopes can be used by the client. The client still has to specify the scope to access the data." Las dos mitades importan. Seleccionar un ámbito aquí no lo mete en todos los tokens — permite que el cliente lo pida. Un cliente que no pide nada no obtiene nada, y por eso cada llamada a token.sh de abajo pasa una cadena de ámbitos explícita.

Confirma que el token lleva de verdad lo que pediste:

~/mcp-auth/token.sh "mcp:invoke office:read" \
  | cut -d. -f2 | base64 -d 2>/dev/null | jq .scope

"mcp:invoke office:read"

Si eso vuelve sin office:read, el ámbito no está en el proveedor — arréglalo antes de escribir una línea de código de servidor, o te pasarás una hora depurando una aplicación de permisos que funciona perfectamente sobre un token al que nunca se le asignó el ámbito.

Paso 2 — La implementación obvia​

Mantén required_scopes=["mcp:invoke"] en el verificador como precio de entrada, y luego pregunta por herramienta si quien llama tiene lo que esa operación necesita. FastMCP expone el token ya verificado a través de get_access_token(), así que un decorador puede leer los claims que el verificador ya comprobó:

from fastmcp.exceptions import ToolError
from fastmcp.server.dependencies import get_access_token

def requires(scope: str):
    def decorate(fn):
        @functools.wraps(fn)
        async def wrapper(*args, **kwargs):
            token = get_access_token()
            held = set(getattr(token, "scopes", None) or [])
            if scope not in held:
                raise ToolError(
                    f'insufficient_scope: this tool requires "{scope}"; '
                    f'token carries {sorted(held) or "nothing"}'
                )
            return await fn(*args, **kwargs)
        return wrapper
    return decorate

Y luego una línea por herramienta:

@mcp.tool
@requires("office:read")
async def find_customer(query: str) -> list[dict]: ...

@mcp.tool
@requires("office:refund")
async def issue_refund(invoice_id: int) -> str: ...

Lánzalo en :8771 y prueba ambas herramientas con ambos tokens:

--- token: mcp:invoke + office:read ---
  find_customer  : ALLOWED -> [{'id': 1, 'name': 'Maria Alvarez', ...}]
  issue_refund   : REFUSED -> insufficient_scope: this tool requires "office:refund"

--- token: mcp:invoke + office:refund ---
  find_customer  : REFUSED -> insufficient_scope: this tool requires "office:read"
  issue_refund   : ALLOWED -> Refunded 80.00 on invoice 2.

Eso es aplicación real de permisos. El token de reembolso no puede leer, el de lectura no puede reembolsar, y el rechazo nombra el ámbito que falta. Para muchos despliegues, aquí es donde se para.

Paso 3 — Por qué ese rechazo no basta​

Mira la capa HTTP en lugar de la librería cliente.

TOK=$(~/mcp-auth/token.sh "mcp:invoke office:read")
curl -sS -i -X POST http://127.0.0.1:8771/mcp \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"issue_refund","arguments":{"invoice_id":2}}}'

HTTP/1.1 200 OK
content-type: text/event-stream

data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"insufficient_scope: this tool
requires \"office:refund\"; token carries ['mcp:invoke', 'office:read']","type":"text"},
"isError":true}}

HTTP 200. La petición tuvo éxito; la que declinó fue la herramienta. Esa es la semántica correcta de JSON-RPC y es inútil para un cliente OAuth.

Un cliente OAuth que quiere escalar — volver al servidor de autorización y pedir office:refund — está atento a un 401 o 403 con una cabecera WWW-Authenticate que le diga qué solicitar. No se pone a extraer inglés de un resultado de herramienta. Así que el rechazo es legible para un humano que lee logs e invisible para la maquinaria diseñada para manejar justo este caso.

Y además llega tarde. El cuerpo de la herramienta corre después del enrutado, después de montar la sesión, después de que el servidor se ha comprometido a una respuesta con éxito. Para entonces ya no queda línea de estado que cambiar.

Paso 4 — El desafío que la especificación realmente quiere​

Conseguir un 403 significa comprobar los ámbitos antes de que responda la capa JSON-RPC, lo que significa un middleware ASGI envolviendo la app de FastMCP:

class ScopeChallengeMiddleware:
    def __init__(self, app):
        self.app = app

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http" or scope["method"] != "POST":
            return await self.app(scope, receive, send)

        # Buffer the body so we can inspect it and still pass it on.
        chunks, more = [], True
        while more:
            msg = await receive()
            chunks.append(msg.get("body", b""))
            more = msg.get("more_body", False)
        body = b"".join(chunks)

        needed = None
        try:
            rpc = json.loads(body)
            if rpc.get("method") == "tools/call":
                needed = TOOL_SCOPES.get((rpc.get("params") or {}).get("name"))
        except Exception:
            pass

        if needed and needed not in token_scopes(dict(scope.get("headers") or [])):
            challenge = (
                f'Bearer error="insufficient_scope", scope="{needed}", '
                f'resource_metadata="{RESOURCE_METADATA}", '
                f'error_description="This operation requires the {needed} scope"'
            )
            await send({"type": "http.response.start", "status": 403,
                        "headers": [(b"content-type", b"application/json"),
                                    (b"www-authenticate", challenge.encode())]})
            await send({"type": "http.response.body",
                        "body": json.dumps({"error": "insufficient_scope",
                                            "scope": needed}).encode()})
            return

        # Replay the buffered body downstream.
        replayed = False
        async def replay():
            nonlocal replayed
            if not replayed:
                replayed = True
                return {"type": "http.request", "body": body, "more_body": False}
            return await receive()

        await self.app(scope, replay, send)

app = ScopeChallengeMiddleware(mcp.http_app(stateless_http=True))

La misma petición, contra :8772:

HTTP/1.1 403 Forbidden
www-authenticate: Bearer error="insufficient_scope", scope="office:refund",
  resource_metadata="http://127.0.0.1:8772/.well-known/oauth-protected-resource",
  error_description="This operation requires the office:refund scope"

Ahora el cliente tiene algo sobre lo que actuar: el estado dice rechazado, scope= dice qué pedir, y resource_metadata dice dónde averiguar cómo. Eso es autorización escalada como protocolo, no como mensaje de log.

Paso 5 — Lo que costó​

El middleware funciona. También es peor código que el decorador, de tres formas concretas, y fingir lo contrario sería deshonesto.

No sabe qué es una herramienta. El middleware ASGI ve bytes y cabeceras. Para averiguar qué herramienta se está llamando, parsea él mismo el sobre JSON-RPC y busca el nombre en una tabla que tiene que mantener:

TOOL_SCOPES = {
    "find_customer": "office:read",
    "open_invoices": "office:read",
    "issue_refund":  "office:refund",
}

Esa tabla es una segunda fuente de verdad. Añade una herramienta y olvida la entrada y queda sin proteger — en silencio, porque el middleware simplemente deja pasar cualquier cosa que no reconoce. El decorador no podía tener ese fallo: el requisito estaba sobre la función.

Decodifica el token sin verificarlo. El middleware corre antes del verificador, así que los claims verificados todavía no existen. Parte el JWT y decodifica en base64 el payload sin comprobar la firma:

payload = auth.split(None, 1)[1].split(".")[1]
claims = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))

Esto no es el agujero que parece — el verificador sigue corriendo después y sigue rechazando un token falsificado, así que nada llega a una herramienta con una firma mala. Pero la decisión de ámbito se toma sobre bytes no autenticados, y la única razón por la que eso es sobrevivible es la segunda comprobación detrás. Es una verruga, no una vulnerabilidad, y es de esas cosas que vale la pena dejar escritas antes de que alguien más tarde quite el verificador "redundante".

Almacena en memoria cada cuerpo de petición. Para leer el sobre y aun así pasarlo hacia abajo, el middleware vacía receive() en memoria y lo reproduce. Bien para llamadas JSON-RPC; piénsalo mejor antes de poner esto delante de subidas grandes.

Resolución de problemas — los errores que esta ejecución produjo de verdad​

insufficient_scope en una herramienta que sí concediste​

Revisa el token, no el servidor:

~/mcp-auth/token.sh "mcp:invoke office:refund" | cut -d. -f2 | base64 -d 2>/dev/null | jq .scope

Si falta office:refund, el ámbito existe como Property Mapping pero nunca se movió a los Selected Scopes del proveedor. Authentik descarta en silencio los ámbitos que un cliente no tiene permitido solicitar en lugar de dar error, así que el token vuelve válido y corto.

El middleware nunca se dispara​

Solo inspecciona POST. Los clientes MCP abren primero un GET para el flujo de eventos, y esa petición no lleva sobre JSON-RPC — si estás mirando la petición equivocada concluirás que el middleware está muerto. Confírmalo con el curl de arriba, que es un único POST.

De repente todas las herramientas devuelven 403​

TOOL_SCOPES está indexado por el nombre registrado de la herramienta, que es el nombre de la función, no la etiqueta decorada. Renombra una función y la tabla deja de coincidir. El caso de paso libre es la dirección peligrosa (sin proteger), pero un error tipográfico en la tabla produce este otro.

El cuerpo del 403 está vacío en algunos clientes​

El desafío vive en la cabecera WWW-Authenticate. Los clientes que solo registran el cuerpo de la respuesta te mostrarán {"error":"insufficient_scope"} y nada sobre qué ámbito. Usa curl -i.

Qué te dio esto y qué no​

Te dio autorización por herramienta de verdad: dos tokens que se diferencian en un ámbito, cada uno capaz de ejecutar exactamente una de dos herramientas, demostrado en la capa HTTP en lugar de afirmado. Y con el middleware, un rechazo del que un cliente puede recuperarse de forma programática.

No te dio un diseño limpio. Ambas implementaciones son concesiones que apuntan en direcciones opuestas:

El resumen honesto es que el comportamiento correcto del protocolo requiere salir de la abstracción que te da el framework, y la versión ergonómica no puede producirlo. Si tus clientes no implementan escalado — y la mayoría de los clientes de agentes hoy no lo hacen — el decorador es el mejor trato. Si lo hacen, lo pagas con una tabla que tienes que acordarte de actualizar.

Tampoco te dio una autorización que sobreviva a que la herramienta haga otra cosa. issue_refund está protegido por office:refund; nada impide que un futuro find_customer se edite para escribir. Los ámbitos controlan la entrada, no el comportamiento — que es el mismo límite que la parte 4 trazó alrededor de la política-en-la-herramienta.

Qué sigue​

El hueco evidente que queda es que ambas versiones confían en la lista de ámbitos del token y en nada más. Ninguna pregunta quién es quien llama ni sobre qué está actuando — un token con office:refund reembolsa cualquier factura, de cualquier cliente, por cualquier importe. Eso es autorización a nivel de objeto, y no vive en los ámbitos de OAuth en absoluto.

Más lectura​

• MCP specification — authorization
• RFC 6750 §3 — the WWW-Authenticate challenge
• RFC 9728 — OAuth 2.0 Protected Resource Metadata
• Authentik — property mappings and scopes

Todas las partes de esta serie hasta ahora le han dado al modelo herramientas: funciones que escribiste tú, con argumentos que definiste tú. Este post va sobre la otra cosa que hacen los agentes, que es escribir código y después ejecutarlo.

Es un riesgo distinto, y vale la pena ser preciso sobre la diferencia. Una llamada a herramienta es el modelo eligiendo de un menú que tú controlas. Ejecutar código generado es el modelo pasándote algo que nadie ha leído nunca, y que tú ejecutas en tu máquina.

Esta es la parte que nadie dice en voz alta cuando te recomiendan añadirte al grupo docker para dejar de escribir sudo.

Ese grupo es root. No "casi root", ni "root para cosas de Docker". Si puedes ejecutar un contenedor, puedes leer, modificar o borrar cualquier archivo de la máquina — incluido el archivo de contraseñas, los directorios personales de otras personas y los archivos que el administrador apartó deliberadamente de ti.

No hace falta ningún exploit. Es un comando, y tarda unos cuatro segundos.

La parte 4 de orquestación de agentes dividió una caja de herramientas para que el agente de agenda no pudiera emitir reembolsos. La parte 5 le dio al agente una identidad propia en el gateway. La parte 6 puso un verificador de JWT delante del servidor de herramientas para que rechace a quien llama sin identificarse.

Todas ellas controlan qué puede llamar el agente. Ninguna controla adónde puede ir.

Esa distinción es todo este artículo. La exfiltración no necesita una herramienta. Necesita un socket.

+

La Parte 5 le dio a un agente su propia identidad en el gateway: un token emitido por authentik con client credentials, con un scope, y que expira a los cinco minutos. Terminó nombrando lo que no había cubierto — el servidor de herramientas MCP de la parte 4 de orquestación de agentes sigue fiándose de cualquier cosa que alcance su puerto, issue_refund incluido.

Aquel post fue explícito sobre el límite de lo que había construido:

The MCP server still trusts everyone. Scoping happens in the client. Anything that can reach 127.0.0.1:8770 can call issue_refund directly, agent or not.

Repartir la caja de herramientas por rol impidió que un agente alcanzara una herramienta que no le tocaba. No hizo nada contra un curl. Esta parte cierra eso.

+

La Parte 4 puso control de acceso por grupos sobre la interfaz de administración del gateway y después, al final, llamó a la API desde un shell sin cuenta, sin sesión y sin grupo. Respondió con normalidad. La conclusión fue que el SSO protege un plano de control y que el plano de datos autentica a quien llama por máquina con claves — cosa que tiene que hacer, porque un agente que corre a las 3 de la mañana no puede completar un login en un navegador.

Eso era cierto y era también un punto y aparte, no una respuesta. "Los clientes máquina usan claves" te deja con una credencial que nunca expira, que ningún proveedor de identidad conoce, y que sobrevive a la persona que la creó. La Parte 4 lo dijo sin rodeos: sacar a alguien de un grupo no revoca sus claves, una clave filtrada no se ve afectada por la identidad en absoluto, y las claves sobreviven a las personas.

Esta parte le da a la máquina una identidad en lugar de una clave.

authentik le emite al agente un token con el flujo de client credentials — sin navegador, sin pantalla de consentimiento, sin humano. El token va firmado, lleva un scope y expira a los cinco minutos. El gateway lo verifica localmente contra las claves públicas de authentik y rechaza cualquier cosa sin el scope correcto. Al final, tres códigos de estado enseñan el límite aguantando.

++

La Parte 3 le dio a un agente cinco herramientas por MCP — un calendario, una lista de clientes, facturas y un reembolso — y puso a un humano delante del reembolso. Terminó admitiendo lo evidente: un solo agente tenía las cinco. Nada impedía que el modelo echara mano de issue_refund cuando se le había pedido reservar una cita. La pausa humana era lo único que se interponía, y una pausa solo se dispara si el modelo llega a llamar la herramienta.

Esta parte quita la herramienta en su lugar. El de agenda recibe tres y el de facturación tres, compartiendo una. Pídele al de agenda que reembolse una factura y no puede — no porque se le haya dicho que no, no porque una política lo bloquee, sino porque issue_refund nunca estuvo en la lista que se le dio.

Luego el supervisor de la Parte 2 vuelve encima, y sale a la luz la propiedad interesante: el enrutado decide quién trabaja, el alcance decide qué es posible. Un reembolso mal enrutado sigue sin poder reembolsar.

+

La Parte 3 puso authentik delante de Langfuse y terminó con una confesión: el paso de vinculaciones quedó vacío, así que cualquier cuenta de authentik podía llegar a Langfuse y nada te avisaría.

Esta parte cierra ese hueco en la gateway LiteLLM — y el cierre salió mal de una forma que vale más que el procedimiento. Configuramos las vinculaciones en el asistente de authentik, las vimos aparecer en la tabla del propio asistente, enviamos, y acabamos con cero vinculaciones guardadas. La aplicación estaba abierta a todo el mundo, la interfaz no dijo nada, y la única razón por la que lo descubrimos es que probamos con una cuenta que debería haber sido rechazada y no lo fue.

Después, ya con el control de acceso funcionando de verdad, llamamos a la API del gateway desde un shell sin cuenta, sin sesión y sin grupo. Respondió con normalidad. Eso no es un fallo — es la diferencia entre un plano de control y un plano de datos, y suponer que el SSO cubre ambos es cómo la gente concluye que ha asegurado algo que no ha asegurado.

+

La Parte 1 cerró los puertos que nadie quiso abrir. La Parte 2 impidió que dos contenedores se ejecutaran como root. Ambas trataban sobre la máquina. Ninguna tocó la pregunta que una pila de IA autoalojada responde peor: ¿quién tiene permiso para iniciar sesión, y dónde se decide eso?

La misma caja de antes. El Langfuse que venimos endureciendo desde la Parte 1 — aquel cuyo Postgres, ClickHouse y Redis la Parte 1 encontró correctamente enlazados a localhost, y cuyo worker la Parte 2 bajó de root — se desplegó en Detecta lo que tus pruebas no ven. Dos partes han asegurado ya la máquina por debajo sin tocar ni una vez la puerta de entrada de la propia aplicación. Esta es la primera parte que cambia Langfuse en sí.

Ahora mismo esa decisión se toma en cada app, por separado. Langfuse tiene su propia tabla de correo y contraseña. También la tiene cualquier otra herramienta en la caja. Cada una es un lugar donde una cuenta puede sobrevivir a la persona que la tenía, donde una contraseña puede reutilizarse, y donde "quitarle el acceso a esta persona" significa acordarse de que esa app existe.

Este post mueve esa decisión a un solo lugar. Ese lugar es authentik — un proveedor de identidad de código abierto que ejecutas tú mismo, la contraparte autoalojada de Okta o Auth0. Guarda las cuentas, muestra la pantalla de inicio de sesión, y da fe de quién es alguien ante cualquier app que pregunte. Las apps dejan de almacenar contraseñas y empiezan a preguntarle a authentik.

Es el mismo trabajo que hace Keycloak, y Keycloak es el nombre más conocido. authentik se gana la elección aquí por el coste de puesta en marcha: un archivo compose y un asistente frente a los realms, clients y ajustes de JVM de Keycloak. Para una caja y una app, esa diferencia es toda la decisión.

Lo desplegamos, conectamos Langfuse a él por OIDC, y terminamos con un inicio de sesión que pasa por authentik y vuelve.

Parte 1 de esta serie auditó una caja multi-agente en vivo y encontró cada pregunta sobre exposición de red que valía la pena hacer. Una línea de esa auditoría no se siguió: "el Postgres, ClickHouse y Redis detrás de Langfuse estaban publicados en 127.0.0.1 en lugar del mundo — alguien tomó una buena decisión allí. Mantén ese pensamiento."

Aquí está la otra mitad de ese pensamiento: conseguir la red correcta no dice nada sobre lo que sucede después de que alguien ya esté dentro de un contenedor. Si el proceso que se ejecuta allí es root, un compromiso comienza con las llaves de todo el sistema de archivos. Así que verificamos — en la misma caja, la misma pila de Langfuse que la Parte 1 ya alabó — si "red correcta" también significaba "privilegio correcto." No lo era, para dos de los seis contenedores. Aquí está cómo se veía realmente la solución, incluyendo la parte que se rompió.

Comienzas con un agente. Luego necesita una base de datos. Después agregas un segundo agente, un puente de mensajería, una pila de observabilidad. Seis meses después, una única instancia de WEC está ejecutando cinco proyectos de compose, veinte y tantos contenedores, y nadie recuerda qué puertos están abiertos al mundo.

Eso no es un hipotético — esa es la caja en la que se escribió este tutorial. Así que en lugar de teorizar, lo investigamos: ¿pueden los contenedores alcanzarse entre sí a través de pilas? ¿Pueden alcanzar las bases de datos? ¿Está el firewall realmente protegiendo algo?

Tres de las respuestas me sorprendieron. Una de ellas fue una base de datos sentada allí sin contraseña. Y el firewall — el firewall estaba mintiendo.

+

En Artículo 2 colocamos Caddy frente a OpenClaw para HTTPS, y en Artículo 3 agregamos un canal de Telegram. La puerta de enlace funciona — pero Caddy sigue escuchando en 0.0.0.0, accesible por cualquier cosa que pueda enrutar hacia la caja. Este es el proyecto final de la serie: unimos el servidor y tu laptop a una malla NetBird, redirigimos openclaw.local a la IP de la malla y cerramos los puertos públicos. La misma URL https://openclaw.local/chat sigue funcionando — pero solo para tus dispositivos. Cada comando y error a continuación proviene de la ejecución real.

+

En Artículo 1 hicimos funcionar OpenClaw — pero solo a través de HTTP sin cifrar, con un workaround allowInsecureAuth. Aquí colocamos Caddy frente a él como un proxy inverso: verdadero HTTPS, autenticación emparejada por dispositivo, y los puertos del gateway cerrados para que el proxy sea la única forma de acceso. Cada comando y error a continuación proviene de la implementación real.