ProHoster > Blog > Pentadbiran > Interaksi dengan Check Point SandBlast melalui API

Interaksi dengan Check Point SandBlast melalui API

Interaksi dengan Check Point SandBlast melalui API

Artikel ini akan berguna kepada mereka yang biasa dengan teknologi Check Point melalui emulasi fail (Emulasi Ancaman) dan pembersihan fail proaktif (Pengekstrakan Ancaman) dan ingin mengambil langkah ke arah mengautomasikan tugasan ini. Check Point mempunyai API Pencegahan Ancaman, yang berjalan dalam awan dan pada peranti tempatan, dan fungsinya adalah sama dengan menyemak fail dalam aliran trafik web/smtp/ftp/smb/nfs. Artikel ini sebahagiannya adalah tafsiran pengarang bagi satu set artikel daripada dokumentasi rasmi, tetapi berdasarkan pengalaman pengendalian saya sendiri dan contoh saya sendiri. Juga dalam artikel anda akan menemui koleksi Posmen pengarang untuk bekerja dengan API Pencegahan Ancaman.

Singkatan asas

API Pencegahan Ancaman berfungsi dengan tiga komponen utama, yang dipanggil dalam API melalui nilai teks berikut:

av — компонент Anti-Virus, отвечает за сигнатурный анализ известных угроз.

te - Komponen Emulasi Ancaman, bertanggungjawab untuk menyemak fail dalam kotak pasir, dan membuat keputusan berniat jahat/jinak selepas emulasi.

pengekstrakan — компонент Threat Extraction, отвечающий за быструю конвертацию офисных документов в безопасный вид (в котором удаляется весь потенциально вредоносный контент), в целях их быстрой доставки пользователям/системам.

Структура API и основные ограничения

Threat Prevention API использует всего 4 запроса — muat naik, pertanyaan, muat turun dan kuota. В заголовке для всех четырех запросов нужно передать API ключ, используя параметр kebenaran. Pada pandangan pertama, struktur mungkin kelihatan lebih mudah daripada dalam API Pengurusan, tetapi bilangan medan dalam permintaan muat naik dan pertanyaan serta struktur permintaan ini agak rumit. Ini boleh dibandingkan secara fungsi dengan profil Pencegahan Ancaman dalam dasar keselamatan get laluan/kotak pasir.

На данный момент, выпущена единственная версия Threat Prevention API — 1.0, в URL для API вызовов следует указывать v1 di bahagian di mana anda perlu menentukan versi. Tidak seperti API Pengurusan, adalah perlu untuk menunjukkan versi API dalam URL, jika tidak, permintaan tidak akan dilaksanakan.

Компонент Anti-Virus при вызове без других компонентов (te, extraction) на данный момент поддерживает только запросы query с md5 хэш суммами. Threat Emulation и Threat Extraction поддерживает также sha1 и sha256 хэш суммы.

Adalah sangat penting untuk tidak membuat kesilapan dalam pertanyaan! Permintaan boleh dilaksanakan tanpa ralat, tetapi tidak sepenuhnya. Memandang ke hadapan sedikit, mari kita lihat apa yang boleh berlaku apabila terdapat ralat/typo dalam pertanyaan.

Permintaan dengan kesilapan menaip dengan perkataan laporan(laporan)

{ "request":  [  

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

Tidak akan ada ralat dalam respons, tetapi tidak akan ada maklumat tentang laporan sama sekali

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

Tetapi untuk permintaan tanpa kesilapan menaip dalam kunci laporan

{ "request":  [  

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

Kami menerima respons yang sudah mengandungi id untuk memuat turun laporan

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

Jika kami menghantar kunci API yang salah/tamat tempoh, kami akan menerima ralat 403 sebagai balasan.

SandBlast API: dalam awan dan pada peranti tempatan

Permintaan API boleh dihantar ke peranti Check Point yang mempunyai komponen Threat Emulation (blade) yang didayakan. Sebagai alamat untuk permintaan, anda perlu menggunakan ip/url peranti dan port 18194 (contohnya, https://10.10.57.19:18194/tecloud/api/v1/file/query). Anda juga harus memastikan bahawa dasar keselamatan pada peranti membenarkan sambungan ini. Keizinan melalui kunci API pada peranti tempatan secara lalai dimatikan и ключ Authorization в заголовках запросов можно не отправлять вовсе.

Permintaan API ke awan CheckPoint harus dihantar ke te.checkpoint.com (contohnya - https://te.checkpoint.com/tecloud/api/v1/file/query). Kunci API boleh diperoleh sebagai lesen percubaan selama 60 hari dengan menghubungi rakan kongsi Check Point atau pejabat tempatan syarikat.

Pada peranti tempatan, Pengekstrakan Ancaman belum lagi disokong sebagai standard. API Pencegahan Ancaman dan harus digunakan API Pencegahan Ancaman untuk Gerbang Keselamatan (kami akan membincangkannya dengan lebih terperinci pada akhir artikel).

Peranti tempatan tidak menyokong permintaan kuota.

Jika tidak, tiada perbezaan antara permintaan kepada peranti tempatan dan kepada awan.

Muat naik panggilan API

Kaedah yang digunakan − SELEPAS

Alamat panggilan - https:///tecloud/api/v1/file/upload

Permintaan terdiri daripada dua bahagian (data borang): fail yang bertujuan untuk emulasi/pembersihan dan badan permintaan dengan teks.

Permintaan teks tidak boleh kosong, tetapi ia mungkin tidak mengandungi sebarang konfigurasi. Untuk membolehkan permintaan itu berjaya, anda mesti menghantar sekurang-kurangnya teks berikut dalam permintaan:

Minimum diperlukan untuk permintaan muat naik

HTTP POST

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

Tajuk:

Kebenaran:

Badan

{

"permintaan": {

}

}

File

File

Dalam kes ini, fail akan diproses mengikut parameter lalai: komponen - te, imej OS - Menang XP dan Menang 7, tanpa menghasilkan laporan.

Komen pada medan utama dalam permintaan teks:

nama fail и jenis fail Anda boleh membiarkannya kosong atau tidak menghantarnya sama sekali, kerana ini bukan maklumat yang sangat berguna semasa memuat naik fail. Dalam respons API, medan ini akan diisi secara automatik berdasarkan nama fail yang dimuat turun dan maklumat dalam cache masih perlu dicari menggunakan jumlah cincang md5/sha1/sha256.

Contoh permintaan dengan nama_fail kosong dan jenis_fail

{

"request": {

"file_name": "",

"file_type": "",

}

}

ciri-ciri — senarai yang menunjukkan fungsi yang diperlukan semasa memproses dalam kotak pasir - av (Anti-Virus), te (Emulasi Ancaman), pengekstrakan (Pengekstrakan Ancaman). Jika parameter ini tidak diluluskan sama sekali, maka hanya komponen lalai akan digunakan - te (Threat Emulation).

Untuk membolehkan penyemakan dalam tiga komponen yang tersedia, anda perlu menentukan komponen ini dalam permintaan API.

Contoh permintaan dengan daftar masuk av, te dan pengekstrakan

{ "request":  [  

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

Kekunci dalam bahagian te

imej — senarai yang mengandungi kamus dengan id dan nombor semakan sistem pengendalian di mana semakan akan dilakukan. ID dan nombor semakan adalah sama untuk semua peranti tempatan dan awan.

Senarai sistem pengendalian dan semakan

ID Imej OS Tersedia

Revisi

OS dan Aplikasi Imej

e50e99f3-5963-4573-af9e-e3f4750b55e2

1

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

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

1

Microsoft Windows: 7 - 32bit
Pejabat: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Pasangkan& ActiveX)
Java Runtime: 1.6.0u0

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

1

Microsoft Windows: 7 - 32bit
Pejabat: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Pasangkan & ActiveX)
Java Runtime: 1.7.0u0

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

1

Microsoft Windows: 7 - 32bit
Pejabat: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Pasangkan & ActiveX)
Java Runtime: 1.7.0u9

3ff3ddae-e7fd-4969-818c-d5f1a2be336d

1

Microsoft Windows: 7 - 64bit
Pejabat: 2013 (32bit)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Pasangkan & ActiveX)
Java Runtime: 1.7.0u9

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

 

1 

Microsoft Windows: 8.1 - 64bit
Pejabat: 2013 (64bit)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Pasangkan & ActiveX)
Java Runtime: 1.7.0u9

10b4a9c6-e414-425c-ae8b-fe4dd7b25244 

 

1

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

Jika kunci imej tidak dinyatakan sama sekali, maka emulasi akan berlaku dalam imej yang disyorkan oleh Check Point (kini Win XP dan Win 7). Imej ini disyorkan berdasarkan pertimbangan keseimbangan prestasi terbaik dan kadar tangkapan.

laporan — senarai laporan yang kami minta sekiranya fail itu ternyata berniat jahat. Pilihan berikut tersedia:

  1. ringkasan - arkib .tar.gz yang mengandungi laporan tentang emulasi oleh semua imej yang diminta (kedua-dua halaman html dan komponen seperti video daripada OS emulator, pembuangan trafik rangkaian, laporan dalam json dan sampel itu sendiri dalam arkib yang dilindungi kata laluan). Kami sedang mencari kunci dalam jawapan - ringkasan laporan untuk memuat turun laporan seterusnya.

  2. pdf - dokumen tentang emulasi dalam satu imej, yang biasa diterima ramai melalui Konsol Pintar. Kami sedang mencari kunci dalam jawapan - pdf_laporan untuk memuat turun laporan seterusnya.

  3. xml - dokumen tentang emulasi dalam satu imej, sesuai untuk penghuraian parameter seterusnya dalam laporan. Kami sedang mencari kunci dalam jawapan - xml_report untuk memuat turun laporan seterusnya.

  4. tar - arkib .tar.gz yang mengandungi laporan tentang emulasi dalam satu imej yang diminta (kedua-dua halaman html dan komponen seperti video daripada OS emulator, pembuangan trafik rangkaian, laporan dalam json dan sampel itu sendiri dalam arkib yang dilindungi kata laluan). Kami sedang mencari kunci dalam jawapan - laporan_penuh untuk memuat turun laporan seterusnya.

Что внутри отчета summaryInteraksi dengan Check Point SandBlast melalui API

Kekunci full_report, pdf_report, xml_report ada dalam kamus untuk setiap 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."
        }
      }
    }
  ]
}

Tetapi kunci summary_report - ada satu untuk emulasi secara umum

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

Anda boleh meminta laporan tar dan xml dan pdf pada masa yang sama, anda boleh meminta ringkasan dan tar dan xml. Ia tidak akan dapat meminta laporan ringkasan dan pdf pada masa yang sama.

Kekunci dalam bahagian pengekstrakan

Untuk pengekstrakan ancaman, hanya dua kekunci digunakan:

kaedah — pdf (tukar kepada pdf, digunakan secara lalai) atau bersih (membersihkan kandungan aktif).

extracted_parts_codes - senarai kod untuk mengalih keluar kandungan aktif, hanya terpakai untuk kaedah bersih

Kod untuk mengalih keluar kandungan daripada fail

Kod

Penerangan Produk

1025

Objek Berpaut

1026

Makro dan Kod

1034

Hiperpautan Sensitif

1137

Tindakan GoToR PDF

1139

Tindakan Pelancaran PDF

1141

Tindakan URI PDF

1142

Tindakan Bunyi PDF

1143

Aksi Filem PDF

1150

Tindakan JavaScript PDF

1151

Tindakan Hantar Borang PDF

1018

Pertanyaan Pangkalan Data

1019

Objek Tertanam

1021

Cepat Simpan Data

1017

Hartanah Custom

1036

Sifat Statistik

1037

Sifat Ringkasan

Untuk memuat turun salinan yang telah dibersihkan, anda juga perlu membuat permintaan pertanyaan (yang akan dibincangkan di bawah) selepas beberapa saat, dengan menyatakan jumlah cincang fail dan komponen pengekstrakan dalam teks permintaan. Anda boleh mengambil fail yang dibersihkan menggunakan id daripada respons kepada pertanyaan - extracted_file_download_id. Sekali lagi, melihat ke hadapan sedikit, saya memberikan contoh permintaan dan respons pertanyaan untuk mencari id untuk memuat turun dokumen yang telah dibersihkan.

Permintaan pertanyaan untuk mencari kunci extracted_file_download_id

{ "request":  [  

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

Respons kepada pertanyaan (cari kunci 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."
                }
            }
        }
    ]
}

Tinjauan

Dalam satu panggilan API, anda boleh menghantar hanya satu fail untuk pengesahan.

Komponen av tidak memerlukan bahagian tambahan dengan kunci; ia cukup untuk menyatakannya dalam kamus ciri-ciri.

Pertanyaan panggilan API

Kaedah yang digunakan − SELEPAS

Alamat panggilan - https:///tecloud/api/v1/file/query

Перед тем как отправлять файл на загрузку (запрос upload), желательно выполнить проверку кэша песочницы (запрос query) в целях оптимизации нагрузки на API сервер, так как возможно на API сервере уже есть информация и вердикт по загружаемому файлу. Вызов состоит только из текстовой части. Обязательная часть запроса — sha1/sha256/md5 hash сумма файла. Её кстати можно получить в ответе на запрос upload.

Minimum diperlukan untuk pertanyaan

HTTP POST

https:///tecloud/api/v1/file/query

Tajuk:

Kebenaran:

Badan

{

"permintaan": {

"sha256":

}

}

Contoh respons kepada permintaan muat naik, yang mana jumlah cincang sha1/md5/sha256 kelihatan

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

Permintaan pertanyaan, sebagai tambahan kepada amaun cincang, sebaiknya sama seperti permintaan muat naik dahulu (atau dirancang), malah "sudah" (mengandungi lebih sedikit medan dalam permintaan pertanyaan berbanding permintaan muat naik). Sekiranya permintaan pertanyaan mengandungi lebih banyak medan daripada permintaan muat naik, anda tidak akan menerima semua maklumat yang diperlukan dalam jawapan.

Berikut ialah contoh respons kepada pertanyaan yang tidak semua data yang diperlukan ditemui

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

Perhatikan ladang kod и label. Данные поля встречаются три раза в словарях status. Вначале видим глобальный ключ «code»: 1006 и «label»: «PARTIALLY_FOUND». Далее данные ключи встречаются по каждому отдельному компоненту, которые мы запросили — te и extraction. И если для te понятно, что данные найдены, то для extraction информация отсутствует.

Inilah rupa pertanyaan untuk contoh di atas

{ "request":  [  

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

Jika anda menghantar permintaan pertanyaan tanpa komponen pengekstrakan

{ "request":  [  

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

Kemudian jawapannya akan mengandungi maklumat lengkap ("kod": 1001, "label": "DIJUMPA")

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

Jika tiada maklumat dalam cache sama sekali, maka respons akan menjadi "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."
        }
      }
    }
  ]
}

Dalam satu panggilan API, anda boleh menghantar beberapa jumlah cincang serentak untuk pengesahan. Respons akan mengembalikan data dalam susunan yang sama seperti yang dihantar dalam permintaan.

Contoh permintaan pertanyaan dengan beberapa jumlah sha256

{ "request":  [  

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

Respons kepada pertanyaan dengan berbilang jumlah sha256

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

Meminta beberapa jumlah cincang serentak dalam permintaan pertanyaan juga akan mempunyai kesan yang baik terhadap prestasi pelayan API.

Muat turun panggilan API

Kaedah yang digunakan − SELEPAS (mengikut dokumentasi), GET juga berfungsi (dan mungkin kelihatan lebih logik)

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

Pengepala memerlukan kunci API untuk diluluskan, kandungan permintaan kosong, id muat turun dihantar dalam alamat url.

Sebagai tindak balas kepada permintaan pertanyaan, jika emulasi selesai dan laporan diminta semasa memuat turun fail, id untuk memuat turun laporan akan kelihatan. Jika salinan yang dibersihkan diminta, anda harus mencari id untuk memuat turun dokumen yang telah dibersihkan.

Secara keseluruhan, kunci dalam jawapan kepada pertanyaan yang mengandungi nilai id untuk dimuatkan boleh:

  • ringkasan laporan

  • laporan_penuh

  • pdf_laporan

  • xml_report

  • extracted_file_download_id

Sudah tentu, untuk menerima kunci ini sebagai tindak balas kepada permintaan pertanyaan, ia mesti dinyatakan dalam permintaan (untuk laporan) atau ingat untuk membuat permintaan menggunakan fungsi pengekstrakan (untuk dokumen yang dibersihkan)

Panggilan API Kuota

Kaedah yang digunakan − SELEPAS

Alamat panggilan - https:///tecloud/api/v1/file/quota

Untuk menyemak baki kuota dalam awan, gunakan pertanyaan kuota. Badan permintaan kosong.

Contoh jawapan kepada permintaan kuota

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

API Pencegahan Ancaman untuk Gerbang Keselamatan

API ini telah dibangunkan sebelum API Pencegahan Ancaman dan bertujuan hanya untuk peranti tempatan. Buat masa ini ia hanya boleh berguna jika anda memerlukan API Pengekstrakan Ancaman. Untuk Emulasi Ancaman adalah lebih baik menggunakan API Pencegahan Ancaman biasa. Untuk menghidupkan TP API untuk SG и сконфигурировать API ключ требуется выполнить действия из sk113599. Saya mengesyorkan agar anda memberi perhatian kepada langkah 6b dan menyemak kebolehaksesan halaman https://<IPAddressofSecurityGateway>/UserCheck/TPAPI kerana sekiranya keputusan negatif, konfigurasi selanjutnya tidak masuk akal. Semua panggilan API akan dihantar ke url ini. Jenis panggilan (muat naik/pertanyaan) dikawal dalam kekunci badan panggilan − permintaan_nama. Также обязательными ключами являются - kunci_api (anda perlu mengingatinya semasa proses konfigurasi) dan versi_protokol (versi semasa ialah 1.1). Anda boleh mendapatkan dokumentasi rasmi untuk API ini di sk137032. Kelebihan relatif termasuk keupayaan untuk menghantar beberapa fail sekaligus untuk emulasi semasa memuatkannya, kerana fail dihantar sebagai rentetan teks base64. Untuk mengekod/menyahkod fail ke/dari base64 anda boleh menggunakan penukar dalam talian di Posman untuk tujuan demonstrasi, contohnya - https://base64.guru. В практических целях при написании кода следует использовать встроенные методы encode и decode.

Sekarang mari kita lihat lebih dekat pada fungsi te и pengekstrakan dalam API ini.

Untuk komponen te kamus disediakan te_options dalam permintaan muat naik/pertanyaan, dan kekunci dalam permintaan ini bertepatan sepenuhnya dengan kekunci te masuk API Pencegahan Ancaman.

Contoh permintaan untuk emulasi fail dalam Win10 dengan laporan

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

Untuk komponen pengekstrakan kamus disediakan scrub_options. Permintaan ini menentukan kaedah pembersihan: tukar kepada PDF, kosongkan kandungan aktif atau pilih mod mengikut profil Pencegahan Ancaman (nama profil ditunjukkan). Perkara yang menarik tentang bertindak balas kepada permintaan API pengekstrakan untuk fail ialah anda mendapat salinan yang telah dibersihkan dalam tindak balas kepada permintaan itu sebagai rentetan yang disulitkan base64 (anda tidak perlu membuat permintaan pertanyaan dan mencari id untuk dimuat turun dokumen itu)

Contoh permintaan untuk mengosongkan fail

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

Ответ на запрос

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

Walaupun fakta bahawa permintaan API yang lebih sedikit diperlukan untuk mendapatkan salinan yang dikosongkan, saya dapati pilihan ini kurang disukai dan mudah daripada permintaan data borang yang digunakan dalam API Pencegahan Ancaman.

Koleksi Posmen

Saya mencipta koleksi dalam Postman untuk API Pencegahan Ancaman dan API Pencegahan Ancaman untuk Gerbang Keselamatan, yang mewakili permintaan API yang paling biasa. Agar API dan kunci ip/url pelayan digantikan secara automatik kepada permintaan, dan jumlah cincangan sha256 diingati selepas memuat turun fail, tiga pembolehubah telah dibuat di dalam koleksi (anda boleh mencarinya dengan pergi ke tetapan koleksi Edit -> Pembolehubah): te_api (diperlukan), api_key (diperlukan untuk diisi, kecuali apabila menggunakan TP API dengan peranti tempatan), sha256 (biarkan kosong, tidak digunakan dalam TP API untuk SG).

Muat turun koleksi Postman untuk API Pencegahan Ancaman

Muat turun koleksi Posmen untuk Pencegahan Ancaman untuk API Gerbang Keselamatan

Contoh Penggunaan

Dalam komuniti Semak Rakan skrip yang ditulis dalam Python dibentangkan yang menyemak fail dari direktori yang dikehendaki melalui API TPDan TP API untuk SG. Melalui interaksi dengan API Pencegahan Ancaman, keupayaan anda untuk mengimbas fail diperluaskan dengan ketara, memandangkan kini anda boleh mengimbas fail dalam beberapa platform sekaligus (mendaftar masuk API VirusTotal, dan kemudian dalam kotak pasir Check Point), dan terima fail bukan sahaja daripada trafik rangkaian, tetapi juga mengambilnya daripada mana-mana pemacu rangkaian dan, sebagai contoh, sistem CRM.

Sumber: www.habr.com

Tambah komen