Sicherheitsberichte mit der API verwalten

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird beschrieben, wie Sie Sicherheitsberichte mit der API für Sicherheitsberichte erstellen und ansehen.

Eine Übersicht über Sicherheitsberichte, einschließlich Einschränkungen, finden Sie unter Übersicht über Sicherheitsberichte. Die API-Referenzdokumentation für Sicherheitsberichte finden Sie unter API-Referenz für Sicherheitsberichte.

Hinweis: Daten, die in die Apigee Analytics-Pipeline fließen, haben im Durchschnitt eine Verzögerung von bis zu 15 bis 20 Minuten. Ein Sicherheitsbericht, bei dem das Ende weniger als 20 Minuten in der Vergangenheit liegt, kann daher zu falschen Ergebnissen führen.

Parameter in Beispiel-API-Aufrufen

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

ORG ist Ihre Organisation.
ENV ist die Umgebung, in der der Bericht berechnet werden soll.
ENVGROUP ist eine Umgebungsgruppe, die die Umgebung enthält.
REPORT_ID ist die Berichts-ID, die von einem Aufruf zum Erstellen eines Sicherheitsberichts zurückgegeben wird.
$TOKEN ist die Umgebungsvariable für ein OAuth-Zugriffstoken.
timeRange ist der Zeitraum für den Bericht.

Sicherheitsbericht erstellen

Geben Sie einen Befehl wie den folgenden ein, um einen Sicherheitsbericht zu erstellen:

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"

Dabei ist Query.json eine Abfragevorlage, die die Abfrage definiert. Im Folgenden finden Sie ein Beispiel für eine Abfragevorlage.

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

Die Abfrage enthält die folgenden Parameter:

Messwerte:
- bot Dies zählt die Anzahl verschiedener IP-Adressen, die als Quellen von Bots identifiziert wurden.
  
  Aggregatfunktion: count_distinct
- bot_traffic Die Gesamtzahl der Anfragen von IP-Adressen, die die Quellen von Bots sind.
  
  Aggregatfunktion: sum
Weitere Informationen finden Sie unter Messwerte und Aggregationsfunktionen.
Dimension: ax_resolved_client_ip. Gruppiert die Anzahl der Bots im Bericht nach der IP-Adresse der Quelle. Informationen zu unterstützten Dimensionen finden Sie unter Dimensionen.
Filter: environment.
groupByTimeUnit: minute
timeRange: last7days. Siehe Zeitraum.

Beachten Sie, dass dieser API-Aufruf denselben Bericht zurückgibt wie das Beispiel für den Bot-IP-Adressbericht, der über die Apigee-UI erstellt wurde.

Zeitraum

Der Zeitraum für den Bericht. Sie können das Feld timeRange auf eine der folgenden Arten festlegen:

Geben Sie an, wie lange der Bericht in die Vergangenheit gehen soll. Folgende Optionen sind verfügbar:
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
Geben Sie eine Start- und Endzeit für den Bericht im folgenden Format an:
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
Sowohl start als auch end müssen in der Vergangenheit liegen und können beim Erstellen des Berichts höchstens ein Jahr vor dem aktuellen Datum liegen.

Beispielantwort

Die obige Abfrage gibt eine Antwort wie die folgende zurück:

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

Die Antwort enthält Folgendes:

Die Berichts-ID, mit der Sie den Bericht nach Abschluss abrufen können. Im obigen Beispiel lautet die Berichts-ID 3964675e-9934-4398-bff5-39dd93a67201.
"state": Der Status des Berichtsjobs, der einer der folgenden sein kann:
- enqueued: Der Berichtsjob wurde gerade erstellt, wird aber noch nicht ausgeführt.
- running: Der Berichtsjob wird ausgeführt.
- completed: Der Berichtjob ist abgeschlossen. In diesem Stadium können Sie den Bericht ansehen.
- expired: Der Berichtsjob ist abgelaufen und Sie können den Bericht nicht mehr aufrufen.

Berichtsstatus abrufen

Senden Sie eine Anfrage wie die folgende, um den Status eines Berichts abzurufen:

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"

wobei REPORT_ID die Berichts-ID ist. Weitere Informationen finden Sie unter Parameter in den Beispielen für API-Aufrufe.

Die Antwort enthält eine Zusammenfassung der Berichtsparameter sowie den aktuellen Status des Berichts. In diesem Beispiel lautet der Status "completed", sodass Sie die Ergebnisse des Berichts ansehen können.

{
  "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"
}

Zum Artikel

Senden Sie zum Herunterladen des Sicherheitsberichts eine Anfrage wie die folgende:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

wobei REPORT_ID die Berichts-ID ist. Siehe Parameter in Beispiel-API-Aufrufen.

Dies gibt eine Datei zurück, die den Bericht enthält, dessen Name das Format OfflineQueryResult-{ID}.zip hat. So rufen Sie den Bericht auf:

Entpacken Sie OfflineQueryResult-{ID}.zip.
Geben Sie gzip -d QueryResults-{ID}*.json.gz ein.
cat QueryResults-{ID}*.json eingeben

Beispiel für Bot-Traffic

Im folgenden Beispiel wird ein Bericht zu bot_traffic erstellt:

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

Die Abfrage enthält die folgenden Parameter:

Messwert: bot_traffic. Dies ist die Gesamtzahl der Anfragen von IP-Adressen, die als Bot-Quellen identifiziert wurden, in Intervallen von einer Minute.

Weitere Informationen finden Sie unter Messwerte und Aggregationsfunktionen.
Dimension: bot_reason. bot_reason kann eine beliebige Kombination der Erkennungsregeln für Bots sein. Wenn ein Bot erkannt wird, besteht bot_reason aus der Teilmenge der Erkennungsregeln, denen das Trafficmuster des Bots entspricht.

Siehe Dimensionen.
Filter: environment.
groupByTimeUnit: minute
timeRange: last7days

Beachten Sie, dass dieser API-Aufruf denselben Bericht zurückgibt wie das Beispiel für den Bot-IP-Adressbericht, der über die Apigee-UI erstellt wurde.

Verzögerung bei Bot-Erkennungsdaten

Die Bot-Erkennung hat eine durchschnittliche Verarbeitungsverzögerung von etwa 15 bis 20 Minuten.

Sicherheitsbericht für eine Umgebungsgruppe erstellen

Mit der Security Reports API können Sie einen Bericht für Daten in einer Umgebungsgruppe statt nur in einer Umgebung erstellen. Geben Sie dazu einen Befehl wie den folgenden ein:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

Die Abfragevorlage Query.json muss die folgende Zeile enthalten:

"envgroup_hostname": "ENVGROUP"

Dabei ist ENVGROUP der Name einer Umgebungsgruppe, die die Umgebung enthält. Sie finden den Namen der Umgebungsgruppe in der Apigee-Benutzeroberfläche unter Verwaltung > Umgebungen > Gruppen.

Hinweise:

Report APIs auf Ebene der Umgebungsgruppe unterstützen nur den Messwert message_count mit der Aggregationsfunktion sum.
Report APIs auf Ebene der Umgebungsgruppe unterstützen nicht die Dimensionen bot_reason oder incident_id, jedoch alle anderen Dimensionen für Sicherheitsberichte.

Berichtsstatus abrufen

Geben Sie einen Befehl wie den folgenden ein, um den Status eines Berichts abzurufen:

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"

Dadurch wird eine Zusammenfassung der Berichtsanfrage und der aktuelle Status des Berichts zurückgegeben. Sie sehen hier ein Beispiel:

{
  "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"
  }
}

Da der Status "completed" lautet, können Sie den Bericht jetzt wie unten beschrieben aufrufen.

Sicherheitsbericht ansehen

Geben Sie einen Befehl wie den folgenden ein, um einen Sicherheitsbericht aufzurufen:

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"

Dies gibt eine Datei zurück, die den Bericht enthält, dessen Name das Format OfflineQueryResult-{ID}.zip hat. So rufen Sie den Bericht auf:

Entpacken Sie OfflineQueryResult-{ID}.zip.
Geben Sie gzip -d QueryResults-{ID}*.json.gz ein.
cat QueryResults-{ID}*.json eingeben

Sicherheitsberichte mit der API verwalten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Parameter in Beispiel-API-Aufrufen

Sicherheitsbericht erstellen

Zeitraum

Beispielantwort

Berichtsstatus abrufen

Zum Artikel

Beispiel für Bot-Traffic

Verzögerung bei Bot-Erkennungsdaten

Sicherheitsbericht für eine Umgebungsgruppe erstellen

Berichtsstatus abrufen

Sicherheitsbericht ansehen

Sicherheitsberichte mit der API verwalten