安全策略执行Hook：安全规则自动执行

一、安全策略执行Hook的设计

安全策略执行Hook是一种在Claude Code操作执行之前拦截并检查安全合规性的守护机制。其核心设计理念是"预防优于补救"：在实际操作发生之前，Hook会逐条校验当前操作是否违反预定义的安全规则，只有通过全部检查的操作才会被放行执行。

该Hook采用前置拦截（before-hook）模式，在工具调用（Tool Call）触发前进行安全检查。一旦检测到违规，Hook可以选择阻断执行、记录告警、通知管理员或者执行预设的应急响应流程。整个检查过程对Claude Code透明，无需人工干预。

设计原则：最小权限原则（Least Privilege）——默认拒绝一切，仅放行明确允许的操作。所有检查规则遵循"白名单优先、黑名单辅助"的策略，确保安全基线的严格性。

Hook类型	拦截目标	检查维度	违规处理
命令执行Hook	before:tool/Bash	命令白名单、黑名单、参数校验	阻断 + 告警
文件操作Hook	before:tool/Write + Edit	路径范围、敏感文件保护	阻断 + 审计日志
网络请求Hook	before:tool/Fetch	IP黑白名单、SSRF检测	阻断 + 告警
配置变更Hook	before:tool/Edit	安全配置文件保护	阻断 + 审批通知

二、命令执行策略Hook（before:tool/Bash）

命令执行策略Hook是所有安全Hook中最关键的一环。它拦截before:tool/Bash事件，检查Claude Code即将执行的Shell命令是否安全合规。恶意或危险的Shell命令是攻击者最常用的攻击向量，因此该Hook需要具备精细的检测能力。

高风险命令黑名单：以下类型的命令必须无条件阻断——rm -rf /（系统级删除）、sudo命令（权限提升）、向内网IP发起的curl请求（SSRF探测）、加密挖矿类命令、反向Shell创建命令、以及任何尝试绕过安全检查的行为。

白名单策略：为了不干扰正常开发工作，需要建立一套经过安全审核的命令白名单。日常开发中常用的安全命令应当被放行，例如：git系列命令（版本控制）、npm/pnpm/yarn（包管理）、pip（Python包管理）、ls/cat/head/tail（文件查看）、mkdir/cp/mv（基础文件操作）等。

正则匹配增强：仅仅匹配命令名是不够的，必须结合参数进行深度检测。例如rm命令本身是安全的，但rm -rf /是危险的；curl命令是常用的，但curl http://10.0.0.1:8080可能是在进行内网探测。通过正则表达式匹配合法参数模式，可以有效降低误报率。

# 命令执行策略Hook示例（伪代码）
function beforeBashHook(command) {
    // 1. 黑名单检测 - 优先阻断高危命令
    const blacklist = [
        /^sudo\s+/,
        /^rm\s+.*\-rf\s+\/$/,
        /^curl\s+.*(?:10\.|172\.1[6-9]\.|192\.168\.)/,
        /^nc\s+/,
        /^bash\s+-i\s+>/,
        /xmr|minerd|cryptonight/
    ];
    for (pattern of blacklist) {
        if (pattern.test(command)) {
            return block("阻断高危命令: " + command);
        }
    }

    // 2. 白名单检测 - 只允许已知安全命令
    const whitelist = [
        /^git\s+/,
        /^npm\s+/,
        /^pnpm\s+/,
        /^yarn\s+/,
        /^pip\s+/,
        /^ls\s*/,
        /^cat\s+/,
        /^head\s+/,
        /^tail\s+/,
        /^mkdir\s+/,
        /^cp\s+/,
        /^mv\s+/,
        /^echo\s+/
    ];
    let allowed = false;
    for (pattern of whitelist) {
        if (pattern.test(command)) {
            allowed = true;
            break;
        }
    }

    if (!allowed) {
        logViolation("非白名单命令", command);
        return block("命令不在白名单中，已阻断: " + command);
    }

    return allow(command);
}

最佳实践：命令白名单应当按项目环境差异化配置。开发环境可适当放宽限制，生产环境则必须严格执行最小权限原则。建议将白名单策略配置文件纳入版本管理，变更需要经过代码审查（Code Review）。

三、文件操作范围限制Hook（before:tool/Write + Edit）

文件操作范围限制Hook负责拦截Claude Code对文件系统的写入和修改操作，确保所有文件变更都在允许的项目目录范围内进行。这一Hook可以防止恶意代码越权修改系统关键文件或安全配置文件。

该Hook监听before:tool/Write和before:tool/Edit两个事件，在每次文件写入操作触发前验证目标路径的合法性。检查维度包括：路径是否在项目沙箱目录内、目标文件是否为系统保护文件、目标文件是否为安全配置文件等。

# 文件操作范围检查Hook示例
function beforeWriteEditHook(filePath) {
    // 解析绝对路径，防止符号链接绕过
    const realPath = resolveSymlinks(path.resolve(filePath));
    const projectRoot = path.resolve("/allowed/project/directory");

    // 1. 检查是否在项目目录内
    if (!realPath.startsWith(projectRoot)) {
        logViolation("越权文件操作", filePath);
        return block("文件操作超出允许范围: " + filePath);
    }

    // 2. 禁止修改系统关键文件
    const systemFiles = [
        "/etc/passwd",
        "/etc/shadow",
        "/etc/sudoers",
        "/boot/",
        "/etc/ssh/",
        "/root/.ssh/"
    ];
    for (sysPath of systemFiles) {
        if (realPath.startsWith(sysPath)) {
            return block("禁止修改系统关键文件: " + filePath);
        }
    }

    // 3. 禁止修改安全配置文件
    const securityConfigs = [
        "/.env",
        "/.env.local",
        "/security-policy.json",
        "/.ssh/authorized_keys",
        "/.git/config",
        "/settings.json",
        "/settings.local.json"
    ];
    for (configFile of securityConfigs) {
        if (realPath.endsWith(configFile)) {
            return block("禁止修改安全配置文件: " + filePath);
        }
    }

    // 4. 记录审计日志
    logAudit("文件操作已放行", filePath);

    return allow(filePath);
}

审计日志字段：每次越权文件操作都会被详细记录，包括操作时间、用户身份、目标文件路径、操作类型（Write/Edit）、阻断原因、以及操作的完整上下文信息。审计日志应定期汇总分析，用于生成安全态势报告。

重要提醒：路径校验需要特别注意符号链接（Symlink）和路径穿越攻击（Path Traversal）。攻击者可能通过创建符号链接将写入路径重定向到系统关键区域，或者使用../../路径穿越语法逃逸沙箱目录。必须使用fs.realpathSync()或等效方法解析真实路径后再进行校验。

四、网络请求限制Hook（before:tool/Fetch）

网络请求限制Hook用于控制Claude Code对外部网络的访问行为，防止数据泄露、SSRF攻击和内网探测。该Hook拦截before:tool/Fetch事件，在每次HTTP请求发起之前检查目标URL的合规性。

网络请求的安全检查是多维度的：首先验证目标IP地址是否属于内网保留段，然后检查请求域名是否在可信域名白名单中，最后对HTTP请求头和请求体进行安全扫描，防止通过HTTP请求携带敏感数据。

# 网络请求限制Hook示例
function beforeFetchHook(url) {
    const parsedUrl = new URL(url);

    // 1. 内网IP阻断（SSRF防护）
    const internalIPs = [
        /^10\.\d{1,3}\.\d{1,3}\.\d{1,3}/,       // 10.x.x.x
        /^172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}/, // 172.16-31.x.x
        /^192\.168\.\d{1,3}\.\d{1,3}/,          // 192.168.x.x
        /^127\./,                                 // localhost
        /^0\./                                      // 特殊地址
    ];
    const hostname = parsedUrl.hostname;
    for (pattern of internalIPs) {
        if (pattern.test(hostname)) {
            logViolation("SSRF攻击尝试", url);
            return block("禁止请求内网地址: " + url);
        }
    }

    // 2. 可信域名白名单
    const allowedDomains = [
        /^api\.github\.com$/,
        /^api\.openai\.com$/,
        /^api\.anthropic\.com$/,
        /^registry\.npmjs\.org$/,
        /^pypi\.org$/,
        /^raw\.githubusercontent\.com$/
    ];
    let allowed = false;
    for (pattern of allowedDomains) {
        if (pattern.test(hostname)) {
            allowed = true;
            break;
        }
    }

    if (!allowed) {
        logViolation("未授权网络请求", url);
        return block("网络请求目标不在白名单中: " + url);
    }

    return allow(url);
}

扩展建议：对于需要频繁访问的外部API域名，可以在策略配置中设置"临时放行"机制，允许开发人员通过审批流程临时添加可信域名到白名单中。临时放行应当设置有效期（如24小时），过期后自动移除。

HTTP请求头安全检查：除了检查目标URL之外，Hook还应当检查请求头中是否包含敏感信息。例如，禁止在请求头中携带内部认证凭据、禁止将Authorization头设置为内部系统Token、禁止通过Cookie头泄露会话信息等。

五、安全策略配置管理

安全策略配置管理是整个安全Hook体系的基础设施。所有安全规则都应当通过独立的策略配置文件进行集中管理，而不是硬编码在Hook代码中。这使得安全策略可以在不修改代码的情况下灵活调整。

策略配置文件格式：推荐使用JSON格式管理策略配置，因为JSON结构清晰、易于解析，且支持版本控制。配置文件应当放在项目根目录的.claude/或security/目录下，命名为security-policy.json。

// security-policy.json 配置文件示例
{
    "version": "1.0",
    "environment": "development",
    "commandPolicy": {
        "blacklist": [
            "^sudo\\s+",
            "^rm\\s+.*-rf\\s+/",
            "^nc\\s+"
        ],
        "whitelist": [
            "^git\\s+",
            "^npm\\s+",
            "^ls\\s*",
            "^cat\\s+"
        ]
    },
    "filePolicy": {
        "allowedPrefixes": ["/home/project"],
        "protectedPaths": [
            "/etc/passwd",
            "/.env",
            "/security-policy.json"
        ]
    },
    "networkPolicy": {
        "blockPrivateIP": true,
        "allowedDomains": [
            "api.github.com",
            "registry.npmjs.org"
        ]
    },
    "audit": {
        "logLevel": "info",
        "alertOnViolation": true,
        "reportSchedule": "daily"
    }
}

按项目/环境差异化配置：不同的项目具有不同的安全需求。例如，前端项目不需要pip命令，后端Python项目不需要npm发布权限。支持多级配置覆盖机制：全局默认策略（适用于所有项目）→ 项目级策略（覆盖全局）→ 环境级策略（开发/测试/生产环境差异配置）。

策略变更审批流程：安全策略的变更必须经过正式的审批流程，防止攻击者通过修改策略配置来绕过安全检查。建议的审批流程为：①开发人员提交策略变更PR；②安全审核人员审查变更内容；③变更通过后自动合并到主分支；④Hook热加载最新配置。任何未经审批的策略变更都应当触发安全告警。

违规统计与报告生成：安全策略执行Hook应当具备完整的违规统计和报告生成能力。每次安全规则被触发时，Hook都需要记录详细的违规信息，包括：违规时间、违规类型、具体操作内容、违规严重等级、操作用户/会话信息等。这些数据经过定期汇总分析后，可以生成安全态势报告。

报告类型	统计周期	内容	接收方
实时告警	即时	高危违规操作详情	安全管理员
日报	每日	所有违规汇总、趋势图	安全团队
周报	每周	分类统计、TOP违规类型	技术负责人
月报	每月	安全态势分析、改进建议	管理层

核心要点总结：安全策略执行Hook是Claude Code安全体系的第一道防线，通过"前置拦截、集中配置、精细检测、审计追踪"四位一体的设计理念，在保证开发效率的同时最大化安全保障。白名单+黑名单的组合策略、多层级路径校验、SSRF防护和策略配置审批流程缺一不可。

六、进一步思考

性能影响：安全Hook作为前置检查，每次工具调用都会触发，因此性能至关重要。Hook代码应当保持轻量高效，避免在网络请求或文件系统中引入显著延迟。建议使用缓存机制优化正则匹配的执行效率。

误报处理：过于严格的安全策略可能导致大量误报，影响正常开发流程。应当建立误报反馈机制，允许开发人员快速申诉被误拦截的操作，并在确认安全后将其添加到白名单中。

Hook自身保护：安全Hook自身也应当受到保护。Hook的配置文件和代码本身应当被纳入"禁止修改"名单，防止攻击者在突破第一道防线后禁用Hook。