Security Reports API

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Neben der Verwendung von Sicherheitsberichten in der Apigee-Benutzeroberfläche können Sie auch über die Apigee Security Reports API auf alle Sicherheitsberichte zugreifen. In diesem Abschnitt wird die Verwendung der Security Reports API beschrieben.

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
Siehe Messwerte und Aggregationsfunktionen.
Dimension: ax_resolved_client_ip. Gruppiert die Anzahl der Bots im Bericht nach der IP-Adresse der Quelle.
Siehe 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 der Vergangenheit reichen 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. Siehe Parameter in Beispiel-API-Aufrufen.

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.

Siehe 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

Messwerte und Aggregationsfunktionen

Sie können die folgenden Messwerte und Aggregationsfunktionen, die Statistiken aus einem Messwert berechnen, für einen Bericht verwenden.

Messwert	Beschreibung	`Aggregation function`
`bot`	Die Anzahl unterschiedlicher IP-Adressen für erkannte Bots in Intervallen von einer Minute.	`count_distinct`
`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 zurückgegebenen Antwortnutzlast in Byte.	`sum`, `avg`, `min`, `max`
`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`

Dimensionen

Mit Dimensionen können Sie Messwerte anhand verwandter Teilmengen der Daten gruppieren. In der folgenden Tabelle werden die Dimensionen beschrieben, die für die erweiterte API-Sicherheit 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, der durch einen Aufruf an die Incidents API zurückgegeben wird. Siehe Beispiel: Details oder bestimmte Vorfälle 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_dn_region
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_family
ax_ua_agent_type
ax_ua_agent_version
ax_ua_agent_category
ax_ua_os_family
bot_reason
client_id
developer
developer_app
developer_email
envgroup_hostname
environment
incident_id (Vorschau)
proxy_basepath
proxy_pathsuffix
request_uri
request_verb
response_status_code
target_host
target_url
useragent

Einschränkungen für Sicherheitsberichte

Siehe Einschränkungen für Sicherheitsberichte.