ZAP API 调用需正确启动进程并配置端口、API key及scope：启动时加-config参数启用远程API，Python访问用127.0.0.1:8080并传params={'apikey'}；需显式管理session、context与认证；spider/ascan前须排除无关域名并严格正则限定scope；alerts()需分页获取，message(id)取原始流量，htmlreport更完整。
ZAP API 调用必须启用并验证端口与 API key
ZAP 默认不开放远程 API，直接调用 zap.urlopen() 或发 HTTP 请求会返回 403 或连接拒绝。核心不是“怎么写 Python 脚本”，而是 ZAP 进程本身是否以正确参数启动。
- 启动 ZAP 时务必加
-config api.addrs.addr.name=.* -config api.addrs.addr.regex=true -config api.key=yourkey123，否则 Python 侧再怎么配 URL 都连不上 - Python 中访问地址必须是
http://127.0.0.1:8080（默认端口），不能用localhost—— 某些容器或 hosts 配置下 DNS 解析会导致 API key 校验失败 - API key 必须和启动参数里的一致，且需通过
requests的params传入，例如：params={'apikey': 'yourkey123'}，放在 header 或 body 都无效
Python zap-api-python 库的 session 管理容易断连
官方 zap-api-python 库封装了基础调用，但它不自动维护 ZAP 的 active scan session 或 context 生命周期。常见现象是：前几步正常，跑着跑着 scan_id 返回 -1 或 AssertionError: No scan ID returned。
- 每次发起 active scan 前，先用
zap.core.new_session()显式新建会话，避免旧 session 数据干扰 - 如果要复用 context（比如带登录脚本的认证测试），必须用
zap.authentication.set_authentication_method()+zap.authentication.set_logged_in_out_urls()配好，且确保 context 已通过zap.context.include_in_context()加入 - 不要依赖库的默认超时；ZAP 扫描可能卡住，建议对
zap.ascan.status(scan_id)加timeout=60和重试逻辑，否则 Python 进程会挂起
爬虫范围控制不当导致扫描超出预期域名
ZAP 的 spider 和 ascan 默认基于“初始 URL”做同源策略推导，但 Python 脚本里若只传一个 https://dev.example.com/login，它可能顺藤摸瓜扫到 https://api.example.com 甚至 https://staging.example.net —— 尤其当页面里有跨域 JS 请求或跳转时。
- 务必在启动 spider 前，用
zap.spider.exclude_from_scan(r'https?://.*\.internal.*')排除内网或无关域名 - 设置严格 scope：先
zap.context.new_context('test')，再zap.context.include_in_context('test', r'^https://prod\.example\.com/.*$')，正则必须以^和$边界限定 - 避免用
zap.spider.scan()的url参数传带 query 的地址（如?token=xxx），ZAP 可能将其当作不同路径反复爬取；应先 login 再 set context scope
报告导出为 JSON 时字段缺失或结构嵌套过深
zap.core.alerts() 返回的 JSON 看似完整，但实际漏掉 request/response 原始内容、HTTP headers、甚至部分 risk 字段——这是 ZAP 的设计限制，不是 Python 脚本没写对。
立即学习“Python免费学习笔记（深入）”；
- 要用
zap.core.alerts(baseurl='', riskid='', start=0, count=1000)手动分页拉取，ZAP 默认只返回前 50 条 - 真正带原始流量数据的接口是
zap.core.message(id)，但 id 需从alerts()结果里的messageId字段取，不是alertId - 导出 HTML 报告更可靠：
zap.core.htmlreport()返回的是完整字符串，可直接写入文件；JSON 报告建议仅用于轻量级统计，别指望它覆盖所有审计细节
ZAP 和 Python 的集成关键不在语法，而在于对 ZAP 进程状态、scope 边界、API 认证链路的理解。漏掉任一环，脚本都可能“看似运行成功”，实则没扫到目标、没拿到数据、或扫了不该扫的地方。
