为映像提供元数据

元数据提供方是指为其客户的容器映像提供元数据的公司。提供方可以使用 Container Analysis 来存储和检索客户映像的元数据。例如,为客户的 Docker 容器提供安全管理的公司可以使用 Container Analysis 来存储和检索映像的安全相关元数据。

本页面介绍了如何使用 Container Analysis API 为客户的映像提供漏洞详细信息。您可以按照相同说明来存储和检索 Container Analysis 支持的任何种类的元数据

准备工作

  1. 为项目启用 Container Analysis API。您可以为现有项目启用此 API,也可以先新建一个项目,然后再启用此 API。

    启用 Container Analysis API

  2. 阅读 Container Analysis 概览

为项目创建漏洞备注和事件

本部分介绍第三方漏洞提供方如何为其用户的项目创建备注和事件。

作为提供方,您需要在自己的项目中为每种漏洞类型创建备注,还需要在客户的项目中为该漏洞的备注创建事件。

创建备注

IAM 权限:

要执行此项任务,您必须对提供方的项目(即用于创建备注的项目)具有以下 IAM 权限

  • containeranalysis.notes.create

也可以授予以下预定义的 IAM 角色,该角色将自动提供所有必要的权限:

  • 您的项目的 Container Analysis 备注编辑者角色。

要创建备注,请执行以下操作:

API

  1. 创建一个名为 note.json 的文件,其中包含漏洞说明和详细信息。以下代码显示了一个示例 note.json 文件:

    {
        "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. 运行以下 curl 命令以创建备注,其中 [PROVIDER_PROJECT_ID] 是您的项目 ID:

    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

如需了解如何安装和使用 Container Registry 客户端库,请参阅 Container Registry 客户端库。如需了解详情,请参阅 Container Registry Java API 参考文档

/**
 * 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

如需了解如何安装和使用 Container Registry 客户端库,请参阅 Container Registry 客户端库。如需了解详情,请参阅 Container Registry Go API 参考文档

// createNote creates and returns a new vulnerability Note.
func createNote(ctx context.Context, client *containeranalysis.GrafeasV1Beta1Client, noteID, projectID string) (*grafeaspb.Note, error) {
	projectName := "projects/" + 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)
}

为备注创建事件

IAM 权限:

要执行此项任务,您必须拥有以下 IAM 权限

  • 客户项目的 containeranalysis.occurrences.create 权限
  • 您的项目的 containeranalysis.notes.attachOccurrence 权限。

也可以授予以下预定义的 IAM 角色,该角色将自动提供所有必要的权限:

  • 客户项目的 Container Analysis 事件编辑者角色
  • 您的项目的 Container Analysis 备注附加者角色。

要为备注创建事件,请按如下所述操作:

API

  1. 创建名为 occurrence.json 的文件,其中包含以下内容:

    {
        "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. 运行以下 curl 命令,其中 [CUSTOMER_PROJECT_ID] 是您的客户的项目 ID:

    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

如需了解如何安装和使用 Container Registry 客户端库,请参阅 Container Registry 客户端库。如需了解详情,请参阅 Container Registry Java API 参考文档

/**
 * 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

如需了解如何安装和使用 Container Registry 客户端库,请参阅 Container Registry 客户端库。如需了解详情,请参阅 Container Registry Go API 参考文档

// 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) {
	noteName := "projects/" + noteProjectID + "/notes/" + noteID
	occProjectName := "projects/" + occProjectID

	req := &grafeaspb.CreateOccurrenceRequest{
		Parent: occProjectName,
		Occurrence: &grafeaspb.Occurrence{
			NoteName: noteName,
			// 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)
}

获取特定备注的所有事件

您可以使用 notes.occurrences.list() 查看客户项目中特定漏洞的所有事件。

IAM 权限:

要执行此项任务,您必须拥有以下 IAM 权限

  • 您的项目的 containeranalysis.notes.listOccurrences 权限

也可以授予以下预定义的 IAM 角色,该角色将自动提供所有必要的权限:

  • 您的项目的 Container Analysis 事件查看者角色

要获取某一备注对应的所有事件,请按如下所述操作:

API

要列出某一备注对应的所有事件,请按如下方式发送 GET 请求:

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

如需了解完整的详细信息,请参阅 projects.notes.occurrences.list API 端点。

Java

如需了解如何安装和使用 Container Registry 客户端库,请参阅 Container Registry 客户端库。如需了解详情,请参阅 Container Registry Java API 参考文档

/**
 * 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

如需了解如何安装和使用 Container Registry 客户端库,请参阅 Container Registry 客户端库。如需了解详情,请参阅 Container Registry Go API 参考文档

// 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) {
	noteName := "projects/" + projectID + "/notes/" + noteID

	req := &grafeaspb.ListNoteOccurrencesRequest{Name: noteName}
	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
}

后续步骤

  • 如需了解如何查看、过滤和获取关于 Container Registry 映像漏洞的通知,请参阅获取映像漏洞
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Container Registry