ProHoster > Blog > administration > Interaktion med Check Point SandBlast via API

Interaktion med Check Point SandBlast via API

Interaktion med Check Point SandBlast via API

Denne artikel vil være nyttig for dem, der er fortrolige med teknologi Check Point ved fil emulering (Trusselsemulering) og proaktiv filrensning (Trusselsudtrækning) og ønsker at tage et skridt i retning af at automatisere disse opgaver. Check Point har Threat Prevention API, som kører både i skyen og på lokale enheder, og funktionelt er det identisk med at tjekke filer i web/smtp/ftp/smb/nfs trafikstrømme. Denne artikel er dels forfatterens fortolkning af et sæt artikler fra den officielle dokumentation, men baseret på min egen driftserfaring og mine egne eksempler. Også i artiklen finder du forfatterens Postman-samlinger til at arbejde med Threat Prevention API.

Grundlæggende forkortelser

Threat Prevention API fungerer med tre hovedkomponenter, som kaldes i API'et gennem følgende tekstværdier:

av — Anti-Virus-komponent, ansvarlig for signaturanalyse af kendte trusler.

te - Threat Emulation-komponent, ansvarlig for at tjekke filer i sandkassen og lave en ondsindet/godartet dom efter emulering.

udvinding - Threat Extraction-komponent, ansvarlig for hurtigt at konvertere office-dokumenter til en sikker form (hvori alt potentielt skadeligt indhold fjernes), for hurtigt at kunne levere dem til brugere/systemer.

API-struktur og hovedbegrænsninger

Threat Prevention API bruger kun 4 anmodninger − upload, forespørg, download og kvote. I overskriften for alle fire anmodninger skal du sende API-nøglen ved hjælp af parameteren Tilladelse. Ved første øjekast kan strukturen virke meget enklere end i Management API, men antallet af felter i upload- og forespørgselsanmodningerne og strukturen af ​​disse anmodninger er ret komplekse. Disse kan funktionelt sammenlignes med Threat Prevention-profiler i en gateway/sandbox-sikkerhedspolitik.

I øjeblikket er den eneste version af Threat Prevention API blevet frigivet - 1.0; URL'en til API-kald skal indeholde v1 i den del, hvor du skal angive versionen. I modsætning til Management API er det nødvendigt at angive API-versionen i URL'en, ellers vil anmodningen ikke blive eksekveret.

Antivirus-komponenten, når den kaldes uden andre komponenter (te, udtrækning), understøtter i øjeblikket kun forespørgselsanmodninger med md5-hash-summer. Threat Emulation og Threat Extraction understøtter også sha1 og sha256 hash-summer.

Det er meget vigtigt ikke at lave fejl i forespørgsler! Anmodningen kan udføres uden fejl, men ikke fuldstændigt. Ser vi lidt fremad, så lad os se på, hvad der kan ske, når der er fejl/tastefejl i forespørgsler.

Anmodning med en tastefejl med ordet reports(reportss)

{ "request":  [  

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

Der vil ikke være fejl i svaret, men der vil slet ikke være oplysninger om indberetningerne

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
      "file_type": "pdf",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

Men for en anmodning uden tastefejl i rapporttasten

{ "request":  [  

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

Vi modtager et svar, der allerede indeholder id til download af rapporter

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
      "file_type": "pdf",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
              "pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
              "xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

Hvis vi sender en forkert/udløbet API-nøgle, vil vi modtage en 403-fejl som svar.

SandBlast API: i skyen og på lokale enheder

API-anmodninger kan sendes til Check Point-enheder, der har Threat Emulation-komponenten (blade) aktiveret. Som adresse for anmodninger skal du bruge enhedens ip/url og port 18194 (f.eks. https://10.10.57.19:18194/tecloud/api/v1/fil/forespørgsel). Du bør også sørge for, at sikkerhedspolitikken på enheden tillader denne forbindelse. Godkendelse via API-nøgle på lokale enheder som standard af og autorisationsnøglen i anmodningsoverskrifter sendes muligvis slet ikke.

API-anmodninger til CheckPoint-skyen skal sendes til te.checkpoint.com (for eksempel - https://te.checkpoint.com/tecloud/api/v1/fil/forespørgsel). API-nøglen kan fås som en prøvelicens i 60 dage ved at kontakte Check Point-partnere eller virksomhedens lokale kontor.

På lokale enheder er Threat Extraction endnu ikke understøttet som standard. Threat Prevention API og skal bruges Threat Prevention API til Security Gateway (vi vil tale mere om det i slutningen af ​​artiklen).

Lokale enheder understøtter ikke kvoteanmodningen.

Ellers er der ingen forskelle mellem anmodninger til lokale enheder og til skyen.

Upload API-kald

Anvendt metode − POST

Opkaldsadresse - https:///tecloud/api/v1/file/upload

Anmodningen består af to dele (form-data): en fil beregnet til emulering/rensning og en anmodningstekst med tekst.

Tekstanmodningen må ikke være tom, men den indeholder muligvis ikke nogen konfiguration. For at anmodningen skal lykkes, skal du som minimum sende følgende tekst i anmodningen:

Minimum påkrævet for en uploadanmodning

HTTP POST

https:///tecloud/api/v1/file/upload

headers:

Bemyndigelse:

Fylde

{

"anmodning": {

}

}

File (Felt)

File (Felt)

I dette tilfælde vil filen blive behandlet i overensstemmelse med standardparametrene: komponent - te, OS billeder - Vind XP og Win 7uden at generere en rapport.

Kommentarer til hovedfelterne i tekstanmodningen:

filnavn и filtype Du kan lade dem være tomme eller slet ikke sende dem, da dette ikke er særlig nyttig information, når du uploader en fil. I API-svaret vil disse felter blive udfyldt automatisk baseret på navnet på den downloadede fil, og oplysningerne i cachen skal stadig søges ved hjælp af md5/sha1/sha256 hash-mængder.

Eksempelanmodning med tomt filnavn og filtype

{

"request": {

"file_name": "",

"file_type": "",

}

}

funktioner — en liste, der angiver den nødvendige funktionalitet ved behandling i sandkassen - av (Anti-Virus), te (Trusselsemulering), udvinding (Trusselsekstraktion). Hvis denne parameter slet ikke videregives, vil kun standardkomponenten blive brugt - te (Trusselsemulering).

For at aktivere indtjekning af de tre tilgængelige komponenter, skal du angive disse komponenter i API-anmodningen.

Eksempel på en anmodning med indtjekning av, te og udtræk

{ "request":  [  

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

Taster i te-sektionen

billeder — en liste med ordbøger med id og revisionsnummer for de operativsystemer, hvori kontrollen vil blive udført. ID'er og revisionsnumre er de samme for alle lokale enheder og skyen.

Liste over operativsystemer og revisioner

Tilgængeligt OS Image ID

Revision

Image OS og applikation

e50e99f3-5963-4573-af9e-e3f4750b55e2

1

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

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

1

Microsoft Windows: 7 - 32 bit
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 - 32 bit
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 - 32 bit
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 - 64 bit
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 - 64 bit
Office: 2013 (64bit)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Plugin & ActiveX)
Java Runtime: 1.7.0u9

10b4a9c6-e414-425c-ae8b-fe4dd7b25244 

 

1

Microsoft Windows: 10
Office: Professional Plus 2016 en-us  
Adobe Acrobat Reader: DC 2015 MUI
Flash Player: 20 (Plugin & ActiveX)
Java Runtime: 1.7.0u9

Hvis billednøglen slet ikke er angivet, vil emulering finde sted i billeder anbefalet af Check Point (i øjeblikket Win XP og Win 7). Disse billeder anbefales baseret på overvejelser om den bedste balance mellem ydeevne og fangsthastighed.

rapporter — en liste over rapporter, som vi anmoder om, hvis filen viser sig at være skadelig. Følgende muligheder er tilgængelige:

  1. resumé - .tar.gz arkiv indeholdende en rapport om emulering af til alle anmodede billeder (både en html-side og komponenter såsom en video fra emulator-operativsystemet, et netværkstrafikdump, en rapport i json og selve prøven i et adgangskodebeskyttet arkiv). Vi leder efter nøglen i svaret - opsummerende rapport til efterfølgende download af rapporten.

  2. pdf - dokument om emulering i en billede, som mange er vant til at modtage gennem Smart Console. Vi leder efter nøglen i svaret - pdf_rapport til efterfølgende download af rapporten.

  3. xml - dokument om emulering i en billede, praktisk til efterfølgende parsing af parametre i rapporten. Vi leder efter nøglen i svaret - xml_rapport til efterfølgende download af rapporten.

  4. tjære - .tar.gz-arkiv, der indeholder en rapport om emulering i en anmodede billeder (både en html-side og komponenter såsom en video fra emulator-operativsystemet, et netværkstrafikdump, en rapport i json og selve prøven i et adgangskodebeskyttet arkiv). Vi leder efter nøglen i svaret - fuld_rapport til efterfølgende download af rapporten.

Hvad er inde i den sammenfattende rapportInteraktion med Check Point SandBlast via API

Nøglerne full_report, pdf_report, xml_report er i ordbogen for hvert 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."
        }
      }
    }
  ]
}

Men summary_report nøglen - der er en til emulering generelt

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

Du kan anmode om tar- og xml- og pdf-rapporter på samme tid, du kan anmode om resumé og tar og xml. Det vil ikke være muligt at rekvirere en sammenfattende rapport og en pdf på samme tid.

Taster i ekstraktionssektionen

Til trusselsudtrækning bruges kun to nøgler:

metode — pdf (konverter til pdf, bruges som standard) eller clean (renser aktivt indhold).

ekstraherede_dele_koder - liste over koder til fjernelse af aktivt indhold, kun gældende for den rene metode

Koder til at fjerne indhold fra filer

Kode

Beskrivelse

1025

Sammenkædede objekter

1026

Makroer og kode

1034

Følsomme hyperlinks

1137

PDF GoToR-handlinger

1139

PDF-starthandlinger

1141

PDF URI-handlinger

1142

PDF lydhandlinger

1143

PDF film handlinger

1150

PDF JavaScript-handlinger

1151

PDF-indsend formularhandlinger

1018

Databaseforespørgsler

1019

Indlejrede objekter

1021

Hurtig gem data

1017

Brugerdefinerede egenskaber

1036

Statistiske egenskaber

1037

Oversigtsegenskaber

For at downloade en renset kopi skal du også lave en forespørgselsanmodning (som vil blive diskuteret nedenfor) efter et par sekunder, idet du angiver hash-mængden af ​​filen og udtrækskomponenten i anmodningsteksten. Du kan hente den rensede fil ved hjælp af id'et fra svaret på forespørgslen - extracted_file_download_id. Endnu en gang, ser jeg lidt fremad, giver jeg eksempler på en anmodning og et forespørgselssvar for at søge efter et id til at downloade et ryddet dokument.

Forespørgselsanmodning om at søge efter nøglen extracted_file_download_id

{ "request":  [  

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

Svar på forespørgsel (se efter nøglen extracted_file_download_id)

{
    "response": [
        {
            "status": {
                "code": 1001,
                "label": "FOUND",
                "message": "The request has been fully answered."
            },
            "sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
            "file_type": "",
            "file_name": "",
            "features": [
                "extraction"
            ],
            "extraction": {
                "method": "pdf",
                "extract_result": "CP_EXTRACT_RESULT_SUCCESS",
                "extracted_file_download_id": "b5f2b34e-3603-4627-9e0e-54665a531ab2",
                "output_file_name": "kp-20-xls.cleaned.xls.pdf",
                "time": "0.013",
                "extract_content": "Macros and Code",
                "extraction_data": {
                    "input_extension": "xls",
                    "input_real_extension": "xls",
                    "message": "OK",
                    "output_file_name": "kp-20-xls.cleaned.xls.pdf",
                    "protection_name": "Potential malicious content extracted",
                    "protection_type": "Conversion to PDF",
                    "protocol_version": "1.0",
                    "risk": 5.0,
                    "scrub_activity": "Active content was found - XLS file was converted to PDF",
                    "scrub_method": "Convert to PDF",
                    "scrub_result": 0.0,
                    "scrub_time": "0.013",
                    "scrubbed_content": "Macros and Code"
                },
                "tex_product": false,
                "status": {
                    "code": 1001,
                    "label": "FOUND",
                    "message": "The request has been fully answered."
                }
            }
        }
    ]
}

Oversigt

I et API-kald kan du kun sende én fil til verifikation.

Av-komponenten kræver ikke en ekstra sektion med nøgler, det er nok at angive det i ordbogen funktioner.

Forespørg API-kald

Anvendt metode − POST

Opkaldsadresse - https:///tecloud/api/v1/fil/query

Før du sender en fil til download (upload-anmodning), er det tilrådeligt at tjekke sandbox-cachen (forespørgselsanmodning) for at optimere belastningen på API-serveren, da API-serveren muligvis allerede har information og en dom om den downloadede fil. Opkaldet består kun af en tekstdel. Den påkrævede del af anmodningen er sha1/sha256/md5 hash-mængde af filen. Det kan du i øvrigt få i svaret på uploadanmodningen.

Minimum påkrævet for forespørgsel

HTTP POST

https:///tecloud/api/v1/fil/query

headers:

Bemyndigelse:

Fylde

{

"anmodning": {

"sha256":

}

}

Et eksempel på et svar på en uploadanmodning, hvor sha1/md5/sha256 hash-beløb er synlige

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

Forespørgselsanmodningen, ud over hash-beløbet, skal ideelt set være den samme som uploadanmodningen var (eller er planlagt til at være), eller endda "allerede" (indeholde færre felter i forespørgselsanmodningen end i uploadanmodningen). I det tilfælde, hvor forespørgselsanmodningen indeholder flere felter, end der var i uploadanmodningen, vil du ikke modtage alle de nødvendige oplysninger i svaret.

Her er et eksempel på et svar på en forespørgsel, hvor ikke alle nødvendige data blev fundet

{
  "response": [
    {
      "status": {
        "code": 1006,
        "label": "PARTIALLY_FOUND",
        "message": "The request cannot be fully answered at this time."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
      "file_type": "doc",
      "file_name": "",
      "features": [
        "te",
        "extraction"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
              "xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 1,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      },
      "extraction": {
        "method": "pdf",
        "tex_product": false,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Could not find the requested file. Please upload it."
        }
      }
    }
  ]
}

Vær opmærksom på felterne kode и label. Disse felter vises tre gange i statusordbøger. Først ser vi den globale nøgle "kode": 1006 og "label": "PARTIALLY_FOUND". Dernæst findes disse nøgler for hver enkelt komponent, som vi har anmodet om - te og ekstraktion. Og hvis det for dig er klart, at dataene er fundet, så er der ingen information til udvinding.

Sådan så forespørgslen ud for eksemplet ovenfor

{ "request":  [  

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

Hvis du sender en forespørgsel uden ekstraktionskomponenten

{ "request":  [  

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

Så vil svaret indeholde fuldstændig information ("kode": 1001, "label": "FOUND")

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
      "file_type": "doc",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
              "xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 1,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

Hvis der slet ikke er nogen information i cachen, vil svaret være "label": "NOT_FOUND"

{
  "response": [
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Could not find the requested file. Please upload it."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "unknown"
            },
            "status": "not_found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Could not find the requested file. Please upload it."
        }
      }
    }
  ]
}

I et API-kald kan du sende flere hash-beløb på én gang til verifikation. Svaret vil returnere data i samme rækkefølge, som det blev sendt i anmodningen.

Eksempel på forespørgselsanmodning med flere sha256-beløb

{ "request":  [  

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

Svar på en forespørgsel med flere sha256-beløb

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
      "file_type": "dll",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    },
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Could not find the requested file. Please upload it."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "unknown"
            },
            "status": "not_found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Could not find the requested file. Please upload it."
        }
      }
    }
  ]
}

At anmode om flere hash-summer på én gang i en forespørgselsanmodning vil også have en gavnlig effekt på API-serverens ydeevne.

Download API-kald

Anvendt metode − POST (ifølge dokumentation), GET virker også (og kan virke mere logisk)

Opkaldsadresse - https:///tecloud/api/v1/file/download?id=

Headeren kræver, at API-nøglen sendes, brødteksten i anmodningen er tom, download-id'et sendes i URL-adressen.

Som svar på en forespørgsel, hvis emuleringen er fuldført, og der blev anmodet om rapporter ved download af filen, vil id'et for download af rapporter være synligt. Hvis der anmodes om en renset kopi, skal du kigge efter id'et for at downloade det rensede dokument.

I alt kan nøglerne i svaret på forespørgslen indeholdende id-værdien til indlæsning være:

  • opsummerende rapport

  • fuld_rapport

  • pdf_rapport

  • xml_rapport

  • extracted_file_download_id

For at modtage disse nøgler som svar på forespørgselsanmodningen skal de naturligvis angives i anmodningen (for rapporter) eller huske at lave en anmodning ved hjælp af udtræksfunktionen (for rensede dokumenter)

Kvote API-kald

Anvendt metode − POST

Opkaldsadresse - https:///tecloud/api/v1/file/kvote

For at kontrollere den resterende kvote i skyen skal du bruge kvoteforespørgslen. Anmodningsteksten er tom.

Eksempel på svar på en kvoteanmodning

{
  "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 til Security Gateway

Denne API blev udviklet før Threat Prevention API og er kun beregnet til lokale enheder. For nu kan det kun være nyttigt, hvis du har brug for Threat Extraction API. Til Threat Emulation er det bedre at bruge den almindelige Threat Prevention API. At tænde TP API til SG og konfigurer den API-nøgle, du skal følge trinene fra sk113599. Jeg anbefaler at være opmærksom på trin 6b og tjekke sidens tilgængelighed https://<IPAddressofSecurityGateway>/UserCheck/TPAPI fordi i tilfælde af et negativt resultat, giver yderligere konfiguration ikke mening. Alle API-kald vil blive sendt til denne url. Opkaldstypen (upload/forespørgsel) reguleres i hovedtasten − request_name. Også nødvendige nøgler er - api_key (du skal huske det under konfigurationsprocessen) og protocol_version (aktuelt er den aktuelle version 1.1). Du kan finde den officielle dokumentation for denne API på sk137032. Relative fordele inkluderer muligheden for at sende flere filer på én gang til emulering, når de indlæses, da filerne sendes som en base64-tekststreng. For at indkode/afkode filer til/fra base64 kan du bruge en online konverter i Postman til demonstrationsformål, for eksempel - https://base64.guru. Af praktiske årsager bør du bruge de indbyggede indkodnings- og afkodningsmetoder, når du skriver kode.

Lad os nu se nærmere på funktionerne te и udvinding i denne API.

Til komponent te ordbog leveret te_indstillinger i upload-/forespørgselsanmodninger, og nøglerne i denne anmodning falder fuldstændig sammen med te-tasterne Threat Prevention API.

Eksempel på anmodning om filemulering i Win10 med rapporter

{
"request": [{
    "protocol_version": "1.1",
    "api_key": "<api_key>",
    "request_name": "UploadFile",
    "file_enc_data": "<base64_encoded_file>",
    "file_orig_name": "<filename>",
    "te_options": {
        "images": [
                {
                    "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                    "revision": 1
                }
            ],
        "reports": ["summary", "xml"]
    }
    }
    ]
}

Til komponent udvinding ordbog leveret scrub_options. Denne anmodning specificerer rensemetoden: konverter til PDF, ryd aktivt indhold, eller vælg en tilstand i overensstemmelse med profilen til forebyggelse af trusler (profilnavnet er angivet). Det fantastiske ved at svare på en ekstraktions-API-anmodning for en fil er, at du får en renset kopi i svaret på den anmodning som en base64-krypteret streng (du behøver ikke at lave en forespørgselsanmodning og slå id'et op for at downloade dokument)

Eksempel på en anmodning om at rydde en fil

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

Besvar en anmodning

{
	"response": [{
		"protocol_version": "1.1",
		"src_ip": "<IP_ADDRESS>",
		"scrub": {
			"file_enc_data": "<base64_encoded_converted_to_PDF_file>",
			"input_real_extension": "js",
			"message": "OK",
			"orig_file_url": "",
			"output_file_name": "hi.cleaned.pdf",
			"protection_name": "Extract potentially malicious content",
			"protection_type": "Conversion to PDF",
			"real_extension": "txt",
			"risk": 0,
			"scrub_activity": "TXT file was converted to PDF",
			"scrub_method": "Convert to PDF",
			"scrub_result": 0,
			"scrub_time": "0.011",
			"scrubbed_content": ""
		}
	}]
}

På trods af, at der kræves færre API-anmodninger for at opnå en ryddet kopi, finder jeg denne mulighed mindre at foretrække og bekvem end formulardataanmodningen, der bruges i Threat Prevention API.

Postmands Samlinger

Jeg oprettede samlinger i Postman til både Threat Prevention API og Threat Prevention API for Security Gateway, som repræsenterer de mest almindelige API-anmodninger. For at serverens ip/url API og nøgle automatisk skal erstattes med anmodninger, og sha256 hash beløbet skal huskes efter download af filen, er der oprettet tre variabler inde i samlingerne (du kan finde dem ved at gå til samlingsindstillingerne Rediger -> Variabler): te_api (påkrævet), api_key (skal udfyldes, undtagen ved brug af TP API med lokale enheder), sha256 (lad tom, ikke brugt i TP API for SG).

Download Postman-kollektionen til Threat Prevention API

Download Postman-samlingen til Threat Prevention for Security Gateway API

Eksempler på anvendelse

I samfundet Tjek kammerater scripts skrevet i Python præsenteres, der tjekker filer fra den ønskede mappe via TP APIOg TP API til SG. Gennem interaktion med Threat Prevention API udvides din mulighed for at scanne filer betydeligt, da du nu kan scanne filer på flere platforme på én gang (tjek ind VirusTotal API, og derefter i Check Point-sandkassen), og modtager filer ikke kun fra netværkstrafik, men tager dem også fra alle netværksdrev og for eksempel CRM-systemer.

Kilde: www.habr.com

Tilføj en kommentar