Este artigo será útil para aqueles que estão familiarizados com tecnologias Check Point de emulação de arquivos (Emulação de Ameaças) e limpeza proativa de arquivos (Threat Extraction) e desejam dar um passo em direção à automação dessas tarefas. A Check Point possui , que funciona tanto na nuvem quanto em dispositivos locais, e funcionalmente é idêntica à verificação de arquivos nos fluxos de tráfego web/smtp/ftp/smb/nfs. Este artigo é em parte uma interpretação autoral de um conjunto de artigos da documentação oficial, mas baseado na minha experiência de uso e em exemplos próprios. Também neste artigo você encontrará coleções autorais do Postman para trabalhar com a Threat Prevention API.
Principais abreviações
A Threat Prevention API opera com três componentes principais, que são chamados no API através dos seguintes valores de texto:
av — componente Anti-Virus, responsável pela análise de assinatura de ameaças conhecidas.
te — componente Threat Emulation, responsável pela verificação de arquivos na sandbox, e emissão de um veredicto malicioso (malicious)/limpo (benign) após a emulação.
extraction — componente Threat Extraction, que é responsável pela rápida conversão de documentos de escritório em uma forma segura (na qual todo conteúdo potencialmente malicioso é removido), para sua rápida entrega aos usuários/sistemas.
Estrutura da API e principais limitações
A Threat Prevention API utiliza apenas 4 requisições — upload, query, download e quota. No cabeçalho de todas as quatro requisições, deve-se passar a chave da API, utilizando o parâmetro Authorization. À primeira vista, a estrutura pode parecer muito mais simples do que no , mas a quantidade de campos nas requisições upload e query e a estrutura dessas requisições são bastante complexas. Elas podem ser funcionalmente comparadas aos perfis de Threat Prevention na política de segurança do gateway/sandbox.
Atualmente, há uma única versão da Threat Prevention API — 1.0, no URL para chamadas da API deve-se especificar v1 na parte em que é necessário indicar a versão. Ao contrário da Management API, indicar a versão da API no endereço URL é obrigatório, senão a requisição não será executada.
O componente Anti-Virus, quando chamado sem outros componentes (te, extraction), atualmente suporta apenas requisições query com somas de hash md5. Threat Emulation e Threat Extraction também suportam somas de hash sha1 e sha256.
É muito importante não cometer erros nas requisições! A solicitação pode ser executada sem erro, mas não completamente. Antecipando um pouco, vamos considerar o que pode acontecer em caso de erros/tipografias nas solicitações.
Solicitação com erro na palavra reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Na resposta não haverá erros, mas também nenhuma informação sobre os relatórios.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "A solicitação foi totalmente respondida."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"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": "FOUND",
"message": "A solicitação foi totalmente respondida."
}
}
}
]
}Aqui está a solicitação sem erro na chave reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Recebemos uma resposta que já contém IDs para o download dos relatórios.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "A solicitação foi totalmente respondida."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicioso",
"full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
"pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
"xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
},
"status": "encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicioso",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "A solicitação foi totalmente respondida."
}
}
}
]
}Se um chave API incorreta/vencida for enviada, teremos um erro 403 na resposta.
SandBlast API: na nuvem e em dispositivos locais.
As solicitações da API podem ser enviadas para dispositivos Check Point que têm o componente (blade) de Emulação de Ameaças habilitado. O endereço para as solicitações deve usar o ip/url do dispositivo e a porta 18194 (por exemplo — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию desligada e a chave Authorization nos cabeçalhos das solicitações pode não ser enviada de forma alguma.
As solicitações da API para a nuvem CheckPoint devem ser enviadas para o endereço te.checkpoint.com (por exemplo — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Nos dispositivos locais, a Extração de Ameaças ainda não é suportada de forma padrão e deve ser utilizado (sobre isso falaremos com mais detalhes no final do artigo).
Dispositivos locais não suportam a solicitação quota.
Fora isso, não há diferenças entre as solicitações para dispositivos locais e para a nuvem.
Chamada da API de Upload
O método utilizado é — POST
O endereço para a chamada é — https://<service_address>/tecloud/api/v1/file/upload
A solicitação consiste em duas partes (form-data): um arquivo destinado à emulação/limpeza e o corpo da solicitação com o texto.
A solicitação de texto não pode estar vazia, mas pode não conter nenhuma configuração. Para que a solicitação seja bem-sucedida, é necessário enviar pelo menos o seguinte texto na solicitação:
O mínimo necessário para a solicitação de upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Cabeçalhos:
Authorization: <api_key>
Corpo
{
"request": {
}
}
Novo projeto
Novo projeto
Nesse caso, o arquivo para processamento será enviado de acordo com os parâmetros padrão: componente — te, imagens do SO — Win XP e Win 7, sem geração de relatório.
Comentários sobre os principais campos na solicitação de texto:
file_name e file_type podem ser deixados em branco ou não enviados, pois não são informações muito úteis ao carregar um arquivo. Na resposta da API, esses campos serão preenchidos automaticamente com base no nome do arquivo carregado, e as informações no cache ainda deverão ser procuradas pelas somas de hash md5/sha1/sha256.
Exemplo de solicitação com file_name e file_type vazios
{
"request": {
"file_name": "",
"file_type": "",
}
}features — uma lista que indica a funcionalidade necessária ao processar no sandbox — av (Anti-Vírus), te (Emulação de Ameaças), extraction (Extração de Ameaças). Se esse parâmetro não for enviado, apenas o componente padrão — te (Emulação de Ameaças) — será ativado.
Para habilitar a verificação nos três componentes disponíveis, é necessário especificar esses componentes na solicitação da API.
Exemplo de solicitação com verificação em av, te e extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Chaves na seção te
images — uma lista, dentro da qual devem ser especificados dicionários com id e número de revisão dos sistemas operacionais nos quais a verificação será realizada. Os IDs e números de revisão são os mesmos para todos os dispositivos locais e para a nuvem.
Lista de sistemas operacionais e revisões
Available OS Image ID
Revision
Image OS and Application
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 e ActiveX 10.0
Java Runtime: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 — 32bits
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Plugin& ActiveX)
Java Runtime: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 — 32bits
Office: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Plugin & ActiveX)
Java Runtime: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 — 32bits
Office: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 — 64bits
Office: 2013 (32bits)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 — 64bits
Office: 2013 (64bits)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
Microsoft Windows: 10
Office: Professional Plus 2016 en-us
Adobe Acrobat Reader: DC 2015 MUI
Flash Player: 20 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
Se a chave images não for especificada, a emulação será realizada em imagens recomendadas pela Check Point (atualmente, estas são Win XP e Win 7). Essas imagens são recomendadas com base no melhor equilíbrio entre desempenho e taxa de captura.
relatórios — lista de relatórios que solicitamos caso o arquivo se revele malicioso. As seguintes opções estão disponíveis:
sumário — arquivo .tar.gz que contém o relatório da emulação sobre todos imagens solicitadas (tanto na forma de página html quanto componentes como vídeo do OS do emulador, dump do tráfego de rede, relatório em json e a própria amostra em um arquivo protegido por senha). Na resposta, buscamos a chave — summary_report para o download posterior do relatório.
pdf — documento da emulação em um imagem, que muitos costumam receber através do Smart Console. Na resposta, buscamos a chave — pdf_report para o download posterior do relatório.
xml — documento da emulação em um imagem, conveniente para o posterior parsing dos parâmetros no relatório. Na resposta, buscamos a chave — xml_report para o download posterior do relatório.
tar — arquivo .tar.gz que contém o relatório da emulação em um imagens solicitadas (tanto na forma de página html quanto componentes como vídeo do OS do emulador, dump do tráfego de rede, relatório em json e a própria amostra em um arquivo protegido por senha). Na resposta, buscamos a chave — full_report para o download posterior do relatório.
O que há dentro do relatório sumário
As chaves full_report, pdf_report, xml_report estão no dicionário para cada SO
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "A solicitação foi totalmente atendida."
},
"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": "FOUND",
"message": "A solicitação foi totalmente atendida."
}
}
}
]
}A chave summary_report — é única para a emulação como um todo
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "A solicitação foi totalmente respondida."
},
"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": "A solicitação foi totalmente respondida."
}
}
}
]
}É possível solicitar relatórios em tar, xml e pdf ao mesmo tempo, e também um resumo em tar e xml. Não é possível solicitar um relatório resumo e pdf ao mesmo tempo.
Chaves na seção de extração
Para extração de ameaças, são usados apenas dois chaves:
método — pdf (conversão para pdf, usado por padrão) ou clean (limpeza de conteúdo ativo).
extracted_parts_codes — lista de códigos para remoção de conteúdo ativo, aplicável apenas para o método clean
Códigos para remoção de conteúdo de arquivos
Código
Descrição
1025
Objetos Vinculados
1026
Macros e Código
1034
Hipertlinks Sensíveis
1137
Ações PDF GoToR
1139
Ações de Lançamento PDF
1141
Ações URI PDF
1142
Ações de Som PDF
1143
Ações de Filme PDF
1150
Ações de JavaScript PDF
1151
Ações de Envio de Formulário PDF
1018
Consultas de Banco de Dados
1019
Objetos Incorporados
1021
Dados de Salvamento Rápido
1017
Propriedades Personalizadas
1036
Propriedades Estatísticas
1037
Propriedades de Resumo
Para baixar uma cópia limpa, será necessário fazer também uma solicitação de query (que será discutida a seguir) alguns segundos depois, especificando o hash do arquivo e o componente de extração no corpo da solicitação. O arquivo limpo pode ser obtido usando o id da resposta à solicitação de query — extracted_file_download_id. Mais uma vez, adiantando, apresento exemplos de solicitação e resposta de query para encontrar o id para o download do documento limpo.
Solicitação de query para localizar a chave extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Resposta à solicitação de query (encontre a chave extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "A solicitação foi totalmente respondida."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extração"
],
"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 e Código",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Conteúdo potencialmente malicioso extraído",
"protection_type": "Conversão para PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Conteúdo ativo foi encontrado - arquivo XLS foi convertido para PDF",
"scrub_method": "Converter para PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros e Código"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "A solicitação foi totalmente respondida."
}
}
}
]
}Visão geral
Em uma chamada da API, você pode enviar apenas um arquivo para verificação.
O componente av não requer uma seção adicional com chaves, basta especificá-lo no dicionário. features.
Chamada da API de Consulta
O método utilizado é — POST
O endereço para a chamada é — https://<service_address>/tecloud/api/v1/file/query
Antes de enviar o arquivo para upload (solicitação de upload), é aconselhável realizar a verificação do cache do sandbox (solicitação de consulta) para otimizar a carga no servidor API, pois pode já haver informações e um veredicto sobre o arquivo a ser carregado. A chamada consiste apenas na parte textual. A parte obrigatória da solicitação é o hash sha1/sha256/md5 do arquivo. Isso pode ser obtido na resposta da solicitação de upload.
Mínimo necessário para a solicitação de consulta
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Cabeçalhos:
Authorization: <api_key>
Corpo
{
"request": {
"sha256": <sha256 hash sum>
}
}
Exemplo de resposta à solicitação de upload, onde são visíveis as somas de hash sha1/md5/sha256.
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "O arquivo foi enviado com sucesso."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "desconhecido"
},
"status": "não_encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "O arquivo foi enviado com sucesso."
}
}
}
}A consulta query, além do hash, idealmente deve ser a mesma que foi (ou se planeja ser) a consulta upload, ou até mesmo "já" (contendo na consulta query menos campos do que na consulta upload). No caso em que a consulta query contém mais campos do que a consulta upload, você não receberá todas as informações necessárias.
Aqui está um exemplo de resposta para a consulta query, onde não foram encontrados todos os dados necessários.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARCIALMENTE_ENCONTRADO",
"message": "A solicitação não pode ser totalmente respondida no 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": "ENCONTRADO",
"message": "A solicitação foi totalmente respondida."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NÃO_ENCONTRADO",
"message": "Não foi possível encontrar o arquivo solicitado. Por favor, faça o upload."
}
}
}
]
}Atente-se aos campos code e label. Esses campos aparecem três vezes nos dicionários de status. No início, vemos a chave global "code": 1006 e "label": "PARCIALMENTE_ENCONTRADO". Em seguida, essas chaves aparecem em cada componente individual que solicitamos — te e extraction. E se para te está claro que os dados foram encontrados, para extraction as informações estão ausentes.
A consulta query para o exemplo acima foi assim
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Se a consulta query for enviada sem o componente extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Então, na resposta haverá informações completas ("code": 1001, "label": "ENCONTRADO")
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "A solicitação foi totalmente respondida."
},
"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": "A solicitação foi totalmente respondida."
}
}
}
]
}Se não houver absolutamente nenhuma informação no cache, a resposta terá "label": "NÃO_ENCONTRADO"
{
"response": [
{
"status": {
"code": 1004,
"label": "NÃO_ENCONTRADO",
"message": "Não foi possível encontrar o arquivo solicitado. Por favor, faça o upload."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "desconhecido"
},
"status": "não_encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NÃO_ENCONTRADO",
"message": "Não foi possível encontrar o arquivo solicitado. Por favor, faça o upload."
}
}
}
]
}Em uma chamada de API, é possível enviar várias somas de hash para verificação ao mesmo tempo. A resposta retornará os dados na mesma ordem em que foram enviados na solicitação.
Exemplo de solicitação query com várias somas sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Resposta à solicitação query com várias somas sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "ENCONTRADO",
"message": "A solicitação foi totalmente respondida."
},
"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": "A solicitação foi totalmente respondida."
}
}
},
{
"status": {
"code": 1004,
"label": "NÃO_ENCONTRADO",
"message": "Não foi possível encontrar o arquivo solicitado. Por favor, faça o upload."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "desconhecido"
},
"status": "não_encontrado",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NÃO_ENCONTRADO",
"message": "Não foi possível encontrar o arquivo solicitado. Por favor, faça o upload."
}
}
}
]
}Fazer uma solicitação de vários hash na consulta também beneficiará o desempenho do servidor API.
Chamada da API de Download
O método utilizado é — POST (de acordo com a documentação), GET também funciona (e pode parecer mais lógico)
O endereço para a chamada é — https://<service_address>/tecloud/api/v1/file/download?id=<id>
O cabeçalho deve conter a chave da API, e o corpo da solicitação deve estar vazio, o id para download é passado na URL.
Na resposta à consulta, caso a emulação tenha sido concluída e relatórios tenham sido solicitados durante o download do arquivo, os ids para download dos relatórios estarão visíveis. Se uma cópia limpa for solicitada, deve-se procurar pelos ids para o download do documento limpo.
Portanto, as chaves na resposta à consulta que contêm o valor id para download podem ser:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Certamente, para que essas chaves sejam obtidas na resposta da consulta, elas precisam ser especificadas na solicitação (para relatórios) ou não se esquecer de fazer a solicitação pela função de extração (para documentos limpos)
Chamada da API de Quota
O método utilizado é — POST
O endereço para a chamada é — https://<service_address>/tecloud/api/v1/file/quota
Para verificar a cota restante na nuvem, usa-se a solicitação quota. O corpo da solicitação está vazio.
Exemplo de resposta à solicitação 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"
}
]
}a API de Prevenção de Ameaças para o Security Gateway
Esta API foi desenvolvida antes da Threat Prevention API e é destinada apenas para dispositivos locais. No momento, só pode ser útil se você precisar da Threat Extraction API. Para Threat Emulation, é melhor usar a Threat Prevention API tradicional. Para habilitar TP API para SG e configurar a chave da API, é necessário realizar as ações descritas em . Recomendo prestar atenção no passo 6b e verificar a acessibilidade da página https:///UserCheck/TPAPI pois, em caso de resultado negativo, uma configuração posterior não faz sentido. Todas as chamadas de API serão enviadas para esta URL. O tipo de chamada (upload/query) éregulado pela chave do corpo da chamada — request_name. Outras chaves obrigatórias são — api_key (é necessário anotá-la durante a configuração) e protocol_version (atualmente, a versão mais recente é 1.1). A documentação oficial para esta API pode ser encontrada em . Entre as vantagens relativas, está a possibilidade de enviar vários arquivos para emulação simultaneamente durante o upload, pois os arquivos são enviados como uma string de texto base64. Para codificar/decodificar arquivos em/para base64, você pode usar um conversor online, por exemplo, no Postman — . Para fins práticos ao escrever o código, recomenda-se usar os métodos embutidos encode e decode.
Agora vamos nos aprofundar nas funções te e extraction nesta API.
Para o componente te é previsto um dicionário te_options nas requisições upload/query, e as chaves nesta requisição coincidem totalmente com as chaves te em .
Um exemplo de requisição para emular um arquivo no Win10 com relatórios
{
"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 o componente extraction é previsto um dicionário scrub_optionsNeste pedido, é especificado o método de limpeza: conversão para PDF, remoção de conteúdo ativo ou selecionar o modo de acordo com o perfil de Threat Prevention (o nome do perfil deve ser especificado). A característica distintiva da resposta a um pedido de API com extração para o arquivo é que você recebe uma cópia limpa como resposta a esse pedido na forma de uma string criptografada base64 (não é necessário fazer um pedido de consulta e procurar o ID para baixar o documento)
Exemplo de pedido para limpeza de arquivo
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Resposta ao pedido
{
"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": "Extrair conteúdo potencialmente malicioso",
"protection_type": "Conversão para PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "Arquivo TXT foi convertido para PDF",
"scrub_method": "Converter para PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Embora menos solicitações de API sejam necessárias para obter uma cópia limpa, considero essa opção menos preferível e conveniente do que a solicitação form-data utilizada em .
Coleções Postman
Criei coleções no Postman tanto para a API de Threat Prevention quanto para a API de Threat Prevention para Security Gateway, onde estão apresentados os pedidos de API mais comuns. Para que o ip/url do servidor API e a chave sejam inseridos automaticamente nos pedidos, e o hash sha256 após o upload do arquivo também seja lembrado, três variáveis foram criadas dentro das coleções (podem ser encontradas nas configurações da coleção Edit -> Variables): te_api (requere preenchimento), api_key (requere preenchimento, exceto no caso de uso da TP API com dispositivos locais), sha256 (deixar em branco, não utilizado na TP API for SG).
Exemplos de uso
Na comunidade estão disponíveis scripts escritos em Python que verificam arquivos do diretório desejado tanto através do , quanto o . Através da interação com a Threat Prevention API, suas capacidades de verificação de arquivos são significativamente ampliadas, pois agora você pode verificar arquivos em várias plataformas (a verificação no , e depois no sandbox Check Point), e os arquivos podem ser obtidos não apenas do tráfego de rede, mas também podem ser retirados de qualquer disco de rede e, por exemplo, de sistemas CRM.
Fonte: habr.com
