Skip to content

clawsec-suite.md

Latest commit

 

History

History
107 lines (93 loc) · 5.91 KB

clawsec-suite.md

File metadata and controls

107 lines (93 loc) · 5.91 KB
Raw

Module: ClawSec Suite Core

Responsibilities

  • 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.

Key Files

  • 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.

Packaged Advisory Trust Set

The standard installed Suite package must contain all five files below:

  • advisories/feed.json
  • advisories/feed.json.sig
  • advisories/checksums.json
  • advisories/checksums.json.sig
  • advisories/feed-signing-public.pem

The local fallback is considered usable only when this complete set verifies. GitHub release and ClawHub packaging must preserve the same signed payload; a registry publish that omits any file is a release failure.

Public Interfaces

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 and Outputs

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.

Configuration

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.

Example Snippets

// 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
}

Edge Cases

  • Missing/malformed feed signatures force remote rejection and local fallback attempts; an incomplete local trust set cannot be accepted as a verified fallback.
  • 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.

Tests

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.

Source References

  • 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