Security Scores and Profiles API

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Übersicht

Auf dieser Seite wird beschrieben, wie Sie Sicherheitsbewertungen und Sicherheitsprofile (auch einfach als „Profile“ bezeichnet) mithilfe von APIs verwalten. Auf dieser Seite finden Sie Beispiel-API-Anfragen.

Eine Übersicht über die Risikobewertungsfunktion, einschließlich Einschränkungen, und eine Anleitung zur Verwendung der Benutzeroberfläche finden Sie unter Risikobewertung – Übersicht und Benutzeroberfläche.

Beispiele für die Risikobewertung v2 API

Parameter für Beispiele für die V2 API

In den Beispielen in diesem Abschnitt können folgende Parameter verwendet werden:

ORG ist Ihre Organisation.
ENV ist die Umgebung, in der Punktzahlen berechnet werden sollen.
PROFILE_ID ist der Name des Profils. PROFILE_ID kann google-default oder der Name eines benutzerdefinierten Profils sein, das Sie erstellen.
PROFILE_DESC (optional) ist die Beschreibung für das Profil. Dies sollte eine für Menschen lesbare Beschreibung des Profils sein, die genügend Informationen enthält, um es von anderen Profilen zu unterscheiden.
PROXY_NAME: Der Name des Proxys.
$TOKEN ist die Umgebungsvariable für ein OAuth-Zugriffstoken.

Ergebnisse der Batch-Sicherheitsbewertung abrufen

Nutzer mit der Rolle Security Admin oder Security Viewer haben Berechtigungen zum Ausführen einer Ad-hoc-Risikobewertungsberechnung. Sie müssen das Sicherheitsprofil, den Umfang (die Apigee-Umgebung) und die zu bewertenden Ressourcen angeben. Die Ressourcen können include_all_resources: true sein, um alle Ressourcen im Umfang zu berechnen, oder nur eine Handvoll. Weitere Informationen zu dieser Funktion finden Sie in der API-Referenzdokumentation zur Apigee Management API unter securityAssessmentResults.batchCompute.

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"
  -H 'Content-type: application/json' \
  -d '{
    "profile": "google-default",
    "scope": "ENV",
    "include_all_resources": {}
  }'

Dies ist eine mögliche Antwort auf die Anfrage:

  {
    "security_assessment_results": [
      {
        "resource": {
          "name" : "my-proxy-1",
          "revision": "1"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 99,
        "severity": "low",
        "failed_assessment_by_weight": {
          "MINOR": 1
        },
        "assessment_recommendations": {
          "CORS-Check": {
            "weight": "MINOR",
            "recommendations": [
              {
                "description": "add CORS policy to your proxy",
                "learn_more_link": "https://example.com"
              }
            ]
          }
        }
      },
      {
        "resource": {
          "name" : "my-proxy-2",
          "revision": "3"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 100,
        "severity": "low",
        "resource_revision": "1",
        "failed_assessment_by_weight": {
          "MINOR": 0
        },
        "assessment_recommendations": {}
      }
    ]
  }

Sicherheitsprofile verwalten

Dieser Abschnitt enthält Beispiele für die Verwaltung von Sicherheitsprofilen mithilfe der APIs und ist nicht vollständig. Weitere Informationen finden Sie in der Referenzdokumentation für die securityProfilesV2 API.

Vorhandene benutzerdefinierte Sicherheitsprofile abrufen

Mit diesem Befehl werden die Informationen für alle Sicherheitsprofile für Ihr Projekt abgerufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
      -H "Authorization: Bearer $TOKEN"

Mit diesem Befehl werden die Metadaten für ein bestimmtes Sicherheitsprofil abgerufen. So können Sie Informationen zum google-default-Profil sowie zu benutzerdefinierten Profilen abrufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
      -H "Authorization: Bearer $TOKEN"

Neues benutzerdefiniertes Sicherheitsprofil erstellen

Verwenden Sie einen Befehl wie diesen, um ein neues benutzerdefiniertes Sicherheitsprofil zu erstellen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2?security_profile_v2_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{
          "description": "PROFILE_DESC",
          "profile_assessment_configs": {
            "auth-policies-check": {"weight": "MINOR"},
            "threat-policies-check": {"weight": "MODERATE"}
          }
       }'
}

Vorhandenes benutzerdefiniertes Sicherheitsprofil aktualisieren

Verwenden Sie folgenden Befehl, um ein vorhandenes Profil zu aktualisieren:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID?update_mask=UPDATE_MASK" \
       -X PATCH \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{"description": "PROFILE_DESC"}'

Dabei kann UPDATE_MASK einen der folgenden Werte haben, sofern vorhanden: description, profile_assessment_configs, description,profile_assessment_configs oder * (alles). Wenn Sie die Aktualisierungsmaske * angeben, werden alle Felder in der Anfrage aktualisiert. Dadurch können Werte entfernt werden, wenn sie nicht in der Anfrage enthalten sind.

Wenn Sie update_mask weglassen, werden nur die in der Aktualisierungsanfrage angegebenen Felder aktualisiert.

Benutzerdefiniertes Sicherheitsprofil löschen

So löschen Sie ein benutzerdefiniertes Sicherheitsprofil:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/securityProfilesV2/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN"

Risikobewertung 1

Dieser Abschnitt enthält Informationen und Beispiele für Risk Assessment v1 APIs.

Beschränkungen der Sicherheitspunktzahlen bei Verwendung der APIs

Für Sicherheitspunktzahlen gelten die folgenden Einschränkungen, wenn sie von den Security Scores und Profiles APIs verwendet werden:

Unterstützte Eingabefelder in JSON:
- timeRange: Die Werte werden durch die in der Referenz zur ComputeputEnvironmentScores API beschriebenen Kriterien begrenzt.
- filters: Siehe In der API unterstützte Filter.
- pageSize: Maximale Anzahl von Unterkomponenten, die auf einer einzelnen Seite zurückgegeben werden sollen: 100.
Mehrere Eingabefilter werden nicht unterstützt.
Das Feld „Auswirkungen“ wird als Antwort nicht unterstützt. (Das Feld „Auswirkungen“ ist die mögliche Auswirkung dieser Empfehlung auf die Gesamtpunktzahl. Dieser Wert gibt an, wie wichtig diese Empfehlung zur Verbesserung der Punktzahl ist.)

Allgemeine Einschränkungen für Sicherheitsbewertungen, die nicht speziell für die Verwendung über die APIs gelten, finden Sie unter Einschränkungen für Sicherheitsbewertungen (Version 1).

Parameter in Beispiel-API-Aufrufen

Die folgenden Abschnitte enthalten Beispiel-API-Aufrufe und können die folgenden Parameter verwenden:

ORG ist Ihre Organisation.
ENV ist die Umgebung, in der Punktzahlen berechnet werden sollen.
ENVGROUP ist eine Umgebungsgruppe, die die Umgebung enthält.
PROFILE_ID ist der Name des Profils. PROFILE_ID kann default oder der Name eines benutzerdefinierten Profils sein, das Sie erstellen.
PROFILE_ID muss 1 bis 63 Zeichen lang sein, wobei es sich um Kleinbuchstaben, um die Ziffern 0 bis 9 oder um Bindestriche handeln kann. Das erste Zeichen muss ein Kleinbuchstabe sein. Das letzte Zeichen muss ein Kleinbuchstabe oder eine Ziffer sein.
PROXY_NAME: Der Name des Proxys.
Optionen:RESOURCES
- {"all_resources":true} für alle Ressourcen im Bereich.
- {"includes": { "resources": [{"name": "<proxy-name>"}]}, um einen oder mehrere angegebene Proxys zu überwachen. Beispiel: {"includes": { "resources": [{"name": "my-proxy-1"}]}, um den Proxy mit dem Namen my-proxy-1 zu überwachen.
- {"excludes": { "resources": [{"name": "<proxy-name>"}]}, um alle Ressourcen mit Ausnahme eines oder mehrerer angegebener Proxys zu überwachen. Beispiel: Mit {"excludes": { "resources": [{"name": "my-proxy-1"}]} werden alle Ressourcen außer dem Proxy namens my-proxy-1 überwacht.
$TOKEN ist die Umgebungsvariable für ein OAuth-Zugriffstoken.
timeRange ist der Zeitraum für die Scores.

Beispiele für die Risikobewertung v1 API

In der API unterstützte Filter

In der folgenden Tabelle sind die in der API unterstützten Filter und ihre Komponentenpfade aufgeführt.

Filter	Komponentenpfad
Umgebungspunktzahlen	`/org@ORG/envgroup@ENVGROUP/env@ENV`
Quelle bewertet alle zugrunde liegenden Komponenten	`/org@ORG/envgroup@ENVGROUP/env@ENV/source`
Missbrauchspunktzahlen	`/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse`
Punktzahlen für alle Proxys	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
Punktzahlen für bestimmten Proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
Richtlinienpunktzahlen für bestimmten Proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual`
Punktzahlen für Mediationsrichtlinien für einen bestimmten Proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation`
Punktzahlen für Sicherheitsrichtlinien für einen bestimmten Proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
Punktzahlen für Auth-Richtlinienwerte für bestimmten Proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
Punktzahlen für CORS-Richtlinien für bestimmten Proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
Punktzahlen für Bedrohungsrichtlinien für einen bestimmten Proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
Richtlinienpunktzahlen für alle Proxys in der Umgebung	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
Punktzahlen für Mediationsrichtlinien für alle Proxys in der Umgebung	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
Punktzahlen für Sicherheitsrichtlinien für alle Proxys in der Umgebung	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
Punktzahlen für Auth-Richtlinien für alle Proxys in der Umgebung	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
Punktzahlen für CORS-Richtlinien für alle Proxys in der Umgebung	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
Punktzahlen für Bedrohungsrichtlinien für alle Proxys in der Umgebung	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat`

Standardsicherheitsprofil verwenden

Die folgenden Beispiele zeigen, wie das Standardsicherheitsprofil verwendet wird. Die in den Beispielen verwendeten Parameter finden Sie unter Parameter in Beispiel-API-Aufrufen.

Standard-Sicherheitsprofil an eine Umgebung anhängen

Zum Aufrufen von Sicherheitspunktzahlen müssen Sie ein Profil an die Umgebung anhängen, deren Sicherheit Sie bewerten möchten. Verwenden Sie den folgenden Befehl, um das Standardsicherheitsprofil an eine Umgebung anzuhängen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments" \
       -X POST \
       -d '{"name": "ENV"}' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Hinweis: Der Parameter securityProfileRevisionId wurde verworfen. Wenn Sie diesen Parameter in einen API-Aufruf einfügen, verwendet Advanced API Security unabhängig vom Wert des Parameters die neueste Version des Profils.

Standarddefinition des Sicherheitsprofils abrufen

Geben Sie den folgenden Befehl ein, um die Definition des Standardsicherheitsprofils abzurufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Standardsicherheitsprofil von einer Umgebung trennen

Wenn Sie das Standardprofil von einer Umgebung trennen müssen, können Sie so vorgehen:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
         -X DELETE
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

Benutzerdefiniertes Sicherheitsprofil verwenden

Sie können ein benutzerdefiniertes Sicherheitsprofil mit einem API-Aufruf auf eine der folgenden Arten erstellen:

Geben Sie das Profil explizit im Text des Aufrufs an.
Hängen Sie an den Aufruf eine JSON-Datei an, die die Profildefinition enthält.

In den folgenden Abschnitten finden Sie Beispiele für beide Methoden. Die in den Beispielen verwendeten Parameter finden Sie unter Parameter in Beispiel-API-Aufrufen.

Die folgenden Felder in den Beispielen von API-Aufrufen geben das benutzerdefinierte Profil an:

description: Eine Beschreibung des benutzerdefinierten Profils.
profileConfig: Eine Liste der Kategorien, die in das benutzerdefinierte Profil aufgenommen werden sollen. Dies kann eine beliebige Teilmenge der folgenden Sicherheitskategorien sein:
- abuse
- authorization
- cors
- mtls
- mediation
- threat

Profil im Text eines API-Aufrufs definieren

Zum Definieren eines benutzerdefinierten Profils im Text eines API-Aufrufs geben Sie einen Befehl wie den folgenden ein:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "description":"test custom profile",
         "profileConfig" : {
           "categories":[
             {"cors":{}},
             {"threat":{}}
           ]
         }
       }'

Dadurch wird ein benutzerdefiniertes Profil erstellt, das die Kategorien „cors“ und „threat“ enthält, und es wird eine Antwort wie diese zurückgegeben:

{
  "name": "PROFILE_ID",
  "revisionId": "1",
  "revisionCreateTime": "2023-07-17T18:47:08Z",
  "revisionUpdateTime": "2023-07-17T18:47:08Z",
  "scoringConfigs": [
    {
      "title": "json",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/json",
      "description": "Check if JSONThreatProtection policy is configured."
    },
    {
      "title": "xml",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/xml",
      "description": "Check if XMLThreatProtection policy is configured."
    },
    {
      "title": "cors",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors",
      "description": "Check if CORS policy is configured."
    }
  ],
  "maxScore": 1200,
  "minScore": 200,
  "profileConfig": {
    "categories": [
      {
        "cors": {}
      },
      {
        "threat": {}
      }
    ]
  },
  "description": "test custom profile"
  }

Profil definieren, indem Sie einer JSON-Datei einen API-Aufruf hinzufügen

Sie können auch ein benutzerdefiniertes Sicherheitsprofil definieren, indem Sie eine JSON-Datei mit einer Profildefinition an einen API-Aufruf anhängen. Erstellen Sie als Beispiel zuerst die folgende JSON-Datei:

{
  "description": "test custom profile",
  "profileConfig" : {
    "categories":[
      {"cors":{}},
      {"threat" :{}},
    ]
  }
}

Dadurch wird ein Profil mit den Kategorien „cors“ und „threat“ definiert. Sie können dann so ein Profil basierend auf diesen Kategorien erstellen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d @create_profile.json

Dabei ist create_profile.json der Name der oben beschriebenen JSON-Datei.

Benutzerdefinierte Sicherheitsprofildefinition abrufen

Geben Sie einen Befehl ähnlich dem folgenden ein, um die Definition eines benutzerdefinierten Sicherheitsprofils abzurufen:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"

Benutzerdefiniertes Sicherheitsprofil von einer Umgebung trennen

Geben Sie zum Trennen eines benutzerdefinierten Sicherheitsprofils von einer Umgebung einen Befehl wie den folgenden ein:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

Benutzerdefiniertes Sicherheitsprofil löschen

Geben Sie einen Befehl wie den folgenden ein, um ein benutzerdefiniertes Sicherheitsprofil zu löschen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

Punktzahlen für eine Umgebung abrufen

In den folgenden Abschnitten finden Sie Beispiele zum Abrufen von Punktzahlen für eine Umgebung. Die in den Beispielen verwendeten Parameter finden Sie unter Parameter in Beispiel-API-Aufrufen.

Alle Punktzahlen für eine Umgebung abrufen

Um alle Punktzahlen für eine Umgebung abzurufen, geben Sie einen Befehl wie den folgenden ein:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              }
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

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

Quellpunktzahlen für eine Umgebung abrufen

Geben Sie einen Befehl wie den folgenden ein, um Quellpunktzahlen für eine Umgebung abzurufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Missbrauchspunktzahl in der Quelle für eine Umgebung abrufen

Geben Sie einen Befehl wie den folgenden ein, um die Missbrauchspunktzahl in der Quelle für eine Umgebung abzurufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Punktzahlen für alle Proxys in einer Umgebung abrufen

Geben Sie einen Befehl wie den folgenden ein, um Punktzahlen für alle Proxys in einer Umgebung abzurufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Punktzahlen für einen bestimmten Proxy in einer Umgebung abrufen

Geben Sie einen Befehl wie den folgenden ein, um Punktzahlen für einen bestimmten Proxy in einer Umgebung abzurufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Dabei ist PROXY der Proxy, dessen Punktzahlen Sie abrufen möchten.

Punktzahlen für ein bestimmtes Ziel in einer Umgebung abrufen

Geben Sie einen Befehl wie den folgenden ein, um Punktzahlen für ein bestimmtes Ziel in einer Umgebung abzurufen:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/target@TARGET"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"