Extraction des données d'activité et d'événement

Introduction

L'obtention des détails des événements de votre locataire IBM Security Verify est aussi simple que deux appels API qui permettent à vos outils SIEM, de Business Intelligence (BI) et d'analyse d'utiliser tous les événements d'audit de la plateforme.

L'API de l'événement IBM Security Verify permet de.. :

1. Taille des pages
2. Filtrage sur les types d'événements (par exemple, gestion, authentification, sso, etc.)
3. Filtrage des ressources (par exemple, utilisateur, jeton, app_consent)
4. Filtrage temporel (c'est-à-dire recherche après une heure ou entre deux heures)

❗️

Gestion d'un grand nombre d'événements

L'API sur les événements est limitée à 10 000 événements dans la réponse. L'API fournit un moyen simple pour vous permettre d'effectuer des appels ultérieurs en toute simplicité. Il inclut un objet search_after qui comprend une heure et un identifiant représentant le dernier événement de l'appel en cours, ce qui vous permet d'effectuer un deuxième appel sans chevauchement d'événements.

Collecte d'informations

Le client API utilisé par l'application doit disposer des autorisations suivantes dans IBM Security Verify:

• Gérer les rapports
• Lire les rapports

L'application doit avoir acquis un jeton d'accès à l'aide du flux " Client Credentials "

Variables

Les variables suivantes sont nécessaires pour ce guide :

Obtenir tous les événements

L'appel le plus simple à faire est de récupérer tous les événements de la plateforme sans filtre. Cependant, dans les environnements plus vastes, vous obtiendrez probablement plus de 10 000 enregistrements, ce qui doit être géré par la pagination.

curl -X GET "https://${tenant_url}/v1.0/events" -H "Authorization: Bearer ${access_token}"

Réponse attendue :

{
    "response": {
        "events": {
            "search_after": {
                "total_events": 54,
                "max_size_limit": "false",
                "time": "1559156150862",
                "id": "def9ea72-30ce-4589-800a-7306e306ea2e"
            },
            "events": [
                {
                    "geoip": {
                        "continent_name": "North America",
                        "country_iso_code": "US",
                        "country_name": "United States",
                        "location": {
                            "lon": "-97.822",
                            "lat": "37.751"
                        }
                    },
                    {...},
                    {...},
                    {...}
                }...

Pour filtrer les événements spécifiques de certains types, nous utiliserons une chaîne de requête de filtrage.

La chaîne de requête pour cet appel comprendra event_type.

Chaque type d'événement devra être échappé avec \" de chaque côté de la valeur.

1. \"management\" correspond aux événements de gestion
2. \"authentication\" correspond aux événements d'authentification dans la plateforme CI.
3. \"sso\" correspond aux événements SSO.
   etc...

curl -X GET "https://${tenant_url}/v1.0/events?event_type=\"sso\"" -H "Authorization: Bearer ${access_token}"
-H 'Authorization: Bearer {token}'

Vous pouvez enchaîner plusieurs types d'événements, séparés par des virgules. Par exemple : event_type=\"sso\",\"authentication\"

Gestion de la pagination (nombre maximal d'enregistrements)

Si votre réponse à l'appel comprend total_events qui dépasse le nombre total de events dans la réponse, ou "max_size_limit": "true", vous pouvez effectuer un deuxième appel avec un filtre afin de ne pas chevaucher le premier appel.

Par exemple, si le premier appel que nous avons passé était :

GET https://mytenant.ice.ibmcloud.com/v1.0/events avec une réponse de :

{
    "response": {
        "events": {
            "search_after": {
                "total_events": 19540,
                "max_size_limit": "false",
                "time": "1559156150862",
                "id": "def9ea72-30ce-4589-800a-7306e306ea2e"
            },

Nous le savons :

1. La réponse comprend 10 000 enregistrements, et
2. Nous avons atteint la limite de taille maximale, et
3. Le dernier événement de la réponse porte l'heure de 1559156150862 et l'identifiant de def9ea72-30ce-4589-800a-7306e306ea2e.

Par conséquent, notre prochain appel se présentera comme suit :

GET /v1.0/events?after=\"1559156150862\",\"def9ea72-30ce-4589-800a-7306e306ea2e\" qui répond par :

{
    "response": {
        "events": {
            "search_after": {
            "total_events": 19450,
            "max_size_limit": "false",
            "time": "1559227423000",
            "id": "f253f26d-bb00-497b-a508-b3ea0e4f6d6f"
        }
      },

Lorsque la limite de taille maximale est fausse, nous savons qu'il n'est pas nécessaire d'effectuer un appel supplémentaire. Cependant, si vous utilisez également le dimensionnement des pages et que votre taille est inférieure à 10 000, le système indiquera toujours que max_size_limit est faux.

Utilisation de paramètres avec l'API d'événements

L'API "événements" est conçue pour l'établissement de rapports sur les données des clients et ne fait pas partie du flux en temps réel. Le temps de traitement moyen pour l'affichage des événements peut atteindre 3000 ms, mais il n'est pas garanti. Cet article développe les conseils et les orientations concernant certains paramètres de l'API sur les événements :

1. Filtrage du type de plage : range_type - time ou indexed_at - la valeur par défaut est time, obligatoire
2. Utilisation de after_id et after_time - doivent être utilisés ensemble pour obtenir le prochain lot d'événements
3. Obtenir tous les types d'événements : all_events - non par défaut, facultatif
4. Filtrage sur un attribut d'événement à l'aide d'une clé et d'une valeur de filtre - les valeurs par défaut sont : filter_key=data data.performedby_type, filter_value="*", optionnel

Plage

L'API des événements : /v1.0/events l'API "Événements", par défaut, obtient l'événement pour les dernières 24 heures. Vous pouvez spécifier l'intervalle de temps. Parfois, il semble que des événements manquent parce qu'il s'écoule un certain temps entre le moment où une transaction se termine sur l'ISV et le moment où la modification est signalée sur l'API des événements. Vous pouvez utiliser range_type, indexed_at au lieu de temps. Le réglage par défaut est time.

time date de l'événement : date à laquelle l'événement a été généré
indexed_at: date à laquelle l'événement a été traité par le service de transformation.

Obtenir la prochaine série d'événements

La réponse de l'API sur les événements ne dépassera pas 10000 événements. Pour obtenir le prochain lot d'événements, utilisez l'heure et l'identifiant de l'objet search_after dans la réponse de l'appel en cours pour les appels suivants.

after_id: L'identifiant d'un événement précédemment renvoyé, après lequel commencer la recherche. Si l'ordre de tri est croissant, les événements générés ou traités après cet événement sont renvoyés par ordre croissant. Notez que l'ordre de tri par défaut est décroissant. Avec cette valeur par défaut, les événements sont renvoyés par ordre décroissant dans les appels suivants à partir du dernier événement. Si les valeurs "de" et "à" figurent dans la demande initiale, elles doivent être conservées dans les demandes suivantes afin de respecter le calendrier. Pour identifier l'événement après lequel commencer la recherche, after_id est l'identifiant de l'événement après lequel la recherche doit être effectuée et doit être utilisé en conjonction avec after_time.
after_time: L'heure de génération de l'événement (heure) ou l'heure de traitement de l'événement par le service de transformation (indexed_at) d'un événement précédemment renvoyé, après laquelle commencer la recherche. Si l'ordre de tri est croissant, les événements générés ou traités après cet événement sont renvoyés dans un ordre croissant pour les appels suivants. Notez que l'ordre de tri par défaut est décroissant. Si les valeurs from et to sont incluses dans la demande initiale, elles doivent être conservées dans les demandes suivantes afin de maintenir la période correcte Pour identifier l'événement après lequel commencer la recherche, after_time est l'horodatage de génération de l'événement après lequel la recherche doit être effectuée et doit être utilisé en conjonction avec after_id

curl -X GET 'https://TENANT_NAME/v1.0/events/?event_type=\"authentication\"&size=2&range_type=indexed_at' -H 'Authorization: Bearer XXX' -H 'Content-Type: application/json'

curl -X GET 'https://TENANT_NAME/v1.0/events/?event_type=\"authentication\"&size=2&range_type=indexed_at&after_id=d340e983-84e5-4216-8771-3c2d60e9d48c&after_time=1612292310689' -H 'Authorization: Bearer XXX' -H 'Content-Type: application/json'

Tous les événements

L'API des événements prend en charge le filtre all_events pour renvoyer certains types d'événements.
si all_events = no, qui est la valeur par défaut. L'API des événements ne renvoie que les événements de gestion, de sso et d'authentification.
si all_events = yes. L'API des événements renvoie tous les types d'événements : Actuellement, tous les types d'événements qui peuvent être inclus sont : gestion, sso, authentification, service, accomplissement, adaptive_risk, cert_campaign, access_request, account_sync, token ou privacy_consent.

Exemple avec all_event=no

curl -X GET --header 'Accept: application/json' 'https://<tenantname>/v1.0/events?all_events=no&range_type=indexed_at' -H 'Authorization: Bearer <token>'

Exemple avec all_event=yes

curl -X GET --header 'Accept: application/json' 'https://<tenantname>/v1.0/events?all_events=yes&range_type=indexed_at' -H 'Authorization: Bearer <token>'

Filtrage sur un attribut d'événement

Pour filtrer sur un attribut d'événement spécifique, nous utiliserons filter_key et filter_value. La valeur par défaut de la clé de filtrage est data.performedby_type et filter_value="*" ; elle ne s'applique qu'aux événements dotés de cet attribut. Vous pouvez utiliser n'importe quel attribut de l'événement pour le filtrer. Notez que la taille limite de l'attribut d'événement est de 32kb

Voici un exemple de réponse à un événement :

{
    "response": {
        "events": {
            "search_after": {
                "total_events": 54,
                "max_size_limit": "false",
                "time": "1559156150862",
                "id": "def9ea72-30ce-4589-800a-7306e306ea2e"
            },
            "events": [
                {
                    "geoip": {
                        "continent_name": "North America",
                        "country_iso_code": "US",
                        "country_name": "United States",
                        "location": {
                            "lon": "-97.822",
                            "lat": "37.751"
                        }
                    },
                    {...},
                    {...},
                    {...}
                }...

Supposons que nous voulions filtrer les événements en provenance de l'Inde. Pour obtenir le résultat souhaité, nous devons mettre
filter_key = geoip.country_name et filter_value = \"India\"

curl -X GET --header 'Accept: application/json' 'https://<tenantname>/v1.0/events?all_events=no&filter_key=geoip.country_name&filter_value=%5C%22India%5C%22&range_type=time&x-forwarded-host=<tenant_id>'

Supposons que nous voulions filtrer les événements liés à un nom d'utilisateur particulier [email protected]. Pour obtenir le résultat, il faut mettre
filter_key = data.username et filter_value = \"[email protected]\"

curl -X GET --header 'Accept: application/json' 'https://<tenantname>/v1.0/events?all_events=no&filter_key=data.username&filter_value=%5C%22abc123%40ibm.com%5C%22&range_type=time&x-forwarded-host=<tenant_id>'