Administra las fuentes de seguridad mediante la API de Security Command Center

En esta guía, se explica cómo usar la API de Security Command Center para crear una fuente para generar resultados. Cuando agregas una fuente, Security Command Center crea las fuentes adecuadas y les asigna los permisos correspondientes.

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 las fuentes de seguridad dependen del nivel al que se te otorgue acceso. Para obtener más información Para conocer los roles de Security Command Center, consulta Control de acceso.

Antes de comenzar

Antes de configurar una fuente, debes hacer lo siguiente: autenticar con la API de Security Command Center.

Crea una fuente

En este ejemplo, se muestra cómo crear una fuente con un nombre visible específico y que se usa en Security Command Center.

El servidor asigna de forma automática un ID al origen.

Python

from google.cloud import securitycenter

client = securitycenter.SecurityCenterClient()
# organization_id is the numeric ID of the organization. e.g.:
# organization_id = "111122222444"
org_name = f"organizations/{organization_id}"

created = client.create_source(
    request={
        "parent": org_name,
        "source": {
            "display_name": "Customized Display Name",
            "description": "A new custom source that does X",
        },
    }
)
print(f"Created Source: {created.name}")

Java

static Source createSource(OrganizationName organizationName) {
  try (SecurityCenterClient client = SecurityCenterClient.create()) {
    // Start setting up a request to create a source in an organization.
    // OrganizationName organizationName = OrganizationName.of(/*organizationId=*/"123234324");
    Source source =
        Source.newBuilder()
            .setDisplayName("Customized Display Name")
            .setDescription("A new custom source that does X")
            .build();

    CreateSourceRequest.Builder request =
        CreateSourceRequest.newBuilder().setParent(organizationName.toString()).setSource(source);

    // Call the API.
    Source response = client.createSource(request.build());

    System.out.println("Created Source: " + response);
    return response;
  } catch (IOException e) {
    throw new RuntimeException("Couldn't create client.", e);
  }
}

Go

import (
	"context"
	"fmt"
	"io"

	securitycenter "cloud.google.com/go/securitycenter/apiv1"
	"cloud.google.com/go/securitycenter/apiv1/securitycenterpb"
)

// createSource creates a new source for organization orgID. orgID is
// the numeric identifier of the organization
func createSource(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.CreateSourceRequest{
		Source: &securitycenterpb.Source{
			DisplayName: "Customized Display Name",
			Description: "A new custom source that does X",
		},
		Parent: fmt.Sprintf("organizations/%s", orgID),
	}
	source, err := client.CreateSource(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateSource: %w", err)
	}

	fmt.Fprintf(w, "New source created: %s\n", source.Name)
	fmt.Fprintf(w, "Display Name: %s\n", source.DisplayName)
	return nil
}

Node.js

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

// Creates a new client.
const client = new SecurityCenterClient();
// organizationId is numeric organization identifier.
/*
 * TODO(developer): Uncomment the following lines
 */
// const organizationId = "1234567777";
async function createSource() {
  const [source] = await client.createSource({
    source: {
      displayName: 'Customized Display Name',
      description: 'A new custom source that does X',
    },
    parent: client.organizationPath(organizationId),
  });
  console.log('New Source: %j', source);
}
createSource();

API

En la API, realiza una solicitud al método organizations.sources.create. El cuerpo de la solicitud contiene una instancia de Fuente.

  POST https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources -d

  {
    "name": "SOURCE_NAME",
    "description": "SOURCE_DESCRIPTION",
    "displayName": "DISPLAY_NAME"
  }

Reemplaza lo siguiente:

  • API_VERSION: Es la versión de la API a la que se orienta.
  • ORGANIZATION_ID: El ID de tu organización.
  • SOURCE_NAME: Es el nombre de la fuente.
  • SOURCE_DESCRIPTION: Es una descripción de la fuente (máx. 1,024 caracteres).
  • DISPLAY_NAME: Es el nombre visible de la fuente (entre uno y 64 caracteres).

La fuente no se puede ver en la consola de Security Command Center hasta que se genera de los resultados de búsqueda. Puedes verificar que se creó. Para ello, sigue las instrucciones en Obtén una fuente específica.

Actualiza una fuente

Puedes actualizar el nombre visible y la descripción de una fuente después de crearla. También puedes usar una máscara de campo para actualizar solo un campo. En el siguiente ejemplo, se usa una máscara de campo para actualizar solo el nombre visible, sin modificar la descripción.

Python

from google.cloud import securitycenter
from google.protobuf import field_mask_pb2

client = securitycenter.SecurityCenterClient()

# Field mask to only update the display name.
field_mask = field_mask_pb2.FieldMask(paths=["display_name"])

# 'source_name' is the resource path for a source that has been
# created previously (you can use list_sources to find a specific one).
# Its format is:
# source_name = "organizations/{organization_id}/sources/{source_id}"
# e.g.:
# source_name = "organizations/111122222444/sources/1234"
updated = client.update_source(
    request={
        "source": {"name": source_name, "display_name": "Updated Display Name"},
        "update_mask": field_mask,
    }
)
print(f"Updated Source: {updated}")

Java

static Source updateSource(SourceName sourceName) {
  try (SecurityCenterClient client = SecurityCenterClient.create()) {
    // Start setting up a request to update a source.
    // SourceName sourceName = SourceName.of(/*organization=*/"123234324",/*source=*/
    // "423432321");
    Source source =
        Source.newBuilder()
            .setDisplayName("Updated Display Name")
            .setName(sourceName.toString())
            .build();
    FieldMask updateMask = FieldMask.newBuilder().addPaths("display_name").build();

    UpdateSourceRequest.Builder request =
        UpdateSourceRequest.newBuilder().setSource(source).setUpdateMask(updateMask);

    // Call the API.
    Source response = client.updateSource(request.build());

    System.out.println("Updated Source: " + response);
    return response;
  } catch (IOException e) {
    throw new RuntimeException("Couldn't create client.", e);
  }
}

Go

import (
	"context"
	"fmt"
	"io"

	securitycenter "cloud.google.com/go/securitycenter/apiv1"
	"cloud.google.com/go/securitycenter/apiv1/securitycenterpb"
	"google.golang.org/genproto/protobuf/field_mask"
)

// updateSource changes a sources display name to "New Display Name" for a
// specific source. sourceName is the full resource name of the source to be
// updated.
func updateSource(w io.Writer, sourceName string) error {
	// sourceName := "organizations/111122222444/sources/1234"
	// 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.UpdateSourceRequest{
		Source: &securitycenterpb.Source{
			Name:        sourceName,
			DisplayName: "New Display Name",
		},
		// Only update the display name field (if not set all mutable
		// fields of the source will be updated.
		UpdateMask: &field_mask.FieldMask{
			Paths: []string{"display_name"},
		},
	}
	source, err := client.UpdateSource(ctx, req)
	if err != nil {
		return fmt.Errorf("UpdateSource: %w", err)
	}
	fmt.Fprintf(w, "Source Name: %s, ", source.Name)
	fmt.Fprintf(w, "Display name: %s, ", source.DisplayName)
	fmt.Fprintf(w, "Description: %s\n", source.Description)

	return nil
}

Node.js

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

// Creates a new client.
const client = new SecurityCenterClient();
// sourceName is the full resource path to the update target.
/*
 * TODO(developer): Uncomment the following lines
 */
// const sourceName = "organizations/111122222444/sources/1234";
async function updateSource() {
  const [source] = await client.updateSource({
    source: {
      name: sourceName,
      displayName: 'New Display Name',
    },
    // Only update the display name field (if not set all mutable
    // fields of the source will be updated.
    updateMask: {paths: ['display_name']},
  });
  console.log('Updated source: %j', source);
}

updateSource();

API

En la API, realiza una solicitud al método organizations.sources.patch. El cuerpo de la solicitud contiene una instancia de Fuente.

  PATCH https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources/SOURCE_ID?updateMask=displayName -d

  {
    "description": "SOURCE_DESCRIPTION",
    "displayName": "DISPLAY_NAME",
  }

Reemplaza lo siguiente:

  • API_VERSION: Es la versión de la API a la que se orienta.
  • ORGANIZATION_ID: El ID de tu organización.
  • SOURCE_ID: Es el ID de origen. Para obtener instrucciones sobre cómo recuperar una fuente ID, consulta Obtener el ID de la fuente
  • SOURCE_DESCRIPTION: Es una descripción de la fuente (máx.: 1,024 caracteres).
  • DISPLAY_NAME: Es el nombre visible de la fuente (entre uno y 64 caracteres).

Obtén una fuente específica

Verifica que se cree o actualice una fuente de forma adecuada mediante la consulta de Security Command Center con el nombre absoluto del recurso de la fuente:

gcloud

  # Note: For GCloud you can use either full resource name or just ID Flags.
  # In this example, we are using ID Flags.
  # ORGANIZATION_ID=12344321
  # SOURCE_ID=43211234

  gcloud scc sources describe $ORGANIZATION_ID --source=$SOURCE_ID

Para obtener más ejemplos, ejecuta lo siguiente:

  gcloud scc sources describe --help

Python

from google.cloud import securitycenter

client = securitycenter.SecurityCenterClient()

# 'source_name' is the resource path for a source that has been
# created previously (you can use list_sources to find a specific one).
# Its format is:
# source_name = "organizations/{organization_id}/sources/{source_id}"
# e.g.:
# source_name = "organizations/111122222444/sources/1234"
source = client.get_source(request={"name": source_name})

print(f"Source: {source}")

Java

static Source getSource(SourceName sourceName) {
  try (SecurityCenterClient client = SecurityCenterClient.create()) {
    // Start setting up a request to get a source.
    // SourceName sourceName = SourceName.of(/*organization=*/"123234324",/*source=*/
    // "423432321");
    GetSourceRequest.Builder request =
        GetSourceRequest.newBuilder().setName(sourceName.toString());

    // Call the API.
    Source response = client.getSource(request.build());

    System.out.println("Source: " + response);
    return response;
  } catch (IOException e) {
    throw new RuntimeException("Couldn't create client.", e);
  }
}

Go

import (
	"context"
	"fmt"
	"io"

	securitycenter "cloud.google.com/go/securitycenter/apiv1"
	"cloud.google.com/go/securitycenter/apiv1/securitycenterpb"
)

// getSource retrieves a source by its resource name and print it to w.
// sourceName is the full resource name of the source to be updated.
func getSource(w io.Writer, sourceName string) error {
	// sourceName := "organizations/111122222444/sources/1234"
	// 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.GetSourceRequest{
		Name: sourceName,
	}
	source, err := client.GetSource(ctx, req)
	if err != nil {
		return fmt.Errorf("GetSource: %w", err)
	}
	fmt.Fprintf(w, "Source: %v\n", source.Name)
	fmt.Fprintf(w, "Display Name: %v\n", source.DisplayName)
	fmt.Fprintf(w, "Description: %v\n", source.Description)
	return nil
}

Node.js

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

// Creates a new client.
const client = new SecurityCenterClient();
// sourceName is the full resource name of the source to be retrieved.
/*
 * TODO(developer): Uncomment the following lines
 */
// const sourceName = "organizations/111122222444/sources/1234";
async function getSource() {
  const [source] = await client.getSource({name: sourceName});
  console.log('Source: %j', source);
}

getSource();

API

En la API, realiza una solicitud al método organizations.sources.get. El cuerpo de la solicitud está vacío.

  GET https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources/SOURCE_ID

Reemplaza lo siguiente:

  • API_VERSION: Es la versión de la API a la que se orienta.
  • ORGANIZATION_ID: El ID de tu organización.
  • SOURCE_ID: Es el ID de origen.

Enumera fuentes

Security Command Center te permite enumerar una fuente específica y enumerar todas las fuentes disponibles actualmente en una organización:

Python

from google.cloud import securitycenter

# Create a new client.
client = securitycenter.SecurityCenterClient()
# 'parent' must be in one of the following formats:
#   "organizations/{organization_id}"
#   "projects/{project_id}"
#   "folders/{folder_id}"
parent = f"organizations/{organization_id}"

# Call the API and print out each existing source.
for i, source in enumerate(client.list_sources(request={"parent": parent})):
    print(i, source)

Java

static ImmutableList<Source> listSources(OrganizationName organizationName) {
  try (SecurityCenterClient client = SecurityCenterClient.create()) {
    // Start setting up a request to list sources in an organization, project, or folder.
    // Parent must be in one of the following formats:
    //    OrganizationName organizationName = OrganizationName.of("organization-id");
    //    ProjectName projectName = ProjectName.of("project-id");
    //    FolderName folderName = FolderName.of("folder-id");
    ListSourcesRequest.Builder request =
        ListSourcesRequest.newBuilder().setParent(organizationName.toString());

    // Call the API.
    ListSourcesPagedResponse response = client.listSources(request.build());

    // This creates one list for all sources.  If your organization has a large number of sources
    // this can cause out of memory issues.  You can process them batches by returning
    // the Iterable returned response.iterateAll() directly.
    ImmutableList<Source> results = ImmutableList.copyOf(response.iterateAll());
    System.out.println("Sources:");
    System.out.println(results);
    return results;
  } catch (IOException e) {
    throw new RuntimeException("Couldn't create client.", e);
  }
}

Go

import (
	"context"
	"fmt"
	"io"

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

// listSources prints all sources in  orgID to w.  orgID is the numeric
// identifier of the organization.
func listSources(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.ListSourcesRequest{
		// Parent must be in one of the following formats:
		//		"organizations/{orgId}"
		//		"projects/{projectId}"
		//		"folders/{folderId}"
		Parent: fmt.Sprintf("organizations/%s", orgID),
	}
	it := client.ListSources(ctx, req)
	for {
		source, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("it.Next: %w", err)
		}
		fmt.Fprintf(w, "Source Name: %s, ", source.Name)
		fmt.Fprintf(w, "Display name: %s, ", source.DisplayName)
		fmt.Fprintf(w, "Description: %s\n", source.Description)
	}
	return nil
}

Node.js

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

// Creates a new client.
const client = new SecurityCenterClient();
//  organizationId is the numeric ID of the organization.
/*
 * TODO(developer): Uncomment the following lines
 */
// parent: must be in one of the following formats:
//    `organizations/${organization_id}`
//    `projects/${project_id}`
//    `folders/${folder_id}`
const parent = `organizations/${organizationId}`;
// Call the API with automatic pagination.
async function listSources() {
  const [response] = await client.listSources({parent: parent});
  let count = 0;
  console.log('Sources:');
  Array.from(response).forEach(source =>
    console.log('%d %j', ++count, source)
  );
}

listSources();

API

En la API, realiza una solicitud al método organizations.sources.list. El cuerpo de la solicitud está vacío.

  GET https://securitycenter.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/sources

Reemplaza lo siguiente:

  • API_VERSION: Es la versión de la API a la que se orienta.
  • ORGANIZATION_ID: Es el ID de tu organización.

¿Qué sigue?

Obtén más información para acceder a Security Command Center mediante un SDK.