Como fornecer metadados de imagens

Provedores de metadados são as empresas que fornecem metadados para as imagens de contêiner dos clientes. Os provedores podem usar o Container Analysis para armazenar e recuperar metadados para as imagens de seus clientes. Por exemplo, uma empresa que fornece gerenciamento de segurança para contêineres do Docker de seus clientes pode usar o Container Analysis para armazenar e recuperar metadados relacionados à segurança das imagens.

Nesta página, explicamos como fornecer detalhes de vulnerabilidade das imagens do cliente usando a API Container Analysis. Use as mesmas instruções para armazenar e recuperar qualquer tipo de metadado compatível com o Container Analysis.

Antes de começar

  1. Ative a API Container Analysis no projeto. É possível ativar a API em um projeto ou criar um novo e ativá-la depois.

    Ativar a API Container Analysis

  2. Leia a Visão geral do Container Analysis.

Como criar notas e ocorrências de vulnerabilidade para projetos

Nesta seção explicamos como provedores de vulnerabilidades de terceiros podem criar notas e ocorrências para os projetos dos usuários.

Como provedor, você criará uma nota no seu projeto para cada tipo de vulnerabilidade. Além disso, criará uma ocorrência no projeto do cliente quando essa vulnerabilidade ocorrer.

Como criar notas

Permissões do IAM:

Para executar essa tarefa, você precisa ter as seguintes permissões do IAM no projeto do provedor (que é o projeto em que as notas são criadas):

  • containeranalysis.notes.create

Como alternativa, conceda o seguinte papel predefinido do IAM, que fornece automaticamente todas as permissões necessárias:

  • Papel "Editor de notas" do Container Analysis no seu projeto.

Para criar uma nota:

API

  1. Crie um arquivo denominado note.json com a descrição e os detalhes da vulnerabilidade. No código a seguir, veja um arquivo note.json de exemplo:

    {
    "shortDescription": "A brief Description of the note",
    "longDescription": "A longer description of the note",
    "kind": "PACKAGE_VULNERABILITY",
    "vulnerabilityType": {
        "details": [
        {
            "package": "libexempi3",
            "cpeUri": "cpe:/o:debian:debian_linux:7",
            "minAffectedVersion": { "name": "2.5.7", "revision": "1"},
            "maxAffectedVersion": { "name": "2.5.9", "revision": "1"},
        },
        {
            "cpeUri": "something else"
        }
        ]
    }
}

  2. Execute o seguinte comando curl para criar uma nota em que [PROVIDER_PROJECT_ID] é o código do projeto:

    curl -X POST -H "Content-Type: application/json" -H \
    "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://containeranalysis.googleapis.com/v1beta1/projects/[PROVIDER_PROJECT_ID]/notes?note_id=[NOTE_ID] -d @note.json

Java

Para saber como instalar e usar a biblioteca de cliente do Container Registry, consulte Bibliotecas de cliente do Container Registry. Para mais informações, consulte a documentação de referência da API Container Registry Java. 

/**
 * Creates and returns a new vulnerability Note
 * @param client The Grafeas client used to perform the API requests.
 * @param noteId A user-specified identifier for the Note.
 * @param projectId the GCP project the Note will be created under
 * @return the newly created Note object
 */
public static Note createNote(GrafeasV1Beta1Client client, String noteId, String projectId) {
  Note.Builder noteBuilder = Note.newBuilder();
  Vulnerability.Builder vulBuilder = Vulnerability.newBuilder();
  // Details about the your vulnerability can be added here
  // Example: vulBuilder.setSeverity(Severity.CRITICAL);
  noteBuilder.setVulnerability(vulBuilder);
  Note newNote = noteBuilder.build();

  final String projectName = ProjectName.format(projectId);
  return client.createNote(projectName, noteId, newNote);
}

Go

Para saber como instalar e usar a biblioteca de cliente do Container Registry, consulte Bibliotecas de cliente do Container Registry. Para mais informações, consulte a documentação de referência da API Container Registry Go. 

// createNote creates and returns a new vulnerability Note.
func createNote(ctx context.Context, client *containeranalysis.GrafeasV1Beta1Client, noteID, projectID string) (*grafeaspb.Note, error) {
	projectName := fmt.Sprintf("projects/%s", projectID)

	req := &grafeaspb.CreateNoteRequest{
		Parent: projectName,
		NoteId: noteID,
		Note: &grafeaspb.Note{
			Type: &grafeaspb.Note_Vulnerability{
				// The 'Vulnerability' field can be modified to contain information about your vulnerability.
				Vulnerability: &vulnerability.Vulnerability{},
			},
		},
	}

	return client.CreateNote(ctx, req)
}

Como criar ocorrências das notas

Permissões do IAM:

Para executar esta tarefa, você precisa ter as seguintes permissões do IAM:

  • containeranalysis.occurrences.create no projeto do seu cliente
  • containeranalysis.notes.attachOccurrence no seu projeto

Como alternativa, conceda o seguinte papel predefinido do IAM, que fornece automaticamente todas as permissões necessárias:

  • Papel "Editor de ocorrências" do Container Analysis no projeto do cliente
  • Papel "Anexador de notas" do Container Analysis no seu projeto

Para criar ocorrências de uma nota:

API

  1. Crie um arquivo denominado occurrence.json com o seguinte conteúdo:

    {
    "resourceUrl": "<resource_url>",
    "noteName": "projects/<provider-project-id>/notes/<note_id>",
    "kind": "PACKAGE_VULNERABILITY",
    "vulnerabilityDetails": {
        "packageIssue": [{
            "affectedLocation": {
                "cpeUri": "7",
                "package": "a",
                "version":  {
                    "epoch": "1"
                    "name": "namestring"
                    "revision": "r"
                },
            },
            "fixedLocation": {
                "cpeUri": "cpe:/o:debian:debian_linux:7",
                "package": "a",
                "version":  {
                    "epoch": "2"
                    "name": "namestring"
                    "revision": "1"
                }
            }
        }]
    }
}

  2. Execute o seguinte comando curl em que [CUSTOMER_PROJECT_ID] é o código do projeto do seu cliente:

    curl -v -X POST -H "Content-Type: application/json" -H \
    "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://containeranalysis.googleapis.com/v1beta1/projects/[CUSTOMER_PROJECT_ID]/occurrences -d @occurrence.json

Java

Para saber como instalar e usar a biblioteca de cliente do Container Registry, consulte Bibliotecas de cliente do Container Registry. Para mais informações, consulte a documentação de referência da API Container Registry Java. 

/**
 * Creates and returns a new Occurrence of a previously created vulnerability Note
 * @param client The Grafeas client used to perform the API requests.
 * @param imageUrl the Container Registry URL associated with the image
 *                 example: "https://gcr.io/project/image@sha256:foo"
 * @param noteId the identifier of the Note associated with this Occurrence
 * @param occProjectId the GCP project the Occurrence will be created under
 * @param noteProjectId the GCP project the associated Note belongs to
 * @return the newly created Occurrence object
 */
public static Occurrence createOccurrence(GrafeasV1Beta1Client client, String imageUrl,
    String noteId, String occProjectId, String noteProjectId) {
  final NoteName noteName = NoteName.of(noteProjectId, noteId);
  final String occProjectName = ProjectName.format(occProjectId);

  Occurrence.Builder occBuilder = Occurrence.newBuilder();
  occBuilder.setNoteName(noteName.toString());
  Details.Builder detailsBuilder = Details.newBuilder();
  // Details about the vulnerability instance can be added here
  occBuilder.setVulnerability(detailsBuilder);
  // Attach the occurrence to the associated image uri
  Resource.Builder resourceBuilder = Resource.newBuilder();
  resourceBuilder.setUri(imageUrl);
  occBuilder.setResource(resourceBuilder);
  Occurrence newOcc = occBuilder.build();
  return client.createOccurrence(occProjectName, newOcc);
}

Go

Para saber como instalar e usar a biblioteca de cliente do Container Registry, consulte Bibliotecas de cliente do Container Registry. Para mais informações, consulte a documentação de referência da API Container Registry Go. 

// createsOccurrence creates and returns a new Occurrence of a previously created vulnerability Note.
func createOccurrence(ctx context.Context, client *containeranalysis.GrafeasV1Beta1Client, imageURL, noteID, occProjectID, noteProjectID string) (*grafeaspb.Occurrence, error) {
	req := &grafeaspb.CreateOccurrenceRequest{
		Parent: fmt.Sprintf("projects/%s", occProjectID),
		Occurrence: &grafeaspb.Occurrence{
			NoteName: fmt.Sprintf("projects/%s/notes/%s", noteProjectID, noteID),
			// Attach the occurrence to the associated image uri.
			Resource: &grafeaspb.Resource{
				Uri: imageURL,
			},
			// Details about the vulnerability instance can be added here.
			Details: &grafeaspb.Occurrence_Vulnerability{
				Vulnerability: &vulnerability.Details{},
			},
		},
	}
	return client.CreateOccurrence(ctx, req)
}

Receber todas as ocorrências de uma nota específica

É possível ver todas as ocorrências de uma vulnerabilidade específica nos projetos do cliente usando notes.occurrences.list().

Permissões do IAM:

Para executar esta tarefa, você precisa ter as seguintes permissões do IAM:

  • containeranalysis.notes.listOccurrences no seu projeto

Como alternativa, conceda o seguinte papel predefinido do IAM, que fornece automaticamente todas as permissões necessárias:

  • Papel "Leitor de ocorrências" do Container Analysis no seu projeto

Para ver todas as ocorrências de uma nota:

API

Para listar todas as ocorrências de uma nota, envie uma solicitação GET da seguinte maneira:

GET https://containeranalysis.googleapis.com/v1beta1/projects/PROJECT_ID/notes/NOTE_ID/occurrences

Consulte o endpoint da API projects.notes.occurrences.list para mais detalhes.

Java

Para saber como instalar e usar a biblioteca de cliente do Container Registry, consulte Bibliotecas de cliente do Container Registry. Para mais informações, consulte a documentação de referência da API Container Registry Java. 

/**
 * Retrieves all the Occurrences associated with a specified Note
 * Here, all Occurrences are printed and counted
 * @param client The Grafeas client used to perform the API requests.
 * @param noteId the Note's unique identifier
 * @param projectId the GCP project the Note belongs to
 * @return number of Occurrences found
 */
public static int getOccurrencesForNote(GrafeasV1Beta1Client client, String noteId,
    String projectId) {
  final NoteName noteName = NoteName.of(projectId, noteId);
  int i = 0;

  ListNoteOccurrencesRequest request = ListNoteOccurrencesRequest.newBuilder()
                                                                 .setName(noteName.toString())
                                                                 .build();
  for (Occurrence o : client.listNoteOccurrences(request).iterateAll()) {
    // Write custom code to process each Occurrence here
    System.out.println(o.getName());
    i = i + 1;
  }
  return i;
}

Go

Para saber como instalar e usar a biblioteca de cliente do Container Registry, consulte Bibliotecas de cliente do Container Registry. Para mais informações, consulte a documentação de referência da API Container Registry Go. 

// getOccurrencesForNote retrieves all the Occurrences associated with a specified Note.
// Here, all Occurrences are printed and counted.
func getOccurrencesForNote(ctx context.Context, client *containeranalysis.GrafeasV1Beta1Client, noteID, projectID string) (int, error) {
	req := &grafeaspb.ListNoteOccurrencesRequest{
		Name: fmt.Sprintf("projects/%s/notes/%s", projectID, noteID),
	}
	it := client.ListNoteOccurrences(ctx, req)
	count := 0
	for {
		occ, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return -1, err
		}
		// Write custom code to process each Occurrence here.
		fmt.Println(occ)
		count = count + 1
	}
	return count, nil
}

A seguir

  • Para instruções sobre como ver, filtrar e receber notificações sobre vulnerabilidades das imagens no Container Registry, consulte o respectivo artigo.
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
Container Registry
Comentários sobre o produto