Genera una lista de resultados de seguridad con la API de Security Command Center

Los resultados de Security Command Center establecen los modelos de riesgos potenciales de seguridad de los recursos de un proyecto o una organización. Un resultado siempre se relaciona con un recurso específico en Security Command Center.

En esta guía, se muestra cómo usar las bibliotecas cliente de Security Command Center para acceder a los resultados. Cada resultado pertenece a una fuente. La mayoría de los detectores o los proveedores de resultados producirán resultados dentro de la misma fuente.

Los roles de IAM de Security Command Center se pueden otorgar a nivel de organización, carpeta o proyecto. Tu capacidad para ver, editar, crear o actualizar resultados, recursos y fuentes de seguridad depende del nivel al que se te otorga acceso. Para obtener más información sobre los roles de Security Command Center, consulta Control de acceso.

Antes de comenzar

Antes de configurar una fuente, debes completar lo siguiente:

Tamaño de la página

Se paginan todas las API de listas del Security Command Center. Cada respuesta muestra una página de resultados y un token para mostrar la página siguiente. El tamaño de la página se puede configurar. El tamaño de página predeterminado es 10. Puedes establecerlo en un mínimo de 1 y un máximo de 1,000.

Retención de resultados

Los resultados permanecen disponibles para que los incluyas en una lista o los consultes durante al menos 13 meses.

Security Command Center almacena instantáneas de cada hallazgo. Una instantánea de un resultado se conserva durante al menos 13 meses. Si se borran todas las instantáneas de un hallazgo, este ya no se puede mostrar ni recuperar.

Para obtener más información sobre la retención de datos de Security Command Center, consulta Retención de datos.

Cómo enumerar todos los resultados

gcloud

Para mostrar una lista de todos los hallazgos de un proyecto, una carpeta o una organización, ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

  • PARENT_TYPE: Es el nivel de la jerarquía de recursos para el que se enumeran los resultados. Usa organizations, folders o projects.
  • PARENT_ID: El ID numérico de la organización, la carpeta o el proyecto, o el ID alfanumérico del proyecto.
  • LOCATION: Si la residencia de datos está habilitada, la ubicación de Security Command Center en la que se enumerarán los resultados. Si la residencia de datos no está habilitada, usa el valor global.

Para obtener más ejemplos, ejecuta lo siguiente: 

gcloud scc findings list --help

Para ver ejemplos en la documentación, consulta 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

El resultado de cada hallazgo es similar al siguiente:

{
  "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 los resultados

Un proyecto, una carpeta o una organización puede tener muchos resultados. En el ejemplo anterior, no se usa un filtro, por lo que se muestran todos los registros de los resultados.

Para obtener información sobre los campos que deseas, puedes usar los filtros de resultados. Estos filtros son como cláusulas “where” en las instrucciones de SQL, excepto en lugar de columnas, se aplican a los objetos que muestra la API.

En el siguiente ejemplo, solo se enumeran los resultados que tienen una categoría “MEDIUM_RISK_ONE”. Los distintos proveedores de resultados (también conocidos como fuentes de seguridad) usan diferentes conjuntos de categorías. Para determinar las categorías que puedes usar en tu filtro, consulta la documentación del proveedor de búsqueda.

gcloud

Usa el siguiente comando para filtrar los resultados:

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

Reemplaza lo siguiente:

  • PARENT_TYPE: Es el nivel de la jerarquía de recursos para el que se enumeran los resultados. Usa organizations, folders o projects.
  • PARENT_ID: El ID numérico de la organización, la carpeta o el proyecto, o el ID alfanumérico del proyecto.
  • LOCATION: Si la residencia de datos está habilitada, es la ubicación de Security Command Center en la que se enumeran los resultados con un filtro. Si la residencia de datos no está habilitada, usa el valor global.
  • SOURCE_ID: Es el ID de la fuente de seguridad que proporciona el tipo de resultado.
  • FILTER: Es el filtro que debes usar. Por ejemplo, el siguiente filtro muestra solo los resultados de la categoría de MEDIUM_RISK_ONE: 
    --filter="category=\"MEDIUM_RISK_ONE\""

Para obtener más ejemplos, ejecuta lo siguiente: 

gcloud scc findings list --help

Para ver ejemplos en la documentación, consulta 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 también admite arreglos y objetos JSON completos como posibles tipos de propiedades. Puedes aplicar los siguientes filtros:

  • Elementos del array
  • Objetos JSON completos con coincidencia parcial de strings dentro del objeto
  • Subcampos de objetos JSON

Operadores admitidos

Las sentencias de consulta de los resultados de Security Command Center admiten los operadores que admite la mayoría de las APIs de Google Cloud.

En la siguiente lista, se muestra el uso de varios operadores:

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

En la siguiente lista, se muestran todos los operadores y las funciones que se admiten en las instrucciones de consulta para los resultados:

  • Para cadenas:
    • = para igualdad completa
    • : para la coincidencia parcial de cadenas
  • Para números:
    • <, >, <=, >= para desigualdades
    • =, != para igualdad
  • Para valores booleanos:
    • = para igualdad
  • Para relaciones lógicas:
    • AND
    • OR
    • NOT o -
  • Para agrupar expresiones:
    • (, ) (paréntesis)
  • Para arrays:
    • contains(), una función para consultar resultados con un campo de array que contiene al menos un elemento que coincide con el filtro especificado
    • containsOnly(), una función para consultar los resultados con un campo de array que solo contiene elementos que coinciden con el filtro especificado
  • Para direcciones IP:
    • inIpRange(), una función para consultar direcciones IP dentro de un rango de CIDR especificado

Cómo filtrar direcciones IP

Algunas propiedades de búsqueda incluyen direcciones IP. Puedes filtrar los resultados según direcciones IP específicas o un rango de direcciones IP.

Las direcciones IP aparecen como cadenas en una variedad de resultados y propiedades de resultados, entre los que se incluyen los siguientes:

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

Para filtrar por una dirección IP específica, puedes usar el operador de igualdad, como se muestra en el siguiente ejemplo:

access.caller_ip="192.0.2.0"

Para filtrar los resultados según un rango de direcciones IP, usa la función inIpRange. Con la función inIpRange, filtras los resultados solo a aquellos que contienen una dirección IP dentro de un rango de CIDR especificado. Si usas la operación NOT con inIpRange, puedes filtrar los resultados solo para aquellos que contengan una dirección IP fuera del rango CIDR especificado.

En el siguiente ejemplo, se muestra la sintaxis de la función inIpRange:

inIpRange(IP_FINDING_FIELD, "CIDR_RANGE")

Si la dirección IP está en un elemento de array en un campo de búsqueda que contiene un array, usa la siguiente sintaxis con la función contains y la función inIpRange:

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

En el siguiente ejemplo, la función inIpRange evalúa cada elemento destination_ip del array que se encuentra en el campo de búsqueda connections para una dirección IP que se encuentra en el rango de CIDR definido por 192.0.2.0/24:

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

En el siguiente ejemplo, se muestra un comando de gcloud CLI que usa la función inIpRange para filtrar los resultados que tienen una dirección IP en el campo connections.source_ip que se encuentra dentro de un rango, pero no en otro. El campo connections es un campo de tipo array, por lo que se usa la función 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\"))"

Ejemplo de objeto JSON

En los ejemplos que aparecen más adelante en esta página, se supone que el siguiente objeto JSON es un atributo de resultado:

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

Ejemplo de filtrado de resultados

Supongamos que el ejemplo de JSON anterior es un atributo de resultado llamado my_property. En el siguiente ejemplo, se incluyen consultas para los resultados que tienen el objeto como propiedad. También puedes usar estos filtros con otros filtros que usen AND y OR en tu consulta.

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

Subfiltros para campos de tipo de array

Cuando llamas a ListFindings, puedes usar una coincidencia de substring :, que realiza una sola verificación de una coincidencia parcial de cadena en todo el contenido del array. Como alternativa, puedes ejecutar un subfiltro directamente en los elementos del array y sus subcampos con una de las siguientes funciones:

  • La función contains() muestra los resultados cuando algún elemento del array contiene el valor especificado.

  • La función containsOnly() muestra los resultados solo si todos los elementos del array coinciden con el subfiltro.

Ambas funciones admiten capacidades de consulta de subfiltros, como las siguientes:

  • Coincidencia exacta de elementos: hace coincidir los elementos del array que contienen la string exacta, "example".
  • Operaciones numéricas específicas: coincide con los elementos del array que son mayores o iguales que 100.
  • Filtrado complejo con estructuras de array: haz coincidir los elementos del array que contienen la propiedad x con el valor y correspondiente.

Formato de la función contains()

La función contains() tiene el siguiente formato:

contains(ARRAY_ATTRIBUTE_NAME, SUBFILTER)

Reemplaza lo siguiente:

  • ARRAY_ATTRIBUTE_NAME: Es un campo o subcampo que es del tipo de array (una lista).
  • SUBFILTER: Es una expresión que define los valores que se deben buscar en el array. El formato del subfiltro difiere según si ARRAY_ATTRIBUTE_NAME es un array de objetos o un array de elementos de tipo primitivo. Si la ARRAY_ATTRIBUTE_NAME es un array de objetos que tienen array anidados, puedes usar una subfiltro con alcance para especificar que deseas que se cumplan todas las condiciones dentro del mismo elemento ARRAY_ATTRIBUTE_NAME.

En la API de Security Command Center, se muestran resultados en los que ARRAY_ATTRIBUTE_NAME contiene al menos un elemento que cumple con SUBFILTER.

Formato de la función containsOnly()

La función containsOnly() tiene el siguiente formato:

containsOnly(ARRAY_ATTRIBUTE_NAME, SUBFILTER)

Reemplaza lo siguiente:

  • ARRAY_ATTRIBUTE_NAME: Es un campo o subcampo que es del tipo de array (una lista). Cuando ejecutas consultas con la API de Security Command Center, puedes usar la función containsOnly() para cualquier atributo de array disponible.
  • SUBFILTER: Es una expresión que define los valores que se deben buscar en el array. El formato del subfiltro difiere según si ARRAY_ATTRIBUTE_NAME es un array de objetos o un array de elementos de tipo primitivo. Si la ARRAY_ATTRIBUTE_NAME es un array de objetos que tienen array anidados, puedes usar una subfiltro con alcance para especificar que deseas que se cumplan todas las condiciones dentro del mismo elemento ARRAY_ATTRIBUTE_NAME.

La API de Security Command Center muestra resultados en los que todos los elementos ARRAY_ATTRIBUTE_NAME coinciden con SUBFILTER.

Subfiltro para un array de objetos

El siguiente es un extracto del ejemplo de JSON anterior. Aquí, el campo list_middle_object es un array de objetos:

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

En el siguiente ejemplo, se consultan los resultados en los que al menos uno de los elementos del campo list_middle_object tiene un subcampo v con un valor mayor o igual que 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)"

Para ver ejemplos prácticos que usen las funciones contains() y containsOnly(), consulta Resultados que contienen valores de array específicos.

Subfiltro para un array que contiene elementos de tipo primitivo

Los tipos básicos son strings, números y booleanos. Para usar la función contains() en un array que contiene tipos básicos, usa la palabra clave especial, elem.

El siguiente es un extracto del ejemplo de JSON anterior. Aquí, el campo u es un arreglo de elementos de tipo primitivo:

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

En el siguiente ejemplo de consulta, se muestran los resultados en los que al menos uno de los elementos del campo u es “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\")"

Para ver ejemplos prácticos que usen la función contains(), consulta Resultados que contienen valores de array específicos.

Subfiltro con permiso

El siguiente es un extracto del ejemplo de JSON anterior. Aquí, el campo list_middle_object es un array de objetos, y los objetos de este array contienen un array anidado.

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

En el siguiente ejemplo de consulta para resultados en los que se cumplen las siguientes condiciones dentro del mismo elemento list_middle_object:

  • El subcampo v tiene un valor mayor o igual que 321.
  • El subcampo w no contiene un elemento con una propiedad a igual 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))"

Para ver ejemplos prácticos que usen la función contains(), consulta Resultados que contienen valores de array específicos.

Ejemplo de resultados de ordenamiento

Puedes ordenar los resultados por subcampos estrictos que son tipos básicos: strings, números y booleanos. Supongamos que el ejemplo de JSON anterior es un atributo de resultado llamado my_property. En el siguiente ejemplo, se incluyen consultas para ordenar los campos de resultados. La palabra clave DESC especifica que el campo que sigue debe ordenarse de forma descendente. El orden predeterminado es ascendente.

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"

Filtra ejemplos

En las siguientes secciones, se muestran ejemplos prácticos de filtros de resultados.

Filtra los resultados que se produjeron después de un momento determinado

Estos filtros de ejemplo coinciden con los resultados más recientes que se produjeron después del miércoles, 5 de junio de 2019 10:12:05 p.m. GMT. Con el filtro event_time, puedes expresar la hora con los siguientes formatos y tipos:

  • Época Unix (en milisegundos) como literal de número entero

    "event_time > 1559772725000"

  • RFC 3339 como literal de string

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

Filtra en campos de tipo de array

En el siguiente ejemplo, se muestra el uso de una coincidencia parcial de strings en un campo de tipo de array dentro de un filtro:

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

La API de Security Command Center muestra cualquier resultado con una string parcial website.com dentro del array. Por ejemplo, coincide con un resultado con indicator.domains = [\"onewebsite.com\"] porque “website.com” es una substring en un elemento del array.

En las secciones siguientes, los filtros de ejemplo muestran algunas opciones para el uso de filtrado enriquecido por tipo de array con la función contains().

Filtra en el campo vulnerability.cve.references

En el siguiente ejemplo, se muestran los resultados en los que al menos un elemento del array vulnerability.cve.references tiene una propiedad source igual a SOURCE_OF_REFERENCE y una propiedad uri que tiene FILTERED_URI.

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

Reemplaza lo siguiente:

  • SOURCE_OF_REFERENCE: el nombre de la fuente de una referencia de vulnerabilidades y riesgos comunes (CVE), por ejemplo, NVD.
  • FILTERED_URI: Es el URI de la fuente de la referencia del CVE.

Filtra en el campo indicator.domains

En el siguiente ejemplo, se muestran los resultados en los que al menos un dominio de indicador tiene mycompanyprefix y .ca.

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

Filtra en el campo indicator.ip_addresses

En el siguiente ejemplo, se muestran los resultados en los que al menos un elemento del array indicator.ip_addresses es igual a IP_ADDRESS.

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

Reemplaza IP_ADDRESS por una dirección IP asociada con los resultados que buscas.

Filtrar a los usuarios asignado al sistema externo

En el siguiente ejemplo, se muestran los resultados en los que al menos un elemento del array external_systems.EXTERNAL_SYSTEM_NAME.assignees es igual a ASSIGNEE.

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

Reemplaza lo siguiente:

  • EXTERNAL_SYSTEM_NAME: El nombre de un sistema SIEM/SOAR de terceros, por ejemplo, demisto
  • ASSIGNEE: un usuario asignado en el sistema externo

Filtra en el campo resource.folders.resource_folder

En el siguiente ejemplo, se muestran los resultados en los que al menos un elemento del array resource.folders.resource_folder no es igual a FOLDER_NAME.

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

Filtra en el campo resource.folders.resource_folder_display_name

En el siguiente ejemplo, se muestran los resultados en los que al menos un elemento del array resource.folders.resource_folder_display_name es igual a DISPLAY_NAME.

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

Reemplaza DISPLAY_NAME por el nombre definido por el usuario de la carpeta asociada con los resultados que buscas.

El filtro solo incluye cuentas de servicio específicas

En el siguiente ejemplo, se muestran resultados solo cuando el valor del miembro de cada entrada iam_bindings es igual a una de las cuentas de servicio proporcionadas.

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

Reemplaza SERVICE_ACCOUNT1, SERVICE_ACCOUNT2 y SERVICE_ACCOUNT3 por las direcciones de correo electrónico de las cuentas de servicio.

Para aprender a usar las funciones contains() y containsOnly() en un filtro de resultados, consulta Filtros secundarios para campos de tipo array.

¿Qué sigue?

Obtén más información para configurar las notificaciones de búsquedas.