Listar suspected threats
List suspected threats for an organization using API key authentication, newest first. A suspected threat is an unconfirmed result of automated threat detection; use the blockStatus filter to find the ones confirmed as threats. Returns human-readable confidence levels (none, low, medium, high) and report status. Supports filtering by source, confidence level, raw score range, asset status, asset type and creation time, plus search. Pages hold up to 1000 results: pass nextCursor back as cursor until it is absent, set includeTotal to get the number of matching suspected threats without paging, and use startDate to fetch only suspected threats created since your last sync.
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 filtroblockStatus 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 encabezadoX-API-KEY:
Solicitud de ejemplo
Esquema de la solicitud
Cuerpo de la solicitud
Esquema del filtro
Cada objeto de filtro debe tener la siguiente estructura:Propiedades del filtro
1. Filtro de fuente ("source")
Valores de fuente disponibles
Valores de fuente disponibles
"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
"assetStatus")
"UNKNOWN"- Estado aún no determinado"ALLOWED"- El asset es legítimo/está permitido"BLOCKED"- El asset está bloqueado/es malicioso
"confidence")
"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
"blockStatus")
"blocked"- el asset está en la Blocklist (lista de bloqueo) (asset.statuses"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.pendingStatuses"BLOCKED"). La app de ChainPatrol las etiqueta como Pending Blocked (bloqueo pendiente).
assetStatus solo ve asset.status, así que assetStatus: ["BLOCKED"]
deja fuera los bloqueos pendientes.
5. Filtro de eliminadas ("deleted")
{ "property": "deleted", "operator": "notIn", "value": ["deleted"] } para dejarlas
fuera, o usa "in" para devolver solo las eliminadas.
6. Filtro de tipo de asset ("assetType")
Valores de tipo de asset disponibles
Valores de tipo de asset disponibles
"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 arreglodetections 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íaincludeTotal: 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):
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
limiten hasta 1000. - Pasa el
nextCursorde cada respuesta comocursor. - Detente cuando una respuesta no tenga
nextCursor.
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, usastartDate 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.
- 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 unendDatefijo se omitirían. En cambio, las toma la siguiente ejecución. - Establece
startDateen 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 sucreatedAt, y la superposición la captura. - Pagina hasta que no haya
nextCursory elimina los duplicados porid. La superposición hace que algunas suspected threats aparezcan en dos ejecuciones.
{ "property": "deleted", "operator": "notIn", "value": ["deleted"] } a
filters. Para obtener solo los dominios falsos sospechosos, agrega
{ "property": "assetType", "operator": "in", "value": ["URL"] }.
Control de acceso
La API aplica un control de acceso estricto según tu clave de API:-
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”
-
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
Implementación de ejemplo
Autorizaciones
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.