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 מפורטים תיאורים של הבקשה והתשובה.

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

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