Gérer l'exclusion de règles à l'aide de l'API

Compatible avec :

Ce document explique comment gérer les exclusions de règles de manière programmatique 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 la génération d'alertes pour des détections spécifiques. En identifiant les activités connues ou sûres, 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 de manière programmatique pour supprimer des résultats de détection spécifiques qui correspondent à vos critères définis. Vous réduisez ainsi le bruit et hiérarchisez les alertes de haute fidélité.

Utilisez le point de terminaison POST pour définir la logique de suppression. Tous les filtres avec le 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 : région de l'instance Google SecOps. Google Cloud

PROJECT_ID : ID de votre projet Google Cloud .

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 où 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. Elles sont gérées par le système et sont ignorées ou provoquent des erreurs si elles sont incluses 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 une valeur de 127.0.0.1

  • Une variable de résultat hostnames dont au moins l'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 ressource FindingsRefinement.

La ressource FindingsRefinement contient la logique de suppression principale (filtres de requête et de résultat). Le nom (ID) de la ressource 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 :

  • Obtenez les détails d'une seule définition d'exclusion grâce à son ID unique.

  • Lorsque vous avez un refinement-id spécifique et que vous devez vérifier les filtres de requête ou de résultat exacts 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 : région de l'instance Google SecOps. Google Cloud

PROJECT_ID : ID de votre projet Google Cloud .

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 sélectionné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 sélectionnées ou les ensembles de règles sélectionnées 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 : région de l'instance Google SecOps. Google Cloud

PROJECT_ID : ID de votre projet Google Cloud .

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 sélectionnées et les ensembles de règles sélectionnées 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 pour l'exclusion

Après avoir créé ou mis à jour une exclusion, utilisez ce point de terminaison pour vérifier les règles ou 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 : région de l'instance Google SecOps. Google Cloud

PROJECT_ID : ID de votre projet Google Cloud .

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

Lister 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 : région de l'instance Google SecOps. Google Cloud

PROJECT_ID : ID de votre projet Google Cloud .

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 lister plus de résultats, comme pour les autres points de terminaison de liste de l'API.

Lister 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 : région de l'instance Google SecOps. Google Cloud

PROJECT_ID : ID de votre projet Google Cloud .

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 lister plus de résultats similaires à d'autres points de terminaison de liste dans l'API.

  • Utilisez le paramètre filter pour filtrer les règles ou les ensembles de règles auxquels des exclusions ont été 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 ensembles de règles spécifiés, puis valide l'efficacité de l'exclusion pour supprimer les détections indésirables. L'UI 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 : région de l'instance Google SecOps. Google Cloud

PROJECT_ID : ID de votre projet Google Cloud .

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 efficace est déterminé uniquement par les filtres de résultats.

  • Les exclusions ne sont pas compatibles avec la configuration d'une valeur TTL (Time To Live). Toutefois, vous pouvez créer un TTL unique en calculant le délai d'expiration spécifique et en ajoutant une condition de code temporel 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 le code temporel 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 Modifier les exclusions de l'interface utilisateur, car elle n'accepte que les champs string.

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