🥇 Koostoime Check Point SandBlastiga API kaudu

See artikkel on kasulik neile, kes on tuttavad tehnoloogiatega Check Point failide emuleerimise osas (Ohuhalduse simuleerimine) ja proaktiivse failide puhastamise osas (Threat Extraction) ja soovivad astuda sammu automatiseerimise poole. Check Point'il on Threat Prevention API, mis töötab nii pilves kui ka kohalikes seadmetes, ja funktsionaalselt on see identne failide kontrollimisega web/smtp/ftp/smb/nfs liikluses. See artikkel on osaliselt autori tõlgendus ametlikest dokumentatsiooni artiklitest, kuid põhineb oma kogemusel ja isiklikel näidistel. Samuti leiate artiklist autori Postman'i kogumid töötamiseks Threat Prevention API-ga.

Peamised akronüümid

Threat Prevention API töötab kolme peamise komponendi kaudu, mida API-s kutsutakse järgmiste tekstiväärtuste kaudu:

av — Anti-Virus komponent, mis vastutab tuntud ohtude signatuuride analüüsi eest.

%Kuupäev — Threat Emulation komponent, mis vastutab failide kontrollimise eest liivakastis ning annab otsuse pahatahtlik (malicious)/puhtalt (benign) pärast emulatsiooni.

extraction — Threat Extraction komponent, mis vastutab kontoritokumentide kiire konverteerimise eest ohutuks vormiks (mille käigus eemaldatakse kogu potentsiaalselt kahjulik sisu), et neid kiiresti edastada kasutajatele/süsteemidele.

API struktuur ja peamised piirangud

Threat Prevention API kasutab kokku 4 päringut — upload, query, download ja quota. Kõige nelja päringu päises tuleb edastada API võti, kasutades parameetrit Authorization. Esmapilgul võib struktuur tunduda oluliselt lihtsam kui Management API, kuid upload ja query päringute valdkondade ning nende päringute struktuur on üsna keerukad. Neid saab funktsionaalselt võrrelda Threat Prevention'i profiilidega kaitse- ja liivakasti poliitikas.

Praegu on välja antud ainus versioon Threat Prevention API-st — 1.0, API väljakutsete URL-is tuleb märkida v1 seal, kus tuleb osutada versioonile. Erinevalt Management API-st on API versiooni määramine URL-aadres, muidu päring ei toimi.

Anti-Virus komponent kutsumise korral ilma teiste komponentideta (te, extraction) toetab praegu ainult päringute tegemist md5 räsiväärtustega. Threat Emulation ja Threat Extraction toetavad ka sha1 ja sha256 räsiväärtusi.

Äärmiselt oluline on päringutes vigu mitte teha! Päring võib täituda ilma veata, kuid mitte täielikult. Kergelt ette hüpates vaatleme, mis võib juhtuda päringute vigade/veapõhjuste korral.

Päring vigaselt sõnas reports (reportss)

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                reportss: ["tar", "pdf", "xml"]
            }
		}
	] 
}

Veateates ei tule, kuid lisainfot aruannete kohta ei tule üldse.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "Päringule on täielikult vastatud."
      },
      "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": "Päringule on täielikult vastatud."
        }
      }
    }
  ]
}

Siin on päring ilma vigadeta võtmes reports.

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                reports: ["tar", "pdf", "xml"]
            }
		}
	] 
}

Saame vastuse, kus on juba olemasid aruannete allalaadimise jaoks.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "Päringule on täielikult vastatud."
      },
      "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": "Päringule on täielikult vastatud."
        }
      }
    }
  ]
}

Kui aga saadetakse vale/kehtetu API võti, saame vastuseks vea 403.

SandBlast API: pilves ja lokaalsetes seadmetes.

API päringuid saab saata Check Point seadmetele, millel on lubatud komponent (blade) Threat Emulation. Päringute jaoks tuleb kasutada seadme ip/url ja porti 18194 (nt — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию välja lülitatud ja Authorization võtit ei pea päringute päistes üldse saatma.

CheckPointi API päringud tuleb saata aadressile te.checkpoint.com (näiteks — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.

Kohandatud seadmetes ei toetata Threat Extraction funksiooni standardis, Threat Prevention API ja tuleb kasutada Threat Prevention API for Security Gateway (sellest räägime lähemalt artikli lõpus).

Kohandatud seadmed ei toeta kvota päringut.

Muus osas ei ole erinevusi kohandatud seadmete ja pilve päringute vahel.

Upload API kutsumise

Kasutatav meetod on — POST

Kutsumise aadress — https://<service_address>/tecloud/api/v1/file/upload

Päring koosneb kahest osast (form-data): fail, mis on mõeldud simuleerimiseks/puhtaks pesemiseks, ja päringu kehast tekstiga.

Tekstipäring ei tohi olla tühi, kuid see ei pea sisaldama mingit konfigureerimist. Et päring oleks edukas, peab minema vähemalt järgmine tekst:

Nõutav minimaalne upload päringule

HTTP POST

https://<service_address>/tecloud/api/v1/file/upload

Päised:

Authorization: <api_key>

Keha

{

"request": {

}

Fail

Sellisel juhul edastatakse fail töötlemiseks vastavalt vaikeseade parameetritele: komponent — %Kuupäev, OS pildid — Win XP ja Win 7, ilma aruande genereerimiseta.

Kommentaarid põhiväljade kohta tekstipäringus:

file_name ja file_type võib jätta tühjaks või üldse mitte saata, kuna see ei ole faili üleslaadimisel eriti kasulik teave. API vastuses täidetakse need väljad automaatselt üleslaadimise faili nime põhjal ja teavet vahemikus tuleb ikkagi otsida md5/sha1/sha256 hash summade järgi.

Näide päringust tühjade file_name ja file_type jaoks

{

"request": {

"file_name": "",

"file_type": "",

}

}

features — loetelu, kus näidatakse vajalik funktsionaalsus töötlemiseks liivakastis — av (anti viirus), te (ohtude simuleerimine), extraction (ohtude eemaldamine). Kui seda parameetrit üldse ei edastata, siis aktiveeritakse ainult vaikeseade komponent — te (ohtude simuleerimine).

Kolme saadaoleva komponendi kontrollimiseks tuleb need komponendid API päringusse märkida.

Näide päringust, kus kontroll on av, te ja extraction

{ "request": [  

		{	
			"sha256": {{sha256}},
			"features": ["av", "te", "extraction"]  
		}
	] 
}

Te lõikide võtmed te

images — loetelu, milles peavad olema sõnastikud id ja operatsioonisüsteemide revisjonide numbritega, kus kontroll toimub. ID ja revisjoni numbrid on kõikide kohandatud seadmete ja pilve jaoks samad.

Operatsioonisüsteemide ja revisjonide loetelu

Available OS Image ID

Revision

Image OS and Application

e50e99f3-5963-4573-af9e-e3f4750b55e2

Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 ja ActiveX 10.0
Java Runtime: 1.6.0u22

7e6fe36e-889e-4c25-8704-56378f0830df

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

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

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

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

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

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

Kui võtme images täielikult ei määra, toimub emulatsioon Check Point'i soovitatud piltidel (praegu Win XP ja Win 7). Need pildid on soovitatavad parima jõudluse ja catch rate'i tasakaalu põhjal.

aruanded — aruannete nimekiri, mida me küsime, juhuks kui fail osutub pahatahtlikuks. Saadaval on järgmised valikud:

kokkuvõte — .tar.gz arhiiv, mis sisaldab emulatsiooniaruannet kõik järelpäringu image'ide kohta (nii HTML-lehe kui ka selliste elementide nagu emulaatori opsüsteemi videoklipid, võrguühenduse dump, aruanne json, samuti proovi arhiiv parooliga kaitstuna). Vastuses otsime võtme — summary_report jääb aruanne allalaadimiseks.
pdf — emulatsioonidokument ühes image'is, mille paljuski on harjutud saama Smart Console'i kaudu. Vastuses otsime võtme — pdf_report jääb aruanne allalaadimiseks.
xml — emulatsioonidokument ühes image, mis on mugav edasiste parameetrite töötlemiseks aruandes. Vastuses otsime võtme — xml_report jääb aruanne allalaadimiseks.
tar — .tar.gz arhiiv, mis sisaldab emulatsiooniaruannet ühes järelpäringu image'ide kohta (nii HTML-lehe kui ka selliste elementide nagu emulaatori opsüsteemi videoklipid, võrguühenduse dump, aruanne json, samuti proovi arhiiv parooliga kaitstuna). Vastuses otsime võtme — full_report jääb aruanne allalaadimiseks.

Mida sisaldab kokkuvõtte aruanne

Võtmed full_report, pdf_report, xml_report on sõnaraamatus igale opsüsteemile

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "Päringule on täielikult vastatud."
      },
      "sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
      "file_type": "html",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "pahatahtlik",
              "full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
              "pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
              "xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
            },
            "status": "leitud",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          },
          {
            "report": {
              "verdict": "pahatahtlik",
              "full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
              "pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
              "xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
            },
            "status": "leitud",
            "id": "6c453c9b-20f7-471a-956c-3198a868dc92",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "pahatahtlik",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "Päringule on täielikult vastatud."
        }
      }
    }
  ]
}

Kuid võtme summary_report — on üks emulatsiooni kohta kokku.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "LEIDUD",
        "message": "Päringule on täielikult vastatud."
      },
      "sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
      "file_type": "exe",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "kuri",
              "full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
              "xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
            },
            "status": "leitud",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          },
          {
            "report": {
              "verdict": "kuri",
              "full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
              "xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
            },
            "status": "leitud",
            "id": "6c453c9b-20f7-471a-956c-3198a868dc92",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "kuri",
        "severity": 4,
        "confidence": 3,
        "summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
        "status": {
          "code": 1001,
          "label": "LEIDUD",
          "message": "Päringule on täielikult vastatud."
        }
      }
    }
  ]
}

Saate korraga küsida nii tar-, xml- kui ka pdf-aruandeid, samuti summary ning tar- ja xml-aruandeid. Korraga ei saa kokku kutsuda summary aruannet ja pdf-d.

Võtmed sektsioonis extraction

Threat extractioni jaoks kasutatakse ainult kahte võtit:

meetod — pdf (konverteerimine pdf-iks, kasutatakse vaikimisi) või clean (aktiivse sisu puhastamine).

extracted_parts_codes — nimekiri aktiivse sisu eemaldamiseks mõeldud koodidest, kehtib ainult meetodi clean puhul

Koodid sisu eemaldamiseks failidest

Kood

Kirjeldus

1025

Lingitud objektid

1026

Makrod ja kood

1034

Tundlikud hüperlingid

1137

PDF GoToR tegevused

1139

PDF Launch tegevused

1141

PDF URI tegevused

1142

PDF heli tegevused

1143

PDF filmi tegevused

1150

PDF JavaScript tegevused

1151

PDF vormi esitamise tegevused

1018

Andmebaasi päringud

1019

Sisekandjad

1021

Kiire salvestamise andmed

1017

Kohandatud omadused

1036

Statistika omadused

1037

Kokkuvõtte omadused

Puhastatud koopia allalaadimiseks tuleb esitada ka päring (sellest räägitakse hiljem) mõne sekundi jooksul, märkides faili hash-summa ja komponente extraction päringu tekstis. Puhastatud faili saab alla laadida päringu vastuses olevale id-le — extracted_file_download_id. Veel kord, pisut edasi vaadates, toon välja päringu ja päringu vastuse näited id-le puhasdokumendi allalaadimise otsimiseks.

Päring query extracted_file_download_id leidmiseks

{ "request":  [  

		{	
			"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
			"features": ["extraction"] , 
			"extraction": {
		        "method": "pdf"
            }
		}
	] 
}

Päringu vastus (otsige võtme extracted_file_download_id)

{
    "response": [
        {
            "status": {
                "code": 1001,
                "label": "LEIDUD",
                "message": "Taotlus on täielikult vastatud."
            },
            "sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
            "file_type": "",
            "file_name": "",
            "features": [
                "väljavõte"
            ],
            "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": "Makrod ja Kood",
                "extraction_data": {
                    "input_extension": "xls",
                    "input_real_extension": "xls",
                    "message": "OK",
                    "output_file_name": "kp-20-xls.cleaned.xls.pdf",
                    "protection_name": "Potentsiaalne pahatahtlik sisu tõmmatud",
                    "protection_type": "PDF-ks muundamine",
                    "protocol_version": "1.0",
                    "risk": 5.0,
                    "scrub_activity": "Aktivne sisu leiti - XLS-fail muundati PDF-ks",
                    "scrub_method": "Muunda PDF-ks",
                    "scrub_result": 0.0,
                    "scrub_time": "0.013",
                    "scrubbed_content": "Makrod ja Kood"
                },
                "tex_product": false,
                "status": {
                    "code": 1001,
                    "label": "LEIDUD",
                    "message": "Taotlus on täielikult vastatud."
                }
            }
        }
    ]
}

Ülevaade

Ühes API kutse andmes saab kontrollimiseks saata ainult ühe faili.

Komponent av ei vaja täiendavat jaotust võtmete jaoks, piisab selle määramisest sõnastikus. features.

Query API kutse.

Kasutatav meetod on — POST

Kutsumise aadress — https://<service_address>/tecloud/api/v1/file/query

Enne faili üleslaadimise saatmist (upload taotlus) on soovitatav kontrollida liivakasti vahemälu (query taotlus) API serveri koormuse optimeerimise eesmärgil, kuna API serveris võib olema juba teave ja otsus üleslaadatava faili kohta. Kutse koosneb ainult tekstiosast. Taotluse kohustuslik osa on sha1/sha256/md5 hash faili summa. Selle saab muide vastuses upload kutsele.

Kohustuslik minimaalne query kutse jaoks.

HTTP POST

https://<service_address>/tecloud/api/v1/file/query

Päised:

Authorization: <api_key>

Keha

{

"request": {

«sha256»: <sha256 hash sum>

}

Näide upload kutse vastusest, kus on nähtavad sha1/md5/sha256 hash summad.

{
  "response": {
    "status": {
      "code": 1002,
      "label": "UPLOAD_SUCCESS",
      "message": "Fail laaditi edukalt üles."
    },
    "sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
    "md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
    "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
    "file_type": "",
    "file_name": "kp-20-doc.doc",
    "features": [
      "te"
    ],
    "te": {
      "trust": 0,
      "images": [
        {
          "report": {
            "verdict": "tundmatu"
          },
          "status": "not_found",
          "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
          "revision": 1
        }
      ],
      "score": -2147483648,
      "status": {
        "code": 1002,
        "label": "UPLOAD_SUCCESS",
        "message": "Fail laaditi edukalt üles."
      }
    }
  }
}

Query päring peaks ideaalis olema sama, nagu oli (või plaanitakse olla) upload päring, või isegi "juba" (sisaldama päringus query vähem välju kui päringus upload). Kui päringus query on rohkem välju kui oli päringus upload, siis te saate vastuses mitte kogu vajaliku teabe.

Siin on näide query päringu vastusest, kus ei leitud kõiki vajalikke andmeid.

{
  "response": [
    {
      "status": {
        "code": 1006,
        "label": "PARTIALLY_FOUND",
        "message": "Päringut ei saa sel hetkel täielikult vastata."
      },
      "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": "Päringule on täielikult vastatud."
        }
      },
      "extraction": {
        "method": "pdf",
        "tex_product": false,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Soovitud faili ei leitud. Palun laadige see üles."
        }
      }
    }
  ]
}

Pange tähele välju. code ja label. Need väljad esinevad kolmel korral status sõnastikes. Alguses näeme globaalse võtmena "code": 1006 ja "label": "PARTIALLY_FOUND". Seejärel esinevad need võtmed iga eraldiseisva komponendi, mida soovisime — te ja extraction. Kui te puhul on selge, et andmed on leitud, siis extraction'i puhul puudub info.

Nii nägi välja query päring eespool toodud näites.

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te", "extraction"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                "reports": [
                    "xml", "pdf"
                ]
            }
		}
	] 
}

Kui saatate query päringu ilma extraction komponendita.

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                "reports": [
                    "xml", "pdf"
                ]
            }
		}
	] 
}

Siis on ka vastuses täielik teave ("code": 1001, "label": "FOUND").

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "Taotlusele on vastatud täielikult."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
      "file_type": "doc",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "kahjulik",
              "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": "kahjulik",
        "severity": 4,
        "confidence": 1,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "Taotlusele on vastatud täielikult."
        }
      }
    }
  ]
}

Kui vaikes ei ole üldse mingit teavet, siis vastuses on "label": "NOT_FOUND"

{
  "response": [
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Külastatud faili ei leitud. Palun Laadige see üles."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "tundmatu"
            },
            "status": "not_found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Külastatud faili ei leitud. Palun Laadige see üles."
        }
      }
    }
  ]
}

Ühes API-kutses saab korraga saata mitu häššsummat kontrollimiseks. Vastuses tagastatakse andmed samas järjekorras, nagu need saadeti päringus.

Näidis päring query mitmete sha256 häššsummadega

{ "request":  [  

		{	
			"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
        },
        		{	
			"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
        }
	] 
}

Vastus päringule query mitmete sha256 häššsummadega

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "LEIDUD",
        "message": "Päringule on täielikult vastatud."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
      "file_type": "dll",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "kahjulik"
            },
            "status": "leitud",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "kahjulik",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "LEIDUD",
          "message": "Päringule on täielikult vastatud."
        }
      }
    },
    {
      "status": {
        "code": 1004,
        "label": "LEIDMATU",
        "message": "Tähtsustatud faili ei leitud. Palun laadige see üles."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "tundmatu"
            },
            "status": "leidmata",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "LEIDMATU",
          "message": "Tähtsustatud faili ei leitud. Palun laadige see üles."
        }
      }
    }
  ]
}

Mitme hash'i summade päring serveri API töö efektiivsusele mõjub positiivselt.

Download API väljakutse

Kasutatav meetod on — POST (vastavalt dokumentatsioonile), GET töötavad samuti (ja võivad tunduda loogilisemad)

Kutsumise aadress — https://<service_address>/tecloud/api/v1/file/download?id=<id>

Pealkirjas tuleb edastada API võti, päringu keha on tühi, id laadimise jaoks edastatakse URL-aadressis.

Päringu vastus näitab, kui emulatsioon on lõpetatud ja faili laadimisel on nõutud aruanded, laadimisid. Kui nõutakse puhastatud koopiat, tuleb otsida puhastatud dokumendi laadimise id-d.

Seega, päringu vastuses olevad id laadimiseks võivad olla:

summary_report
full_report
pdf_report
xml_report
extracted_file_download_id

Muidugi, et päringu vastuses oleksid need võtmed, tuleb need päringus märkida (aruannete jaoks) või mitte unustada teha päring väljavõtte funktsiooni kaudu (puhastatud dokumentide jaoks)

Quota API väljakutse

Kasutatav meetod on — POST

Kutsumise aadress — https://<service_address>/tecloud/api/v1/file/quota

Pilves olevate jäänud kvootide kontrollimiseks kasutatakse päringut quota. Päringu keha on tühi.

Näide vastusest päringule quota

{
  "response": [
    {
      "remain_quota_hour": 1250,
      "remain_quota_month": 10000000,
      "assigned_quota_hour": 1250,
      "assigned_quota_month": 10000000,
      "hourly_quota_next_reset": "1599141600",
      "monthly_quota_next_reset": "1601510400",
      "quota_id": "TEST",
      "cloud_monthly_quota_period_start": "1421712300",
      "cloud_monthly_quota_usage_for_this_gw": 0,
      "cloud_hourly_quota_usage_for_this_gw": 0,
      "cloud_monthly_quota_usage_for_quota_id": 0,
      "cloud_hourly_quota_usage_for_quota_id": 0,
      "monthly_exceeded_quota": 0,
      "hourly_exceeded_quota": 0,
      "cloud_quota_max_allow_to_exceed_percentage": 1000,
      "pod_time_gmt": "1599138715",
      "quota_expiration": "0",
      "action": "ALLOW"
    }
  ]
}

Threat Prevention API for Security Gateway

See API on arenduses on Threat Prevention API ja on mõeldud ainult kohalikeks seadmeteks. Hetkel on see kasulik, ainult juhul, kui vajate Threat Extraction API. Threat Emulation jaoks on parem kasutada tavalist Threat Prevention API. Et lubada TP API for SG ja configureerima API võtme jaoks peate tegema järgmist sk113599. Soovitan tähelepanu pöörata sammule 6b ja kontrollida lehe kättesaadavust https:///UserCheck/TPAPI , kuna negatiivse tulemuse korral pole edasine konfiguratsioon mõttekas. Kõik API kutsed saadetakse sellele URL-ile. Kutsumise tüüp (upload/query) reguleeritakse kõnekäigu keha võtmes — request_name. Samuti on kohustuslikud võti — api_key (peate selle konfiguratsiooni ajal meeles pidama) ja protocol_version (hetkel on aktuaalne versioon 1.1). Selle API ametlikku dokumentatsiooni leiate sk137032. Suhete eeliste hulka kuulub võimalus saata samaaegselt mitmeid faile emuleerimiseks nende üleslaadimise ajal, kuna failid saadetakse tekstirea base64 kujul. Failide kodeerimiseks/dekodeerimiseks base64-sse võite kasutada näidisena Postmanis veebikonverterit, näiteks — https://base64.guru. Praktilistes olukordades koodi kirjutamisel tuleks kasutada sisseehitatud meetodeid encode ja decode.

Nüüd vaatame lähemalt funktsioone %Kuupäev ja extraction selles API-s.

Komponendi jaoks %Kuupäev on ette nähtud sõnastik te_options ülesandeid upload/query, ning võtmed selles ülesandes vastavad täielikult te võtmetele Threat Prevention API.

Näidiste ülesande lähtefaili emuleerimise jaoks Win10-s koos aruannetega

{
"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"]
    }
    }
    ]
}

Komponendi jaoks extraction on ette nähtud sõnastik scrub_optionsSelles päringus määratakse puhastusmeetod: konverteerimine PDF-ks, aktiivsete sisu eemaldamine või režiimi valimine Threat Prevention profiili järgi (profiili nimi tuleb ära märkida). API päringus failide eemaldamise vastuse eripära on see, et saate vastuseks selle päringu korral puhastatud koopia, mis on esitatud šifreeritud base64 stringina (te ei pea tegema query päringut ega otsima dokumenti ID-d üleslaadimiseks).

Puhastusfaili päringu näide

    {
	"request": [{
		"protocol_version": "1.1",
		"api_key": "",
		"request_name": "UploadFile",
		"file_enc_data": "",
		"file_orig_name": "hi.txt",
		"scrub_options": {
			"scrub_method": 2
		}
	}]
}

Päringule vastamine

{
	"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": "Eemalda potentsiaalselt kahjulik sisu",
			"protection_type": "Konverteerimine PDF-ks",
			"real_extension": "txt",
			"risk": 0,
			"scrub_activity": "TXT-fail konverteeriti PDF-ks",
			"scrub_method": "Konverteerimine PDF-ks",
			"scrub_result": 0,
			"scrub_time": "0.011",
			"scrubbed_content": ""
		}
	}]
}

Kuigi puhastatud koopia saamiseks on vajalik vähem API päringuid, arvan ma, et selline valik on vähem soovitatav ja mugav võrreldes form-data päringuga, mida kasutatakse Threat Prevention API.

Postmani kogud

Olen loonud kogud Postmanis nii Threat Prevention API jaoks kui ka Threat Prevention API for Security Gateway jaoks, kus on esitatud kõige levinumad API päringud. Selleks, et IP / URL API server ja võtmed oleksid päringutes automaatselt sisestatud ning faili üleslaadimise järel sha256 hash summat ka meeles peetaks, on kogudes loodud kolm muutujat (need leiad, minnes kogude seadistustes Edit -> Variables): te_api (täitmine vajalik), api_key (täitmine vajalik, välja arvatud juhul, kui kasutatakse TP API-d kohalike seadmetega), sha256 (jätke tühi, ei kasutata TP API for SG).

Laadi alla Postmani kogu Threat Prevention API jaoks

Laadi alla Postmani kogu Threat Prevention for Security Gateway API jaoks

Kasutamise näited

Kogukonnas Check Mates on esitatud Pythonis kirjutatud skriptid, mis kontrollivad faile soovitud kaustast läbi TP API, kui ka TP API for SG. Koostöös Threat Prevention API-ga on teie failide kontrollimise võimalused oluliselt laienenud, kuna nüüd saate faile kontrollida mitmetes platvormides (huvitav on kontrollimine VirusTotal API, ja seejärel Check Point liivakastis), ning faile saab hankida mitte ainult võrgu liiklusest, vaid ka igasugustelt võrgu ketastelt ja näiteks CRM süsteemidest.

Allikas: habr.com