Kubescape HTTP Handler 实战指南用 REST API 将 Kubernetes 安全扫描嵌入 CI/CD 与自动化平台【免费下载链接】kubescapeKubescape is an open-source Kubernetes security platform for your IDE, CI/CD pipelines, and clusters. It includes risk analysis, security, compliance, and misconfiguration scanning, saving Kubernetes users and administrators precious time, effort, and resources.项目地址: https://gitcode.com/GitHub_Trending/ku/kubescape导读Kubescape 不仅是一个命令行扫描工具还内置了一个可独立部署的 HTTP Handler服务端模块当以服务形式运行时它会在8080端口启动 Web 服务器对外暴露一套 REST API用于以编程方式触发安全扫描、拉取扫描结果、查询扫描状态以及管理缓存结果。本文以仓库中的 httphandler/README.md 为骨架结合 httphandler 目录下的源码与部署示例完整讲解四个核心 API 的请求/响应契约、请求体字段、全部环境变量、优雅停机语义、pprof 性能剖析以及微服务与 Prometheus 两种落地部署方式。读完本文你将能独立部署 Kubescape 扫描服务并把扫描即 API的能力接入 CI/CD 流水线、自定义仪表盘和定时巡检任务。Overview服务化扫描的整体形态当 Kubescape 以服务Server模式运行时它不再是一次性执行的 CLI 进程而是一个常驻的 Web 服务。从入口 httphandler/main.go 可以看到服务启动后会依次完成配置加载config.LoadConfig(/etc/config)、凭据加载、服务发现SaaS 后端接线、存储初始化最终调用listener.SetupHTTPListener(ctx)拉起 HTTP 监听。在 httphandler/listener/setup.go 中路由注册清晰地划分了三个边界健康检查无鉴权GET /livez与GET /readyz供 kubelet 探活使用因此刻意不设鉴权OpenAPI 文档GET /docs前缀下的 OpenAPI UI核心业务 API/v1/*包括扫描触发、状态查询、结果获取与删除以及 Prometheus 指标端点。完整的/v1路由如下见 setup.go方法路径说明POST/v1/scan触发一次扫描异步/同步DELETE/v1/scan取消正在排队或执行的扫描GET/v1/status查询扫描是否仍在进行GET/v1/results获取扫描结果DELETE/v1/results删除缓存的扫描结果GET/v1/metricsPrometheus 指标标记为 deprecated端口默认8080可通过KS_PORT环境变量覆盖见 setup.go。服务支持通过KS_CERT_FILE/KS_KEY_FILE配置 TLS 证书对内网启用 HTTPS两者必须同时设置。优雅停机Graceful Shutdown生产环境中最容易忽略的细节是停机行为。HTTP Handler 在收到SIGTERM或SIGINT后不会立刻杀进程而是执行一套分阶段的优雅停机协议停止接收新连接与新扫描服务关闭 admission准入正在解析阶段的扫描请求包括 metrics 扫描会收到503 Service Unavailable排空已接受扫描最长 20 秒已入队的扫描会继续执行完包括结果处理与持久化取消剩余扫描超过排空窗口仍未完成的扫描会复用与DELETE /v1/scan相同的取消机制context 取消终止等待 worker 退出成功的停机必须等到扫描 worker 完全退出如果 HTTP 排空与 worker 退出在25 秒内未完成停机会报错、关闭剩余连接并在尝试一次 OpenTelemetry flush额外最多 5 秒后以失败状态退出——该失败路径不保证持久化Completion 回调不参与 worker-join 保证回调仍保持原有的 best-effort 语义。上述常量在 listener/setup.go 中定义为scanDrainPeriod 20 * time.Second与applicationShutdownTimeout 25 * time.Second停机编排逻辑实现在serveUntilShutdown见 setup.go。worker 侧的排空/取消逻辑见 requestshandler.go 的BeginShutdown与Shutdown。实践提示文档明确建议根据自身负载合理设置 Pod 的terminationGracePeriodSeconds否则 Kubernetes 可能在清理完成前强制终止进程。仓库自带的部署清单 ks-deployment.yaml 给出的参考值是35s25 秒停机 5 秒遥测 调度余量。API Reference四个核心端点POST /v1/scan —— 触发扫描扫描默认异步执行请求立即返回一个 scan ID扫描在后台队列中执行。Query 参数参数类型默认值说明waitboolfalse是否等待扫描完成同步模式keepboolfalse返回后是否在缓存中保留结果skipPersistenceboolfalse扫描后不持久化数据callbackstring-扫描完成信号回调 URL仅携带 scan ID结果仍需GET /v1/results获取说明skipPersistence与callback在 README 参数表中未列出但它们真实存在于 requestparser.go 的ScanQueryParams结构中是同步扫描与事件驱动集成的有用补充。异步响应示例{ id: scan-12345, type: busy, response: scanning in progress }同步响应waittrue与GET /v1/results的响应一致直接返回结果对象。背压与限流服务接受有界数量的排队扫描。从源码看requestshandler.go 定义了defaultScanQueueCapacity 10与defaultMaxScanRequestBodyBytes 1 MiB分别对应环境变量KS_SCAN_QUEUE_CAPACITY和KS_SCAN_REQUEST_MAX_BYTES。行为包括队列满时返回429 Too Many Requests并携带Retry-After响应头源码中固定为1秒见 requestshandler.go请求体超过配置上限时在扫描被准入之前即返回413 Request Entity Too Large通过http.MaxBytesReader实现见 requestshandler.go停机期间的新扫描请求返回503 Service Unavailable。取消扫描DELETE /v1/scan虽然 README 的 API 参考未单列但源码与路由表都支持该端点。带id参数取消指定扫描不带则取消正在运行的用户扫描无进行中扫描时返回404成功则返回type: notBusy的响应见 requestshandler.go。GET /v1/results —— 获取结果Query 参数参数类型默认值说明idstring-扫描 ID为空时返回最新一次扫描结果keepboolfalse返回后是否在缓存中保留结果响应成功{ id: scan-12345, type: v1results, response: { /* scan results object */ } }响应错误{ id: scan-12345, type: error, response: error message }响应进行中{ id: scan-12345, type: busy, response: scanning in progress }源码层面的行为细节见 requestshandler.go 的validateScanID与GetResults在线非 offline模式下id为空会被视为参数错误返回400offline 模式下才回退到最新用户扫描请求的扫描仍在进行时返回type: busy结果文件不存在时返回204 No Content扫描执行失败时服务会把错误明文写入FailedOutputDir此时GetResults返回500且response为真正的失败原因ScanFailedError而不是 JSON 解析错误见 requestshandlerutils.go默认情况下结果在返回后被删除keepfalse但最新扫描回退场景刻意保留结果以防误删。GET /v1/status —— 检查状态适合轮询场景只查状态不拉取完整结果开销更小。Query 参数参数类型默认值说明idstring-扫描 ID为空时检查是否有任意扫描在进行响应进行中{ id: scan-12345, type: busy, response: scanning in progress }响应完成{ id: scan-12345, type: notBusy, response: scanning completed }注意一个细节id为空时服务会先解析为最新用户扫描再判断其是否忙碌——这是为了避免/v1/metrics抓取覆盖 latestID 导致状态误报见 requestshandler.go。DELETE /v1/results —— 删除缓存结果Query 参数参数类型默认值说明idstring-要删除的扫描 ID为空时删除最新结果allboolfalse删除全部缓存结果alltrue时清空OutputDir与FailedOutputDir两个目录见 requestshandler.go。removeResultsFile在删除时不仅清理无扩展名的规范 JSON 文件还会按json/junit/sarif/html/pdf/prometheus/yaml/csv/cyclonedx/spdx等打印器扩展名逐一清理伴生文件见 requestshandlerutils.go。Request / Response Objects请求体与响应对象详解Trigger Scan Object扫描请求体{ format: json, excludedNamespaces: [kube-system, kube-public], includeNamespaces: [production, staging], useCachedArtifacts: false, keepLocal: true, targetType: framework, targetNames: [nsa, mitre] }字段类型说明formatstring输出格式默认jsonexcludedNamespaces[]string扫描时要排除的命名空间includeNamespaces[]string扫描时要包含的命名空间useCachedArtifactsbool使用本地缓存的策略工件离线模式keepLocalbool不把结果提交到后端SaaStargetTypestringframework或controltargetNames[]string要扫描的框架/控制项名称从 datastructuremethods.go 的ToScanInfo可以补充以下语义targetType为framework时targetNames中含all或空串会触发全框架扫描targetType为control时只扫描指定控制项未知类型则回退为全量扫描useCachedArtifactstrue等价于让扫描从getter.DefaultLocalStore读取工件避免每次扫描都联网下载策略请求体还支持源码中实现的submit显式提交结果到 SaaS、hostScanner启用主机扫描器、scanObject单资源扫描、exceptions内联异常策略服务会将其临时落盘并在扫描后清理等字段请求体中的命名空间列表会被strings.Join为逗号分隔字符串后交给ScanInfo与KS_EXCLUDE_NAMESPACES/KS_INCLUDE_NAMESPACES环境变量同样处理。安全边界account/accessKey会被忽略。这些端点无鉴权因此服务永远不会从请求体中读取 Kubescape SaaS 身份——否则任何调用者都能把扫描结果可能包含集群 Secret 与 RBAC 数据重定向到其控制的账号。身份只来自服务端自身配置KS_ACCOUNT_ID/KS_ACCESS_KEY或启动时从凭据文件加载的 credentials见 datastructuremethods.go 与 main.go 的loadAndSetCredentials。请求体仍接受这些字段仅为向后兼容实际不产生任何效果。Response Object统一响应对象{ id: scan-12345, type: v1results, response: { /* payload */ } }字段类型说明idstring扫描标识typestring响应类型见下表responseany响应载荷响应类型Response Types类型说明v1results扫描结果对象busy扫描进行中notBusy无扫描进行中ready扫描完成结果就绪error发生错误API Examples可直接复制的实战命令1. 基础异步扫描三连触发 → 轮询 → 拉结果# 1. 触发扫描 curl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa]} # 2. 检查状态 curl http://127.0.0.1:8080/v1/status # 3. 获取结果 curl http://127.0.0.1:8080/v1/results -o results.json2. 同步扫描一次调用直接拿到结果curl -X POST http://127.0.0.1:8080/v1/scan?waittrue \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa]} \ -o results.json同步模式非常适合 CI 门禁waittrue会阻塞直到扫描完成并返回完整结果此时 HTTP 请求可能持续数分钟——这正是 setup.go 中刻意不设置ReadTimeout/WriteTimeout的原因只设置ReadHeaderTimeout: 10s防御 slowloris。3. 只扫描指定命名空间curl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d { includeNamespaces: [production], targetType: framework, targetNames: [nsa, mitre] }4. 账号集成在服务端配置而非每次请求携带账号与访问密钥配置在服务端而不是随请求发送原因见上文安全边界说明# 在服务端 / Helm values 中配置 export KS_ACCOUNT_IDYOUR-ACCOUNT-ID export KS_ACCESS_KEYYOUR-ACCESS-KEYcurl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d { submit: true, targetType: framework, targetNames: [nsa] }5. 删除全部缓存结果curl -X DELETE http://127.0.0.1:8080/v1/results?alltrue6. 取消进行中的扫描# 取消指定扫描也支持不带 id 取消当前运行中的扫描 curl -X DELETE http://127.0.0.1:8080/v1/scan?idscan-123457. 事件驱动扫描完成回调callback参数允许服务在扫描完成时向指定 URL POST 一个仅含id与status的信号{id:...,status:completed|failed}接收方需再通过GET /v1/results拉取数据。回调默认关闭防止服务被当作任意出站请求发射器需设置KS_CALLBACK_ENABLEDtrue或配置KS_CALLBACK_ALLOWED_CIDRS白名单才可用投递为 at-least-once、best-effort接收方应基于 ID 去重并保留轮询兜底详见 requestshandlerutils.go。Environment Variables完整环境变量参考HTTP Handler 的所有行为都由环境变量控制。除 README 列出的变量外下表同时整合了 main.go、setup.go 与 requestshandlerutils.go 中实际读取的全部变量变量说明示例KS_ACCOUNT_ID每次扫描使用的 Kubescape SaaS 账号 IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxKS_ACCESS_KEY每次扫描使用的 Kubescape SaaS 访问密钥your-access-keyKS_EXCLUDE_NAMESPACES默认排除的命名空间逗号分隔kube-system,kube-publicKS_INCLUDE_NAMESPACES默认包含的命名空间逗号分隔production,stagingKS_FORMAT默认输出格式jsonKS_FORMAT_VERSION输出格式版本v2KS_LOGGER_NAMELogger 名称kubescapeKS_LOGGER_LEVEL日志级别info,debug,warning,errorKS_DOWNLOAD_ARTIFACTS每次扫描是否下载策略工件false时从本地缓存加载true,falseKS_SCAN_QUEUE_CAPACITY活动扫描之后最多排队的扫描数默认1010KS_SCAN_REQUEST_MAX_BYTESPOST /v1/scan请求体最大字节数默认1048576即 1 MiB1048576KS_PPROF_ENABLED启用 pprof 调试服务默认关闭仅绑定回环地址true,falseKS_PPROF_ADDR启用时 pprof 调试服务的绑定地址127.0.0.1:6060KS_API_TOKEN/v1/*API 的 Bearer Token 鉴权可选默认关闭。设置后每个/v1/scan、/v1/results、/v1/status请求都必须携带Authorization: Bearer token否则返回401健康探针/livez、/readyz与 OpenAPI 文档保持开放。若将:8080暴露到集群之外建议设置随机值并启用 TLSKS_CERT_FILE/KS_KEY_FILE或使用 TLS 终结的 Ingressopenssl rand -hex 32生成KS_PORTHTTP 监听端口默认80808080KS_CERT_FILE/KS_KEY_FILETLS 证书与私钥路径须成对设置/etc/tls/tls.crtKS_OFFLINEtrue时强制离线模式使用本地工件缓存trueKS_CONTEXT集群上下文名称my-clusterKS_KEEP_LOCAL不向 Kubescape SaaS 提交结果trueKS_SUBMIT显式开启结果提交存在即生效解析失败会告警并忽略trueKS_REGO_PRINT打印 rego 规则falseKS_ENABLE_HOST_SCANNER启用主机扫描器trueKS_HOST_SCAN_YAML主机扫描 YAML 路径/path/to/host-scan.yamlKS_CALLBACK_ENABLED开启扫描完成回调默认关闭trueKS_CALLBACK_ALLOWED_CIDRS回调目标 IP 白名单逗号分隔 CIDR配置后即视为开启回调10.0.0.0/8KS_SERVICE_DISCOVERY_FILE_PATH文件式服务发现路径默认/etc/config/services.json支持 sidecar 与私有集群注入后端端点/etc/config/services.jsonKS_CREDENTIALS_SECRET_PATH凭据文件路径默认/etc/credentials/etc/credentials鉴权细节源码佐证bearerAuthMiddleware使用subtle.ConstantTimeCompare做常数时间比较以防时序侧信道并接受大小写不敏感的Bearer方案见 setup.go。鉴权是增量式加固扫描 API 默认开放以保证集群内既有安装不因升级而中断这与默认关闭的 pprof 不同见 setup.go。Deployment Examples两种典型落地方式方式一微服务部署API 驱动扫描在集群内将 Kubescape 部署为微服务通过 REST API 驱动扫描是 CI/CD 集成、自定义仪表盘和自动化编排的基础形态。快速部署kubectl apply -f httphandler/examples/microservice/ks-deployment.yaml部署清单 ks-deployment.yaml 已经内置了完整资源kubescape命名空间、kubescape-discoveryServiceAccount、具有get/list/describe全资源权限的 ClusterRole 与绑定、NodePort 类型 Service以及 Deploymentquay.io/kubescape/kubescape:latest启动命令ksserver。其中值得关注的默认配置terminationGracePeriodSeconds: 35与优雅停机协议匹配/livez与/readyz健康探针每 3 秒一次初始延迟 3 秒KS_ENABLE_HOST_SCANNERtrue启用主机扫描器KS_DOWNLOAD_ARTIFACTStrue每次扫描都下载最新策略工件。验证与访问# 检查 Pod 状态 kubectl get pods -l appkubescape # 检查 Service kubectl get svc kubescape # 本地端口转发访问 kubectl port-forward svc/kubescape 8080:8080 # 或获取 LoadBalancer 外部 IP若修改 serviceType kubectl get svc kubescape -o jsonpath{.status.loadBalancer.ingress[0].ip}部署前应结合集群实际调整serviceTypeClusterIP / NodePort / LoadBalancer、命名空间、资源配额、ServiceAccount 权限。完整部署指南见 httphandler/examples/microservice/README.md。典型 CI 门禁脚本来自微服务示例文档同步扫描后提取合规分数低于阈值即让流水线失败#!/bin/bash RESULT$(curl -s --header Content-Type: application/json \ --request POST \ --data {targetType: framework, targetNames: [nsa]} \ http://kubescape:8080/v1/scan?waittrue) # 提取合规分数 SCORE$(echo $RESULT | jq .response.summaryDetails.complianceScore) # 分数低于阈值则失败 if (( $(echo $SCORE 80 | bc -l) )); then echo Compliance score $SCORE is below threshold (80) exit 1 fi定时扫描 CronJob每 6 小时触发一次 NSA 与 MITRE 框架扫描apiVersion: batch/v1 kind: CronJob metadata: name: kubescape-scheduled-scan spec: schedule: 0 */6 * * * # 每 6 小时 jobTemplate: spec: template: spec: containers: - name: scanner image: curlimages/curl command: - /bin/sh - -c - | curl -X POST http://kubescape:8080/v1/scan \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa, mitre]} restartPolicy: OnFailure大集群超时建议异步触发 轮询而不是长阻塞的同步调用# 触发扫描立即返回 curl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa]} # 轮询状态 while true; do STATUS$(curl -s http://127.0.0.1:8080/v1/status | jq -r .type) if [ $STATUS ! busy ]; then break fi sleep 10 done # 获取结果 curl http://127.0.0.1:8080/v1/results -o results.json方式二Prometheus 集成指标暴露将 Kubescape 指标暴露给 Prometheus 抓取可把安全态势接入现有可观测体系。指标端点挂载在/v1/metrics带鉴权与 OpenTelemetry 中间件见 setup.go实现在 prometheus.go。抓取方式与 ServiceMonitor 配置请参考 httphandler/examples/prometheus/README.md。Debugging调试与性能剖析开启调试日志export KS_LOGGER_LEVELdebug源码中日志级别通过logger.L().SetLevel(...)应用级别字符串无效时回退到debug并记录错误见 main.go。pprof 性能剖析pprof 调试服务默认关闭且只绑定127.0.0.1因此只能从 Pod 自身的网络命名空间内访问无法从网络直接触达这是刻意的安全设计——历史上它曾因日志级别为 debug 而默认暴露未鉴权的剖析端点见 setup.go 的注释。启用后通过kubectl port-forward访问export KS_PPROF_ENABLEDtrue # 然后例如kubectl port-forward pod 6060:6060 # 堆剖析 go tool pprof http://127.0.0.1:6060/debug/pprof/heap # CPU 剖析采样 30 秒 go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds30 # Goroutine 剖析 go tool pprof http://127.0.0.1:6060/debug/pprof/goroutine若6060端口与 Pod 内 sidecar 冲突可用KS_PPROF_ADDR修改绑定地址如KS_PPROF_ADDR127.0.0.1:6061。绑定到非回环地址属于刻意的显式选择仅在可信网络上才应这样做。pprof 处理器注册在独立 mux 上而非http.DefaultServeMux保证该依赖自包含且由编译器强制见 setup.go。相关文档CLI ReferenceArchitectureGetting Started GuideTroubleshootingMicroservice Deployment GuidePrometheus Integration Guide小结Kubescape HTTP Handler 将 Kubernetes 安全扫描包装为一组语义清晰、背压可控的 REST API配合优雅停机、可选的 Bearer 鉴权、pprof 剖析与完善的部署清单足以支撑从 CI 门禁到定时巡检的各类自动化场景。理解其请求/响应契约尤其busy/notBusy/v1results/error四种响应类型、环境变量矩阵与账号身份只来自服务端配置的安全边界是把它正确接入生产环境的关键。若需从源码层面继续深入可依次阅读 httphandler/listener/setup.go路由与停机、httphandler/handlerequests/v1/requestshandler.go四端点实现与 httphandler/handlerequests/v1/requestshandlerutils.go扫描执行与回调投递。【免费下载链接】kubescapeKubescape is an open-source Kubernetes security platform for your IDE, CI/CD pipelines, and clusters. It includes risk analysis, security, compliance, and misconfiguration scanning, saving Kubernetes users and administrators precious time, effort, and resources.项目地址: https://gitcode.com/GitHub_Trending/ku/kubescape创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kubescape HTTP Handler 实战指南：用 REST API 将 Kubernetes 安全扫描嵌入 CI/CD 与自动化平台
Kubescape HTTP Handler 实战指南用 REST API 将 Kubernetes 安全扫描嵌入 CI/CD 与自动化平台【免费下载链接】kubescapeKubescape is an open-source Kubernetes security platform for your IDE, CI/CD pipelines, and clusters. It includes risk analysis, security, compliance, and misconfiguration scanning, saving Kubernetes users and administrators precious time, effort, and resources.项目地址: https://gitcode.com/GitHub_Trending/ku/kubescape导读Kubescape 不仅是一个命令行扫描工具还内置了一个可独立部署的 HTTP Handler服务端模块当以服务形式运行时它会在8080端口启动 Web 服务器对外暴露一套 REST API用于以编程方式触发安全扫描、拉取扫描结果、查询扫描状态以及管理缓存结果。本文以仓库中的 httphandler/README.md 为骨架结合 httphandler 目录下的源码与部署示例完整讲解四个核心 API 的请求/响应契约、请求体字段、全部环境变量、优雅停机语义、pprof 性能剖析以及微服务与 Prometheus 两种落地部署方式。读完本文你将能独立部署 Kubescape 扫描服务并把扫描即 API的能力接入 CI/CD 流水线、自定义仪表盘和定时巡检任务。Overview服务化扫描的整体形态当 Kubescape 以服务Server模式运行时它不再是一次性执行的 CLI 进程而是一个常驻的 Web 服务。从入口 httphandler/main.go 可以看到服务启动后会依次完成配置加载config.LoadConfig(/etc/config)、凭据加载、服务发现SaaS 后端接线、存储初始化最终调用listener.SetupHTTPListener(ctx)拉起 HTTP 监听。在 httphandler/listener/setup.go 中路由注册清晰地划分了三个边界健康检查无鉴权GET /livez与GET /readyz供 kubelet 探活使用因此刻意不设鉴权OpenAPI 文档GET /docs前缀下的 OpenAPI UI核心业务 API/v1/*包括扫描触发、状态查询、结果获取与删除以及 Prometheus 指标端点。完整的/v1路由如下见 setup.go方法路径说明POST/v1/scan触发一次扫描异步/同步DELETE/v1/scan取消正在排队或执行的扫描GET/v1/status查询扫描是否仍在进行GET/v1/results获取扫描结果DELETE/v1/results删除缓存的扫描结果GET/v1/metricsPrometheus 指标标记为 deprecated端口默认8080可通过KS_PORT环境变量覆盖见 setup.go。服务支持通过KS_CERT_FILE/KS_KEY_FILE配置 TLS 证书对内网启用 HTTPS两者必须同时设置。优雅停机Graceful Shutdown生产环境中最容易忽略的细节是停机行为。HTTP Handler 在收到SIGTERM或SIGINT后不会立刻杀进程而是执行一套分阶段的优雅停机协议停止接收新连接与新扫描服务关闭 admission准入正在解析阶段的扫描请求包括 metrics 扫描会收到503 Service Unavailable排空已接受扫描最长 20 秒已入队的扫描会继续执行完包括结果处理与持久化取消剩余扫描超过排空窗口仍未完成的扫描会复用与DELETE /v1/scan相同的取消机制context 取消终止等待 worker 退出成功的停机必须等到扫描 worker 完全退出如果 HTTP 排空与 worker 退出在25 秒内未完成停机会报错、关闭剩余连接并在尝试一次 OpenTelemetry flush额外最多 5 秒后以失败状态退出——该失败路径不保证持久化Completion 回调不参与 worker-join 保证回调仍保持原有的 best-effort 语义。上述常量在 listener/setup.go 中定义为scanDrainPeriod 20 * time.Second与applicationShutdownTimeout 25 * time.Second停机编排逻辑实现在serveUntilShutdown见 setup.go。worker 侧的排空/取消逻辑见 requestshandler.go 的BeginShutdown与Shutdown。实践提示文档明确建议根据自身负载合理设置 Pod 的terminationGracePeriodSeconds否则 Kubernetes 可能在清理完成前强制终止进程。仓库自带的部署清单 ks-deployment.yaml 给出的参考值是35s25 秒停机 5 秒遥测 调度余量。API Reference四个核心端点POST /v1/scan —— 触发扫描扫描默认异步执行请求立即返回一个 scan ID扫描在后台队列中执行。Query 参数参数类型默认值说明waitboolfalse是否等待扫描完成同步模式keepboolfalse返回后是否在缓存中保留结果skipPersistenceboolfalse扫描后不持久化数据callbackstring-扫描完成信号回调 URL仅携带 scan ID结果仍需GET /v1/results获取说明skipPersistence与callback在 README 参数表中未列出但它们真实存在于 requestparser.go 的ScanQueryParams结构中是同步扫描与事件驱动集成的有用补充。异步响应示例{ id: scan-12345, type: busy, response: scanning in progress }同步响应waittrue与GET /v1/results的响应一致直接返回结果对象。背压与限流服务接受有界数量的排队扫描。从源码看requestshandler.go 定义了defaultScanQueueCapacity 10与defaultMaxScanRequestBodyBytes 1 MiB分别对应环境变量KS_SCAN_QUEUE_CAPACITY和KS_SCAN_REQUEST_MAX_BYTES。行为包括队列满时返回429 Too Many Requests并携带Retry-After响应头源码中固定为1秒见 requestshandler.go请求体超过配置上限时在扫描被准入之前即返回413 Request Entity Too Large通过http.MaxBytesReader实现见 requestshandler.go停机期间的新扫描请求返回503 Service Unavailable。取消扫描DELETE /v1/scan虽然 README 的 API 参考未单列但源码与路由表都支持该端点。带id参数取消指定扫描不带则取消正在运行的用户扫描无进行中扫描时返回404成功则返回type: notBusy的响应见 requestshandler.go。GET /v1/results —— 获取结果Query 参数参数类型默认值说明idstring-扫描 ID为空时返回最新一次扫描结果keepboolfalse返回后是否在缓存中保留结果响应成功{ id: scan-12345, type: v1results, response: { /* scan results object */ } }响应错误{ id: scan-12345, type: error, response: error message }响应进行中{ id: scan-12345, type: busy, response: scanning in progress }源码层面的行为细节见 requestshandler.go 的validateScanID与GetResults在线非 offline模式下id为空会被视为参数错误返回400offline 模式下才回退到最新用户扫描请求的扫描仍在进行时返回type: busy结果文件不存在时返回204 No Content扫描执行失败时服务会把错误明文写入FailedOutputDir此时GetResults返回500且response为真正的失败原因ScanFailedError而不是 JSON 解析错误见 requestshandlerutils.go默认情况下结果在返回后被删除keepfalse但最新扫描回退场景刻意保留结果以防误删。GET /v1/status —— 检查状态适合轮询场景只查状态不拉取完整结果开销更小。Query 参数参数类型默认值说明idstring-扫描 ID为空时检查是否有任意扫描在进行响应进行中{ id: scan-12345, type: busy, response: scanning in progress }响应完成{ id: scan-12345, type: notBusy, response: scanning completed }注意一个细节id为空时服务会先解析为最新用户扫描再判断其是否忙碌——这是为了避免/v1/metrics抓取覆盖 latestID 导致状态误报见 requestshandler.go。DELETE /v1/results —— 删除缓存结果Query 参数参数类型默认值说明idstring-要删除的扫描 ID为空时删除最新结果allboolfalse删除全部缓存结果alltrue时清空OutputDir与FailedOutputDir两个目录见 requestshandler.go。removeResultsFile在删除时不仅清理无扩展名的规范 JSON 文件还会按json/junit/sarif/html/pdf/prometheus/yaml/csv/cyclonedx/spdx等打印器扩展名逐一清理伴生文件见 requestshandlerutils.go。Request / Response Objects请求体与响应对象详解Trigger Scan Object扫描请求体{ format: json, excludedNamespaces: [kube-system, kube-public], includeNamespaces: [production, staging], useCachedArtifacts: false, keepLocal: true, targetType: framework, targetNames: [nsa, mitre] }字段类型说明formatstring输出格式默认jsonexcludedNamespaces[]string扫描时要排除的命名空间includeNamespaces[]string扫描时要包含的命名空间useCachedArtifactsbool使用本地缓存的策略工件离线模式keepLocalbool不把结果提交到后端SaaStargetTypestringframework或controltargetNames[]string要扫描的框架/控制项名称从 datastructuremethods.go 的ToScanInfo可以补充以下语义targetType为framework时targetNames中含all或空串会触发全框架扫描targetType为control时只扫描指定控制项未知类型则回退为全量扫描useCachedArtifactstrue等价于让扫描从getter.DefaultLocalStore读取工件避免每次扫描都联网下载策略请求体还支持源码中实现的submit显式提交结果到 SaaS、hostScanner启用主机扫描器、scanObject单资源扫描、exceptions内联异常策略服务会将其临时落盘并在扫描后清理等字段请求体中的命名空间列表会被strings.Join为逗号分隔字符串后交给ScanInfo与KS_EXCLUDE_NAMESPACES/KS_INCLUDE_NAMESPACES环境变量同样处理。安全边界account/accessKey会被忽略。这些端点无鉴权因此服务永远不会从请求体中读取 Kubescape SaaS 身份——否则任何调用者都能把扫描结果可能包含集群 Secret 与 RBAC 数据重定向到其控制的账号。身份只来自服务端自身配置KS_ACCOUNT_ID/KS_ACCESS_KEY或启动时从凭据文件加载的 credentials见 datastructuremethods.go 与 main.go 的loadAndSetCredentials。请求体仍接受这些字段仅为向后兼容实际不产生任何效果。Response Object统一响应对象{ id: scan-12345, type: v1results, response: { /* payload */ } }字段类型说明idstring扫描标识typestring响应类型见下表responseany响应载荷响应类型Response Types类型说明v1results扫描结果对象busy扫描进行中notBusy无扫描进行中ready扫描完成结果就绪error发生错误API Examples可直接复制的实战命令1. 基础异步扫描三连触发 → 轮询 → 拉结果# 1. 触发扫描 curl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa]} # 2. 检查状态 curl http://127.0.0.1:8080/v1/status # 3. 获取结果 curl http://127.0.0.1:8080/v1/results -o results.json2. 同步扫描一次调用直接拿到结果curl -X POST http://127.0.0.1:8080/v1/scan?waittrue \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa]} \ -o results.json同步模式非常适合 CI 门禁waittrue会阻塞直到扫描完成并返回完整结果此时 HTTP 请求可能持续数分钟——这正是 setup.go 中刻意不设置ReadTimeout/WriteTimeout的原因只设置ReadHeaderTimeout: 10s防御 slowloris。3. 只扫描指定命名空间curl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d { includeNamespaces: [production], targetType: framework, targetNames: [nsa, mitre] }4. 账号集成在服务端配置而非每次请求携带账号与访问密钥配置在服务端而不是随请求发送原因见上文安全边界说明# 在服务端 / Helm values 中配置 export KS_ACCOUNT_IDYOUR-ACCOUNT-ID export KS_ACCESS_KEYYOUR-ACCESS-KEYcurl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d { submit: true, targetType: framework, targetNames: [nsa] }5. 删除全部缓存结果curl -X DELETE http://127.0.0.1:8080/v1/results?alltrue6. 取消进行中的扫描# 取消指定扫描也支持不带 id 取消当前运行中的扫描 curl -X DELETE http://127.0.0.1:8080/v1/scan?idscan-123457. 事件驱动扫描完成回调callback参数允许服务在扫描完成时向指定 URL POST 一个仅含id与status的信号{id:...,status:completed|failed}接收方需再通过GET /v1/results拉取数据。回调默认关闭防止服务被当作任意出站请求发射器需设置KS_CALLBACK_ENABLEDtrue或配置KS_CALLBACK_ALLOWED_CIDRS白名单才可用投递为 at-least-once、best-effort接收方应基于 ID 去重并保留轮询兜底详见 requestshandlerutils.go。Environment Variables完整环境变量参考HTTP Handler 的所有行为都由环境变量控制。除 README 列出的变量外下表同时整合了 main.go、setup.go 与 requestshandlerutils.go 中实际读取的全部变量变量说明示例KS_ACCOUNT_ID每次扫描使用的 Kubescape SaaS 账号 IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxKS_ACCESS_KEY每次扫描使用的 Kubescape SaaS 访问密钥your-access-keyKS_EXCLUDE_NAMESPACES默认排除的命名空间逗号分隔kube-system,kube-publicKS_INCLUDE_NAMESPACES默认包含的命名空间逗号分隔production,stagingKS_FORMAT默认输出格式jsonKS_FORMAT_VERSION输出格式版本v2KS_LOGGER_NAMELogger 名称kubescapeKS_LOGGER_LEVEL日志级别info,debug,warning,errorKS_DOWNLOAD_ARTIFACTS每次扫描是否下载策略工件false时从本地缓存加载true,falseKS_SCAN_QUEUE_CAPACITY活动扫描之后最多排队的扫描数默认1010KS_SCAN_REQUEST_MAX_BYTESPOST /v1/scan请求体最大字节数默认1048576即 1 MiB1048576KS_PPROF_ENABLED启用 pprof 调试服务默认关闭仅绑定回环地址true,falseKS_PPROF_ADDR启用时 pprof 调试服务的绑定地址127.0.0.1:6060KS_API_TOKEN/v1/*API 的 Bearer Token 鉴权可选默认关闭。设置后每个/v1/scan、/v1/results、/v1/status请求都必须携带Authorization: Bearer token否则返回401健康探针/livez、/readyz与 OpenAPI 文档保持开放。若将:8080暴露到集群之外建议设置随机值并启用 TLSKS_CERT_FILE/KS_KEY_FILE或使用 TLS 终结的 Ingressopenssl rand -hex 32生成KS_PORTHTTP 监听端口默认80808080KS_CERT_FILE/KS_KEY_FILETLS 证书与私钥路径须成对设置/etc/tls/tls.crtKS_OFFLINEtrue时强制离线模式使用本地工件缓存trueKS_CONTEXT集群上下文名称my-clusterKS_KEEP_LOCAL不向 Kubescape SaaS 提交结果trueKS_SUBMIT显式开启结果提交存在即生效解析失败会告警并忽略trueKS_REGO_PRINT打印 rego 规则falseKS_ENABLE_HOST_SCANNER启用主机扫描器trueKS_HOST_SCAN_YAML主机扫描 YAML 路径/path/to/host-scan.yamlKS_CALLBACK_ENABLED开启扫描完成回调默认关闭trueKS_CALLBACK_ALLOWED_CIDRS回调目标 IP 白名单逗号分隔 CIDR配置后即视为开启回调10.0.0.0/8KS_SERVICE_DISCOVERY_FILE_PATH文件式服务发现路径默认/etc/config/services.json支持 sidecar 与私有集群注入后端端点/etc/config/services.jsonKS_CREDENTIALS_SECRET_PATH凭据文件路径默认/etc/credentials/etc/credentials鉴权细节源码佐证bearerAuthMiddleware使用subtle.ConstantTimeCompare做常数时间比较以防时序侧信道并接受大小写不敏感的Bearer方案见 setup.go。鉴权是增量式加固扫描 API 默认开放以保证集群内既有安装不因升级而中断这与默认关闭的 pprof 不同见 setup.go。Deployment Examples两种典型落地方式方式一微服务部署API 驱动扫描在集群内将 Kubescape 部署为微服务通过 REST API 驱动扫描是 CI/CD 集成、自定义仪表盘和自动化编排的基础形态。快速部署kubectl apply -f httphandler/examples/microservice/ks-deployment.yaml部署清单 ks-deployment.yaml 已经内置了完整资源kubescape命名空间、kubescape-discoveryServiceAccount、具有get/list/describe全资源权限的 ClusterRole 与绑定、NodePort 类型 Service以及 Deploymentquay.io/kubescape/kubescape:latest启动命令ksserver。其中值得关注的默认配置terminationGracePeriodSeconds: 35与优雅停机协议匹配/livez与/readyz健康探针每 3 秒一次初始延迟 3 秒KS_ENABLE_HOST_SCANNERtrue启用主机扫描器KS_DOWNLOAD_ARTIFACTStrue每次扫描都下载最新策略工件。验证与访问# 检查 Pod 状态 kubectl get pods -l appkubescape # 检查 Service kubectl get svc kubescape # 本地端口转发访问 kubectl port-forward svc/kubescape 8080:8080 # 或获取 LoadBalancer 外部 IP若修改 serviceType kubectl get svc kubescape -o jsonpath{.status.loadBalancer.ingress[0].ip}部署前应结合集群实际调整serviceTypeClusterIP / NodePort / LoadBalancer、命名空间、资源配额、ServiceAccount 权限。完整部署指南见 httphandler/examples/microservice/README.md。典型 CI 门禁脚本来自微服务示例文档同步扫描后提取合规分数低于阈值即让流水线失败#!/bin/bash RESULT$(curl -s --header Content-Type: application/json \ --request POST \ --data {targetType: framework, targetNames: [nsa]} \ http://kubescape:8080/v1/scan?waittrue) # 提取合规分数 SCORE$(echo $RESULT | jq .response.summaryDetails.complianceScore) # 分数低于阈值则失败 if (( $(echo $SCORE 80 | bc -l) )); then echo Compliance score $SCORE is below threshold (80) exit 1 fi定时扫描 CronJob每 6 小时触发一次 NSA 与 MITRE 框架扫描apiVersion: batch/v1 kind: CronJob metadata: name: kubescape-scheduled-scan spec: schedule: 0 */6 * * * # 每 6 小时 jobTemplate: spec: template: spec: containers: - name: scanner image: curlimages/curl command: - /bin/sh - -c - | curl -X POST http://kubescape:8080/v1/scan \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa, mitre]} restartPolicy: OnFailure大集群超时建议异步触发 轮询而不是长阻塞的同步调用# 触发扫描立即返回 curl -X POST http://127.0.0.1:8080/v1/scan \ -H Content-Type: application/json \ -d {targetType: framework, targetNames: [nsa]} # 轮询状态 while true; do STATUS$(curl -s http://127.0.0.1:8080/v1/status | jq -r .type) if [ $STATUS ! busy ]; then break fi sleep 10 done # 获取结果 curl http://127.0.0.1:8080/v1/results -o results.json方式二Prometheus 集成指标暴露将 Kubescape 指标暴露给 Prometheus 抓取可把安全态势接入现有可观测体系。指标端点挂载在/v1/metrics带鉴权与 OpenTelemetry 中间件见 setup.go实现在 prometheus.go。抓取方式与 ServiceMonitor 配置请参考 httphandler/examples/prometheus/README.md。Debugging调试与性能剖析开启调试日志export KS_LOGGER_LEVELdebug源码中日志级别通过logger.L().SetLevel(...)应用级别字符串无效时回退到debug并记录错误见 main.go。pprof 性能剖析pprof 调试服务默认关闭且只绑定127.0.0.1因此只能从 Pod 自身的网络命名空间内访问无法从网络直接触达这是刻意的安全设计——历史上它曾因日志级别为 debug 而默认暴露未鉴权的剖析端点见 setup.go 的注释。启用后通过kubectl port-forward访问export KS_PPROF_ENABLEDtrue # 然后例如kubectl port-forward pod 6060:6060 # 堆剖析 go tool pprof http://127.0.0.1:6060/debug/pprof/heap # CPU 剖析采样 30 秒 go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds30 # Goroutine 剖析 go tool pprof http://127.0.0.1:6060/debug/pprof/goroutine若6060端口与 Pod 内 sidecar 冲突可用KS_PPROF_ADDR修改绑定地址如KS_PPROF_ADDR127.0.0.1:6061。绑定到非回环地址属于刻意的显式选择仅在可信网络上才应这样做。pprof 处理器注册在独立 mux 上而非http.DefaultServeMux保证该依赖自包含且由编译器强制见 setup.go。相关文档CLI ReferenceArchitectureGetting Started GuideTroubleshootingMicroservice Deployment GuidePrometheus Integration Guide小结Kubescape HTTP Handler 将 Kubernetes 安全扫描包装为一组语义清晰、背压可控的 REST API配合优雅停机、可选的 Bearer 鉴权、pprof 剖析与完善的部署清单足以支撑从 CI 门禁到定时巡检的各类自动化场景。理解其请求/响应契约尤其busy/notBusy/v1results/error四种响应类型、环境变量矩阵与账号身份只来自服务端配置的安全边界是把它正确接入生产环境的关键。若需从源码层面继续深入可依次阅读 httphandler/listener/setup.go路由与停机、httphandler/handlerequests/v1/requestshandler.go四端点实现与 httphandler/handlerequests/v1/requestshandlerutils.go扫描执行与回调投递。【免费下载链接】kubescapeKubescape is an open-source Kubernetes security platform for your IDE, CI/CD pipelines, and clusters. It includes risk analysis, security, compliance, and misconfiguration scanning, saving Kubernetes users and administrators precious time, effort, and resources.项目地址: https://gitcode.com/GitHub_Trending/ku/kubescape创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考