Saltar al contenido principal
POST
List suspected threats for organization

Descripción general

Lista las Suspected Threats (amenazas sospechosas detectadas automáticamente, todavía sin confirmar) de tu organización: Assets (activos digitales: URL, direcciones, perfiles, apps, etc.) que la detección automatizada de ChainPatrol marcó. Una suspected threat no está confirmada hasta que se revisa y se bloquea. Usa el filtro blockStatus que aparece más abajo para seleccionar las que ya fueron confirmadas. La API conserva el nombre “detection”: el endpoint es /detection/list, los resultados vienen en el arreglo detections y cada elemento es un resultado de detección.

Inicio rápido

Autenticación

Incluye tu clave de API en el encabezado X-API-KEY:

Solicitud de ejemplo

Esquema de la solicitud

Cuerpo de la solicitud

startDate y endDate filtran según cuándo se creó la suspected threat, no según cuándo el asset se vio por primera vez, se reportó o se bloqueó. Omite ambos cuando quieras todas las suspected threats: un rango de fechas deja fuera en silencio el historial más antiguo, lo que se interpreta como resultados faltantes y no como un filtro.

Esquema del filtro

Cada objeto de filtro debe tener la siguiente estructura:

Propiedades del filtro

1. Filtro de fuente ("source")
  • "ASSET_CHECK" - Verificaciones de assets
  • "BING_SEARCH" - Resultados de búsqueda de Bing
  • "CERTSTREAM" - Registros de transparencia de certificados
  • "DNS_TWIST" - Detección con DNS twist
  • "DUCK_DUCK_GO_SEARCH" - Resultados de búsqueda de DuckDuckGo
  • "EXTERNAL" - Envíos externos de amenazas
  • "GOOGLE_SEARCH" - Resultados de búsqueda de Google
  • "GUESTBOOK" - Envíos de Guestbook
  • "MEDIUM_TAG_RSS" - Feeds RSS de Medium
  • "MOZILLA_ADDON_SEARCH" - Búsquedas de complementos de Mozilla
  • "REDDIT_SUBREDDIT_SEARCH" - Búsquedas en subreddits de Reddit
  • "TWITTER" - Monitoreo de Twitter
  • "TWITTER_POST_SEARCH" - Búsquedas de publicaciones de Twitter
  • "TWITTER_SEARCH" - Resultados de búsqueda de Twitter
  • "URLSCAN" - Resultados de URLScan.io
  • "YAHOO_SEARCH" - Resultados de búsqueda de Yahoo
  • "YANDEX_IMAGE_SEARCH" - Resultados de la búsqueda inversa de imágenes de Yandex para las imágenes de tu marca
  • "YOUTUBE_SEARCH" - Resultados de búsqueda de YouTube
2. Filtro de estado del asset ("assetStatus")
Valores de estado del asset disponibles:
  • "UNKNOWN" - Estado aún no determinado
  • "ALLOWED" - El asset es legítimo/está permitido
  • "BLOCKED" - El asset está bloqueado/es malicioso
3. Filtro de confianza ("confidence")
Valores de nivel de confianza disponibles:
  • "none" - No se alcanzó ningún umbral de confianza
  • "low" - Suspected threat de confianza baja
  • "medium" - Suspected threat de confianza media
  • "high" - Suspected threat de confianza alta
4. Filtro de estado de bloqueo ("blockStatus")
Selecciona las suspected threats cuyo asset ya se convirtió en una amenaza confirmada:
  • "blocked" - el asset está en la Blocklist (lista de bloqueo) (asset.status es "BLOCKED")
  • "pending" - se confirmó que el asset es malicioso, pero todavía no se aplica el bloqueo porque la protección no está activa para tu organización (asset.pendingStatus es "BLOCKED"). La app de ChainPatrol las etiqueta como Pending Blocked (bloqueo pendiente).
Pasa ambos valores para obtener todas las amenazas confirmadas, tal como las cuenta la app. El filtro assetStatus solo ve asset.status, así que assetStatus: ["BLOCKED"] deja fuera los bloqueos pendientes. 5. Filtro de eliminadas ("deleted")
Las suspected threats eliminadas se incluyen de forma predeterminada. Agrega { "property": "deleted", "operator": "notIn", "value": ["deleted"] } para dejarlas fuera, o usa "in" para devolver solo las eliminadas. 6. Filtro de tipo de asset ("assetType")
  • "URL" - URL de sitios web
  • "PAGE" - Páginas web
  • "ADDRESS" - Direcciones de blockchain
  • "TWITTER" - Perfiles/publicaciones de Twitter
  • "FACEBOOK" - Perfiles/páginas de Facebook
  • "YOUTUBE" - Canales/videos de YouTube
  • "REDDIT" - Publicaciones/subreddits de Reddit
  • "TELEGRAM" - Canales/grupos de Telegram
  • "DISCORD" - Servidores de Discord (obsoleto)
  • "DISCORD_USER" - Usuarios de Discord
  • "LINKEDIN" - Perfiles de LinkedIn
  • "INSTAGRAM" - Perfiles de Instagram
  • "THREADS" - Perfiles de Threads
  • "TIKTOK" - Perfiles de TikTok
  • "MEDIUM" - Artículos/perfiles de Medium
  • "EMAIL" - Direcciones de correo electrónico
  • "WHATSAPP" - Contactos de WhatsApp
  • "GOOGLE_APP_STORE" - Apps de Google Play Store
  • "APPLE_APP_STORE" - Apps de Apple App Store
  • "AMAZON_APP_STORE" - Apps de Amazon App Store
  • "MICROSOFT_APP_STORE" - Apps de Microsoft Store
  • "CHROME_WEB_STORE" - Extensiones de Chrome
  • "MOZILLA_ADDONS" - Complementos de Firefox
  • "OPERA_ADDONS" - Complementos de Opera
  • "PATREON" - Perfiles de Patreon
  • "OPENSEA" - Colecciones/perfiles de OpenSea
  • "FARCASTER" - Perfiles de Farcaster
  • "IPFS" - Hashes de IPFS
  • "GOOGLE_FORM" - Google Forms
  • "QUORA" - Perfiles/publicaciones de Quora
  • "GITHUB" - Repositorios/perfiles de GitHub
  • "TEACHABLE" - Cursos de Teachable
  • "SUBSTACK" - Publicaciones de Substack
  • "DEBANK" - Perfiles de DeBank
  • "TAWK_TO" - Widgets de chat de Tawk.to
  • "JOTFORM" - Formularios de JotForm
  • "PRIMAL" - Perfiles de Primal
  • "BLUESKY" - Perfiles de Bluesky
  • "SNAPCHAT" - Perfiles de Snapchat
  • "DESO" - Perfiles de DeSo

Esquema de la respuesta

Cuerpo de la respuesta

Objeto de resultado de detección

Cada elemento del arreglo detections es una suspected threat, con la siguiente estructura:

Objeto de asset

Ejemplo de respuesta completa

Conteos y umbrales de puntaje

Para contar las suspected threats sin tener que paginarlas, envía includeTotal: true. La respuesta incluye entonces total: cuántas suspected threats coinciden con tus filtros, tu búsqueda y tu rango de fechas en todas las páginas. Se cuenta antes de aplicar el cursor, así que cada página de un recorrido informa el mismo número. Implica una consulta de conteo adicional, así que pídelo en la primera página y no en todas. confidence se agrupa a partir de score según los umbrales propios de tu organización, así que "high" no equivale a un puntaje fijo. Para un umbral fijo, como “más del 80%”, usa minScore (y, si quieres, maxScore):
Un minScore mayor que maxScore se rechaza con un 400. Consulta Cómo evaluar las suspected threats para ver las preguntas que suele hacerse la gente cuando mira estos datos por primera vez, y la solicitud que responde cada una.

Paginación y sincronización incremental

Las suspected threats se devuelven de la más reciente a la más antigua. No hay una exportación en una sola llamada: una organización puede tener cientos de miles de suspected threats, muchas más de las que caben en una respuesta. En su lugar, recórrelas por páginas:
  • Establece limit en hasta 1000.
  • Pasa el nextCursor de cada respuesta como cursor.
  • Detente cuando una respuesta no tenga nextCursor.
Las respuestas tienen un tope de 4MB. Una página que lo supere falla con un error 413 en lugar de recortarse. Reintenta con un limit más pequeño. Una página de 1000 filas suele quedar muy por debajo de 1MB.

Obtener solo las suspected threats nuevas

Después de una sincronización completa inicial, usa startDate para que cada ejecución solo obtenga lo que se creó desde la anterior. Con 1,000 a 10,000 suspected threats nuevas por día, eso equivale a unas pocas páginas de 1000 filas.
  1. Registra la hora en que empieza la sincronización y envíala como endDate. Las suspected threats creadas mientras estás paginando quedan al frente del orden (de la más reciente a la más antigua), así que sin un endDate fijo se omitirían. En cambio, las toma la siguiente ejecución.
  2. Establece startDate en la hora de inicio de la ejecución anterior, menos unos minutos de superposición. Una suspected threat puede tardar unos segundos en ser visible después de su createdAt, y la superposición la captura.
  3. Pagina hasta que no haya nextCursor y elimina los duplicados por id. La superposición hace que algunas suspected threats aparezcan en dos ejecuciones.
Las suspected threats eliminadas se incluyen a menos que agregues { "property": "deleted", "operator": "notIn", "value": ["deleted"] } a filters. Para obtener solo los dominios falsos sospechosos, agrega { "property": "assetType", "operator": "in", "value": ["URL"] }.
Una sincronización con startDate solo devuelve las suspected threats creadas dentro del rango. Si una suspected threat se reporta o se elimina después de que la obtuviste, la siguiente ejecución incremental no la volverá a devolver. Ejecuta una sincronización completa periódica (por ejemplo, diaria) si necesitas esos cambios.

Control de acceso

La API aplica un control de acceso estricto según tu clave de API:
  1. Claves de API de organización:
    • Solo pueden acceder a las suspected threats de la organización a la que están asociadas
    • Deben coincidir exactamente con el parámetro slug
    • Ejemplo: una clave de API de “acme-org” solo puede consultar resultados de “acme-org”
  2. Claves de API de usuario:
    • Pueden acceder a las suspected threats de cualquier organización de la que el usuario sea miembro
    • Requieren que el usuario sea un miembro activo de la organización consultada
Si intentas consultar una organización sin los permisos adecuados, recibirás un error 403 Forbidden con el mensaje: “API key does not have access to this organization”

Implementación de ejemplo

Autorizaciones

X-API-KEY
string
header
requerido

Your API key. This is required by most endpoints to access our API programatically. Reach out to us at support@chainpatrol.io to get an API key for your use.

Cuerpo

application/json
slug
string
requerido

Organization slug

cursor
number

Pass the nextCursor from the previous response to fetch the next page. Omit it for the first page.

limit
number
predeterminado:50

Number of results per page, between 1 and 1000. Defaults to 50.

Rango requerido: 1 <= x <= 1000
filters
object[]

Filters to apply to the results

query
string
predeterminado:""

Search query for threat content

minScore
number

Only return suspected threats whose raw score is at least this value (inclusive, 0-1). Use this rather than the confidence filter when you need a fixed cut-off such as 0.8: confidence buckets depend on your organization's thresholds.

Rango requerido: 0 <= x <= 1
maxScore
number

Only return suspected threats whose raw score is at most this value (inclusive, 0-1). Must not be below minScore.

Rango requerido: 0 <= x <= 1
includeTotal
boolean
predeterminado:false

Also return total: how many suspected threats match the filters, search and date range across all pages. Costs an extra count query, so request it on the first page of a sweep rather than every page.

startDate
string

Only return suspected threats created at or after this time (inclusive). For incremental syncs, pass the time your previous sync started minus a few minutes of overlap, and de-duplicate by id.

endDate
string

Only return suspected threats created at or before this time (inclusive). Pin it to the time a sync starts so every page of that sync sees the same result set.

Respuesta

Successful response

detections
object[]
requerido
nextCursor
number
total
number

How many suspected threats match the filters, search and date range across all pages, regardless of cursor. Present only when includeTotal is true.