API 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 profili e i punteggi di sicurezza della valutazione del rischio utilizzando le API. Presenta anche 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

Recuperare i risultati della valutazione di sicurezza batch

Gli utenti con il ruolo Security Admin o Security Viewer dispongono delle autorizzazioni per eseguire un calcolo ad hoc di valutazione del rischio. Dovrai specificare il profilo di sicurezza, l'ambito e le risorse da valutare. Le risorse possono essere da include_all_resources: true a in 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": {}
  }'

dove:

  • ORG è la tua organizzazione.
  • ENV è l'ambiente in cui visualizzi i punteggi.

Questa è una potenziale risposta alla richiesta precedente.

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

Valutazione del rischio v1

Questa sezione mostra informazioni ed esempi per le API di valutazione del rischio v1.

Limitazioni dei punteggi di sicurezza durante l'utilizzo delle API

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

  • Campi di immissione supportati in JSON:
  • Non sono supportati filtri di input multipli.
  • Il campo dell'impatto nella risposta non è supportato. (Il campo impatto è il potenziale impatto consigliato sul punteggio complessivo. Questo indica quanto sia importante questo consiglio per migliorare il punteggio.

Per i limiti del punteggio di sicurezza generale non specifici per l'uso delle API, consulta Limitazioni dei punteggi di sicurezza v1.

Parametri nelle chiamate API di esempio

Le seguenti sezioni 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.

    Il campo PROFILE_ID deve contenere da 1 a 63 caratteri, che possono essere lettere minuscole, numeri 0-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 tutto 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 dell'API Risk Assessment v1

Filtri supportati nell'API

Nella tabella seguente sono elencati i filtri supportati nell'API e i relativi i percorsi dei componenti.

Filtro Percorso del 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 un proxy specifico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME
Punteggi dei criteri 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 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 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

I seguenti esempi mostrano come utilizzare il parametro 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 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"

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

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

In questo modo viene creato un profilo personalizzato che include le categorie di rischio e minaccia. 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 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 categorie di valore e minaccia. Puoi quindi creare un profilo su queste categorie, come indicato di seguito:

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"

Ottenere i risultati per un ambiente

Le sezioni seguenti presentano esempi di come ottenere punteggi per un ambiente. Consulta Parametri nelle chiamate API di esempio per 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 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"
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 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.

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"