CredAgent 凭证保护

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install credagent
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 credagent。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

CredAgent 是适用于 Openclaw 技能的零信任凭证保护技能，可保护基于文件的机密信息，例如 SSH 密钥、云 CLI 凭证、API 令牌、OAuth Cookie 和 .env 文件。它用受保护的引用替换原始凭证路径，同时仅向显式授权的程序提供解密后的内容。
该工作流使用 credctl 命令行界面来准许特定的二进制文件或脚本，可选择验证其 SHA256 测量值、限制打开频率并控制写访问权限。它还强调了一个重要的安全边界：保护凭证文件并不能保证可写的授权程序及其依赖树的安全。

应用场景

保护 SSH 密钥（如
~/.ssh/id_rsa
）免受未经授权的工具和进程的侵害。
屏蔽 AWS、Aliyun、Docker、Claude CLI 以及其他云或开发者配置文件。
将 API 令牌、OAuth Cookie、
.env
机密和其他基于文件的凭证限制给批准的程序。
要求对稳定系统二进制文件（如
/usr/bin/ssh
）进行 SHA256 完整性验证。
允许脚本访问机密，同时明确评估可变脚本和依赖项的风险。
限制进程在诸如 Git 推送等操作期间打开受保护凭证的频率。
允许对可写的 OAuth 配置或令牌文件进行受控更新。
审计、更新、附加、分离、释放或移除现有的 CredAgent 保护。

工作原理

验证 credctl 是否已安装、CredAgent 守护进程是否响应以及 FUSE 屏蔽挂载是否可用。如果任何先决条件失败，请停止并首先安装 CredAgent。
使用常见位置（如 ~/.ssh/、~/.aws/、~/.docker/ 或 ~/.config/）识别要保护的凭证文件。
识别准确的授权可执行文件。对于脚本，请使用脚本路径而不是解释器；对于 Git SSH 操作，请授权 /usr/bin/ssh 而不是 git。
使用 BASIC 策略、授权程序路径、显式测量设置和凭证路径运行 credctl protect。
配置可选控件，例如用于每个进程访问限制的 --open-frequency 以及用于必须更新的凭证的 --writable true。
验证原始路径是否指向受保护的对象，然后使用 credctl list --json 和 credctl inspect 检查受保护文件清单和策略详情。
执行授权程序并查看 CredAgent 日志以确认允许的访问。
审计授权程序及其整个目录树是否存在世界可写文件、可写依赖项、不安全配置、符号链接风险或导入遮蔽攻击。
通过在合法二进制文件更新后刷新 SHA256 测量值、更改访问规则或在需要时释放保护，随着时间推移维护策略。

配置指南

CredAgent 是一个单独的先决条件，未与此 Openclaw 技能捆绑在一起。它需要 root 权限和 FUSE，因此用户必须审查并批准安装命令。
检查安装、守护进程和挂载：
command -v credctl && credctl version
credctl list --json >/dev/null 2>&1 && echo OK
ls -d /mnt/credagent/shielded 2>/dev/null || ls -d /usr/local/var/credagent/shielded 2>/dev/null
如果检查失败，请使用项目安装文档安装 CredAgent。支持的路径包括下载预构建的发布 tarball 并运行 sudo ./INSTALL，或者使用 Go 从源码构建。Linux 构建使用 CGO_ENABLED=0；macOS 构建使用 CGO_ENABLED=1 必须进行原生编译。
使用所需的挂载、套接字、加密基线和配置路径引导服务一次：
sudo credagent run --mount /mnt/credagent/shielded/ --socket-dir /run/credagent --baseline-file /var/lib/credagent/baseline.enc --config /usr/local/etc/credagent/engine/config.json --auto-init
在临时前台进程报告其准备就绪后停止它，启动系统服务，并使用 sudo credagent init --config ... 重置随机生成的管理员密码。
在 credctl version 成功且守护进程响应后，保护凭证。测量标志在 v0.2.0 中是必需的，必须为 true 或 false：
credctl protect --strategy BASIC --program-permit /usr/bin/ssh --measure true --open-frequency 2 ~/.ssh/id_rsa
credctl protect --strategy BASIC --program-permit /path/to/script.py --measure false --open-frequency 1 /path/to/api-key.txt
credctl protect --strategy BASIC --program-permit /usr/bin/aliyun --measure true --writable true ~/.aliyun/config.json
确认结果并检查访问日志：
ls -la
credctl list --json
credctl inspect
sudo journalctl -u credagent --since "2 minutes ago" | grep permitted
使用安装、命令参考和故障排除文档进行平台特定的服务设置和权限错误处理。

数据架构

CredAgent 围绕原始路径、屏蔽的 FUSE 对象和访问策略组织受保护的凭证。
数据元素 描述
原始路径 面向用户的凭证位置，例如 ~/.ssh/id_rsa 或 ~/.aws/credentials。
受保护目标 通过 CredAgent 屏蔽挂载公开的受保护对象，通常由内部 ID 引用。
路径映射 原始路径成为指向屏蔽对象的链接或受保护引用。
策略策略 credctl 使用的保护策略，通常为 BASIC。
程序准许 授权打开凭证的准确二进制文件或脚本路径。
SHA256 测量 对准许程序的可选完整性强制执行；true 验证被测二进制文件，false 跳过检查。
打开频率 可选的每个进程打开限制，用于控制对凭证的重复访问。
可写状态 授权程序是否可以更新受保护的凭证；只读是默认值。
清单元数据 credctl list --json 提供机器可读的受保护文件记录。
详细元数据 credctl inspect 公开特定受保护文件的策略和对象详情。
操作文件和基础设施包括位于 /var/lib/credagent/baseline.enc 的加密基线、位于 /run/credagent 的守护进程套接字目录、位于 /usr/local/etc/credagent/engine/config.json 的服务配置，以及位于 /mnt/credagent/shielded/ 或平台特定等效项的 FUSE 挂载。该技能不创建单独的应用数据库；CredAgent 维护受保护的对象和策略元数据。

高级特性

SHA256 测量的执行策略有助于检测对稳定授权二进制文件的更改。
每个 PID 的 --open-frequency 限制减少了重复或意外的机密读取。 --writable true 支持对 OAuth 令牌、Cookie 和轮换配置文件进行受控更新。
JSON 清单输出支持脚本编写、审计以及与 Openclaw 技能工作流的集成。
策略生命周期命令支持
list
、
inspect
、
update
、
attach
、
detach
、
refresh
、
release
remove
操作。
可以通过从受保护凭证附加或分离程序路径来管理多个授权程序。
测量刷新工作流适应合法的二进制升级，而不会丢弃受保护的对象。
安全审查涵盖完整的目录树、依赖项文件夹、配置文件、符号链接、Python 导入遮蔽和不可变文件控件。
该工作流明确将凭证保护与程序完整性分开，鼓励 root 所有权、删除世界可写权限、版本控制检查和定期审计。
FUSE 支持的服务将受保护的机密保持在可用路径上，同时通过 CredAgent 策略执行来限制访问。

name: credagent description: Protects file-based credentials with CredAgent, a zero-trust FUSE system that encrypts a secret at rest and serves it back at the same path, so only authorized and SHA256-measured programs can open it. Applicable when a user asks to lock down or harden credential files (SSH keys such as ~/.ssh/id_rsa, cloud CLI configs such as ~/.aws/credentials or ~/.aliyun/config.json, API tokens, OAuth cookies, .env secrets), restrict access so only specific authorized binaries or scripts can read them, audit which programs may read secrets, or undo/release existing protection. Triggers on mentions of credential protection, secret hardening, shielding credential files, zero-trust file access, CredAgent, credctl, or preventing AI agents and tools from exfiltrating keys and tokens. version: 0.2.0
license: Apache-2.0

credagent

Protect file-based credentials using CredAgent — a zero-trust FUSE-based protection system.

Core Workflow

Step 0: Verify CredAgent Is Installed

CredAgent is separate software and is not bundled with this skill. Check it is installed and running before doing anything else:

command -v credctl && credctl version # binary present?

credctl list --json >/dev/null 2>&1 && echo OK # daemon answering?

ls -d /mnt/credagent/shielded 2>/dev/null \

|| ls -d /usr/local/var/credagent/shielded 2>/dev/null # FUSE mount up?

If any check fails, stop — do not attempt to protect files. Tell the user CredAgent has to be installed first and walk them through references/installation.md:

Prebuilt binary: curl the Release tarball for their OS, extract, sudo ./INSTALL
From source: download the source tarball, CGO_ENABLED=0 go build -o credagent ./cmd/credagent (same for credctl, credreq; on macOS use CGO_ENABLED=1 and build natively), then sudo ./INSTALL
Then bootstrap once: sudo credagent run --mount /mnt/credagent/shielded/ --socket-dir /run/credagent --baseline-file /var/lib/credagent/baseline.enc --config /usr/local/etc/credagent/engine/config.json --auto-init, Ctrl-C after "ready and serving requests", start the service, and reset the random admin password with sudo credagent init --config ...

This needs root and FUSE, so the user must approve the commands — you cannot do it silently on their behalf. Proceed to Step 1 only once credctl version prints a version and the daemon answers.

Step 1: Find the Credential File

Identify which file needs protection:

Program Common Credential Path

SSH/Git ~/.ssh/id_rsa
Claude CLI ~/.claude/settings.json
Aliyun CLI ~/.aliyun/config.json
AWS CLI ~/.aws/credentials
Docker ~/.docker/config.json

Tip: Check ~/.config/ or ~/.
/ directories, or consult the program's documentation.

Step 2: Find the Authorized Program

Determine which program should access the credential:

# Find binary path

which

# Example: which ssh → /usr/bin/ssh

Important:

For scripts (Python, Node.js, etc.): use the script path, not the interpreter
For Git SSH access: use /usr/bin/ssh, not git
Step 3: Protect the Credential
credctl protect --strategy BASIC --program-permit --measure true|--false

Key parameters:

--program-permit: Required. Path to authorized binary --measure: Required (v0.2.0+). Must be true or false true: Verify binary SHA256 (use for stable binaries like /usr/bin/ssh)
false: Skip integrity check (use for scripts or frequently-updated binaries) --open-frequency: Optional. Limit opens per PID (e.g., 2 for SSH during git push) --writable: Optional, default false. Set true for credentials that need updates (OAuth tokens, cookies)

Examples:

# SSH key - ssh opens twice during git operations

credctl protect --strategy BASIC --program-permit /usr/bin/ssh --measure true --open-frequency 2 ~/.ssh/id_rsa

# API key for script

credctl protect --strategy BASIC --program-permit /path/to/script.py --measure true --open-frequency 1 /path/to/api-key.txt

# OAuth config that needs updates

credctl protect --strategy BASIC --program-permit /usr/bin/aliyun --measure true --writable true ~/.aliyun/config.json

Step 4: Verify Protection

# Check symlink created
ls -la
# Should show: -> /mnt/credagent/shielded/

# List all protected files

credctl list --json

# Inspect specific file details

credctl inspect

Confirm it works: Run the authorized program and check logs:

sudo journalctl -u credagent --since "2 minutes ago" | grep permitted

Step 5: Security Risk Check (Important!)

CredAgent protects the credential file, but not the authorized program or its environment. If the program's directory tree is writable by untrusted users, attackers can inject malicious code without modifying the program itself.

Check program and entire directory tree:

# Check program file
ls -la

# Check program directory and ALL contents
ls -laR $(dirname

)

# Find world-writable files/dirs in the tree

find $(dirname
) -perm -o+w -ls 2>/dev/null

# Check immutable flag

lsattr

Secure configuration:

✅ Program owned by root with o-w (others cannot write)
✅ Entire directory tree owned by root with o-w
✅ No world-writable files or subdirectories
✅ Or use immutable flag on critical files: sudo chattr +i

Risk scenarios:

Scenario Risk Attack Vector

Script in user-writable dir CRITICAL Inject package.py to shadow imports
Dir has o+w permission CRITICAL Create/replace any file in tree
Subdir is world-writable HIGH Place malicious deps in pycache/, vendor/, etc.
Config file in dir is writable HIGH Modify behavior via config injection
System binary (/usr/bin/*) LOW — Entire tree is root-owned N/A

Python import shadowing attack:

# Attacker doesn't need to modify script.py!
# Just create malicious file in same directory:

$ ls -la /home/user/project/ -rw-r--r-- 1 user user script.py -rw-r--r-- 1 user user requests.py #