如何使用AgentSecCore

场景1：用户输入"扫描 'github' 这个 skill " 或 "扫描所有 skill"

对指定或全部 Skill 执行完整安全扫描 + 签名认证（Phase 1 环境准备 → Phase 2 逐文件安全审查 → Phase 3 签名入链）。指定单个 Skill 时，报告仅包含该 Skill 的结果。完成后 Agent 输出执行报告：

[skill-ledger] 执行报告
┌─────────────┬────────────┬──────────┬────────────┬─────────────────────┬────────┬──────────────────────┐
│ Skill       │ 状态        │ 版本     │ 状态指纹     │ 最近更新时间          │ 文件数  │ 摘要                 │
├─────────────┼────────────┼──────────┼────────────┼─────────────────────┼────────┼──────────────────────┤
│ github      │  pass      │ v000001  │ 5e2d1a8    │ 2025-04-23T15:30:00Z│ 5      │ 无风险发现            │
│ my-tool     │  warn      │ v000002  │ 9c3f7b1    │ 2025-04-23T15:31:00Z│ 3      │ 2 条 warn            │
│ docker      │  pass      │ v000002  │ 7d4e9b0    │ 2025-04-19T08:15:00Z│ 8      │ 沿用上次结果           │
└─────────────┴────────────┴──────────┴────────────┴─────────────────────┴────────┴──────────────────────┘

安全结论：
   pass: 2     warn: 1    总计： 3 个 Skill

   my-tool - 存在 2 条低风险发现：
    • obfuscated-code - 超长单行代码 (lib/encoder.js:203)
    • suspicious-network - 直连非标准端口 IP (net/client.py:88)

场景2：用户输入 "检查 'github' 这个 skill 的状态" 或 "检查所有 skill 状态"

仅检查指定或全部 Skill 的完整性状态，不执行扫描。指定单个 Skill 时，报告仅包含该 Skill。Agent 输出安全状态报告：

[skill-ledger] 安全状态报告
┌─────────────┬────────────┬──────────┬────────────┬─────────────────────┬────────┬──────────────────────┐
│ Skill       │ 状态        │ 版本     │ 状态指纹     │ 最近更新时间          │ 文件数  │ 摘要                 │
├─────────────┼────────────┼──────────┼────────────┼─────────────────────┼────────┼──────────────────────┤
│ github      │  none      │ v000001  │ 3f8a1c2    │ 2025-04-20T10:30:00Z│ 5      │ 从未扫描              │
│ docker      │  pass      │ v000002  │ 7d4e9b0    │ 2025-04-19T08:15:00Z│ 8      │ 无风险发现            │
│ my-tool     │  drifted   │ v000001  │ a91c5f3    │ 2025-04-18T14:00:00Z│ 3      │ +1 新增, ~1 修改      │
│ dev-helper  │  warn      │ v000003  │ c0b7e28    │ 2025-04-17T09:00:00Z│ 12     │ 2 条 warn            │
└─────────────┴────────────┴──────────┴────────────┴─────────────────────┴────────┴──────────────────────┘

安全结论：
  安全通过： 1 (docker)
  需关注： 3 - 1 从未扫描, 1 文件变更, 1 低风险

  my-tool: SKILL.md 和 run.py 已修改, new-helper.sh 新增
  dev-helper: obfuscated-code (utils.js:142), suspicious-network (fetch.py:58)

  建议： 对非 pass 状态的 Skill 执行安全扫描以更新状态。

Hook 自动防护

除了通过上述 Skill 主动触发外，Skill Ledger 还通过 Hook 机制在 Skill 被调用时自动执行完整性检查：

• Copilot Shell：每次调用 Skill 工具前，自动检查该 Skill 的完整性状态。当前版本为最小化干预，不会阻断执行或在用户界面输出告警，但所有校验记录均保存在日志中，可通过可观测能力查询。

• OpenClaw：通过安全插件实现相同的自动检查能力，行为与 Copilot Shell 一致。

Step 1：初始化签名密钥

agent-sec-cli skill-ledger init-keys

生成 Ed25519 密钥对（默认无口令，零交互）。密钥存放在 ~/.local/share/agent-sec/skill-ledger/ 下。

预期输出：

{
  "command": "init-keys",
  "fingerprint": "sha256:a3b1c9...",
  "publicKeyPath": "/home/user/.local/share/agent-sec/skill-ledger/key.pub",
  "privateKeyPath": "/home/user/.local/share/agent-sec/skill-ledger/key.enc",
  "encrypted": false
}

生产环境推荐启用口令保护：

# 交互式输入口令
agent-sec-cli skill-ledger init-keys --passphrase

# 或通过环境变量（适用于 CI/CD）
SKILL_LEDGER_PASSPHRASE="your-secret" agent-sec-cli skill-ledger init-keys --passphrase

Step 2：检查 Skill 完整性

# 检查单个 Skill
agent-sec-cli skill-ledger check /path/to/your-skill

# 批量检查所有已注册 Skill
agent-sec-cli skill-ledger check --all

首次检查会自动创建基线 manifest（状态为 none），后续检查将报告文件变更、签名状态和扫描结果。

预期输出：

{
  "status": "drifted",
  "skillName": "your-skill",
  "versionId": "v000001",
  "createdAt": "2025-04-20T10:30:00Z",
  "updatedAt": "2025-04-22T14:00:00Z",
  "fileCount": 5,
  "manifestHash": "sha256:3f8a1c2...",
  "added": ["new-file.sh"],

  "removed": [ ],

  "modified": ["SKILL.md"]
}

状态含义及建议操作：

Step 3：执行安全扫描 + 签名认证

当已有 findings 文件时（如由 Agent 扫描产出），可直接调用 certify：

agent-sec-cli skill-ledger certify /path/to/your-skill \
  --findings /tmp/skill-vetter-findings-your-skill.json \
  --scanner skill-vetter

预期输出：

{
  "versionId": "v000002",
  "scanStatus": "pass",
  "newVersion": true,
  "skillName": "your-skill",
  "createdAt": "2025-04-20T10:30:00Z",
  "updatedAt": "2025-04-23T15:31:00Z",
  "fileCount": 5,
  "manifestHash": "sha256:5e2d1a8..."
}

scanStatus 为聚合安全状态：pass（无风险）/ warn（低风险）/ deny（高危）。

口令提示：若密钥启用了口令保护，需通过环境变量传递：SKILL_LEDGER_PASSPHRASE="口令" agent-sec-cli skill-ledger certify ...

Step 4：查看 skill-ledger 的配置及 skill 整体状况

# 查看密钥、配置、所有 Skill 健康度
agent-sec-cli skill-ledger status

# 包含每个 Skill 详细状态
agent-sec-cli skill-ledger status --verbose

预期输出：

{
  "command": "status",
  "keys": {
    "initialized": true,
    "fingerprint": "sha256:a3b1c9...",
    "publicKeyPath": "/home/user/.local/share/agent-sec/skill-ledger/key.pub",
    "encrypted": false,
    "keyringSize": 0
  },
  "config": {
    "configPath": "/home/user/.config/agent-sec/skill-ledger/config.json",
    "customized": false,
    "skillDirPatterns": 4,
    "registeredScanners": ["skill-vetter"]
  },
  "skills": {
    "discovered": 5,
    "breakdown": { "pass": 3, "none": 1, "drifted": 1, "warn": 0, "deny": 0, "tampered": 0, "error": 0 },
    "health": "attention"
  }
}

health 标签：healthy（全部通过）/ attention（存在漂移或低风险）/ critical（存在高危或篡改）/ unscanned（从未扫描）/ empty（无已注册 Skill）。

Step 5：审计版本链（可选）

# 基础审计
agent-sec-cli skill-ledger audit /path/to/your-skill

# 同时验证快照文件哈希
agent-sec-cli skill-ledger audit /path/to/your-skill --verify-snapshots

深度验证全部历史版本的完整性——校验哈希、签名有效性和版本链接。适用于合规审计、安全事件后取证等场景。

预期输出：

{
  "valid": true,
  "versions_checked": 3,

  "errors": [ ]

}

Step 6：查看已注册扫描器（可选）

agent-sec-cli skill-ledger list-scanners

列出所有已注册的扫描器及其启用状态，用于确认 certify --scanner 可用的扫描器名称。

预期输出：

{
  "command": "list-scanners",
  "scanners": [
    { "name": "skill-vetter", "type": "skill", "parser": "findings-array", "enabled": true, "description": "Agent-driven skill security vetter" }
  ]
}

场景 1 进行系统安全基线审计与加固

# 针对操作系统进行安全基线检查
agent-sec-cli harden --scan --config agentos_baseline

预期结果：

• 执行基础基线扫描，5 秒内完成五大安全域检查

• 自动识别不符合项，输出清晰的原因分析与修复建议

• 客户可通过执行 reinforce 一键自动修复，秒级完成加固

场景 2 OpenClaw 专属安全基线检查

# 针对 OpenClaw 运行环境进行专项安全基线检查
agent-sec-cli harden --scan --level openclaw

使用场景:

• 部署 OpenClaw 前后进行环境安全检查

• 定期巡检 OpenClaw 运行环境的安全基线

预期结果:

• 输出针对性的系统安全基线报告,标注 OpenClaw 专属风险项

场景 1：网络访问执行（允许）

# 输入 Prompt，下载网页到 /tmp 目录
Download the Alibaba Cloud official website page to the /tmp directory

预期结果：

• 命令在沙箱内执行

• 网络连接被允许（网络命令自动放行）

• 文件系统仍受限，无法通过 curl 下载到系统目录

场景 2：网络下载到系统关键目录（阻止）

# 输入prompt，尝试下载到 /etc 目录
Download the Alibaba Cloud official website page to the /etc directory

预期结果：

• 写入 /etc 被拒绝

• Agent 提示："无法写入系统目录，请改存到 /tmp 或当前目录"

• 即使网络可访问，敏感目录的写保护仍然生效

场景 3：系统危险命令阻断

# 尝试重启系统
reboot

预期结果：

• 命令被直接阻断，不会进入沙箱执行

• Agent 提示："该命令涉及系统危险操作，已被安全策略阻断"

• 不会触发系统重启或关机

场景 4：文件系统操作（允许）

# 在 /tmp 目录下操作
mkdir -p /tmp/test_dir && rm -rf /tmp/test_dir

预期结果：

• 命令在沙箱内成功执行

• /tmp/test_dir 被创建后删除

• 不影响系统其他目录

场景 5：文件系统操作（阻止）

# 尝试写入系统目录
echo "test" > /etc/test.txt

预期结果：

• 命令在沙箱内执行失败

• 返回 "Read-only file system" 错误

• Agent 提示："无法写入系统目录，如需修改请使用沙箱外执行"

场景 6：危险系统调用拦截

# 尝试执行 ptrace 系统调用
python3 -c "import ctypes; libc = ctypes.CDLL(None); libc.ptrace(0, 0, None, None)"

预期结果：

• 命令在沙箱内执行

• ptrace 调用被拦截，返回 EPERM (errno=1)