back
loading skill details...
Security guard for OpenClaw skills, developed and maintained by rose北港（小红帽 / 猫猫帽帽）. Audits installed or incoming skills with local rules plus Zenmux AI inten...
---
name: skillguard-hardened
version: 1.0.5
license: MIT
description: Security guard for OpenClaw skills, developed and maintained by rose北港（小红帽 / 猫猫帽帽）. Audits installed or incoming skills with local rules plus Zenmux AI intent review, then recommends pass, warn, block, or quarantine.
metadata: {"clawdbot":{"emoji":"🛡️","requires":{"bins":["python3"],"env":["ZENMUX_API_KEY"]},"primaryEnv":"ZENMUX_API_KEY"}}
---
# 小红帽 / 猫猫帽帽 / rose北港 SkillGuard (Hardened)
**SkillGuard** is a native security defense line for the OpenClaw skill ecosystem. It detects suspicious behavior before installing, updating, or executing skills, as well as during routine inspections. It provides controlled remediation actions such as quarantine, restore, and forced deletion.
*(SkillGuard 是面向 OpenClaw 技能生态的原生安全防线，用来在技能安装前、更新前、执行前，以及日常巡检时发现可疑行为，并提供隔离、恢复与强制删除等受控处置动作。)*
## Security Transparency & Disclosures (安全透明度与披露)
> [!NOTE]
> SkillGuard is a high-privilege security tool. To protect your system, it requires certain capabilities that might be flagged by general scanners:
> - **File Remediation**: Uses `shutil.rmtree` to permanently delete malicious skills *only* when explicitly confirmed with `--force --yes`.
> - **Guarded Execution**: Uses `subprocess.run` to execute skills within a monitored wrapper.
> - **Remote Updates**: Downloads latest security policies and official skill manifests from trusted domains only (`moltbook.com`, `fluxapay.xyz`).
> - **Clean Package**: As of v1.0.2, all malicious test fixtures have been removed from the distribution package and are now generated dynamically during local testing only.
## What It Does (功能说明)
- Scans skill directories located under `skills/` and `.skills/`. *(扫描 `skills/` 与 `.skills/` 下的技能目录。)*
- Uses local static rules to identify high-risk behaviors, sensitive access, persistence, obfuscation, and prompt injection. *(用本地静态规则识别高危行为、敏感访问、持久化、混淆与提示词注入。)*
- Uses Zenmux Claude for semantic-level intent auditing, identifying deviations between "declared capabilities" and "actual behavior". *(用 Zenmux Claude 做语义级意图审计，识别“声明能力”和“实际行为”之间的偏移。)*
- Outputs structured JSON reports for easy consumption by other Agents or automated flows. *(输出结构化 JSON 报告，便于其他 Agent 或自动化流程消费。)*
- Supports isolation (quarantine) and restoration by default, and never physically deletes skills without explicit confirmation. *(默认支持隔离与恢复，不会在没有显式确认的情况下直接物理删除技能。)*
## Commands (指令)
### Full Audit (全量审计)
```bash
python3 {baseDir}/scripts/scan_skills.py scan
python3 {baseDir}/scripts/scan_skills.py scan --root /root/clawd/skills --root /root/clawd/.skills
python3 {baseDir}/scripts/scan_skills.py --format json scan
python3 {baseDir}/scripts/scan_skills.py scan --auto-remediate quarantine
python3 {baseDir}/scripts/scan_skills.py scan --auto-remediate delete --force --yes
```
### Install Gate (安装门禁)
```bash
python3 {baseDir}/scripts/scan_skills.py check-install /path/to/incoming-skill
```
### Update Gate (更新门禁)
```bash
python3 {baseDir}/scripts/scan_skills.py check-update /path/to/updated-skill
```
### Pre-Execution Gate (执行前门禁)
```bash
python3 {baseDir}/scripts/scan_skills.py check-exec /path/to/skill
python3 {baseDir}/scripts/guarded_flow.py exec --skill-root /path/to/skill -- bash /path/to/skill/scripts/run.sh
```
### Guarded Install / Update Flows (守卫安装/更新流)
```bash
python3 {baseDir}/scripts/guarded_flow.py npx-add owner/repo@skill -g -y
python3 {baseDir}/scripts/guarded_flow.py npx-update
python3 {baseDir}/scripts/guarded_flow.py moltbook-install
python3 {baseDir}/scripts/guarded_flow.py moltbook-update
```
### Quarantine / Restore / Delete (隔离/恢复/删除)
```bash
python3 {baseDir}/scripts/manage_skill.py quarantine suspicious-skill --reason "manual review"
python3 {baseDir}/scripts/manage_skill.py restore suspicious-skill
python3 {baseDir}/scripts/manage_skill.py list
python3 {baseDir}/scripts/manage_skill.py delete suspicious-skill --force --yes
python3 {baseDir}/scripts/manage_skill.py clean suspicious-skill
python3 {baseDir}/scripts/manage_skill.py disinfect suspicious-skill --action delete --force --yes
```
## Exit Codes (退出状态码)
- `0`: No block policies matched in this check. *(本次检查未命中阻断策略。)*
- `1`: Block policy hit, or management action failed. *(命中阻断策略，或管理动作失败。)*
## Report Output (报告输出)
Default JSON reports are written to: *(默认 JSON 报告写入：)*
```text
/root/clawd/output/skillguard/reports/
```
Quarantine state and audit logs are written to: *(隔离态与审计日志写入：)*
```text
/root/clawd/output/skillguard/quarantine/
/root/clawd/output/skillguard/audit.log
```
## Safety Model (安全模型)
- The default behavior acts as a 4-level recommendation (`PASS / WARN / BLOCK / QUARANTINE`) and will not delete automatically. *(默认行为是 `PASS / WARN / BLOCK / QUARANTINE` 四级建议，不会自动删除。)*
- Deletion (`delete`) requires explicit flags `--force --yes`. *(`delete` 必须显式传入 `--force --yes`。)*
- `clean` / `disinfect` scan a skill first, then quarantine or delete it based on the resulting recommendation. *(`clean` / `disinfect` 会先扫描，再按风险结果自动隔离或删除技能。)*
- `scan --auto-remediate` upgrades bulk scanning into bulk quarantine/delete, and defaults to acting on `BLOCK / QUARANTINE`. *(`scan --auto-remediate` 可把批量扫描升级为批量查杀，默认只处置 `BLOCK / QUARANTINE`。)*
- Remediation actions only take effect within whitelisted skill root directories or SkillGuard's quarantine directory. *(处置动作只允许在白名单技能根目录或 SkillGuard 的隔离目录内生效。)*
- The Zenmux API Key is never hardcoded; it must be provided via environment variables: *(Zenmux Key 不写死在代码里，需通过环境变量提供：)*
- `ZENMUX_API_KEY`
- Optional model override: `ZENMUX_MODEL`
## Notes (注意事项)
- If the Zenmux API Key is not configured, SkillGuard will fallback to local rule mode and note in the report that AI auditing is not enabled. *(如果没有配置 Zenmux Key，SkillGuard 会退回本地规则模式，并在报告里写明 AI 审计未启用。)*
- Suitable as a pre-security checker for skill marketplaces, skill installers, or Agent schedulers. *(适合作为技能市场、技能安装器、Agent 调度器的前置安全检查器。)*
- `guarded_flow.py` is used to integrate SkillGuard into real installation, update, and execution workflows. *(`guarded_flow.py` 用于把 SkillGuard 接入真实安装、更新和执行流程。)*
don't have the plugin yet? install it then click "run inline in claude" again.
extracted implicit intent statement, formalized all external dependencies and edge cases (zenmux api, file permissions, network timeouts, empty dirs), converted command list to numbered procedure steps with explicit inputs/outputs, made decision logic explicit (fallback to local rules, block logic, delete confirmation), added detailed output contract with file paths and schema, and defined outcome signals for verification.
intent
skillguard is a native security defense line for the openclaw skill ecosystem. use it to detect suspicious behavior before installing, updating, or executing skills, and during routine inspections. it scans skill directories against local static rules (high-risk behaviors, sensitive access, persistence, obfuscation, prompt injection) and runs semantic-level intent auditing via zenmux claude to catch deviations between declared capabilities and actual behavior. outputs structured json reports for consumption by other agents or automated flows. supports isolation (quarantine), restoration, and forced deletion (with explicit confirmation only). pick this when you need to gate skill installations, updates, executions, or run bulk security audits across your skill ecosystem.
inputs
external connections:
ZENMUX_API_KEY environment variable (required for ai intent auditing; optional if fallback to local rules acceptable). optional model override via ZENMUX_MODEL env var.moltbook.com, fluxapay.xyz.parameters and context:
skills/ and .skills/ by default, or custom paths via --root /path/to/skills.--auto-remediate quarantine or --auto-remediate delete (delete requires --force --yes).--format json / --format text.scan_skills.py (no external config required, but policies can be updated from remote).edge cases and constraints:
/root/clawd/output/skillguard/quarantine/.procedure
[scan full ecosystem] run python3 {baseDir}/scripts/scan_skills.py scan (or with custom roots --root /path/to/skills --root /path/to/.skills). input: skill directories. output: json report with pass/warn/block/quarantine recommendations for each skill.
[gate before install] run python3 {baseDir}/scripts/scan_skills.py check-install /path/to/incoming-skill on the incoming skill tarball or directory. input: skill path. output: exit code (0 = safe, 1 = blocked) and json report; if block recommendation, installation is prevented.
[gate before update] run python3 {baseDir}/scripts/scan_skills.py check-update /path/to/updated-skill on the updated skill. input: updated skill path. output: exit code and json report; block prevents update.
[gate before execution] run python3 {baseDir}/scripts/scan_skills.py check-exec /path/to/skill for lightweight pre-exec scan, or use python3 {baseDir}/scripts/guarded_flow.py exec --skill-root /path/to/skill -- bash /path/to/skill/scripts/run.sh for wrapped execution with monitoring. input: skill path and exec command. output: exit code (0 = allowed, 1 = blocked); if allowed, skill runs under guarded subprocess wrapper.
[guarded install/update workflows] use python3 {baseDir}/scripts/guarded_flow.py npx-add owner/repo@skill -g -y, npx-update, moltbook-install, or moltbook-update to integrate skillguard gates into real installation pipelines. input: package specifier or moltbook manifest. output: exit code and audit log; on block, installation is rolled back.
[quarantine] run python3 {baseDir}/scripts/manage_skill.py quarantine <skill-name> --reason "description" to isolate a skill (moves it to /root/clawd/output/skillguard/quarantine/). input: skill name and reason. output: quarantine directory path and audit log entry.
[restore] run python3 {baseDir}/scripts/manage_skill.py restore <skill-name> to move a quarantined skill back to its original location. input: skill name. output: restored path and audit log entry.
[list quarantine] run python3 {baseDir}/scripts/manage_skill.py list to view all quarantined skills. input: none. output: table of quarantined skills, dates, and reasons.
[delete with confirmation] run python3 {baseDir}/scripts/manage_skill.py delete <skill-name> --force --yes to permanently delete a skill (only in whitelisted roots or quarantine). input: skill name plus explicit flags. output: deletion confirmation and audit log entry.
[clean or disinfect] run python3 {baseDir}/scripts/manage_skill.py clean <skill-name> to scan then auto-quarantine, or disinfect <skill-name> --action delete --force --yes to scan then auto-delete high-risk skills. input: skill name and optional action flags. output: scan report, remediation action taken, and audit log.
[bulk auto-remediate] run python3 {baseDir}/scripts/scan_skills.py scan --auto-remediate quarantine to scan all skills and auto-quarantine those matching block/quarantine recommendations, or use --auto-remediate delete --force --yes for bulk deletion (acts only on block/quarantine by default). input: remediation action flag. output: bulk remediation report and audit log.
[format output] use --format json to output structured json reports (default) or --format text for human-readable plaintext. input: format flag. output: report written to /root/clawd/output/skillguard/reports/.
decision points
if zenmux api key is present and reachable: run full semantic intent auditing via claude, merge results with local rules. else: fallback to local static rules only, disable ai auditing, note in report.
if skill is flagged block or quarantine (default policies): check if --auto-remediate flag is set. if yes, apply quarantine or delete action (delete requires --force --yes). else: output recommendation only, no auto action.
if delete or disinfect command is invoked: require --force --yes flags. if missing, abort with error and audit log entry. if present, proceed with permanent deletion only if skill is in whitelisted roots or quarantine directory.
if check-install, check-update, or check-exec returns block recommendation: prevent installation, update, or execution (exit code 1). if warn or pass: allow with optional human review (exit code 0).
if skill directory is empty or does not exist: return zero-risk report (no block), note in audit log.
if remote policy update fails (network timeout, dns failure): use last cached policies, log warning to audit log, continue scan.
if quarantine directory lacks write permissions: fail remediation action with error, audit log entry.
output contract
json reports (default): written to /root/clawd/output/skillguard/reports/<timestamp>-<skill-name>.json. schema includes per-skill fields: name, path, scan-timestamp, local-rules-findings (array of violations with severity), ai-intent-findings (array of deviations if zenmux enabled), overall-recommendation (pass/warn/block/quarantine), remediation-applied (if auto-remediate flag used).
quarantine state: stored in /root/clawd/output/skillguard/quarantine/<skill-name>/ with manifest and reason file.
audit log: /root/clawd/output/skillguard/audit.log records all scans, gates, quarantine/restore/delete actions with timestamp, user/agent, action, skill name, and result.
exit codes: 0 (no block match, or successful action), 1 (block match, failed action, or missing required flags).
outcome signal
user knows the skill worked when: (1) scan or gate command returns exit code 0 (safe) or 1 (blocked) as expected, (2) json report in /root/clawd/output/skillguard/reports/ contains complete findings with no parse errors, (3) quarantine/restore/delete command updates quarantine directory and audit log, (4) guarded installation/update/execution integrates gate checks and prevents unsafe skills, (5) bulk auto-remediate processes all flagged skills without errors, (6) audit log entries appear immediately after each action with correct timestamps and details.
security transparency and disclosures
skillguard is a high-privilege security tool. to protect your system, it uses certain capabilities that might be flagged by general scanners: file remediation via shutil.rmtree (only on explicit --force --yes confirmation), guarded execution via subprocess.run within monitored wrapper, remote policy updates from trusted domains only (moltbook.com, fluxapay.xyz), and clean distribution (malicious test fixtures removed as of v1.0.2, generated dynamically at local test time only).
credits: developed and maintained by rose北港 (小红帽 / 猫猫帽帽).