API Punteggi e profili di sicurezza

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

Oltre a visualizzare i punteggi di sicurezza e i profili di sicurezza nella UI di Apigee, puoi anche accedervi utilizzando l'API dei profili e dei punteggi di sicurezza. Questa pagina presenta alcuni esempi di utilizzo dell'API Security score and Profiles.

Limitazioni dei punteggi di sicurezza quando si utilizzano le API

Quando vengono utilizzati dalle API dei punteggi e dei profili di sicurezza, i punteggi di sicurezza presentano le seguenti limitazioni:

• Campi di immissione supportati in JSON:
  • timeRange: la lunghezza dell'intervallo di tempo può essere al massimo di 14 giorni, mentre startTime e endTime per l'intervallo di tempo devono rientrare negli ultimi 90 giorni. Vedi Intervallo di tempo.
  • filters: consulta la sezione Filtri supportati dall'API.
  • pageSize: numero massimo di sottocomponenti da restituire in una singola pagina: 100.
• Non sono supportati filtri di input multipli.
• Il campo dell'impatto nella risposta non è supportato. Il campo impatto indica l'impatto potenziale di questo suggerimento sul punteggio complessivo. Ciò indica quanto sia importante questo consiglio per migliorare il punteggio.

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

Nota: i punteggi di sicurezza del proxy sono interessati solo dai criteri collegati a un flusso. Consulta In che modo i criteri influiscono sui punteggi di sicurezza del proxy.

Ritardi nei dati

I dati su cui si basano i punteggi di sicurezza di Advanced API Security presentano i seguenti ritardi a causa del modo in cui vengono elaborati:

• Quando abiliti Advanced API Security in un'organizzazione, possono essere necessarie fino a 6 ore prima che i punteggi per i proxy e le destinazioni esistenti vengano riportati in un ambiente.
• La presenza nel punteggio dell'ambiente dei nuovi eventi relativi ai proxy (deployment e annullamento del deployment) e alle destinazioni (creazione, aggiornamento, eliminazione) in un ambiente può richiedere fino a 6 ore.
• I dati che fluiscono nella pipeline di analisi Apigee hanno un ritardo medio massimo di 15-20 minuti. Di conseguenza, i dati relativi all'abuso dei punteggi della fonte presentano un ritardo nell'elaborazione di circa 15-20 minuti.

Parametri nelle chiamate API di esempio

Le seguenti sezioni forniscono esempi di chiamate API che utilizzano l'API dei profili e dei punteggi di sicurezza. Le chiamate API contengono i seguenti parametri:

• ORG è la tua organizzazione.
• ENV è l'ambiente in cui vuoi calcolare 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.

• $TOKEN è la variabile di ambiente per un token di accesso OAuth.
• timeRange è l'intervallo di tempo per i punteggi.

Intervallo di tempo

L'intervallo di tempo per i dati su cui vengono calcolati i punteggi di sicurezza. Puoi impostare l'intervallo di tempo specificando un'ora di inizio e di fine per i punteggi nel seguente formato:

"timeRange":
  {
    "startTime": "YYYY-MM-DDT00:00:00Z",
    "endTime": "YYYY-MM-DDT00:00:00Z"
  }

Sia startTime che endTime devono essere riferiti agli ultimi 90 giorni.

Usare il profilo di sicurezza predefinito

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

Collega 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 collegare il profilo di sicurezza predefinito a un ambiente, utilizza il comando seguente:

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"

Nota: il parametro securityProfileRevisionId è stato deprecato. Se includi questo parametro in una chiamata API, Advanced API Security utilizzerà la revisione più recente del profilo, indipendentemente dal valore del parametro.

Ottieni la definizione del profilo di sicurezza predefinita

Per visualizzare 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"

Scollega il profilo di sicurezza predefinito da un ambiente

Se devi scollegare il profilo predefinito da un ambiente:

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

Usa un profilo di sicurezza personalizzato

Anteprima - Profili personalizzati di sicurezza API avanzata

Questa funzionalità è coperta dai Termini dell'offerta pre-GA dei Termini di servizio di Google Cloud. Le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Il supporto per il lancio in anteprima dei profili personalizzati di sicurezza delle API avanzate è disponibile tramite il forum della community di Google Cloud - Apigee.

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

• Definisci in modo esplicito 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

  Definisci 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 corri e minacce e restituisce la seguente risposta:

  {
    "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 definisce il profilo 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 categorie di valore e minaccia. Dopodiché potrai 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.

  Ottieni una definizione di profilo di sicurezza personalizzata

  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"

  Scollega 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"

  Nota: se elimini un profilo di sicurezza personalizzato, perderai tutti i punteggi relativi al profilo e tutti gli ambienti collegati al profilo verranno scollegati automaticamente.

  Ottieni punteggi per un ambiente

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

  Ottieni tutti i punteggi 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"

  Consulta la pagina di riferimento computeEnvironmentScores per una descrizione della richiesta e della risposta.

  Ottieni punteggi di origine per un ambiente

  Per ottenere i punteggi di 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"}]
             }' \
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

  Ottieni il punteggio degli abusi nell'origine per un ambiente

  Per ottenere il punteggio degli abusi nell'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"

  Ottieni punteggi per tutti i proxy in un ambiente

  Per ottenere i punteggi per 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"

  Ottieni punteggi per un proxy specifico in un ambiente

  Per ottenere punteggi per 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.

  Ottieni 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"

  Filtri supportati nell'API

  La seguente tabella elenca i filtri supportati nell'API e i relativi percorsi dei componenti. Nei percorsi dei componenti, sostituisci le variabili come segue:

  • ORG: la tua organizzazione.
  • ENV: l'ambiente in cui visualizzi i punteggi.
  • PROXY_NAME: il nome del proxy.

  Filtro	Percorso componente
  Punteggi di 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 illeciti	/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse
  Punteggi per tutti i proxy	/org@ORG/envgroup@ENVGROUP/env@ENV/proxies
  Punteggi per proxy specifico	/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME
  Punteggi dei criteri per 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 delle norme sulla mediazione per un proxy specifico	/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation
  Punteggi dei criteri di sicurezza per proxy specifico	/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security
  Punteggi dei criteri di autenticazione per proxy specifico	/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth
  Punteggio dei criteri CORS per proxy specifico	/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors
  Punteggi dei criteri di minaccia per 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 delle norme di mediazione per tutti i proxy nel 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