API des scores et des profils de sécurité

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

Consultez la documentation d' Apigee Edge.

En plus d'afficher les scores et les profils de sécurité dans l'interface utilisateur d'Apigee, vous pouvez également y accéder à l'aide de l'API des scores et des profils de sécurité. Cette page présente quelques exemples d'utilisation de l'API des scores et des profils de sécurité.

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 : la durée de la période ne peut pas dépasser 14 jours et les valeurs startTime et endTime doivent être comprises dans les 90 derniers jours. Consultez la section Période.
    • 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 des scores de sécurité non spécifiques à une utilisation des API, consultez la section Limites des scores de sécurité.

Retards de données

Les données sur lesquelles se basent les scores de sécurité d'Advanced API Security sont soumises aux délais suivants, en raison de la façon dont les données sont traitées :

  • Lorsque vous activez Advanced API Security dans une organisation, l'actualisation des scores des proxys et des cibles existants dans un environnement peut prendre jusqu'à six heures.
  • Les nouveaux événements liés aux proxys (déploiement et annulation du déploiement) et aux cibles (créer, mettre à jour, supprimer) dans un environnement peuvent prendre jusqu'à six heures pour apparaître dans le score de l'environnement.
  • Les données transmises par le pipeline Apigee Analytics ont un retard moyen de 15 à 20 minutes. Par conséquent, les données d'utilisation abusive des scores des sources présentent un retard de traitement d'environ 15 à 20 minutes.

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

Les sections suivantes fournissent des exemples d'appels d'API qui utilisent les API de scores et de profils de sécurité. Les appels d'API contiennent 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.

  • $TOKEN est la variable d'environnement d'un jeton d'accès OAuth.
  • timeRange correspond à la période du score.

Période

Période pour laquelle les données de calcul des scores de sécurité sont calculées. Vous pouvez définir la période en spécifiant une heure de début et une heure de fin pour les scores, au format suivant :

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

Les valeurs de startTime et endTime doivent être comprises dans les 90 derniers jours.

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"

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 la réponse suivante :

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

    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"

    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"

    Filtres compatibles avec l'API

    Le tableau suivant répertorie les filtres compatibles avec l'API et leurs chemins de composants. Dans les chemins des composants, remplacez les variables comme suit :

    • ORG : votre organisation
    • ENV : environnement dans lequel vous consultez les scores
    • PROXY_NAME : nom du proxy
    Filter 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