ProHoster > Blogs > Administrācija > Saziņa ar Check Point SandBlast, izmantojot API

Saziņa ar Check Point SandBlast, izmantojot API

Saziņa ar Check Point SandBlast, izmantojot API

Å is raksts bÅ«s noderÄ«gs tiem, kas ir iepazinuÅ”ies ar tehnoloÄ£ijām Check Point par failu emulāciju (Threat Emulation) un proaktÄ«vo failu tÄ«rÄ«Å”anu (Threat Extraction) un vēlas veikt soli uz automatizāciju Å”ajās jomās. Check Point piedāvā Threat Prevention API, kas darbojas gan mākoņos, gan uz vietējiem ierÄ«cēm, un funkcionāli tas ir identisks failu pārbaudei web/smtp/ftp/smb/nfs plÅ«smās. Å is raksts daļēji ir autora interpretācija oficiālās dokumentācijas rakstu kopumam, taču balstās uz personÄ«go pieredzi un piemēriem. Rakstā jÅ«s atradÄ«siet arÄ« autora Postman kolekcijas darbam ar Threat Prevention API.

Galvenās saīsinājumi

Threat Prevention API darbojas ar trim galvenajiem komponentiem, kuri API tiek izsaukti ar Ŕādiem tekstu vērtÄ«bām:

av ā€” Anti-Virus komponenta, kas atbild par parakstu analÄ«zi pazÄ«stamām draudiem.

te ā€” Threat Emulation komponenta, kas atbild par failu pārbaudi smiltÄ«s un lēmuma pieņemÅ”anu, vai failus var uzskatÄ«t par ļaunprātÄ«giem (malicious)/tÄ«riem (benign) pēc emulācijas.

extraction ā€” Threat Extraction komponenta, kas atbild par ātru biroja dokumentu konvertÄ“Å”anu droŔā formā (no kurām tiek izņemts viss potenciāli kaitÄ«gais saturs), lai to ātri varētu piegādāt lietotājiem/sistēmām.

API struktūra un galvenie ierobežojumi

Threat Prevention API izmanto tikai 4 pieprasÄ«jumus ā€” upload, query, download un quota. Visos četros pieprasÄ«jumos ir jānodroÅ”ina API atslēga, izmantojot parametru Authorization. Pirmā mirkļa iespaidā struktÅ«ra var Ŕķist daudz vienkārŔāka nekā Management API, taču lauku skaits pieprasÄ«jumos upload un query, kā arÄ« Å”o pieprasÄ«jumu struktÅ«ra ir pietiekami sarežģīta. Tos var funkcionāli salÄ«dzināt ar Threat Prevention profiliem droŔības politikas ietvaros/gasÅ«lēs.

PaÅ”laik ir izlaista tikai viena Threat Prevention API versija ā€” 1.0, un URL API izsaukumiem jānorāda v1 tajā daļā, kur vajadzÄ«gs norādÄ«t versiju. AtŔķirÄ«bā no Management API, versiju API URL obligāti jānorāda, citādi pieprasÄ«jums netiks veikts.

Anti-Virus komponents, izsaucot bez citiem komponentiem (te, extraction), Ŕobrīd atbalsta tikai query pieprasījumus ar md5 hash summām. Threat Emulation un Threat Extraction atbalsta arī sha1 un sha256 hash summas.

Ir ļoti svarÄ«gi neizdarÄ«t kļūdas pieprasÄ«jumos! PieprasÄ«jums var tikt izpildÄ«ts bez kļūdām, bet ne pilnÄ«bā. Nedaudz ieskicējot, aplÅ«kosim, kas notiek pie kļūdām/printÄ“Å”anas kļūdām pieprasÄ«jumos.

Pieprasījums ar drukas kļūdu vārdā reports(reportss)

{ "request":  [  

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

Atbildē kļūdu nebūs, bet informācija par ziņojumiem vispār nebūs

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "ATRASTS",
        "message": "Pieprasījums ir pilnībā atbildēts."
      },
      "sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
      "file_type": "pdf",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "ļaunprātīgs"
            },
            "status": "atrodams",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "ļaunprātīgs",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "ATRASTS",
          "message": "Pieprasījums ir pilnībā atbildēts."
        }
      }
    }
  ]
}

Un Å”eit ir pieprasÄ«jums bez kļūdas atslēgas vārdā reports

{ "request":  [  

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

Mēs saņemam atbildi, kurā jau ir iekļauti id ziņojumu lejupielādei

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "ATRASTS",
        "message": "Pieprasījums ir pilnībā atbildēts."
      },
      "sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
      "file_type": "pdf",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "ļaunprātīgs",
              "full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
              "pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
              "xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
            },
            "status": "atrodams",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "ļaunprātīgs",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "ATRASTS",
          "message": "Pieprasījums ir pilnībā atbildēts."
        }
      }
    }
  ]
}

Ja nosūtīsiet nepareizu/novēloti API atslēgu, atbildē saņemsim kļūdu 403.

SandBlast API: mākoņos un lokālajās ierīcēs

API pieprasÄ«jumus var nosÅ«tÄ«t uz Check Point ierÄ«cēm, kurās ir aktivizēts Threat Emulation komponents (blade). Kā adresi pieprasÄ«jumiem jāizmanto ierÄ«ces ip/url un ports 18194 (piemēram ā€” https://10.10.57.19:18194/tecloud/api/v1/file/query). Š¢Š°ŠŗŠ¶Šµ сŠ»ŠµŠ“уŠµŃ‚ уŠ±ŠµŠ“Šøться Š² тŠ¾Š¼, чтŠ¾ ŠæŠ¾Š»ŠøтŠøŠŗŠ¾Š¹ Š±ŠµŠ·Š¾ŠæŠ°ŃŠ½Š¾ŃŃ‚Šø Š½Š° устрŠ¾Š¹ŃŃ‚Š²Šµ рŠ°Š·Ń€ŠµŃˆŠµŠ½Š¾ тŠ°ŠŗŠ¾Šµ ŠæŠ¾Š“ŠŗŠ»ŃŽŃ‡ŠµŠ½ŠøŠµ. ŠŠ²Ń‚Š¾Ń€ŠøŠ·Š°Ń†Šøя чŠµŃ€ŠµŠ· API ŠŗŠ»ŃŽŃ‡ Š½Š° Š»Š¾ŠŗŠ°Š»ŃŒŠ½Ń‹Ń… устрŠ¾Š¹ŃŃ‚Š²Š°Ń… ŠæŠ¾ уŠ¼Š¾Š»Ń‡Š°Š½Šøю izslēgts un Authorization atslēgu var nepildÄ«t vispār pie pieprasÄ«jumu galviņām.

API pieprasÄ«jumus CheckPoint mākoņa vajadzÄ«bām jānosÅ«ta uz adresi te.checkpoint.com (piemēram ā€” https://te.checkpoint.com/tecloud/api/v1/file/query). API ŠŗŠ»ŃŽŃ‡ Š¼Š¾Š¶Š½Š¾ ŠæŠ¾Š»ŃƒŃ‡Šøть Š² Š²ŠøŠ“Šµ трŠøŠ°Š»ŃŒŠ½Š¾Š¹ Š»ŠøцŠµŠ½Š·ŠøŠø Š½Š° 60 Š“Š½ŠµŠ¹, Š¾Š±Ń€Š°Ń‚ŠøŠ²ŃˆŠøсь Šŗ ŠæŠ°Ń€Ń‚Š½ŠµŃ€Š°Š¼ Check Point ŠøŠ»Šø Š² Š»Š¾ŠŗŠ°Š»ŃŒŠ½Ń‹Š¹ Š¾Ń„Šøс ŠŗŠ¾Š¼ŠæŠ°Š½ŠøŠø.

Lokalizētajos ierīcēs Threat Extraction pagaidām netiek atbalstīts standarta Threat Prevention API un jāizmanto Threat Prevention API for Security Gateway (par to runāsim sīkāk raksta beigās).

Lokalizētās ierīces neatbalsta quota pieprasījumus.

Pārējā ziņā atŔķirÄ«bu starp pieprasÄ«jumiem uz lokalizētām ierÄ«cēm un mākoņa nav.

Upload API izsaukums

Izmantojamā metode ā€” POST

Izsaukuma adrese ā€” https://<service_address>/tecloud/api/v1/file/upload

PieprasÄ«jums sastāv no divām daļām (form-data): faila, kas paredzēts emulÄ“Å”anai/izsistÄ«Å”anai, un pieprasÄ«juma Ä·ermeņa ar tekstu.

Teksta pieprasÄ«jums nedrÄ«kst bÅ«t tukÅ”s, bet tas var nesaturēt nekādu konfigurāciju. Lai pieprasÄ«jums bÅ«tu veiksmÄ«gs, jānosÅ«ta vismaz Ŕāds teksts pieprasÄ«jumā:

NepiecieŔamais minimums upload pieprasījumam

HTTP POST

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

Galvenes:

Authorization: <api_key>

Ķermenis

{

Ā«requestĀ»: {

}

}

Fails

Fails

Å ajā gadÄ«jumā fails tiks apstrādāts atbilstoÅ”i noklusējuma parametriem: komponents ā€” te, operētājsistēmu attēli ā€” Win XP un Win 7, bez ziņojumu Ä£enerÄ“Å”anas.

Piezīmes par galvenajiem laukiem tekstā pieprasījumā:

file_name un file_type var atstāt tukÅ”us vai vispār nesÅ«tÄ«t, jo Ŕī informācija nav Ä«paÅ”i noderÄ«ga faila augÅ”upielādē. API atbildē Å”ie lauki tiks automātiski aizpildÄ«ti, pamatojoties uz augÅ”upielādētā faila nosaukumu, un informācija keÅ”atmiņā tomēr bÅ«s jāmeklē pēc md5/sha1/sha256 hash summām.

Piemērs pieprasÄ«jumam ar tukÅ”iem file_name un file_type

{

"request": {

"file_name": "",

"file_type": "",

}

}

features ā€” saraksts, kurā norādÄ«ts nepiecieÅ”amais funkcionalitāte apstrādē smiltÄ«s ā€” av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Ja Å”o parametru vispār nenodot, tiks izmantots tikai noklusējuma komponents ā€” te (Threat Emulation).

Lai ieslēgtu pārbaudi trÄ«s pieejamos komponentos, nepiecieÅ”ams norādÄ«t Å”os komponentus API pieprasÄ«jumā.

Piemērs pieprasījumam ar pārbaudi av, te un extraction

{ "request": [  

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

Atslēgas sadaļā te

images ā€” saraksts, kurā jāiekļauj vārdnÄ«cas ar id un versijas numuru operētājsistēmām, kurās tiks veikta pārbaude. ID un versijas numuri ir vienādi visām lokalizētām ierÄ«cēm un mākoņiem.

Operētājsistēmu un versiju saraksts

Available OS Image ID

Revision

Image OS and Application

e50e99f3-5963-4573-af9e-e3f4750b55e2

1

Microsoft Windows: XP ā€” 32bit SP3
Birojs: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash PlayerĀ 9r115 unĀ ActiveXĀ 10.0
Java Runtime:Ā 1.6.0u22

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

1

Microsoft Windows: 7 ā€” 32biti
Birojs: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player:Ā 10.2r152 (PaplaÅ”inājums&Ā ActiveX)
Java Runtime:Ā 1.6.0u0

8d188031-1010-4466-828b-0cd13d4303ff

1

Microsoft Windows: 7 ā€” 32biti
Birojs: 2010
Adobe Acrobat Reader: 9.4
Flash Player:Ā 11.0.1.152 (PaplaÅ”inājumsĀ &Ā ActiveX)
Java Runtime:Ā 1.7.0u0

5e5de275-a103-4f67-b55b-47532918fa59

1

Microsoft Windows: 7 ā€” 32biti
Birojs: 2013
Adobe Acrobat Reader: 11.0
Flash Player:Ā 15 (PaplaÅ”inājumsĀ &Ā ActiveX)
Java Runtime:Ā 1.7.0u9

3ff3ddae-e7fd-4969-818c-d5f1a2be336d

1

Microsoft Windows: 7 ā€” 64biti
Birojs: 2013 (32biti)
Adobe Acrobat Reader: 11.0.01
Flash Player:Ā 13 (PaplaÅ”inājumsĀ &Ā ActiveX)
Java Runtime:Ā 1.7.0u9

6c453c9b-20f7-471a-956c-3198a868dc92Ā 

Ā 

1Ā 

Microsoft Windows: 8.1 ā€” 64biti
Birojs: 2013 (64biti)
Adobe Acrobat Reader: 11.0.10
Flash Player:Ā 18.0.0.160 (PaplaÅ”inājumsĀ &Ā ActiveX)
Java Runtime:Ā 1.7.0u9

10b4a9c6-e414-425c-ae8b-fe4dd7b25244Ā 

Ā 

1

Microsoft Windows: 10
Birojs: Professional Plus 2016 en-usĀ Ā 
Adobe Acrobat Reader: DC 2015 MUI
Flash Player:Ā 20 (PaplaÅ”inājumsĀ &Ā ActiveX)
Java Runtime:Ā 1.7.0u9

Ja atslēga images netiek norādÄ«ta, emulācija notiks, izmantojot Check Point ieteiktos attēlus (paÅ”laik tie ir Win XP un Win 7). Å ie attēli ir ieteikti, ņemot vērā labāko veiktspējas un catch rate lÄ«dzsvaru.

pārskati ā€” saraksts ar pārskatiem, kurus mēs pieprasām, ja fails izrādās kaitÄ«gs. Pieejami Ŕādi varianti:

  1. kopsavilkums ā€” .tar.gz arhÄ«vs, kas satur emulācijas pārskatu par visiem pieprasÄ«tajiem attēliem (kā html lapa, kā arÄ« tādi komponenti kā video no emulators, tÄ«kla trafika dumps, pārskats json formātā, kā arÄ« pats paraugs arhÄ«vā ar paroli aizsargāts). Atbildē meklējam atslēgu ā€” summary_report lai turpmāk lejupielādētu pārskatu.

  2. pdf ā€” emulācijas dokuments vienā attēlā, ko daudzi ir pieraduÅ”i saņemt caur Smart Console. Atbildē meklējam atslēgu ā€” pdf_report lai turpmāk lejupielādētu pārskatu.

  3. xml ā€” emulācijas dokuments vienā attēls, ērts turpmākai parametru parsÄ“Å”anai pārskatā. Atbildē meklējam atslēgu ā€” xml_report lai turpmāk lejupielādētu pārskatu.

  4. tar ā€” .tar.gz arhÄ«vs, kas satur emulācijas pārskatu par vienā pieprasÄ«tajiem attēliem (kā html lapa, kā arÄ« tādi komponenti kā video no emulators, tÄ«kla trafika dumps, pārskats json formātā, kā arÄ« pats paraugs arhÄ«vā ar paroli aizsargāts). Atbildē meklējam atslēgu ā€” full_report lai turpmāk lejupielādētu pārskatu.

Kas iekļauts kopsavilkuma pārskatāSaziņa ar Check Point SandBlast, izmantojot API

Atslēgas full_report, pdf_report, xml_report ir vārdnīcā katrai OS

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "ATRADĀS",
        "message": "Pieprasījums ir pilnībā atbildēts."
      },
      "sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
      "file_type": "html",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "kaitīgs",
              "full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
              "pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
              "xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
            },
            "status": "atrasts",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          },
          {
            "report": {
              "verdict": "kaitīgs",
              "full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
              "pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
              "xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
            },
            "status": "atrasts",
            "id": "6c453c9b-20f7-471a-956c-3198a868dc92",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "kaitīgs",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "ATRADĀS",
          "message": "Pieprasījums ir pilnībā atbildēts."
        }
      }
    }
  ]
}

Šeit atslēga summary_report ir viena visai emulācijai

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

Vienlaikus var pieprasīt tar, xml un pdf ziņojumus, kā arī var pieprasīt kopsavilkumu un tar un xml. Kopsavilkumu un pdf vienlaikus nevar pieprasīt.

Atslēgas seksijā extraction

Tāpat draudu izņēmumam izmanto tikai divas atslēgas:

metode ā€” pdf (konversija uz pdf, tiek izmantots noklusējumā) vai clean (aktÄ«vā satura attÄ«rÄ«Å”ana).

izņemto_daļu_kodi ā€” aktÄ«vā satura dzÄ“Å”anas kodi, attiecas tikai uz metodi clean

Kodi satura noņemÅ”anai no failiem

Kods

Apraksts

1025

Saistītie objekti

1026

Makros un kods

1034

Jutīgi hiperlinki

1137

PDF GoToR darbības

1139

PDF Launch darbības

1141

PDF URI darbības

1142

PDF skaņas darbības

1143

PDF filmas darbības

1150

PDF JavaScript darbības

1151

PDF formas nosūtīŔanas darbības

1018

Datubāzes vaicājumi

1019

Iegultie objekti

1021

Ātrā saglabāŔanas dati

1017

Pielāgotās īpaŔības

1036

Statistikas īpaŔības

1037

Kopsavilkuma īpaŔības

Lai lejupielādētu attÄ«rÄ«tu kopiju, bÅ«s jādara vēl viens vaicājums (par to tiks runāts tālāk) pēc dažām sekundēm, norādot faila hash summu un komponentu extraction tekstā. AttÄ«rÄ«tu failu varēs lejupielādēt, izmantojot id no atbildes uz vaicājumu ā€” extracted_file_download_id. Vēlreiz, nedaudz iepriekÅ” iepriekÅ” norādot, sniedzu vaicājuma un atbildes piemērus, lai atrastu id attÄ«rÄ«tā dokumenta lejupielādei.

Vaicājums query, lai atrastu atslēgu extracted_file_download_id

{ "request":  [  

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

Atbilde uz vaicājumu query (atrodiet atslēgu extracted_file_download_id)

{
    "response": [
        {
            "status": {
                "code": 1001,
                "label": "ATRADĀS",
                "message": "Pieprasījums ir pilnībā apstrādāts."
            },
            "sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
            "file_type": "",
            "file_name": "",
            "features": [
                "izvilkŔana"
            ],
            "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": "Makro un kods",
                "extraction_data": {
                    "input_extension": "xls",
                    "input_real_extension": "xls",
                    "message": "Labi",
                    "output_file_name": "kp-20-xls.cleaned.xls.pdf",
                    "protection_name": "Iespējams ļaunprātīgs saturs izvilkts",
                    "protection_type": "Konversija uz PDF",
                    "protocol_version": "1.0",
                    "risk": 5.0,
                    "scrub_activity": "Atrasta aktīvā satura - XLS fails tika konvertēts uz PDF",
                    "scrub_method": "Konvertēt uz PDF",
                    "scrub_result": 0.0,
                    "scrub_time": "0.013",
                    "scrubbed_content": "Makro un kods"
                },
                "tex_product": false,
                "status": {
                    "code": 1001,
                    "label": "ATRADĀS",
                    "message": "Pieprasījums ir pilnībā apstrādāts."
                }
            }
        }
    ]
}

Vispārīga informācija

Viena API izsaukuma ietvaros var nosūtīt tikai vienu failu pārbaudei.

Komponentam av nav nepiecieÅ”ams papildu atslēgu sekcijas, pietiek to norādÄ«t vārdnÄ«cā features.

Query API izsaukums

Izmantojamā metode ā€” POST

Izsaukuma adrese ā€” https://<service_address>/tecloud/api/v1/file/query

Pirms sÅ«tÄ«t failu augÅ”upielādei (augÅ”upielādes pieprasÄ«jums), vēlams veikt smilÅ”u kastes keÅ”a pārbaudi (query pieprasÄ«jums), lai optimizētu slodzi uz API serveri, jo iespējams, ka API serverÄ« jau ir informācija un slēdzi par augÅ”upielādējamo failu. Izsaukums sastāv tikai no teksta daļas. Obligātā pieprasÄ«juma daļa ir sha1/sha256/md5 hash summa failam. Tās vērtÄ«bu var saņemt atbildē uz augÅ”upielādes pieprasÄ«jumu.

Minimālais nepiecieŔamais pieprasījums par query

HTTP POST

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

Galvenes:

Authorization: <api_key>

Ķermenis

{

Ā«requestĀ»: {

Ā«sha256Ā»: <sha256 hash sum>

}

}

AugÅ”upielādes pieprasÄ«juma atbildes piemērs, kurā redzamas sha1/md5/sha256 hash summas

{
  "response": {
    "status": {
      "code": 1002,
      "label": "UPLOAD_SUCCESS",
      "message": "Fails tika veiksmÄ«gi augÅ”upielādēts."
    },
    "sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
    "md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
    "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
    "file_type": "",
    "file_name": "kp-20-doc.doc",
    "features": [
      "te"
    ],
    "te": {
      "trust": 0,
      "images": [
        {
          "report": {
            "verdict": "nezināms"
          },
          "status": "nav atrasts",
          "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
          "revision": 1
        }
      ],
      "score": -2147483648,
      "status": {
        "code": 1002,
        "label": "UPLOAD_SUCCESS",
        "message": "Fails tika veiksmÄ«gi augÅ”upielādēts."
      }
    }
  }
}

Query pieprasÄ«jumam, izņemot hash summu, ideālā gadÄ«jumā jābÅ«t tādam paÅ”am kā upload pieprasÄ«jumam (vai tas ir plānots), vai pat "jau" (tā jāietver query pieprasÄ«jumā mazāk lauku nekā upload pieprasÄ«jumā). GadÄ«jumā, ja query pieprasÄ«jumā ir vairāk lauku nekā upload pieprasÄ«jumā, jÅ«s saņemsiet atbildi bez visiem nepiecieÅ”amajiem datiem.

Å eit ir piemērs atbildei uz query pieprasÄ«jumu, kurā nebija atrasti visi nepiecieÅ”amie dati.

{
  "response": [
    {
      "status": {
        "code": 1006,
        "label": "PARTIALLY_FOUND",
        "message": "Pieprasījumu Ŕobrīd nevar pilnībā apstrādāt."
      },
      "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": "Pieprasījumu ir pilnībā apstrādāts."
        }
      },
      "extraction": {
        "method": "pdf",
        "tex_product": false,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Neatrada pieprasÄ«to failu. LÅ«dzu, augÅ”upielādējiet to."
        }
      }
    }
  ]
}

LÅ«dzu, pievērsiet uzmanÄ«bu pieprasÄ«juma laukiem. code un label. Å ie lauki parādās trÄ«s reizes status vārdnÄ«cās. Sākumā redzam globālo atslēgu "code": 1006 un "label": "PARTIALLY_FOUND". Pēc tam Å”ie atslēgas vārdi parādās katram atseviŔķam komponentam, ko mēs pieprasÄ«jām ā€” te un extraction. Un, ja par te ir skaidrs, ka dati ir atrasti, tad attiecÄ«bā uz extraction informācija trÅ«kst.

Tā izskatÄ«jās query pieprasÄ«jums iepriekÅ” minētajam piemēram.

{ "request":  [  

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

Ja nosūtāt query pieprasījumu bez komponenta extraction.

{ "request":  [  

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

Tad arī atbildē būs pilnīga informācija ("code": 1001, "label": "FOUND").

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "ATRASTS",
        "message": "Pieprasījums ir pilnībā apstrādāts."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
      "file_type": "doc",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "ļaunprātīgs",
              "pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
              "xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
            },
            "status": "atrasts",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "ļaunprātīgs",
        "severity": 4,
        "confidence": 1,
        "status": {
          "code": 1001,
          "label": "ATRASTS",
          "message": "Pieprasījums ir pilnībā apstrādāts."
        }
      }
    }
  ]
}

Ja nav vispār nekādas informācijas keÅ”atmiņā, atbilde bÅ«s "label": "NAV_ATRASTS"

{
  "response": [
    {
      "status": {
        "code": 1004,
        "label": "NAV_ATRASTS",
        "message": "Nebija iespējams atrast pieprasÄ«to failu. LÅ«dzu, augÅ”upielādējiet to."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "nezināms"
            },
            "status": "nav_atrast",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NAV_ATRASTS",
          "message": "Nebija iespējams atrast pieprasÄ«to failu. LÅ«dzu, augÅ”upielādējiet to."
        }
      }
    }
  ]
}

Viens API pieprasījums var nosūtīt vairākas hash summas pārbaudei. Atbilde tiks atgriezta tajā paŔā secībā, kādā tās tika nosūtītas pieprasījumā.

Pieprasījuma query piemērs ar vairākām sha256 summām

{ "request":  [  

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

Atbilde uz pieprasījumu query ar vairākām sha256 summām

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "ATRASTOTS",
        "message": "Pieprasījums ir pēc iespējas pilnībā apmierināts."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
      "file_type": "dll",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "ļaunprātīgs"
            },
            "status": "atrodams",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "ļaunprātīgs",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "ATRASTOTS",
          "message": "Pieprasījums ir pēc iespējas pilnībā apmierināts."
        }
      }
    },
    {
      "status": {
        "code": 1004,
        "label": "NEATRASTOTS",
        "message": "Neizdevās atrast pieprasÄ«to failu. LÅ«dzu, augÅ”upielādējiet to."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "nezināms"
            },
            "status": "neatrasts",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NEATRASTOTS",
          "message": "Neizdevās atrast pieprasÄ«to failu. LÅ«dzu, augÅ”upielādējiet to."
        }
      }
    }
  ]
}

Vairāku hash summu pieprasÄ«Å”ana vienlaikus query pieprasÄ«jumā arÄ« labvēlÄ«gi ietekmēs API servera veiktspēju.

Download API izsaukums

Izmantojamā metode ā€” POST (saskaņā ar dokumentāciju), GET arÄ« darbojas (un var Ŕķist loÄ£iskāks)

Izsaukuma adrese ā€” https://<service_address>/tecloud/api/v1/file/download?id=<id>

Galvenē ir jānosÅ«ta API atslēga, pieprasÄ«juma Ä·ermenis ā€” tukÅ”s, id tiek nosÅ«tÄ«ts URL adresē.

Atbildot uz query pieprasÄ«jumu, ja emulācija ir pabeigta un faila augÅ”upielādes laikā tika pieprasÄ«ti ziņojumi, bÅ«s redzami id ziņojumu lejupielādÄ“Å”anai. Ja tiek pieprasÄ«ts attÄ«rÄ«ts dokuments, tad jāmeklē id attÄ«rÄ«tajam dokumentam.

Kopumā atbildē uz query pieprasÄ«jumu, kas satur id vērtÄ«bas lejupielādei, var bÅ«t Ŕādi atslēgas:

  • summary_report

  • full_report

  • pdf_report

  • xml_report

  • extracted_file_download_id

Bez Å”aubām, lai atbildē uz query pieprasÄ«jumu tiktu saņemtas Ŕīs atslēgas, tās ir jānorāda pieprasÄ«jumā (ziņojumiem) vai jāpārliecinās, ka tiek veikts izsaukums uz extraction funkciju (attÄ«rÄ«tiem dokumentiem)

Quota API izsaukums

Izmantojamā metode ā€” POST

Izsaukuma adrese ā€” https://<service_address>/tecloud/api/v1/file/quota

AtlikuŔās kvotas pārbaude mākoņos tiek veikta, izmantojot quota pieprasÄ«jumu. PieprasÄ«juma Ä·ermenis ir tukÅ”s.

Piemērs atbildei uz quota pieprasījumu

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

Å is API tika izstrādāts pirms Threat Prevention API un ir paredzēts tikai lokālajiem ierÄ«cēm. PaÅ”laik tas var bÅ«t noderÄ«gs tikai tad, ja jums ir nepiecieÅ”ams Threat Extraction API. Threat Emulation labāk izmantot parasto Threat Prevention API. TP API for SG Lai konfigurētu API atslēgu, jāveic soļi no sk113599. Iesaku pievērst uzmanÄ«bu 6b. solim un pārbaudÄ«t lapas pieejamÄ«bu https:///UserCheck/TPAPI , jo negatÄ«vā rezultātā tālākā konfigurācija nav jēgpilna. Uz Å”o URL tiks nosÅ«tÄ«ti visi API izsaukumi. Izsaukuma veids (upload/query) tiek regulēts izsaukuma Ä·ermeņa atslēgā ā€” request_name. Obligāti nepiecieÅ”amās atslēgas ir ā€” api_key (jāatceras to konfigurācijas procesā) un protocol_version (paÅ”laik aktuālā versija ir 1.1). Oficiālo dokumentāciju Å”im API varat atrast sk137032. AttiecÄ«gajiem ieguvumiem var minēt iespēju nosÅ«tÄ«t vairākus failus uz simulāciju, jo faili tiek sÅ«tÄ«ti kā base64 teksta virkne. Failu kodÄ“Å”anai/dekodÄ“Å”anai no base64 var izmantot tieÅ”saistes konvertētāju, piemēram ā€” https://base64.guru. Praktiskos nolÅ«kos kodÄ“Å”anas rakstÄ«Å”anas ietvaros vajadzētu izmantot iebÅ«vētos encode un decode metodus.

Tagad pievērsÄ«simies detalizētāk funkcijām te un extraction Å”ajā API.

Komponentam te ir paredzēts vārdnÄ«ca te_options izsaukumos upload/query, un atslēgas Å”ajā izsaukumā pilnÄ«bā sakrÄ«t ar atslēgām te Threat Prevention API.

Piemērs pieprasījumam, lai simulētu failu Win10 ar ziņojumiem

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

Komponentam extraction ir paredzēts vārdnÄ«ca scrub_optionsÅ ajā pieprasÄ«jumā norādÄ«ts tÄ«rÄ«Å”anas metode: konvertācija PDF, aktÄ«vā satura tÄ«rÄ«Å”ana vai izvēlēties režīmu atbilstoÅ”i Threat Prevention profilam (norādiet profila nosaukumu). IzŔķiroÅ”a atŔķirÄ«ba API pieprasÄ«juma atbildē ar ekstrakciju failam ir tā, ka jÅ«s saņemat tÄ«rÄ«tu kopiju atbildē uz Å”o pieprasÄ«jumu kā Å”ifrētu base64 virkni (jums nav nepiecieÅ”ams veikt query pieprasÄ«jumu un meklēt id, lai lejupielādētu dokumentu)

Faila tÄ«rÄ«Å”anas pieprasÄ«juma piemērs

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

Atbilde uz pieprasījumu

{
	"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": "Iespējamu ļaunprātÄ«gu satura izvilkÅ”ana",
			"protection_type": "Konversija uz PDF",
			"real_extension": "txt",
			"risk": 0,
			"scrub_activity": "TXT fails tika konvertēts uz PDF",
			"scrub_method": "Konvertēt uz PDF",
			"scrub_result": 0,
			"scrub_time": "0.011",
			"scrubbed_content": ""
		}
	}]
}

Neskatoties uz to, ka, lai iegÅ«tu tÄ«rÄ«tu kopiju, nepiecieÅ”ams mazāk API pieprasÄ«jumu, es uzskatu, ka Ŕāda iespēja ir mazāk vēlama un ērta nekā form-data pieprasÄ«jums, kas tiek izmantots Threat Prevention API.

Postman kolekcijas

Es esmu izveidojis kolekcijas Postman gan Threat Prevention API, gan Threat Prevention API for Security Gateway, kur ir sniegti visbiežāk lietotie API pieprasÄ«jumi. Lai API servera ip/url un atslēga tiktu automātiski ievadÄ«tas pieprasÄ«jumos, kā arÄ« sha256 kopsumma pēc faila augÅ”upielādes tiktu atcerēta, iekŔā kolekcijās ir izveidotas trÄ«s mainÄ«gās (tās var atrast, pārejot uz kolekcijas iestatÄ«jumiem Edit -> Variables): te_api (jāaizpilda), api_key (jāaizpilda, izņemot gadÄ«jumus, kad tiek izmantots TP API ar lokālām ierÄ«cēm), sha256 (jāatstāj tukÅ”s, TP API for SG netiek izmantots).

Lejupielādēt Postman kolekciju Threat Prevention API

Lejupielādēt Postman kolekciju Threat Prevention for Security Gateway API

IzmantoÅ”anas piemēri

Kopienā Check Mates ir sniegti Python valodā rakstÄ«ti skripti, kas pārbauda failus no izvēlētās direktorijas gan caur TP API, gan TP API for SG. SadarbÄ«bā ar Threat Prevention API jÅ«su iespējas failu pārbaudei ievērojami paplaÅ”inās, jo tagad varat pārbaudÄ«t failus vienlaicÄ«gi vairākās platformās (interesanti ir pārbaudÄ«t ar VirusTotal API, un pēc tam Check Point smilÅ”u kastē), un failus iegÅ«t ne tikai no tÄ«kla trafika, bet arÄ« ņemt tos no jebkuriem tÄ«kla diskiem un, piemēram, CRM sistēmām.

Avots: habr.com

Iegādājieties uzticamu tÄ«mekļa hostingu ar DDoS aizsardzÄ«bu, VPS VDS serveriem šŸ”„ Iegādājieties uzticamu tÄ«mekļa hostingu ar DDoS aizsardzÄ«bu, VPS VDS serveriem | ProHoster