ProHoster > Blogg > Administration > Interaktion med Check Point SandBlast via API

Interaktion med Check Point SandBlast via API

Interaktion med Check Point SandBlast via API

Denna artikel kommer att vara anvÀndbar för dem som Àr bekanta med teknologier Check Point för filsimulering (Hotemulering) och proaktiv rensning av filer (Threat Extraction) och vill ta ett steg mot automatisering av dessa uppgifter. Check Point har Threat Prevention API, som fungerar bÄde i molnet och pÄ lokala enheter, och funktionellt Àr det identiskt med kontroll av filer i strömmar av web/smtp/ftp/smb/nfs trafik. Denna artikel Àr delvis en personlig tolkning av ett antal artiklar frÄn den officiella dokumentationen, men baserad pÄ egen erfarenhet och egna exempel. I artikeln hittar du ocksÄ personligt skapade Postman-kollektiner för arbete med Threat Prevention API.

Huvudsakliga förkortningar

Threat Prevention API arbetar med tre huvudkomponenter, som i API anropas genom följande textvÀrden:

av — komponenten Anti-Virus, ansvarar för signaturbaserad analys av kĂ€nda hot.

te — komponenten Threat Emulation, ansvarar för att kontrollera filer i en sandlĂ„da och att ge ett beslut om skadlig (malicious)/ren (benign) efter simulering.

extraction — komponenten Threat Extraction, som ansvarar för snabb konvertering av kontorsdokument till en sĂ€ker version (dĂ€r allt potentiellt skadligt innehĂ„ll tas bort), för att snabbt kunna leverera dem till anvĂ€ndare/system.

API-struktur och huvudsakliga begrÀnsningar

Threat Prevention API anvĂ€nder totalt 4 anrop — upload, query, download och quota. I rubriken för alla fyra anropen mĂ„ste API-nyckeln överföras med parametern Authorization. Vid första anblick kan strukturen verka mycket enklare Ă€n i Management API, men antalet fĂ€lt i anropen upload och query samt strukturen för dessa anrop Ă€r ganska komplexa. De kan funktionellt jĂ€mföras med profiler för Threat Prevention i sĂ€kerhetspolicyn för gateway/sandlĂ„da.

För nĂ€rvarande har endast en version av Threat Prevention API slĂ€ppts — 1.0, i URL:en för API-anrop bör man ange v1 i den del dĂ€r versionen ska anges. Till skillnad frĂ„n Management API Ă€r det obligatoriskt att ange API-versionen i URL-adressen, annars kommer anropet att misslyckas.

Komponenten Anti-Virus vid anrop utan andra komponenter (te, extraction) stödjer för nÀrvarande endast anrop med md5 hash-summor. Threat Emulation och Threat Extraction stöder Àven sha1 och sha256 hash-summor.

Det Àr mycket viktigt att inte göra misstag i anropen! FörfrÄgan kan genomföras utan fel, men inte helt. LÄt oss titta framÄt pÄ vad som kan hÀnda vid fel/slumpar i förfrÄgningar.

FörfrÄgan med ett stavfel i ordet reports(reportss)

{ "request":  [  

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

I svaret kommer det inte att finnas nÄgra fel, men samtidigt kommer det inte att finnas nÄgon information om rapporterna.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "FörfrÄgan har besvarats helt."
      },
      "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": "FörfrÄgan har besvarats helt."
        }
      }
    }
  ]
}

Men hÀr Àr förfrÄgan utan stavfel i nyckeln reports.

{ "request":  [  

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

Vi fÄr ett svar som redan innehÄller id:n för att ladda ner rapporterna.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "FörfrÄgan har besvarats helt."
      },
      "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": "FörfrÄgan har besvarats helt."
        }
      }
    }
  ]
}

Om man skickar en felaktig/utslagen API-nyckel fÄr man ett felmeddelande 403.

SandBlast API: i molnet och pÄ lokala enheter.

API-förfrĂ„gningar kan skickas till Check Point-enheter dĂ€r komponenten (blade) Threat Emulation Ă€r aktiverad. Adressen för förfrĂ„gningar bör anvĂ€nda enhetens ip/url och port 18194 (till exempel — https://10.10.57.19:18194/tecloud/api/v1/file/query). йаĐșжД ŃĐ»Đ”ĐŽŃƒĐ”Ń‚ ŃƒĐ±Đ”ĐŽĐžŃ‚ŃŒŃŃ ĐČ Ń‚ĐŸĐŒ, Ń‡Ń‚ĐŸ ĐżĐŸĐ»ĐžŃ‚ĐžĐșĐŸĐč Đ±Đ”Đ·ĐŸĐżĐ°ŃĐœĐŸŃŃ‚Đž ĐœĐ° ŃƒŃŃ‚Ń€ĐŸĐčстĐČĐ” Ń€Đ°Đ·Ń€Đ”ŃˆĐ”ĐœĐŸ таĐșĐŸĐ” ĐżĐŸĐŽĐșĐ»ŃŽŃ‡Đ”ĐœĐžĐ”. АĐČŃ‚ĐŸŃ€ĐžĐ·Đ°Ń†ĐžŃ чДрДз API Đșлюч ĐœĐ° Đ»ĐŸĐșĐ°Đ»ŃŒĐœŃ‹Ń… ŃƒŃŃ‚Ń€ĐŸĐčстĐČах ĐżĐŸ ŃƒĐŒĐŸĐ»Ń‡Đ°ĐœĐžŃŽ avstĂ€ngd och Authorization-nyckeln i förfrĂ„gningar behöver inte skickas överhuvudtaget.

API-förfrĂ„gningar till CheckPoint-molnet mĂ„ste skickas till adressen te.checkpoint.com (till exempel — https://te.checkpoint.com/tecloud/api/v1/file/query). API Đșлюч ĐŒĐŸĐ¶ĐœĐŸ ĐżĐŸĐ»ŃƒŃ‡ĐžŃ‚ŃŒ ĐČ ĐČОЎД Ń‚Ń€ĐžĐ°Đ»ŃŒĐœĐŸĐč Đ»ĐžŃ†Đ”ĐœĐ·ĐžĐž ĐœĐ° 60 ĐŽĐœĐ”Đč, ĐŸĐ±Ń€Đ°Ń‚ĐžĐČшось Đș ĐżĐ°Ń€Ń‚ĐœĐ”Ń€Đ°ĐŒ Check Point ОлО ĐČ Đ»ĐŸĐșĐ°Đ»ŃŒĐœŃ‹Đč ĐŸŃ„ĐžŃ ĐșĐŸĐŒĐżĐ°ĐœĐžĐž.

PÄ lokala enheter stöds inte Threat Extraction för nÀrvarande i standard Threat Prevention API och bör anvÀnda Threat Prevention API for Security Gateway (om den kommer vi att prata mer i slutet av artikeln).

Lokala enheter stöder inte quota-förfrÄgningar.

I övrigt finns det inga skillnader mellan förfrÄgningar till lokala enheter och till molnet.

Anrop av Upload API

Den anvĂ€nda metoden Ă€r — POST

Adressen för anropet Ă€r — https://<service_address>/tecloud/api/v1/file/upload

FörfrÄgan bestÄr av tvÄ delar (form-data): en fil avsedd för emulering/rensning och begÀrans kropp med text.

TextbegÀran kan inte vara tom, men den kan sakna all konfiguration. För att begÀran ska vara framgÄngsrik behöver du skicka minst följande text i begÀran:

NödvÀndigt minimum för upload-begÀran

HTTP POST

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

Headers:

Authorization: <api_key>

Body

{

«request»: {

}

}

Arkiv

Arkiv

I sĂ„ fall kommer filen att bearbetas enligt standardparametrarna: komponent — te, OS-avbildningar — Win XP och Win 7, utan att generera en rapport.

Kommentarer angÄende huvudfÀlten i textbegÀran:

file_name och file_type kan lÀmnas tomma eller inte skickas alls, eftersom detta inte Àr sÀrskilt anvÀndbar information vid filuppladdning. I API-svaret kommer dessa fÀlt fyllas automatiskt baserat pÄ namnet pÄ den uppladdade filen, och informationen i cachen mÄste ÀndÄ sökas med md5/sha1/sha256 hash-vÀrden.

Exempel pÄ begÀran med tomma file_name och file_type

{

"request": {

"file_name": "",

"file_type": "",

}

}

features — en lista som anger nödvĂ€ndig funktionalitet vid bearbetning i sandlĂ„dan — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Om denna parameter inte anges överhuvudtaget anvĂ€nds endast standardkomponenten — te (Threat Emulation).

För att aktivera kontrollen i de tre tillgÀngliga komponenterna mÄste dessa komponenter anges i API-begÀran.

Exempel pÄ begÀran med kontroll i av, te och extraction

{ "request": [  

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

Nycklar i avsnittet te

images — en lista dĂ€r ordlistor med id och versionsnummer av operativsystemen ska anges, i vilka kontrollen ska utföras. ID och versionsnummer Ă€r desamma för alla lokala enheter och molnet.

Lista över operativsystem och versioner

Available OS Image ID

Revision

Image OS and Application

e50e99f3-5963-4573-af9e-e3f4750b55e2

1

Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 och 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

Om nyckeln 'images' inte anges, kommer emuleringen att ske i bilder rekommenderade av Check Point (för nÀrvarande Win XP och Win 7). Dessa bilder rekommenderas för att uppnÄ den bÀsta balansen mellan prestanda och fÄngstrÀff.

rapporter — lista över rapporter som vi begĂ€r i hĂ€ndelse av att filen visar sig vara skadlig. Följande alternativ finns:

  1. sammanfattning — .tar.gz arkiv som innehĂ„ller en emuleringsrapport för med allt de begĂ€rda image'erna (bĂ„de som html-sida samt komponenter som video frĂ„n emulerings-OS, dump av nĂ€tverkstrafik, rapport i json, samt sjĂ€lva provet i ett skyddat arkiv). Vi söker nyckeln — summary_report för efterföljande nedladdning av rapporten.

  2. pdf — dokumentation av emuleringen i ett image, som mĂ„nga Ă€r vana att fĂ„ via Smart Console. Vi söker nyckeln — pdf_report för efterföljande nedladdning av rapporten.

  3. xml — dokumentation av emuleringen i ett image, lĂ€mplig för efterföljande parsing av parametrar i rapporten. Vi söker nyckeln — xml_report för efterföljande nedladdning av rapporten.

  4. tar — .tar.gz arkiv som innehĂ„ller en emuleringsrapport i ett de begĂ€rda image'erna (bĂ„de som html-sida samt komponenter som video frĂ„n emulerings-OS, dump av nĂ€tverkstrafik, rapport i json, samt sjĂ€lva provet i ett skyddat arkiv). Vi söker nyckeln — full_report för efterföljande nedladdning av rapporten.

Vad som finns i sammanfattningsrapportenInteraktion med Check Point SandBlast via API

Nycklarna full_report, pdf_report, xml_report finns i ordboken för varje OS

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

Och hĂ€r Ă€r nyckeln summary_report — finns en för emuleringen totalt

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

Det gÄr att begÀra tar- och xml- och pdf-rapporter samtidigt, man kan begÀra sammanfattning och tar och xml. Det gÄr inte att begÀra sammanfattningsrapport och pdf samtidigt.

Nycklar i avsnittet extraction

För hotextraktion anvÀnds bara tvÄ nycklar:

metod — pdf (konvertering till pdf, anvĂ€nds som standard) eller clean (rengöring av aktivt innehĂ„ll).

extracted_parts_codes — lista med koder för att ta bort aktivt innehĂ„ll, tillĂ€mpligt endast för metoden clean

Koder för att ta bort innehÄll frÄn filer

Code

Beskrivning

1025

LĂ€nkade objekt

1026

Makron och kod

1034

KÀnsliga hyperlÀnkar

1137

PDF GoToR-ÄtgÀrder

1139

PDF Launch-ÄtgÀrder

1141

PDF URI-ÄtgÀrder

1142

PDF LjudÄtgÀrder

1143

PDF FilmÄtgÀrder

1150

PDF JavaScript-ÄtgÀrder

1151

PDF Skicka formulÀrÄtgÀrder

1018

DatabasfrÄgor

1019

InbÀddade objekt

1021

Snabb spara-data

1017

Anpassade egenskaper

1036

Statistikegenskaper

1037

Sammanfattningsegenskaper

För att hĂ€mta en rensad kopia mĂ„ste man ocksĂ„ göra en query-begĂ€ran (som beskrivs senare) efter nĂ„gra sekunder, ange hashvĂ€rdet av filen och komponenten extraction i begĂ€rans text. Den rensade filen kan hĂ€mtas med hjĂ€lp av id frĂ„n svaret pĂ„ query-begĂ€ran — extracted_file_download_id. Återigen, för att förbereda för kommande, hĂ€r Ă€r exempel pĂ„ begĂ€ran och svar för att hitta id för att ladda ner det rensade dokumentet.

Query-begÀran för att hitta nyckeln extracted_file_download_id

{ "request":  [  

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

Svar pÄ query-begÀran (hitta nyckeln extracted_file_download_id)

{
    "response": [
        {
            "status": {
                "code": 1001,
                "label": "FOUND",
                "message": "BegÀran har besvarats helt."
            },
            "sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
            "file_type": "",
            "file_name": "",
            "features": [
                "utvinning"
            ],
            "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": "Makron och Kod",
                "extraction_data": {
                    "input_extension": "xls",
                    "input_real_extension": "xls",
                    "message": "OK",
                    "output_file_name": "kp-20-xls.cleaned.xls.pdf",
                    "protection_name": "Potentiellt skadligt innehÄll utvunnet",
                    "protection_type": "Konvertering till PDF",
                    "protocol_version": "1.0",
                    "risk": 5.0,
                    "scrub_activity": "Aktivt innehÄll har hittats - XLS-fil har konverterats till PDF",
                    "scrub_method": "Konvertera till PDF",
                    "scrub_result": 0.0,
                    "scrub_time": "0.013",
                    "scrubbed_content": "Makron och Kod"
                },
                "tex_product": false,
                "status": {
                    "code": 1001,
                    "label": "FOUND",
                    "message": "BegÀran har besvarats helt."
                }
            }
        }
    ]
}

AllmÀn information

I ett API-anrop kan endast en fil skickas för granskning.

Komponenten av krÀver ingen ytterligare sektion med nycklar, det rÀcker att ange den i ordboken. features.

Anrop av Query API

Den anvĂ€nda metoden Ă€r — POST

Adressen för anropet Ă€r — https://<service_address>/tecloud/api/v1/file/query

Innan du skickar en fil för uppladdning (anrop upload) Àr det önskvÀrt att kontrollera cache av sandlÄdan (anrop query) för att optimera belastningen pÄ API-servern, eftersom det kan finnas information och ett utlÄtande om den uppladdade filen redan pÄ API-servern. Anropet bestÄr endast av textdelen. Den obligatoriska delen av begÀran Àr sha1/sha256/md5 hash-summan av filen. Den kan förresten erhÄllas i svaret pÄ anropet upload.

NödvÀndigt minimum för begÀran query

HTTP POST

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

Headers:

Authorization: <api_key>

Body

{

«request»: {

«sha256»: <sha256 hash sum>

}

}

Exempel pÄ svar frÄn anropet upload, dÀr sha1/md5/sha256 hash-summor syns

{
  "response": {
    "status": {
      "code": 1002,
      "label": "UPLOAD_SUCCESS",
      "message": "Filen har laddats upp framgÄngsrikt."
    },
    "sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
    "md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
    "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
    "file_type": "",
    "file_name": "kp-20-doc.doc",
    "features": [
      "te"
    ],
    "te": {
      "trust": 0,
      "images": [
        {
          "report": {
            "verdict": "okÀnd"
          },
          "status": "not_found",
          "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
          "revision": 1
        }
      ],
      "score": -2147483648,
      "status": {
        "code": 1002,
        "label": "UPLOAD_SUCCESS",
        "message": "Filen har laddats upp framgÄngsrikt."
      }
    }
  }
}

FörfrÄgan query, förutom hash-summan, bör helst vara densamma som den planerade förfrÄgan upload, eller till och med «redan» (innehÄlla fÀrre fÀlt i förfrÄgan query Àn i förfrÄgan upload). Om förfrÄgan query innehÄller fler fÀlt Àn i förfrÄgan upload, fÄr du inte all den information som krÀvs.

HÀr Àr ett exempel pÄ svar pÄ förfrÄgan query, dÀr alla nödvÀndiga uppgifter inte hittades.

{
  "response": [
    {
      "status": {
        "code": 1006,
        "label": "PARTIALLY_FOUND",
        "message": "FörfrÄgan kan inte besvaras helt just nu."
      },
      "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": "FörfrÄgan har besvarats helt."
        }
      },
      "extraction": {
        "method": "pdf",
        "tex_product": false,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Kunde inte hitta den begÀrda filen. VÀnligen ladda upp den."
        }
      }
    }
  ]
}

Observera fĂ€lten code och label. Dessa fĂ€lt förekommer tre gĂ„nger i ordböckerna status. Först ser vi den globala nyckeln «code»: 1006 och «label»: «PARTIALLY_FOUND». DĂ€refter förekommer dessa nycklar i varje enskild komponent som vi har begĂ€rt — te och extraction. Och om det Ă€r klart för te att uppgifterna har hittats, sĂ„ Ă€r informationen för extraction obefintlig.

SÄ hÀr sÄg förfrÄgan query ut för ovanstÄende exempel

{ "request":  [  

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

Om du skickar förfrÄgan query utan komponenten extraction

{ "request":  [  

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

SÄ kommer svaret att innehÄlla komplett information ("code": 1001, "label": "FOUND")

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "FörfrÄgan har besvarats fullstÀndigt."
      },
      "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": "FörfrÄgan har besvarats fullstÀndigt."
        }
      }
    }
  ]
}

Om det inte finns nÄgon information i cachen alls, kommer svaret att innehÄlla "label": "NOT_FOUND"

{
  "response": [
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Det gick inte att hitta den begÀrda filen. VÀnligen ladda upp den."
      },
      "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 gick inte att hitta den begÀrda filen. VÀnligen ladda upp den."
        }
      }
    }
  ]
}

I ett API-anrop kan flera hash-vÀrden skickas för kontrold. I svaret kommer data att returneras i exakt samma ordning som de skickades i förfrÄgan.

Exempel pÄ en frÄga med flera sha256 hash-vÀrden

{ "request":  [  

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

Svar pÄ frÄgan med flera sha256 hash-vÀrden

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "BegÀran har besvarats fullstÀndigt."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
      "file_type": "dll",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "skadlig"
            },
            "status": "hittad",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "skadlig",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "BegÀran har besvarats fullstÀndigt."
        }
      }
    },
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Kunde inte hitta den begÀrda filen. VÀnligen ladda upp den."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "okÀnd"
            },
            "status": "inte_hittad",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Kunde inte hitta den begÀrda filen. VÀnligen ladda upp den."
        }
      }
    }
  ]
}

Att begÀra flera hash-vÀrden i frÄga kommer ocksÄ att gynna API-serverns prestanda.

Anrop av Download API

Den anvĂ€nda metoden Ă€r — POST (enligt dokumentationen), GET fungerar ocksĂ„ (och kan verka mer logiskt)

Adressen för anropet Ă€r — https://<service_address>/tecloud/api/v1/file/download?id=<id>

I rubriken mÄste API-nyckeln anges, kroppens förfrÄgan Àr tom och id för nedladdning anges i URL:en.

Som svar pÄ query-förfrÄgan, om emuleringen Àr klar och rapporter har begÀrts vid filöverföringen, kommer id för att ladda ner rapporterna att vara synliga. Om en rensad kopia begÀrs, ska id för att ladda ner det rensade dokumentet sökas.

Sammanfattningsvis kan nycklarna i svaret pÄ query-förfrÄgan som innehÄller id-vÀrdet för nedladdning vara:

  • summary_report

  • full_report

  • pdf_report

  • xml_report

  • extracted_file_download_id

SjÀlvklart, för att dessa nycklar ska erhÄllas i svaret pÄ query-förfrÄgan, mÄste de anges i förfrÄgan (för rapporter) eller se till att göra en förfrÄgan för extraction-funktionen (för rensade dokument).

Anrop av Quota API

Den anvĂ€nda metoden Ă€r — POST

Adressen för anropet Ă€r — https://<service_address>/tecloud/api/v1/file/quota

För att kontrollera kvarstÄende kvot i molnet anvÀnds förfrÄgan quota. Kroppen av förfrÄgan Àr tom.

Exempel pÄ svar pÄ förfrÄgan 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

Det hĂ€r API:et utvecklades tidigare Ă€n Threat Prevention API och Ă€r avsett endast för lokala enheter. För nĂ€rvarande kan det vara anvĂ€ndbart endast om du behöver Threat Extraction API. För Threat Emulation bör du anvĂ€nda det vanliga Threat Prevention API. För att aktivera TP API för SG och konfigurera API-nyckeln krĂ€vs det att du följer stegen i sk113599. Jag rekommenderar att du lĂ€gger vikt vid steg 6b och kontrollerar tillgĂ„ngen till sidan https:///UserCheck/TPAPI eftersom en negativ slutsats gör att vidare konfiguration inte Ă€r meningsfull. Alla API-anrop kommer att skickas till denna URL. Typen av anrop (upload/query) styrs av nyckeln i anropets kropp — request_name. De obligatoriska nycklarna Ă€r ocksĂ„ — api_key (glöm inte att spara den under konfigurationen) och protocol_version (för nĂ€rvarande Ă€r den aktuella versionen 1.1). Du kan hitta den officiella dokumentationen för detta API i sk137032. Bland de relativa fördelarna finns möjligheten att skicka flera filer för emulering vid uppladdning, eftersom filerna skickas som en textstrĂ€ng i base64. För att koda/dekoda filer till/frĂ„n base64 kan du anvĂ€nda en online-konverterare för demonstrativa Ă€ndamĂ„l i Postman, till exempel — https://base64.guru. I praktiska tillĂ€mpningar, nĂ€r du skriver kod, bör du anvĂ€nda inbyggda metoder för kodning och dekodning.

Nu ska vi gÄ in mer i detalj pÄ funktionerna te och extraction i detta API.

För komponenten te finns en ordbok te_options i anropen upload/query, och nycklarna i denna begÀran överensstÀmmer helt med nycklarna te i Threat Prevention API.

Exempel pÄ begÀran för emulering av 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"]
    }
    }
    ]
}

För komponenten extraction finns en ordbok scrub_optionsI denna begÀran anges rensningsmetoden: konvertering till PDF, borttagning av aktivt innehÄll eller att vÀlja lÀget enligt profilen för Threat Prevention (profilnamnet anges). En sÀrskiljande egenskap hos svaret pÄ API-begÀran med extraction för filen Àr att du fÄr en rensad kopia som ett svar pÄ denna begÀran i form av en krypterad base64-strÀng (du behöver inte göra en query-begÀran och leta efter id för att ladda ner dokumentet)

Exempel pÄ begÀran för rensning av 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Ä begÀran

{
	"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": "Extrahera potentiellt skadligt innehÄll",
			"protection_type": "Konvertering till PDF",
			"real_extension": "txt",
			"risk": 0,
			"scrub_activity": "TXT-fil har konverterats till PDF",
			"scrub_method": "Konvertera till PDF",
			"scrub_result": 0,
			"scrub_time": "0.011",
			"scrubbed_content": ""
		}
	}]
}

Trots att det krÀvs fÀrre API-begÀrningar för att fÄ en rensad kopia, anser jag att detta alternativ Àr mindre önskvÀrt och bekvÀmt Àn begÀran form-data som anvÀnds i Threat Prevention API.

Postman-samlingar

Jag har skapat samlingar i Postman för bÄde Threat Prevention API och Threat Prevention API för Security Gateway, dÀr de mest vanliga API-begÀrningarna presenteras. För att ip/url API-server och nyckel ska fyllas i automatiskt i begÀrningarna, och hash-summan sha256 efter filuppladdning ocksÄ ska sparas, har tre variabler skapats inuti samlingarna (de kan hittas genom att gÄ till instÀllningarna för samlingen Redigera -> Variabler): te_api (mÄste fyllas i), api_key (mÄste fyllas i, förutom vid anvÀndning av TP API med lokala enheter), sha256 (lÀmna tomt, anvÀnds inte i TP API för SG).

Ladda ner Postman-samlingen för Threat Prevention API

Ladda ner Postman-samlingen för Threat Prevention för Security Gateway API

Exempel pÄ anvÀndning

I gemenskapen Check Mates presenteras skript skrivna i Python som kontrollerar filer frÄn den angivna katalogen bÄde via TP API, sÄvÀl som TP API för SG. Genom interaktion med Threat Prevention API utvidgas dina möjligheter att kontrollera filer avsevÀrt, eftersom du nu kan kontrollera filer pÄ flera plattformar samtidigt (en intressant kontroll Àr i VirusTotal API, och sedan i Check Point-sandboxen), och filerna kan inte bara hÀmtas frÄn nÀtverksflödet, utan ocksÄ samlas frÄn alla nÀtverksdiskar och till exempel CRM-system.

KĂ€lla: habr.com

Köp pĂ„litlig webbhotell med DDoS-skydd, VPS VDS-servrar đŸ”„ Köp pĂ„litlig webbhotell med DDoS-skydd, VPS VDS-servrar | ProHoster