Denne artikel vil være nyttig for dem, der er bekendt med teknologier Check Point til emulering af filer (Trusselsemlation) og proaktiv rensning af filer (Trusseludtrækning) og ønsker at tage et skridt mod automatisering af disse opgaver. Check Point har , der fungerer både i skyen og på lokale enheder, og funktionelt er det identisk med kontrol af filer i strømme af web/smtp/ftp/smb/nfs trafik. Denne artikel er delvist en personlig fortolkning af en række artikler fra den officielle dokumentation, men bygget på min erfaring med drift og egne eksempler. Du vil også finde forfatterens Postman-samlinger til arbejde med Threat Prevention API.
Vigtigste forkortelser
Threat Prevention API arbejder med tre hovedkomponenter, som i API'et kaldes via følgende tekstværdier:
av — Anti-Virus komponent, ansvarlig for signaturanalyse af kendte trusler.
te — Threat Emulation komponent, ansvarlig for kontrol af filer i sandkassen og for at afgive dom om skadelig (malicious)/ren (benign) efter emuleringen.
extraction — Threat Extraction komponent, ansvarlig for hurtig konvertering af kontor dokumenter til en sikker version (hvor alt potentielt skadelig indhold fjernes), for hurtigt at kunne levere det til brugere/systemer.
API-struktur og hovedbegrænsninger
Threat Prevention API bruger kun 4 forespørgsler — upload, query, download og quota. I headeren for alle fire forespørgsler skal API-nøglen sendes ved at bruge parameteren Authorization. Ved første øjekast kan strukturen virke meget enklere end i , men antallet af felter i upload- og forespørgselsanmodningerne og strukturen af disse forespørgsler er ret komplekse. De kan funktionelt sammenlignes med profiler for Threat Prevention i sikkerhedspolitikken for gateway/sandkasse.
I øjeblikket er der kun udgivet én version af Threat Prevention API — 1.0, i URL til API-kald skal versionen angives v1 i den del, hvor versionen skal angives. I modsætning til Management API, er det obligatorisk at angive API-versionen i URL-adressen, ellers vil forespørgslen ikke blive udført.
Anti-Virus komponenten understøtter ved kald uden andre komponenter (te, extraction) kun forespørgsler om query med md5 hash-værdier. Threat Emulation og Threat Extraction understøtter også sha1 og sha256 hash-værdier.
Det er meget vigtigt ikke at lave fejl i forespørgslerne! An inquiry may be executed without an error, but not completely. Let's look ahead at what might happen with errors/typos in inquiries.
Inquiry with a typo in the word reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}There will be no error in the response, but there will be no information about the reports at all.
{
"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."
}
}
}
]
}Now consider the inquiry without a typo in the key reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}We receive a response that already contains IDs for downloading the reports.
{
"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."
}
}
}
]
}If an incorrect/expired API key is sent, the response will return an error 403.
SandBlast API: in the cloud and on local devices.
API requests can be sent to Check Point devices where the Threat Emulation component (blade) is enabled. For requests, you should use the device's IP/URL and port 18194 (for example — https://.10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию disabled og Authorization-nøgle i anmodningsoverskrifterne kan slet ikke sendes.
API-anmodninger til CheckPoint-skyen skal sendes til adressen te.checkpoint.com (f.eks. — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
På lokale enheder understøttes Threat Extraction endnu ikke som standard og skal bruge (det vil vi tale mere om til sidst i artiklen).
Lokale enheder understøtter ikke quota-anmodninger.
Bortset fra dette er der ikke forskelle mellem anmodninger til lokale enheder og til skyen.
Opkald til Upload API
Den anvendte metode er — POST
Adressen til opkaldet er — https://<service_address>/tecloud/api/v1/file/upload
Anmodningen består af to dele (form-data): en fil beregnet til emulering/rensning og brødteksten med indholdet.
Brødteksten kan ikke være tom, men den kan ikke indeholde nogen konfiguration. For at anmodningen skal være vellykket, skal du mindst sende følgende tekst i anmodningen:
Det nødvendige minimum for upload-anmodningen
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Overskrifter:
Authorization: <api_key>
Krop
{
"request": {
}
}
Fil
Fil
I så fald vil filen til behandling komme ind i overensstemmelse med standardparametrene: komponent — te, operativsystembilleder — Win XP og Win 7, uden at der genereres en rapport.
Kommentarer til de vigtigste felter i brødteksten:
file_name og file_type kan efterlades tomme eller slet ikke sendes, da disse ikke er nyttige oplysninger ved filupload. I API-svaret vil disse felter automatisk blive udfyldt baseret på navnet på den uploadede fil, og informationen i cachen må stadig søges efter md5/sha1/sha256 hash.
Eksempel på anmodning med tomme file_name og file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — en liste, hvor den nødvendige funktionalitet under behandling i sandkassen angives — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Hvis denne parameter slet ikke sendes, vil kun standardkomponenten — te (Threat Emulation) — blive brugt.
For at aktivere kontrol i de tre tilgængelige komponenter skal du angive disse komponenter i API-anmodningen.
Eksempel på anmodning med kontrol i av, te og extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Nøgler i afsnittet te
images — en liste, som skal indeholde ordbøger med id og revisionsnummer for operativsystemer, hvor kontrol skal udføres. ID og revisionsnumre er de samme for alle lokale enheder og skyen.
Liste over operativsystemer og revisioner
Available OS Image ID
Revision
Billede OS og applikation
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 og 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
Hvis nøglebilledet ikke angives overhovedet, vil emuleringen finde sted i billeder anbefalet af Check Point (i øjeblikket er det Win XP og Win 7). Disse billeder er anbefalet for at opnå den bedste balance mellem ydeevne og fangstrate.
rapporter — listen over rapporter, som vi anmoder om i tilfælde af, at filen skulle vise sig at være skadelig. Følgende muligheder er tilgængelige:
resumé — .tar.gz arkiv, der indeholder en rapport om emuleringen for alle anmodede image'er (både som html-side og andre komponenter såsom en video fra emulatorens OS, dump af netværkstrafik, rapport i json, samt selve eksemplet i en beskyttet arkiv). I svaret leder vi efter nøgle— summary_report til efterfølgende download af rapporten.
pdf — dokument om emuleringen i et image, som mange er vant til at modtage via Smart Console. I svaret leder vi efter nøgle— pdf_report til efterfølgende download af rapporten.
xml — dokument om emuleringen i et image, praktisk til efterfølgende parsing af parametre i rapporten. I svaret leder vi efter nøgle— xml_report til efterfølgende download af rapporten.
tar — .tar.gz arkiv, der indeholder en rapport om emuleringen i et anmodede image'er (både som html-side og andre komponenter såsom en video fra emulatorens OS, dump af netværkstrafik, rapport i json, samt selve eksemplet i en beskyttet arkiv). I svaret leder vi efter nøgle— full_report til efterfølgende download af rapporten.
Hvad der er inde i rapporten summary
Nøglerne full_report, pdf_report, xml_report er tilgængelige i ordbogen for hver OS
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Anmodningen er blevet fuldt besvaret."
},
"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": "Anmodningen er blevet fuldt besvaret."
}
}
}
]
}Og nøgle summary_report — er én til emuleringen som helhed
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Forespørgslen er blevet fuldt besvaret."
},
"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": "Forespørgslen er blevet fuldt besvaret."
}
}
}
]
}Det er muligt at anmode om både tar- og xml- og pdf-rapporter samtidig, og man kan også anmode om en summary samt tar og xml. Det er ikke muligt at anmode om en summary-rapport og pdf samtidigt.
Nøgler i afsnittet extraction
Der bruges kun to nøgler til trusselsekstraktion:
metode — pdf (konvertering til pdf, bruges som standard) eller clean (rensning af aktivt indhold).
extracted_parts_codes — liste over koder til fjernelse af aktivt indhold, gælder kun for metoden clean
Koder til fjernelse af indhold fra filer
Kode
Beskrivelse
1025
Koblede objekter
1026
Makroer og kode
1034
Følsomme hyperlinks
1137
PDF GoToR-handlinger
1139
PDF Launch-handlinger
1141
PDF URI-handlinger
1142
PDF Lyd-handlinger
1143
PDF Film-handlinger
1150
PDF JavaScript-handlinger
1151
PDF Indsend formular-handlinger
1018
Databasespørgsmål
1019
Indlejrede objekter
1021
Hurtig gemme-data
1017
Brugerdefinerede egenskaber
1036
Statistiske egenskaber
1037
Sammendragsegenskaber
For at downloade en renset kopi skal der også sends en query-anmodning (som vil blive beskrevet senere) om et par sekunder, hvor hashværdien af filen og komponenten extraction angives i anmodningsteksten. Den rensede fil kan hentes med id'et fra svaret på query-anmodningen — extracted_file_download_id. Endnu engang, for at forberede mig lidt, viser jeg eksempler på anmodning og svar for at finde id til download af det rensede dokument.
Query-anmodning for at finde nøgle extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Svar på query-anmodning (find nøgle extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Anmodningen er blevet besvaret fuldt ud."
},
"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": "Makroer og Kode",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potentielt skadeligt indhold udvundet",
"protection_type": "Konvertering til PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Aktivt indhold blev fundet - XLS-fil blev konverteret til PDF",
"scrub_method": "Konverter til PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Makroer og Kode"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Anmodningen er blevet besvaret fuldt ud."
}
}
}
]
}Generel information
I en API-anmodning kan der kun sendes én fil til kontrol.
Komponenten av kræver ikke et ekstra afsnit med nøgler, det er tilstrækkeligt at angive det i ordbogen features.
Anmodning til Query API
Den anvendte metode er — POST
Adressen til opkaldet er — https://<service_address>/tecloud/api/v1/file/query
Før du sender en fil til upload (anmodning upload), er det en god idé at udføre en cachekontrol (anmodning query) for at optimere belastningen på API-serveren, da der muligvis allerede er oplysninger og domme om den uploadede fil på API-serveren. Anmodningen består kun af tekstdelen. Den obligatoriske del af anmodningen er sha1/sha256/md5 hash-summen af filen. Den kan i øvrigt hentes i svaret på upload-anmodningen.
Minimumskrav til query-anmodningen
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Overskrifter:
Authorization: <api_key>
Krop
{
"request": {
"sha256": <sha256 hash sum>
}
}
Eksempel på svar på upload-anmodning, hvor sha1/md5/sha256 hash-summerne er synlige
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Filen blev uploadet med succes."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "ukendt"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Filen blev uploadet med succes."
}
}
}
}Forespørgslen query bør ideelt set være den samme som upload-forespørgslen (eller planlægges at være), eller endda "allerede" (indeholde færre felter i forespørgslen query end i forespørgslen upload). I tilfælde af, at forespørgslen query indeholder flere felter end i forespørgslen upload, vil du ikke modtage alle de nødvendige oplysninger i svaret.
Her er et eksempel på svaret på forespørgslen query, hvor ikke alle de nødvendige data blev fundet.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Forespørgslen kan ikke besvares fuldt ud på nuværende tidspunkt."
},
"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": "Forespørgslen er blevet fuldt besvaret."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Den ønskede fil kunne ikke findes. Venligst upload den."
}
}
}
]
}Vær opmærksom på felterne. code og label. Disse felter forekommer tre gange i status-ordbøgerne. Først ser vi den globale nøgle "code": 1006 og "label": "PARTIALLY_FOUND". Derefter forekommer disse nøgler for hver enkelt komponent, vi har anmodet om — te og extraction. Og hvis det for te er forståeligt, at dataene er fundet, så mangler informationen for extraction.
Sådan så forespørgslen query ud for eksemplet ovenfor.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Hvis du sender forespørgslen query uden komponenten extraction.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Så vil svaret også indeholde fuldstændige oplysninger ("code": 1001, "label": "FOUND").
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Anmodningen er blevet besvaret fuldt ud."
},
"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": "Anmodningen er blevet besvaret fuldt ud."
}
}
}
]
}Hvis der ikke er nogen oplysninger i cachen overhovedet, vil svaret være «label»: «NOT_FOUND»
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Det kunne ikke lade sig gøre at finde den ønskede fil. Upload venligst filen."
},
"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": "Det kunne ikke lade sig gøre at finde den ønskede fil. Upload venligst filen."
}
}
}
]
}I én API-anmodning kan du sende flere hash-værdier til kontrol. Dataene vil blive returneret i den samme rækkefølge, som de blev sendt i anmodningen.
Eksempel på en forespørgsel med flere sha256-hash-værdier
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Svar på en forespørgsel med flere sha256-hash-værdier
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Anmodningen er blevet besvaret fuldt ud."
},
"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": "Anmodningen er blevet besvaret fuldt ud."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Kunne ikke finde den anmodede fil. Venligst upload den."
},
"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": "Kunne ikke finde den anmodede fil. Venligst upload den."
}
}
}
]
}At anmode om flere hash-summer i en enkelt forespørgsel vil også gavne API-serverens ydeevne.
Kald Download API
Den anvendte metode er — POST (ifølge dokumentationen), GET fungerer også (og kan virke mere logisk)
Adressen til opkaldet er — https://<service_address>/tecloud/api/v1/file/download?id=<id>
API-nøglen skal overføres i headeren, anmodningens krop er tom, id til download sendes i URL-adressen.
I svaret på query-anmodningen, hvis emuleringen er afsluttet, og ved upload af filen var rapporter blevet anmodet, vil ids for download af rapporter være synlige. Hvis der anmodes om en renset kopi, skal id'et for download af det rensede dokument findes.
Sammenfattende kan nøglerne i svaret på query-anmodningen, der indeholder id-værdien for download, være:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Selvfølgelig, for at disse nøgler skal komme med i svaret på query-anmodningen, skal de angives i anmodningen (for rapporterne) eller man skal huske at anmode om funktionen extraction (for de rensede dokumenter)
Kald Quota API
Den anvendte metode er — POST
Adressen til opkaldet er — https://<service_address>/tecloud/api/v1/file/quota
For at kontrollere den resterende kvote på cloud'en anvendes anmodningen quota. Anmodningens krop er tom.
Eksempel på svar på quota-anmodning
{
"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
Denne API blev udviklet tidligere end Threat Prevention API og er kun beregnet til lokale enheder. I øjeblikket kan den kun være nyttig, hvis du har brug for Threat Extraction API. For Threat Emulation er det bedre at bruge den almindelige Threat Prevention API. For at aktivere TP API for SG og konfigurere API-nøglen skal du følge trinene fra . Jeg anbefaler at være opmærksom på trin 6b og kontrollere tilgængeligheden af siden https:///UserCheck/TPAPI da et negativt svar ville gøre yderligere konfiguration meningsløs. Alle API-opkald vil blive sendt til denne URL. Opkaldenes type (upload/query) reguleres i nøglefeltet i opkaldet — request_name. De obligatoriske nøgler omfatter også — api_key (det er vigtigt at huske på i konfigurationen) og protocol_version (den nuværende version er 1.1). Den officielle dokumentation til denne API kan findes i . Nogle relative fordele inkluderer muligheden for at sende flere filer til emulering ved upload, da filerne sendes som en base64-tekststreng. For at kode/dekode filer til/fra base64 kan du bruge en online konverter i Postman til demonstrationsformål, for eksempel — . I praktiske formål skal du under kodning bruge de indbyggede metoder encode og decode.
Lad os nu se nærmere på funktionerne te og extraction i denne API.
For komponenten te er der et ordforråd te_options i upload/query-anmodningerne, og nøglerne i denne anmodning svarer fuldstændigt til nøglerne te i .
Eksempel på anmodning til emulering af en fil i Win10 med rapporter
{
"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"]
}
}
]
}For komponenten extraction er der et ordforråd scrub_optionsI denne anmodning angives rengøringsmetoden: konvertering til PDF, fjernelse af aktivt indhold eller at vælge tilstand i overensstemmelse med profilen for trusselbeskyttelse (navn på profilen angives). Et særkende ved svaret på API-anmodningen med extraction for filen er, at du modtager en rengjort kopi som svar på denne anmodning i form af en krypteret base64-streng (du behøver ikke at lave en forespørgsel og lede efter id for at downloade dokumentet)
Eksempel på anmodning om rengøring af fil
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Svar på anmodning
{
"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": "Fjern potentielt skadelig indhold",
"protection_type": "Konvertering til PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT-fil blev konverteret til PDF",
"scrub_method": "Konverter til PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Selvom færre API-anmodninger kræves for at få en rengjort kopi, anser jeg denne mulighed for mindre foretrukken og praktisk end anmodningen form-data, der anvendes i .
Postman-samlinger
Jeg har oprettet samlinger i Postman både for Threat Prevention API og for Threat Prevention API for Security Gateway, hvor de mest almindelige API-anmodninger er præsenteret. For at IP/URL API-serveren og nøglen kan indsættes automatisk i anmodningerne, og hash-summen sha256 gemmes efter upload af filen, er der oprettet tre variabler inden for samlingerne (de kan findes ved at gå til indstillingerne for samlingen Rediger -> Variabler): te_api (skal udfyldes), api_key (skal udfyldes, bortset fra tilfælde af brug af TP API med lokale enheder), sha256 (skal holdes tom, bruges ikke i TP API for SG).
Eksempler på brug
I fællesskabet er der præsenteret scripts skrevet i Python, der kontrollerer filer fra den ønskede mappe både gennem , og . Gennem interaktionen med Threat Prevention API udvides dine muligheder for filkontrol betydeligt, da du nu kan kontrollere filer på flere platforme samtidigt (interessant er kontrol i , og derefter i Check Point sandkassen), og filer kan ikke kun modtages fra netværkstrafik, men også hentes fra enhver netværksdisk og f.eks. CRM-systemer.
Kilde: habr.com
Russian
Italian
German
Polish
Estonian
Albanian
Bulgarian
Croatian
Czech
Danish
Dutch
English
French
Hungarian
Latvian
Norwegian
Portuguese
Romanian
Slovak
Slovenian
Spanish
Swedish