Security Stats API

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Mit der Security Stats API können Sie die Statistiken zu Missbrauch und Bots in den letzten 14 Tagen ansehen. Es gibt zwei Arten von Sicherheitsstatistiken:

  • Tabellarische Statistiken ohne Zeitdimension. Tabellarische Statistiken werden häufig mit einer Aggregationsfunktion berechnet, z. B. sum for message_count oder bot_traffic.
  • Zeitreihenstatistiken mit Zeitdimension.
Hinweis: Die Bot-Erkennung hat eine durchschnittliche Verarbeitungsverzögerung von etwa 15 bis 20 Minuten.

Parameter in Beispiel-API-Aufrufen

In den folgenden Abschnitten finden Sie Beispiele für API-Aufrufe, die die Security Stats API verwenden. Die API-Aufrufe enthalten die folgenden Variablenparameter:

  • ORG: Meine Organisation.
  • ENV: Ihre Umgebung.
  • METRIC_i: Ein Messwert für die Statistik. Weitere Informationen finden Sie unter Messwerte und Aggregationsfunktionen.
  • AGGREGATION_i: Eine Aggregationsfunktion für den Messwert. Siehe die folgende Tabelle.
  • DIMENSION_i: Eine Dimension zum Gruppieren der Werte der Statistik.
  • PAGE_SIZE: Maximale Anzahl von Unterkomponenten, die auf einer einzelnen Seite zurückgegeben werden.
  • time_range: Der Zeitraum für die Statistiken im Formular 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    Dabei gilt:

    • START_TIME ist die Startzeit des Zeitraums.
    • END_TIME ist die Endzeit des Zeitraums.

    START_TIME und END_TIME haben das Format "YYYY-MM-DDT00:00:00Z".

    Der Zeitraum darf maximal 14 Tage betragen und sowohl das Start- als auch das Enddatum müssen innerhalb der letzten 365 Tage liegen.

Beispiel: Tabellarische Sicherheitsstatistiken für eine Umgebung abfragen

Anfragen zum Abfragen tabellarischer Statistiken haben folgendes Format:

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
          }
        }'

Siehe Parameter in Beispiel-API-Aufrufen.

Die maximale Anzahl an Messwerten, Aggregatfunktionen und Dimensionen, die in einer Anfrage enthalten sein können, finden Sie unter Einschränkungen für Sicherheitsstatistiken.

Das folgende Beispiel zeigt eine Anfrage zum Abfragen von Tabellenstatistiken:

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
          }
        }'

Eine Beschreibung der Anfrage und Antwort finden Sie auf der Referenzseite zu queryTabularStats.

Beispiel: Zeitreihensicherheitsstatistiken für eine Umgebung abfragen

Time Series APIs geben Zeitreihenstatistiken für die ausgewählten Messwerte zurück, gruppiert nach der ausgewählten Dimension.

Mit dem folgenden Aufruf werden Zeitreihenstatistiken für Bot-Traffic aufgerufen, gruppiert nach API-Proxy. Da es vier Proxys gibt, erhalten Sie vier Sequenzen von Zeitreihenpunkten. Die Reihenfolge der Punkte jeder Zeile entspricht dem jeweiligen Index im Spaltenfeld.

Ein Beispiel für eine Anfrage:

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
          }
        }'

Siehe Parameter in Beispiel-API-Aufrufen.

Eine Beschreibung der Anfrage und Antwort finden Sie auf der Referenzseite zu queryTabularStats.

Beispiel: Vorfalldetails für die Missbrauchserkennung abfragen

Im folgenden Beispiel werden die Details eines Vorfalls für die Missbrauchserkennung von Advanced API Security abgefragt. Der Aufruf gibt Details für die Bot-Anzahl für die Entwickler-App für einen bestimmten Vorfall zurück.

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
          }
        }'

Siehe Parameter in Beispiel-API-Aufrufen.

Dies gibt eine Antwort wie die folgende zurück:

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

Eine Beschreibung der Anfrage und Antwort finden Sie auf der Referenzseite zu queryTabularStats.

Messwerte und Aggregationsfunktionen

In der folgenden Tabelle werden die Messwerte und Aggregationsfunktionen beschrieben, die in der SecurityStats API verfügbar sind:

Metric Beschreibung Aggregation function
bot Die Anzahl unterschiedlicher IP-Adressen für erkannte Bots in Intervallen von einer Minute. count_distinct
bot_first_detected Datum und Uhrzeit der ersten Erkennung des Bots. Nur über die API verfügbar. min
bot_last_detected Datum und Uhrzeit der letzten Erkennung des Bots. Nur über die API verfügbar. max
bot_traffic Die Anzahl der Nachrichten von IP-Adressen erkannter Bots in Intervallen von einer Minute. sum
message_count

Gesamtzahl der von Apigee in Intervallen von einer Minute verarbeiteten API-Aufrufe.

Hinweis: message_count kann nicht mit anderen Messwerten im selben Bericht verwendet werden.

 sum
response_size Größe der Antwort. average, max, min, sum

Dimensionen

Mit Dimensionen können Sie Messwerte anhand verwandter Teilmengen der Daten gruppieren. In der folgenden Tabelle werden die Dimensionen beschrieben, die für erweiterte API-Sicherheitsberichte spezifisch sind.

Dimension Beschreibung
bot_reason Kann eine beliebige Kombination der Erkennungsregeln für die Sicherheit sein. bot_reason besteht aus der Teilmenge der Erkennungsregeln, denen das Trafficmuster des Bots entspricht.
incident_id (Vorschau) Die UUID für einen Sicherheitsvorfall, die durch einen Aufruf der Incidents API zurückgegeben wird. Weitere Informationen finden Sie unter Beispiel: Details zu einem bestimmten Vorfall abrufen.
security_action Die Sicherheitsaktion. Mögliche Werte sind ALLOW, DENY oder FLAG.
security_action_name Der Name der Sicherheitsaktion.
security_action_headers Header, mit denen Sie eine Flag-Sicherheitsaktion abfragen können.

Hinweis: bot_reason und incident_id funktionieren nur mit den folgenden Messwerten:

  • bot
  • bot_traffic
  • response_size

Zusätzlich zu den oben beschriebenen Dimensionen unterstützt die erweiterte API-Sicherheit auch die folgenden Dimensionen:

  • access_token
  • api_product
  • apiproxy
  • 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
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • response_status_code
  • target_url
  • useragent

Einschränkungen für Sicherheitsstatistiken

Für die Security Stats API (tabellarisch und Zeitreihen) gelten folgende Limits:

  • Maximale Seitengröße: 14400
  • Maximal 10 Zeitreihendimensionen
  • Maximal 15 Dimensionen für tabellarische Statistiken
  • Maximal 5 Messwertaggregationen
  • Maximal 5 Aggregationen von Zeitreihenmesswerten
  • Zeitraum: Die Länge darf maximal 14 Tage betragen. Sowohl das Start- als auch das Enddatum müssen innerhalb der letzten 365 Tage liegen.
  • Die Dimensionen incident_id und bot_reason können nicht mit den Messwerten message_count oder response_size verwendet werden.

Security Stats API und Security Reports API vergleichen

Sowohl die Security Stats API als auch die Security Reports API geben Missbrauchs- und Bot-bezogene Sicherheitsstatistiken zurück, unterscheiden sich jedoch in folgenden Punkten:

  • Die Security Stats API ist so konzipiert, dass Statistiken zum letzten API-Traffic angezeigt werden. Die Daten für die Security Stats API reichen nur 14 Tage zurück. Sie können die Statistiken jedoch sofort aufrufen, wenn Sie eine Anfrage senden.

    Sicherheitsstatistiken werden auch in der Ansicht "Missbrauchsmesswerte" in der Apigee-Benutzeroberfläche angezeigt.

  • Die Security Reports API dient zum Anzeigen von Statistiken für lang andauernde Vorgänge. Zur Verwendung der Security Scores API senden Sie einen Job und rufen die Ergebnisse erst auf, wenn der Job abgeschlossen ist. Die Daten für die Security Scores API reichen bis zu einem Jahr zurück.