通过 NeuVector API 获取镜像扫描状态

在 CI/CD 流水线中，通常会通过 Jenkins 插件等方式触发 NeuVector 的镜像扫描。扫描完成后，可以在 NeuVector UI 页面中确认扫描结果已成功写入系统。

由于镜像扫描本身会消耗一定的时间和资源（尤其是镜像体积较大时，扫描耗时会明显增加），因此在流水线中往往希望在镜像已经完成扫描的情况下避免重复触发扫描任务，以提升整体执行效率。

基于 NeuVector v5.4.8 版本，可以通过以下 API 判断指定镜像是否已经完成扫描：

/v1/scan/registry/{registryName}/images
/v1/scan/registry/_repo_scan/images

---

检查通过 NV Registries UI 扫描的镜像

下面示例用于检查 通过 NeuVector Registries UI 触发扫描 的镜像是否已存在扫描结果。

_controllerIP_=10.43.62.240
_controllerRESTAPIPort_=10443
_TOKEN_='xxx'
_registryName_=Harbor_Library_Nginx
_repository_=library/nginx
_tag_=mainline

curl -k -G "https://$_controllerIP_:$_controllerRESTAPIPort_/v1/scan/registry/$_registryName_/images" \
     -H "X-Auth-Apikey: $_TOKEN_" \
     --data-urlencode "f_repository=in,$_repository_" \
     --data-urlencode "f_tag=eq,$_tag_"

返回示例（已扫描）

{
  "images": [
    {
      "author": "",
      "base_os": "debian:13",
      "created_at": "2025-10-07T21:06:46Z",
      "critical": 0,
      "cvedb_create_time": "",
      "digest": "sha256:df2ff23047d975130cd6395465eca8730df85529056dd82761cb79d0cfc644f7",
      "domain": "",
      "envs": null,
      "high": 27,
      "image_id": "07ccdb7838758e758a4d52a9761636c385125a327355c0c94a6acff9babff938",
      "labels": {
        "maintainer": "NGINX Docker Maintainers <docker-maint@nginx.com>"
      },
      "layers": [],
      "medium": 56,
      "repository": "library/nginx",
      "result": "succeeded",
      "run_as_root": true,
      "scanned_at": "2025-12-20T00:02:37Z",
      "scanned_timestamp": 1766188957,
      "scanner_version": "4.017",
      "size": 159950606,
      "status": "finished",
      "tag": "mainline"
    }
  ]
}

返回示例（未扫描）

{
  "images": []
}

---

检查通过 CI 扫描的镜像

以下示例用于检查 通过 CI 流水线触发扫描 的镜像扫描状态。

_controllerIP_=10.43.62.240
_controllerRESTAPIPort_=10443
_TOKEN_='xxx'
_repository_=library/nginx
_tag_=mainline

# 注意：请求路径中的 _repo_scan 为固定值，不可修改
curl -k -G "https://$_controllerIP_:$_controllerRESTAPIPort_/v1/scan/registry/_repo_scan/images" \
  -H "X-Auth-Apikey: $_TOKEN_" \
  --data-urlencode "f_repository=in,$_repository_" \
  --data-urlencode "f_tag=eq,$_tag_"

---

通过 Digest 精确确认扫描状态

在存在多个仓库、且镜像名称与标签相同（repository/image:tag 相同）的场景下，建议使用 镜像 digest 来准确判断是否已完成扫描。

_controllerIP_=10.43.62.240
_controllerRESTAPIPort_=10443
_TOKEN_='xxx'
_digest_='sha256:yyy'

curl -k -G "https://$_controllerIP_:$_controllerRESTAPIPort_/v1/scan/registry/_repo_scan/images" \
  -H "X-Auth-Apikey: $_TOKEN_" \
  --data-urlencode "f_digest=$_digest_"

---

通过以上方式，即可在 CI/CD 流水线中根据接口返回结果判断镜像是否已完成扫描，从而决定是否需要再次触发 NeuVector 的镜像扫描任务。