Python:Claude Code 上的上下文感知权限守卫 - 防止误操作与数据泄露

Claude Code 只支持工具级 allow‑or‑deny 的扩展性瓶颈

Claude Code 预置的权限模型仅能对每个工具设置 allow 或 deny，缺乏对同一工具不同操作的细粒度控制。实际使用中会出现如下局面：  

• git push 可以放行，但 git push --force 可能导致历史回滚，需要额外确认。  
• rm -rf __pycache__ 属于安全清理，rm ~/.bashrc 则属于潜在破坏。  
• 仅靠 deny list 难以覆盖所有恶意路径，且维护成本随项目规模线性增长。

这些限制导致开发者在高安全要求的 CI/CD 环境或共享工作站上难以实现“最小特权”。  

基于结构化分类器的即时工具调用拦截

nah 首先对每一次工具调用执行 结构化分类，仅使用规则引擎完成，不依赖 LLM，保证毫秒级响应。下面是核心分类逻辑的 Python 示例（已封装为 nah.classifier 模块）：  

from nah import classifier

def classify_tool_call(tool, args):
    """返回 {'action': str, 'pipes': int, 'sensitive': bool}"""
    return classifier.analyze(tool, args)

• action：如 Read、Write、Bash。  
• pipes：检测管道组合（|, &&）以识别 “decode‑and‑execute” 模式。  
• sensitive：基于路径白名单或正则判断是否涉及关键目录（~/.ssh、~/.aws 等）。

分类结果直接映射到 allow / ask / block 决策，极大降低误报率。  

路径敏感度检测与项目边界约束实现

nah 对每个文件路径执行两层检查：  

1. 敏感路径库（硬编码或可配置）匹配 ~/.ssh, ~/.aws, .env 等。  
2. 项目根目录检测：只有在当前工作区（--project-root）内部的写入/编辑才被视为安全。

def is_path_allowed(path, project_root):
    if not path.startswith(project_root):
        return False               # 超出项目边界，触发 ask
    if any(path.startswith(p) for p in SENSITIVE_PATHS):
        return False               # 敏感路径，触发 ask
    return True

此机制防止恶意脚本通过相对路径逃逸到用户主目录。  

内容检查：从私钥到恶意 payload 的模式匹配

对 Write 与 Edit 操作，nah 在写入前读取文件内容并执行 正则/AST 检查，捕获以下模式：  

• 私钥标识 (-----BEGIN PRIVATE KEY-----)  
• 可能的凭证泄露 (AWS_ACCESS_KEY_ID=)  
• 可执行脚本的危险片段 (| bash, eval()

SECRET_PATTERNS = [
    r'BEGIN PRIVATE KEY',
    r'AWS_SECRET_ACCESS_KEY',
    r'\| *bash',
    r'eval\(',
]

def inspect_content(content):
    for pat in SECRET_PATTERNS:
        if re.search(pat, content, re.I):
            return False   # block
    return True

检测结果直接决定 nah（阻断）或 **nah?**（询问）状态。  

可选 LLM 层的二次判定流程

当结构化分类器返回 ask，nah 可转交给配置的 LLM（如 Claude）进行语义分析。LLM 只在剩余不确定的调用上介入，保持整体系统的 确定性 + 可解释性。  

def resolve_ask(decision_context):
    if not llm_configured():
        return 'ask'               # 保持人工确认
    return llm.evaluate(decision_context)

该层的加入提升了对复杂管道、模糊脚本的判定成功率，同时保持了 可审计日志。  

CLI 安装与系统钩子注册细节

nah 通过两步完成部署：  

1. pip install nah 将 Python 包放入用户环境。  
2. nah install 在 Claude Code 中注册 PreToolUse Hook，拦截所有工具调用。

卸载时执行 nah uninstall && pip uninstall nah 即可彻底清除。  

引入 Deterministic 分类导致的性能与复杂度权衡

• 性能：纯规则分类在本地完成，平均耗时 2‑5 ms，几乎不影响交互式使用。  
• 复杂度：规则库需随项目演进手动维护，尤其是新增敏感路径或自定义命令模式。  
• 可扩展性：加入 LLM 只在少数 “ask” 场景触发，避免大规模模型调用成本。

生产环境部署 nah 的安全参数与监控清单

• 强制项目根目录：使用 --project-root /srv/app 防止跨目录写入。  
• **禁用 --dangerously-skip-permissions**：该模式会导致钩子异步失效，必须关闭。  
• 日志聚合：将 nah 的决策日志发送至集中式 SIEM，便于事后审计。  
• LLM 备份：在高安全区间保持 LLM 离线模式，仅在必要时启用。

项目地址: https://github.com/manuelschipper/nah/