API des scores et des profils de sécurité

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Présentation

Cette page explique comment gérer les scores de sécurité et les profils de sécurité de l'évaluation des risques (également appelés simplement "profils") à l'aide d'API. Cette page présente des exemples de requêtes API.

Pour obtenir une présentation de la fonctionnalité d'évaluation des risques, y compris ses limites et des instructions sur l'utilisation de l'interface utilisateur, consultez la page Présentation de l'évaluation des risques et interface utilisateur.

Exemples d'API Risk Assessment v2

Paramètres pour les exemples d'API v2

Les exemples de cette section peuvent utiliser les paramètres suivants :

ORG est votre organisation.
ENV est l'environnement dans lequel vous souhaitez calculer les scores.
PROFILE_ID est le nom du profil. PROFILE_ID peut être google-default ou le nom d'un profil personnalisé que vous créez.
PROFILE_DESC (facultatif) est la description du profil. La description du profil doit être lisible et fournir suffisamment d'informations pour le différencier des autres profils.
PROXY_NAME : nom du proxy
$TOKEN est la variable d'environnement d'un jeton d'accès OAuth.

Récupérer les résultats de l'évaluation de sécurité par lot

Les utilisateurs disposant des rôles Security Admin ou Security Viewer sont autorisés à effectuer un calcul ad hoc de l'évaluation des risques. Vous devez spécifier le profil de sécurité, le champ d'application (l'environnement Apigee) et les ressources à évaluer. Les ressources peuvent être include_all_resources: true pour calculer toutes les ressources du champ d'application ou seulement quelques-unes. Pour en savoir plus sur cette fonctionnalité, consultez securityAssessmentResults.batchCompute dans la documentation de référence de l'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": {}
  }'

Voici une réponse potentielle à la requête :

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

Gérer les profils de sécurité

Cette section fournit des exemples de gestion des profils de sécurité à l'aide des API et n'est pas exhaustive. Pour en savoir plus, consultez la documentation de référence de l'API securityProfilesV2.

Obtenir les profils de sécurité personnalisés existants

Cette commande récupère les informations de tous les profils de sécurité de votre projet :

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

Cette commande récupère les métadonnées d'un profil de sécurité spécifique et peut être utilisée pour récupérer des informations sur le profil google-default ainsi que sur les profils personnalisés :

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

Créer un profil de sécurité personnalisé

Pour créer un profil de sécurité personnalisé, utilisez une commande comme celle-ci :

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

Mettre à jour un profil de sécurité personnalisé existant

Pour mettre à jour un profil existant, utilisez une commande comme celle-ci :

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

où UPDATE_MASK peut être l'une des valeurs suivantes, le cas échéant : description, profile_assessment_configs, description,profile_assessment_configs ou * (tout). Si vous spécifiez le masque de mise à jour *, la requête met à jour tous les champs, ce qui peut supprimer des valeurs si elles ne sont pas incluses dans la requête.

Si vous omettez update_mask, seuls les champs fournis dans la requête de mise à jour sont mis à jour.

Supprimer un profil de sécurité personnalisé

Pour supprimer un profil de sécurité personnalisé :

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

Risk Assessment v1

Cette section fournit des informations et des exemples sur les API Risk Assessment v1.

Limites des scores de sécurité lors de l'utilisation des API

Les scores de sécurité présentent les limites suivantes lorsqu'ils sont utilisés à partir des API de scores et de profils de sécurité :

Champs de saisie compatibles au format JSON :
- timeRange: les valeurs sont limitées par les critères décrits dans la documentation de référence de l'API computEnvironmentScores.
- filters : Consultez la section Filtres compatibles avec l'API.
- pageSize : nombre maximal de sous-composants à renvoyer sur une seule page : 100.
L'utilisation de plusieurs filtres d'entrée n'est pas acceptée.
Le champ d'impact dans la réponse n'est pas accepté. (Le champ "Impact" correspond à l'impact potentiel de cette recommandation sur le score global. Cela indique l'importance de la recommandation pour améliorer le score.)

Pour connaître les limites générales du score de sécurité non spécifiques à l'utilisation des API, consultez la page Limites des scores de sécurité v1.

Paramètres dans des exemples d'appels d'API

Les sections suivantes fournissent des exemples d'appels d'API et peuvent utiliser les paramètres suivants :

ORG est votre organisation.
ENV est l'environnement dans lequel vous souhaitez calculer les scores.
ENVGROUP est un groupe d'environnements contenant l'environnement.
PROFILE_ID est le nom du profil. PROFILE_ID peut être default ou le nom d'un profil personnalisé que vous créez.
PROFILE_ID doit contenir entre 1 et 63 caractères, qui peuvent être des lettres minuscules, des chiffres 0-9 ou des traits d'union. Le premier caractère doit être une lettre minuscule. Le dernier caractère doit être une lettre minuscule ou un chiffre.
PROXY_NAME : nom du proxy
RESOURCES peut être :
- {"all_resources":true} pour toutes les ressources du champ d'application.
- {"includes": { "resources": [{"name": "<proxy-name>"}]} pour surveiller un ou plusieurs proxys spécifiés. Par exemple, {"includes": { "resources": [{"name": "my-proxy-1"}]} pour surveiller le proxy appelé my-proxy-1.
- {"excludes": { "resources": [{"name": "<proxy-name>"}]} pour surveiller toutes les ressources, à l'exception d'un ou de plusieurs proxys spécifiés. Par exemple, {"excludes": { "resources": [{"name": "my-proxy-1"}]} surveille toutes les ressources, à l'exception du proxy appelé my-proxy-1.
$TOKEN est la variable d'environnement d'un jeton d'accès OAuth.
timeRange correspond à la période du score.

Exemples d'API Risk Assessment v1

Filtres compatibles avec l'API

Le tableau suivant répertorie les filtres compatibles avec l'API et leurs chemins de composants.

Filtre	Chemin du composant
Scores d'environnement	`/org@ORG/envgroup@ENVGROUP/env@ENV`
La source répertorie tous les composants sous-jacents	`/org@ORG/envgroup@ENVGROUP/env@ENV/source`
Scores d'utilisation abusive	`/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse`
Scores pour tous les proxys	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
Scores pour un proxy spécifique	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
Scores de règle pour un proxy spécifique	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual`
Scores de règle de médiation pour un proxy spécifique	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation`
Scores de règle de sécurité pour un proxy spécifique	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
Scores de règle d'authentification pour un proxy spécifique	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
Score de règle CORS pour un proxy spécifique	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
Scores de règle de détection des menaces pour un proxy spécifique	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
Scores de règle pour tous les proxys dans l'environnement	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
Scores de règle de médiation pour tous les proxys dans l'environnement	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
Score de règle de sécurité pour tous les proxys dans l'environnement	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
Scores de règle d'authentification pour tous les proxys dans l'environnement	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
Scores de règle CORS pour tous les proxys dans l'environnement	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
Scores de règle de détection des menaces pour tous les proxys dans l'environnement	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat`

Utiliser le profil de sécurité par défaut

Les exemples suivants montrent comment utiliser le profil de sécurité par défaut. Consultez la section Paramètres dans les exemples d'appels d'API pour connaître les paramètres utilisés dans les exemples.

Associer le profil de sécurité par défaut à un environnement

Pour afficher les scores de sécurité, vous devez associer un profil à l'environnement dont vous souhaitez évaluer la sécurité. Pour associer le profil de sécurité par défaut à un environnement, exécutez la commande suivante :

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"

Remarque : Le paramètre securityProfileRevisionId est obsolète. Si vous incluez ce paramètre dans un appel d'API, Advanced API Security utilise la dernière révision du profil, quelle que soit la valeur du paramètre.

Obtenir la définition de profil de sécurité par défaut

Pour obtenir la définition du profil de sécurité par défaut, saisissez la commande suivante :

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

Dissocier le profil de sécurité par défaut d'un environnement

Si vous devez dissocier le profil par défaut d'un environnement, procédez comme suit :

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

Utiliser un profil de sécurité personnalisé

Vous pouvez créer un profil de sécurité personnalisé avec un appel d'API de l'une des manières suivantes :

Définir explicitement le profil dans le corps de l'appel.
Joindre un fichier JSON contenant la définition du profil à l'appel.

Les sections suivantes présentent des exemples des deux méthodes. Consultez la section Paramètres dans les exemples d'appels d'API pour connaître les paramètres utilisés dans les exemples.

Les champs suivants dans les exemples d'appels d'API spécifient le profil personnalisé :

description : description du profil personnalisé.
profileConfig : liste des catégories à inclure dans le profil personnalisé. Il peut s'agir de n'importe quel sous-ensemble des catégories de sécurité suivantes :
- abuse
- authorization
- cors
- mtls
- mediation
- threat

Définir le profil dans le corps d'un appel d'API

Pour définir un profil personnalisé dans le corps d'un appel d'API, saisissez une commande semblable à celle-ci :

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

Cela crée un profil personnalisé qui inclut les catégories cors et threat, et renvoie une réponse semblable à celle-ci :

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

Définir le profil en associant un fichier JSON à un appel d'API

Vous pouvez également définir un profil de sécurité personnalisé en associant un fichier JSON qui le définit à un appel d'API. Par exemple, créez d'abord le fichier JSON suivant :

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

Ceci définit un profil avec les catégories cors et threat. Vous pouvez ensuite créer un profil sur la base de ces catégories comme suit :

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

où create_profile.json est le nom du fichier JSON décrit ci-dessus.

Obtenir une définition de profil de sécurité personnalisée

Pour obtenir la définition d'un profil de sécurité personnalisé, saisissez une commande semblable à celle-ci :

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

Dissocier un profil de sécurité personnalisé d'un environnement

Pour dissocier un profil de sécurité personnalisé d'un environnement, saisissez une commande semblable à celle-ci :

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

Supprimer un profil de sécurité personnalisé

Pour supprimer un profil de sécurité personnalisé, saisissez une commande semblable à celle-ci :

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

Obtenir les scores d'un environnement

Les sections suivantes présentent des exemples d'obtention de scores pour un environnement. Consultez la section Paramètres dans les exemples d'appels d'API pour connaître les paramètres utilisés dans les exemples.

Obtenir tous les scores d'un environnement

Pour obtenir tous les scores d'un environnement, saisissez une commande semblable à celle-ci :

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"

Consultez la page de référence de computeEnvironmentScores pour obtenir la description de la requête et de la réponse.

Obtenir les scores des sources d'un environnement

Pour obtenir les scores des sources d'un environnement, saisissez une commande semblable à celle-ci :

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"

Obtenir le score d'utilisation abusive à la source pour un environnement

Pour obtenir le score d'utilisation abusive à la source pour un environnement, saisissez une commande semblable à celle-ci :

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"

Obtenir les scores pour tous les proxys d'un environnement

Pour obtenir les scores pour tous les proxys d'un environnement, saisissez une commande semblable à celle-ci :

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"

Obtenir les scores d'un proxy spécifique dans un environnement

Pour obtenir les scores d'un proxy spécifique dans un environnement, saisissez une commande semblable à celle-ci :

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"

où PROXY est le proxy dont vous souhaitez obtenir les scores.

Obtenir les scores d'une cible spécifique dans un environnement

Pour obtenir des scores pour une cible spécifique dans un environnement, saisissez une commande semblable à celle-ci :

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"