Dit artikel is nuttig voor degenen die bekend zijn met technologieën Check Point voor het emuleren van bestanden (Threat Emulation) en proactieve bestandsopschoning (Bedreigingsextractie) en willen een stap in de richting van automatisering van deze taken maken. Check Point heeft , dat zowel in de cloud als op lokale apparaten werkt, en functioneel identiek is aan het controleren van bestanden in web/smtp/ftp/smb/nfs verkeer. Dit artikel is gedeeltelijk een persoonlijke interpretatie van een set artikelen uit de officiële documentatie, maar is gebaseerd op mijn eigen ervaringen en voorbeelden. Ook in dit artikel vind je persoonlijke verzamelingen Postman voor het werken met de Threat Prevention API.
Belangrijke afkortingen
Threat Prevention API werkt met drie hoofdcomponenten, die in de API worden aangesproken door de volgende tekstwaarden:
av — de Anti-Virus component die verantwoordelijk is voor handtekeninganalyse van bekende bedreigingen.
tum — de Threat Emulation component die verantwoordelijk is voor het controleren van bestanden in een sandbox en het uitspreken van een oordeel over kwaadaardig (malicious)/schoon (benign) na emulatie.
extraction — de Threat Extraction component die verantwoordelijk is voor de snelle conversie van kantoor documenten naar een veilige versie (waarbij alle potentieel schadelijke inhoud wordt verwijderd) voor snelle levering aan gebruikers/systemen.
Structuur van de API en belangrijke beperkingen
Threat Prevention API gebruikt slechts 4 verzoeken — upload, query, download en quota. In de header voor alle vier de verzoeken moet de API-sleutel worden doorgegeven met de parameter Authorization. Op het eerste gezicht kan de structuur veel eenvoudiger lijken dan in de , maar het aantal velden in de verzoeken upload en query en de structuur van deze verzoeken zijn vrij complex. Ze kunnen functioneel worden vergeleken met profielen van Threat Prevention in de beveiligingspolicy van de gateway/sandbox.
Momenteel is er slechts één versie van de Threat Prevention API uitgebracht — 1.0, in de URL voor API-aanroepen moet worden aangegeven v1 in het gedeelte waar de versie moet worden opgegeven. In tegenstelling tot de Management API is het verplicht om de versie van de API in het URL-adres op te nemen, anders wordt het verzoek niet uitgevoerd.
De Anti-Virus component ondersteunt momenteel alleen query-verzoeken met md5-hashwaarden bij aanroep zonder andere componenten (te, extraction). Threat Emulation en Threat Extraction ondersteunen ook sha1 en sha256 hash waarden.
Het is heel belangrijk om geen fouten te maken in de verzoeken! Een verzoek kan worden uitgevoerd zonder fout, maar niet volledig. Laten we alvast kijken wat er kan gebeuren bij fouten/tipfouten in verzoeken.
Verzoek met een typefout in het woord reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}In de foutmelding zal niets verschijnen, maar er zal helemaal geen informatie over rapporten zijn.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Het verzoek is volledig beantwoord."
},
"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": "Het verzoek is volledig beantwoord."
}
}
}
]
}Hier is een verzoek zonder typefout in de sleutel reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}We ontvangen een antwoord waarin al id’s voor het downloaden van rapporten zijn opgenomen.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Het verzoek is volledig beantwoord."
},
"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": "Het verzoek is volledig beantwoord."
}
}
}
]
}Als je echter een onjuiste/verlopen API-sleutel verzendt, krijg je foutmelding 403 als antwoord.
SandBlast API: in de cloud en op lokale apparaten.
API-aanvragen kunnen worden verzonden naar Check Point-apparaten waarop de Threat Emulation-component (blade) is ingeschakeld. Als adres voor aanvragen moet je het ip/url van het apparaat gebruiken en poort 18194 (bijvoorbeeld — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию uitgeschakeld en de Authorization sleutel in de aanvraagkoppen hoeft helemaal niet te worden verzonden.
API-aanvragen naar de CheckPoint-cloud moeten worden verzonden naar het adres te.checkpoint.com (bijvoorbeeld — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Op lokale apparaten wordt Threat Extraction momenteel niet ondersteund in de standaard en moet worden gebruikt met (hierover zullen we aan het einde van het artikel meer details geven).
Lokale apparaten ondersteunen geen quota-aanvragen.
Verder zijn er geen verschillen tussen aanvragen aan lokale apparaten en aan de cloud.
Aanroep van de Upload API
De gebruikte methode is: PUT
Adres voor de aanroep: https://<service_address>/tecloud/api/v1/file/upload
De aanvraag bestaat uit twee delen (form-data): een bestand bestemd voor emulatie/reiniging en de aanroeptekst.
De tekstuele aanvraag mag niet leeg zijn, maar kan geen configuratie bevatten. Om de aanvraag succesvol te maken, moet minimaal de volgende tekst in de aanvraag worden verzonden:
Minimale vereisten voor de uploadaanvraag
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Headers:
Authorization: <api_key>
Body
{
"request": {
}
}
Bestand
Bestand
In dat geval komt het bestand voor verwerking volgens de standaardparameters binnen: component — tum, besturingssystemen — Win XP en Win 7, zonder het genereren van een rapport.
Opmerkingen over de belangrijkste velden in de tekstuele aanvraag:
file_name en file_type kunnen leeg gelaten worden of helemaal niet verzonden worden, aangezien dit geen bijzonder nuttige informatie is bij het uploaden van een bestand. In het API-antwoord worden deze velden automatisch ingevuld op basis van de naam van het geüploade bestand, en de informatie in de cache zal toch moeten worden gezocht op de md5/sha1/sha256-hashwaarden.
Voorbeeld van een aanvraag met lege file_name en file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — een lijst waarin de benodigde functionaliteit voor verwerking in de sandbox wordt opgegeven — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Als deze parameter helemaal niet wordt doorgegeven, wordt alleen de standaardcomponent — te(Threat Emulation) gebruikt.
Om controle in de drie beschikbare componenten in te schakelen, moeten deze componenten in de API-aanroep worden opgegeven.
Voorbeeld van een aanvraag met controle in av, te en extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Sleutels in het te-gedeelte
images — een lijst waarin woordenboeken met ID's en versienummers van besturingssystemen moeten worden vermeld waarin de controle zal plaatsvinden. ID's en versienummers zijn gelijk voor alle lokale apparaten en de cloud.
Lijst van besturingssystemen en versies
Beschikbare OS Image ID
Revisie
Image OS en Toepassing
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 en ActiveX 10.0
Java Runtime: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 — 32bit
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 — 32bit
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 — 32bit
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 — 64bit
Office: 2013 (32bit)
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 — 64bit
Office: 2013 (64bit)
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
Als de sleutel images helemaal niet wordt opgegeven, vindt de emulator plaats in de door Check Point aanbevolen beelden (op dit moment zijn dit Win XP en Win 7). Deze beelden zijn aanbevolen voor de beste balans tussen prestaties en catch rate.
rapporten — een lijst van rapporten die we aanvragen voor het geval het bestand kwaadwillig blijkt te zijn. De volgende opties zijn beschikbaar:
samenvatting — .tar.gz archief dat het emulatie-rapport bevat van met alles de aangevraagde image’s (zowel als html-pagina alsook componenten zoals een video uit het emulator-besturingssysteem, dump van netwerkverkeer, rapport in json, evenals het monster in een met wachtwoord beschermd archief). We zoeken in het antwoord naar de sleutel — samenvattingsrapport voor het volgende downloaden van het rapport.
pdf — document van de emulatie in één image, dat velen gewend zijn te ontvangen via Smart Console. We zoeken in het antwoord naar de sleutel — pdf-rapport voor het volgende downloaden van het rapport.
xml — document van de emulatie in één image, handig voor de verdere parsing van de parameters in het rapport. We zoeken in het antwoord naar de sleutel — xml-rapport voor het volgende downloaden van het rapport.
tar — .tar.gz archief dat het emulatie-rapport bevat in één de aangevraagde image’s (zowel als html-pagina alsook componenten zoals een video uit het emulator-besturingssysteem, dump van netwerkverkeer, rapport in json, evenals het monster in een met wachtwoord beschermd archief). We zoeken in het antwoord naar de sleutel — volledig rapport voor het volgende downloaden van het rapport.
Wat erin het samenvattingsrapport zit
De sleutels full_report, pdf_report, xml_report zijn aanwezig in het woordenboek voor elk besturingssysteem
{
"response": [
{
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "kwaadwillig",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "gevonden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "kwaadwillig",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "gevonden",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "kwaadwillig",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
}
}
}
]
}De sleutel samenvattingsrapport is er één voor de algehele emulatie
{
"response": [
{
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "kwaadaardig",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "gevonden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "kwaadaardig",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "gevonden",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "kwaadaardig",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
}
}
}
]
}U kunt gelijktijdig tar-, xml- en pdf-rapporten aanvragen, alsook een samenvattend rapport in combinatie met tar en xml. Een samenvattend rapport en pdf kunnen niet tegelijkertijd worden aangevraagd.
Sleutels in de sectie extraction
Voor bedreigingsextractie worden slechts twee sleutels gebruikt:
methode — pdf (conversie naar pdf, standaard gebruikt) of clean (verwijderen van actieve inhoud).
extracted_parts_codes — lijst van codes voor het verwijderen van actieve inhoud, alleen van toepassing voor de methode clean
Codes voor het verwijderen van inhoud uit bestanden
Code
Beschrijving
1025
Gekoppelde Objecten
1026
Macro's en Code
1034
Gevoelige Hyperlinks
1137
PDF GoToR Acties
1139
PDF Launch Acties
1141
PDF URI Acties
1142
PDF Geluidsacties
1143
PDF Filmacties
1150
PDF JavaScript Acties
1151
PDF Verzendformulier Acties
1018
Databasequery's
1019
Ingebedde Objecten
1021
Snelle Opslaggegevens
1017
Aangepaste Eigenschappen
1036
Statistische Eigenschappen
1037
Samenvattingseigenschappen
Voor het downloaden van een schone kopie is ook een query-aanvraag nodig (waarover later meer), door de hashwaarde van het bestand en de component extraction in de tekst van de aanvraag op te geven. Het schone bestand kan worden gedownload met behulp van de id uit het antwoord op de query-aanvraag — extracted_file_download_id. Nogmaals, iets vooruitlopend, geef ik voorbeelden van de aanvraag en het antwoord van de query voor het zoeken naar de id om het schone document te downloaden.
Query-aanvraag voor het vinden van de sleutel extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Antwoord op de query-aanvraag (vind de sleutel extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extractie"
],
"extraction": {
"method": "pdf",
"extract_result": "CP_EXTRACT_RESULT_SUCCESS",
"extracted_file_download_id": "b5f2b34e-3603-4627-9e0e-54665a531ab2",
"output_file_name": "kp-20-xls.clean.xlsx.pdf",
"time": "0.013",
"extract_content": "Macro's en Code",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.clean.xlsx.pdf",
"protection_name": "Potentieel kwaadaardige inhoud geëxtraheerd",
"protection_type": "Conversie naar PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Actieve inhoud gevonden - XLS-bestand is geconverteerd naar PDF",
"scrub_method": "conversie naar PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macro's en Code"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
}
}
}
]
}Algemene Informatie
Een enkele API-aanroep kan slechts één bestand naar controle verzenden.
De av-component vereist geen extra sectie met sleutels; het is voldoende om deze in de woordenlijst op te nemen. features.
API-aanroep Query
De gebruikte methode is: PUT
Adres voor de aanroep: https://<service_address>/tecloud/api/v1/file/query
Voordat je een bestand voor upload (upload-aanroep) verstuurt, is het aan te raden om een controle van de sandbox-cache (query-aanroep) uit te voeren om de belasting op de API-server te optimaliseren, aangezien er mogelijk al informatie en een oordeel over het te uploaden bestand op de API-server beschikbaar is. De aanroep bestaat uitsluitend uit de tekstuele inhoud. Een verplicht onderdeel van de aanvraag is de sha1/sha256/md5 hash van het bestand. Deze kan overigens in de reactie op de upload-aanroep worden verkregen.
Minimale vereisten voor de query-aanroep
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Headers:
Authorization: <api_key>
Body
{
"request": {
"sha256": <sha256 hash sum>
}
}
Voorbeeld van een reactie op de upload-aanroep, waar de sha1/md5/sha256 hash-sommen zichtbaar zijn
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCES",
"message": "Het bestand is succesvol geüpload."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "onbekend"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCES",
"message": "Het bestand is succesvol geüpload."
}
}
}
}De query-parameter moet in het ideale geval hetzelfde zijn als de upload aanvraag, of zelfs al moeten voldoen aan de voorwaarden (d.w.z. de query bevat minder velden dan de upload aanvraag). Als de query meer velden bevat dan de upload aanvraag, ontvangt u mogelijk niet alle benodigde informatie.
Hier is een voorbeeld van een antwoord op de query-aanroep, waarin niet alle vereiste gegevens zijn gevonden.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "De aanvraag kan op dit moment niet volledig worden beantwoord."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te",
"extraction"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "De aanvraag is volledig beantwoord."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Kon het gevraagde bestand niet vinden. Gelieve het te uploaden."
}
}
}
]
}Let op de velden code en label. Deze velden komen drie keer voor in de status dictionaries. We zien eerst de globale sleutel "code": 1006 en "label": "PARTIALLY_FOUND". Vervolgens komen deze sleutels voor elk afzonderlijk onderdeel dat we hebben opgevraagd — te en extraction. En terwijl voor te duidelijk is dat de gegevens zijn gevonden, ontbreekt de informatie voor extraction.
Zo zag de query-aanroep eruit voor het bovenstaande voorbeeld
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Als u de query-aanroep zonder de extraction component verzendt
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Dan zal het antwoord ook de volledige informatie bevatten ("code": 1001, "label": "FOUND")
{
"response": [
{
"status": {
"code": 1001,
"label": "Gevonden",
"message": "De aanvraag is volledig beantwoord."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "kwaadaardig",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "gevonden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "kwaadaardig",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "Gevonden",
"message": "De aanvraag is volledig beantwoord."
}
}
}
]
}Als er helemaal geen informatie in de cache is, dan staat er in het antwoord "label": "NIET_GEVONDEN"
{
"response": [
{
"status": {
"code": 1004,
"label": "NIET_GEVONDEN",
"message": "Het aangevraagde bestand kon niet worden gevonden. Upload het alstublieft."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "onbekend"
},
"status": "niet_gevonden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NIET_GEVONDEN",
"message": "Het aangevraagde bestand kon niet worden gevonden. Upload het alstublieft."
}
}
}
]
}In één API-aanroep kunnen meerdere hash-sommen tegelijk voor controle worden verzonden. In het antwoord worden de gegevens in dezelfde volgorde teruggegeven als ze in de aanvraag zijn verzonden.
Voorbeeld van een query-aanroep met meerdere sha256-sommen
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Antwoord op de query-aanroep met meerdere sha256-sommen
{
"response": [
{
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "kwaadaardig"
},
"status": "gevonden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "kwaadaardig",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "GEVONDEN",
"message": "De aanvraag is volledig beantwoord."
}
}
},
{
"status": {
"code": 1004,
"label": "NIET_GEVONDEN",
"message": "Kon het aangevraagde bestand niet vinden. Upload deze alstublieft."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "onbekend"
},
"status": "niet_gefounden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NIET_GEVONDEN",
"message": "Kon het aangevraagde bestand niet vinden. Upload deze alstublieft."
}
}
}
]
}Het verzoek om meerdere hashwaarden in een enkele query zal ook gunstig zijn voor de API serverprestaties.
Oproep naar de Download API
De gebruikte methode is: PUT (volgens de documentatie), GET werkt ook (en kan logischer lijken)
Adres voor de aanroep: https://<service_address>/tecloud/api/v1/file/download?id=<id>
In de header moet de API sleutel worden doorgegeven, het verzoeklichaam is leeg, id voor de download wordt doorgegeven in het url-adres.
Als reactie op de query-aanroep, in het geval dat de emulatie is voltooid en er rapporten zijn aangevraagd tijdens het uploaden van het bestand, zullen de id's voor het downloaden van de rapporten zichtbaar zijn. Als er een schone versie wordt aangevraagd, moet je het id voor het downloaden van het schone document zoeken.
Kortom, de sleutels in het antwoord op de query die de id voor de download bevatten, kunnen zijn:
samenvattingsrapport
volledig rapport
pdf-rapport
xml-rapport
extracted_file_download_id
Zeker, om deze sleutels in het antwoord op de query te krijgen, moeten ze worden opgegeven in de aanvraag (voor rapporten) of vergeet niet een verzoek te doen voor de extractiefunctie (voor schone documenten)
Oproep naar de Quota API
De gebruikte methode is: PUT
Adres voor de aanroep: https://<service_address>/tecloud/api/v1/file/quota
Voor het controleren van de resterende quota in de cloud wordt een quota-aanroep gebruikt. Het verzoeklichaam is leeg.
Voorbeeldantwoord op de quota-aanroep
{
"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
Deze API is ontwikkeld voordat de Threat Prevention API, en is alleen bedoeld voor lokale apparaten. Op dit moment kan het nuttig zijn als je de Threat Extraction API nodig hebt. Voor Threat Emulation is het beter om de reguliere Threat Prevention API te gebruiken. Om in te schakelen TP API voor SG en de API-sleutel te configureren, moeten de stappen in . Ik raad aan om stap 6b te bekijken en de toegankelijkheid van de pagina te controleren https:///UserCheck/TPAPI want bij een negatief resultaat heeft verdere configuratie geen zin. Naar deze URL zullen alle API-aanroepen worden verzonden. Het type aanroep (upload/query) wordt geregeld met de sleutel in de aanroepbody — request_name. Daarnaast zijn de verplichte sleutels — api_key (moet worden onthouden tijdens de configuratie) en protocol_version (op dit moment is de actuele versie 1.1). Je kunt de officiële documentatie voor deze API vinden in . Tot de relatieve voordelen behoren de mogelijkheid om meerdere bestanden tegelijkertijd te uploaden voor emulatie, aangezien bestanden worden verzonden als een base64-tekststring. Om bestanden in/uit base64 te coderen/decoderen, kun je voor demonstratiedoeleinden een online converter in Postman gebruiken, bijvoorbeeld — . In praktische toepassingen bij het schrijven van code moeten de ingebouwde methoden encode en decode worden gebruikt.
Laten we nu dieper ingaan op de functies tum en extraction in deze API.
Voor de component tum is er een woordenboek te_options in de upload/query-aanvragen, en de sleutels in deze aanvraag komen volledig overeen met de sleutels te in .
Een voorbeeld van een aanvraag voor emulatie van een bestand in Win10 met rapporten
{
"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"]
}
}
]
}Voor de component extraction is er een woordenboek scrub_optionsIn dit verzoek wordt de schoonmaakmethode opgegeven: conversie naar PDF, verwijdering van actieve inhoud, of het kiezen van de modus volgens het Threat Prevention-profiel (de naam van het profiel wordt opgegeven). Het bijzondere aan het antwoord op de API-aanroep voor extractie van een bestand is dat je een schone kopie ontvangt als reactie op dit verzoek in de vorm van een versleutelde base64-string (je hoeft geen query-aanroep te doen en het id voor het downloaden van het document te zoeken).
Voorbeeld van een verzoek voor het schoonmaken van een bestand
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Antwoord op het verzoek
{
"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": "Extract potentially malicious content",
"protection_type": "Conversion to PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT-bestand is geconverteerd naar PDF",
"scrub_method": "Conversie naar PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Hoewel het minder API-verzoeken vereist om een schone kopie te verkrijgen, beschouw ik deze optie als minder wenselijk en handig dan het form-data verzoek dat wordt gebruikt in .
Postman-collecties
Ik heb collecties in Postman gemaakt voor zowel de Threat Prevention API als de Threat Prevention API for Security Gateway, waarin de meest gebruikte API-verzoeken zijn opgenomen. Om ervoor te zorgen dat de ip/url van de API-server en de sleutel automatisch in de verzoeken worden ingevoegd, en dat de sha256-hashsom na het uploaden van het bestand ook wordt onthouden, zijn er drie variabelen gecreëerd binnen de collecties (je kunt deze vinden door naar de instellingen van de collectie te gaan en te klikken op Bewerken -> Variabelen): te_api (moet ingevuld worden), api_key (moet ingevuld worden, behalve in het geval van het gebruik van de TP API met lokale apparaten), sha256 (laat leeg, wordt niet gebruikt in de TP API for SG).
Voorbeelden van gebruik
In de gemeenschap zijn er scripts gepresenteerd, geschreven in Python, die bestanden uit de gewenste directory controleren via , als voor . Door interactie met de Threat Prevention API worden je mogelijkheden voor het controleren van bestanden aanzienlijk uitgebreid, omdat je nu bestanden in meerdere platforms tegelijk kunt controleren (het is interessant om het te controleren in , en daarna in de Check Point sandbox), en bestanden ontvangen niet alleen uit het netwerkverkeer, maar ook ophalen van andere netwerkschijven en bijvoorbeeld CRM-systemen.
Bron: habr.com
