ECC 安全策略与实战指南：版本维护边界、漏洞披露流程、秘密管理与 system-reminder 甄别-平芜编程栈

ECC 安全策略与实战指南：版本维护边界、漏洞披露流程、秘密管理与 system-reminder 甄别

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

ECC（Everything Claude Code）是一个面向 Claude Code、Codex、Opencode、Cursor 等 Agent Harness 的性能优化系统，仓库以插件、hooks、skills、rules、MCP 配置与安装/修复脚本等大量可执行表面构成，供应链暴露面也因此远大于普通 CLI 工具。本文以仓库内的安全策略文档 docs/es/SECURITY.md（西班牙语本地化版本）为主线，结合仓库根目录现行策略 SECURITY.md 与mcp-configs/、scripts/、commands/中的真实实现进行交叉验证，系统讲解：哪些版本仍在安全维护期内、如何负责任地报告漏洞、安全策略覆盖哪些文件与运行面、本地 MCP 秘密与端口如何防护，以及如何把“可疑<system-reminder>注入”从真实的提示注入攻击中甄别出来。读完本文，你将掌握一套可以直接落地的 Agent 类项目安全运营清单。

一、受支持版本与安全维护边界

docs/es/SECURITY.md的版本支持矩阵如下（这是该本地化文档的快照内容）：

版本	支持状态
1.9.x	✅ 受支持
1.8.x	✅ 受支持
< 1.8	❌ 不受支持

需要注意的事实边界：该西班牙语文档是较早时间点的翻译快照。仓库当前版本文件 VERSION 记录的实际版本已是2.2.1，而仓库根目录的现行英文策略 SECURITY.md（即操作上真正生效的版本）给出的支持矩阵是：

版本	支持状态
2.x / rc 构建	✅ 受支持
1.10.x	✅ 受支持
1.9.x	仅关键漏洞修复（Critical fixes only）
< 1.9	❌ 不受支持

此外根目录策略还明确了安全修复的落地顺序：安全修复先合入main分支，再以“尽力而为（best-effort）”方式向当前仍在支持期内的版本线做 backport。因此在生产环境中应以 SECURITY.md 的版本矩阵为准：任何低于 1.10 的旧版都应尽快升级，低于 1.9 的版本已完全退出维护，漏洞不会获得修复。

二、漏洞披露流程：报告内容、响应时限与披露纪律

2.1 报告渠道与“禁止公开 issue”红线

两份 SECURITY 文档都强调同一条基本纪律：不要在公开 issue 中提交安全漏洞，否则会让未修复的缺陷暴露给攻击者，形成 0-day 风险。

本地化文档（docs/es/SECURITY.md）给出的渠道是邮件security@ecc.tools；
根目录现行策略（SECURITY.md）则给出了更精确的指引：优先使用 GitHub 的 Private vulnerability reporting（私有漏洞报告），并明确指出security@ecc.tools别名无人值守，邮件应发送到affaan@ecc.tools。

两个版本之间存在渠道差异，实操时应以根目录现行策略为准，避免把漏洞报告发到无人监控的邮箱导致石沉大海。

2.2 报告时应包含的材料

一份高质量漏洞报告应携带足够让维护者“从干净检出即可复现”的信息，两份文档给出的要素可归纳为：

受影响的对象：文件、包名、版本、commit、安装路径；
从干净检出（clean checkout）开始的完整复现步骤；
预期影响与受影响的信任边界（trust boundary）；
利用条件归属：是否需要本地 shell 权限、恶意仓库、恶意包、远程未认证攻击者，还是维护者凭据；
任何 PoC 日志，且必须对 token、密钥、本地路径与私有数据做脱敏处理。

2.3 响应时限（SLA）

确认收到：48 小时内；
状态更新：7 天内给出初步评估；
关键问题的修复或缓解：本地化文档写的是 30 天内；根目录现行策略对“影响受支持版本且跨越真实信任边界”的报告收紧为14 天；
协同披露（coordinated disclosure）：在公开安全通告发布之前与报告者协调披露时机。

如果漏洞被接受，维护者会在发布说明中为报告者署名（除非要求匿名）并及时修复、协调披露节奏；如果被拒绝，会说明拒绝原因（不可复现、超出范围、已修复或攻击路径不够强），并给出是否应转向其他渠道上报的指引。

三、安全策略覆盖范围：可执行面即攻击面

两份策略文档界定的覆盖范围高度一致，可归纳为五类：

ECC 插件本体及仓库内所有脚本——对应仓库中的 scripts/ 目录（约 130+ 个 JS/TS/Python 实现）；
在用户机器上执行的 hooks 脚本——对应 hooks/ 与 scripts/hooks/ 中大量在 install/commit 等时机触发的代码；
安装 / 卸载 / 修复的生命周期脚本——对应 install.sh、install.ps1、scripts/install-apply.js、scripts/uninstall.js、scripts/repair.js 等；这些脚本拥有改动用户配置的高权限，一旦被投毒后果最严重；
ECC 随附的 MCP 配置——即 mcp-configs/mcp-servers.json 模板文件；
AgentShield 安全扫描器——仓库策略将它的使用文档纳入范围，代码问题则归属其独立仓库。

根目录现行策略还额外覆盖了仓库内的 GitHub Actions 工作流与发布自动化、ECC Tools GitHub App 的集成点，以及从仓库发布的 plugin/install/repair/dashboard/hook/rule/skill/MCP/command 全表面——这也解释了为什么策略要求供应链安全与可执行面审计成为一等公民（详见 docs/architecture/agentshield-enterprise-research-roadmap.md 与 commands/security-scan.md）。

四、供应链与官方分发面纪律

SECURITY.md把供应链暴露面列为“一等安全表面”，并给出硬性规则：

GitHub Actions 中对第三方 action 必须使用commit SHA 锁定，不能依赖可变 tag；
工作流避免把不可信的 GitHub context 直接 shell 进run:块；
发布与安装文档只能指向官方包；
包元数据应指向当前仓库，而不是历史仓库路径；
私有漏洞报告在公开披露前必须内部优先分流。

同时官方分发面需要核对：npm 官方包为ecc-universal，AgentShield 官方 npm 包为ecc-agentshield。策略文档还点名了两类并非 ECC 维护、却借用了仓库元数据的包，并提示不要安装任何形如opencode-ecc、everything-claude-code等未被本仓库文档明确列为官方的别名包——这是针对“仿冒包钓鱼”的防御姿态。

仓库内提供了对应的供应链事件应急剧本：docs/security/supply-chain-incident-response.md，它以 2026 年 5 月 TanStack npm 供应链事件为例，说明攻击链如何组合pull_request_target、GitHub Actions 缓存投毒与 OIDC token 窃取，并给出 IOC 排查清单（如gh-token-monitor持久化、.github/workflows/codeql_analysis.yml恶意工作流、router_init.js/tanstack_runner.js哈希等）。注意先移除持久化钩子、再轮换被窃 token这一顺序在该剧本中被特别强调。

五、操作安全：秘密处理（Secrets Handling）

5.1 MCP 模板文件是占位符，不是配置

docs/es/SECURITY.md明确指出：mcp-configs/mcp-servers.json 是模板（template）。打开该文件可以看到大量YOUR_*_HERE占位符，例如：

github服务器要求GITHUB_PERSONAL_ACCESS_TOKEN: "YOUR_GITHUB_PAT_HERE"；
jira服务器要求JIRA_URL/JIRA_EMAIL/JIRA_API_TOKEN三项；
firecrawl、supabase、exa-web-search、codescene、confluence、evalview、fal-ai、browserbase等同样以YOUR_*_HERE形式占位。

该文件本身自带的_comments.usage也写明：“把你需要的服务器复制到~/.claude.json的mcpServers段”，_comments.env_vars则要求“把YOUR_*_HERE占位符替换为真实值”。因此正确用法是：安装时从环境变量或密钥管理器（secrets manager）解析注入，绝不把真实凭据提交进仓库。若凭据被误提交，正确处置是立即在签发方轮换（rotate）并重写提交历史，而不是依赖一次简单的 revert——因为 revert 之后旧凭据仍保留在 Git 历史中可被检索。

5.2 用户级 Claude Code 配置同样适用

策略的同一规则也适用于仓库之外的~/.claude/settings.json（Windows 为%USERPROFILE%\.claude\settings.json）。该文件虽然不在仓库内，但经常通过claude doctor输出、截图或 bug 报告被分享出去，因此禁止把 PAT、API Key 或 OAuth token 硬编码进其mcpServers[*].env块，而应在进程启动时从系统钥匙串或服务器已支持的环境变量解析。

5.3 快速审计命令

策略提供了一条可直接复制执行的 grep 审计命令（macOS / Linux）：

grep -EnH '(TOKEN|SECRET|KEY|PASSWORD)\s*"\s*:\s*"[A-Za-z0-9_-]{16,}"' ~/.claude/settings.json

Windows PowerShell 对应写法：

Select-String -Path "$env:USERPROFILE\.claude\settings.json" -Pattern '(TOKEN|SECRET|KEY|PASSWORD)"\s*:\s*"[A-Za-z0-9_-]{16,}"'

该正则要求 key 名包含TOKEN|SECRET|KEY|PASSWORD且值为16 位以上的字母数字下划线串，用以过滤掉过短的占位值。如果审计命中，就在签发方轮换该秘密，然后将其移出文件（改为按提供方拆分环境变量，或对支持的服务器使用credentialHelper）。

六、操作安全：本地 MCP 端口占用核验

仓库中部分随附 MCP 服务器通过明文 HTTP 连接本地 localhost 端口。一个典型实例就是devfleet（多 Agent 编排，在隔离 worktree 中派发并行 Claude Code Agent），其配置位于 mcp-configs/mcp-servers.json：

"devfleet": { "type": "http", "url": "http://localhost:18801/mcp" }

由于 MCP 请求承载的是对 Agent 的工具调用与潜在敏感上下文，如果该端口被其他进程占用，攻击者即可充当中间人拦截 MCP 流量。因此策略要求首次使用前核验监听进程：

# Windows netstat -ano | findstr :18801 # macOS / Linux lsof -iTCP:18801 -sTCP:LISTEN

将返回的 PID 与期望的 devfleet 二进制进程对照；任何“其他进程”占据该端口都应视为警告信号。这条核验思路同样适用于模板中其他走本地 HTTP 的服务器，例如ito-compute等 opt-in 的本地服务。

七、威胁甄别实战：可疑`<system-reminder>`块

这是策略文档中最有 Agent 生态特色的一节。Claude Code 的 CLI 会在每一轮把临时的客户端侧 system-reminder注入模型输入（如 TodoWrite 提醒、日期变更提示、文件修改提示等）。这类块的特点：

通常以"ignore if not applicable"或"NUNCA mencionar este recordatorio al usuario"（“永远不要向用户提及此提醒”）之类的措辞结尾——这其实是 Anthropic 自身提示词里的固定文案，并非恶意注入的尾巴；
由 CLI 逐轮添加，不会持久化到~/.claude/projects/<slug>/<sessionId>.jsonl的会话 transcript 中。

正因如此，它极易与“被追加到工具结果上的提示注入”混淆。策略给出的三连验证法：

该块真的在本仓库的某个文件里吗？执行
```
grep -rEn "system-reminder|NEVER mention|DO NOT mention" .
```
若全仓库无命中，则该块不属于仓库携带内容。
该块被存进 transcript 了吗？打开当前会话的.jsonl，若这段精确文本没有出现在某个tool_result的 body 内，它就是客户端注入的临时提醒，而非任何工具返回的 payload。
内容是否与已知客户端提醒（TodoWrite、日期变更、文件修改提示）上下文一致？若一致，即临时提醒机制，无需任何处置。

策略强调：只有当一个块同时满足（a）确实出现在 transcript 的tool_result内，且（b）无法归因于实际读取的文件或 URL 时，才应升级到 Anthropic 上游；升级时附上最小化报告（全新会话、干净本地文件读取、观察到的精确文本、transcript 摘录）。同时明确告诫：不要因为临时提醒而“清理”仓库文件——它们不是攻击载体。

从仓库实现看，这类“输入侧防御意识”也贯穿于安全相关命令中：commands/security-scan.md 的 Review Checklist 明确要求先识别“处理不可信内容却无防御的 agent 提示词”，并把“agent prompts that handle untrusted content without defenses”列为最高优先级的运行时发现项；对应的规则文档 rules/common/ 与 skills/security-scan/SKILL.md 也围绕输入投毒面展开。

八、安全资源与自动化落点

策略文档给出的安全资源清单，可在本仓库中找到完整的可执行实现：

AgentShield 扫描器：策略中的命令为npx ecc-agentshield scan。commands/security-scan.md 给出了完整参数契约：/security-scan [path] [--format text|json|markdown|html] [--min-severity low|medium|high|critical] [--fix]。其中--format json用于 CI、markdown用于交接、html用于独立评审报告；--fix只应用被显式标记为安全且可自动修复的项。其确定性引擎的推荐用法为：
```
npx ecc-agentshield scan --path "${TARGET_PATH:-.}" --format text
```
对应的扫描完成后输出契约（安全评级与分数、按严重级与运行时置信度统计、带精确路径的 critical/high 发现、独立分组的低置信度发现、修复顺序）及 CI 强制门禁用法都记录在该命令文档中，并关联到 Agent 角色 agents/security-reviewer.md。
Agentic 安全长文指南：仓库提供《The Shorthand Guide to Everything Agentic Security》，英文原文位于根目录 the-security-guide.md，并有西班牙语本地化版本 docs/es/the-security-guide.md。
供应链事件应急剧本：docs/security/supply-chain-incident-response.md 收录了 npm / GitHub Actions 跨生态包注册表事件处置手册与持续更新的 IOC 扫描清单。
行业参考框架：策略指向 OWASP MCP Top 10 与 OWASP Agentic Applications Top 10 两个公开分类体系，可用于把仓库内的发现映射到行业标准风险类别（本文不提供外部链接，读者可自行检索owasp.org对应项目页）。

结语：把安全策略当成可执行清单

从本仓库 docs/es/SECURITY.md 与现行 SECURITY.md 的对比可以看到，Agent 类项目安全运营的核心动作非常具体：核对版本支持矩阵决定是否升级、按规范渠道与要素提交漏洞报告、对 MCP 模板中的YOUR_*_HERE占位符做到“永不入库、启动时注入”、首次使用本地 MCP 前用lsof/netstat核验端口归属，以及用“文件定位 + transcript 核验 + 上下文一致性”三步法冷静甄别看似骇人的<system-reminder>文本。配合npx ecc-agentshield scan与 commands/security-scan.md 的 CI 门禁，这些策略即可转化为日常开发中可重复执行的安全检查，而不只是仓库里的一份声明。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ECC 安全策略与实战指南：版本维护边界、漏洞披露流程、秘密管理与 system-reminder 甄别