Dit artikel zal nuttig zijn voor degenen die bekend zijn met technologie Check Point door bestandsemulatie (Bedreigingsemulatie) en proactieve bestandsopschoning (Bedreigingsextractie) en wil een stap zetten in de richting van het automatiseren van deze taken. Checkpoint heeft
Basisafkortingen
De Threat Prevention API werkt met drie hoofdcomponenten, die in de API worden aangeroepen via de volgende tekstwaarden:
av — Antiviruscomponent, verantwoordelijk voor handtekeninganalyse van bekende bedreigingen.
te - Component voor bedreigingsemulatie, verantwoordelijk voor het controleren van bestanden in de sandbox en het maken van een kwaadaardig/goedaardig oordeel na emulatie.
extractie - Threat Extraction-component, verantwoordelijk voor het snel omzetten van kantoordocumenten in een veilige vorm (waarin alle potentieel schadelijke inhoud wordt verwijderd), om ze snel aan gebruikers/systemen te bezorgen.
API-structuur en belangrijkste beperkingen
Threat Prevention API gebruikt slechts 4 verzoeken − uploaden, opvragen, downloaden en quota. In de header van alle vier de verzoeken moet u de API-sleutel doorgeven met behulp van de parameter autorisatie. Op het eerste gezicht lijkt de structuur veel eenvoudiger dan in
Op dit moment is de enige versie van de Threat Prevention API uitgebracht: 1.0; de URL voor API-aanroepen moet bevatten v1 in het gedeelte waar u de versie moet opgeven. In tegenstelling tot de Management API is het noodzakelijk om de API-versie in de URL aan te geven, anders wordt het verzoek niet uitgevoerd.
Wanneer de Anti-Virus-component wordt aangeroepen zonder andere componenten (te, extractie), ondersteunt deze momenteel alleen queryverzoeken met md5-hash-sommen. Threat Emulation en Threat Extraction ondersteunen ook sha1- en sha256-hash-sommen.
Het is erg belangrijk om geen fouten te maken in zoekopdrachten! Het verzoek kan foutloos worden uitgevoerd, maar niet volledig. Laten we een beetje vooruit kijken en kijken naar wat er kan gebeuren als er fouten/typefouten in zoekopdrachten voorkomen.
Verzoek met een typfout met het woord report(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}
Er zal geen fout in het antwoord voorkomen, maar er zal helemaal geen informatie over de rapporten zijn
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"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": "The request has been fully answered."
}
}
}
]
}
Maar voor een verzoek zonder typefout in de rapportsleutel
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}
We ontvangen een reactie die al een ID bevat voor het downloaden van rapporten
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"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": "The request has been fully answered."
}
}
}
]
}
Als wij een onjuiste/verlopen API-sleutel versturen, krijgen wij als reactie een 403-foutmelding.
SandBlast API: in de cloud en op lokale apparaten
API-verzoeken kunnen worden verzonden naar Check Point-apparaten waarop de component Threat Emulation (Blade) is ingeschakeld. Als adres voor verzoeken moet u het ip/url-adres van het apparaat en poort 18194 gebruiken (bijvoorbeeld https://10.10.57.19:18194/tecloud/api/v1/bestand/query). Zorg er ook voor dat het beveiligingsbeleid op het apparaat deze verbinding toestaat. Autorisatie standaard via API-sleutel op lokale apparaten uit en de autorisatiesleutel in de aanvraagheaders wordt mogelijk helemaal niet verzonden.
API-verzoeken naar de CheckPoint-cloud moeten worden verzonden naar te.checkpoint.com (bijvoorbeeld - https://te.checkpoint.com/tecloud/api/v1/bestand/query). De API-sleutel kan als proeflicentie voor 60 dagen worden verkregen door contact op te nemen met Check Point-partners of het lokale kantoor van het bedrijf.
Op lokale apparaten wordt Threat Extraction nog niet standaard ondersteund.
Lokale apparaten ondersteunen het quotumverzoek niet.
Voor het overige zijn er geen verschillen tussen verzoeken aan lokale apparaten en aan de cloud.
Upload API-oproep
Gebruikte methode − POST
Beladres - https:///tecloud/api/v1/file/upload
Het verzoek bestaat uit twee delen (formuliergegevens): een bestand bedoeld voor emulatie/opschoning en een verzoektekst met tekst.
Het tekstverzoek mag niet leeg zijn, maar mag geen configuratie bevatten. Om het verzoek succesvol te laten zijn, moet u in ieder geval de volgende tekst meesturen in het verzoek:
Minimaal vereist voor een uploadverzoek
HTTP-POST
https:///tecloud/api/v1/file/upload
headers:
autorisatie:
Lichaam
{
"verzoek": {
}
}
Dien in
Dien in
In dit geval wordt het bestand verwerkt in overeenstemming met de standaardparameters: component - te, OS-afbeeldingen - Win XP en Win 7, zonder een rapport te genereren.
Opmerkingen over de belangrijkste velden in het tekstverzoek:
bestandsnaam и bestandstype U kunt ze leeg laten of helemaal niet verzenden, aangezien dit niet 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 gedownloade bestand en moet de informatie in de cache nog steeds worden doorzocht met behulp van md5/sha1/sha256-hashbedragen.
Voorbeeldverzoek met lege bestandsnaam en bestandstype
{
"request": {
"file_name": "",
"file_type": "",
}
}
functionaliteiten — een lijst die de noodzakelijke functionaliteit aangeeft bij verwerking in de sandbox - av (Anti-Virus), te (Threat Emulation), extractie (Threat Extraction). Als deze parameter helemaal niet wordt doorgegeven, wordt alleen de standaardcomponent gebruikt: te (bedreigingsemulatie).
Om het inchecken van de drie beschikbare componenten mogelijk te maken, moet u deze componenten opgeven in de API-aanvraag.
Voorbeeld van een aanvraag met inchecken av, te en extractie
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}
Toetsen in het te-gedeelte
afbeeldingen — een lijst met woordenboeken met ID en revisienummer van de besturingssystemen waarin de controle zal worden uitgevoerd. ID's en revisienummers zijn hetzelfde voor alle lokale apparaten en de cloud.
Lijst met besturingssystemen en revisies
Beschikbare OS-image-ID
Herziening
Image-besturingssysteem en -applicatie
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP - 32bit SP3
Kantoor: 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
Kantoor: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Inpluggen& ActiveX)
Java-runtime: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 - 32bit
Kantoor: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Inpluggen & ActiveX)
Java-runtime: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 - 32bit
Kantoor: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Inpluggen & ActiveX)
Java-runtime: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 - 64bit
Kantoor: 2013 (32-bits)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Inpluggen & ActiveX)
Java-runtime: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 - 64bit
Kantoor: 2013 (64-bits)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Inpluggen & ActiveX)
Java-runtime: 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
Microsoft Windows: 10
Kantoor: Professional Plus 2016 nl-nl
Adobe Acrobat Reader: DC 2015 MUI
Flash Player: 20 (Inpluggen & ActiveX)
Java-runtime: 1.7.0u9
Als de afbeeldingensleutel helemaal niet is opgegeven, vindt emulatie plaats in afbeeldingen die worden aanbevolen door Check Point (momenteel Win XP en Win 7). Deze afbeeldingen worden aanbevolen op basis van overwegingen van de beste balans tussen prestaties en vangstpercentage.
meldt — een lijst met rapporten die we opvragen voor het geval het bestand schadelijk blijkt te zijn. De volgende opties zijn beschikbaar:
-
beknopte versie - .tar.gz-archief met een rapport over emulatie door alle gevraagde afbeeldingen (zowel een html-pagina als componenten zoals een video van het besturingssysteem van de emulator, een dump van netwerkverkeer, een rapport in json en het voorbeeld zelf in een met een wachtwoord beveiligd archief). We zijn op zoek naar de sleutel in het antwoord - samenvattingsverslag voor het later downloaden van het rapport.
-
pdf - document over emulatie in een afbeelding, die velen gewend zijn te ontvangen via de Smart Console. We zijn op zoek naar de sleutel in het antwoord - pdf_rapport voor het later downloaden van het rapport.
-
xml - document over emulatie in een afbeelding, handig voor het later parseren van parameters in het rapport. We zijn op zoek naar de sleutel in het antwoord - xml_rapport voor het later downloaden van het rapport.
-
teer - .tar.gz-archief met een rapport over emulatie in een gevraagde afbeeldingen (zowel een html-pagina als componenten zoals een video van het besturingssysteem van de emulator, een dump van netwerkverkeer, een rapport in json en het voorbeeld zelf in een met een wachtwoord beveiligd archief). We zijn op zoek naar de sleutel in het antwoord - volledig rapport voor het later downloaden van het rapport.
Wat staat er in het samenvattende rapport?
De sleutels full_report, pdf_report, xml_report staan in het woordenboek voor elk besturingssysteem
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicious",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "found",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}
Maar de summary_report-sleutel: er is er een voor emulatie in het algemeen
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicious",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "found",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}
U kunt tegelijkertijd tar- en xml- en pdf-rapporten opvragen, u kunt samenvattingen en tar- en xml-rapporten opvragen. Het is niet mogelijk om tegelijkertijd een samenvattend rapport en een pdf op te vragen.
Sleutels in het extractiegedeelte
Voor het extraheren van bedreigingen worden slechts twee sleutels gebruikt:
methode — pdf (converteren naar pdf, standaard gebruikt) of clean (actieve inhoud opschonen).
geëxtraheerde_onderdelen_codes - lijst met codes voor het verwijderen van actieve inhoud, alleen van toepassing op de schone methode
Codes voor het verwijderen van inhoud uit bestanden
Code
Omschrijving
1025
Gekoppelde objecten
1026
Macro's en code
1034
Gevoelige hyperlinks
1137
PDF GoToR-acties
1139
PDF-startacties
1141
PDF-URI-acties
1142
PDF-geluidsacties
1143
PDF-filmacties
1150
PDF JavaScript-acties
1151
PDF-verzendformulieracties
1018
Database Queries
1019
Ingesloten objecten
1021
Snel gegevens opslaan
1017
Aangepaste eigenschappen
1036
Statistische eigenschappen
1037
Samenvatting eigenschappen
Om een opgeschoonde kopie te downloaden, moet u na een paar seconden ook een queryverzoek indienen (dat hieronder wordt besproken), waarbij u de hash-hoeveelheid van het bestand en de extractiecomponent in de verzoektekst specificeert. U kunt het opgeschoonde bestand ophalen met behulp van de id uit het antwoord op de vraag: extracted_file_download_id. Nogmaals, een beetje vooruitkijkend, geef ik voorbeelden van een verzoek en een vraagantwoord om te zoeken naar een ID voor het downloaden van een gewist document.
Queryverzoek om te zoeken naar de sleutel geëxtraheerde_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}
Antwoord op vraag (zoek naar geëxtraheerde_file_download_id sleutel)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extraction"
],
"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 and Code",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potential malicious content extracted",
"protection_type": "Conversion to PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Active content was found - XLS file was converted to PDF",
"scrub_method": "Convert to PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros and Code"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}
Overzicht
In één API-aanroep kunt u slechts één bestand ter verificatie verzenden.
De av-component vereist geen extra sectie met sleutels, het volstaat om dit in het woordenboek op te geven functionaliteiten.
Query-API-aanroep
Gebruikte methode − POST
Beladres - https:///tecloud/api/v1/file/query
Voordat u een bestand verzendt om te downloaden (uploadverzoek), is het raadzaam om de sandbox-cache (queryverzoek) te controleren om de belasting van de API-server te optimaliseren, aangezien de API-server mogelijk al informatie en een oordeel over het gedownloade bestand heeft. De oproep bestaat alleen uit een tekstgedeelte. Het vereiste deel van het verzoek is de sha1/sha256/md5-hashhoeveelheid van het bestand. Je kunt het trouwens krijgen in het antwoord op het uploadverzoek.
Minimaal vereist voor query
HTTP-POST
https:///tecloud/api/v1/file/query
headers:
autorisatie:
Lichaam
{
"verzoek": {
"sha256":
}
}
Een voorbeeld van een reactie op een uploadverzoek, waarbij sha1/md5/sha256 hash-hoeveelheden zichtbaar zijn
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "The file was uploaded successfully."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "The file was uploaded successfully."
}
}
}
}
Het queryverzoek zou, naast de hash-hoeveelheid, idealiter hetzelfde moeten zijn als het uploadverzoek was (of gepland is te zijn), of zelfs “al” (bevat minder velden in het queryverzoek dan in het uploadverzoek). In het geval dat het queryverzoek meer velden bevat dan in het uploadverzoek, ontvangt u niet alle vereiste informatie in het antwoord.
Hier ziet u een voorbeeld van een antwoord op een zoekopdracht waarbij niet alle vereiste gegevens zijn gevonden
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "The request cannot be fully answered at this time."
},
"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": "The request has been fully answered."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}
Let op de velden code и label. Deze velden verschijnen drie keer in statuswoordenboeken. Eerst zien we de globale sleutel “code”: 1006 en “label”: “PARTIALLY_FOUND”. Vervolgens worden deze sleutels gevonden voor elk afzonderlijk onderdeel dat we hebben aangevraagd: te en extractie. En als het bijvoorbeeld duidelijk is dat de gegevens zijn gevonden, dan is er voor extractie geen informatie.
Zo zag de query eruit in het bovenstaande voorbeeld
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}
Als u een queryverzoek verzendt zonder de extractiecomponent
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}
Dan bevat het antwoord volledige informatie (“code”: 1001, “label”: “FOUND”)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"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": "The request has been fully answered."
}
}
}
]
}
Als er helemaal geen informatie in de cache zit, is het antwoord “label”: “NOT_FOUND”
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}
In één API-aanroep kunt u meerdere hash-bedragen tegelijk verzenden ter verificatie. Het antwoord retourneert gegevens in dezelfde volgorde als waarin deze in het verzoek zijn verzonden.
Voorbeeldqueryverzoek met verschillende sha256-bedragen
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}
Antwoord op een vraag met meerdere sha256-bedragen
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"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": "The request has been fully answered."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}
Het in één keer opvragen van meerdere hash-sommen in een query-verzoek zal ook een gunstig effect hebben op de prestaties van de API-server.
API-oproep downloaden
Gebruikte methode − POST (volgens documentatie), GET werkt ook (en lijkt misschien logischer)
Beladres - https:///tecloud/api/v1/file/download?id=
De header vereist dat de API-sleutel wordt doorgegeven, de hoofdtekst van het verzoek is leeg en de download-ID wordt doorgegeven in het URL-adres.
Als reactie op een queryverzoek, als de emulatie is voltooid en er rapporten zijn opgevraagd bij het downloaden van het bestand, zal de id voor het downloaden van rapporten zichtbaar zijn. Als er om een opgeschoonde kopie wordt gevraagd, moet u naar de ID zoeken om het opgeschoonde document te downloaden.
In totaal kunnen de sleutels in het antwoord op de vraag met de id-waarde voor laden zijn:
-
samenvattingsverslag
-
volledig rapport
-
pdf_rapport
-
xml_rapport
-
uitgepakt_bestand_download_id
Om deze sleutels te ontvangen als reactie op het opvraagverzoek, moeten ze uiteraard in het verzoek worden gespecificeerd (voor rapporten) of vergeet niet om een verzoek in te dienen met behulp van de extractiefunctie (voor opgeschoonde documenten)
Quota-API-aanroep
Gebruikte methode − POST
Beladres - https:///tecloud/api/v1/file/quota
Gebruik de quotaquery om het resterende quotum in de cloud te controleren. De aanvraagtekst is leeg.
Voorbeeldantwoord op een quotumverzoek
{
"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"
}
]
}
Bedreigingspreventie-API voor Security Gateway
Deze API is ontwikkeld vóór de Threat Prevention API en is alleen bedoeld voor lokale apparaten. Voorlopig kan het alleen nuttig zijn als je de Threat Extraction API nodig hebt. Voor Threat Emulation is het beter om de reguliere Threat Prevention API te gebruiken. Aanzetten TP API voor SG en configureer de API-sleutel die u nodig hebt om de stappen te volgen
Laten we nu de functies eens nader bekijken te и extractie in deze API.
Voor onderdeel te woordenboek voorzien te_opties in upload-/queryverzoeken, en de sleutels in dit verzoek vallen volledig samen met de sleutels in
Voorbeeldverzoek voor bestandsemulatie in Win10 met rapporten
{
"request": [{
"protocol_version": "1.1",
"api_key": "<api_key>",
"request_name": "UploadFile",
"file_enc_data": "<base64_encoded_file>",
"file_orig_name": "<filename>",
"te_options": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": ["summary", "xml"]
}
}
]
}
Voor onderdeel extractie woordenboek voorzien scrub_opties. Dit verzoek specificeert de opschoonmethode: converteren naar PDF, actieve inhoud wissen of een modus selecteren in overeenstemming met het Bedreigingspreventieprofiel (de profielnaam wordt aangegeven). Het mooie van het reageren op een extractie-API-verzoek voor een bestand is dat je in het antwoord op dat verzoek een opgeschoonde kopie krijgt als een met base64 gecodeerde tekenreeks (je hoeft geen queryverzoek in te dienen en de ID op te zoeken om het bestand te downloaden). document)
Voorbeeld van een verzoek om een bestand te wissen
{
"request": [{
"protocol_version": "1.1",
"api_key": "<API_KEY>",
"request_name": "UploadFile",
"file_enc_data": "<base64_encoded_file>",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}
Reageer op een verzoek
{
"response": [{
"protocol_version": "1.1",
"src_ip": "<IP_ADDRESS>",
"scrub": {
"file_enc_data": "<base64_encoded_converted_to_PDF_file>",
"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 file was converted to PDF",
"scrub_method": "Convert to PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
}
Ondanks het feit dat er minder API-verzoeken nodig zijn om een goedgekeurde kopie te verkrijgen, vind ik deze optie minder de voorkeur en handiger dan het formuliergegevensverzoek dat wordt gebruikt in
Postbode-collecties
Ik heb verzamelingen gemaakt in Postman voor zowel de Threat Prevention API als de Threat Prevention API voor Security Gateway, die de meest voorkomende API-verzoeken vertegenwoordigen. Om ervoor te zorgen dat de server ip/url API en sleutel automatisch in verzoeken worden vervangen, en dat de sha256 hash-hoeveelheid wordt onthouden na het downloaden van het bestand, zijn er drie variabelen aangemaakt in de collecties (je kunt ze vinden door naar de collectie-instellingen te gaan Bewerken -> Variabelen): te_api (vereist), api_key (verplicht in te vullen, behalve bij gebruik van TP API met lokale apparaten), sha256 (leeg laten, niet gebruikt in TP API voor SG).
Gebruiksvoorbeelden
In de gemeenschap
Bron: www.habr.com