veracode/api-signing

Veracode API Signing Docker镜像文档

镜像概述与主要用途

Veracode API Signing Docker镜像用于为Veracode API请求生成基于哈希的消息认证码（HMAC）签名，以确保安全访问Veracode API资源。该镜像基于Python官方Docker镜像构建，提供两种变体，分别适用于需要shell环境的场景（如流水线）和直接通过命令行调用API的场景。通过使用此镜像，用户可在客户端生成HMAC签名，避免明文传输凭据，同时确保请求的完整性和防篡改性。

核心功能与特性

安全特性

• 凭据安全传输：API密钥不会明文传输，而是在客户端加密生成HMAC，仅在服务端解密验证。
• 消息完整性验证：HMAC签名可验证请求在传输过程中是否被篡改，任何修改都会导致签名失效。
• 防重放***：签名包含一次性随机数（nonce），有效防止重放***。
• 凭据可撤销性：支持撤销和重新生成API凭据，以应对凭据泄露风险。

镜像特性

• 两种变体：提供环境变体（带shell）和命令变体（直接运行http命令）。
• 基于Python官方镜像：确保基础环境的稳定性和安全性。
• 非特权用户运行：默认以非特权本地用户身份运行容器，降低安全风险。

使用场景与适用范围

• CI/CD流水线集成：如GitLab流水线，通过镜像提供的shell环境执行API请求。
• 命令行API调用：直接通过http命令（结合veracode_hmac认证）调用Veracode API。
• Shell别名简化操作：通过shell别名将容器命令映射为本地可执行命令，简化日常使用。

镜像详情

变体说明

veracode/api-signing（环境变体）

• 用途：提供shell环境，适用于流水线或需要交互式shell的场景。
• 标签：latest标签默认指向此变体。

veracode/api-signing:cmd（命令变体）

• 用途：直接运行http命令（带veracode_hmac认证），适用于通过shell别名快速调用API的场景。

使用方法

1. 作为环境运行（环境变体）

在GitLab流水线中使用

适用于需要在流水线中执行API请求的场景。需预先将Veracode API凭据设置为项目或组变量（VERACODE_API_KEY_ID和VERACODE_API_KEY_SECRET）。

yaml
# 此任务假设Veracode API凭据已设置为组或项目变量，变量名分别为VERACODE_API_KEY_ID和VERACODE_API_KEY_SECRET
check_credentials:
    image: veracode/api-signing
    script:
      - http --auth-type veracode_hmac https://api.veracode.com/api/authn/v2/api_credentials

本地shell环境

将当前主机目录挂载到容器内，以非特权用户身份运行交互式shell：

bash
docker run -it --rm -v $PWD:/home/luser veracode/api-signing /bin/bash

自定义用户与工作目录

默认以非特权用户在/home/luser目录运行，可通过--user和--workdir参数覆盖默认配置：

bash
# 以root用户运行
docker run -it --rm --user root veracode/api-signing /bin/bash

# 修改工作目录
docker run -it --rm --workdir /my/app/path veracode/api-signing /bin/bash

# 同时自定义用户和工作目录
docker run -it --rm --user root --workdir /my/app/path veracode/api-signing /bin/bash

2. 作为命令运行（命令变体）

通过veracode/api-signing:cmd变体直接执行http命令，结合veracode_hmac认证调用Veracode API。

使用凭据文件

将Veracode凭据文件（路径通常为~/.veracode/credentials）挂载到容器内，用于API认证：

bash
# 获取当前API凭据信息
docker run -it --rm \
    -v ~/.veracode/credentials:/home/luser/.veracode/credentials \
    veracode/api-signing:cmd \
        https://api.veracode.com/api/authn/v2/api_credentials

# 查询应用列表（指定应用名称）
docker run -it --rm \
    -v ~/.veracode/credentials:/home/luser/.veracode/credentials \
    veracode/api-signing:cmd \
        https://api.veracode.com/appsec/v1/applications \
        name==veracode-api-signing

使用环境变量

通过环境变量VERACODE_API_KEY_ID和VERACODE_API_KEY_SECRET传递凭据，无需挂载文件：

bash
docker run -it --rm \
    --env VERACODE_API_KEY_ID=c2db7664... \  # 替换为实际API Key ID
    --env VERACODE_API_KEY_SECRET=24f62c81... \  # 替换为实际API Key Secret
    veracode/api-signing:cmd \
        https://api.veracode.com/appsec/v1/applications \
        business_unit==Product%20Security  # 查询指定业务单元的应用

通过Shell别名简化操作

将容器命令映射为本地shell别名，实现类似本地可执行程序的使用体验：

bash
# 设置别名（需根据实际凭据文件路径调整）
alias 'veracode-http'='docker run -it --rm -v $PWD:/home/luser -v ~/.veracode/credentials:/home/luser/.veracode/credentials veracode/api-signing:cmd'

# 使用别名调用API
veracode-http --help  # 查看帮助
veracode-http https://api.veracode.com/appsec/v1/applications name==MyApplication  # 查询指定名称的应用
veracode-http --pretty none --body https://api.veracode.com/api/authn/v2/api_credentials | jq '.expiration_ts'  # 提取凭据过期时间

配置参数与环境变量

参考资料

有关HMAC认证及API签名库的更多使用示例，请访问Veracode帮助中心。