排查Zap Docker镜像认证API扫描404/403错误问题

一、排查ZAP认证配置是否生效 #

1. 检查替换规则配置 #

确保options.prop中的Authorization头替换规则正确，GitHub令牌的前缀是token而非Bearer，正确配置示例：

replacer.full_list(0).description=GitHub Auth Token
replacer.full_list(0).enabled=true
replacer.full_list(0).matchtype=REQ_HEADER
replacer.full_list(0).matchstring=Authorization
replacer.full_list(0).replacement=token ghp_your_valid_token

误写前缀是导致403的常见原因。

2. 开启调试日志验证请求 #

在扫描命令中添加-d参数开启调试模式，查看Zap发送的请求头是否包含正确的Authorization字段：

docker run -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-weekly zap-api-scan.py -t openapi.json -f openapi -z "-config /zap/wrk/options.prop" -r report_html.html -d

搜索日志中的Authorization关键字，确认其值与Postman中使用的完全一致。

3. 容器内手动测试请求 #

进入Zap容器，用curl直接测试私有端点，排除容器网络或环境问题：

# 获取容器ID
docker ps
# 进入容器
docker exec -it <container_id> /bin/bash
# 测试私有仓库端点
curl -H "Authorization: token ghp_your_valid_token" https://api.github.com/repos/your-username/your-private-repo

如果curl返回正常，说明问题出在Zap的配置或扫描逻辑；如果curl也返回403，检查令牌权限或GitHub的限制。

二、GitHub API的特殊限制排查 #

1. OpenAPI定义的路径参数问题 #

GitHub的OpenAPI定义包含大量参数化路径（如/repos/{owner}/{repo}），Zap可能未正确替换这些参数，导致请求不存在的路径（404）。解决方法：

• 手动修改openapi.json，将参数化路径替换为实际的私有仓库路径（如/repos/your-username/your-private-repo）后再扫描。
• 扫描时用-P参数指定参数值：

  docker run -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-weekly zap-api-scan.py -t openapi.json -f openapi -z "-config /zap/wrk/options.prop" -P owner=your-username -P repo=your-private-repo -r report_html.html
  

2. 令牌权限与速率限制 #

• 确认GitHub令牌拥有repo权限（针对私有仓库）：进入GitHub设置→开发者设置→个人访问令牌，检查权限列表。
• 检查速率限制：查看Zap返回的响应头，若包含X-RateLimit-Remaining: 0，说明触发了速率限制，需等待或使用更高权限的令牌。

三、替代测试API推荐 #

如果GitHub API的限制难以绕过，可以用以下API测试Zap的认证扫描功能：

• JSONPlaceholder：免费公开的模拟API，支持RESTful操作，可用于基础扫描测试；若需认证场景，可自行部署带认证的私有版本。
• Swagger Petstore：官方提供的测试API，带有完整的OpenAPI定义，支持API Key认证，适合练手。
• 本地Mock服务器：用json-server或mockoon搭建本地API，自定义认证规则（如Bearer令牌），完全可控，适合复杂场景测试。

内容的提问来源于stack exchange，提问作者Anagha Ms