API per punteggi e profili di sicurezza

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

Questa pagina descrive come gestire i punteggi di sicurezza e i profili di sicurezza della valutazione del rischio (chiamati anche semplicemente "profili") utilizzando le API. Questa pagina presenta richieste API di esempio.

Per una panoramica della funzionalità di valutazione del rischio, incluse le limitazioni, e le istruzioni per l'utilizzo dell'interfaccia utente, consulta Panoramica della valutazione del rischio e dell'interfaccia utente.

Esempi di API Risk Assessment v2

Parametri per gli esempi dell'API v2

Gli esempi in questa sezione possono utilizzare i seguenti parametri:

  • ORG è la tua organizzazione.
  • ENV è l'ambiente in cui vuoi che vengano calcolati i punteggi.
  • PROFILE_ID è il nome del profilo. PROFILE_ID può essere google-default o il nome di un profilo personalizzato creato da te.
  • PROFILE_DESC (facoltativo) è la descrizione del profilo. Deve essere una descrizione del profilo leggibile da una persona che fornisca informazioni sufficienti per distinguerlo dagli altri profili.
  • PROXY_NAME: il nome del proxy.
  • $TOKEN è la variabile di ambiente per un token di accesso OAuth.

Recuperare i risultati della valutazione della sicurezza collettiva

Gli utenti con i ruoli Security Admin o Security Viewer dispongono delle autorizzazioni per eseguire un calcolo ad hoc della valutazione del rischio. Dovrai specificare il profilo di sicurezza, l'ambito (l'ambiente Apigee) e le risorse da valutare. Le risorse possono essere include_all_resources: true per calcolare su tutte le risorse nell'ambito o solo su alcune. Per ulteriori informazioni su questa funzionalità, consulta securityAssessmentResults.batchCompute nella documentazione di riferimento dell'API Apigee Management.

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

Questa è una potenziale risposta alla richiesta:

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

Gestire i profili di sicurezza

Questa sezione fornisce esempi per la gestione dei profili di sicurezza mediante le API e non è esaustiva. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API securityProfilesV2.

Visualizzare i profili di sicurezza personalizzati esistenti

Questo comando recupera le informazioni per tutti i profili di sicurezza del progetto:

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

Questo comando recupera i metadati di un profilo di sicurezza specifico e può essere utilizzato per recuperare informazioni sul profilo google-default e sui profili personalizzati:

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

Creare un nuovo profilo di sicurezza personalizzato

Per creare un nuovo profilo di sicurezza personalizzato, utilizza un comando come questo:

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

Aggiornare un profilo di sicurezza personalizzato esistente

Per aggiornare un profilo esistente, utilizza un comando come:

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

dove UPDATE_MASK può essere uno di questi valori, se presente: description, profile_assessment_configs, description,profile_assessment_configs o * (tutto). Se specifichi la maschera di aggiornamento *, la richiesta aggiorna tutti i campi, il che potrebbe rimuovere i valori se non sono inclusi nella richiesta.

Se ometti update_mask, vengono aggiornati solo i campi forniti nella richiesta di aggiornamento.

Eliminare un profilo di sicurezza personalizzato

Per eliminare un profilo di sicurezza personalizzato:

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

Valutazione del rischio v1

Questa sezione mostra informazioni ed esempi per le API Risk Assessment v1.

Limitazioni dei punteggi di sicurezza durante l'utilizzo delle API

I punteggi di sicurezza presentano le seguenti limitazioni se utilizzati dalle API dei punteggi di sicurezza e dei profili:

  • Campi di input supportati in JSON:
  • Non sono supportati più filtri di input.
  • Il campo Impatto nella risposta non è supportato. Il campo Impatto indica l'impatto potenziale di questo consiglio sul punteggio complessivo. Questo indica quanto sia importante questo consiglio per migliorare il punteggio.

Per le limitazioni generali del punteggio di sicurezza non specifiche per l'utilizzo dalle API, consulta Limitazioni dei punteggi di sicurezza v1.

Parametri nelle chiamate API di esempio

Le sezioni seguenti forniscono esempi di chiamate API e possono utilizzare i seguenti parametri:

  • ORG è la tua organizzazione.
  • ENV è l'ambiente in cui vuoi che vengano calcolati i punteggi.
  • ENVGROUP è un gruppo di ambienti contenente l'ambiente.
  • PROFILE_ID è il nome del profilo. PROFILE_ID può essere default o il nome di un profilo personalizzato creato da te.

    PROFILE_ID deve contenere da 1 a 63 caratteri, che possono essere lettere minuscole, numeri da 0 a 9 o trattini. Il primo carattere deve essere una lettera minuscola. L'ultimo carattere deve essere una lettera minuscola o un numero.

  • PROXY_NAME: il nome del proxy.
  • RESOURCES può essere:
    • {"all_resources":true} per tutte le risorse nell'ambito.
    • {"includes": { "resources": [{"name": "<proxy-name>"}]} per monitorare uno o più proxy specificati. Ad esempio, {"includes": { "resources": [{"name": "my-proxy-1"}]} per monitorare il proxy chiamato my-proxy-1.
    • {"excludes": { "resources": [{"name": "<proxy-name>"}]} per monitorare tutte le risorse tranne uno o più proxy specificati. Ad esempio, {"excludes": { "resources": [{"name": "my-proxy-1"}]} monitora tutte le risorse tranne il proxy denominato my-proxy-1.
  • $TOKEN è la variabile di ambiente per un token di accesso OAuth.
  • timeRange è l'intervallo di tempo per i punteggi.

Esempi di API Risk Assessment v1

Filtri supportati nell'API

La tabella seguente elenca i filtri supportati nell'API e i relativi percorsi dei componenti.

Filtro Percorso del componente
Punteggi dell'ambiente /org@ORG/envgroup@ENVGROUP/env@ENV
L'origine assegna un punteggio a tutti i componenti sottostanti /org@ORG/envgroup@ENVGROUP/env@ENV/source
Punteggi relativi agli abusi /org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse
Punteggi per tutti i proxy /org@ORG/envgroup@ENVGROUP/env@ENV/proxies
Punteggi per un proxy specifico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME
Punteggi delle norme per un proxy specifico
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual
Punteggi dei criteri di mediazione per un proxy specifico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation
Punteggi dei criteri di sicurezza per un proxy specifico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security
Punteggi delle norme di autenticazione per un proxy specifico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth
Punteggio del criterio CORS per un proxy specifico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors
Punteggi dei criteri di minaccia per un proxy specifico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat
Punteggi dei criteri per tutti i proxy nell'ambiente
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual
Punteggi dei criteri di mediazione per tutti i proxy nell'ambiente /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation
Punteggi dei criteri di sicurezza per tutti i proxy nell'ambiente /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security
Punteggi dei criteri di autenticazione per tutti i proxy nell'ambiente /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth
Punteggi dei criteri CORS per tutti i proxy nell'ambiente /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors
Punteggi dei criteri di minaccia per tutti i proxy nell'ambiente /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat

Utilizzare il profilo di sicurezza predefinito

Gli esempi riportati di seguito mostrano come utilizzare il profilo di sicurezza predefinito. Consulta Parametri nelle chiamate API di esempio per i parametri utilizzati negli esempi.

Collegare il profilo di sicurezza predefinito a un ambiente

Per visualizzare i punteggi di sicurezza, devi collegare un profilo all'ambiente di cui vuoi valutare la sicurezza. Per associare il profilo di sicurezza predefinito a un ambiente, utilizza il seguente comando:

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"
Ottenere la definizione del profilo di sicurezza predefinito

Per ottenere la definizione del profilo di sicurezza predefinito, inserisci il seguente comando:

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

Scollegare il profilo di sicurezza predefinito da un ambiente

Se devi scollegare il profilo predefinito da un ambiente, procedi nel seguente modo:

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

Utilizzare un profilo di sicurezza personalizzato

Puoi creare un profilo di sicurezza personalizzato con una chiamata API in uno dei seguenti modi:

  • Definisci esplicitamente il profilo nel corpo della chiamata.
  • Allega alla chiamata un file JSON contenente la definizione del profilo.

Le sezioni seguenti forniscono esempi di entrambi i metodi. Consulta Parametri nelle chiamate API di esempio per i parametri utilizzati negli esempi.

I seguenti campi nelle chiamate API di esempio specificano il profilo personalizzato:

  • description: una descrizione del profilo personalizzato.
  • profileConfig: un elenco delle categorie da includere nel profilo personalizzato. Può essere qualsiasi sottoinsieme delle seguenti categorie di sicurezza:
    • abuse
    • authorization
    • cors
    • mtls
    • mediation
    • threat
Definire il profilo nel corpo di una chiamata API

Per definire un profilo personalizzato nel corpo di una chiamata API, inserisci un comando simile al seguente:

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":{}}
           ]
         }
       }'

Viene creato un profilo personalizzato che include le categorie cors e threat e restituisce una risposta come questa:

{
  "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"
  }
Definisci il profilo allegando un file JSON a una chiamata API

Puoi anche definire un profilo di sicurezza personalizzato allegando un file JSON che lo definisce a una chiamata API. Ad esempio, crea prima il seguente file JSON:

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

Questo definisce un profilo con le categorie cors e threat. Poi, puoi creare un profilo basato su queste categorie come segue:

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

dove create_profile.json è il nome del file JSON descritto sopra.

Ottenere una definizione del profilo di sicurezza personalizzato

Per ottenere la definizione di un profilo di sicurezza personalizzato, inserisci un comando simile al seguente:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"
Scollegare un profilo di sicurezza personalizzato da un ambiente

Per scollegare un profilo di sicurezza personalizzato da un ambiente, inserisci un comando simile al seguente:

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

Per eliminare un profilo di sicurezza personalizzato, inserisci un comando simile al seguente:

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

Ottenere i risultati per un ambiente

Le sezioni seguenti presentano esempi di assegnazione di punteggi a un ambiente. Consulta Parametri nelle chiamate API di esempio per i parametri utilizzati negli esempi.

Ottenere tutti i risultati per un ambiente

Per ottenere tutti i punteggi per un ambiente, inserisci un comando simile al seguente:

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"

Per una descrizione della richiesta e della risposta, consulta la pagina di riferimento computeEnvironmentScores.

Recuperare i punteggi delle origini per un ambiente

Per ottenere i punteggi delle origini per un ambiente, inserisci un comando simile al seguente:

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"
Ottenere il punteggio di abuso nell'origine per un ambiente

Per ottenere il punteggio di attività illecita in origine per un ambiente, inserisci un comando simile al seguente:

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"
Ottenere i punteggi per tutti i proxy in un ambiente

Per ottenere i punteggi di tutti i proxy in un ambiente, inserisci un comando simile al seguente:

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"
Ottenere i punteggi per un proxy specifico in un ambiente

Per ottenere i punteggi di un proxy specifico in un ambiente, inserisci un comando simile al seguente:

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"

dove PROXY è il proxy di cui vuoi ottenere i punteggi.

Ottenere i punteggi per un target specifico in un ambiente

Per ottenere i punteggi per un target specifico in un ambiente, inserisci un comando simile al seguente:

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"