Saltar al contenido principal

Descripción general

Un reporte es la forma de avisarle a ChainPatrol sobre una amenaza. Cada reporte agrupa uno o más assets (activos digitales: las URL, dominios, cuentas de redes sociales o direcciones de blockchain sobre los que quieres que actuemos) con el contexto y la evidencia que nuestro equipo de revisión necesita para actuar. Todo pasa por POST /report/create. Los archivos de evidencia son lo único que requiere una llamada aparte antes: los archivos se suben a POST /attachment/upload, que devuelve las URL que luego pasas a report.create.
Los adjuntos son opcionales. Si no tienes archivos para enviar, omite por completo el paso 2 y llama a report.create directamente. Y si ya alojas tu evidencia en algún lugar de acceso público, pon esas URL directamente en attachmentUrls: el endpoint de subida existe para que no tengas que alojarlas tú.

Antes de empezar

Necesitas:
  • Una clave de API con permiso Read & write (lectura y escritura), enviada como X-API-KEY en cada solicitud. Las claves nuevas son de solo lectura de forma predeterminada, y una clave de solo lectura recibe 403 Forbidden aquí. Consulta Autenticación de la External API.
  • El slug de tu organización: el identificador que aparece en la URL de tu Dashboard (panel principal), es decir, https://app.chainpatrol.io/<slug>. Si tu clave está limitada a una sola organización, puedes omitir organizationSlug y usaremos la organización de la clave.
Todos los endpoints se sirven desde https://app.chainpatrol.io/api/v2.

El flujo

1

Verifica si ya existe un reporte (opcional)

Si tu pipeline puede volver a descubrir la misma amenaza, verifica primero con POST /reports/search. Volver a reportar un asset que ya tiene un reporte pendiente falla con un 422 y un error REPORT_ALREADY_EXISTS, así que buscar primero hace que tu tasa de errores siga siendo significativa.
2

Sube tus archivos de evidencia

Envía cada archivo a POST /attachment/upload y guarda las URL que devuelve. Se admiten archivos de mensajes .eml, capturas de pantalla, PDF y más; consulta los tipos de archivo admitidos.
Response
Todavía no hay nada adjunto a un reporte: la subida solo almacena el archivo y te entrega una URL. Con multipart puedes enviar hasta 10 archivos en una sola solicitud; el límite de 4 MB se aplica a todo el cuerpo de la solicitud.
3

Crea el reporte

Llama a POST /report/create con tus assets y las URL de los adjuntos del paso anterior.
Response
Guarda el id: es como se identifica el reporte en el dashboard y en GET /organization/reports.
4

Haz seguimiento de lo que pasa después

El reporte pasa a revisión. Las imágenes que adjuntaste aparecen integradas en el reporte; los demás archivos se listan como evidencia descargable, y nuestro equipo de Takedowns (solicitudes de baja de contenido fraudulento) puede reenviarlos al registrador o al proveedor de hosting; por eso un .eml original vale más que una captura de pantalla de ese mensaje.Consulta periódicamente GET /organization/reports para ver el estado, o configura un webhook para recibir una notificación cuando cambien los estados de los assets, en lugar de consultar periódicamente.

Ejemplo completo

Sube y reporta en un solo script: dos archivos se suben en una única solicitud multipart, y ambas URL se adjuntan a un mismo reporte.

Campos del reporte

Los campos que más vas a usar. El esquema completo, con todos los campos opcionales, está en la página de referencia Crear reporte.
organizationSlug, discordGuildId y telegramGroupId son tres formas de nombrar lo mismo. Usa organizationSlug salvo que estés creando una integración con Discord o Telegram y solo tengas a mano el ID de la plataforma.

Los adjuntos en más detalle

  • Cualquier tipo de archivo de la lista admitida, no solo imágenes. El endpoint de subida acepta mensajes .eml y .msg, PDF, documentos de Word, CSV, texto plano y los formatos de imagen más comunes.
  • Las imágenes se muestran; los demás archivos se listan. Clasificamos por extensión: las extensiones de imagen se muestran integradas en el reporte y todo lo demás aparece como archivo descargable.
  • Los archivos que no son imágenes pueden enviarse con el takedown. Nuestro equipo puede adjuntarlos al correo que se envía a un registrador o proveedor de hosting, con el nombre de archivo que subiste; por eso, usa nombres de archivo descriptivos.
  • Las URL alojadas por ti también funcionan. Todo lo que esté en attachmentUrls se guarda tal cual. Si alojas la evidencia por tu cuenta, mantén esos enlaces activos; no podemos volver a descargar un enlace que ya expiró.
  • Adjunta los archivos al reporte del que son evidencia. Los adjuntos pertenecen al reporte en su conjunto, no a un asset individual; por eso, si dos amenazas no están relacionadas, crea dos reportes.

Manejo de errores

report.create devuelve 422 Unprocessable Content cuando la solicitud está bien formada pero los assets no se pueden reportar; es el resultado más común que debes contemplar en tu código. La respuesta incluye una entrada por cada asset con error en data.errors, cada una con un errorType, un message y una suggestion:
Todos los assets deben ser válidos para que se cree el reporte: un 422 significa que no se creó ningún reporte. Corrige o quita los assets con problemas y vuelve a enviar. Todos los errorType están listados en la página de referencia Crear reporte. Para los errores de subida, consulta las respuestas de error en la página Subir archivo adjunto.

Buenas prácticas

  • Un reporte por amenaza, varios assets por reporte. Si una campaña de phishing abarca un sitio, una cuenta de Twitter y una dirección de wallet, pon los tres en un mismo reporte: el contexto compartido es lo que permite revisarlos juntos.
  • Busca antes de enviar si tu pipeline puede volver a descubrir el mismo asset.
  • Envía el .eml original cuando lo tengas. Los encabezados son lo que los proveedores de correo y los registradores usan para actuar; una captura de pantalla de un correo es una evidencia mucho más débil.
  • Incluye una descripción con la que una persona pueda actuar. Cuál fue el señuelo, dónde se vio, quién lo reportó.
  • Define brandSlug cuando sepas qué marca se está suplantando: ahorra un paso de revisión. Obtén los slugs válidos desde Listar marcas de la organización.
  • No reintentes un 422 sin cambios. Es un resultado de validación, no una falla transitoria. Reintenta los 5xx con backoff exponencial.

Otras formas de crear reportes

CLI

chainpatrol reports create crea un reporte desde la terminal, incluido --attachment-url para la evidencia que ya subiste.

Dashboard

Tu equipo puede crear reportes manualmente y arrastrar archivos de evidencia directamente sobre ellos.

Security Portal

Un formulario público de envío para tu comunidad, sin necesidad de iniciar sesión.

Bots

Los bots de Discord, Telegram y Slack permiten que tu comunidad reporte desde donde ya está.
La CLI y el SDK de JavaScript reciben URL de adjuntos, no archivos. Para subir un archivo hoy, llama directamente a POST /attachment/upload y pasa la URL que devuelve.