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

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

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

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

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

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

הערות:

• ממשקי Report 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
.