Elenco dei risultati di sicurezza utilizzando l'API Security Command Center

I risultati di Security Command Center modellano i potenziali rischi per la sicurezza delle risorse in un progetto o in un'organizzazione. Un risultato si riferisce sempre a una risorsa specifica in Security Command Center.

Questa guida mostra come utilizzare le librerie client di Security Command Center per accedere ai risultati. Ogni risultato appartiene a una fonte. La maggior parte dei fornitori di rilevatori o risultati genera risultati all'interno della stessa origine.

I ruoli IAM per Security Command Center possono essere concessi a livello di organizzazione, cartella o progetto. La possibilità di visualizzare, modificare, creare o aggiornare risultati, asset e origini di sicurezza dipende dal livello per cui ti è stato concesso l'accesso. Per scoprire di più sui ruoli di Security Command Center, consulta Controllo degli accessi.

Prima di iniziare

Prima di configurare una sorgente, devi completare i seguenti passaggi:

Dimensioni pagina

Tutte le API di elenco di Security Command Center sono paginate. Ogni risposta restituisce una pagina di risultati e un token per restituire la pagina successiva. Le dimensioni della pagina sono configurabili. Le dimensioni della pagina predefinite sono 10. Puoi impostarlo su un valore minimo di 1 e un valore massimo di 1000.

Conservazione dei risultati

Un rilevamento rimane disponibile per l'inserimento o l'esecuzione di query per almeno 13 mesi.

Security Command Center memorizza gli snapshot di ogni risultato. Uno screenshot di un rilevamento viene conservato per almeno 13 mesi. Se tutti gli snapshot per una segnalazione vengono eliminati, la segnalazione non può più essere elencata o recuperata.

Per ulteriori informazioni sulla conservazione dei dati di Security Command Center, consulta Conservazione dei dati.

Elenca tutti i risultati

gcloud

Per elencare tutti i risultati in un progetto, una cartella o un'organizzazione, esegui il seguente comando:

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

Sostituisci quanto segue:

  • PARENT_TYPE: il livello della gerarchia delle risorse per elencare i risultati. Utilizza organizations, folders o projects.
  • PARENT_ID: l'ID numerico dell'organizzazione, della cartella o del progetto oppure l'ID progetto alfanumerico.
  • LOCATION: se la residenza dei dati è attivata, la località di Security Command Center in cui elencare i risultati. Se la residenza dei dati non è attivata, utilizza il valore global.

Per altri esempi, esegui: 

gcloud scc findings list --help

Per esempi nella documentazione, consulta gcloud scc findings list.

Vai

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

L'output di ogni risultato è simile al seguente:

{
  "finding": {
    "name": "organizations/ORGANIZATION_ID/sources/SOURCE_ID/findings/FINDING_ID",
    "parent": "organizations/ORGANIZATION_ID/sources/SOURCE_ID",
    "resourceName": "//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER",
    "state": "ACTIVE",
    "category": "Malware: Cryptomining Bad Domain",
    "sourceProperties": {
      "sourceId": {
        "projectNumber": "PROJECT_NUMBER",
        "customerOrganizationNumber": "ORGANIZATION_ID"
      },
      "detectionCategory": {
        "technique": "cryptomining",
        "indicator": "domain",
        "ruleName": "bad_domain",
        "subRuleName": "cryptomining"
      },
      "detectionPriority": "LOW",
      "affectedResources": [
        {
          "gcpResourceName": "//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER"
        }
      ],
      "evidence": [
        {
          "sourceLogId": {
            "projectId": "PROJECT_ID",
            "resourceContainer": "projects/PROJECT_ID",
            "timestamp": {
              "seconds": "1636566099",
              "nanos": 5.41483849E8
            },
            "insertId": "INSERT_ID"
          }
        }
      ],
      "properties": {
        "domains": ["DOMAIN"],
        "instanceDetails": "/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_ID",
        "network": {
          "project": "PROJECT_ID",
          "location": "ZONE"
        },
        "dnsContexts": [
          {
            "authAnswer": true,
            "sourceIp": "SOURCE_IP_ADDRESS",
            "queryName": "DOMAIN",
            "queryType": "A",
            "responseCode": "NXDOMAIN"
          }
        ],
        "vpc": {
          "vpcName": "default"
        }
      },
      "findingId": "FINDING_ID",
      "contextUris": {
        "mitreUri": {
          "displayName": "MITRE Link",
          "url": "https://attack.mitre.org/techniques/T1496/"
        },
        "virustotalIndicatorQueryUri": [
          {
            "displayName": "VirusTotal Domain Link",
            "url": "https://www.virustotal.com/gui/domain/DOMAIN/detection"
          }
        ],
        "cloudLoggingQueryUri": [
          {
            "displayName": "Cloud Logging Query Link",
            "url": "https://console.cloud.google.com/logs/query;query\u003dtimestamp%3D%222021-11-10T17:41:39.541483849Z%22%0AinsertId%3D%22INSERT_ID%22%0Aresource.labels.project_id%3D%22PROJECT_ID%22?project\u003dPROJECT_ID"
          }
        ],
        "relatedFindingUri": {}
      }
    },
    "securityMarks": {
      "name": "organizations/ORGANIZATION_ID/sources/SOURCE_ID/findings/FINDING_ID/securityMarks"
    },
    "eventTime": "2021-11-10T17:41:41.594Z",
    "createTime": "2021-11-10T17:41:42.014Z",
    "severity": "LOW",
    "workflowState": "NEW",
    "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",
    "projectName": "//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER",
    "projectDisplayName": "PROJECT_ID",
    "parentName": "//cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID",
    "parentDisplayName": "PARENT_NAME",
    "type": "google.cloud.resourcemanager.Project",
    "displayName": "PROJECT_ID"
  }
}

Filtra i risultati

Un progetto, una cartella o un'organizzazione potrebbe avere molti risultati. L'esempio precedente non utilizza un filtro, pertanto vengono restituiti tutti i record di ricerca.

Per aiutarti a ottenere informazioni solo sui campi che ti interessano, puoi utilizzare i filtri di ricerca. Questi filtri sono simili alle clausole "where" negli enunciati SQL, ma invece di essere applicati alle colonne, vengono applicati agli oggetti restituiti dall'API.

L'esempio seguente elenca solo i risultati con una categoria "MEDIUM_RISK_ONE". Fornitori di risultati diversi (noti anche come origini di sicurezza) utilizzano insiemi diversi di categorie. Per determinare le categorie che puoi utilizzare nel filtro, consulta la documentazione del fornitore di risultati.

gcloud

Utilizza il seguente comando per filtrare i risultati:

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

Sostituisci quanto segue:

  • PARENT_TYPE: il livello della gerarchia delle risorse per elencare i risultati. Utilizza organizations, folders o projects.
  • PARENT_ID: l'ID numerico dell'organizzazione, della cartella o del progetto oppure l'ID progetto alfanumerico.
  • LOCATION: se la residenza dei dati è abilitata, la posizione di Security Command Center in cui elencare i risultati con un filtro. Se la residenza dei dati non è abilitata, utilizza il valore global.
  • SOURCE_ID: l'ID dell'origine di sicurezza che fornisce il tipo di rilevamento.
  • FILTER: il filtro da utilizzare. Ad esempio, il seguente filtro restituisce solo i risultati della categoria MEDIUM_RISK_ONE: 
    --filter="category=\"MEDIUM_RISK_ONE\""

Per altri esempi, esegui: 

gcloud scc findings list --help

Per esempi nella documentazione, consulta gcloud scc findings list.

Vai

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 supporta anche array e oggetti JSON completi come potenziali tipi di proprietà. Puoi filtrare in base a:

  • Elementi array
  • Oggetti JSON completi con corrispondenza parziale della stringa all'interno dell'oggetto
  • Subcampi dell'oggetto JSON

Operatori supportati

Le istruzioni di query per i risultati di Security Command Center supportano gli operatori supportati dalla maggior parte delle API Google Cloud.

L'elenco seguente mostra l'utilizzo di vari operatori:

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

Il seguente elenco mostra tutti gli operatori e le funzioni supportati nelle istruzioni di query per i risultati:

  • Per le stringhe:
    • = per la piena uguaglianza
    • : per la corrispondenza parziale delle stringhe
  • Per i numeri:
    • <, >, <=, >= per le disuguaglianze
    • =, != per l'uguaglianza
  • Per i valori booleani:
    • = per l'uguaglianza
  • Per le relazioni logiche:
    • AND
    • OR
    • NOT o -
  • Per raggruppare le espressioni:
    • (, ) (parentesi tonde)
  • Per gli array:
    • contains(), una funzione per eseguire query sui risultati con un campo array contenente almeno un elemento che corrisponde al filtro specificato
    • containsOnly(), una funzione per eseguire query sui risultati con un campo array contenente solo gli elementi corrispondenti al filtro specificato
  • Per gli indirizzi IP:
    • inIpRange(), una funzione per eseguire query sugli indirizzi IP all'interno di un intervallo CIDR specificato

Filtraggio in base agli indirizzi IP

Alcune proprietà dei risultati includono gli indirizzi IP. Puoi filtrare i risultati in base a indirizzi IP specifici o a un intervallo di indirizzi IP.

Gli indirizzi IP vengono visualizzati come stringhe in una serie di risultati e proprietà dei risultati, tra cui:

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

Per filtrare in base a un indirizzo IP specifico, puoi utilizzare l'operatore di uguaglianza, come mostrato nell'esempio seguente:

access.caller_ip="192.0.2.0"

Per filtrare i risultati in base a un intervallo di indirizzi IP, utilizza la funzione inIpRange. Utilizzando la funzione inIpRange, puoi filtrare i risultati in modo da visualizzare solo quelli che contengono un indirizzo IP all'interno di un intervallo CIDR specificato. Utilizzando l'operazione NOT con inIpRange, puoi filtrare i risultati solo su quelli che contengono un indirizzo IP esterno all'intervallo CIDR specificato.

L'esempio seguente mostra la sintassi della funzione inIpRange:

inIpRange(IP_FINDING_FIELD, "CIDR_RANGE")

Se l'indirizzo IP si trova in un elemento dell'array in un campo di risultati che contiene un array, utilizza la seguente sintassi sia con la funzione contains sia con la funzione inIpRange:

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

Nell'esempio seguente, la funzione inIpRange valuta ogni destination_ip elemento dell'array contenuto nel connections campo di ricerca per un indirizzo IP che si trova nell'intervallo CIDR definito da 192.0.2.0/24:

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

L'esempio seguente mostra un comando gcloud CLI che utilizza la funzione inIpRange per filtrare i risultati che hanno un indirizzo IP nel campo connections.source_ip compreso in un intervallo, ma non in un altro. Il campo connections è un campo di tipo array, pertanto viene utilizzata la funzione contains:

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\"))"

Esempio di oggetto JSON

Gli esempi riportati di seguito in questa pagina presuppongono che il seguente oggetto JSON sia un attributo risultato:

{
  "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"
    ]
  }
}

Esempio di filtraggio dei risultati

Supponiamo che l'esempio JSON precedente sia un attributo di rilevamento chiamato my_property. L'esempio seguente include query per i risultati che hanno l'oggetto come proprietà. Puoi anche utilizzare questi filtri con altri filtri utilizzando AND e OR nella query.

gcloud scc findings list PARENT_TYPE/PARENT_ID \
    --location=LOCATION \
    --source=SOURCE_ID \
    --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\""

Filtri secondari per i campi di tipo array

Quando chiami ListFindings, puoi utilizzare una corrispondenza di sottostringa :, che esegue un singolo controllo per una corrispondenza di stringa parziale tra tutti i contenuti dell'array. In alternativa, puoi eseguire un sottofiltro direttamente sugli elementi dell'array e dei relativi sottocampi utilizzando una delle seguenti funzioni:

  • La funzione contains() per restituire i risultati quando uno degli elementi dell'array contiene il valore specificato.

  • La funzione containsOnly() restituisce i risultati solo se tutti gli elementi dell'array corrispondono al sottofiltro.

Entrambe queste funzioni supportano funzionalità di query sui sottofiltri, ad esempio:

  • Corrispondenza esatta degli elementi: trova gli elementi dell'array che contengono la stringa esatta "example".
  • Operazioni numeriche specifiche: corrispondono agli elementi dell'array maggiori o uguali a 100.
  • Filtri complessi in base a strutture di array: abbina gli elementi dell'array che contengono la proprietà x a un valore corrispondente y.

Formato della funzione contains()

La funzione contains() ha il seguente formato:

contains(ARRAY_ATTRIBUTE_NAME, SUBFILTER)

Sostituisci quanto segue:

  • ARRAY_ATTRIBUTE_NAME: un campo o un sottocampo di tipo array (un elenco).
  • SUBFILTER: un'espressione che definisce i valori da cercare nell'array. Il formato del sottofiltro è diverso a seconda che ARRAY_ATTRIBUTE_NAME sia un array di oggetti o un array di elementi di tipo primitivo. Se ARRAY_ATTRIBUTE_NAME è un array di oggetti con array nidificati, puoi utilizzare un sottofiltro basato su ambito per specificare che tutte le condizioni devono essere soddisfatte nello stesso elemento ARRAY_ATTRIBUTE_NAME.

L'API Security Command Center restituisce i risultati in cui il ARRAY_ATTRIBUTE_NAME contiene almeno un elemento chesoddisfa il SUBFILTER.

Formato della funzione containsOnly()

La funzione containsOnly() ha il seguente formato:

containsOnly(ARRAY_ATTRIBUTE_NAME, SUBFILTER)

Sostituisci quanto segue:

  • ARRAY_ATTRIBUTE_NAME: un campo o un sottocampo di tipo array (un elenco). Quando esegui query utilizzando l'API Security Command Center, puoi utilizzare la funzione containsOnly() per qualsiasi attributo array disponibile.
  • SUBFILTER: un'espressione che definisce i valori da cercare nell'array. Il formato del sottofiltro è diverso a seconda che ARRAY_ATTRIBUTE_NAME sia un array di oggetti o un array di elementi di tipo primitivo. Se ARRAY_ATTRIBUTE_NAME è un array di oggetti con array nidificati, puoi utilizzare un filtro secondario basato su ambito per specificare che tutte le condizioni devono essere soddisfatte nello stesso elemento ARRAY_ATTRIBUTE_NAME.

L'API Security Command Center restituisce i risultati in cui tutti gli elementi ARRAY_ATTRIBUTE_NAME corrispondono a SUBFILTER.

Filtro secondario per un array di oggetti

Di seguito è riportato un estratto dell'esempio JSON precedente. In questo caso, il campo list_middle_object è un array di oggetti:

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

Il seguente esempio esegue query sui risultati in cui almeno uno degli elementi nel campo list_middle_object ha un sottocampo v con un valore maggiore o uguale a 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)"

Per esempi pratici che utilizzano le funzioni contains() e containsOnly(), consulta Risultati che contengono valori di array specifici.

Filtro secondario per un array contenente elementi di tipo primitivo

I tipi primitivi sono stringhe, numeri e booleani. Per utilizzare la funzione contains() su un array contenente tipi primitivi, utilizza la parola chiave speciale elem.

Di seguito è riportato un estratto dell'esempio JSON precedente. In questo caso, il campo u è un array di elementi di tipo primitivo:

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

L'esempio seguente esegue query sui risultati in cui almeno uno degli elementi nel campo u è "elemento-elenco-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\")"

Per esempi pratici che utilizzano la funzione contains(), consulta Risultati che contengono valori di array specifici.

Filtro secondario basato sugli ambiti

Di seguito è riportato un estratto dell'esempio JSON precedente. Qui, il campo list_middle_object è un array di oggetti e gli oggetti in questo array contengono un array nidificato.

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

L'esempio seguente esegue query sui risultati in cui entrambe le seguenti condizioni sono soddisfatte nello stesso elemento list_middle_object:

  • Il sottocampo v ha un valore maggiore o uguale a 321.
  • Il sottocampo w non contiene un elemento con una proprietà a pari a 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))"

Per esempi pratici che utilizzano la funzione contains(), consulta Risultati che contengono valori di array specifici.

Esempio di ordinamento dei risultati

Puoi ordinare i risultati in base a sottocampi rigorosi che sono tipi primitivi: stringhe, numeri e valori booleani. Supponiamo che l'esempio JSON precedente sia un attributo di ricerca denominato my_property. L'esempio seguente include query per ordinare i campi di ricerca. La parola chiave DESC specifica che il campo che segue deve essere ordinato in ordine decrescente. L'ordine predefinito è crescente.

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"

Esempi di filtro

Le sezioni seguenti mostrano esempi pratici di ricerca dei filtri.

Filtra i risultati che si sono verificati dopo un determinato momento

Questi filtri di esempio corrispondono ai risultati che si sono verificati più di recente dopo le 22:12:05 GMT di mercoledì 5 giugno 2019. Con il filtro event_time, puoi esprimere il tempo utilizzando i seguenti formati e tipi:

  • Tempo Unix epoch (in millisecondi) come valore letterale intero

    "event_time > 1559772725000"

  • RFC 3339 come valore letterale di stringa

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

Filtrare in base a campi di tipo array

L'esempio seguente mostra l'utilizzo di una corrispondenza parziale di stringhe in un campo di tipo array all'interno di un filtro:

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

L'API Security Command Center restituisce qualsiasi risultato con una stringa parziale website.com all'interno dell'array. Ad esempio, corrisponde a un risultato conindicator.domains = [\"onewebsite.com\"] perché "sitoweb.com" è una sottostringa in un elemento dell'array.

Nelle sezioni seguenti, i filtri di esempio mostrano alcune opzioni per l'utilizzo di filtri di tipo array avanzato utilizzando la funzione contains().

Filtra in base al campo vulnerability.cve.references

L'esempio seguente restituisce risultati in cui almeno un elemento nell'array vulnerability.cve.references ha sia una proprietà source uguale a SOURCE_OF_REFERENCE sia una proprietà uri con FILTERED_URI.

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

Sostituisci quanto segue:

Filtra in base al campo indicator.domains

L'esempio seguente restituisce i risultati in cui almeno un dominio dell'indicatore contiene sia mycompanyprefix sia .ca.

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

Filtra in base al campo indicator.ip_addresses

L'esempio seguente restituisce i risultati in cui almeno un elemento nell'array indicator.ip_addresses è uguale a IP_ADDRESS.

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

Sostituisci IP_ADDRESS con un indirizzo IP associato ai risultati che stai cercando.

Filtrare in base agli assegnatari del sistema esterno

L'esempio seguente restituisce i risultati in cui almeno un elemento nell'array external_systems.EXTERNAL_SYSTEM_NAME.assignees è uguale a ASSIGNEE.

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

Sostituisci quanto segue:

  • EXTERNAL_SYSTEM_NAME: il nome di un sistema SIEM/SOAR di terze parti, ad esempio demisto.
  • ASSIGNEE: un assegnatario nel sistema esterno.

Filtra in base al campo resource.folders.resource_folder

L'esempio seguente restituisce risultati in cui almeno un elemento nell'array resource.folders.resource_folder non è uguale a FOLDER_NAME.

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

Filtra in base al campo resource.folders.resource_folder_display_name

L'esempio seguente restituisce i risultati in cui almeno un elemento nell'array resource.folders.resource_folder_display_name è uguale a DISPLAY_NAME.

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

Sostituisci DISPLAY_NAME con il nome definito dall'utente della cartella associata ai risultati che stai cercando.

Il filtro include solo account di servizio specifici

L'esempio seguente restituisce risultati solo quando il valore del membro di ogni voce iam_bindings è uguale a uno degli account di servizio forniti.

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

Sostituisci SERVICE_ACCOUNT1, SERVICE_ACCOUNT2 e SERVICE_ACCOUNT3 con gli indirizzi email degli account servizio.

Per scoprire come utilizzare le funzioni contains() e containsOnly() in un filtro di risultati, consulta Filtri secondari per i campi di tipo array.

Passaggi successivi

Scopri di più sulla configurazione delle notifiche sui risultati.