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 porPOST /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-KEYen cada solicitud. Las claves nuevas son de solo lectura de forma predeterminada, y una clave de solo lectura recibe403 Forbiddenaquí. 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 omitirorganizationSlugy usaremos la organización de la clave.
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 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.
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
3
Crea el reporte
Llama a Guarda el
POST /report/create con tus assets y las URL de
los adjuntos del paso anterior.Response
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
.emly.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
attachmentUrlsse 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:
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
.emloriginal 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
brandSlugcuando 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
422sin cambios. Es un resultado de validación, no una falla transitoria. Reintenta los5xxcon 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.