Présentation de l'API Discovery Shadow

Présentation

La détection des API Apigee Shadow détecte les API Shadow (également appelées API non documentées) dans votre infrastructure cloud existante. Les API Shadow présentent un risque pour la sécurité de votre système, car elles peuvent ne pas être sécurisées, surveillées ni gérées.

L'utilisation de la détection d'API Shadow n'affecte pas de manière significative le trafic d'exécution ni ne le ralentit. Cependant, les latences de queue du trafic via les équilibreurs de charge observés peuvent être considérablement affectées.

Les instructions de cette page pour configurer et afficher les résultats des observations de l'API sont basées sur l'interface utilisateur d'Apigee dans la console Cloud. Vous pouvez également utiliser les API de gestion d'Apigee (APIM) pour gérer la détection d'API Shadow. Consultez la page API de gestion de la détection d'API Shadow.

Activer la découverte de l'API Shadow

La détection d'API Shadow fait partie du module complémentaire Advanced API Security d'Apigee. Pour la découverte de l'API Shadow, le module complémentaire s'applique par organisation. Pour les clients avec abonnement, il est disponible avec l'organisation Apigee. Toutefois, les clients facturés à l'usage doivent activer le module complémentaire pour au moins un environnement. La détection d'API Shadow n'est pas disponible pour les environnements d'évaluation Apigee.

Pour utiliser cette fonctionnalité, vous devez activer le module complémentaire. Si vous avez souscrit un abonnement, vous pouvez activer le module complémentaire pour votre organisation. Pour plus d'informations, consultez la page Gérer Advanced API Security pour les organisations avec abonnement. Si vous êtes un client facturé à l'usage, vous pouvez activer le module complémentaire dans vos environnements éligibles. Pour en savoir plus, consultez la page Gérer le module complémentaire Advanced API Security.

Rôles et autorisations requis pour la détection de l'API Shadow

Le tableau ci-dessous présente les rôles requis pour effectuer des tâches liées à la détection de l'API Shadow.

Tâche	Rôles requis
Activer ou désactiver Advanced API Security	Administrateur de l'organisation Apigee (roles/apigee.admin)
Créer des sources d'observation et des jobs	Administrateur de gestion des API (roles/apim.admin)
Afficher les observations	Lecteur de gestion des API (roles/apim.viewer)

Accéder à la détection de l'API Shadow dans la console Apigee

Pour accéder à la détection de l'API Shadow dans la console Apigee, procédez comme suit :

Connectez-vous à l'interface utilisateur Apigee dans la console Cloud.
Accédez à Observation de l'API > API Shadow.
La page principale affiche toutes les observations d'API déjà générées. Sélectionnez les onglets Observations des API et Tâches d'observation pour passer de l'affichage des résultats à la Création de tâches d'observation.

Créer des tâches d'observation

Les tâches d'observation fournissent les instructions dont Shadow API Discovery a besoin pour rechercher des API shadow. Procédez comme suit pour créer une tâche d'observation. Tenez compte des comportements et limites qui s'appliquent à la création de tâches d'observation.

Sélectionnez l'onglet Jobs d'observation, puis cliquez sur Créer un job d'observation.
Sélectionnez une ou plusieurs sources d'observation ou cliquez sur Créer une source d'observation en bas de la liste Sources d'observation pour créer de nouvelles sources d'emplacement si nécessaire. Notez que le processus de création de la source d'observation peut prendre plusieurs minutes.

Les sources d'observation incluent :
Nom de la source : nom que vous spécifiez pour identifier la source.
Emplacement : emplacement où observer. L'inclusion de régions sources supplémentaires permet d'obtenir une vue plus large des API de votre infrastructure. Consultez les Bonnes pratiques. Vous ne pouvez créer qu'une seule source d'observation dans un emplacement.
Réseau et Sous-réseau : réseau et sous-réseau VPC. Le sous-réseau doit se trouver dans la même région que la source d'observation.
Créer un job d'observation. Indiquez un nom de tâche d'observation, qui doit être unique pour chaque emplacement. Sélectionnez un emplacement, qui spécifie l'emplacement où auront lieu l'agrégation et le traitement des données. Toutes les données collectées dans les régions sources sont traitées dans cette région et y sont accessibles, conformément aux Règles de Google concernant la résidence des données. La création d'une tâche d'observation peut prendre quelques minutes.
Activer le job d'observation (facultatif). Vous pouvez activer la tâche lorsque vous la créez. Dans ce cas, la surveillance commence immédiatement. Si vous n'activez pas la tâche immédiatement, vous pouvez activer la tâche d'observation ultérieurement à partir de la liste des tâches d'observation.

Activer, désactiver et supprimer des tâches d'observation

Pour indiquer si une tâche d'observation existante est activée (active), sélectionnez Activer ou Désactiver dans le menu Actions de la ligne correspondant à cette tâche sur la page Tâches d'observation.

Pour supprimer une tâche d'observation existante, sélectionnez Supprimer dans le menu Actions de cette tâche. La suppression d'une tâche supprime également les résultats d'observation associés. Par conséquent, si vous souhaitez conserver les résultats tout en empêchant la poursuite de la tâche, désactivez-la plutôt que de la supprimer. Les tâches actives ne peuvent pas être supprimées. Désactivez d'abord les tâches actives si vous devez les supprimer.

Afficher les observations d'API

Pour afficher les observations d'API des tâches d'observation activées, choisissez l'onglet Observations d'API, puis sélectionnez la tâche d'observation dans la liste.

La liste des observations affiche les valeurs suivantes :

Nom d'hôte : nom d'hôte de l'API. Cliquez sur le nom d'hôte pour afficher les détails de l'observation.
Opérations d'API : nombre d'opérations d'API (telles que les requêtes GET ou PUT) observées.
Adresses IP de serveurs : adresses IP des serveurs hébergeant les API détectées.
Emplacements sources : zones sources dans lesquelles le trafic a été observé.
Dernier événement détecté (UTC) : date et heure de détection de la requête la plus récente envoyée à l'API.
Tags : liste des tags que vous ou une autre personne avez créés pour étiqueter cette observation. Pour en savoir plus, consultez la section Utiliser des tags.
Actions : actions supplémentaires disponibles pour chaque observation.

Afficher les détails de l'observation

Une fois que vous avez cliqué sur le nom d'hôte dans la liste des observations, la page des détails de l'observation s'affiche.

Détail du job d'observation de la détection de l'API Shadow

Cette page inclut les informations suivantes sur l'observation.

La boîte de résumé en haut de la page affiche les informations suivantes :
- ID d'observation de l'API : il s'agit d'un identifiant spécifique à Apigee.
- Opérations d'API : consultez la section Afficher les observations d'API pour obtenir une description de ce champ.
- Heure de création (UTC) : date et heure de création du job d'observation.
- Tags : utilisez des tags pour organiser les résultats des jobs d'observation.
- Heure du dernier événement détecté : consultez la section Afficher les observations de l'API pour obtenir une description de ce champ.
Table des opérations d'API spécifiques détectées sur cette API découverte. Pour chaque requête, les informations suivantes sont affichées :
- Chemin : chemin d'accès de la requête.
- Méthode : méthode de la requête (par exemple GET, PUT, etc.).
- Nombre : le nombre de requêtes adressées à ce chemin avec cette méthode.
- Requête de transaction : corps de la requête provenant des données de trafic. Inclut les en-têtes de requête et le nombre de transactions correspondants pour cette opération d'API.
- En-têtes de réponse de transaction : en-têtes de réponse des données de trafic. Inclut les en-têtes de réponse et le nombre de transactions correspondant pour cette opération d'API.
- Codes de réponse de transaction : codes de réponse et nombre correspondant de réponses avec ce code pour cette opération d'API.
- Première observation (UTC) : date et heure de la première observation de la requête envoyée à cette opération d'API.
- Dernière occurrence (UTC) : date et heure les plus récentes auxquelles la requête adressée à cette opération d'API a été observée.

Utiliser les tags

Les tags vous permettent de classer les résultats des observations. Les tags sont des métadonnées et ne servent qu'à votre suivi. Ils ne modifient rien aux résultats d'observation ni ne déclenchent aucune action. Par exemple, l'ajout d'un tag "Nécessite votre attention" ne crée aucune notification ni alerte. Les nouveaux résultats d'observation ne comportent pas de tags.

Les tags présentent les caractéristiques suivantes :

Vous pouvez ajouter le même tag à plusieurs résultats d'observation.
Les noms de tags peuvent inclure des caractères en minuscule et en majuscule, des chiffres et des caractères spéciaux, y compris des espaces.
Une fois qu'un tag est créé, son nom ne peut plus être modifié. Pour le renommer, supprimez-le, puis recréez-le.
Supprimer un tag de tous les résultats d'observation le supprime du système.

Vous pouvez gérer les tags depuis la liste d'observation ou la page des détails de l'observation.

Pour gérer les tags à partir de la liste des observations sur les API :

Consultez les tags existants dans la colonne Tags de la liste des observations.
Pour gérer les tags d'un résultat, sélectionnez Gérer les tags dans le menu Actions de la ligne correspondant à ce résultat.
Pour gérer les tags d'un ou de plusieurs résultats simultanément, sélectionnez plusieurs résultats dans la liste, puis Gérer les tags en haut de la liste.

Pour gérer les tags à partir des détails de l'observation de l'API :

Consultez les tags existants dans la section Tags.
Pour ajouter ou gérer des tags, sélectionnez Gérer les tags en haut de la page.

Dans le panneau latéral Gérer les tags, sélectionnez des tags existants ou ajoutez-en de nouveaux pour ajouter des tags. Pour supprimer des tags, désélectionnez-les. Cliquez sur Enregistrer pour enregistrer les nouveaux tags.

Bonnes pratiques

Nous vous recommandons de suivre ces pratiques lorsque vous utilisez la détection de l'API Shadow :

Suivez les règles de résidence des données de votre organisation pour vous assurer du respect des réglementations et des lois applicables.
Aggrégez les données de régions sources aussi nombreuses que possible pour obtenir la meilleure corrélation interrégionale. L'inclusion de plusieurs régions sources dans vos tâches d'observation permet d'obtenir une vue plus large des API dans votre infrastructure.

Comportements et limites

Cette section répertorie les comportements et les limites qui s'appliquent à la détection de l'API Shadow :

L'utilisation de la détection d'API Shadow ne garantit pas l'observation de 100% du trafic, ni la découverte de toutes les API Shadow.
Shadow API Discovery ne trouve les API Shadow que sur votre infrastructure Google Cloud.
La détection de l'API Shadow n'est actuellement compatible qu'avec les équilibreurs de charge d'application régionaux.
La détection d'API Shadow recherche des API de protocole HTTP, et non gRPC.
Avertissement : La détection d'API Shadow est compatible avec les équilibreurs de charge sur un réseau par projet. Si vous activez la détection d'API Shadow sur un projet comportant plusieurs réseaux, vous risquez d'observer un comportement inattendu.
Avertissement : L'activation de la détection d'API Shadow peut entraîner une augmentation de la latence pour les appels de l'équilibreur de charge dans tous les réseaux du projet.
La détection du trafic par une tâche d'observation nouvellement activée peut prendre jusqu'à 60 minutes.
Pour pouvoir détecter les API Shadow, du trafic doit transiter par les équilibreurs de charge de vos projets observés. La détection d'API Shadow nécessite au minimum quelques minutes à quelques heures de détection du trafic, en fonction du volume de trafic. Le trafic creux nécessite des temps d'observation plus longs avant que les résultats ne soient disponibles.
Par région, il existe une limite d'une source d'observation et un maximum de trois jobs d'observation. Si vous avez besoin de plus de trois jobs d'observation, veuillez contacter Google Cloud Customer Care pour discuter du cas d'utilisation.
Les tâches d'observation peuvent être créées, désactivées ou supprimées, mais pas modifiées. Si vous devez modifier une tâche d'observation, supprimez-la et recréez-la.
Seules certaines régions sont compatibles avec les tâches de détection de l'API Shadow pour le moment. Consultez la liste des régions compatibles avec cette requête :
```
curl -H "Authorization: Bearer $(gcloud auth print-access-token)"
https://apim.googleapis.com/v1alpha/projects/{PROJECT}/locations
```