ruflo V3 Security Architect Agent：从威胁建模到 CVE 修复的 Secure-by-Default 安全架构设计

本篇技术指南以 ruflo 仓库中的 v3-security-architect Agent 技能文件为核心，完整还原该项目 V3 安全架构师的职责边界、五类优先修复项（CVE-1 至 HIGH-2）、分层威胁模型与三类安全模式的设计思路；并结合 @claude-flow/security 模块的真实源码实现（bcrypt 密码哈希、凭据随机生成、无 Shell 命令执行、路径遍历防护）与 CVE 修复追踪机制，带你掌握一套可落地、可验证、可审计的 Agent 安全架构设计方法。

V3 Security Architect 的角色定位与技能定义

该 Agent 技能定义在 SKILL.md 中，其 frontmatter 元数据明确刻画了角色属性：

• version：3.0.0-alpha，更新于 2026-01-04；
• v3_role：architect（架构师），agent_id：2；
• priority：critical，domain：security，phase：foundation（基础阶段）。

其核心使命是：为 V3 代码库设计并实现完整的安全架构，解决所有已识别的漏洞，并确立贯穿整个代码库的 secure-by-default（默认安全）模式。

技能文件还定义了 pre_execution 与 post_execution 两个钩子：

• 执行前钩子：打印本次安全整改的优先级清单（CVE-1 依赖漏洞、CVE-2 弱密码哈希、CVE-3 硬编码凭据、HIGH-1 命令注入、HIGH-2 路径遍历），检查 npm audit 是否可用，并声明目标——90/100 安全评分 + secure-by-default 模式；
• 执行后钩子：调用 npx agentic-flow@alpha memory store-pattern 将本次安全架构决策以 critical 优先级存入 Agent 记忆（session-id 形如 v3-security-$(date +%s)），使安全模式在后续协作中可被其他 Agent 检索复用。

这一设计体现了一个关键理念：安全架构不是散落的修复补丁，而是需要显式建模、持久化沉淀、跨 Agent 协同的工程活动。

优先安全修复项清单：CVE-1 至 HIGH-2

技能文件定义了五项按优先级排序的修复任务，每项均包含问题描述、修复动作、受影响文件与时间线：

编号	问题	修复动作	受影响文件	时间线
CVE-1	依赖漏洞：@anthropic-ai/claude-code 版本过旧	升级至 @anthropic-ai/claude-code@^2.0.31	package.json	Phase 1 Week 1
CVE-2	弱密码哈希：SHA-256 + 硬编码 salt	改用 bcrypt，12 rounds	api$auth-service.ts:580-588（即 v2/src/api/auth-service.ts）	Phase 1 Week 1
CVE-3	认证服务中硬编码默认凭据	安装时生成随机凭据	api$auth-service.ts:602-643	Phase 1 Week 1
HIGH-1	命令注入：spawn() 调用使用 shell: true	改用无 Shell 的 execFile	多处 spawn() 调用点	Phase 1 Week 2
HIGH-2	路径遍历：文件路径未校验	path.resolve() + 前缀校验	所有文件操作模块	Phase 1 Week 2

这五项修复并非停留在纸面。仓库中 CVE-REMEDIATION.ts 以 CVE_REGISTRY 数据结构把它们逐条登记为可程序化校验的条目（CVEEntry 接口含 severity、remediationFile、remediationStatus、testFile、testStatus、timeline 等字段），且五项的 remediationStatus 均已标记为 fixed、testStatus 为 passing。从源码结构看，该文件还记录了后续 ADR-165 阶段（2026-06-30）补充修复的一批供应链漏洞，包括 vitest <3.2.6 的 WebSocket RPC 任意代码执行（CVSS 9.8，GHSA-5xrq-8626-4rwp）、@grpc/grpc-js 恶意请求 DoS、form-data 原型污染、hono CORS/路径匹配绕过、http-proxy-middleware 请求走私、undici 响应解析漏洞、vite dev server 任意文件读取、handlebars 原型污染/RCE 以及 protobufjs 对象注入/ReDoS——修复手段是统一在根 package.json 与 v3/package.json 中写入 npm overrides，将传递依赖强制钉到已修补的最低版本，这正是 SECURITY_PATTERNS.dependencyOverrides 中声明的策略："pin transitive deps to patched floor versions"。

威胁模型：分层安全架构与五条安全边界

技能文件给出了 V3 的分层威胁模型，自上而下为四层：

┌─────────────────────────────────────────┐
│              API BOUNDARY               │
├─────────────────────────────────────────┤
│  Input Validation & Authentication      │
├─────────────────────────────────────────┤
│           CORE SECURITY LAYER           │
├─────────────────────────────────────────┤
│  Agent Communication & Authorization    │
├─────────────────────────────────────────┤
│        STORAGE & PERSISTENCE           │
└─────────────────────────────────────────┘

与之配套的是五条安全边界的防护职责：

• API Layer：输入校验、限流（rate limiting）、CORS；
• Authentication：基于 Token 的认证、会话管理；
• Authorization：基于角色的访问控制（RBAC）；
• Agent Communication：Agent 间消息加密——在多 Agent 协作系统中，这是区别于传统单体应用的关键边界；
• Data Protection：静态数据加密与安全的密钥管理。

在源码层面可以印证这套分层并非空谈：@claude-flow/security 模块除了五大 CVE 修复原语外，还包含 authorization/propagator.ts（授权上下文传播）、oauth/（OAuth + PKCE 认证流）、policy/（策略引擎与评估器）、mcp-caller-identity.ts 等文件，分别对应认证、授权、策略评估这几条边界的具体落地。

安全模式目录：从技能文件模式到源码实现

技能文件定义了"Secure Patterns Catalog"，包含输入校验、路径净化、命令执行三类可复用模式。下面逐一对比文档中的参考实现与仓库中的生产级实现。

输入校验：Zod 模式化边界检查

技能文件给出的参考模式：

// Zod-based validation
const TaskInputSchema = z.object({
  taskId: z.string().uuid(),
  content: z.string().max(10000),
  agentType: z.enum(['security', 'core', 'integration'])
});

生产实现位于 input-validator.ts。它在 Zod 基础上做了三处增强：

1. 安全化错误映射：模块加载时通过 z.setErrorMap(securityErrorMap) 统一错误文案（如 "Input exceeds maximum allowed size"），避免在错误信息中回显用户输入；
2. 统一限制常量：LIMITS 定义了密码长度 8–128、邮箱最长 254、路径最长 4096、内容最大 1MB、数组最多 1000 项、对象最多 100 个键等边界，所有 Schema 共享同一套上限；
3. 正则黑名单：PATTERNS.NO_SHELL_CHARS 直接拒绝包含 ;&|$(){}>< 及换行、空字节的输入，SafeStringSchema` 即为"不可携带 Shell 元字符的安全字符串"。

该模块共导出 13 类以上可复用 Schema（SafeStringSchema、IdentifierSchema、FilenameSchema、EmailSchema、PasswordSchema、UUIDSchema、HttpsUrlSchema、SemverSchema、PortSchema、IPv4Schema、SpawnAgentSchema、TaskInputSchema、SecurityConfigSchema 等），完整清单见 模块 README 的 "Validation Schemas" 表格。

路径净化：从 startsWith 前缀校验到对称规范化

技能文件给出的参考实现：

// Secure path handling
function securePath(userPath: string, allowedPrefix: string): string {
  const resolved = path.resolve(allowedPrefix, userPath);
  if (!resolved.startsWith(path.resolve(allowedPrefix))) {
    throw new SecurityError('Path traversal detected');
  }
  return resolved;
}

这个 path.resolve() + prefix check 思路正是 path-validator.ts 的核心，但生产实现补上了三类参考实现未覆盖的攻击面：

• 遍历模式黑名单（TRAVERSAL_PATTERNS，L94-L104）：除了字面的 ../ 与 ..\，还拦截 URL 编码变体 %2e%2e、双重编码 %252e%252e、混合编码 .%2e / %2e.，以及空字节 \0 与 %00；
• 敏感文件拒绝：默认阻断 .env、.pem、.key、.pfx、.keystore 等密钥类扩展名，以及 id_rsa、shadow、passwd、authorized_keys、.git 等敏感文件名；
• 对称规范化（canonicalization symmetry）：源码注释特别指出——"只规范化一侧而不同步规范化另一侧，会在符号链接前缀下要么静默拒绝一切、要么静默放行逃逸"。为此模块实现了 canonicalize()（L157-L173）：当候选路径尚不存在时（ENOENT），沿父目录逐级向上找到最长已存在祖先并解析其 realpath，再把剩余段重新挂回，从而让"符号链接父目录下的待创建文件"也被规范化到真实位置，且前缀比较采用路径边界锚定（追加分隔符），保证 /srv/app-secrets 不会被误判为位于 /srv/app 之内。

配置项（PathValidatorConfig）还包括 blockedExtensions、blockedNames、maxPathLength（默认 4096）、resolveSymlinks（默认 true）、allowNonExistent（默认 true，服务于写操作）、allowHidden（默认 false）。

命令执行：execFile + 白名单 + 参数黑名单

技能文件的参考模式：

import { execFile } from 'child_process';

// ❌ Dangerous: shell injection possible
// exec(`git ${userInput}`, { shell: true });

// ✅ Safe: no shell interpretation
execFile('git', [userInput], { shell: false });

生产实现 safe-executor.ts 在此基础上构建了完整的 SafeExecutor 类（L163 起），防护维度包括：

• 无 Shell 解释：全程使用 promisify(execFile)，参数以数组传递，shell: true 路径被彻底移除；
• 命令白名单（allowedCommands）：只有显式声明的命令可以执行；
• 危险命令硬黑名单（DANGEROUS_COMMANDS，L129-L146）：rm、rmdir、format、mkfs、dd、chmod、chown、kill、reboot、shutdown 等即使用户加入白名单也应被拦截；
• 参数黑名单（DEFAULT_BLOCKED_PATTERNS，L102-L124）：拦截分号、&&、||、管道、反引号、$(、${、重定向符、后台符、换行与空字节等一切可构成命令拼接的字符；
• 资源约束：默认 30 秒超时、10MB 输出缓冲上限，并可通过 createDevelopmentExecutor() / createReadOnlyExecutor() 等工厂函数获得预配置实例。

CVE-2 / CVE-3 的源码级实现

CVE-2 修复：PasswordHasher（bcrypt 12 rounds）

password-hasher.ts 用 PasswordHasher 类替换了原先"SHA-256 + 硬编码 salt"的实现，安全属性包括：

• 自适应成本因子：默认 12 rounds（推荐生产下限），构造函数强制校验 rounds 必须在 10–20 之间、最小长度不小于 8，否则抛出 INVALID_ROUNDS / INVALID_MIN_LENGTH 错误；
• 每密码独立随机 salt：由 bcrypt 在哈希时自动生成，彻底消除硬编码 salt 的彩虹表风险；
• 复杂度校验：validate() 默认要求至少一个大写字母、一个小写字母、一个数字（requireSpecial 默认关闭），hash() 在哈希前先执行该校验；
• 时序安全验证：verify() 先校验 hash 是否为合法 bcrypt 格式（正则 ^\$2[aby]\$\d{2}\$[./A-Za-z0-9]{53}$，即 60 字符），再调用 bcrypt.compare（内部时序安全比较），任何异常一律返回 false 以抑制时序侧信道；
• 平滑升级能力：needsRehash() 从 $2b$XX$... 中解析历史 rounds，低于当前配置即提示重哈希，使成本因子可以随硬件演进逐步上调。

值得注意的一个工程细节（源码 L16-L22 注释）：模块已从 bcrypt 切换到纯 JS 实现 bcryptjs，目的是切断 @mapbox/node-pre-gyp → tar <=7.5.10 这条引入了 6 个 HIGH 级 CVE 的传递依赖链；由于 bcryptjs 产出相同的 $2a$/$2b$ 哈希格式与 hash()/compare() API，该替换对调用方和已持久化的哈希完全透明——这是"安全修复本身不能引入新的供应链风险"的典型案例。

CVE-3 修复：CredentialGenerator（crypto.randomBytes）

credential-generator.ts 用密码学安全随机数替代硬编码默认凭据：

• 长度底线（validateConfig()，L123-L144）：密码至少 16 字符（默认 32）、API key 至少 32 字符（默认 48）、secret 至少 32 字符（默认 64），低于底线直接抛 CredentialGeneratorError；
• 拒绝采样消除模偏差：generateSecureString()（L154 起）基于 crypto.randomBytes 做拒绝采样（rejection sampling），对字节值取模前拒绝超出均匀分布范围的样本，确保每个字符在字符集中概率均等——这是很多"简单取模"实现会忽略的熵质量细节；
• 输出结构：generateInstallationCredentials() 产出 adminPassword、servicePassword、jwtSecret、sessionSecret、encryptionKey 及 generatedAt，API key 则采用 URL-safe 字符集（字母数字 + -_）并附 keyId（UUID）便于轮换审计。

修复追踪与程序化验收

技能文件的验证标准（Validation Criteria）是：所有 CVE 均有已测试的修复、npm audit 显示 0 个 high/critical 漏洞、安全模式完成文档化并落地、威胁模型覆盖全部 V3 域、建立安全测试框架。

仓库用 CVE-REMEDIATION.ts 把"验收"变成了可执行代码：

• validateRemediation()（L524-L543）：遍历 CVE_REGISTRY，仅当所有条目 remediationStatus === 'fixed' 且 testStatus === 'passing' 时才返回 allFixed: true，否则返回逐条问题清单；
• getRemediationReport()（L548 起）：自动生成 Markdown 格式的《V3 Security Remediation Report》，汇总总数/已修复/待定/CVSS 分数/GHSA 编号，以及 SECURITY_PATTERNS 的完整实现对照表（算法、参数、理由）；
• 每个 CVE 条目都绑定了对应的测试文件，与技能文件"测试覆盖 >95%"的要求呼应。实际的测试文件位于 tests 目录：password-hasher.test.ts、credential-generator.test.ts、safe-executor.test.ts、path-validator.test.ts、input-validator.test.ts、token-generator.test.ts 以及 acceptance/security-compliance.test.ts 等。

SECURITY_PATTERNS 常量（L446-L480）则把六大模式固化为一等公民的数据结构：bcrypt 12 rounds、crypto.randomBytes 最小熵（密码 32 / secret 64）、execFile + 白名单、path.resolve + 前缀检查 + 符号链接解析 + 遍历模式拦截、zod 校验 + 净化、npm overrides 钉住传递依赖——每一项都附 rationale 说明设计理由，这正是技能文件要求产出的 SECURE-PATTERNS.md 的"代码化"形态。

交付物、协同分工与成功指标

技能文件定义的 Phase 1（Week 1-2）交付物为四份文档：SECURITY-ARCHITECTURE.md（完整威胁模型）、CVE-REMEDIATION-PLAN.md（详细修复时间线）、SECURE-PATTERNS.md（可复用安全模式）、THREAT-MODEL.md（攻击面分析）。从当前仓库状态看，其中 CVE 修复计划与安全模式已分别以 CVE-REMEDIATION.ts 的注册表/报告生成器和 SECURITY_PATTERNS 常量形式沉淀在代码库中，getRemediationReport() 可在任意时点重新生成修复报告。

在多 Agent 协作中，Security Architect（Agent #2）与下游角色有明确分工：

• Security Implementer（Agent #3）：接收架构师提供的详细实现规格，审查所有安全关键代码变更，验证 CVE 修复实现的正确性；
• Security Tester（Agent #4）：接收安全模式的测试规格，定义渗透测试要求，建立安全回归测试套件。

成功指标（Success Metrics）为：安全评分 90/100（npm audit + 自定义扫描）、100% 已识别 CVE 修复、安全关键代码测试覆盖率 >95%、完整的安全架构文档、所有交付物在 Phase 1 内完成。

实战：在项目中启用 @claude-flow/security

上述架构最终落地为可独立使用的库 @claude-flow/security（模块 README）。createSecurityModule() 一次装配全部组件：

import { createSecurityModule } from '@claude-flow/security';

const security = createSecurityModule({
  projectRoot: '/workspaces/project',
  hmacSecret: process.env.HMAC_SECRET!,
  bcryptRounds: 12,
  allowedCommands: ['git', 'npm', 'node']
});

const hash = await security.passwordHasher.hash('userPassword123');
const pathResult = await security.pathValidator.validate('/workspaces/project/src/file.ts');
const output = await security.safeExecutor.execute('git', ['status']);
const creds = await security.credentialGenerator.generate();

由于每个原语（PasswordHasher、PathValidator、SafeExecutor、InputValidator、CredentialGenerator）都可独立导入，无需 CLI、MCP 服务器或守护进程，任何需要在系统边界做校验的 Node 应用都可以直接复用：

import {
  InputValidator, EmailSchema, PasswordHasher, createCredentialGenerator,
  createDevelopmentExecutor, createProjectPathValidator,
} from '@claude-flow/security';

// 1. 边界输入校验（非法即抛错，合法则返回类型化值）
const email = InputValidator.validate(EmailSchema, '[e-mail]');

// 2. bcrypt 哈希（CVE-2 修复）
const hasher = new PasswordHasher({ rounds: 12 });
const hash = await hasher.hash('CorrectHorseBatteryStaple9');
const ok = await hasher.verify('CorrectHorseBatteryStaple9', hash); // true

// 3. 高熵 API key（CVE-3 修复），底层 crypto.randomBytes，拒绝低于 32 字节熵
const creds = createCredentialGenerator();
const apiKey = creds.generateApiKey('ck_live_');

// 4. 白名单命令执行（HIGH-1 修复）
const exec = createDevelopmentExecutor({ projectRoot: process.cwd() });
const { stdout } = await exec.execute('git', ['status', '--porcelain']);

// 5. 路径遍历拒绝（HIGH-2 修复）
const paths = createProjectPathValidator(process.cwd());
const result = await paths.validate('../../etc/passwd');
if (!result.isValid) console.log('blocked:', result.errors.join('; '));
// → blocked: Path traversal pattern detected

模块还暴露了安全常量与安全配置审计：MIN_BCRYPT_ROUNDS = 12、MAX_BCRYPT_ROUNDS = 14、MIN_PASSWORD_LENGTH = 8、MAX_PASSWORD_LENGTH = 72（bcrypt 上限）、DEFAULT_TOKEN_EXPIRATION = 3600、DEFAULT_SESSION_EXPIRATION = 86400；auditSecurityConfig()（index.ts L356 起）会对不达标配置输出告警，例如 bcryptRounds (10) below recommended minimum (12)、hmacSecret should be at least 32 characters。

小结

ruflo 的 V3 Security Architect 技能展示了一种可复制的 Agent 安全架构方法论：先以威胁模型划定 API 边界、认证、授权、Agent 通信、存储五层防线；再把 CVE-1 至 HIGH-2 逐项转化为带文件位置与时间线的修复计划；随后将修复固化为可程序化验收的 CVE_REGISTRY + 测试套件，把安全模式固化为可独立复用的 @claude-flow/security 原语；最后通过 Agent #2（架构）→ #3（实现）→ #4（测试）的分工闭环保障交付质量。对读者而言，这套"威胁建模 → 修复计划 → 模式目录 → 程序化验收"的完整链路，以及其中 bcrypt 12 rounds、crypto 随机凭据 + 拒绝采样、无 Shell 白名单执行、对称路径规范化等具体技术决策，均可直接迁移到任何需要默认安全的 TypeScript 系统边界设计中。