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 Format
```
"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
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 und 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.