security-patterns

安全模式

用于构建强化型应用的全面安全模式。每个类别都在 rules/ 中有单独的规则文件，并按需加载。

快速参考

类别	规则	影响	使用场景
身份验证	upstream	严重	JWT 令牌、OAuth 2.1/PKCE、RBAC/权限
纵深防御	1	严重	多层安全、零信任架构
输入验证	2	高	架构验证（Zod/Pydantic）、输出编码、文件上传
OWASP Top 10	1	严重	注入防护、修复身份验证漏洞
LLM 安全	refs	高	提示词注入防御、输出护栏、内容过滤
PII 脱敏	refs	高	使用 Presidio、Langfuse、LLM Guard 检测/脱敏 PII
扫描	upstream	高	依赖项审计、SAST（Semgrep/Bandit）、密钥检测
高级护栏	2	严重	NeMo/Guardrails AI 验证器、红队测试、OWASP LLM

共：4 个类别中的 6 个规则文件。 标记为 “upstream” 或 “refs” 的主题仅在此处保留 ork 差异：本文件中的底线要求和关键决策、references/ork-delta.md 中的经验教训和项目决策，以及 上游覆盖内容中的一手资料。

快速开始

# Argon2id password hashing
from argon2 import PasswordHasher
ph = PasswordHasher()
password_hash = ph.hash(password)
ph.verify(password_hash, password)

# JWT access token (15-min expiry)
import jwt
from datetime import datetime, timedelta, timezone
payload = {
    'sub': user_id, 'type': 'access',
    'exp': datetime.now(timezone.utc) + timedelta(minutes=15),
}
token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')

// Zod v4 schema validation
import { z } from 'zod';
const UserSchema = z.object({
  email: z.email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin']).default('user'),
});
const result = UserSchema.safeParse(req.body);

# PII masking with Langfuse
import re
from langfuse import Langfuse

def mask_pii(data, **kwargs):
    if isinstance(data, str):
        data = re.sub(r'\b[\w.-]+@[\w.-]+\.\w+\b', '[REDACTED_EMAIL]', data)
        data = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[REDACTED_SSN]', data)
    return data

langfuse = Langfuse(mask=mask_pii)

身份验证

使用 OAuth 2.1、Passkeys/WebAuthn、JWT 令牌和基于角色的访问控制来实现安全身份验证。

JWT、OAuth 2.1/PKCE/DPoP、Passkeys/WebAuthn、RBAC 和 MFA 的实现教程均由上游覆盖（参见上游覆盖内容）。包括 argon2-cffi 优于 passlib 这一经验教训在内的 ork 差异，位于 references/ork-delta.md。

关键决策： Argon2id > bcrypt | 访问令牌有效期 15 分钟 | 必须使用 PKCE | Passkeys > TOTP > SMS

纵深防御

采用无单点故障的多层安全架构。

规则	描述
defense-layers.md	8 层安全架构（从边缘层到可观测性）

零信任和租户隔离实现方案（租户范围的仓库、 RLS、按租户键控的缓存）由上游覆盖；不可变的 RequestContext 模式 保留在 references/request-context-pattern.md 中，经过净化的审计日志记录则位于 references/audit-logging.md。

关键决策： 不可变数据类上下文 | 在查询层面进行租户过滤 | LLM 提示词中不包含 ID

sandbox.network.deniedDomains（CC 2.1.113+）

在网络层实施阻止列表，在 Bash/WebFetch 出站流量发出前进行拦截——与钩子层的 DENY_PATTERNS 配合，实现纵深防御。设置示例：

"sandbox": {
  "network": {
    "deniedDomains": ["*.evil.com", "pastebin.com", "transfer.sh"]
  }
}

支持通配符（*.example.com、evil.com/*/malicious/*）。插件在 src/settings/ork.settings.json 中提供基线列表；项目设置可对其进行扩展。适用场景：提示词注入数据外传目标、已知恶意注册表、绕过审计的粘贴服务。

sandbox.credentials（CC 2.1.187+）

阻止沙箱化的 Bash 读取凭据文件和机密环境变量，作为 sandbox.filesystem.denyRead 的纵深防御。各作用域的设置会合并（任何作用域都可以添加，均无法移除）；较旧版本的 CC 会忽略此键。mode 可以是 deny，或从 CC 2.1.221 起支持的 mask。设置示例：

"sandbox": {
  "credentials": {
    "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
    "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
  }
}

ork 不提供 sandbox.credentials 基线：CC 只会读取插件设置文件中的 permissions 键，因此，原先位于 src/settings/ork.settings.json 的规则已在 #3357 中移除，因为它不会生效。请在用户设置或托管设置中配置此项（拒绝访问 ~/.aws/credentials、~/.ssh、~/.gnupg、~/.netrc、~/.npmrc，以及可能劫持 git-push 身份验证的令牌环境变量）。配合 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 使用，可在不考虑沙箱状态的情况下清除所有子进程凭据。

使用掩码而非拒绝。 从 CC 2.1.221 起，在 Linux 和 WSL 上，凭据文件条目可以使用 mode: "mask"：沙箱化的命令会读取哨兵副本（整个文件，或仅 extract 正则表达式捕获的范围），沙箱代理则会在数据外发时替换为真实值。macOS 上的文件掩码会回退为 deny，因此在 Mac 上使用它并不比 mode: deny 多任何作用。更丰富的选项从 CC 2.1.224 起提供：除了 mode: deny，还可以对凭据进行掩码，让命令仍能使用已编辑的值运行：extract 和 onExtractNoMatch 可从结构化环境变量值中提取机密，decode: "jwt" 配合 maskClaims 可对指定的 JWT 声明进行掩码，而 awsPairs/sigv4 会在掩码后重新签署 AWS SigV4 请求。以下两项限制决定了这些选项是否可用：

• 这些选项需要 sandbox.network.tlsTerminate，因此仅适用于由 CC 终止的流量。
• 这些选项仅接受用户设置、托管设置或 --settings 中的配置。插件提供的值或项目 .claude/settings.json 中设置的值都会被忽略，因此 ork 无法像提供拒绝列表那样将这些选项作为基线提供。请将这些选项记录下来供运维人员参考；不要将它们添加到 src/settings/ork.settings.json 并期待其生效。

拒绝路径末尾绝不要加斜杠。 在 CC 2.1.223 及更早版本中，以 / 结尾的 sandbox.filesystem 拒绝条目（例如 denyRead: "~/.aws/"）在 Linux 和 macOS 上可以被悄悄绕过：规则能解析，检查结果也显示正常，却没有任何保护作用。此问题已在 2.1.224 中修复，但仍建议避免这种写法，因为无论如何，它看起来都像是提供了保护。ork 提供的值（~/.aws/credentials、~/.ssh/*、~/.gnupg/*）从未受此问题影响。

输入验证

使用 Zod v4 和 Pydantic 验证并清理所有不可信输入。

规则	描述
validation-input.md	使用 Zod v4 和 Pydantic 进行架构验证、类型强制转换
validation-output.md	HTML 清理、输出编码、XSS 防护

高级架构示例（判别联合、文件上传验证、URL 允许列表）以及完整的 Zod v4 API 已由上游覆盖；Zod v4 而非 v3 的易错点列表见 references/ork-delta.md，带类型的架构示例见 scripts/validation-schemas.ts。

关键决策： 允许列表优先于阻止列表 | 始终在服务端验证 | 验证魔数，而非扩展名

OWASP Top 10

防护最关键的 Web 应用安全风险。

规则	描述
supply-chain.md	锁文件完整性、依赖项混淆、来源证明、SBOM（A03:2025）

注入防护（SQL/命令/SSRF）、身份验证缺陷修复（JWT 算法混淆、 CSRF、时序攻击），以及易受攻击与安全实现的演示，均已由上游覆盖；请参阅 上游覆盖（不要重复编写）。

关键决策： 仅使用参数化查询 | 硬编码 JWT 算法 | 使用 SameSite=Strict Cookie

大模型安全

用于大模型集成的安全模式，包括上下文隔离和输出验证。

参考资料	描述
references/context-separation.md	上下文隔离架构、禁止使用的模式
references/prompt-audit.md	提示词审计、安全的提示词构建器
references/output-guardrails.md	输出验证流程：架构、依据、安全性、大小
references/pre-llm-filtering.md	租户范围内的检索、内容提取
references/post-llm-attribution.md	确定性归因（三阶段模式）

关键决策： ID 在大模型之外流转，绝不经过大模型 | 归因具有确定性 | 审计每条提示词

上下文隔离（严重）

敏感 ID 和数据在大模型之外流转，绝不经过大模型。大模型只能看到内容——映射回实体的操作会在之后以确定性方式完成。

# CORRECT: IDs bypass the LLM
context = {"user_id": user_id, "tenant_id": tenant_id}  # kept server-side
llm_input = f"Summarize this document:\n{doc_text}"       # no IDs in prompt
llm_output = call_llm(llm_input)
result = {"summary": llm_output, **context}               # IDs reattached after

输出验证流程

每条大模型响应在交付给用户之前，都必须通过包含 4 个阶段的防护流程：

def validate_llm_output(raw_output: str, schema, sources: list[str]) -> str:
    # 1. Schema — does it match expected structure?
    parsed = schema.parse(raw_output)
    # 2. Grounding — are claims supported by source documents?
    assert_grounded(parsed, sources)
    # 3. Safety — toxicity, PII leakage, prompt leakage
    assert_safe(parsed, max_toxicity=0.5)
    # 4. Size — prevent token-bomb responses
    assert len(parsed.text) < MAX_OUTPUT_CHARS
    return parsed.text

PII 屏蔽

用于大模型可观测性流程和日志记录的 PII 检测与屏蔽。

参考资料	描述
references/presidio-integration.md	Microsoft Presidio 设置、自定义识别器
references/langfuse-mask-callback.md	Langfuse SDK 屏蔽实现

LLM Guard 的匿名化/去匿名化与 Vault 以及 structlog/loguru 脱敏处理器已在上游涵盖；请参阅上游覆盖范围（不要重复说明）。

关键决策： 企业级场景使用 Presidio | 替换为类型令牌 | 在初始化时使用屏蔽回调

扫描

对依赖项、代码和机密进行自动化安全扫描。工具教程 （npm audit、pip-audit、Trivy、Semgrep、Bandit、Gitleaks、TruffleHog、detect-secrets） 已在上游涵盖；可运行的项目流水线是 scripts/scan-vulnerabilities.sh， 强制执行而非仅提供建议的仓库门禁（推送前安全套件、CI gitleaks）记录在 references/ork-delta.md 中。

关键决策： 使用提交前钩子左移安全检查 | 对严重/高危问题进行阻断 | Gitleaks + detect-secrets 基线

高级防护

使用 NeMo Guardrails、Guardrails AI 验证器和 DeepTeam 红队测试，保障生产环境中的大模型安全。

规则	描述
guardrails-nemo.md	NeMo Guardrails、Colang 2.0 流程、Guardrails AI 验证器、分层验证
guardrails-llm-validation.md	DeepTeam 红队测试（40+ 种漏洞）、符合 OWASP LLM Top 10

关键决策： 流程使用 NeMo，验证器使用 Guardrails AI | 毒性阈值 0.5 | 发布前及每季度进行红队测试

上游内容覆盖范围（无需重述）

这些主题已从此技能中移除，以避免重复供应商内容。请参阅第一方 资料；此处仅保留 ork 的差异内容（底线、经验教训、项目决策），见 references/ork-delta.md。

主题	第一方资料
JWT 实现 + 密码哈希（PyJWT、Argon2id）	https://pyjwt.readthedocs.io/ + https://argon2-cffi.readthedocs.io/
OAuth 2.1、PKCE、DPoP、Passkeys/WebAuthn 流程	https://oauth.net/2.1/ + https://www.w3.org/TR/webauthn-3/ + https://github.com/duo-labs/py_webauthn
RBAC 装饰器、MFA/TOTP、速率限制、身份验证清单	OWASP Cheat Sheet Series：https://cheatsheetseries.owasp.org/（Authentication、Session Management、MFA）
零信任租户隔离（租户范围的仓库、RLS、按租户键控的缓存）	PostgreSQL RLS：https://www.postgresql.org/docs/current/ddl-rowsecurity.html + OWASP LLM08：https://genai.owasp.org/
Zod v4 API + 验证方案（强制转换、联合类型、文件/URL 架构）	https://zod.dev (context7: /colinhacks/zod) + https://docs.pydantic.dev/
OWASP Top 10 易受攻击与安全示例（注入、XSS、CSRF、JWT 混淆、时序攻击）	https://owasp.org/Top10/ + https://cheatsheetseries.owasp.org/
LLM 提示词注入防御 + 输出护栏教程	OWASP LLM Top 10：https://genai.owasp.org/llm-top-10/
使用 LLM Guard 清理 PII（Anonymize/Deanonymize/Vault）	https://protectai.github.io/llm-guard/
使用 structlog/loguru 在记录日志前进行脱敏	https://www.structlog.org/ + https://loguru.readthedocs.io/
依赖项、密钥和 SAST 扫描工具	https://semgrep.dev/docs/ + https://github.com/gitleaks/gitleaks + https://trufflesecurity.com/trufflehog + https://bandit.readthedocs.io/

托管钩子层级（CC 2.1.49）

插件设置遵循 3 层优先级：

层级	来源	可覆盖？
1. 托管（插件 settings.json）	插件作者提供默认值	可以，由用户覆盖
2. 项目（.claude/settings.json）	仓库配置	可以，由用户覆盖
3. 用户（~/.claude/settings.json）	个人偏好	最终决定权

OrchestKit 提供的安全钩子是托管默认设置——用户可以禁用，但会收到警告。企业管理员可以通过托管配置文件锁定设置。

**CC 2.1.166 — 托管设置强制执行修复：**在 2.1.166 之前，托管设置中的单个无效条目会悄无声息地导致所有其余有效策略的强制执行失效——一个拼写错误就可能使整个安全锁定形同虚设。依赖托管配置文件时，请使用 2.1.166+，并在部署前验证文件。同一版本还修复了使用 ${VAR} 引用时，allowedMcpServers/deniedMcpServers 谓词无法匹配的问题。

**CC 2.1.160 — 写入提示：**Claude Code 现在会在写入 shell 启动文件（.zshenv、.zlogin、.bash_login、~/.config/git/）之前提示；在 acceptEdits 模式下，也会在写入允许代码执行的构建工具配置（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/）之前提示。请将这些视为纵深防御默认设置：有意批准，而不是一概允许。

权限规则语义（≥ 2.1.166）：allow/ask/deny 规则新增了与安全相关的行为——Read deny 现在会在 Glob/Grep 中隐藏文件，deny 工具名称支持 glob（"*" = 默认拒绝），显式的 WebFetch(domain:…) 会覆盖预先批准主机的自动允许，从其他会话转发的 SendMessage 不携带权限，组织托管规则适用于整个会话。完整模型和推荐的基线 settings.json，请参阅 references/cc-permission-model.md。

**跨会话回复会发送到父会话（CC 2.1.248）：**当子 Agent 向另一个会话发送 SendMessage 时，回复会发送到父会话的对话中，而不会发送给子 Agent；子 Agent 发送后继续执行，由父会话读取回复。跨会话 SendMessage / ListAgents 也可在 Bedrock、Vertex 和 Foundry 上使用，并且在禁用遥测时也能使用（CC 2.1.248）。

反模式（禁止）

# Authentication
user.password = request.form['password']       # Plaintext password storage
response_type=token                             # Implicit OAuth grant (deprecated)
return "Email not found"                        # Information disclosure

# Input Validation
"SELECT * FROM users WHERE name = '" + name + "'"  # SQL injection
if (file.type === 'image/png') {...}               # Trusting Content-Type header

# LLM Safety
prompt = f"Analyze for user {user_id}"             # ID in prompt
artifact.user_id = llm_output["user_id"]           # Trusting LLM-generated IDs

# PII
logger.info(f"User email: {user.email}")           # Raw PII in logs
get_client().start_observation(name="llm", input=raw_prompt)  # Unmasked observability data

详细文档

使用 Read("references/<file>") 按需加载：

文件	内容
ork-delta.md	从已移除的上游重复说明中保留下来的 Ork 专属经验教训和内部决策
cc-permission-model.md	CC allow/ask/deny 规则语义（≥2.1.166）：Read-deny 在 Glob/Grep 中隐藏内容、deny-glob、WebFetch 优先级、跨会话授权、组织托管规则
request-context-pattern.md	用于身份流转的不可变请求上下文
audit-logging.md	脱敏结构化日志、合规性
context-separation.md	大模型上下文分离架构
output-guardrails.md	输出验证流水线实现
pre-llm-filtering.md	租户范围内的检索、内容提取
post-llm-attribution.md	确定性归因模式
prompt-audit.md	提示词审计模式、安全的提示词构建器
presidio-integration.md	Microsoft Presidio 设置、自定义识别器
langfuse-mask-callback.md	Langfuse SDK 掩码实现

相关技能

• api-design-framework - API 安全模式
• ork:rag-retrieval - 需要租户范围内检索的 RAG 流水线模式
• llm-evaluation - 输出质量评估，包括幻觉检测

能力详情

authentication

关键词： password、hashing、JWT、token、OAuth、PKCE、passkey、WebAuthn、RBAC、session 解决的问题：

• 使用现代标准实现安全身份验证
• 正确管理 JWT 令牌过期时间
• 使用 PKCE 流程实现 OAuth 2.1
• Passkeys/WebAuthn 注册和登录
• 基于角色的访问控制

defense-in-depth

关键词： 深度防御、安全层、多层、请求上下文、租户隔离 解决的问题：

• 如何端到端保护 AI 应用
• 实施 8 层安全架构
• 创建不可变请求上下文
• 确保查询级别的租户隔离

cc-subprocess-hardening (CC 2.1.98)

关键词： 子进程、沙箱、PID 命名空间、环境变量清理、脚本上限 解决的问题：

• 限制失控的钩子脚本：CLAUDE_CODE_SCRIPT_CAPS=100
• 从子进程中清除凭据：CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1
• 在 Linux 上通过 PID 命名空间隔离子进程沙箱
• 防止通过反斜杠转义和复合命令绕过 Bash 权限

CC 2.1.128 — SDK 宿主“始终允许”持久化：当用户在 SDK 宿主的 Bash 权限提示中选择“始终允许”时，授权现在会通过 .claude/settings.local.json 持久保存，不再于会话结束时失效。请审查 SDK 消费方的 .gitignore，确认其中排除了 .claude/settings.local.json ——提交该文件会泄露每位开发者的 Bash 授权。项目提交的 .claude/settings.json 不变；只有用户机器本地文件会收到新条目。

CC 2.1.169 — 强制执行托管 MCP 策略 + OTEL 证书路径信任：已修复两类策略绕过问题。企业 allowedMcpServers/deniedMcpServers 策略在重新连接、IDE 中输入的配置、安装后首次会话中的 --mcp-config 服务，以及远程设置加载前均未得到强制执行——请将任何 2.1.169 之前的托管 MCP 审计视为未覆盖这些路径。而且，不受信任的项目设置可以在未经信任确认的情况下设置 OTEL 客户端证书路径（克隆的仓库可能会将遥测指向攻击者的证书）；现在此操作已受信任机制保护。这两项修复都已包含在 ork 的最低版本（2.1.220）中。

CC 2.1.163 — 主目录路径拒绝规则现在涵盖 $HOME Bash 引用：修复之前，Read(~/.ssh/**) 这样的拒绝规则会阻止 Read 工具，但不会阻止通过 $HOME/.ssh/... 访问同一文件的 Bash 命令——这是一个隐蔽的机密读取绕过问题。如果你通过权限拒绝规则限制对主目录机密（例如 ~/.aws/credentials、~/.ssh/*、~/.gnupg/*）的访问，请将 CC 最低版本固定为 >= 2.1.163；较旧版本（< 2.1.163）仍会放行 Bash 路径——ork 的最低版本现为 2.1.220，已包含此修复。

input-validation

关键词： 架构、验证、Zod、Pydantic、净化、HTML、XSS、文件上传 解决的问题：

• 根据架构验证输入（Zod v4、Pydantic）
• 使用允许列表防止注入攻击
• 净化 HTML 并防止 XSS
• 根据魔数验证文件上传

owasp-top-10

关键词： OWASP、SQL 注入、访问控制失效、CSRF、XSS、SSRF 解决的问题：

• 修复 OWASP Top 10 漏洞
• 防止 SQL 和命令注入
• 实施 CSRF 防护
• 修复身份验证失效

llm-safety

关键词： 提示词注入、上下文隔离、护栏、幻觉、LLM 输出 解决的问题：

• 防止提示词注入攻击
• 实施上下文隔离（在 LLM 周围使用 ID）
• 通过护栏流水线验证 LLM 输出
• 确定性地进行 LLM 后归因

pii-masking

关键词： PII、掩码、Presidio、Langfuse、脱敏、GDPR、隐私 解决的问题：

• 检测并掩码 LLM 流水线中的 PII
• 将掩码与 Langfuse 可观测性集成
• 实施日志记录前脱敏
• 符合 GDPR 的数据处理