Este artículo será útil para aquellos que están familiarizados con las tecnologías Check Point de emulación de archivos (Emulación de Amenazas) y la limpieza proactiva de archivos (Extracción de Amenazas) y desean dar un paso hacia la automatización de estas tareas. Check Point ofrece , que funciona tanto en la nube como en dispositivos locales, y funcionalmente es idéntica a la verificación de archivos en flujos de tráfico web/smtp/ftp/smb/nfs.Este artículo es en parte una interpretación personal de un conjunto de artículos de la documentación oficial, pero se basa en mi experiencia de uso y ejemplos propios. También en el artículo encontrarás colecciones personales de Postman para trabajar con la API de Prevención de Amenazas.
Abreviaturas Principales
La API de Prevención de Amenazas trabaja con tres componentes principales, que se llaman en la API a través de los siguientes valores de texto:
av — componente Anti-Virus, encargado del análisis de firmas de amenazas conocidas.
te — componente de Emulación de Amenazas, encargado de verificar archivos en una caja de arena, y emitir un veredicto malicioso (malicious)/limpio (benign) después de la emulación.
extraction — componente de Extracción de Amenazas, que se encarga de la rápida conversión de documentos de oficina a un formato seguro (del que se elimina todo el contenido potencialmente dañino), con el fin de entregarlos rápidamente a usuarios/sistemas.
Estructura de la API y Principales Limitaciones
La API de Prevención de Amenazas utiliza solo 4 solicitudes — upload, query, download y quota.En la cabecera de las cuatro solicitudes se debe enviar la clave de la API, utilizando el parámetro Authorization.A primera vista, la estructura puede parecer mucho más simple que en , pero el número de campos en las solicitudes upload y query y la estructura de estas solicitudes son bastante complejos. Se pueden comparar funcionalmente con los perfiles de Prevención de Amenazas en la política de seguridad del gateway/sandbox.
En este momento, se ha lanzado una única versión de la API de Prevención de Amenazas — 1.0, en la URL para las llamadas a la API se debe especificar v1 en la parte donde se requiere especificar la versión. A diferencia de la API de Gestión, es obligatorio indicar la versión de la API en la dirección URL, de lo contrario la solicitud no se ejecutará.
El componente Anti-Virus al ser llamado sin otros componentes (te, extraction) actualmente solo admite solicitudes query con sumas de verificación md5. La Emulación de Amenazas y la Extracción de Amenazas también admiten sumas de verificación sha1 y sha256.
¡Es muy importante no cometer errores en las solicitudes! La solicitud puede ejecutarse sin errores, pero no de manera completa. Avancemos un poco para ver qué puede suceder en caso de errores o erratas en las solicitudes.
Solicitud con un error tipográfico en la palabra reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}En la respuesta no habrá errores, pero tampoco habrá información sobre los informes.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La solicitud ha sido respondida completamente."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La solicitud ha sido respondida completamente."
}
}
}
]
}Aquí está la solicitud sin tipografía en la clave reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Recibimos una respuesta que ya contiene los id para descargar los informes.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La solicitud ha sido respondida completamente."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
"pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
"xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La solicitud ha sido respondida completamente."
}
}
}
]
}Si se envía una clave API incorrecta o caducada, obtendremos un error 403 en respuesta.
SandBlast API: en la nube y en dispositivos locales.
Las solicitudes de API pueden enviarse a dispositivos Check Point que tienen habilitado el componente (blade) Threat Emulation. Para las solicitudes, se debe usar el ip/url del dispositivo y el puerto 18194 (por ejemplo — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию desactivada y la clave de autorización en los encabezados de las solicitudes no es necesaria en absoluto.
Las solicitudes API a la nube de CheckPoint deben enviarse a la dirección te.checkpoint.com (por ejemplo — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
En los dispositivos locales, Threat Extraction aún no está soportado en el estándar y se debe utilizar (hablaremos de ello con más detalle al final del artículo).
Los dispositivos locales no soportan la solicitud quota.
Por lo demás, no hay diferencias entre las solicitudes a dispositivos locales y a la nube.
La llamada a Upload API
El método utilizado es — POST
La dirección para la llamada es — https://<service_address>/tecloud/api/v1/file/upload
La solicitud consta de dos partes (form-data): un archivo destinado a emulación/limpieza y el cuerpo de la solicitud con el texto.
La solicitud de texto no puede estar vacía, pero puede no contener ninguna configuración. Para que la solicitud sea exitosa, se debe enviar al menos el siguiente texto en la solicitud:
Mínimo requerido para la solicitud de carga
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Encabezados:
Authorization: <api_key>
Cuerpo
{
«request»: {
}
}
Archivo
Archivo
En tal caso, el archivo para procesamiento se enviará de acuerdo con los parámetros predeterminados: componente — te, imágenes de SO — Win XP y Win 7, sin generación de informe.
Comentarios sobre los campos principales de la solicitud de texto:
file_name y file_type pueden dejarse vacíos o no enviarse en absoluto, ya que no son información muy útil al cargar un archivo. En la respuesta API, estos campos se llenarán automáticamente en base al nombre del archivo que se carga, y la información en caché aún tendrá que buscarse por las sumas de hash md5/sha1/sha256.
Ejemplo de solicitud con file_name y file_type vacíos
{
"request": {
"file_name": "",
"file_type": "",
}
}features — una lista que indica la funcionalidad necesaria para el procesamiento en la sandbox — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Si no se envía este parámetro, solo se usará el componente predeterminado — te (Threat Emulation).
Para habilitar la verificación en los tres componentes disponibles, es necesario indicar estos componentes en la solicitud API.
Ejemplo de solicitud con verificación en av, te y extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Claves en la sección te
images — una lista que debe incluir diccionarios con id y número de revisión de los sistemas operativos en los que se realizará la verificación. ID y números de revisión son iguales para todos los dispositivos locales y la nube.
Lista de sistemas operativos y revisiones
Available OS Image ID
Revision
Image OS and Application
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Oficina: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 y ActiveX 10.0
Java Runtime: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 — 32bit
Oficina: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Complemento& ActiveX)
Java Runtime: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 — 32bit
Oficina: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Complemento & ActiveX)
Java Runtime: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 — 32bit
Oficina: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Complemento & ActiveX)
Java Runtime: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 — 64bit
Oficina: 2013 (32bit)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Complemento & ActiveX)
Java Runtime: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 — 64bit
Oficina: 2013 (64bit)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Complemento & ActiveX)
Java Runtime: 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
Microsoft Windows: 10
Oficina: Professional Plus 2016 en-us
Adobe Acrobat Reader: DC 2015 MUI
Flash Player: 20 (Complemento & ActiveX)
Java Runtime: 1.7.0u9
Si la clave images no se indica en absoluto, la emulación se realizará en las imágenes recomendadas por Check Point (en este momento son Win XP y Win 7). Estas imágenes se recomiendan en función del mejor equilibrio de rendimiento y tasa de detección.
informes — lista de informes que solicitamos en caso de que el archivo resulte ser malicioso. Las siguientes opciones están disponibles:
resumen — archivo .tar.gz que contiene el informe de emulación sobre todos los images solicitados (tanto como página html como componentes como un video del sistema operativo emulador, un volcado de tráfico de red, un informe en json, así como la muestra misma en un archivo protegido por contraseña). En la respuesta buscamos la clave — summary_report para la posterior descarga del informe.
pdf — documento de emulación en una imagen, que muchos están acostumbrados a recibir a través de Smart Console. En la respuesta buscamos la clave — pdf_report para la posterior descarga del informe.
xml — documento de emulación en una imagen, conveniente para el posterior parseo de parámetros en el informe. En la respuesta buscamos la clave — xml_report para la posterior descarga del informe.
tar — archivo .tar.gz que contiene el informe de emulación en una los images solicitados (tanto como página html como componentes como un video del sistema operativo emulador, un volcado de tráfico de red, un informe en json, así como la muestra misma en un archivo protegido por contraseña). En la respuesta buscamos la clave — full_report para la posterior descarga del informe.
Qué hay dentro del informe summary
Las claves full_report, pdf_report, xml_report están en el diccionario para cada sistema operativo
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido completamente respondida."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicioso",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicioso",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "encontrado",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicioso",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido completamente respondida."
}
}
}
]
}Y aquí la clave summary_report — hay una para la emulación en general
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido respondida por completo."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicioso",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicioso",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "encontrado",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicioso",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido respondida por completo."
}
}
}
]
}Se pueden solicitar informes tar y xml y pdf al mismo tiempo, se pueden solicitar resumen y tar y xml. No se puede solicitar al mismo tiempo un informe de resumen y pdf.
Claves en la sección de extracción
Solo se utilizan dos claves para la extracción de amenazas:
método — pdf (conversión a pdf, se usa por defecto) o clean (eliminación de contenido activo).
extracted_parts_codes — lista de códigos para eliminar contenido activo, aplicable solo para el método clean
Códigos para eliminar contenido de archivos
Código
Descripción
1025
Objetos Vinculados
1026
Macros y Código
1034
Hipervínculos Sensibles
1137
Acciones PDF GoToR
1139
Acciones de Lanzamiento PDF
1141
Acciones URI PDF
1142
Acciones de Sonido PDF
1143
Acciones de Película PDF
1150
Acciones JavaScript PDF
1151
Acciones de Envío de Formulario PDF
1018
Consultas de Base de Datos
1019
Objetos Embebidos
1021
Datos de Guardado Rápido
1017
Propiedades Personalizadas
1036
Propiedades Estatísticas
1037
Propiedades Resumidas
Para descargar una copia limpia, también se requiere realizar una solicitud query (de la que hablaremos más adelante) en unos segundos, indicando el hash del archivo y el componente de extracción en el texto de la solicitud. Se podrá recuperar el archivo limpio usando el id de la respuesta a la solicitud query — extracted_file_download_id. Una vez más, adelantando un poco, doy ejemplos de la solicitud y respuesta query para encontrar el id para descargar el documento limpio.
Solicitud query para buscar la clave extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Respuesta a la solicitud query (encuentre la clave extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido completamente respondida."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extracción"
],
"extraction": {
"method": "pdf",
"extract_result": "CP_EXTRACT_RESULT_SUCCESS",
"extracted_file_download_id": "b5f2b34e-3603-4627-9e0e-54665a531ab2",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"time": "0.013",
"extract_content": "Macros y Código",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Contenido potencialmente malicioso extraído",
"protection_type": "Conversión a PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Se encontró contenido activo - El archivo XLS fue convertido a PDF",
"scrub_method": "Convertir a PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros y Código"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido completamente respondida."
}
}
}
]
}Información General
En una llamada a la API se puede enviar solo un archivo para su verificación.
El componente av no requiere una sección adicional con claves, es suficiente incluirlo en el diccionario features.
Llamada a la API de Consulta
El método utilizado es — POST
La dirección para la llamada es — https://<service_address>/tecloud/api/v1/file/query
Antes de enviar un archivo para carga (solicitud de carga), es recomendable realizar una verificación de caché de sandbox (solicitud de consulta) para optimizar la carga en el servidor API, ya que es posible que ya haya información y un veredicto sobre el archivo a cargar en el servidor API. La llamada consiste solo en la parte de texto. La parte obligatoria de la solicitud es el hash sha1/sha256/md5 del archivo. Este, por cierto, se puede obtener en la respuesta a la solicitud de carga.
Mínimo requerido para la solicitud de consulta
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Encabezados:
Authorization: <api_key>
Cuerpo
{
«request»: {
"sha256": <sha256 hash sum>
}
}
Ejemplo de respuesta a la solicitud de carga, donde se ven los hash sha1/md5/sha256
{
"response": {
"status": {
"code": 1002,
"label": "CARGA_EXITOSA",
"message": "El archivo se cargó correctamente."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "desconocido"
},
"status": "no_encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "CARGA_EXITOSA",
"message": "El archivo se cargó correctamente."
}
}
}
}La consulta query, además del hash, idealmente debería ser la misma que la consulta upload (o que se planea ser), o incluso "ya" (contener en la consulta query menos campos que en la consulta upload). En el caso de que la consulta query contenga más campos que la consulta upload, recibirás en la respuesta no toda la información requerida.
Aquí hay un ejemplo de la respuesta a la consulta query, donde no se encontraron todos los datos requeridos.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "La solicitud no puede ser respondida completamente en este momento."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te",
"extraction"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicioso",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicioso",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La solicitud ha sido respondida completamente."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "No se pudo encontrar el archivo solicitado. Por favor, súbelo."
}
}
}
]
}Atención a los campos code y label. Estos campos aparecen tres veces en los diccionarios de estado. Al principio vemos la clave global "code": 1006 y "label": "PARTIALLY_FOUND". Luego, estas claves aparecen en cada uno de los componentes individuales que hemos solicitado: te y extraction. Y si para te está claro que se encontraron datos, para extraction la información está ausente.
Esta es la consulta query que se usó para el ejemplo anterior.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Si envías la consulta query sin el componente extraction.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Entonces en la respuesta habrá información completa ("code": 1001, "label": "FOUND")
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido respondida completamente."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicioso",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicioso",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido respondida completamente."
}
}
}
]
}Si no hay información en la caché, la respuesta será "label": "NO_ENCONTRADO"
{
"response": [
{
"status": {
"code": 1004,
"label": "NO_ENCONTRADO",
"message": "No se pudo encontrar el archivo solicitado. Por favor, cárgalo."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "desconocido"
},
"status": "no_encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NO_ENCONTRADO",
"message": "No se pudo encontrar el archivo solicitado. Por favor, cárgalo."
}
}
}
]
}En una llamada a la API se pueden enviar varias sumas de verificación para su revisión. En la respuesta se devolverán los datos en el mismo orden en que fueron enviados en la solicitud.
Ejemplo de solicitud query con múltiples sumas sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Respuesta a la solicitud query con múltiples sumas sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido respondida completamente."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicioso"
},
"status": "encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicioso",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "La solicitud ha sido respondida completamente."
}
}
},
{
"status": {
"code": 1004,
"label": "NO_ENCONTRADO",
"message": "No se pudo encontrar el archivo solicitado. Por favor, súbalo."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "desconocido"
},
"status": "no_encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NO_ENCONTRADO",
"message": "No se pudo encontrar el archivo solicitado. Por favor, súbalo."
}
}
}
]
}Realizar una solicitud de múltiples hash en la consulta también beneficiará el rendimiento del servidor API.
Llamada a la API de descarga
El método utilizado es — POST (según la documentación), GET también funciona (y puede parecer más lógico)
La dirección para la llamada es — https://<service_address>/tecloud/api/v1/file/download?id=<id>
Se requiere pasar la clave API en el encabezado, el cuerpo de la solicitud debe estar vacío, el id para la descarga se pasa en la URL.
En respuesta a la solicitud de consulta, si la emulación se ha completado y se han solicitado informes durante la descarga del archivo, se mostrarán los id para la descarga de informes. En caso de que se solicite una copia limpia, se debe buscar el id para la descarga del documento limpiado.
En resumen, las claves en la respuesta a la solicitud de consulta que contienen el valor id para la descarga pueden ser:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Por supuesto, para que estos claves sean recibidas en la respuesta a la solicitud de consulta, deben ser especificadas en la solicitud (para informes) o no olvidar hacer la solicitud a la función de extracción (para documentos limpiados)
Llamada a la API de cuota
El método utilizado es — POST
La dirección para la llamada es — https://<service_address>/tecloud/api/v1/file/quota
Para verificar la cuota restante en la nube se utiliza la solicitud quota. El cuerpo de la solicitud está vacío.
Ejemplo de respuesta a la solicitud quota
{
"response": [
{
"remain_quota_hour": 1250,
"remain_quota_month": 10000000,
"assigned_quota_hour": 1250,
"assigned_quota_month": 10000000,
"hourly_quota_next_reset": "1599141600",
"monthly_quota_next_reset": "1601510400",
"quota_id": "TEST",
"cloud_monthly_quota_period_start": "1421712300",
"cloud_monthly_quota_usage_for_this_gw": 0,
"cloud_hourly_quota_usage_for_this_gw": 0,
"cloud_monthly_quota_usage_for_quota_id": 0,
"cloud_hourly_quota_usage_for_quota_id": 0,
"monthly_exceeded_quota": 0,
"hourly_exceeded_quota": 0,
"cloud_quota_max_allow_to_exceed_percentage": 1000,
"pod_time_gmt": "1599138715",
"quota_expiration": "0",
"action": "ALLOW"
}
]
}Threat Prevention API for Security Gateway
Esta API fue desarrollada antes que la API de Prevención de Amenazas y está destinada únicamente a dispositivos locales. En este momento, solo puede ser útil si necesitas la API de Extracción de Amenazas. Para la Emulación de Amenazas, es mejor utilizar la API de Prevención de Amenazas convencional. Para habilitar API de TP para SG y configurar la clave de la API, se requieren las acciones de . Recomiendo prestar atención al paso 6b y verificar la disponibilidad de la página https:///UserCheck/TPAPI porque si el resultado es negativo, la configuración posterior no tiene sentido. Todas las llamadas a la API se enviarán a esta URL. El tipo de llamada (upload/query) se regula en la clave del cuerpo de la llamada — request_name. También son obligatorias las claves — api_key (es necesario recordarla durante la configuración) y protocol_version (la versión actual es 1.1). La documentación oficial para esta API se puede encontrar en . Entre las ventajas relativas se incluye la posibilidad de enviar varios archivos para emulación durante su carga, ya que los archivos se envían como una cadena de texto en base64. Para codificar/decodificar archivos en/de base64, puedes utilizar un convertidor en línea en Postman, por ejemplo — . En la práctica, al escribir código, se deben utilizar los métodos integrados de encode y decode.
Ahora profundicemos en las funciones te y extraction de esta API.
Para el componente te se prevé un diccionario te_options en las solicitudes upload/query, y las claves en esta solicitud coinciden completamente con las claves te en .
Ejemplo de solicitud para emular un archivo en Win10 con informes
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "",
"te_options": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": ["summary", "xml"]
}
}
]
}Para el componente extraction se prevé un diccionario scrub_options. En esta solicitud se especifica el método de limpieza: conversión a PDF, limpieza de contenido activo o elegir el modo según el perfil de Prevención de Amenazas (se indica el nombre del perfil). La característica distintiva de la respuesta a la solicitud de API con extracción para el archivo es que recibes una copia limpia en respuesta a esta solicitud en forma de una cadena en base64 (no necesitas realizar una consulta query y buscar el id para cargar el documento)
Ejemplo de solicitud para limpiar un archivo
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Respuesta a la solicitud
{
"response": [{
"protocol_version": "1.1",
"src_ip": "",
"scrub": {
"file_enc_data": "",
"input_real_extension": "js",
"message": "OK",
"orig_file_url": "",
"output_file_name": "hi.cleaned.pdf",
"protection_name": "Extraer contenido potencialmente malicioso",
"protection_type": "Conversión a PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "El archivo TXT fue convertido a PDF",
"scrub_method": "Convertir a PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} A pesar de que se requieren menos solicitudes de API para obtener una copia limpia, considero que esta opción es menos preferible y conveniente en comparación con la solicitud form-data utilizada en .
Colecciones de Postman
He creado colecciones en Postman tanto para la API de Prevención de Amenazas como para la API de Prevención de Amenazas para Gateway de Seguridad, donde se presentan las solicitudes de API más comunes. Para que el ip/url del servidor API y la clave se inserten automáticamente en las solicitudes, y el hash SHA256 después de cargar el archivo también se recuerde, dentro de las colecciones se han creado tres variables (puedes encontrarlas al ir a la configuración de la colección Edit -> Variables): te_api (requerido completar), api_key (requerido completar, excepto en el caso de usar la API de TP con dispositivos locales), sha256 (dejar vacío, no se utiliza en la API de TP para SG).
Ejemplos de uso
En la comunidad se presentan scripts escritos en Python que verifican archivos de la carpeta deseada tanto a través de , como . A través de la interacción con la API de Prevención de Amenazas, tus capacidades para verificar archivos se amplían considerablemente, ya que ahora puedes verificar archivos en varias plataformas simultáneamente (resulta interesante la verificación en , y luego en el entorno aislado de Check Point), y los archivos se obtienen no solo del tráfico de red, sino también de cualquier disco en red y, por ejemplo, de sistemas CRM.
Fuente: habr.com
