Como gerenciar fontes de segurança usando a API Security Command Center

Veja neste guia como usar a API Security Command Center para criar uma fonte que gera descobertas. Quando você adiciona uma fonte, o Security Command Center cria as fontes apropriadas e atribui a elas as permissões relevantes.

Requisito: para criar uma origem, o Security Command Center precisa ser ativado no nível da organização.

Os papéis do IAM para o Security Command Center podem ser concedidos no nível da organização, da pasta ou do projeto. A capacidade de ver, editar, criar ou atualizar descobertas, recursos e fontes de segurança depende do nível a que você tem acesso. Para saber mais sobre os papéis do Security Command Center, consulte Controle de acesso.

Antes de começar

Antes de configurar uma fonte, você precisa autenticar com a API Security Command Center.

Como criar uma fonte

Neste exemplo, mostramos como criar uma origem com um nome de exibição e uma descrição específicos usados no Security Command Center.

O servidor atribui automaticamente um ID à origem.

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

Na API, faça uma solicitação para o método organizations.sources.create: O corpo da solicitação contém uma instância do Source.

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

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

Substitua:

• API_VERSION: a versão da API que você está segmentando.
• ORGANIZATION_ID: o código da sua organização.
• SOURCE_NAME: o nome da origem.
• SOURCE_DESCRIPTION: uma descrição da origem (máximo: 1.024 caracteres).
• DISPLAY_NAME: o nome de exibição da origem (entre um e 64 caracteres).

A fonte não fica visível no console do Security Command Center até gerar descobertas. Verifique se ela foi criada seguindo as instruções em Receber uma fonte específica.

Como atualizar uma fonte

Você pode atualizar o nome de exibição e a descrição de uma fonte depois que ela é criada. Você também pode usar uma máscara de campo para atualizar apenas um campo. O exemplo abaixo usa uma máscara de campo para atualizar apenas o nome de exibição, deixando a descrição inalterada.

Observação: origens não podem ser excluídas ou desativadas.

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

Na API, faça uma solicitação para o método organizations.sources.patch: O corpo da solicitação contém uma instância do Source.

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

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

Substitua:

• API_VERSION: a versão da API que você está segmentando.
• ORGANIZATION_ID: o código da sua organização.
• SOURCE_ID: o ID da origem. Para instruções sobre como recuperar um ID de origem, consulte Como conseguir o ID de origem.
• SOURCE_DESCRIPTION: uma descrição da origem (máximo: 1.024 caracteres).
• DISPLAY_NAME: o nome de exibição da origem (entre um e 64 caracteres).

Receber uma fonte específica

Verifique se uma origem foi criada ou atualizada corretamente. Para isso, consulte o Security Command Center com o nome do recurso absoluto da origem:

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 mais exemplos, execute:

  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

Na API, faça uma solicitação para o método organizations.sources.get: O corpo da solicitação está vazio.

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

Substitua:

• API_VERSION: a versão da API que você está segmentando.
• ORGANIZATION_ID: o código da sua organização.
• SOURCE_ID: o ID da origem.

Como listar fontes

O Security Command Center permite que você liste uma fonte específica e liste todas as fontes atualmente disponíveis em uma organização:

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

Na API, faça uma solicitação para o método organizations.sources.list: O corpo da solicitação está vazio.

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

Substitua:

• API_VERSION: a versão da API que você está segmentando.
• ORGANIZATION_ID: o código da sua organização.

A seguir

Saiba mais sobre como acessar o Security Command Center usando um SDK.