Saltar a contenido

Servidor MCP

Ostorlab expone un servidor MCP, que permite a los asistentes de IA y a los frameworks de agentes trabajar directamente con sus scans, vulnerabilidades, tickets y activos — sin necesidad de un cliente GraphQL personalizado.

Mientras que la API GraphQL le ofrece toda la superficie de la plataforma para construir integraciones, el servidor MCP proporciona a un cliente de IA un conjunto estructurado de herramientas tipadas que puede descubrir e invocar por sí mismo. Pregunte a su asistente «¿qué encontró el último scan de mi aplicación?» y elegirá las herramientas correctas, las encadenará y responderá.

Endpoint

https://api.ostorlab.co/apis/mcp/{api_key}/

El transporte es streamable HTTP. La clave de API forma parte de la ruta de la URL.

Warning

La barra final es obligatoria. Sin ella, el servidor responde con una redirección 307. Los clientes que siguen redirecciones funcionarán igualmente, pero pagarán un viaje de ida y vuelta adicional en cada petición; los clientes que no siguen redirecciones en POST fallarán.

Warning

La clave en la URL es una credencial. Las URL se registran habitualmente en los logs de proxy, el historial del navegador y el historial del shell, y los archivos de configuración de los clientes MCP suelen almacenarse en texto plano. Trate la URL del endpoint exactamente igual que la propia clave. Para retirar una clave, revóquela — establecer una fecha de expiración no impide que la clave siga funcionando en esta ruta.

Obtención de una clave de API

Cree una desde la aplicación web en Integrations/API → API Keys (https://report.ostorlab.co/integrations/api). El rol de la clave determina lo que las herramientas MCP pueden hacer — véase Permisos.

Conexión de un cliente

La mayoría de los clientes solicitan un nombre de servidor, un transporte y una URL. El transporte es streamable HTTP; cuando un cliente pida un tipo, use http.

Claude Code

claude mcp add --transport http ostorlab https://api.ostorlab.co/apis/mcp/YOUR_API_KEY/

Claude Desktop, Cursor, VS Code, Windsurf, Zed

Estos clientes leen un archivo de configuración JSON. Su ubicación varía según el cliente y la plataforma — consulte la documentación de su cliente — pero la entrada tiene la misma forma:

{
  "mcpServers": {
    "ostorlab": {
      "type": "http",
      "url": "https://api.ostorlab.co/apis/mcp/YOUR_API_KEY/"
    }
  }
}

Algunos clientes llaman a la sección servers en lugar de mcpServers, y algunos usan serverUrl en lugar de url. Si el suyo rechaza el bloque anterior, revise los nombres de las claves en su documentación — el transporte y la URL son lo que importa.

Confirmación de funcionamiento

Pida al cliente que ejecute una herramienta de lectura, por ejemplo listar sus scans. Una clave inválida devuelve Invalid API Key. Pedir la lista de herramientas no es una comprobación útil: la lista se devuelve para cualquier clave, válida o no.

Permisos

Cada herramienta comprueba los permisos de la clave de API antes de hacer nada. Las claves llevan un rol. Un rol concede un conjunto de acciones. Cada herramienta requiere una acción.

Tipo de herramienta Acción requerida
Leer scans, vulnerabilidades, tickets, comentarios y checklists read
Crear o modificar tickets, comentarios y checklists write
Triar vulnerabilidades write
Iniciar, reejecutar y detener scans write
Listar activos y tags de la superficie de ataque attack_surface_read
Aceptar o rechazar activos descubiertos, y agregar, modificar o eliminar tags attack_surface_audit
Leer y triar la cola de descubrimiento, y leer el grafo de la superficie de ataque attack_surface_audit, excepto el grafo que requiere attack_surface_read
Gestionar claves de API, usuarios y single sign-on, leer el registro de auditoría, leer y modificar la configuración de la organización, gestionar agentes de tickets, scanners y grupos de scanners, crear reglas de automatización, y configurar, leer o eliminar la mayoría de las integraciones admin

Una clave sin la acción requerida recibe un error claro en lugar de un resultado parcial.

Los roles se asignan a las acciones de la siguiente manera:

Rol read write admin attack_surface_read attack_surface_audit
reader sí no no sí no
user sí sí no sí sí
admin sí sí sí sí sí
attack_surface_auditor no no no sí sí

De esa tabla se derivan dos conclusiones. Cualquier rol dispone de attack_surface_read, por lo que cualquier clave puede invocar list_assets y list_tags. Y una clave attack_surface_auditor no tiene ni read ni write, por lo que se limita a las herramientas de superficie de ataque: puede leer activos y tags, y puede aceptarlos, rechazarlos y editarlos, pero no puede ver un scan, una vulnerabilidad ni un ticket.

Si su organización tiene habilitado el acceso a nivel de objeto, las herramientas lo respetan, siguiendo las mismas reglas que la ruta de clave de API en GraphQL:

  • Scans y tickets — una clave que no sea admin solo ve los scans y tickets individuales que se le han concedido.
  • Activos — la concesión es sobre el propietario (owner), no sobre el activo. Una clave ve todos los activos pertenecientes a los propietarios que se le han concedido. Use list_owners para ver qué propietarios puede alcanzar una clave y, por lo tanto, qué activos puede ver.

Herramientas disponibles

Las siguientes tablas agrupan las herramientas según el recurso sobre el que operan. Cada tabla indica la acción que debe poseer la clave, para que pueda determinar de un vistazo qué herramientas puede alcanzar una clave con un rol determinado.

El servidor siempre se describe a sí mismo. Cada herramienta incluye su propia descripción y su propia lista de argumentos, y el cliente lee ambas al conectarse. Si una herramienta no figura aquí, pida a su cliente que muestre su lista de herramientas — esa es la respuesta autoritativa para el servidor con el que se está comunicando.

Scans

Herramienta Acción Descripción
list_scans read Lista scans, filtrados por status, asset_id, scan_profile, risk_rating, created_after, archived.
get_scan read Los detalles de un scan.
get_scan_status read El progreso de un scan, su historial reciente de estados y los errores que haya reportado.
list_scan_profiles read Los perfiles de scan que la organización puede ejecutar, con los nombres exactos que espera create_scan.
search_store_applications read Busca una aplicación en las tiendas móviles públicas para obtener el nombre y paquete que espera create_scan.
create_scan write Inicia un scan contra un objetivo web, de red o de tienda móvil.
create_source_code_scan write Inicia un scan de un repositorio Git.
create_source_code_archive_scan write Inicia un scan de un archivo comprimido de código fuente que haya subido.
create_mobile_file_scan write Inicia un scan de un binario móvil que haya subido.
create_multi_asset_scan write Inicia un scan que cubre varios objetivos simultáneamente.
create_mobile_testflight_scan write Inicia un scan de una build de iOS distribuida a través de TestFlight.
create_autodiscovery_scan write Inicia un scan en toda la superficie de ataque descubierta de la organización.
create_rescan write Vuelve a ejecutar un scan existente con el mismo activo, perfil, credenciales y configuración.
stop_scan write Detiene un scan en ejecución.
generate_scan_report write Genera un informe PDF para un scan y devuelve un enlace para descargarlo.

get_scan y get_scan_status no devuelven scans archivados, aunque list_scans pueda listarlos. Invocarlos sobre un scan archivado devuelve Scan not found.

create_scan toma un asset_type de tipo web, network o mobile_store, y los campos del objetivo asociados: urls para web, networks para red, y mobile_asset_type junto con application_name y package_name para un objetivo de tienda móvil. También recibe scan_profile_name, que debe ser uno de los nombres devueltos por list_scan_profiles. Si se envía un nombre que la organización no puede ejecutar, la petición se rechaza de inmediato y el error indica los perfiles válidos, por lo que es recomendable invocar primero list_scan_profiles.

create_rescan es la vía más directa cuando el objetivo ya ha sido escaneado previamente. Solo requiere el id de un scan existente y copia todo a partir de él, evitando errores en la selección del perfil o del activo. El nuevo scan se titula Rescan of <original title>, y siempre resulta visible incluso si el original estaba oculto.

Otras herramientas inician scans contra objetivos que create_scan no cubre. create_source_code_scan toma un repositorio Git. create_mobile_testflight_scan toma una build de iOS distribuida mediante TestFlight. create_autodiscovery_scan no toma ningún objetivo: escanea todo el conjunto de descubrimiento aceptado de la organización, abarcando todo lo que list_autodiscovery_assets haya incorporado al inventario. create_multi_asset_scan toma varios objetivos combinados —web, red, repositorio, tienda móvil y archivos subidos— y los ejecuta como un único scan.

Dos de ellas toman un archivo en lugar de un identificador de objetivo: create_mobile_file_scan escanea un binario móvil y create_source_code_archive_scan escanea un archivo comprimido de código fuente. Ambas reciben un identificador de carga (upload handle), descrito a continuación.

Subir un archivo para escanear

Los argumentos de una herramienta se envían en formato JSON, por lo que no pueden transportar los bytes de un archivo. Suba el archivo primero y pase el identificador devuelto a la herramienta de scan.

curl -X POST https://api.ostorlab.co/apis/upload/ \
     -H "X-API-Key: <your-api-key>" \
     -F "file=@app.apk"

La respuesta contiene un upload_id, junto con el nombre del archivo, su tamaño y el hash SHA-256 registrado por el servidor, lo que le permite verificar que el archivo llegó intacto:

{
  "upload_id": "de6024a2-8af5-4e0c-87d2-fdc2c306225f",
  "filename": "app.apk",
  "size": 4171034,
  "sha256": "4ad2930d93c3af606582b26c55ac285485e9623bb508dbf05e5d391b8e4b0969",
  "expires_at": "2026-09-10T09:44:04Z"
}

Pase ese upload_id como application_upload_id a create_mobile_file_scan, como archive_upload_id a create_source_code_archive_scan, o en una de las listas de subida que acepta create_multi_asset_scan.

Tres consideraciones sobre un identificador de carga:

  • Pertenece a la organización que lo subió. Un identificador de otra organización se rechaza igual que uno desconocido, devolviendo Upload not found.
  • Expira. Tras su vencimiento, es rechazado con Upload has expired.
  • Un scan lo consume. Una vez creado el scan, el identificador deja de resolver; es necesario subir el archivo de nuevo para ejecutar un segundo scan. Si la llamada falla, el identificador permanece utilizable, permitiendo reintentos sin volver a subir el archivo.

Warning

Cada herramienta create_* aquí descrita inicia un scan real y consume créditos de scan. Haga que su cliente le muestre el objetivo y el perfil antes de invocarla.

Warning

generate_scan_report se bloquea hasta que el PDF esté finalizado, lo cual puede tardar algunos minutos. Una respuesta lenta no indica un fallo. No interrumpa por timeout ni reintente antes de recibir respuesta. La respuesta contiene una url, no el archivo en sí. Descargue esa URL vía HTTPS incluyendo la misma clave de API en una cabecera X-API-Key.

Pentests con IA

Un pentest con IA —también denominado Agentic Deep Scan— pertenece a una categoría distinta a la de un scan convencional. Sus identificadores no coinciden con los de un scan y sus resultados se denominan riesgos (risks) en lugar de vulnerabilidades.

Herramienta Acción Descripción
get_agentic_deep_scan read Un pentest con IA: su estado, objetivo, tiempos y resumen.
get_ai_pentest_usage read El consumo de tokens de IA que utilizó un pentest con IA.
list_risks read Los riesgos identificados por un pentest con IA, filtrados por pentest y por severidad.
list_ai_provider_api_keys read Las claves de API de proveedores de IA almacenadas por la organización.

Note

Los riesgos no son devueltos por list_vulnerabilities ni por search_vulnerabilities, y un pentest con IA no es devuelto por get_scan. Pasar el id de un pentest con IA a get_scan devuelve Scan not found. —lo que significa «herramienta incorrecta», no «no existe». Un cliente que solo conozca las herramientas de vulnerabilidades reportará erróneamente que el pentest con IA no encontró nada.

Vulnerabilidades

Herramienta Acción Descripción
list_vulnerabilities read Hallazgos en un scan, filtrados por scan_id, risk_rating, kb_detail_id o el ticket al que pertenecen.
search_vulnerabilities read Hallazgos a través de todos los scans, filtrados por activo, rango de fechas, severidad, detalle de base de conocimiento y texto libre.
get_vulnerability read Un hallazgo: detalle técnico, detalle de explotación, vectores CVSS y metadatos de ubicación.
update_vulnerability write Triaje: establecer un nivel de riesgo personalizado o vector CVSS, o marcar un hallazgo como falso positivo o excepción aceptada.

Use search_vulnerabilities cuando la consulta abarque más de un scan —«todos los hallazgos críticos en esta aplicación», «¿qué encontramos el mes pasado?». Use list_vulnerabilities únicamente cuando ya disponga del id de un scan concreto. No itere con list_vulnerabilities sobre una lista de scans para resolver una pregunta que search_vulnerabilities responde en una sola invocación.

Dos aspectos clave sobre update_vulnerability:

  • Marcar un hallazgo como falso positivo o excepción actúa sobre los tickets vinculados a ese hallazgo. Un hallazgo sin ticket permanece sin cambios, y la llamada igualmente reporta éxito.
  • Su parámetro all_vulnerabilities aplica el cambio a todos los hallazgos del mismo scan que compartan el mismo detalle de la base de conocimiento, y recalcula el nivel de riesgo global del scan. El radio de impacto es mucho mayor que un único hallazgo.

Cada hallazgo lleva un campo dna —una huella derivada del título, detalle técnico y ubicación del hallazgo. La misma incidencia detectada en un scan posterior conserva el mismo dna siempre que esos tres elementos no varíen, lo que resulta muy útil para deduplicar al importar hallazgos a otros sistemas. No se garantiza estabilidad si el detalle técnico cambia entre ejecuciones.

Artefactos de scan

Un scan recopila más información aparte de los hallazgos. Estas herramientas leen los artefactos capturados por un scan durante su ejecución.

Herramienta Acción Descripción
list_api_endpoints read Los endpoints de API descubiertos por un scan.
list_http_traffic read Los intercambios HTTP capturados por un scan.
list_http_folders read Las carpetas HTTP observadas por un scan.
list_pcap_files read Las capturas de paquetes (PCAP) producidas por un scan.
list_ide_files read Los archivos localizados dentro del binario del scan.
list_ide_functions read Las funciones descompiladas a partir del binario del scan.
list_ide_logs read Los registros de ejecución capturados en el dispositivo mientras se conducía la aplicación.
list_call_ui_nodes read Las pantallas alcanzadas por un scan móvil mientras interactuaba con la aplicación.
list_stack_traces read Las trazas de pila (stack traces) registradas mientras se ejecutaba la aplicación.

La información recopilada depende del tipo de scan ejecutado. Un scan web contiene tráfico HTTP pero carece de binario descompilado; un scan móvil puede incluir ambos. Un resultado vacío indica que ese scan no recopiló elementos de esa naturaleza, no que el scan haya fallado.

Tickets

Herramienta Acción Descripción
list_tickets read Tickets, filtrados por status, priority, assigned_email, agent, tag, title, created_since, modified_since. Ordenables, con un limit.
get_ticket read Un ticket, por id o por clave (por ejemplo os-1234).
create_ticket write Crea un ticket, opcionalmente con tags, un asignado, un agente de ticket y una fecha límite.
update_ticket write Modifica cualquiera de esos mismos campos.
delete_ticket write Elimina un ticket. Acción irreversible.

Comentarios y checklists

Herramienta Acción Descripción
list_comments, create_comment, update_comment, delete_comment read para listar, write para el resto Hilo de comentarios en un ticket.
list_checklists, create_checklist, update_checklist, delete_checklist read para listar, write para el resto Checklists de remediación adjuntas a un ticket.
create_checklist_item, update_checklist_item, delete_checklist_item write Elementos individuales de una checklist.

Note

Agregar un comentario a un ticket que tiene un agente de tickets asignado iniciará una ejecución del agente.

Los comentarios creados a través de MCP no llevan autor asociado, ya que el servidor autentica una clave de API en lugar de un usuario. En la aplicación web se muestran sin autor.

Agentes de tickets

Un agente de tickets es un agente de IA que la plataforma puede ejecutar sobre un ticket para realizar labores de remediación. Para enrutar un ticket a un agente, simplemente asígnelo.

Herramienta Acción Descripción
list_ticket_agents read Los agentes a los que se pueden enrutar tickets, con un indicador enabled y un resumen de lo que ejecuta cada uno.
assign_ticket_agent write Asigna un agente a un ticket, lo que inicia una ejecución.
create_ticket_agent admin Agrega un nuevo agente, opcionalmente con la definición de ejecución que debe utilizar.
update_ticket_agent admin Modifica el nombre, descripción o definición de ejecución de un agente.
delete_ticket_agent admin Elimina un agente.

Warning

Asignar un agente inicia una ejecución, y una ejecución no se puede deshacer. Una vez que un ticket tiene un agente asignado, cada comentario posterior en ese ticket inicia otra ejecución. Lea el campo agent_run en la respuesta para verificar si esta ejecución realmente inició o fue omitida —no asuma que comenzó automáticamente.

Eliminar un agente anula la asignación en todos los tickets que lo tenían asociado. Los tickets se conservan, pero su agente queda sin asignar; la única forma de restaurarlo es crear un nuevo agente y asignarlo ticket por ticket. La respuesta incluye el contador unassigned_tickets, por lo que conviene verificar dicha cifra antes de dar por sentado que un agente no está en uso. La definición de ejecución del agente también se destruye y no puede consultarse en su totalidad antes de la eliminación: list_ticket_agents devuelve únicamente un resumen ofuscado. Los valores de los argumentos nunca se devuelven, por lo que estas herramientas no pueden utilizarse para extraer credenciales de un agente.

Ticket streams

Un ticket stream agrupa tickets para darles seguimiento conjunto a lo largo de un sprint, un lanzamiento o una iniciativa de seguridad.

Herramienta Acción Descripción
list_ticket_streams read Streams, filtrados por estado, por subcadena de nombre o por id de stream.
get_ticket_stream read Detalles de un stream.
create_ticket_stream write Crea un stream, opcionalmente con responsable, miembros, tickets asociados y fechas.
update_ticket_stream write Modifica cualquiera de esos mismos campos.
delete_ticket_stream write Elimina un stream. Los tickets y las cuentas de usuario referenciadas se conservan.

member_emails y ticket_ids reemplazan el conjunto actual en lugar de añadir elementos a él. Para agregar un miembro, pase la lista completa de los miembros con los que debe quedar el stream.

Activos e inventario

Herramienta Acción Descripción
list_assets attack_surface_read Activos de la superficie de ataque, filtrados por asset_type, owner_id, search, tags.
create_asset write Registra un activo —dominio, aplicación, dirección IP, repositorio o nodo genérico— bajo un propietario.
update_asset write Modifica el propietario, ubicación, color, nota, requisitos de CIA o tags de un activo.
delete_asset write Elimina un activo del inventario.
list_fingerprints attack_surface_read Las tecnologías observadas en todo el inventario.
list_ports attack_surface_read Los puertos diferenciados observados en todo el inventario.
list_protocols attack_surface_read Los protocolos diferenciados observados en todo el inventario.

Un activo se identifica mediante la tupla asset_type y asset_id, y no únicamente por el id. Cada subtipo de activo reside en su propia tabla, por lo que un mismo número representa activos diferentes en subtipos distintos. Tanto update_asset como delete_asset requieren el par, y es el mismo par que devuelve list_assets.

create_asset es idempotente para el mismo propietario: registrar un activo que ya existe allí devuelve la fila existente con el flag created en false en lugar de fallar. Si el identificador ya existe bajo un propietario distinto, la llamada se rechaza con un error genérico, evitando que una escritura pueda usarse para descubrir activos que la clave no puede ver.

Eliminar un activo no elimina sus scans ni sus hallazgos. Los enlaces con el scan se desvinculan y los scans se conservan.

El parámetro tags en update_asset reemplaza la totalidad de las tags del activo; no realiza una fusión.

list_fingerprints, list_ports y list_protocols proporcionan un resumen del inventario en lugar de listar fila por fila. Cada una devuelve los valores diferenciados observados en los activos alcanzables por la clave, respondiendo a «¿qué tecnologías estamos ejecutando?» y «¿qué puertos están expuestos?» sin tener que paginar por list_assets.

Owners

Un propietario (owner) representa a un equipo y define el límite sobre el cual se concede el acceso a nivel de objeto. Con el acceso a nivel de objeto habilitado, una clave ve los activos cuyo propietario puede alcanzar. Debe existir un propietario antes de poder asignarle activos.

Herramienta Acción Descripción
list_owners read Los propietarios de la organización, filtrados por subcadena de nombre.
create_owner write Crea un propietario con nombre, tipo de propiedad y contacto y propietario superior opcionales.
update_owner write Renombra un propietario, cambia su tipo, reasigna su contacto o lo mueve bajo otro propietario superior.
delete_owner write Elimina un propietario.

ownership_type debe ser uno de los siguientes: rejected, acquisition, third_party_service o internal.

Warning

delete_owner rechaza la eliminación mientras el propietario conserve activos asociados o candidatos descubiertos pendientes apuntando hacia él. La eliminación nunca se propaga en cascada —los activos se mantienen y el bloqueo existe precisamente para protegerlos. Si el propietario fuese eliminado manteniendo activos asociados, todas las concesiones de acceso a nivel de objeto realizadas a través de él se perderían, revocando silenciosamente la visibilidad de esos activos para las claves autorizadas por esa vía. Reasigne o elimine primero los activos antes de eliminar al propietario.

Para una clave que no sea admin bajo control de acceso a nivel de objeto, list_owners devuelve los propietarios concedidos a la clave junto con sus propietarios superiores. Una clave admin ve todos los propietarios de la organización. Por lo tanto, un resultado vacío indica que la organización carece de propietarios o que la clave no tiene acceso a ninguno de ellos.

Ubicaciones de activos

Una ubicación es un sitio o región etiquetado y opcionalmente anidado bajo el cual se pueden agrupar activos. Se trata únicamente de una etiqueta organizativa; no es un scanner ni determina dónde se ejecuta un scan.

Herramienta Acción Descripción
list_asset_locations read Las ubicaciones configuradas para la organización.
create_asset_location write Crea una ubicación con un nombre, una dirección opcional y una ubicación superior opcional.
update_asset_location write Renombra una ubicación, cambia su dirección o la mueve bajo otra ubicación superior.
delete_asset_location write Elimina una ubicación.

create_asset_location es idempotente: si se envía una ubicación con el mismo nombre, dirección y ubicación superior, se devuelve tal cual con el flag created en false.

delete_asset_location rechaza la eliminación mientras haya activos vinculados a dicha ubicación o ubicaciones secundarias anidadas bajo ella. La eliminación nunca se propaga en cascada: los activos y las ubicaciones secundarias se conservan, motivo por el cual la operación se detiene. Reubique o retire dichos elementos antes de eliminar la ubicación.

Activos descubiertos

El descubrimiento de superficie de ataque propone candidatos. Cada candidato permanece en una cola de revisión hasta que alguien lo acepta en el inventario o lo rechaza.

Herramienta Acción Descripción
list_autodiscovery_assets attack_surface_audit La cola de descubrimiento pendiente, filtrada por patrón de clave, tipo de candidato, rango de puntuación y propietario.
accept_autodiscovery_asset attack_surface_audit Incorpora un candidato al inventario.
reject_autodiscovery_asset attack_surface_audit Descarta un candidato.
assign_potential_node_owner attack_surface_audit Asigna candidatos pendientes a un propietario.
compute_potential_assets attack_surface_audit Recalcula la cola de inmediato en lugar de esperar a la siguiente ejecución programada.
suggest_autodiscovery_domains attack_surface_audit Sugiere los dominios pertenecientes a una empresa a partir de una descripción en texto libre.
get_attack_surface_graph attack_surface_read El entorno del grafo alrededor de uno o más puntos de partida.

Warning

Aceptar un candidato hace que el activo sea escaneable y facturable —se incorpora al inventario, se convierte en objetivo de scan y cuenta contra el plan de la organización. Tanto accept como reject requieren un identificador explícito y carecen deliberadamente de operaciones por lotes o filtros, impidiendo que un modelo vuelque toda la cola al inventario en una única llamada. Revise cada candidato individualmente.

Rechazar un candidato cuya clave no coincide con ningún activo del inventario registra además dicha clave para que las ejecuciones de descubrimiento posteriores no vuelvan a proponerlo. Rechazar un candidato cuya clave coincide con un activo existente solo lo elimina de la cola, y una ejecución posterior podría volver a sugerirlo.

assign_potential_node_owner establece el propietario bajo el cual quedará el candidato antes de que sea aceptado, asegurando que el activo ingrese al inventario correctamente atribuido a un equipo. No acepta el candidato por sí mismo: este permanece en la cola hasta que se invoque accept_autodiscovery_asset.

get_attack_surface_graph responde a «¿con qué está conectado esto?». Proporcione uno o más puntos de partida y recorrerá las conexiones hacia el exterior, devolviendo el entorno alcanzado en dos listas planas: los nodos y las aristas que los unen. La exploración está acotada, por lo que un punto de inicio en una zona densa del grafo devuelve un entorno delimitado en lugar de la totalidad de elementos alcanzables.

compute_potential_assets ejecuta el descubrimiento bajo demanda sin esperar a la próxima ejecución programada. Si ya hay una ejecución en marcha, la llamada se acopla a ella sin lanzar una segunda, por lo que invocarla dos veces resulta inocuo.

Configuración del descubrimiento

El descubrimiento se orienta mediante un prompt que describe lo que la organización posee, garantizando que los candidatos propuestos correspondan a su empresa y no a entidades con nombres similares.

Herramienta Acción Descripción
get_attack_surface_agent_config read El prompt que guía el descubrimiento para la organización.
create_attack_surface_agent_config write Establece dicho prompt.
update_attack_surface_agent_config write Modifica el prompt.
delete_attack_surface_agent_config write Elimina el prompt.

suggest_autodiscovery_domains complementa estas herramientas: transforma una descripción en texto libre de una empresa en una lista de dominios que probablemente le pertenezcan, facilitando la redacción del prompt sin partir de cero. Solo sugiere —no añade nada a la cola ni al inventario.

Tags

Una tag es una tupla compuesta por name y value, por lo que el mismo nombre puede existir varias veces con valores diferentes —env=prod y env=staging son dos tags distintas. Pase un value para crear una de ellas. Omítalo si desea una etiqueta simple.

Herramienta Acción Descripción
list_tags attack_surface_read Las tags definidas en la organización, filtradas por subcadena de nombre.
list_asset_tags attack_surface_read Las tags en uso real en los activos alcanzables por la clave.
add_tag attack_surface_audit Crea una tag, con color, descripción e icono opcionales.
update_tag attack_surface_audit Renombra o actualiza el estilo de una tag.
delete_tags attack_surface_audit Elimina tags por id.
delete_unused_tags attack_surface_audit Elimina todas las tags que no están referenciadas por ningún elemento.

Los nombres de las tags son propios de cada organización, por lo que un nombre deducido al azar no coincidirá con nada en lugar de fallar. Consulte list_tags antes de filtrar por una tag o asociarla.

update_tag modifica la tag en todos los lugares donde se utilice, de forma que cada ticket y activo que la posea reflejará el nuevo nombre. No está diseñada para trasladar algunos elementos hacia otra tag. Intentar renombrar una tag hacia un par name/value que ya posee otra tag existente será rechazado, evitando fusiones no deseadas.

delete_tags desvincula la tag de cada ticket y activo que la contenía. Dichos tickets y activos se conservan —solo se retira el enlace con la tag. La llamada es atómica (todo o nada): si algún id no se encuentra o no es accesible, no se elimina nada y el error reporta los ids afectados.

list_tags devuelve todas las tags definidas en la organización, incluyendo aquellas no utilizadas. list_asset_tags devuelve únicamente las tags en uso sobre activos alcanzables por la clave, constituyendo una lista más concisa para seleccionar filtros.

delete_unused_tags no recibe identificadores. Elimina en una única llamada todas las tags que no están referenciadas ni por tickets ni por activos, y dicha acción no se puede deshacer. Compare list_tags con list_asset_tags previamente para saber con certeza qué tags se eliminarán.

Credenciales de prueba

Una credencial de prueba es un inicio de sesión reutilizable que la plataforma puede emplear para autenticarse durante la ejecución de un scan.

Herramienta Acción Descripción
list_test_credentials read Las credenciales almacenadas, filtradas por tipo y por subcadena de campos no secretos.
create_test_credential write Almacena una nueva credencial de uno de los tipos soportados.
update_test_credential write Reemplaza los valores de una credencial almacenada, manteniendo su id.
delete_test_credential write Elimina una credencial.

Los secretos almacenados nunca se devuelven. list_test_credentials proporciona los identificadores no secretos y un indicador has_secret por cada fila.

update_test_credential realiza un reemplazo completo, no una fusión. Cualquier campo del tipo de credencial que se omita será borrado, incluida la etiqueta credential_name. Envíe el valor actual de cualquier campo que desee preservar. El credential_type debe coincidir con el tipo original con el que se creó la credencial.

Es preferible utilizar update_test_credential en lugar de borrar y recrear al rotar credenciales: el id se mantiene intacto, por lo que los scans ya configurados para utilizar dicha credencial continuarán autenticándose. Eliminar una credencial provocará que dichos scans comiencen a fallar en la autenticación.

Scans programados

Una regla de programación (schedule rule) lanza scans con una cadencia recurrente, asegurando que la cobertura se mantenga actualizada entre scans puntuales.

Herramienta Acción Descripción
list_schedule_rules read Las reglas de programación de la organización, filtradas según si están activas o no.
create_schedule_rule write Crea una regla sobre uno o más activos, con un perfil de scan y una cadencia.
update_schedule_rule write Modifica los activos, perfil, cadencia o estado activo de una regla.
delete_schedule_rule write Elimina una regla. Acción irreversible.

La cadencia puede ser de dos tipos. Con cadence_type configurado en cron, crontab es una expresión cron estándar de cinco campos como 0 16 * * * para ejecutarse diariamente a las 16:00. Con cadence_type configurado en continuous, max_no_scan_duration_seconds establece el intervalo máximo permitido entre dos scans de los activos cubiertos por la regla.

Warning

Una regla se crea desactivada por defecto, ya que una regla activa lanza scans recurrentes facturables. Mantenga active en su valor por defecto, revise la regla con list_schedule_rules, y únicamente entonces actívela. Envíe active=True en la creación solo si desea que la regla comience a ejecutarse de inmediato.

update_schedule_rule permite activar una regla una vez verificada, pasando active=True. También es el mecanismo para desactivarla temporalmente sin perderla. delete_schedule_rule elimina la regla de forma definitiva; los scans que ya se hubiesen ejecutado se conservan.

Reglas de automatización

Una regla de automatización ejecuta una acción determinada cada vez que los hallazgos coinciden con una condición. Es el mecanismo mediante el cual se conectan la creación automática de tickets y el enrutamiento de notificaciones.

Herramienta Acción Descripción
list_automation_rules read Las reglas compartidas de la organización, filtradas por contexto y por estado de activación.
list_action_definitions read Las acciones que una regla puede ejecutar y los argumentos que espera cada una.
update_automation_rule write Modifica el nombre, condición, acción, contexto o alcance compartido de una regla, o la desactiva.
delete_automation_rule write Elimina una regla.
create_automation_rule admin Crea una regla a partir de un contexto, una consulta de filtrado y una única acción.

context debe ser attack_surface, remediation o inventory. filter_query es la condición, escrita como un array JSON, y debe contener al menos una entrada —un array vacío no aplica filtro alguno, por lo que la regla coincidiría con cada elemento de su contexto.

Al igual que las reglas de programación, una nueva regla de automatización se crea desactivada. Confirme la condición y la acción, y actívela posteriormente con update_automation_rule.

Para desactivar una regla conservándola, invoque update_automation_rule con active=False. Dicha acción es reversible. delete_automation_rule no lo es.

Solo las reglas compartidas con toda la organización son visibles mediante una clave de API. Las reglas personales privadas de un usuario no se devuelven.

La acción ejecutada por la regla debe ser una de las definidas por la plataforma. Consulte list_action_definitions antes de invocar create_automation_rule para verificar qué acciones existen y qué parámetros requieren, en lugar de intentar deducir nombres de acción y procesar fallos.

Scanners

Un scanner es una máquina propia que ejecuta scans, de modo que el tráfico de scan se origina en su red en lugar de la red de Ostorlab. Un grupo de scanners reúne varios de ellos para que un scan pueda apuntar al grupo en lugar de a un único equipo.

Herramienta Acción Descripción
list_scanners read Los scanners que la organización puede utilizar.
list_scanner_groups read Los grupos de scanners definidos en la organización.
create_scanner admin Registra un scanner para permitirle vincular scans a él.
update_scanner admin Modifica el nombre, descripción o pertenencia a grupos de un scanner.
delete_scanner admin Da de baja un scanner. Acción irreversible.
create_scanner_group admin Crea un grupo de scanners.
update_scanner_group admin Modifica el nombre, descripción o scanners miembros de un grupo.
delete_scanner_group admin Elimina un grupo de scanners.
grant_scanner_access admin Permite que organizaciones secundarias ejecuten scans en uno de sus scanners.
revoke_scanner_access admin Revoca dicho acceso.

grant_scanner_access y revoke_scanner_access solo alcanzan organizaciones dependientes de la suya, y el scanner debe ser propiedad de su organización. La concesión es atómica: una lista que incluya una organización no subordinada se rechazará antes de escribir ningún cambio, evitando concesiones parciales.

Integraciones

Herramienta Acción Descripción
list_integrations read Las integraciones con terceros conectadas en la organización, con su estado de activación y destino no secreto.
get_jira_ticket_map read Informa si un ticket fue enviado a Jira y en qué issue de Jira se convirtió.
configure_jira_integration write Establece o reemplaza la URL del espacio de trabajo de Jira, credenciales y proyecto por defecto.
configure_slack_integration write Agrega un webhook de Slack y selecciona qué eventos de finalización de scan notifican en él.
create_servicenow_ticket write Envía un ticket a ServiceNow como un incidente.
get_slack_integration admin Consulta los webhooks de Slack configurados y sus selectores de notificación.
delete_git_pat_integration admin Elimina una integración de token de acceso personal (PAT) de Git.
delete_servicenow_sync_config admin Elimina una configuración de sincronización de ServiceNow.

Invoque list_integrations antes de cualquier acción que dependa de una integración —enviar un ticket, emitir una notificación o mencionar un proveedor en una respuesta. Le permite conocer qué proveedores están conectados, evitando tener que intentar la acción y leer un error para comprobarlo. Una integración reportada como activa puede tener credenciales expiradas o revocadas; estas herramientas no pueden determinar si funciona correctamente en tiempo real.

Ninguna de estas herramientas devuelve credenciales. Esto incluye tokens de API de Jira, secretos de OAuth, contraseñas y URLs de webhooks entrantes de Slack. Solo se devuelven campos no confidenciales autorizados.

Las dos herramientas de configuración se comportan de forma diferente ante llamadas repetidas. Jira permite una única configuración por organización, por lo que invocar nuevamente configure_jira_integration actualiza el mismo registro y sustituye las credenciales anteriores. Slack no tiene esta restricción, por lo que llamar de nuevo a configure_slack_integration agrega un segundo webhook en lugar de modificar el primero.

Warning

delete_git_pat_integration detiene los scans de código fuente y las pull requests de remediación automática que dependían de él. El token almacenado se elimina de Ostorlab pero sigue siendo válido en el proveedor, por lo que debe revocarlo en el proveedor por separado.

delete_servicenow_sync_config destruye además el registro de qué tickets ya habían sido enviados bajo dicha configuración. Los incidentes de ServiceNow se conservan, pero se pierde el enlace desde cada ticket de Ostorlab a su número de incidente, impidiendo el seguimiento o actualización de tickets ya enviados. Eliminar la última configuración de sincronización activa impide por completo que los tickets lleguen a ServiceNow.

La tabla anterior resume las herramientas principales. Las secciones siguientes detallan las herramientas adicionales para cada proveedor: dichas tablas amplían la lista en lugar de duplicarla.

Webhooks

Una integración de webhook es una URL propia hacia la cual Ostorlab envía notificaciones de eventos (POST).

Herramienta Acción Descripción
create_webhook_integration admin Define la URL donde Ostorlab publicará las notificaciones de eventos.
update_webhook_integration admin Modifica el endpoint, cabeceras o estado activo de un webhook.
delete_webhook_integration admin Elimina una integración de webhook.

Slack

Herramienta Acción Descripción
update_slack_integration admin Modifica la URL de un webhook de Slack o sus selectores de notificación.
delete_slack_integration admin Elimina un webhook de Slack.

Dado que configure_slack_integration añade un nuevo webhook en lugar de reemplazar el anterior, update_slack_integration es el método para modificar un webhook existente. Tanto este como delete_slack_integration requieren un id, que corresponde al id devuelto por get_slack_integration.

Jira

Herramienta Acción Descripción
get_jira_integration admin La configuración de Jira almacenada, sin sus credenciales.
test_jira_integration admin Ejecuta las comprobaciones de Jira y reporta cada resultado individualmente.
create_jira_ticket_map write Registra que un ticket corresponde a una incidencia de Jira ya existente.
update_jira_ticket_map write Reasigna el mapeo de Jira de un ticket hacia otra incidencia.
delete_jira_ticket_map write Desvincula un ticket de su incidencia de Jira.
create_jira_ticket write Crea una nueva incidencia en Jira para un ticket y registra la correspondencia.
list_jira_metadata admin Los proyectos, tipos de incidencia y campos que las credenciales almacenadas pueden visualizar.

Un ticket map es el enlace entre un ticket de Ostorlab y una incidencia de Jira, y get_jira_ticket_map lo consulta. Las tres herramientas de escritura de mapeo gestionan dicho enlace manualmente para incidencias creadas en Jira externamente a Ostorlab. Modifican únicamente el enlace. Ninguna de ellas crea, edita ni elimina incidencias en Jira, por lo que desvincular un ticket deja intacta la incidencia en Jira.

create_jira_ticket es la herramienta que sí interactúa directamente con Jira. Crea una nueva incidencia para el ticket y registra el mapeo en la misma llamada, siendo la herramienta adecuada cuando la incidencia de Jira aún no existe. Ante un fallo no se crea nada —ni incidencia ni mapeo— y se especifica la causa, de forma que si las credenciales no tienen acceso a un proyecto se informa claramente en lugar de arrojar un error genérico.

list_jira_metadata permite consultar los valores requeridos por create_jira_ticket y configure_jira_integration: los proyectos accesibles para las credenciales, los tipos de incidencia admitidos por cada proyecto y los campos disponibles para el mapeo. Un resultado vacío indica que las credenciales no tienen acceso a ningún proyecto, lo que conviene verificar con test_jira_integration antes de asumir un error en la herramienta.

test_jira_integration reporta cada verificación por su nombre, de modo que un fallo permite identificar con precisión qué componente es incorrecto —la URL, las credenciales o el proyecto— en lugar de limitarse a indicar un fallo indeterminado.

Linear

Herramienta Acción Descripción
configure_linear_integration admin Establece o reemplaza la conexión con Linear.
get_linear_integration admin La configuración de Linear almacenada, sin sus credenciales.
test_linear_integration admin Reporta si Linear está configurado, activo y accesible.
list_linear_teams admin Los equipos de Linear sobre los cuales se pueden crear issues.

ServiceNow

Herramienta Acción Descripción
configure_servicenow_integration admin Establece o reemplaza la conexión con ServiceNow.
test_servicenow_integration admin Ejecuta las verificaciones de una configuración de ServiceNow y reporta cada resultado individualmente.
delete_servicenow_integration admin Elimina una integración con ServiceNow.
configure_servicenow_sync_config admin Mapea tickets hacia una tabla de ServiceNow y sus campos correspondientes.
get_servicenow_sync_config read Muestra cómo una configuración de sincronización mapea tickets a una tabla.
list_servicenow_fields read Las columnas de la tabla de ServiceNow a la que apunta una configuración de sincronización.
get_servicenow_ticket_map read Informa si un ticket fue enviado a ServiceNow y en qué registro se convirtió.
create_servicenow_ticket_map write Registra que un ticket corresponde a un registro de ServiceNow ya existente.
update_servicenow_ticket_map write Reasigna el mapeo de un ticket hacia otro registro en ServiceNow.
delete_servicenow_ticket_map write Desvincula un ticket de su registro en ServiceNow.

ServiceNow se configura en dos pasos. configure_servicenow_integration almacena la instancia y sus credenciales. configure_servicenow_sync_config define luego a qué tabla se envían los tickets y a qué columna corresponde cada campo del ticket. Invoque primero list_servicenow_fields para consultar las columnas reales de dicha tabla, garantizando que el mapeo utilice columnas válidas.

Las herramientas de correspondencia de tickets funcionan igual que las de Jira: gestionan el vínculo entre un ticket de Ostorlab y un registro de ServiceNow sin alterar el registro en sí. create_servicenow_ticket es la herramienta encargada de crear efectivamente un registro en ServiceNow.

Código fuente

Herramienta Acción Descripción
list_repositories read Los repositorios que Ostorlab puede alcanzar actualmente.
create_git_pat_integration admin Registra un token de acceso personal (PAT) de Git.
update_git_pat_integration admin Reemplaza un token almacenado o modifica su alcance.
create_standard_git_integration admin Registra una instancia autohospedada de Git.
update_standard_git_integration admin Modifica el registro de una instancia autohospedada de Git.
delete_standard_git_integration admin Elimina el registro de una instancia autohospedada de Git.
enable_github_app_connection admin Reanuda scans de código fuente y pull requests para los repositorios de una GitHub App.
disable_github_app_connection admin Los detiene temporalmente, conservando la instalación.
delete_github_app_connection admin Elimina la instalación de una GitHub App en la organización.
update_source_code_oauth_integration admin Activa o desactiva una integración OAuth de código fuente.
delete_source_code_oauth_integration admin Elimina una integración OAuth de código fuente.

list_repositories es la herramienta a consultar antes de create_source_code_scan. Devuelve los repositorios que las integraciones de código fuente conectadas exponen en ese momento, asegurando que se escanee un recurso que la plataforma puede clonar realmente en lugar de un nombre aproximado.

disable_github_app_connection es la variante reversible de delete_github_app_connection. La desactivación detiene scans y pull requests manteniendo la instalación, de modo que enable_github_app_connection restaura la operatividad inmediatamente. La eliminación retira la instalación por completo, exigiendo reinstalar la aplicación desde GitHub para recuperarla.

App Center

Herramienta Acción Descripción
create_app_center_integration admin Conecta una aplicación de App Center para que sus compilaciones se escaneen automáticamente.
update_app_center_integration admin Modifica una integración de App Center.
delete_app_center_integration admin Elimina una integración de App Center.

Vanta

Herramienta Acción Descripción
get_vanta_auth_url admin El enlace a abrir en el navegador para autorizar a Ostorlab en Vanta.
delete_vanta_integration write Desconecta Vanta.

La conexión con Vanta requiere un navegador. get_vanta_auth_url proporciona el enlace que un usuario debe abrir para autorizar a Ostorlab, y la vinculación se completa en dicho entorno y no a través de una herramienta, impidiendo que un cliente complete este proceso de forma autónoma.

Organización y acceso

Herramienta Acción Descripción
me ninguna más allá de una clave válida La organización a la que pertenece la clave y el rol que ostenta.
list_shared_access_tokens read Los enlaces de compartición activos de la organización, con el scan que otorga cada uno y su frecuencia de uso.
list_invitations read Las personas invitadas a la organización que aún no se han incorporado.
create_shared_access_token write Crea un enlace que permite a personas sin cuenta visualizar un scan concreto.
revoke_shared_access_token write Inhabilita inmediatamente un enlace de acceso compartido.
list_organisation_users admin Quién tiene acceso a la organización, con qué rol y acotado a qué propietarios.
add_user admin Invita a un usuario a unirse a la organización con un rol determinado.
update_user_access admin Modifica el rol de un miembro o los propietarios a los que está asignado.
revoke_user admin Retira el acceso de un usuario a la organización.
review_invitation admin Acepta o rechaza una invitación pendiente.
get_organisation_settings admin Los ajustes y permisos de la organización.
update_organisation_settings admin Modifica las opciones de configuración que admiten escritura.
list_api_keys admin Las claves de API de la organización: nombre, rol, fechas de creación y vencimiento, estado de revocación y forma enmascarada de la clave.
update_api_key admin Restringe una clave: reduce su rol, retira asignaciones de propietarios, adelanta su vencimiento o la renombra.
revoke_api_key admin Desactiva inmediatamente una clave de API.
list_audit_actions admin Registro de qué usuario modificó qué elemento y cuándo, filtrado por rango temporal y por actor.

me describe a la clave, no a un usuario humano. El servidor autentica una clave, por lo que la respuesta a «¿quién soy?» corresponde a la organización a la que pertenece la clave y el nombre, prefijo, rol, propietarios concedidos y fecha de vencimiento de la propia clave. No devuelve ninguna cuenta de usuario.

add_user envía una invitación en lugar de crear una cuenta directamente. El usuario figurará en list_invitations hasta que acepte, momento en el cual aparecerá en list_organisation_users.

update_api_key únicamente puede restringir una clave. El rol establecido no puede ser superior al que la clave ya posee, las asignaciones de propietarios pueden retirarse pero no añadirse, y el vencimiento solo puede adelantarse en el tiempo. Por lo tanto, no es posible usarla para conceder privilegios adicionales a una clave, y nunca revela material de clave.

La revocación es la única acción que invalida de inmediato una clave de API. Una fecha de vencimiento por sí sola no lo hace: la clave continuará funcionando en la ruta MCP hasta que se marque como revoked. revoke_api_key aplica dicha marca de forma irreversible. Una clave no puede revocarse a sí misma; esa petición es rechazada, ya que cortaría la conexión en mitad de la sesión.

El texto en claro de una clave de API nunca es devuelto por ninguna herramienta. Existe únicamente en el instante en que la clave es creada, almacenándose únicamente su hash con posterioridad. list_api_keys devuelve en su lugar masked_key —el prefijo de la clave seguido de asteriscos, en el mismo formato mostrado en la interfaz web y en la traza de auditoría. Utilice dicho formato cuando deba identificar una clave ante otra persona.

Warning

Cualquier persona en posesión de un token de acceso compartido puede ver el scan al que apunta y sus hallazgos sin necesidad de tener cuenta. Estos tokens no vencen. list_shared_access_tokens enumera únicamente los enlaces activos en este momento, por lo que cada fila representa un acceso concedido actualmente. El token sin procesar se devuelve solo una vez, en la respuesta a create_shared_access_token.

list_audit_actions devuelve una lista vacía en lugar de un error si la organización tiene desactivada la auditoría de acciones. La respuesta incluye un campo message aclaratorio, evitando que «cero filas» se interprete como «no ha habido actividad».

Inicio de sesión único (SSO)

Herramienta Acción Descripción
get_saml_config admin La configuración de inicio de sesión único (SSO) mediante SAML de la organización.
configure_saml admin Configura el SSO mediante SAML por primera vez.
update_saml admin Modifica la configuración SAML existente.

configure_saml es una operación estricta de creación: se rechaza si la organización ya dispone de una configuración y nunca sustituye una existente. update_saml es la herramienta para actualizar una configuración preexistente y realiza una actualización parcial —únicamente se escriben los campos enviados. Consulte previamente get_saml_config para comprobar cuál de las dos procede utilizar.

SLOs de remediación

Un SLO (Service Level Objective) en este contexto representa un plazo límite: el número máximo de días que un ticket de una severidad o prioridad determinada puede permanecer abierto.

Herramienta Acción Descripción
get_slo_config read Los plazos de la organización por severidad y prioridad, expresados en días.
update_slo_config write Modifica dichos plazos.

Un plazo establecido en null indica que no existe límite temporal para esa severidad o prioridad. update_slo_config opera mediante actualización parcial: una clave enviada con un número positivo establece dicho plazo, una clave enviada como null lo elimina, y cualquier clave omitida permanece sin alteraciones. Si se envía una clave desconocida, la petición es rechazada.

Prompts de automatización de UI

Herramienta Acción Descripción
list_ui_automation_rules read Las reglas de automatización de interfaz de usuario disponibles para la organización.
create_ui_prompts write Crea prompts de automatización de interfaz de usuario.
update_ui_prompts write Modifica el código, nombre o descripción de los prompts de automatización de interfaz pertenecientes a su organización.
delete_ui_prompts write Elimina prompts de automatización de UI pertenecientes a su organización. Acción irreversible.

code representa un reemplazo completo y se sobrescribe en cada llamada, mientras que name y description solo se modifican si se envían. Por ende, una invocación que solo pretenda renombrar un prompt debe reenviar igualmente el código existente, o de lo contrario el código se sobrescribirá con lo que se haya transmitido.

La llamada no es de tipo «todo o nada». Los prompts alcanzables se actualizan aun cuando otros no puedan serlo. La respuesta desglosa los identificadores actualizados y, para cada uno de los restantes, el motivo por el cual no se modificó.

list_ui_automation_rules devuelve también reglas que la organización no posee, correspondientes a las reglas compartidas que cualquier organización puede emplear. Únicamente las que pertenecen a su organización pueden modificarse o eliminarse, por lo que un prompt que figure correctamente en el listado puede ser denegado por update_ui_prompts y delete_ui_prompts.

Base de conocimiento

La base de conocimiento contiene datos de referencia propios de Ostorlab. Es idéntica para todas las organizaciones y no representa una vista exclusiva de la suya, por lo que estas herramientas devuelven registros que no guardan relación directa con sus propios scans.

Herramienta Acción Descripción
list_cves read Registros de CVE, buscados por id, severidad o texto en la descripción.
list_kb_applications read Las aplicaciones públicas monitorizadas por Ostorlab para detectar CVEs recién publicados.
list_kb_targets read Registros que vinculan un CVE con las versiones de aplicación afectadas por él.
list_app_cards read Las App Cards compartidas disponibles en Ostorlab.

list_kb_targets actúa como punto de unión entre las otras dos: dado un CVE identifica las versiones de aplicación afectadas, y dada una aplicación lista los CVEs publicados frente a ella.

Store de agentes

Un perfil de scan se compone de agentes. La tienda (store) constituye el catálogo de agentes existentes.

Herramienta Acción Descripción
search_agents read Busca en la tienda de agentes por nombre.
get_agent read Un agente específico, con los argumentos que acepta su versión más reciente.

search_agents representa el paso de descubrimiento y get_agent el paso de detalle: busque por nombre para localizar la clave del agente y consulte a continuación los argumentos que dicha clave admite.

Exportaciones

Cada una de estas herramientas genera un archivo y devuelve un enlace hacia él, no el contenido directo. Descargue dicha URL mediante HTTPS empleando la misma clave de API en la cabecera X-API-Key, de forma idéntica a como opera generate_scan_report.

Herramienta Acción Descripción
export_scan read El archivo comprimido completo de un scan.
export_scan_sarif read Los hallazgos de un scan en formato SARIF.
export_vulnerabilities read Los hallazgos de un scan en formato CSV.
export_tickets read Los tickets de remediación en formato CSV.
export_assets attack_surface_read Los activos confirmados del inventario en formato CSV.
export_potential_nodes attack_surface_read Los candidatos de descubrimiento pendientes en formato CSV.

Las dos exportaciones de superficie de ataque requieren attack_surface_read, acción concedida a todos los roles. Las cuatro restantes requieren read, por lo que una clave attack_surface_auditor puede exportar activos y candidatos de descubrimiento, pero no scans, hallazgos ni tickets.

Límites de resultados

Toda herramienta de listado limita la cantidad de datos que devuelve. La forma en que la herramienta informa de dicho límite no es homogénea en toda la plataforma. Existen tres comportamientos:

Algunas herramientas devuelven un cursor. Un cursor es un token opaco que marca el punto donde concluyó la página recibida. Se devuelve en el campo next_cursor. Envíe dicho valor en el argumento cursor de la siguiente llamada para obtener la página posterior. Un valor null en next_cursor indica que ha llegado a la última página. No intente interpretar ni construir cursores manualmente: su estructura interna es un detalle de implementación y solo tiene sentido para la herramienta que lo generó.

Otras herramientas devuelven un valor booleano truncated. Este indica que existen más filas en el servidor, pero no proporciona un cursor para obtenerlas. En tal caso, acote la consulta mediante filtros.

Unas pocas no devuelven ninguno de los dos indicadores. En ellas el límite opera de forma silenciosa: se recibe el número tope de filas sin señal alguna de la existencia de filas adicionales.

Herramienta Por defecto Máximo Cómo se señalan más filas
list_scans 200 200 next_cursor
list_vulnerabilities 200 200 next_cursor
list_assets 200 200 next_cursor
list_risks 200 200 next_cursor
get_scan_status (historial de estados) 50 50 nada
list_scan_profiles sin límite sin límite no aplicable
list_checklists sin límite sin límite no aplicable
search_vulnerabilities 200 200 truncated
list_tags 200 200 next_cursor
list_api_keys 200 200 truncated
list_shared_access_tokens 200 200 truncated
list_ticket_agents 100 100 truncated
list_owners 200 200 next_cursor
list_asset_locations 200 200 next_cursor
list_autodiscovery_assets 200 200 next_cursor
list_test_credentials 200 200 next_cursor
list_integrations 200 200 next_cursor
list_audit_actions 200 200 next_cursor
list_organisation_users 200 200 next_cursor
list_schedule_rules 100 100 next_cursor
list_automation_rules 100 100 next_cursor
get_slack_integration 100 100 next_cursor
list_ticket_streams 50 200 next_cursor
list_tickets 50 200 truncated y next_cursor
list_comments 50 200 truncated y next_cursor

Solicitar un límite superior al máximo lo ajusta automáticamente al tope en lugar de rechazar la petición. Solicitar cero, un número negativo o un valor no numérico es rechazado con Invalid limit. Un cursor está vinculado a los filtros con los que fue generado, por lo que reutilizarlo con filtros diferentes será rechazado con Invalid cursor. en lugar de devolver silenciosamente la página errónea.

En las herramientas que no emiten ninguna señal, el tope representa toda la respuesta que obtendrá: un scan con 500 entradas de estado devolverá 50 desde get_scan_status, sin indicación de que existen las 450 restantes. Acote mediante filtros cuando el recuento exacto sea relevante —no solicite a un modelo que calcule totales a partir de una lista truncada.

Eliminación

Toda herramienta delete_* y revoke_* de esta página elimina datos de manera permanente. Esto abarca delete_ticket, delete_comment, delete_checklist y delete_checklist_item, e igualmente delete_asset, delete_owner, delete_asset_location, delete_tags, delete_unused_tags, delete_test_credential, delete_scanner, delete_scanner_group, delete_schedule_rule, delete_automation_rule, delete_ui_prompts, delete_ticket_agent, delete_ticket_stream, delete_checklist, las operaciones de eliminación de integraciones, y revoke_api_key, revoke_shared_access_token y revoke_user.

Algunas de ellas rechazan la acción en lugar de propagarse en cascada. delete_owner y delete_asset_location no se ejecutarán mientras existan elementos que dependan de ellos, y delete_asset conserva los scans y hallazgos vinculados al activo. En los casos en que una herramienta se propaga en cascada o conserva datos, la sección descriptiva correspondiente lo especifica.

Las herramientas publican anotaciones (annotations) dirigidas al cliente. Una anotación es una indicación que acompaña a la herramienta en el catálogo y describe el impacto de su ejecución, permitiendo al cliente decidir si debe solicitar confirmación previa al usuario. Se emplean tres tipos:

  • readOnlyHint — la herramienta no altera el estado.
  • destructiveHint — la herramienta altera el estado de forma irreversible.
  • idempotentHint — invocar la herramienta dos veces produce el mismo efecto que invocarla una vez.

Las herramientas destructivas están debidamente señaladas, al igual que cualquier otra herramienta que elimine o sobrescriba datos.

Warning

Una anotación es una sugerencia, no un mecanismo de bloqueo estricto. La solicitud de confirmación depende exclusivamente de la implementación de su cliente. Ciertos clientes solicitan confirmación cada vez que se invoca una herramienta destructiva, otros solicitan autorización la primera vez y la recuerdan, y otros no preguntan en absoluto. El servidor procesará la llamada en cualquiera de los casos. Compruebe cómo gestiona su cliente las indicaciones destructivas antes de conectar un modelo a una clave con permisos de escritura.

No todas las herramientas incluyen anotaciones explícitas. Una herramienta sin anotaciones hace que el cliente adopte el comportamiento por defecto de la especificación MCP, asumiendo que la llamada es destructiva y no idempotente. Esto significa que una herramienta de solo lectura no anotada puede parecer más peligrosa para un cliente cauteloso de lo que realmente es.

Errores

Una herramienta que experimenta un fallo devuelve una respuesta estándar exitosa en cuyo cuerpo figura el campo error:

{"error": "Invalid API Key."}

El indicador JSON-RPC isError permanece en false. Si su cliente bifurca su lógica evaluando isError, interpretará los fallos de autenticación y de permisos como llamadas exitosas —inspeccione el campo error en su lugar.

Ejemplos

Peticiones en lenguaje natural que funcionan de forma óptima una vez conectado el servidor:

  • «Lista los scans finalizados en la última semana con nivel de riesgo alto.»
  • «Muéstrame los hallazgos críticos del scan 12345 y abre un ticket para cada uno.»
  • «¿Cuál es el detalle técnico de la vulnerabilidad 987 y hay comentarios registrados en su ticket?»
  • «Marca la vulnerabilidad 654 como falso positivo.»
  • «¿Qué tickets abiertos están asignados a rubberduck?»
  • «¿Qué perfiles de scan podemos ejecutar contra un objetivo web? Inicia un Fast Scan sobre example.com.»
  • «¿Cuáles de nuestras claves de API nunca han sido revocadas y fueron creadas hace más de un año?»
  • «¿Qué candidatos figuran en la cola de descubrimiento de superficie de ataque con una puntuación superior a 80?»

Resolución de problemas

HTTP 404 al conectar A la URL le falta el segmento de la clave de API o la barra diagonal final. Debe tener el formato /apis/mcp/YOUR_API_KEY/.

Invalid API Key. La clave de API no es reconocida. Verifique que fue copiada en su totalidad y que no ha sido revocada.

API Key does not have write permission. La herramienta requiere un rol más elevado del que posee la clave. Emita una clave con el rol necesario.

Scan not found. para un scan visible en la aplicación web Existen cuatro causas posibles: el scan está archivado (get_scan y get_scan_status rechazan scans archivados), el scan pertenece a otra organización, su organización utiliza acceso a nivel de objeto y dicha clave no tiene concedido ese scan, o el id corresponde a un pentest con IA en lugar de a un scan convencional —las herramientas de scan no resuelven identificadores de pentests con IA, debiendo emplear get_agentic_deep_scan para ellos. Un scan no accesible se reporta deliberadamente de la misma forma que uno inexistente.