- Act as the main skill-of-skills security bundle for OpenClaw-style agents.
- Verify advisory feed authenticity (Ed25519 signatures and optional checksum manifests).
- Detect advisory matches against installed skills and emit actionable runtime alerts.
- Enforce two-step confirmation for risky skill installations.
skills/clawsec-suite/skill.json: suite metadata, embedded components, catalog defaults.skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts: runtime event handler.skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs: signed feed loading/parsing.skills/clawsec-suite/hooks/.../lib/matching.ts: advisory-to-skill matching logic.skills/clawsec-suite/hooks/.../lib/state.ts: scan state persistence.skills/clawsec-suite/hooks/.../lib/suppression.mjs: allowlist-based suppression loader.skills/clawsec-suite/scripts/guarded_skill_install.mjs: advisory-gated installer wrapper.skills/clawsec-suite/scripts/discover_skill_catalog.mjs: remote/fallback catalog discovery.
| Interface | Consumer | Behavior |
|---|
| Hook handler default export | OpenClaw hook runtime | Handles agent:bootstrap and command:new events. |
guarded_skill_install.mjs CLI | Operators/automation | Blocks on advisory matches unless --confirm-advisory. |
discover_skill_catalog.mjs CLI | Suite docs/automation | Lists installable skills with fallback metadata. |
feed.mjs functions | Suite scripts and tests | Feed load, signature verification, checksum manifest checks. |
| Exit code contract | External wrappers | 42 indicates explicit second confirmation required. |
Inputs/outputs are summarized in the table below.
| Type | Name | Location | Description |
|---|
| Input | Advisory feed + signatures | Remote URLs or local advisories/ files | Risk intelligence source for hook and installer. |
| Input | Installed skill metadata | Skill directories under install root | Matcher compares installed versions to advisory affected specs. |
| Input | Suppression config | OPENCLAW_AUDIT_CONFIG or default config paths | Selective suppression by check and skill name. |
| Output | Runtime alert messages | Hook event messages[] | Advisories and recommended user actions. |
| Output | Persistent state | ~/.openclaw/clawsec-suite-feed-state.json | De-dup alerts, track scan windows. |
| Output | CLI gating exit codes | Installer process status | Ensures deliberate user confirmation on risk. |
| Variable | Default | Module Effect |
|---|
CLAWSEC_FEED_URL | Hosted advisory URL | Chooses primary remote feed endpoint. |
CLAWSEC_LOCAL_FEED* vars | Suite-local advisories directory | Configures local signed fallback artifacts. |
CLAWSEC_FEED_PUBLIC_KEY | advisories/feed-signing-public.pem | Verification key path. |
CLAWSEC_ALLOW_UNSIGNED_FEED | 0 | Enables temporary migration bypass mode. |
CLAWSEC_VERIFY_CHECKSUM_MANIFEST | 1 | Enables checksum manifest verification layer. |
CLAWSEC_HOOK_INTERVAL_SECONDS | 300 | Controls event-driven scan throttling. |
// hook only handles selected events
function shouldHandleEvent(event: HookEvent): boolean {
const eventName = toEventName(event);
return eventName === 'agent:bootstrap' || eventName === 'command:new';
}
// guarded installer confirmation contract
if (matches.length > 0 && !args.confirmAdvisory) {
process.stdout.write('Re-run with --confirm-advisory to proceed.\n');
process.exit(EXIT_CONFIRM_REQUIRED); // 42
}
- Missing/malformed feed signatures force remote rejection and local fallback attempts.
- Ambiguous checksum manifest basename collisions are treated as errors.
- Unknown skill versions are treated conservatively in version matching logic.
- Suppression is disabled unless config includes the pipeline sentinel (
enabledFor).
- Invalid environment path tokens are rejected to avoid accidental literal path usage.
| Test File | Focus |
|---|
skills/clawsec-suite/test/feed_verification.test.mjs | Signature/checksum verification and fail-closed behavior. |
skills/clawsec-suite/test/guarded_install.test.mjs | Confirmation gating and match semantics. |
skills/clawsec-suite/test/path_resolution.test.mjs | Home/path expansion and invalid token handling. |
skills/clawsec-suite/test/advisory_suppression.test.mjs | Suppression config parsing and matching. |
skills/clawsec-suite/test/skill_catalog_discovery.test.mjs | Remote index and fallback merge behavior. |
- skills/clawsec-suite/skill.json
- skills/clawsec-suite/SKILL.md
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/matching.ts
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/state.ts
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/version.mjs
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- skills/clawsec-suite/scripts/discover_skill_catalog.mjs
- skills/clawsec-suite/test/feed_verification.test.mjs
- skills/clawsec-suite/test/guarded_install.test.mjs
- skills/clawsec-suite/test/path_resolution.test.mjs