Répertorier des résultats de sécurité à l'aide de l'API Security Command Center

Niveaux de service Standard (ancienne version), Standard, Premium et Enterprise (obsolète)

Le niveau de service Security Command Center Enterprise sera arrêté le 21 mai 2027.

Si votre organisation utilise le niveau de service Enterprise, elle passera automatiquement au niveau de service Premium le 21 mai 2027 ou après. Contactez votre responsable de compte ou un spécialiste des ventesGoogle Cloud si vous avez des questions.

Les résultats Security Command Center modélisent les risques de sécurité potentiels qui s'appliquent aux éléments d'un projet ou d'une organisation. Un résultat correspond toujours à un élément spécifique dans Security Command Center.

Ce guide explique comment accéder aux résultats à l'aide des bibliothèques clientes de Security Command Center. Chaque résultat appartient à une source. La plupart des détecteurs ou des fournisseurs de résultats produisent des résultats dans la même source.

Les rôles IAM pour Security Command Center peuvent être accordés au niveau de l'organisation, du dossier ou du projet. Votre capacité à afficher, modifier, créer ou mettre à jour les résultats, les éléments et les sources de sécurité dépend du niveau pour lequel vous disposez d'un accès. Pour en savoir plus sur les rôles Security Command Center, consultez la page Contrôle des accès.

Avant de commencer

Avant de configurer une source, vous devez effectuer les opérations suivantes :

• S'authentifier auprès de l'API Security Command Center

Format de page

Toutes les API de liste Security Command Center sont paginées. Chaque réponse renvoie une page de résultats et un jeton pour renvoyer la page suivante. La taille de la page est configurable. La taille de page par défaut est de 10. Vous pouvez définir une valeur minimale de 1 et une valeur maximale de 1 000.

Conservation des résultats

Selon votre niveau Security Command Center, les résultats restent disponibles pour que vous puissiez les lister ou les interroger pendant des périodes spécifiques. Pour en savoir plus sur la conservation des données Security Command Center, consultez Conservation des données.

Lister tous les résultats

gcloud

Pour lister tous les résultats d'un projet, d'un dossier ou d'une organisation, exécutez la commande suivante :

gcloud scc findings list PARENT_TYPE/PARENT_ID \
  --location=LOCATION

Remplacez les éléments suivants :

• PARENT_TYPE : niveau de la hiérarchie des ressources pour lequel lister les résultats. Utilisez organizations, folders ou projects.
• PARENT_ID : ID numérique de l'organisation, du dossier ou du projet, ou ID alphanumérique du projet.
• LOCATION : emplacement Security Command Center dans lequel lister les résultats. Si la résidence des données est activée, utilisez eu, sa ou us. Sinon, utilisez la valeur global.

Pour plus d'exemples, exécutez la commande suivante :

gcloud scc findings list --help

Pour obtenir des exemples dans la documentation, consultez gcloud scc findings list.

Go

import (
	"context"
	"fmt"
	"io"

	securitycenter "cloud.google.com/go/securitycenter/apiv2"
	"cloud.google.com/go/securitycenter/apiv2/securitycenterpb"
	"google.golang.org/api/iterator"
)

// listFindings prints all findings in orgID to w. orgID is the numeric
// identifier of the organization.
func listFindings(w io.Writer, orgID string) error {
	// orgID := "12321311"
	// Instantiate a context and a security service client to make API calls.
	ctx := context.Background()
	client, err := securitycenter.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("securitycenter.NewClient: %w", err)
	}
	defer client.Close() // Closing the client safely cleans up background resources.

	req := &securitycenterpb.ListFindingsRequest{
		// List findings across all sources.
		// Parent must be in one of the following formats:
		//		"organizations/{orgId}/sources/-/locations/global"
		//		"projects/{projectId}/sources/-/locations/global"
		//		"folders/{folderId}/sources/-/locations/global"
		Parent: fmt.Sprintf("organizations/%s/sources/-/locations/global", orgID),
	}
	it := client.ListFindings(ctx, req)
	for {
		result, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("it.Next: %w", err)
		}
		finding := result.Finding
		fmt.Fprintf(w, "Finding Name: %s, ", finding.Name)
		fmt.Fprintf(w, "Resource Name %s, ", finding.ResourceName)
		fmt.Fprintf(w, "Category: %s\n", finding.Category)
	}
	return nil
}

Java

import com.google.cloud.securitycenter.v2.ListFindingsRequest;
import com.google.cloud.securitycenter.v2.ListFindingsResponse.ListFindingsResult;
import com.google.cloud.securitycenter.v2.SecurityCenterClient;
import java.io.IOException;

public class ListAllFindings {

  public static void main(String[] args) throws IOException {
    // organizationId: The source to list all findings for.
    // You can also use project/ folder as the parent resource.
    String organizationId = "google-cloud-organization-id";

    // Specify the location to list the findings.
    String location = "global";

    // The source id to scope the findings.
    String sourceId = "source-id";

    listAllFindings(organizationId, sourceId, location);
  }

  // List all findings under a given parent resource.
  public static void listAllFindings(String organizationId, String sourceId, String location)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (SecurityCenterClient client = SecurityCenterClient.create()) {
      ListFindingsRequest request =
          ListFindingsRequest.newBuilder()
              // To list findings across all sources, use "-".
              .setParent(
                  String.format("organizations/%s/sources/%s/locations/%s", organizationId,
                      sourceId,
                      location))
              .build();

      for (ListFindingsResult result : client.listFindings(request).iterateAll()) {
        System.out.printf("Finding: %s", result.getFinding().getName());
      }
      System.out.println("\nListing complete.");
    }
  }
}

Node.js

// Imports the Google Cloud client library.
const {SecurityCenterClient} = require('@google-cloud/security-center').v2;

// Creates a new client.
const client = new SecurityCenterClient();

// TODO(developer): Update the following for your own environment.
const organizationId = '1081635000895';
const location = 'global';

// Required. Name of the source the findings belong to. If no location is
// specified, the default is global. The following list shows some examples:
// - `organizations/[organization_id]/sources/[source_id]/locations/[location_id]`
// - `folders/[folder_id]/sources/[source_id]`
// - `folders/[folder_id]/sources/[source_id]/locations/[location_id]`
// - `projects/[project_id]/sources/[source_id]`
// - `projects/[project_id]/sources/[source_id]/locations/[location_id]`
// To groupBy across all sources provide a source_id of `-`.
const parent = `organizations/${organizationId}/sources/-/locations/${location}`;

// Build the list findings request.
const listFindingsRequest = {
  parent,
};

async function listAllFindings() {
  // Call the API.
  const iterable = client.listFindingsAsync(listFindingsRequest);
  let count = 0;

  for await (const response of iterable) {
    // Just print a few for demonstration.
    if (count > 5) break;
    console.log(
      `${++count} ${response.finding.name} ${response.finding.resourceName}`
    );
  }
}

await listAllFindings();

Python

def list_all_findings(organization_id, source_name, location_id) -> int:
    """
    lists all findings for a source
    Args:
       organization_id: organization_id is the numeric ID of the organization. e.g.:organization_id = "111122222444"
       source_name: is the resource path for a source that has been created
       location_id: GCP location id; example: 'global'
    Returns:
        int: returns the count of all findings for a source
    """
    from google.cloud import securitycenter_v2

    # Create a client.
    client = securitycenter_v2.SecurityCenterClient()
    parent = f"organizations/{organization_id}"
    all_sources = f"{parent}/sources/{source_name}/locations/{location_id}"

    # Create the request dictionary
    request = {"parent": all_sources}

    # Print the request for debugging
    print("Request: ", request)

    finding_result_iterator = client.list_findings(request={"parent": all_sources})
    for count, finding_result in enumerate(finding_result_iterator):
        print(
            "{}: name: {} resource: {}".format(
                count, finding_result.finding.name, finding_result.finding.resource_name
            )
        )
    return finding_result_iterator

Le résultat de chaque élément se présente comme suit. Pour obtenir la liste complète des champs, consultez ListFindingsResult.

{
  "finding": {
    "name": "organizations/ORGANIZATION_ID/sources/SOURCE_ID/findings/FINDING_ID",
    "parentDisplayName": "SOURCE_DISPLAY_NAME",
    "resourceName": "//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER",
    "state": "ACTIVE",
    "category": "Malware: Cryptomining Bad Domain",
    "eventTime": "2021-11-10T17:41:41.594Z",
    "createTime": "2021-11-10T17:41:42.014Z",
    "severity": "LOW",
    "canonicalName": "projects/PROJECT_NUMBER/sources/SOURCE_ID/findings/FINDING_ID",
    "mute": "UNDEFINED",
    "findingClass": "THREAT",
    "indicator": {
      "domains": ["DOMAIN"]
    }
  },
  "resource": {
    "name": "//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER",
    "gcpMetadata": {
      "projectDisplayName": "PROJECT_ID"
    }
  }
}

Filtrer les résultats

Un projet, un dossier ou une organisation peuvent contenir de nombreux résultats. L'exemple ci-dessus n'utilise pas de filtre. Par conséquent, tous les enregistrements de résultats sont renvoyés.

Pour vous aider à obtenir des informations uniquement sur les champs qui vous intéressent, vous pouvez utiliser les filtres de recherche. Ces filtres sont semblables à des clauses "where" dans les instructions SQL, à ceci près qu'à la place des colonnes, elles s'appliquent aux objets renvoyés par l'API.

L'exemple suivant ne répertorie que les résultats possédant une catégorie "MEDIUM_RISK_ONE". Différents fournisseurs de résultats (également appelés sources de sécurité) utilisent différents ensembles de catégories. Pour déterminer les catégories que vous pouvez utiliser dans votre filtre, consultez la documentation du fournisseur de résultats.

gcloud

Utilisez la commande suivante pour filtrer les résultats :

gcloud scc findings list PARENT_TYPE/PARENT_ID \
  --location=LOCATION \
  --source=SOURCE_ID \
  --filter="FILTER"

Remplacez les éléments suivants :

• PARENT_TYPE : niveau de la hiérarchie des ressources pour lequel lister les résultats. Utilisez organizations, folders ou projects.
• PARENT_ID : ID numérique de l'organisation, du dossier ou du projet, ou ID alphanumérique du projet.
• LOCATION : emplacement Security Command Center dans lequel lister les résultats avec un filtre. Si la résidence des données est activée, utilisez eu, sa ou us. Sinon, utilisez la valeur global.
• SOURCE_ID : ID de la source de sécurité qui fournit le type de résultat.
• FILTER : filtre à utiliser. Par exemple, le filtre suivant ne renvoie que les résultats de la catégorie MEDIUM_RISK_ONE :

  --filter="category=\"MEDIUM_RISK_ONE\""

Pour plus d'exemples, exécutez la commande suivante :

gcloud scc findings list --help

Pour obtenir des exemples dans la documentation, consultez gcloud scc findings list.

Go

import (
	"context"
	"fmt"
	"io"

	securitycenter "cloud.google.com/go/securitycenter/apiv2"
	"cloud.google.com/go/securitycenter/apiv2/securitycenterpb"
	"google.golang.org/api/iterator"
)

// listFilteredFindings prints findings with category 'MEDIUM_RISK_ONE' for a
// specific source to w. sourceName is the full resource name of the source
// to search for findings under.
func listFilteredFindings(w io.Writer, sourceName string) error {
	// Specific source:
	// 		sourceName := "{parent}/sources/{sourceId}"
	// All sources:
	// 		sourceName := "{parent}/sources/-"
	// where,
	// Parent must be in one of the following formats:
	//		"organizations/{orgId}"
	//		"projects/{projectId}"
	//		"folders/{folderId}"
	// Instantiate a context and a security service client to make API calls.
	ctx := context.Background()
	client, err := securitycenter.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("securitycenter.NewClient: %w", err)
	}
	defer client.Close() // Closing the client safely cleans up background resources.

	req := &securitycenterpb.ListFindingsRequest{
		Parent: sourceName,
		Filter: `category="MEDIUM_RISK_ONE"`,
	}
	it := client.ListFindings(ctx, req)
	for {
		result, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("it.Next: %w", err)
		}
		finding := result.Finding
		fmt.Fprintf(w, "Finding Name: %s, ", finding.Name)
		fmt.Fprintf(w, "Resource Name %s, ", finding.ResourceName)
		fmt.Fprintf(w, "Category: %s\n", finding.Category)
	}
	return nil
}

Java

import com.google.cloud.securitycenter.v2.ListFindingsRequest;
import com.google.cloud.securitycenter.v2.ListFindingsResponse.ListFindingsResult;
import com.google.cloud.securitycenter.v2.SecurityCenterClient;
import java.io.IOException;

public class ListFindingsWithFilter {

  public static void main(String[] args) throws IOException {
    // TODO: Replace the variables within {}
    // organizationId: Google Cloud Organization id.
    // You can also use project/ folder as the parent resource.
    String organizationId = "google-cloud-organization-id";

    // Specify the location to list the findings.
    String location = "global";

    // The source id to scope the findings.
    String sourceId = "source-id";

    listFilteredFindings(organizationId, sourceId, location);
  }

  // List filtered findings under a source.
  public static void listFilteredFindings(String organizationId, String sourceId, String location)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (SecurityCenterClient client = SecurityCenterClient.create()) {

      // Use any one of the following formats:
      //  * organizations/{organization_id}/sources/{source_id}/locations/{location}
      //  * folders/{folder_id}/sources/{source_id}/locations/{location}
      //  * projects/{project_id}/sources/{source_id}/locations/{location}
      String parent = String.format("organizations/%s/sources/%s/locations/%s", organizationId,
          sourceId,
          location);

      // Listing all findings of category "MEDIUM_RISK_ONE".
      String filter = "category=\"MEDIUM_RISK_ONE\"";

      ListFindingsRequest request =
          ListFindingsRequest.newBuilder()
              .setParent(parent)
              .setFilter(filter)
              .build();

      for (ListFindingsResult result : client.listFindings(request).iterateAll()) {
        System.out.printf("Finding: %s", result.getFinding().getName());
      }
      System.out.println("\nListing complete.");
    }
  }
}

Node.js

// Imports the Google Cloud client library.
const {SecurityCenterClient} = require('@google-cloud/security-center').v2;

// Creates a new client.
const client = new SecurityCenterClient();

// TODO(developer): Update the following for your own environment.
const organizationId = '1081635000895';
const location = 'global';

// Required. Name of the source to groupBy. If no location is specified,
// finding is assumed to be in global.
//  The following list shows some examples:
// - `organizations/[organization_id]/sources/[source_id]`
// - `organizations/[organization_id]/sources/[source_id]/locations/[location_id]`
// - `folders/[folder_id]/sources/[source_id]`
// - `folders/[folder_id]/sources/[source_id]/locations/[location_id]`
// - `projects/[project_id]/sources/[source_id]`
// - `projects/[project_id]/sources/[source_id]/locations/[location_id]`
// To groupBy across all sources provide a source_id of `-`.
const parent = `organizations/${organizationId}/sources/-/locations/${location}`;

// Listing all findings of category "MEDIUM_RISK_ONE".
const filter = 'category="MEDIUM_RISK_ONE"';

// Build the list findings with filter request.
const listFilteredFindingsRequest = {
  parent,
  filter,
};

async function listFilteredFindings() {
  // Call the API.
  const iterable = client.listFindingsAsync(listFilteredFindingsRequest);
  let count = 0;
  console.log('Findings:');
  for await (const response of iterable) {
    // Just print a few for demonstration.
    if (count > 5) break;
    console.log(
      `${++count} ${response.finding.name} ${response.finding.resourceName}`
    );
  }
}
await listFilteredFindings();

Python

def list_filtered_findings(organization_id, source_name, location_id) -> int:
    """
    lists filtered findings for a source
    Args:
        organization_id: organization_id is the numeric ID of the organization. e.g.:organization_id = "111122222444"
        source_name: is the resource path for a source that has been created
        location_id: GCP location id; example: 'global'
    Returns:
         int: returns the filtered findings for a source
    """
    count = 0
    from google.cloud import securitycenter_v2

    # Create a new client.
    client = securitycenter_v2.SecurityCenterClient()
    parent = f"organizations/{organization_id}"
    all_sources = f"{parent}/sources/{source_name}/locations/{location_id}"
    finding_result_iterator = client.list_findings(
        request={"parent": all_sources, "filter": 'severity="LOW"'}
    )
    # Iterate an print all finding names and the resource they are
    # in reference to.
    for count, finding_result in enumerate(finding_result_iterator):
        print(
            "{}: name: {} resource: {}".format(
                count, finding_result.finding.name, finding_result.finding.resource_name
            )
        )
    return count

Security Command Center est également compatible avec les tableaux et objets JSON entiers en tant que types de propriétés potentiels. Vous pouvez appliquer les filtres suivants :

• Éléments de tableau
• Objets JSON entiers avec correspondance de chaîne partielle dans l'objet
• Sous-champs d'objets JSON

Opérateurs compatibles

Les instructions de requête pour les résultats Security Command Center sont compatibles avec les opérateurs pris en charge par la plupart des API Google Cloud .

La liste suivante montre l'utilisation de différents opérateurs :

• state="ACTIVE" AND NOT mute="MUTED"
• create_time>"2023-08-15T19:05:32.428Z"
• resource.parent_name:"prod"
• severity="CRITICAL" OR severity="HIGH"

La liste suivante présente tous les opérateurs et fonctions compatibles avec les instructions de requête pour les résultats :

• Pour les chaînes :

  • = pour une correspondance exacte

    Par exemple, resource.parent_name="prod" correspond à la valeur prod. Il ne correspond pas à production ni à canaryprod.

  • : pour une correspondance partielle

    Par exemple, resource.parent_name:"prod" correspond aux valeurs prod, production et canaryprod.

• Pour les nombres (sauf int64) :

  • <, >, <=, >= pour les inégalités
  • =, != pour l'égalité

• Pour les nombres (int 64) :

  • =, != pour l'égalité

• Pour les valeurs booléennes :

  • = pour l'égalité

• Pour les relations logiques :

  • AND
  • OR
  • NOT ou -

• Pour regrouper des expressions :

  • (, ) (parenthèses)

• Pour les tableaux :
  • contains(), une fonction permettant d'interroger les résultats avec un champ de tableau contenant au moins un élément correspondant au filtre spécifié
  • containsOnly(), une fonction permettant d'interroger les résultats avec un champ de tableau qui ne contient que des éléments correspondant au filtre spécifié
• Pour les adresses IP :
  • inIpRange(), une fonction permettant d'interroger les adresses IP dans une plage CIDR spécifiée

Filtrer les adresses IP

Certaines propriétés des résultats incluent des adresses IP. Vous pouvez filtrer les résultats en fonction d'adresses IP spécifiques ou d'une plage d'adresses IP.

Les adresses IP s'affichent sous forme de chaînes dans divers résultats et propriétés de résultats, y compris les suivants :

• access.caller_ip
• connections.destinationIp
• connections.sourceIp
• indicator.ip_addresses

Pour filtrer sur une adresse IP spécifique, vous pouvez utiliser l'opérateur d'égalité, comme illustré dans l'exemple suivant :

access.caller_ip="192.0.2.0"

Pour filtrer les résultats en fonction d'une plage d'adresses IP, utilisez la fonction inIpRange. La fonction inIpRange vous permet de filtrer les résultats pour n'afficher que ceux qui contiennent une adresse IP dans une plage CIDR spécifiée. En utilisant l'opération NOT avec inIpRange, vous pouvez filtrer les résultats pour n'afficher que ceux qui contiennent une adresse IP en dehors de la plage CIDR spécifiée.

L'exemple suivant montre la syntaxe de la fonction inIpRange :

inIpRange(IP_FINDING_FIELD, "CIDR_RANGE")

Si l'adresse IP se trouve dans un élément de tableau d'un champ de résultat contenant un tableau, utilisez la syntaxe suivante avec la fonction contains et la fonction inIpRange :

contains(ATTRIBUTE_WITH_ARRAY, inIpRange(IP_FINDING_FIELD, "CIDR_RANGE"))

Dans l'exemple suivant, la fonction inIpRange évalue chaque élément destination_ip du tableau contenu dans le champ de résultat connections pour une adresse IP qui se trouve dans la plage CIDR définie par 192.0.2.0/24 :

contains(connections, inIpRange(destination_ip, "192.0.2.0/24"))

L'exemple suivant montre une commande gcloud CLI qui utilise la fonction inIpRange pour filtrer les résultats dont l'adresse IP dans le champ connections.source_ip se trouve dans une plage, mais pas dans une autre. Le champ connections est un champ de type tableau. La fonction contains est donc utilisée :

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="contains(connections, inIpRange(source_ip, \"2001:db8::/32\")) \
      AND NOT contains(connections, inIpRange(source_ip, \"192.0.2.0/24\"))"

Exemple d'objet JSON

Dans les exemples décrits ultérieurement sur cette page, nous partons du principe que l'objet JSON suivant est un attribut de résultat :

{
  "outer_object": {
    "middle_object": {
      "deeply_nested_object": {
        "x": 123
      },
      "y": "some-string-value"
    },
    "list_middle_object": [
      {
        "v": 321,
        "w": [
          {
            "a": 3,
            "b": 4
          }
        ]
      }
    ],
    "z": "some-other-string-value",
    "u": [
      "list-element-1",
      "list-element-2",
      "list-element-3"
    ]
  }
}

Exemple de filtrage de résultats

Supposons que l'exemple JSON précédent est un attribut de résultat nommé my_property. L'exemple suivant inclut des requêtes de résultats contenant l'objet en tant que propriété. Vous pouvez également associer ces filtres à d'autres filtres en utilisant AND et OR dans votre requête. Par exemple, la première requête utilise le filtre ACTIVE pour afficher les résultats actifs.

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="state=\"ACTIVE\""
    --filter="my_property.outer_object.middle_object.deeply_nested_object.x = 123"

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="my_property.outer_object.middle_object.y = \"some-string-value\""

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="my_property.outer_object.middle_object.y : \"string-value\""

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="my_property.outer_object.z = \"some-other-string-value\""

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="my_property.outer_object.z : \"other-string-value\""

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="my_property.outer_object.u : \"list-element-1\""

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="my_property.outer_object.u : \"list-element-2\""

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="my_property.outer_object.u : \"list-element-3\""

Remarque  : Si vous souhaitez utiliser ces filtres dans la console Google Cloud , n'incluez pas les caractères d'échappement. Par exemple, au lieu de \"string-value\", utilisez "string-value".

Sous-filtres pour les champs de type tableau

Lorsque vous appelez ListFindings, vous pouvez utiliser une correspondance de sous-chaîne :, qui effectue une seule vérification pour une correspondance de chaîne partielle sur l'ensemble du contenu du tableau. Vous pouvez également exécuter un sous-filtre directement sur les éléments du tableau et ses sous-champs à l'aide de l'une des fonctions suivantes :

• La fonction contains() permet de renvoyer des résultats lorsque des éléments du tableau contiennent la valeur spécifiée.

• La fonction containsOnly() permet de renvoyer des résultats uniquement si tous les éléments du tableau correspondent au sous-filtre.

Ces deux fonctions sont compatibles avec les requêtes de sous-filtres, comme les suivantes :

• Correspondance exacte des éléments : fait correspondre les éléments d'un tableau contenant la chaîne exacte "example".
• Opérations arithmétiques spécifiques : fait correspondre les éléments d'un tableau supérieurs ou égaux à 100.
• Filtrage complexe en fonction des structures des tableaux : fait correspondre les éléments d'un tableau contenant la propriété x avec une valeur y correspondante.

Format de la fonction contains()

La fonction contains() a le format suivant :

contains(ARRAY_ATTRIBUTE_NAME, SUBFILTER)

Remplacez les éléments suivants :

• ARRAY_ATTRIBUTE_NAME : champ ou sous-champ de type tableau (liste).
• SUBFILTER : expression qui définit les valeurs à rechercher dans le tableau. Le format du sous-filtre diffère selon que ARRAY_ATTRIBUTE_NAME est un tableau d'objets ou un tableau d'éléments de type primitif. Si ARRAY_ATTRIBUTE_NAME est un tableau d'objets comportant des tableaux imbriqués, vous pouvez utiliser un sous-filtre spécifique pour indiquer que vous souhaitez que toutes les conditions soient remplies dans le même élément ARRAY_ATTRIBUTE_NAME.

L'API Security Command Center renvoie les résultats pour lesquels ARRAY_ATTRIBUTE_NAME contient au moins un élément correspondant au sous-filtre SUBFILTER.

Remarque  : Si vous souhaitez utiliser ces filtres dans la console Google Cloud , n'incluez pas les caractères d'échappement. Par exemple, au lieu de \"string-value\", utilisez "string-value".

Format de la fonction containsOnly()

La fonction containsOnly() a le format suivant :

containsOnly(ARRAY_ATTRIBUTE_NAME, SUBFILTER)

Remplacez les éléments suivants :

• ARRAY_ATTRIBUTE_NAME : champ ou sous-champ de type tableau (liste). Lorsque vous exécutez des requêtes à l'aide de l'API Security Command Center, vous pouvez utiliser la fonction containsOnly() pour n'importe quel attribut de tableau disponible.
• SUBFILTER : expression qui définit les valeurs à rechercher dans le tableau. Le format du sous-filtre diffère selon que ARRAY_ATTRIBUTE_NAME est un tableau d'objets ou un tableau d'éléments de type primitif. Si ARRAY_ATTRIBUTE_NAME est un tableau d'objets comportant des tableaux imbriqués, vous pouvez utiliser un sous-filtre spécifique pour indiquer que vous souhaitez que toutes les conditions soient remplies dans le même élément ARRAY_ATTRIBUTE_NAME.

L'API Security Command Center renvoie les résultats pour lesquels tous les éléments ARRAY_ATTRIBUTE_NAME correspondent à SUBFILTER.

Remarque  : Si vous souhaitez utiliser ces filtres dans la console Google Cloud , n'incluez pas les caractères d'échappement. Par exemple, au lieu de \"string-value\", utilisez "string-value".

Sous-filtre pour un tableau d'objets

Voici un extrait de l'exemple JSON précédent. Ici, le champ list_middle_object est un tableau d'objets :

    "list_middle_object": [
      {
        "v": 321,
        "w": [
          {
            "a": 3,
            "b": 4
          }
        ]
      }
    ]

L'exemple suivant interroge les résultats pour lesquels au moins un des éléments du champ list_middle_object comporte un sous-champ v dont la valeur est supérieure ou égale à 321 :

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="contains(my_property.outer_object.list_middle_object, v  >= 321)"

Pour obtenir des exemples pratiques utilisant les fonctions contains() et containsOnly(), consultez Résultats contenant des valeurs de tableau spécifiques.

Sous-filtre pour un tableau contenant des éléments de type primitif

Les types primitifs sont des chaînes, des nombres et des valeurs booléennes. Pour utiliser la fonction contains() sur un tableau contenant des types primitifs, vous devez utiliser le mot clé spécial elem.

Voici un extrait de l'exemple JSON précédent. Ici, le champ u est un tableau d'éléments de type primitif :

"u": ["list-element-1", "list-element-2", "list-element-3"]

L'exemple suivant interroge les résultats pour lesquels au moins un des éléments du champ u est "list-element-1" :

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="contains(my_property.outer_object.u, elem = \"list-element-1\")"

Pour obtenir des exemples pratiques utilisant la fonction contains(), consultez la section Résultats contenant des valeurs de tableau spécifiques.

Sous-filtre spécifique

Voici un extrait de l'exemple JSON précédent. Ici, le champ list_middle_object est un tableau d'objets. Les objets de ce tableau contiennent un tableau imbriqué.

"list_middle_object": [
  {
    "v": 321,
    "w": [
      {
        "a": 3,
        "b": 4
      }
    ]
  }
]

L'exemple suivant interroge les résultats pour lesquels les deux conditions suivantes sont remplies dans le même élément list_middle_object :

• La valeur du sous-champ v est supérieure ou égale à 321.
• Le sous-champ w ne contient pas d'élément dont la propriété a est égale à 3.

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --filter="contains(my_property.outer_object.list_middle_object, v  >= 321 AND -contains(w, a = 3))"

Pour obtenir des exemples pratiques utilisant la fonction contains(), consultez la section Résultats contenant des valeurs de tableau spécifiques.

Exemple de tri des résultats

Vous pouvez trier les résultats par sous-champs stricts de type primitif : chaînes, nombres et booléens. Supposons que l'exemple JSON précédent est un attribut de résultat nommé my_property. L'exemple suivant inclut des requêtes permettant de trier les champs de résultats. Le mot clé DESC indique que le champ suivant doit être trié par ordre décroissant. L'ordre par défaut est croissant.

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --order-by="my_property.outer_object.middle_object.deeply_nested_object.x DESC"

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --order-by="my_property.outer_object.middle_object.deeply_nested_object.x"

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --order-by="my_property.outer_object.middle_object.y DESC"

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --order-by="my_property.outer_object.middle_object.y"

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --order-by="my_property.outer_object.z DESC"

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --order-by="my_property.outer_object.z"

Filtrer les exemples

Les sections suivantes présentent des exemples pratiques de filtres de résultats.

Remarque  : Si vous souhaitez utiliser ces filtres dans la console Google Cloud , n'incluez pas les caractères d'échappement. Par exemple, au lieu de \"string-value\", utilisez "string-value".

Filtrer les résultats générés après un moment précis

Ces exemples de filtres correspondent aux résultats les plus récents obtenus après le mercredi 5 juin 2019 à 22:12:05 GMT. Avec le filtre event_time, vous pouvez exprimer le temps en utilisant les formats et types suivants :

• Epoch Unix (en millisecondes) sous forme de littéral entier

  "event_time > 1559772725000"
  

• RFC 3339 en tant que littéral de chaîne

  "event_time > \"2019-06-05T22:34:40+00:00\""
  

Filtrer les champs de type tableau

L'exemple suivant décrit l'utilisation d'une correspondance de chaîne partielle sur un champ de type tableau dans un filtre :

"indicator.domains : \"website.com\""

L'API Security Command Center renvoie tous les résultats avec une chaîne partielle website.com dans le tableau. Par exemple, il fait correspondre un résultat avec indicator.domains = [\"onewebsite.com\"], car "website.com" est une sous-chaîne dans un élément du tableau.

Dans les sections suivantes, les exemples de filtres montrent certaines options d'utilisation d'un filtre complet de type tableau à l'aide de la fonction contains().

Filtrer le champ vulnerability.cve.references

L'exemple suivant renvoie les résultats pour lesquels au moins un élément du tableau vulnerability.cve.references possède une propriété source égale à SOURCE_OF_REFERENCE et une propriété uri contenant FILTERED_URI.

"contains(vulnerability.cve.references, source = \"SOURCE_OF_REFERENCE\" AND uri : \"FILTERED_URI\")"

Remplacez les éléments suivants :

• SOURCE_OF_REFERENCE : nom de la source d'une référence Common Vulnerabilities and Exposures (CVE), par exemple, NVD.
• FILTERED_URI : URI de la source de la référence CVE.

Filtrer le champ indicator.domains

L'exemple suivant renvoie les résultats pour lesquels au moins un domaine d'indicateur contient à la fois mycompanyprefix et .ca.

"contains(indicator.domains, elem : \"mycompanyprefix\" AND elem : \".ca\")"

Filtrer le champ indicator.ip_addresses

L'exemple suivant renvoie les résultats pour lesquels au moins un élément du tableau indicator.ip_addresses est égal à IP_ADDRESS.

"contains(indicator.ip_addresses, elem = \"IP_ADDRESS\")"

Remplacez IP_ADDRESS par une adresse IP associée aux résultats que vous recherchez.

Filtrer les personnes responsables des systèmes externes

L'exemple suivant renvoie les résultats pour lesquels au moins un élément du tableau external_systems.EXTERNAL_SYSTEM_NAME.assignees est égal à ASSIGNEE.

"contains(external_systems.EXTERNAL_SYSTEM_NAME.assignees, elem = \"ASSIGNEE\")"

Remplacez les éléments suivants :

• EXTERNAL_SYSTEM_NAME : nom d'un système SIEM/SOAR tiers, par exemple demisto.
• ASSIGNEE : personne responsable d'un système externe.

Filtrer le champ resource.folders.resource_folder

L'exemple suivant renvoie les résultats pour lesquels au moins un élément du tableau resource.folders.resource_folder n'est pas égal à FOLDER_NAME.

"contains(resource.folders.resource_folder, -(elem = \"FOLDER_NAME\"))"

Filtrer le champ resource.folders.resource_folder_display_name

L'exemple suivant renvoie les résultats pour lesquels au moins un élément du tableau resource.folders.resource_folder_display_name est égal à DISPLAY_NAME.

"contains(resource.folders.resource_folder_display_name, elem = \"DISPLAY_NAME\")"

Remplacez DISPLAY_NAME par le nom défini par l'utilisateur pour le dossier associé aux résultats que vous recherchez.

Le filtre n'inclut que des comptes de service spécifiques.

L'exemple suivant ne renvoie des résultats que lorsque la valeur du membre de chaque entrée iam_bindings est égale à l'un des comptes de service fournis.

containsOnly(iam_bindings, (member = SERVICE_ACCOUNT1 OR member = SERVICE_ACCOUNT2 OR member = "SERVICE_ACCOUNT3 "))

Remplacez SERVICE_ACCOUNT1, SERVICE_ACCOUNT2 et SERVICE_ACCOUNT3 par les adresses e-mail des comptes de service.

Pour apprendre à utiliser les fonctions contains() et containsOnly() dans un filtre de résultat, consultez Sous-filtres pour les champs de type tableau.

Étapes suivantes

En savoir plus sur la configuration des notifications de résultats