هذه المقالة ستكون مفيدة لأولئك الذين هم على دراية بالتكنولوجيا نقطة تفتيش عن طريق مضاهاة الملف (مضاهاة التهديد) والتنظيف الاستباقي للملفات (استخراج التهديد) ويريد اتخاذ خطوة نحو أتمتة هذه المهام. نقطة التفتيش لديها ، والذي يعمل في السحابة وعلى الأجهزة المحلية، و من الناحية الوظيفية، فهو مطابق للتحقق من الملفات في تدفقات حركة مرور الويب/smtp/ftp/smb/nfs. هذه المقالة هي جزئيًا تفسير المؤلف لمجموعة من المقالات من الوثائق الرسمية، ولكنها مبنية على تجربتي التشغيلية والأمثلة الخاصة بي. ستجد أيضًا في المقالة مجموعات Postman الخاصة بالمؤلف للعمل مع Threat Prevention API.
الاختصارات الأساسية
تعمل واجهة API لمنع التهديدات مع ثلاثة مكونات رئيسية، يتم استدعاؤها في واجهة برمجة التطبيقات من خلال القيم النصية التالية:
av — مكون مكافحة الفيروسات، المسؤول عن تحليل التوقيع للتهديدات المعروفة.
te - مكون محاكاة التهديدات، المسؤول عن فحص الملفات في وضع الحماية، وإصدار حكم ضار/حميد بعد المحاكاة.
استخلاص - مكون استخراج التهديدات، المسؤول عن تحويل مستندات المكتب بسرعة إلى نموذج آمن (حيث تتم إزالة جميع المحتويات الضارة المحتملة)، من أجل تسليمها بسرعة إلى المستخدمين/الأنظمة.
هيكل API والقيود الرئيسية
تستخدم واجهة برمجة التطبيقات لمنع التهديدات 4 طلبات فقط - التحميل والاستعلام والتنزيل والحصة النسبية. في رأس جميع الطلبات الأربعة، تحتاج إلى تمرير مفتاح واجهة برمجة التطبيقات (API) باستخدام المعلمة ترخيص. للوهلة الأولى، قد يبدو الهيكل أبسط بكثير مما كانت عليه في ولكن عدد الحقول في طلبات التحميل والاستعلام وبنية هذه الطلبات معقدة للغاية. يمكن مقارنتها وظيفيًا بملفات تعريف منع التهديدات في سياسة أمان البوابة/صندوق الحماية.
في الوقت الحالي، تم إصدار الإصدار الوحيد من واجهة برمجة التطبيقات لمنع التهديدات - 1.0؛ ويجب أن يتضمن عنوان URL لاستدعاءات واجهة برمجة التطبيقات v1 في الجزء الذي تحتاج إلى تحديد الإصدار فيه. على عكس واجهة برمجة تطبيقات الإدارة، من الضروري الإشارة إلى إصدار واجهة برمجة التطبيقات في عنوان URL، وإلا فلن يتم تنفيذ الطلب.
عند استدعاء مكون مكافحة الفيروسات دون مكونات أخرى (te، الاستخراج)، فإنه يدعم حاليًا فقط طلبات الاستعلام التي تحتوي على مجموع تجزئة md5. تدعم محاكاة التهديد واستخراج التهديد أيضًا مجموعتي التجزئة sha1 وsha256.
من المهم جدًا عدم ارتكاب الأخطاء في الاستعلامات! يمكن تنفيذ الطلب دون أخطاء، ولكن ليس بشكل كامل. بالنظر إلى الأمام قليلاً، دعونا نلقي نظرة على ما يمكن أن يحدث عند وجود أخطاء/أخطاء مطبعية في الاستعلامات.
الطلب به خطأ مطبعي في كلمة تقارير(تقارير)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}لن يكون هناك خطأ في الرد، ولكن لن تكون هناك معلومات حول التقارير على الإطلاق
{
"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."
}
}
}
]
}ولكن بالنسبة لطلب بدون خطأ مطبعي في مفتاح التقارير
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}نتلقى ردًا يحتوي بالفعل على معرف تنزيل التقارير
{
"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."
}
}
}
]
}إذا أرسلنا مفتاح API غير صحيح/منتهي الصلاحية، فسنتلقى خطأ 403 ردًا على ذلك.
SandBlast API: في السحابة وعلى الأجهزة المحلية
يمكن إرسال طلبات واجهة برمجة التطبيقات (API) إلى أجهزة Check Point التي تم تمكين مكون محاكاة التهديد (الشفرة). كعنوان للطلبات، يجب عليك استخدام عنوان IP/url الخاص بالجهاز والمنفذ 18194 (على سبيل المثال، https://10.10.57.19:18194/tecloud/api/v1/file/query). يجب عليك أيضًا التأكد من أن سياسة الأمان الموجودة على الجهاز تسمح بمثل هذا الاتصال. التفويض عبر مفتاح API على الأجهزة المحلية بشكل افتراضي إيقاف وقد لا يتم إرسال مفتاح التفويض الموجود في رؤوس الطلبات على الإطلاق.
ينبغي إرسال طلبات API إلى سحابة CheckPoint إلى te.checkpoint.com (على سبيل المثال - https://te.checkpoint.com/tecloud/api/v1/file/query). يمكن الحصول على مفتاح API كترخيص تجريبي لمدة 60 يومًا عن طريق الاتصال بشركاء Check Point أو المكتب المحلي للشركة.
على الأجهزة المحلية، لا يتم حتى الآن دعم ميزة "استخراج التهديدات" بشكل قياسي. وينبغي استخدامها (سنتحدث عنها بمزيد من التفصيل في نهاية المقال).
الأجهزة المحلية لا تدعم طلب الحصة النسبية.
وبخلاف ذلك، لن تكون هناك اختلافات بين الطلبات المقدمة إلى الأجهزة المحلية والطلبات السحابية.
تحميل استدعاء API
الطريقة المستخدمة - سأعين
عنوان الاتصال - https:///tecloud/api/v1/file/upload
يتكون الطلب من جزأين (بيانات النموذج): ملف مخصص للمضاهاة/التنظيف ونص الطلب مع النص.
لا يمكن أن يكون الطلب النصي فارغًا، لكنه لا يجوز أن يحتوي على أي تكوين. لكي ينجح الطلب، يجب عليك إرسال النص التالي على الأقل في الطلب:
الحد الأدنى المطلوب لطلب التحميل
بريد HTTP
https:///tecloud/api/v1/file/upload
رؤوس:
تفويض:
الجسم
{
"طلب": {
}
}
قم بتقديم
قم بتقديم
في هذه الحالة، ستتم معالجة الملف وفقًا للمعلمات الافتراضية: المكون - teصور نظام التشغيل - فوز XP وفوز 7، دون إنشاء تقرير.
التعليقات على الحقول الرئيسية في طلب النص:
اسم_الملف и نوع الملف يمكنك تركها فارغة أو عدم إرسالها على الإطلاق، لأن هذه ليست معلومات مفيدة بشكل خاص عند تحميل ملف. في استجابة واجهة برمجة التطبيقات (API)، سيتم ملء هذه الحقول تلقائيًا بناءً على اسم الملف الذي تم تنزيله، وسيظل يتعين البحث عن المعلومات الموجودة في ذاكرة التخزين المؤقت باستخدام كميات التجزئة md5/sha1/sha256.
طلب مثال مع اسم_ملف فارغ ونوع_ملف
{
"request": {
"file_name": "",
"file_type": "",
}
}ملامح — قائمة تشير إلى الوظائف الضرورية عند المعالجة في وضع الحماية - av (مكافحة الفيروسات)، te (محاكاة التهديد)، الاستخراج (استخراج التهديد). إذا لم يتم تمرير هذه المعلمة على الإطلاق، فسيتم استخدام المكون الافتراضي فقط - te (محاكاة التهديد).
لتمكين التحقق من المكونات الثلاثة المتوفرة، تحتاج إلى تحديد هذه المكونات في طلب API.
مثال على طلب مع التحقق من av، te والاستخراج
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}المفاتيح في قسم te
صور - قائمة تحتوي على قواميس مع معرف ورقم المراجعة لأنظمة التشغيل التي سيتم إجراء الفحص فيها. المعرفات وأرقام المراجعة هي نفسها بالنسبة لجميع الأجهزة المحلية والسحابة.
قائمة أنظمة التشغيل والمراجعات
معرف صورة نظام التشغيل المتاح
تنقيح
نظام تشغيل الصور والتطبيق
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
مايكروسوفت ويندوز: XP - 32 بت SP3
Office: 2003، 2007
أدوبي أكروبات ريدر: 9.0
فلاش بلاير 9r115 و اكتف 10.0
جافا وقت التشغيل: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
مايكروسوفت ويندوز: 7 - 32 بت
Office: 2003، 2007
أدوبي أكروبات ريدر: 9.0
مشغل الفلاش: 10.2r152 (المساعد& اكتف)
جافا وقت التشغيل: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
مايكروسوفت ويندوز: 7 - 32 بت
Office: 2010
أدوبي أكروبات ريدر: 9.4
مشغل الفلاش: 11.0.1.152 (المساعد & اكتف)
جافا وقت التشغيل: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
مايكروسوفت ويندوز: 7 - 32 بت
Office: 2013
أدوبي أكروبات ريدر: 11.0
مشغل الفلاش: 15 (المساعد & اكتف)
جافا وقت التشغيل: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
مايكروسوفت ويندوز: 7 - 64 بت
Office: 2013 (32 بت)
أدوبي أكروبات ريدر: 11.0.01
مشغل الفلاش: 13 (المساعد & اكتف)
جافا وقت التشغيل: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
مايكروسوفت ويندوز: 8.1 - 64 بت
Office: 2013 (64 بت)
أدوبي أكروبات ريدر: 11.0.10
مشغل الفلاش: 18.0.0.160 (المساعد & اكتف)
جافا وقت التشغيل: 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
مايكروسوفت ويندوز: 10
Office: Professional Plus 2016 باللغة الإنجليزية
أدوبي أكروبات ريدر: واجهة المستخدم المتعددة اللغات DC 2015
مشغل الفلاش: 20 (المساعد & اكتف)
جافا وقت التشغيل: 1.7.0u9
إذا لم يتم تحديد مفتاح الصور على الإطلاق، فسيتم إجراء المحاكاة في الصور الموصى بها بواسطة Check Point (حاليًا Win XP وWin 7). يوصى بهذه الصور بناءً على الاعتبارات المتعلقة بأفضل توازن بين الأداء ومعدل الالتقاط.
تقارير - قائمة التقارير التي نطلبها في حالة تبين أن الملف ضار. الخيارات التالية متاحة:
-
ملخص - أرشيف .tar.gz يحتوي على تقرير عن المحاكاة بواسطة جميع الصور المطلوبة (صفحة html ومكونات مثل فيديو من نظام التشغيل المحاكي، وتفريغ حركة مرور الشبكة، وتقرير بتنسيق json، والعينة نفسها في أرشيف محمي بكلمة مرور). نحن نبحث عن المفتاح في الجواب - تقرير ملخص لتحميل التقرير لاحقا
-
النسخة الإلكترونية pdf - وثيقة حول مضاهاة في واحد الصورة التي اعتاد الكثيرون على تلقيها من خلال Smart Console. نحن نبحث عن المفتاح في الجواب - pdf_report لتحميل التقرير لاحقا
-
XML - وثيقة حول مضاهاة في واحد صورة ملائمة للتحليل اللاحق للمعلمات في التقرير. نحن نبحث عن المفتاح في الجواب - xml_report لتحميل التقرير لاحقا
-
قطران - أرشيف .tar.gz يحتوي على تقرير عن المحاكاة في واحد الصور المطلوبة (صفحة html ومكونات مثل فيديو من نظام التشغيل المحاكي، وتفريغ حركة مرور الشبكة، وتقرير بتنسيق json، والعينة نفسها في أرشيف محمي بكلمة مرور). نحن نبحث عن المفتاح في الجواب - تقرير كامل لتحميل التقرير لاحقا
ماذا يوجد داخل التقرير الموجز
المفاتيح full_report، وpdf_report، وxml_report موجودة في القاموس الخاص بكل نظام تشغيل
{
"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."
}
}
}
]
}لكن مفتاح Summary_report - يوجد مفتاح للمحاكاة بشكل عام
{
"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."
}
}
}
]
}يمكنك طلب تقارير tar وxml وpdf في نفس الوقت، ويمكنك طلب ملخص وتقارير tar وxml. لن يكون من الممكن طلب تقرير ملخص وملف pdf في نفس الوقت.
المفاتيح في قسم الاستخراج
لاستخراج التهديد، يتم استخدام مفتاحين فقط:
طريقة - pdf (التحويل إلى pdf، يُستخدم بشكل افتراضي) أو نظيف (تنظيف المحتوى النشط).
extracted_parts_codes - قائمة رموز إزالة المحتوى النشط، تنطبق فقط على الطريقة النظيفة
رموز لإزالة المحتوى من الملفات
رمز
الوصف
1025
كائنات مرتبطة
1026
وحدات الماكرو والكود
1034
الارتباطات التشعبية الحساسة
1137
إجراءات PDF GoToR
1139
إجراءات إطلاق PDF
1141
إجراءات PDF URI
1142
إجراءات PDF الصوتية
1143
إجراءات فيلم PDF
1150
إجراءات جافا سكريبت في PDF
1151
PDF إرسال إجراءات النموذج
1018
استعلامات قاعدة البيانات
1019
كائنات مضمنة
1021
حفظ سريع للبيانات
1017
خصائص مخصصة
1036
الخصائص الإحصائية
1037
خصائص الملخص
لتنزيل نسخة نظيفة، ستحتاج أيضًا إلى تقديم طلب استعلام (سيتم مناقشته أدناه) بعد بضع ثوانٍ، مع تحديد مقدار تجزئة الملف ومكون الاستخراج في نص الطلب. يمكنك التقاط الملف الذي تم تنظيفه باستخدام المعرف من الرد على الاستعلام - extracted_file_download_id. مرة أخرى، وبالنظر إلى الأمام قليلاً، أقدم أمثلة على طلب واستجابة استعلام للبحث عن معرف لتنزيل مستند تم مسحه.
طلب استعلام للبحث عن المفتاح extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}الاستجابة للاستعلام (ابحث عن مفتاح 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."
}
}
}
]
}نظرة عامة
في مكالمة API واحدة، يمكنك إرسال ملف واحد فقط للتحقق.
لا يتطلب مكون AV قسمًا إضافيًا به مفاتيح، يكفي تحديده في القاموس ملامح.
استدعاء API الاستعلام
الطريقة المستخدمة - سأعين
عنوان الاتصال - https:///tecloud/api/v1/file/query
قبل إرسال ملف للتنزيل (طلب التحميل)، يُنصح بالتحقق من ذاكرة التخزين المؤقت لصندوق الحماية (طلب استعلام) من أجل تحسين التحميل على خادم API، نظرًا لأن خادم API قد يكون لديه بالفعل معلومات وحكم على الملف الذي تم تنزيله. تتكون المكالمة من جزء نصي فقط. الجزء المطلوب من الطلب هو مقدار تجزئة الملف sha1/sha256/md5. بالمناسبة، يمكنك الحصول عليه في الرد على طلب التحميل.
الحد الأدنى المطلوب للاستعلام
بريد HTTP
https:///tecloud/api/v1/file/query
رؤوس:
تفويض:
الجسم
{
"طلب": {
"sha256":
}
}
مثال على الاستجابة لطلب تحميل، حيث تكون كميات التجزئة sha1/md5/sha256 مرئية
{
"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."
}
}
}
}يجب أن يكون طلب الاستعلام، بالإضافة إلى مبلغ التجزئة، هو نفس طلب التحميل (أو المخطط له)، أو حتى "بالفعل" (يحتوي على حقول أقل في طلب الاستعلام مقارنة بطلب التحميل). في حالة احتواء طلب الاستعلام على حقول أكثر مما كانت عليه في طلب التحميل، فلن تتلقى جميع المعلومات المطلوبة في الرد.
فيما يلي مثال للاستجابة لاستعلام لم يتم العثور فيه على كافة البيانات المطلوبة
{
"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."
}
}
}
]
}انتبه إلى الحقول الكود и ملصق. تظهر هذه الحقول ثلاث مرات في قواميس الحالة. أولاً نرى "رمز" المفتاح العام: 1006 و"التسمية": "PARTIALLY_FOUND". بعد ذلك، تم العثور على هذه المفاتيح لكل مكون فردي طلبناه - الشركة المصرية للاتصالات والاستخراج. وإذا كان من الواضح أنه تم العثور على البيانات، فلا توجد معلومات للاستخراج.
هذا ما بدا عليه الاستعلام في المثال أعلاه
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}إذا قمت بإرسال طلب استعلام بدون مكون الاستخراج
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}ثم ستحتوي الإجابة على معلومات كاملة ("الرمز": 1001، "التسمية": "تم العثور عليه")
{
"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."
}
}
}
]
}إذا لم تكن هناك معلومات في ذاكرة التخزين المؤقت على الإطلاق، فسيكون الرد هو "التسمية": "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."
}
}
}
]
}في استدعاء واحد لواجهة برمجة التطبيقات (API)، يمكنك إرسال عدة مبالغ تجزئة مرة واحدة للتحقق. ستعيد الاستجابة البيانات بنفس الترتيب الذي تم إرسالها به في الطلب.
مثال لطلب استعلام بمبالغ sha256 متعددة
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}الرد على استعلام بمبالغ 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."
}
}
}
]
}إن طلب عدة مجموعات تجزئة مرة واحدة في طلب استعلام سيكون له أيضًا تأثير مفيد على أداء خادم API.
تنزيل استدعاء API
الطريقة المستخدمة - سأعين (حسب الوثائق)، للحصول على يعمل أيضًا (وقد يبدو أكثر منطقية)
عنوان الاتصال - https:///tecloud/api/v1/file/download?id=
يتطلب الرأس تمرير مفتاح API، ويكون نص الطلب فارغًا، ويتم تمرير معرف التنزيل في عنوان URL.
ردًا على طلب استعلام، إذا اكتملت المحاكاة وتم طلب التقارير عند تنزيل الملف، فسيكون معرف تنزيل التقارير مرئيًا. إذا تم طلب نسخة نظيفة، فيجب عليك البحث عن المعرف لتنزيل المستند المنظف.
في المجمل، يمكن أن تكون المفاتيح الموجودة في الرد على الاستعلام الذي يحتوي على قيمة المعرف للتحميل:
-
تقرير ملخص
-
تقرير كامل
-
pdf_report
-
xml_report
-
extracted_file_download_id
بالطبع، من أجل الحصول على هذه المفاتيح استجابة لطلب الاستعلام، يجب تحديدها في الطلب (للتقارير) أو تذكر تقديم طلب باستخدام وظيفة الاستخراج (للمستندات المنظفة)
استدعاء الحصة API
الطريقة المستخدمة - سأعين
عنوان الاتصال - https:///tecloud/api/v1/file/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 Extraction API. بالنسبة لمحاكاة التهديدات، من الأفضل استخدام واجهة برمجة تطبيقات منع التهديدات العادية. لتشغيل TP API لSG وقم بتكوين مفتاح API الذي تحتاج إلى اتباع الخطوات منه . أوصي بالاهتمام بالخطوة 6 ب والتحقق من إمكانية الوصول إلى الصفحة https://<IPAddressofSecurityGateway>/UserCheck/TPAPI لأنه في حالة وجود نتيجة سلبية، مزيد من التكوين لا معنى له. سيتم إرسال كافة استدعاءات واجهة برمجة التطبيقات (API) إلى عنوان url هذا. يتم تنظيم نوع المكالمة (تحميل/استعلام) في مفتاح نص المكالمة - request_name. المفاتيح المطلوبة أيضا هي - مفتاح API (عليك أن تتذكره أثناء عملية التكوين) و Protocol_version (الإصدار الحالي هو 1.1). يمكنك العثور على الوثائق الرسمية لواجهة برمجة التطبيقات هذه على . تشمل المزايا النسبية القدرة على إرسال عدة ملفات مرة واحدة للمحاكاة عند تحميلها، حيث يتم إرسال الملفات كسلسلة نصية base64. لتشفير/فك تشفير الملفات إلى/من base64، يمكنك استخدام محول عبر الإنترنت في Postman لأغراض العرض التوضيحي، على سبيل المثال - . لأغراض عملية، يجب عليك استخدام أساليب التشفير وفك التشفير المضمنة عند كتابة التعليمات البرمجية.
الآن دعونا نلقي نظرة فاحصة على الوظائف te и استخلاص في واجهة برمجة التطبيقات هذه.
للمكون te القاموس المقدمة te_options في طلبات التحميل/الاستعلام، وتتطابق المفاتيح الموجودة في هذا الطلب تمامًا مع المفاتيح الموجودة في .
طلب مثال لمحاكاة الملفات في Win10 مع التقارير
{
"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"]
}
}
]
}للمكون استخلاص القاموس المقدمة scrub_options. يحدد هذا الطلب طريقة التنظيف: التحويل إلى PDF، أو مسح المحتوى النشط، أو تحديد الوضع وفقًا لملف تعريف منع التهديدات (يُشار إلى اسم ملف التعريف). إن الشيء العظيم في الاستجابة لطلب استخراج API لملف ما هو أنك تحصل على النسخة المنظفة في الاستجابة لهذا الطلب كسلسلة مشفرة base64 (لا تحتاج إلى تقديم طلب استعلام والبحث عن المعرف للتنزيل المستند)
مثال على طلب مسح ملف
{
"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": ""
}
}]
} على الرغم من حقيقة أن هناك عددًا أقل من طلبات واجهة برمجة التطبيقات (API) المطلوبة للحصول على نسخة واضحة، إلا أنني أجد هذا الخيار أقل تفضيلاً وملاءمة من طلب بيانات النموذج المستخدم في .
مجموعات ساعي البريد
لقد قمت بإنشاء مجموعات في Postman لكل من واجهة برمجة تطبيقات منع التهديدات وواجهة برمجة تطبيقات منع التهديدات لبوابة الأمان، والتي تمثل طلبات واجهة برمجة التطبيقات الأكثر شيوعًا. من أجل استبدال خادم ip/url API والمفتاح تلقائيًا في الطلبات، وتذكر مبلغ تجزئة sha256 بعد تنزيل الملف، تم إنشاء ثلاثة متغيرات داخل المجموعات (يمكنك العثور عليها بالذهاب إلى إعدادات المجموعة تحرير -> المتغيرات): te_api (مطلوب), api_key (مطلوب ملؤه، إلا عند استخدام TP API مع الأجهزة المحلية), sha256 (اتركه فارغًا، غير مستخدم في TP API لـ SG).
أمثلة على الاستخدام
في المجتمع يتم تقديم البرامج النصية المكتوبة بلغة Python والتي تقوم بفحص الملفات من الدليل المطلوب عبر و . من خلال التفاعل مع واجهة برمجة تطبيقات منع التهديدات، يتم توسيع قدرتك على فحص الملفات بشكل كبير، حيث يمكنك الآن فحص الملفات في عدة منصات في وقت واحد (تسجيل الوصول ، ثم في وضع الحماية Check Point)، واستلام الملفات ليس فقط من حركة مرور الشبكة، ولكن أيضًا أخذها من أي محركات أقراص شبكة، وعلى سبيل المثال، أنظمة CRM.
المصدر: www.habr.com