ניהול דוחות אבטחה באמצעות ה-API

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

בדף הזה מוסבר איך ליצור דוחות אבטחה ולהציג אותם באמצעות Security Reports API.

סקירה כללית של דוחות האבטחה, כולל מגבלות, מופיעה במאמר סקירה כללית של דוחות האבטחה. לתיעוד הפניית ה-API של דוחות אבטחה, ראו את הפניית ה-API של דוחות אבטחה.

הערה: הנתונים שזורמים אל צינור הנתונים של Apigee Analytics מגיעים עם עיכוב של 15 עד 20 דקות בממוצע. כתוצאה מכך, דוח אבטחה שזמן הסיום שלו הוא פחות מ-20 דקות לפני הזמן הנוכחי עלול להחזיר תוצאות שגויות.

פרמטרים בדוגמאות לקריאות ל-API

בקטעים הבאים מוצגות דוגמאות לקריאות API שמשתמשות ב-API של דוחות האבטחה. הקריאות ל-API מכילות את הפרמטרים הבאים:

• ORG הוא הארגון שלכם.
• ‫ENV הוא הסביבה שבה רוצים לחשב את הדוח.
• ‫ENVGROUP היא קבוצת סביבות שמכילה את הסביבה.
• ‫REPORT_ID הוא מזהה הדוח שמוחזר על ידי קריאה אל create a security report.
• ‫$TOKEN הוא משתנה הסביבה של אסימון גישה ל-OAuth.
• ‫timeRange הוא טווח הזמן של הדוח.

יצירת דוח אבטחה

כדי ליצור דוח אבטחה, מזינים פקודה כמו הבאה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

כאשר Query.json היא תבנית שאילתה שמגדירה את השאילתה. בהמשך מוצגת דוגמה לתבנית שאילתה.

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

השאילתה כוללת את הפרמטרים הבאים:

• מדדים:

  • ‫bot. הערך הזה מייצג את מספר כתובות ה-IP השונות שזוהו כמקורות של בוטים.

    פונקציית צבירה: count_distinct

  • ‫bot_traffic. המספר הכולל של בקשות מכתובות IP שהן המקורות של בוטים.

    פונקציית צבירה: sum

  אפשר לקרוא את ההסבר במאמר על מדדים ופונקציות צבירה.

• מאפיין: ax_resolved_client_ip. האפשרות הזו מקבצת את ספירת הבוטים בדוח לפי כתובת ה-IP של המקור שלהם. מידע על מאפיינים נתמכים זמין במאמר מאפיינים.
• מסנן: environment.
• groupByTimeUnit: minute
• טווח זמן: last7days. טווח זמן

שימו לב שקריאה ל-API זו מחזירה את אותו דוח כמו בדוגמה של דוח כתובות ה-IP של בוטים שנוצר באמצעות ממשק המשתמש של Apigee.

טווח זמן

טווח הזמן של הדוח. אפשר להגדיר את השדה timeRange באחת מהדרכים הבאות:

• מציינים כמה זמן אחורה הדוח צריך להגיע. האפשרויות הן:

  "timeRange": "{last60minutes/last24hours/last7days}"

• מציינים את שעת ההתחלה ושעת הסיום של הדוח בפורמט הבא:

  "timeRange": {
          "start": "YYYY-MM-DDT00:00:00Z",
          "end": "YYYY-MM-DDT00:00:00Z"
          }

  התאריכים start ו-end צריכים להיות בעבר, וההפרש ביניהם לא יכול להיות גדול משנה אחת לפני התאריך הנוכחי שבו יוצרים את הדוח.

דוגמה לתשובה

השאילתה שלמעלה מחזירה תגובה כמו זו:

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

התשובה מכילה את הפרטים הבאים:

• מזהה הדוח, שבו אפשר להשתמש כדי לקבל את הדוח אחרי שהוא מוכן. בדוגמה שלמעלה, מזהה הדוח הוא 3964675e-9934-4398-bff5-39dd93a67201.
• ‫"state": המצב של עבודת הדוח, שיכול להיות אחד מהבאים:
  • ‫enqueued: עבודת הדוח נוצרה זה עתה, אבל היא עדיין לא פועלת.
  • ‫running: משימת הדוח פועלת.
  • ‫completed: משימת הדוח הושלמה. בשלב הזה אפשר לראות את הדוח.
  • ‫expired: תוקף עבודת הדיווח פג, ואי אפשר יותר להציג את הדוח.

קבלת סטטוס הדוח

כדי לקבל את הסטטוס של דוח, שולחים בקשה כמו הבקשה הבאה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

כאשר REPORT_ID הוא מזהה הדוח. אפשר לעיין בפרמטרים בדוגמאות של קריאות ל-API.

התשובה מכילה סיכום של פרמטרים של הדוח, וגם את הסטטוס הנוכחי של הדוח. בדוגמה הזו, הסטטוס הוא "completed", ולכן אפשר לראות את התוצאות של הדוח.

{
  "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d",
  "state": "completed",
  "created": "2022-06-27T13:00:25-07:00",
  "updated": "2022-06-27T13:01:08-07:00",
  "result": {
    "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d/result",
    "expires": "2022-07-04T13:01:08-07:00"
  },
  "resultRows": "848",
  "resultFileSize": "5.10 KB",
  "executionTime": "43 seconds",
  "queryParams": {
    "metrics": [
      "name:bot,func:count_distinct,alias:count_distinct_bot,op:,val:",
      "name:bot_traffic,func:sum,alias:sum_bot_traffic,op:,val:"
    ],
    "dimensions": [
      "ax_resolved_client_ip"
    ],
    "startTimestamp": "2022-06-20T20:00:25.098237292Z",
    "endTimestamp": "2022-06-27T20:00:25.098237292Z",
    "mimeType": "json",
    "timeUnit": "minute"
  },
  "displayName": "Sample Query Bot"
}

להורדת הדוח

כדי להוריד את דוח האבטחה, שולחים בקשה כמו הבקשה הבאה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

כאשר REPORT_ID הוא מזהה הדוח. מידע נוסף זמין במאמר בנושא פרמטרים בדוגמאות של קריאות ל-API.

הפעולה הזו מחזירה קובץ שמכיל את הדוח, והשם שלו הוא מהצורה OfflineQueryResult-{ID}.zip. כדי לראות את הדוח:

1. חילוץ ZIP OfflineQueryResult-{ID}.zip.
2. מזינים gzip -d QueryResults-{ID}*.json.gz.
3. יש להזין cat QueryResults-{ID}*.json
.

דוגמה לתנועה מבוטים

בדוגמה הבאה נוצר דוח על bot_traffic:

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

השאילתה כוללת את הפרמטרים הבאים:

• מדד: bot_traffic. המספר הכולל של בקשות מכתובות IP שזוהו כמקורות של בוטים, במרווחי זמן של דקה.

  אפשר לקרוא את ההסבר במאמר על מדדים ופונקציות צבירה.

• מאפיין: bot_reason. ‫bot_reason יכול להיות כל שילוב של כללי הזיהוי של בוטים. כשמזוהה בוט, bot_reason כולל את קבוצת המשנה של כללי הזיהוי שתבנית התנועה של הבוט תאמה להם.

  מידע על מאפיינים

• מסנן: environment.
• groupByTimeUnit: minute
• timeRange: last7days

שימו לב שקריאה ל-API זו מחזירה את אותו דוח כמו בדוגמה של דוח כתובות ה-IP של בוטים שנוצר באמצעות ממשק המשתמש של Apigee.

עיכוב בנתוני זיהוי בוטים

יש עיכוב בעיבוד של זיהוי בוטים, שנמשך בממוצע כ-15 עד 20 דקות.

יצירת דוח אבטחה לקבוצת סביבות

באמצעות Security Reports API, אפשר ליצור דוח לנתונים בקבוצת סביבות (בניגוד לסביבה אחת בלבד). כדי לעשות זאת, מזינים פקודה כמו הבאה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

ומקפידים שתבנית השאילתה, Query.json, תכיל את השורה הבאה:

"envgroup_hostname": "ENVGROUP"

כאשר ENVGROUP הוא השם של קבוצת סביבות שמכילה את הסביבה. כדי למצוא את השם של קבוצת הסביבות בממשק המשתמש של Apigee, עוברים אל Admin > Environments > Groups.

הערות:

• ממשקי API של דוחות ברמת קבוצת הסביבות תומכים רק במדד message_count עם פונקציית הצבירה sum.
• ממשקי Report API ברמת קבוצת הסביבות לא תומכים במאפיינים bot_reason או incident_id, אבל הם תומכים בכל המאפיינים האחרים של דוחות אבטחה.

קבלת סטטוס הדוח

כדי לקבל את הסטטוס של דוח, מזינים פקודה כמו הפקודה הבאה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

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

{
  "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "completed",
  "created": "2021-08-06T15:28:28-07:00",
  "updated": "2021-08-06T15:28:40-07:00",
  "result": {
    "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201/result",
    "expires": "2021-08-13T15:28:40-07:00"
  },
  "resultRows": "60",
  "resultFileSize": "0.31 KB",
  "executionTime": "11 seconds",
  "queryParams": {
    "metrics": [
      "name:message_count,func:sum,alias:sum_message_count,op:,val:"
    ],
    "dimensions": [
      "apiproxy"
    ],
    "startTimestamp": "2021-08-06T21:28:28.570770570Z",
    "endTimestamp": "2021-08-06T22:28:28.570770570Z",
    "mimeType": "json",
    "timeUnit": "minute"
  }
}

מכיוון שהמדינה היא "completed", עכשיו אפשר לצפות בדוח, כמו שמתואר בהמשך.

הצגת דוח אבטחה

כדי להציג דוח אבטחה, מזינים פקודה כמו הבאה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

הפעולה הזו מחזירה קובץ שמכיל את הדוח, והשם שלו הוא מהצורה OfflineQueryResult-{ID}.zip. כדי לראות את הדוח:

1. חילוץ ZIP OfflineQueryResult-{ID}.zip.
2. מזינים gzip -d QueryResults-{ID}*.json.gz.
3. יש להזין cat QueryResults-{ID}*.json
.