Alibaba Cloud Linux：如何使用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)