🥇אינטראקציה עם Check Point SandBlast באמצעות API

מאמר זה יהיה שימושי למי שמכיר את הטכנולוגיה צק פוינט על ידי אמולציית קבצים (חיקוי איום) וניקוי קבצים יזום (חילוץ איומים) ורוצה לעשות צעד לקראת אוטומציה של משימות אלו. לצ'ק פוינט יש API למניעת איומים, הפועל גם בענן וגם במכשירים מקומיים, ו מבחינה פונקציונלית זה זהה לבדיקת קבצים בזרמי תנועה באינטרנט/smtp/ftp/smb/nfs. מאמר זה הוא בחלקו הפרשנות של המחבר לקבוצת מאמרים מהתיעוד הרשמי, אך מבוסס על ניסיון ההפעלה שלי והדוגמאות שלי. כמו כן במאמר תמצאו את אוספי Postman של המחבר לעבודה עם ה-API למניעת איומים.

קיצורים בסיסיים

ה-API למניעת איומים עובד עם שלושה רכיבים עיקריים, הנקראים ב-API דרך ערכי הטקסט הבאים:

av - רכיב אנטי וירוס, אחראי על ניתוח חתימות של איומים ידועים.

te - רכיב אמולציית איומים, אחראי על בדיקת קבצים בארגז החול, וביצוע פסק דין זדוני/שפיר לאחר אמולציה.

הוֹצָאָה - רכיב חילוץ איומים, אחראי להמרה מהירה של מסמכי משרד לצורה בטוחה (בה כל התוכן שעלול להיות זדוני מוסר), על מנת להעביר אותם במהירות למשתמשים/מערכות.

מבנה API ומגבלות עיקריות

API למניעת איומים משתמש רק ב-4 בקשות - העלאה, שאילתה, הורדה ומכסה. בכותרת של כל ארבע הבקשות עליך להעביר את מפתח ה-API באמצעות הפרמטר הרשאה. במבט ראשון, המבנה עשוי להיראות הרבה יותר פשוט מאשר בפנים ניהול API, אך מספר השדות בבקשות ההעלאה והשאילתה והמבנה של בקשות אלו מורכבים למדי. ניתן להשוות אלה באופן פונקציונלי לפרופילי מניעת איומים במדיניות אבטחה של שער/ארגז חול.

נכון לעכשיו, הגרסה היחידה של ה-API למניעת איומים שוחררה - 1.0; כתובת ה-URL עבור קריאות API צריכה לכלול v1 בחלק שבו אתה צריך לציין את הגרסה. בניגוד לניהול API, יש צורך לציין את גרסת ה-API ב-URL, אחרת הבקשה לא תבוצע.

רכיב האנטי וירוס, כאשר נקרא ללא רכיבים אחרים (te, חילוץ), תומך כרגע רק בבקשות שאילתות עם סכומי hash של md5. אמולציית איומים וחילוץ איומים תומכים גם בסכומי hash sha1 ו-sha256.

חשוב מאוד לא לעשות טעויות בשאילתות! ניתן לבצע את הבקשה ללא שגיאה, אך לא במלואה. במבט מעט קדימה, בואו נסתכל מה יכול לקרות כשיש שגיאות/שגיאות כתיב בשאילתות.

בקשה עם שגיאת הקלדה עם המילה reports(reportss)

{ "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 למכשירי צ'ק פוינט שרכיב הדמיית איומים (להב) מופעל בהם. ככתובת לבקשות, עליך להשתמש ב-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 יום על ידי פנייה לשותפים של צ'ק פוינט או למשרד המקומי של החברה.

במכשירים מקומיים, חילוץ איומים עדיין לא נתמך כסטנדרט. API למניעת איומים וצריך להשתמש בו API למניעת איומים עבור שער אבטחה (נדבר על זה ביתר פירוט בסוף המאמר).

מכשירים מקומיים אינם תומכים בבקשת המכסה.

אחרת, אין הבדלים בין בקשות למכשירים מקומיים ולענן.

העלה קריאת API

השיטה בשימוש - POST

כתובת שיחה - https:///tecloud/api/v1/file/upload

הבקשה מורכבת משני חלקים (טופס-נתונים): קובץ המיועד לאמולציה/ניקוי וגוף בקשה עם טקסט.

בקשת הטקסט לא יכולה להיות ריקה, אך ייתכן שהיא לא תכיל שום תצורה. על מנת שהבקשה תצליח, עליך לשלוח בבקשה את הטקסט הבא לפחות:

נדרש מינימום לבקשת העלאה

פוסט HTTP

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

כותרות:

הרשאה:

גוף

{

"בקשה": {

}

שלח

במקרה זה, הקובץ יעובד בהתאם לפרמטרי ברירת המחדל: רכיב - te, תמונות מערכת הפעלה - זכה ב-XP וב-Win 7, מבלי להפיק דוח.

הערות על השדות העיקריים בבקשת הטקסט:

שם קובץ и סוג קובץ אתה יכול להשאיר אותם ריקים או לא לשלוח אותם בכלל, מכיוון שזה לא מידע שימושי במיוחד בעת העלאת קובץ. בתגובת ה-API, שדות אלו ימולאו אוטומטית על סמך שם הקובץ שהורד, ועדיין יהיה צורך לחפש את המידע במטמון באמצעות כמויות hash md5/sha1/sha256.

בקשה לדוגמה עם file_name וקובץ_type ריקים

{

"request": {

"file_name": "",

"file_type": "",

}

}

מאפיינים — רשימה שמציינת את הפונקציונליות הדרושה בעת עיבוד בארגז החול - av (אנטי וירוס), te (הדמיית איומים), מיצוי (חילוץ איומים). אם פרמטר זה לא יועבר כלל, אזי ישמש רק רכיב ברירת המחדל - te (Emulation Threat).

כדי לאפשר בדיקה של שלושת הרכיבים הזמינים, עליך לציין רכיבים אלה בבקשת ה-API.

דוגמה לבקשה עם צ'ק אין av, te וחילוץ

{ "request":  [  

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

מפתחות בקטע te

תמונות - רשימה המכילה מילונים עם מזהה ומספר גרסת מערכות ההפעלה שבהן תתבצע הבדיקה. מזהים ומספרי גרסאות זהים עבור כל המכשירים המקומיים והענן.

רשימת מערכות הפעלה ותיקונים

מזהה תמונת מערכת הפעלה זמינה

עריכה

מערכת הפעלה תמונה ואפליקציה

e50e99f3-5963-4573-af9e-e3f4750b55e2

Microsoft Windows: XP - 32bit SP3
Office: 2003, 2007
תוכנת Adobe Acrobat Reader: 9.0
נגן פלאש 9r115 ו ActiveX 10.0
זמן ריצה של Java: 1.6.0u22

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

Microsoft Windows: 7 - 32 סיביות
Office: 2003, 2007
תוכנת Adobe Acrobat Reader: 9.0
נגן פלאש: 10.2r152 (חיבור& ActiveX)
זמן ריצה של Java: 1.6.0u0

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

Microsoft Windows: 7 - 32 סיביות
Office: 2010
תוכנת Adobe Acrobat Reader: 9.4
נגן פלאש: 11.0.1.152 (חיבור & ActiveX)
זמן ריצה של Java: 1.7.0u0

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

Microsoft Windows: 7 - 32 סיביות
Office: 2013
תוכנת Adobe Acrobat Reader: 11.0
נגן פלאש: 15 (חיבור & ActiveX)
זמן ריצה של Java: 1.7.0u9

3ff3ddae-e7fd-4969-818c-d5f1a2be336d

Microsoft Windows: 7 - 64 סיביות
Office: 2013 (32 סיביות)
תוכנת Adobe Acrobat Reader: 11.0.01
נגן פלאש: 13 (חיבור & ActiveX)
זמן ריצה של Java: 1.7.0u9

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

Microsoft Windows: 8.1 - 64 סיביות
Office: 2013 (64 סיביות)
תוכנת Adobe Acrobat Reader: 11.0.10
נגן פלאש: 18.0.0.160 (חיבור & ActiveX)
זמן ריצה של Java: 1.7.0u9

10b4a9c6-e414-425c-ae8b-fe4dd7b25244

Microsoft Windows: 10
Office: Professional Plus 2016 en-us
תוכנת Adobe Acrobat Reader: DC 2015 MUI
נגן פלאש: 20 (חיבור & ActiveX)
זמן ריצה של Java: 1.7.0u9

אם מפתח התמונות לא צוין כלל, אמולציה תתבצע בתמונות המומלצות על ידי צ'ק פוינט (כרגע Win XP ו-Win 7). תמונות אלו מומלצות על סמך שיקולים של האיזון הטוב ביותר בין ביצועים וקצב תפיסה.

דיווחים - רשימה של דיווחים שאנו מבקשים למקרה שהתיק יתברר כזדוני. האפשרויות הבאות זמינות:

תקציר - ארכיון .tar.gz המכיל דוח על אמולציה מאת כל תמונות מבוקשות (הן דף HTML והן רכיבים כגון סרטון ממערכת ההפעלה של האמולטור, dump תעבורה ברשת, דוח ב-json והדוגמה עצמה בארכיון מוגן בסיסמה). אנחנו מחפשים את המפתח בתשובה - דוח מסכם להורדה הבאה של הדוח.
PDF - מסמך על אמולציה ב אחת תמונה, שרבים רגילים לקבל דרך ה-Smart Console. אנחנו מחפשים את המפתח בתשובה - pdf_report להורדה הבאה של הדוח.
xml - מסמך על אמולציה ב אחת תמונה, נוחה לניתוח לאחר מכן של פרמטרים בדוח. אנחנו מחפשים את המפתח בתשובה - xml_report להורדה הבאה של הדוח.
זפת - ארכיון .tar.gz המכיל דוח על אמולציה ב אחת תמונות מבוקשות (הן דף HTML והן רכיבים כגון סרטון ממערכת ההפעלה של האמולטור, dump תעבורה ברשת, דוח ב-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, בשימוש כברירת מחדל) או נקי (ניקוי תוכן פעיל).

codes_parts_extracted - רשימת קודים להסרת תוכן פעיל, מתאימה רק לשיטה הנקייה

קודים להסרת תוכן מקבצים

קופונים

תיאור

1025

אובייקטים מקושרים

1026

מאקרו וקוד

1034

היפר-קישורים רגישים

1137

PDF פעולות GoToR

1139

פעולות השקת PDF

1141

פעולות URI של PDF

1142

PDF פעולות קול

1143

פעולות סרטי PDF

1150

פעולות JavaScript של PDF

1151

PDF שליחת טופס פעולות

1018

שאילתות על מסד הנתונים

1019

אובייקטים מוטבעים

1021

שמירת נתונים מהירה

1017

מאפיינים מותאמים אישית

1036

מאפיינים סטטיסטיים

1037

מאפייני סיכום

כדי להוריד עותק נקי, תצטרך גם לבצע בקשת שאילתה (עליה נדון בהמשך) לאחר מספר שניות, תוך ציון כמות ה-hash של הקובץ ורכיב החילוץ בטקסט הבקשה. אתה יכול לאסוף את הקובץ הנוקה באמצעות המזהה מהתגובה לשאילתה - 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 של שאילתה

השיטה בשימוש - POST

כתובת שיחה - https:///tecloud/api/v1/file/query

לפני שליחת קובץ להורדה (בקשת העלאה), רצוי לבדוק את מטמון ה-sandbox (בקשת שאילתה) על מנת לייעל את העומס על שרת ה-API, שכן ייתכן שלשרת ה-API כבר יש מידע ופסק דין על הקובץ שהורד. השיחה מורכבת רק מחלק טקסט. החלק הנדרש של הבקשה הוא sha1/sha256/md5 כמות hash של הקובץ. אגב, אתה יכול לקבל את זה בתגובה לבקשת ההעלאה.

מינימום נדרש עבור שאילתה

פוסט HTTP

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

כותרות:

הרשאה:

גוף

{

"בקשה": {

"sha256":

}

דוגמה לתגובה לבקשת העלאה, שבה סכומי hash של 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, "תווית": "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."
        }
      }
    }
  ]
}

אם אין מידע במטמון כלל, התגובה תהיה "תווית": "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, אתה יכול לשלוח כמה סכומי hash בו-זמנית לאימות. התגובה תחזיר נתונים באותו סדר שבו נשלחה בבקשה.

בקשת שאילתה לדוגמה עם מספר סכומי 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."
        }
      }
    }
  ]
}

בקשת מספר סכומי hash בו-זמנית בבקשת שאילתה תשפיע לטובה גם על הביצועים של שרת ה-API.

הורד קריאת API

השיטה בשימוש - POST (על פי תיעוד), לקבל גם עובד (ואולי נראה יותר הגיוני)

כתובת שיחה - https:///tecloud/api/v1/file/download?id=

הכותרת מחייבת את העברת מפתח ה-API, גוף הבקשה ריק, מזהה ההורדה מועבר בכתובת ה-URL.

בתגובה לבקשת שאילתה, אם האמולציה הושלמה וביקשו דוחות בעת הורדת הקובץ, המזהה להורדת דוחות יהיה גלוי. אם מבקשים עותק נקי, עליך לחפש את המזהה כדי להוריד את המסמך הנוקה.

בסך הכל, המפתחות בתגובה לשאילתה המכילה את ערך המזהה לטעינה יכולים להיות:

דוח מסכם
דוח_מלא
pdf_report
xml_report
מזהה_הורדה_קובץ_חלץ

כמובן שכדי לקבל מפתחות אלו בתגובה לבקשת השאילתה, יש לציין אותם בבקשה (לדוחות) או לזכור לבצע בקשה באמצעות פונקציית החילוץ (עבור מסמכים מנוקים)

קריאה ל-Quota API

השיטה בשימוש - POST

כתובת שיחה - 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"
    }
  ]
}

API למניעת איומים עבור שער אבטחה

API זה פותח לפני ה-API למניעת איומים ומיועד רק למכשירים מקומיים. לעת עתה זה יכול להיות שימושי רק אם אתה צריך את ה-API לחילוץ איומים. עבור Threat Emulation עדיף להשתמש ב-API הרגיל למניעת איומים. להדליק TP API עבור SG ולהגדיר את מפתח ה-API שממנו אתה צריך לבצע את השלבים sk113599. אני ממליץ לשים לב לשלב 6ב ולבדוק את נגישות העמוד https://<IPAddressofSecurityGateway>/UserCheck/TPAPI כי במקרה של תוצאה שלילית, תצורה נוספת אינה הגיונית. כל קריאות ה-API יישלחו לכתובת האתר הזו. סוג השיחה (העלאה/שאילתה) מוסדר במקש גוף השיחה - request_name. גם מפתחות נדרשים הם - api_key (עליך לזכור את זה במהלך תהליך ההגדרה) ו protocol_version (כרגע הגרסה הנוכחית היא 1.1). אתה יכול למצוא את התיעוד הרשמי עבור API זה בכתובת sk137032. היתרונות היחסיים כוללים את היכולת לשלוח מספר קבצים בבת אחת לאמולציה בעת טעינתם, שכן הקבצים נשלחים כמחרוזת טקסט base64. כדי לקודד/פענח קבצים מ/אל base64 אתה יכול להשתמש בממיר מקוון ב-Postman למטרות הדגמה, למשל - https://base64.guru. למטרות מעשיות, עליך להשתמש בשיטות הקידוד והפענוח המובנות בעת כתיבת קוד.

עכשיו בואו נסתכל מקרוב על הפונקציות te и הוֹצָאָה ב-API זה.

עבור רכיב te מילון מסופק te_options בבקשות העלאה/שאילתה, והמפתחות בבקשה זו תואמים לחלוטין למפתחות te in API למניעת איומים.

בקשה לדוגמה לאמולציית קבצים ב-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 כדי לקבל עותק מסולק, אני מוצא את האפשרות הזו פחות עדיפה ונוחה מאשר בקשת הטופס-נתונים המשמשת ב- API למניעת איומים.

אוספי הדוור

יצרתי אוספים ב-Postman הן עבור ה-API למניעת איומים והן עבור ה-API למניעת איומים עבור שער אבטחה, המייצגים את בקשות ה-API הנפוצות ביותר. על מנת שה-IP/url API והמפתח של השרת יוחלפו אוטומטית בבקשות, וכמות ה-hash sha256 תיזכר לאחר הורדת הקובץ, נוצרו שלושה משתנים בתוך האוספים (תוכלו למצוא אותם על ידי מעבר להגדרות האוסף עריכה -> משתנים): te_api (חובה), api_key (נדרש למלא, למעט בעת שימוש ב-TP API עם מכשירים מקומיים), sha256 (להשאיר ריק, לא בשימוש ב-TP API עבור SG).

הורד את אוסף Postman עבור API למניעת איומים

הורד את אוסף Postman for Threat Prevention for Security Gateway API

דוגמאות לשימוש

בקהילה בדוק חברים מוצגים סקריפטים שנכתבו ב-Python שבודקים קבצים מהספרייה הרצויה דרך TP APIו - TP API עבור SG. באמצעות אינטראקציה עם ה-API למניעת איומים, יכולתך לסרוק קבצים מורחבת משמעותית, שכן כעת תוכל לסרוק קבצים במספר פלטפורמות בו זמנית (צ'ק-אין VirusTotal API, ולאחר מכן בארגז החול של צ'ק פוינט), ולקבל קבצים לא רק מתעבורת רשת, אלא גם לקחת אותם מכל כונני רשת, למשל, ממערכות CRM.

מקור: www.habr.com

אינטראקציה עם Check Point SandBlast באמצעות API

קיצורים בסיסיים

מבנה API ומגבלות עיקריות

SandBlast API: בענן ובמכשירים מקומיים

העלה קריאת API

מפתחות בקטע te

מפתחות בקטע החילוץ

סקירה

קריאת API של שאילתה

הורד קריאת API

קריאה ל-Quota API

API למניעת איומים עבור שער אבטחה

אוספי הדוור

דוגמאות לשימוש

הוספת תגובה ביטול תגובה