SkillHub

中文

English

中文

English

Appearance

配置与查看安全扫描 ​

本页说明技能作者、审核员如何判读版本扫描报告，以及部署方如何配置和诊断 Scanner。报告提供风险发现与执行证据，不代替人工审核，也不保证技能在 Agent 中的实际行为。头像机器审核属于另一条处理链路，参见技能头像与审核。

前置条件与职责 ​

操作执行主体前置条件说明
读取报告已登录且有报告访问权限的账号技能及目标版本可定位技能详情或审核详情中核对版本；公开可见不代表匿名可读报告。
修订内容技能作者具有版本更新权限根据发现项修改包，再沿发布流程提交，不修改历史报告。
审核决策具有目标命名空间审核权限的账号读取本次提交及扫描状态扫描完成不等于批准。
配置与诊断部署方具有容器或集群操作权限业务角色不自动授予主机操作权限。

扫描执行、报告判读与人工审核之间的关系

图：扫描任务产生报告；执行失败与风险发现分别处置，人工审核独立判断。

判读本次版本报告 ​

  1. 在技能详情或审核详情选择目标版本。先记录版本与扫描时间，避免将旧报告用于新内容。
  2. 检查 failureReason 和 scannedAt，区分任务未完成、执行失败和已生成结果。SCAN_FAILED 表示执行失败，不表示已认定内容有害。
  3. 对已完成报告，结合 verdict、isSafe、maxSeverity 和 findings 阅读机器结果；逐项核对文件位置、说明与修复措施，不能只查看发现数量。
  4. 作者修订问题后提交新版本；审核员依据本次内容与报告作出批准或拒绝决定。版本仍在 SCANNING 时不能按普通提审路径批准，具体流程见审核技能与套装。

以下是报告字段的示例节选，不是真实实例结果；接口按技能和版本返回扫描报告列表。

json
{
  "verdict": "DANGEROUS",
  "isSafe": false,
  "maxSeverity": "HIGH",
  "findingsCount": 1,
  "findings": [{
    "ruleId": "EXAMPLE_RULE",
    "severity": "HIGH",
    "filePath": "scripts/example.py",
    "lineNumber": 12,
    "message": "Example finding",
    "remediation": "Review the indicated operation"
  }],
  "failureReason": null
}
机器结果映射依据处置依据说明
SAFEScanner 返回 is_safe=true仍须核对内容、依赖及适用场景是机器判定，不是安全保证。
BLOCKED非上述结果且最高级别为 CRITICAL重点核查发现项及危险操作枚举名称不等于注册中心已自动拒绝审核。
DANGEROUS非上述结果且最高级别为 HIGH核查风险证据与修订内容不等于扫描执行失败。
SUSPICIOUS其他非 SAFE 结果，包括级别缺失阅读具体发现及报告完整性不得因级别较低直接认定可发布。

映射与字段依据：Scanner 适配器、报告接口和扫描状态处理。

配置扫描与确认生效 ​

下表是本页涉及的应用绑定。变量必须实际传入注册中心容器；仅在 .env.release 增加清单未引用的键不会生效。Compose 修改后重新创建注册中心；Kubernetes 更新覆盖配置并滚动受影响 Deployment。完整配置以应用配置及Scanner 配置说明为准。

配置项应用默认与部署覆盖影响说明
SKILLHUB_SECURITY_SCANNER_ENABLED应用、release Compose、Kustomize、Helm 为 true；运行脚本 --no-scanner 为 false关闭后拒绝普通新非私有上传生效需重建或滚动。
SKILLHUB_SECURITY_SCANNER_URL应用 http://localhost:8000；Compose http://skill-scanner:8000；Kustomize http://skillhub-scanner:8000；Helm 按 release 生成注册中心访问 Scanner 的地址生效需重建或滚动。
SKILLHUB_SECURITY_SCANNER_MODE应用 local；Compose、Kustomize、Helm 覆盖为 uploadlocal 需双方共享相同目录路径；upload 传包生效需重建或滚动。
SKILLHUB_SCANNER_POLICY_PRESETbalanced；可选 strict、permissive传给 Scanner 的分析策略显式透传并重建后生效。
SKILLHUB_SCANNER_FAIL_ON_SEVERITY配置声明为 high当前适配器未将此字段传入扫描选项不得将其视为已实现的自动发布阻断保障。
SKILLHUB_SCANNER_USE_BEHAVIORAL / SKILLHUB_SCANNER_USE_METAtrue / false行为与元数据分析开关显式透传并重建注册中心。
SKILLHUB_SCANNER_USE_AI_DEFENSE / SKILLHUB_SCANNER_USE_VIRUSTOTAL均为 false可选外部检测引擎除开关外须配置相应服务凭据；重建受影响服务。
SKILLHUB_SCANNER_USE_LLM / SKILLHUB_SCANNER_LLM_PROVIDERfalse / anthropic；提供方可选 openai、azure开启外部模型分析注册中心重建；Scanner 侧另配 SKILL_SCANNER_LLM_API_KEY，可配 SKILL_SCANNER_LLM_BASE_URL、SKILL_SCANNER_LLM_MODEL；密钥变更后重建对应服务。

策略选项依据装配代码与扫描选项。LLM 分析可能向配置的外部服务发送内容并产生费用；启用前由部署方核对数据范围与服务条款，不公开密钥或完整环境输出。

扫描关闭时，普通公开（PUBLIC）和空间成员可见（NAMESPACE_ONLY）新上传返回 error.security.scanner.required。私有（PRIVATE）仍可上传，但停留在 UPLOADED，须另行确认发布。已发布私有技能扩大范围时，最新版本已有可复用报告（taskId、scannedAt 非空，failureReason=null、isSafe=true）可继续审核；否则扫描关闭时拒绝。依据发布前置、可见范围变更与私有发布确认。

诊断连接与任务 ​

Compose 命令在含 .env.release、compose.release.yml 的运行目录执行。Kustomize 使用清单默认名称；Helm 名称按 Chart README核对，不得混用。探测仅输出固定允许值；异常配置脱敏，包含凭据或非保守 URL 形态时跳过。缺失变量取应用默认值，额外 Spring 覆盖须在受保护配置中核对。

参数值影响范围说明
wget -T5秒本次健康请求阶段超时不修改扫描任务超时。
wget -t1次本次请求尝试次数不触发扫描。

Compose：

bash
   docker compose --env-file .env.release -f compose.release.yml exec -T server sh -c '
     enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true}
     mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local}
     url=${SKILLHUB_SECURITY_SCANNER_URL:-http://localhost:8000}
     case "$enabled" in true|false) ;; *) enabled=unrecognized_redacted ;; esac
     case "$mode" in local|upload) ;; *) mode=unrecognized_redacted ;; esac
     case "$url" in
       http://localhost:8000|http://localhost:8000/) host=localhost:8000 ;;
       http://skill-scanner:8000|http://skill-scanner:8000/) host=skill-scanner:8000 ;;
       http://skillhub-scanner:8000|http://skillhub-scanner:8000/) host=skillhub-scanner:8000 ;;
       *) host=custom_or_unrecognized_redacted ;;
     esac
     probe=allowed
     case "$url" in http://?*|https://?*) ;; *) probe=skipped_unrecognized_url ;; esac
     case "$url" in *[!a-zA-Z0-9:/._~\[\]-]*|*@*|*\?*|*\#*|*\\*) probe=skipped_unrecognized_url ;; esac
     authority=${url#*://}; authority=${authority%%/*}
     case "$authority" in ""|:*|*:) probe=skipped_unrecognized_url ;; esac
     printf "enabled=%s mode=%s scanner_host=%s\n" "$enabled" "$mode" "$host"
     if [ "$enabled" = false ]; then printf "health=skipped_disabled\n"
     elif [ "$enabled" != true ]; then printf "health=skipped_unrecognized_enabled\n"
     elif [ "$mode" = unrecognized_redacted ]; then printf "health=skipped_unrecognized_mode\n"
     elif [ "$probe" != allowed ]; then printf "health=%s\n" "$probe"
     else
       wget -T 5 -t 1 -q -O /dev/null -- "${url%/}/health"; printf "health_exit=%s\n" "$?"
     fi
   '

Kustomize：

bash
   kubectl -n skillhub exec deployment/skillhub-server -c server -- sh -c '
     enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true}
     mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local}
     url=${SKILLHUB_SECURITY_SCANNER_URL:-http://localhost:8000}
     case "$enabled" in true|false) ;; *) enabled=unrecognized_redacted ;; esac
     case "$mode" in local|upload) ;; *) mode=unrecognized_redacted ;; esac
     case "$url" in
       http://localhost:8000|http://localhost:8000/) host=localhost:8000 ;;
       http://skill-scanner:8000|http://skill-scanner:8000/) host=skill-scanner:8000 ;;
       http://skillhub-scanner:8000|http://skillhub-scanner:8000/) host=skillhub-scanner:8000 ;;
       *) host=custom_or_unrecognized_redacted ;;
     esac
     probe=allowed
     case "$url" in http://?*|https://?*) ;; *) probe=skipped_unrecognized_url ;; esac
     case "$url" in *[!a-zA-Z0-9:/._~\[\]-]*|*@*|*\?*|*\#*|*\\*) probe=skipped_unrecognized_url ;; esac
     authority=${url#*://}; authority=${authority%%/*}
     case "$authority" in ""|:*|*:) probe=skipped_unrecognized_url ;; esac
     printf "enabled=%s mode=%s scanner_host=%s\n" "$enabled" "$mode" "$host"
     if [ "$enabled" = false ]; then printf "health=skipped_disabled\n"
     elif [ "$enabled" != true ]; then printf "health=skipped_unrecognized_enabled\n"
     elif [ "$mode" = unrecognized_redacted ]; then printf "health=skipped_unrecognized_mode\n"
     elif [ "$probe" != allowed ]; then printf "health=%s\n" "$probe"
     else
       wget -T 5 -t 1 -q -O /dev/null -- "${url%/}/health"; printf "health_exit=%s\n" "$?"
     fi
   '

标准结果如下；health_exit=0 仅表示健康端点可达。自定义地址显示 custom_or_unrecognized_redacted，不代表无效；普通自定义 HTTP(S)／IPv6 地址仍可探测。skipped_* 表示本次诊断跳过，不能据此判定产品配置有效或无效。

text
# Compose
 enabled=true mode=upload scanner_host=skill-scanner:8000
 health_exit=0
# Kustomize
 enabled=true mode=upload scanner_host=skillhub-scanner:8000
 health_exit=0

随后以本版本的失败原因和时间关联日志；反馈前脱敏，不公开整份日志。

bash
   # Compose，仍在本次运行目录
   docker compose --env-file .env.release -f compose.release.yml logs --since=10m --tail=100 server skill-scanner
   # Kustomize，使用清单默认名称
   kubectl -n skillhub logs deployment/skillhub-server -c server --since=10m --tail=100
   kubectl -n skillhub logs deployment/skillhub-scanner -c scanner --since=10m --tail=100

结果确认与失败处置 ​

已生成报告应能定位目标版本、扫描时间及具体发现；普通非私有版本扫描执行完成后进入 PENDING_REVIEW，私有版本进入 UPLOADED。已发布版本补扫不改变其发布状态。上述结果均不等于人工已批准。

现象最可能原因定位手段处置
非私有上传返回 error.security.scanner.required扫描关闭探测显示 enabled=false恢复服务与开关；不要修改数据库状态绕过检查。
标准部署显示 local 或 localhost透传缺失或覆盖不正确对照本页配置表与容器输出修正配置并重建；不要将容器 localhost 当作宿主机。
health_exit 非零服务未就绪或网络/地址错误Compose 执行 docker compose --env-file .env.release -f compose.release.yml ps skill-scanner；Kustomize 执行 kubectl -n skillhub get pods -l app.kubernetes.io/name=skillhub-scanner恢复连接后跟踪原任务；不要删除数据库或持久卷。
健康可达但版本仍扫描或失败执行错误、超时或恢复重试超限本版本 failureReason 与上述日志仅在页面提供重试且有权限时重试；不要重复上传制造新版本。
报告非 SAFE 但任务已完成扫描发现风险核对 findings 与文件位置修订或提交审核证据；不要把 BLOCKED 枚举当成自动拒绝记录。

诊断依据：Compose、Kustomize与Server 镜像。标准镜像提供 sh、wget。

边界与后续 ​

扫描执行时长由包内容、分析引擎和外部依赖决定，本页不承诺固定完成时间。风险发现、执行失败、人工拒绝是不同结果；审核实现当前不会仅凭最高严重级别自动替代人工审核。完成本步骤后，作者在发布与更新跟踪版本，审核员在审核处理申请；部署方排障不得改写版本或审核记录。

版权所有 © 科大讯飞股份有限公司