Security stats API

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

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

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

• נתונים סטטיסטיים בטבלה, שלא כוללים מאפיין זמן. לרוב, נתונים סטטיסטיים בטבלה מחושבים באמצעות פונקציית צבירה, למשל sum for message_count או bot_traffic.
• נתונים סטטיסטיים של סדרות זמן, שכוללים מימד זמן.

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

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

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

• ‫ORG: הארגון שלכם.
• ‫ENV: הסביבה שלכם.
• ‫METRIC_i: מדד לנתון הסטטיסטי. אפשר לקרוא על כך במאמר מדדים ופונקציות צבירה.
• ‫AGGREGATION_i: פונקציית צבירה למדד. פרטים נוספים מופיעים בטבלה שבהמשך.
• ‫DIMENSION_i: מאפיין לקיבוץ הערכים של הנתון הסטטיסטי.
• ‫PAGE_SIZE: המספר המקסימלי של רכיבי משנה שמוחזרים בדף יחיד.
• ‫time_range: טווח הזמן של הנתונים הסטטיסטיים בפורמט

  "time_range": {
      "start_time": START_TIME,
      "end_time": END_TIME
  }

  where:

  • ‫START_TIME היא שעת ההתחלה של טווח הזמן.
  • ‫END_TIME היא שעת הסיום של טווח הזמן.

  הערכים START_TIME ו-END_TIME הם בפורמט "YYYY-MM-DDT00:00:00Z".

  אורך טווח הזמן יכול להיות עד 14 ימים, ותאריך ההתחלה ותאריך הסיום צריכים להיות בטווח של 365 הימים האחרונים.

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

בקשה לשאילתת נתונים סטטיסטיים בטבלה מופיעה בפורמט הבא:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

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

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

דוגמה לבקשה לשאילתת נתונים סטטיסטיים בטבלה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

ב דף העזר של queryTabularStats מפורטים תיאורים של הבקשה והתשובה.

דוגמה: שאילתה של נתוני אבטחה של סדרת זמן בסביבה

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

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

הנה דוגמה לבקשה:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

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

ב דף העזר של queryTabularStats מפורטים תיאורים של הבקשה והתשובה.

דוגמה: שאילתת פרטי אירוע לצורך זיהוי התנהלות פוגעת

בדוגמה הבאה מוצגת שאילתה שמחזירה את הפרטים של אירוע ב-זיהוי התנהלות פוגעת של Advanced API Security. הקריאה מחזירה פרטים על מספר הבוטים באפליקציית המפתח עבור תקרית מסוימת.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

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

התגובה שמתקבלת נראית כך:

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

ב דף העזר של queryTabularStats מפורטים תיאורים של הבקשה והתשובה.

מדדים ופונקציות צבירה

בטבלה הבאה מפורטים המדדים ופונקציות הצבירה שזמינים ב-Security Stats API:

Metric	תיאור	Aggregation function
bot	מספר כתובות ה-IP הייחודיות של בוטים שזוהו במרווחי זמן של דקה.	count_distinct
bot_first_detected	התאריך והשעה שבהם הבוט זוהה לראשונה. האפשרות הזו זמינה רק דרך ה-API.	min
bot_last_detected	התאריך והשעה שבהם הבוט זוהה לאחרונה. האפשרות הזו זמינה רק דרך ה-API.	max
bot_traffic	מספר ההודעות מכתובות IP של בוטים שזוהו במרווחי זמן של דקה אחת.	sum
message_count	המספר הכולל של קריאות ל-API שעובדו על ידי Apigee במרווחי זמן של דקה. הערה: אי אפשר להשתמש במדד message_count עם מדדים אחרים באותו דוח.	sum
response_size	גודל התשובה.	average,‏ max,‏ min,‏ sum

מידות

מאפיינים מאפשרים לקבץ ערכי מדדים על סמך קבוצות משנה קשורות של הנתונים. בטבלה הבאה מתוארים המאפיינים שספציפיים לדוחות של Advanced API Security:

מאפיין	תיאור
bot_reason	יכול להיות כל שילוב של כללי זיהוי של אבטחה. ‫bot_reason כולל את קבוצת המשנה של כללי הזיהוי שתבנית התנועה של הבוט תאמה להם.
incident_id (תצוגה מקדימה)	ה-UUID של אירוע אבטחה, שמוחזר על ידי קריאה ל-Incidents API. אפשר לעיין ב דוגמה: קבלת פרטים או אירוע ספציפי.
security_action	פעולת האבטחה. הערכים האפשריים הם ALLOW,‏ DENY או FLAG.
security_action_name	השם של פעולת האבטחה.
security_action_headers	כותרות שאפשר להשתמש בהן כדי לשלוח שאילתה לפעולת אבטחה של דגל.

הערה: הפונקציות bot_reason ו-incident_id פועלות רק עם המדדים הבאים:

• bot
• bot_traffic
• response_size

בנוסף למאפיינים שמתוארים למעלה, Advanced API Security תומכת גם במאפיינים הבאים:

• access_token
• api_product
• apiproxy
• app_group_app
• app_group_name
• ax_edge_execution_fault_code
• ax_geo_city
• ax_geo_continent
• ax_geo_country
• ax_geo_region
• ax_isp
• ax_resolved_client_ip
• ax_ua_agent_version
• client_id
• developer
• developer_app
• developer_email
• environment
• is_filtered_out
• proxy_basepath
• proxy_pathsuffix
• request_uri
• response_status_code
• target_url
• useragent

מגבלות על נתוני אבטחה

ל-API של נתוני האבטחה (גם בפורמט טבלאי וגם בפורמט של סדרות זמן) יש את המגבלות הבאות:

• גודל הדף המרבי: 14400
• עד 10 מאפיינים של סדרות זמן
• עד 15 מאפיינים של נתונים בטבלה
• אפשר להוסיף עד 5 צבירות של מדדים.
• מקסימום 5 צבירות של מדדים של סדרות זמן
• טווח הזמן: האורך יכול להיות עד 14 ימים, ותאריך ההתחלה ותאריך הסיום צריכים להיות בטווח של 365 הימים האחרונים.
• אי אפשר להשתמש במאפיינים incident_id ו-bot_reason עם המדדים message_count או response_size.
• המאפיין is_filtered_out נתמך רק בנתונים סטטיסטיים טבלאיים, והוא חל גם על נתונים ישנים.

השוואה בין Security Stats API לבין Security Reports API

גם ה-API של נתוני האבטחה וגם ה-API של דוחות האבטחה מחזירים נתוני אבטחה שקשורים להתנהלות פוגעת ולבוטים, אבל יש ביניהם הבדלים:

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

  נתוני אבטחה מוצגים גם בתצוגת המדדים של התנהלות פוגעת בממשק המשתמש של Apigee.

• ‫Security reports API מיועד להצגת נתונים סטטיסטיים של פעולות ממושכות. כדי להשתמש ב-API של ציוני האבטחה, צריך לשלוח עבודה ולצפות בתוצאות רק כשהעבודה מסתיימת. הנתונים של Security Scores API זמינים עד שנה אחורה.