Nous avons réorganisé la structure de navigation de notre documentation pour l'aligner directement sur vos workflows opérationnels. Pour en savoir plus, consultez les notes de version et la vidéo de présentation.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Gérer les exclusions de règles

Compatible avec :

Google secops SIEM

Ce document explique comment gérer par programmation les exclusions de règles dans Google Security Operations à l'aide de l'API. Les exclusions servent de filtres que vous définissez en fonction des champs du modèle de données unifié (UDM) pour empêcher des détections spécifiques de générer des alertes. En identifiant les activités connues ou sécurisées, ces filtres éliminent le bruit inutile dans votre tableau de bord.

Créer une exclusion avec des filtres de résultat

Vous pouvez créer une règle d'exclusion par programmation pour supprimer des résultats de détection spécifiques qui correspondent aux critères que vous avez définis, ce qui réduit le bruit et permet de hiérarchiser les alertes de haute fidélité.

Utilisez le point de terminaison POST pour définir la logique de suppression. Tous les filtres du tableau outcomeFilters sont liés par une clause AND implicite.

Méthode : POST

Point de terminaison :

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID

Remplacez les éléments suivants :

REGION : Google Cloud région de l'instance Google SecOps

PROJECT_ID : ID de votre Google Cloud projet

LOCATION : emplacement de l'instance Google SecOps (souvent identique à la région)

INSTANCE_ID : ID de l'instance Google SecOps

Exemple :

POST https://us-chronicle.googleapis.com/v1/projects/my-project/locations/us/instances/my-instance/findingsRefinements

Corps de la requête :

  {
  "displayName": "Exclusion with outcome filters",
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.01",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ]
}

L'exemple montre comment définir une logique de suppression dans laquelle plusieurs filtres du tableau outcomeFilters sont liés par une clause AND implicite.

Champs obligatoires : displayName, type, query

Champs générés par le système : ne spécifiez pas name, createTime ni updateTime. Ils sont gérés par le système et sont ignorés ou provoquent des erreurs s'ils sont inclus dans la requête.

La logique de suppression suit une relation AND. La requête crée une exclusion qui supprime toutes les détections comportant un événement avec les éléments suivants :

"altostrat.com" comme nom d'hôte principal
Une variable de résultat ip avec la valeur 127.0.0.1
Une variable de résultat hostnames dont au moins une des valeurs agrégées est altostrat.com.

Tous les filtres spécifiés dans l'exclusion sont implicitement liés par une clause AND.

Réponse de l'API : l'API renvoie le nom de la ressource FindingsRefinement.

La ressource FindingsRefinement contient la logique de suppression de base (la requête et les filtres de résultat). Le nom de la ressource (ID) est utilisé pour les opérations ultérieures sur l'exclusion.

Accéder à une exclusion

Utilisez le point de terminaison GET pour effectuer les opérations suivantes :

Obtenir les détails d'une seule définition d'exclusion par son ID unique.
Lorsque vous disposez d'un refinement-id spécifique et que vous devez vérifier la requête exacte ou les filtres de résultat qu'il contient.

Méthode : GET

Point de terminaison :

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

Remplacez les éléments suivants :

REGION : Google Cloud région de l'instance Google SecOps

PROJECT_ID : ID de votre Google Cloud projet

LOCATION : emplacement de l'instance Google SecOps (souvent identique à la région)

INSTANCE_ID : ID de l'instance Google SecOps

Exemple :

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777

Appliquer une exclusion à une règle ou à un ensemble de règles

Vous devez appliquer l'exclusion à des règles spécifiques ou à des ensembles de règles organisés. Lorsque vous appliquez l'exclusion à une règle ou à un ensemble de règles, une ressource FindingsRefinementDeployment est créée. Vous pouvez utiliser cette ressource pour déterminer les règles personnalisées, les règles organisées ou les ensembles de règles organisés qui s'appliquent à la ressource FindingsRefinement. Vous pouvez ensuite spécifier le paramètre update_mask dans la requête API pour indiquer les champs de FindingsRefinementDeployment à mettre à jour.

Méthode : PATCH

Point de terminaison :

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

Remplacez les éléments suivants :

REGION : Google Cloud région de l'instance Google SecOps

PROJECT_ID : ID de votre Google Cloud projet

LOCATION : emplacement de l'instance Google SecOps (souvent identique à la région)

INSTANCE_ID : ID de l'instance Google SecOps

REFINEMENT_ID : ID unique de l'affinage des résultats

Exemple :

 PATCH https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777?update_mask=enabled,detectionExclusionApplication

Corps de la requête :


  {
  "name": "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777"
  "enabled": true,
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...list curated rule set resource names
    ],
    "curatedRules": [
      ...list curated rule resource names
    ],
    "rules": [
      ...list rule resource names
    ],
  }
}

Lorsque vous appliquez l'exclusion à une règle ou à un ensemble de règles, le système crée une ressource FindingsRefinementDeployment. Cette ressource détermine les règles personnalisées, les règles organisées et les ensembles de règles organisés qui s'appliquent à la ressource FindingsRefinement. Vous pouvez également inclure le paramètre update_mask dans la requête API pour spécifier les champs de FindingsRefinementDeployment à mettre à jour.

Accéder au déploiement de l'exclusion

Une fois que vous avez créé ou mis à jour une exclusion, utilisez ce point de terminaison pour vérifier les règles ou les ensembles de règles auxquels cette exclusion spécifique est déployée.

Méthode : GET

Point de terminaison :

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

Remplacez les éléments suivants :

REGION : Google Cloud région de l'instance Google SecOps

PROJECT_ID : ID de votre Google Cloud projet

LOCATION : emplacement de l'instance Google SecOps (souvent identique à la région)

INSTANCE_ID : ID de l'instance Google SecOps

REFINEMENT_ID : ID unique de l'affinage des résultats

Exemple :

   GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment

Répertorier toutes les exclusions

Utilisez ce point de terminaison pour récupérer la liste des ressources findingsRefinements.

Méthode : GET

Point de terminaison :

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

Remplacez les éléments suivants :

REGION : Google Cloud région de l'instance Google SecOps

PROJECT_ID : ID de votre Google Cloud projet

LOCATION : emplacement de l'instance Google SecOps (souvent identique à la région)

INSTANCE_ID : ID de l'instance Google SecOps

Exemple :

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements

Paramètres de requête facultatifs : pageSize, pageToken

Vous pouvez utiliser les paramètres facultatifs pour afficher plus de résultats, comme pour les autres points de terminaison de liste de l'API.

Répertorier tous les déploiements d'exclusion

Utilisez ce point de terminaison pour obtenir la liste des ressources FindingsRefinement créées dans votre instance.

Méthode : GET

Point de terminaison :

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

Remplacez les éléments suivants :

REGION : Google Cloud région de l'instance Google SecOps

PROJECT_ID : ID de votre Google Cloud projet

LOCATION : emplacement de l'instance Google SecOps (souvent identique à la région)

INSTANCE_ID : ID de l'instance Google SecOps

Exemple :

  GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:listAllFindingsRefinementDeployments

Paramètres de requête facultatifs :

Utilisez les paramètres pageSize et pageToken pour afficher plus de résultats, comme pour les autres points de terminaison de liste de l'API.
Utilisez le paramètre filter pour filtrer les règles ou les ensembles de règles auxquels des exclusions sont appliquées.

Tester une exclusion à l'aide de l'API

Ce point de terminaison teste l'exclusion par rapport aux détections des règles et des ensembles de règles spécifiés, puis valide l'efficacité de l'exclusion pour supprimer les détections indésirables. L'interface utilisateur utilise les détections des 30 derniers jours pour les tests.

Méthode : POST

Point de terminaison :

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:testFindingsRefinement

Remplacez les éléments suivants :

REGION : Google Cloud région de l'instance Google SecOps

PROJECT_ID : ID de votre Google Cloud projet

LOCATION : emplacement de l'instance Google SecOps (souvent identique à la région)

INSTANCE_ID : ID de l'instance Google SecOps

Exemple :

POST https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:testFindingsRefinement

Corps de la requête :

 {
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.01",
      "outcome_filter_operator": "EQUAL",
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS",
    },
  ]
  "interval": {
    "start_time": {
      "seconds": 1756684800, // Sep. 1 2025 00:00 UTC
    },
    "end_time": {
      "seconds": 1759276800, // Oct. 1 2025 00:00 UTC
    },
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...curated rule set resource names
    ],
    "curatedRules": [
      ...curated rule resource names
    ],
    "rules": [
      ...rule resource names
    ],
  }
}

Ce point de terminaison teste l'exclusion sur les détections générées dans les règles et les ensembles de règles spécifiés dans la requête. Il permet de déterminer l'efficacité de l'exclusion pour supprimer les détections qui ne devraient pas être générées. Le système utilise les détections des 30 derniers jours comme plage de dates pour tester les exclusions.

Limites

Toutes les exclusions (avec ou sans filtres de résultat) doivent spécifier un champ query. Pour créer une exclusion avec uniquement outcomeFilters, spécifiez une expression régulière match-all.
```
  ...other fields in FindingsRefinement

  query: "principal.hostname = /.*/"

  outcomeFilters: [ your outcome filters ]
```
L'expression régulière correspond à n'importe quel nom d'hôte. Par conséquent, cette requête correspond à toutes les détections. Par conséquent, le filtrage effectif est déterminé uniquement par les filtres de résultat.
Les exclusions ne sont pas compatibles avec une configuration de valeur TTL (Time To Live). Toutefois, vous pouvez créer une valeur TTL unique en calculant le délai d'expiration spécifique et en ajoutant une condition d'horodatage dans la définition de l'exclusion. Par exemple, pour définir une exclusion qui expire à la fin de l'année, spécifiez la requête comme suit :
```
  ...other fields in FindingsRefinement

  query: "metadata.event_timestamp.seconds < 1767225600" // Jan 1 2026 00:00 UTC

  outcomeFilters: [your outcome filters]
```
Cet exemple confirme que seules les détections créées par des événements dont l'horodatage est antérieur à la fin de l'année sont supprimées.

Remarque : Il est possible que cela ne s'affiche pas correctement dans la fenêtre Edit Exclusions (Modifier les exclusions) de l'interface utilisateur, car elle n'est compatible qu'avec les champs string.
Règles composites : les exclusions de champs UDM sont évaluées par rapport aux événements bruts. Si vous tentez d'exclure des valeurs UDM spécifiques d'une règle composite (qui se déclenche en fonction d'autres détections plutôt que d'événements bruts), vous devez appliquer l'exclusion aux règles sous-jacentes fondamentales qui alimentent la règle composite.

Pour trouver la règle fondamentale, vous pouvez inspecter la définition de la règle composite dans la console Google SecOps (sous Content Hub > Curated Detections) et examiner la section events: de la logique YARA-L pour identifier les noms des règles fondamentales.

Vous avez encore besoin d'aide ? Obtenez des réponses auprès des membres de la communauté et des professionnels Google SecOps.