clawsec-suite

Files (41)

• .clawhubignore
• CHANGELOG.md
• HEARTBEAT.md
• README.md
• SKILL.md
• feed-signing-public.pem · advisories/
• feed.json · advisories/
• feed.json.sig · advisories/
• HOOK.md · hooks/clawsec-advisory-guardian/
• handler.ts · hooks/clawsec-advisory-guardian/
• advisory_scope.mjs · hooks/clawsec-advisory-guardian/lib/
• feed.mjs · hooks/clawsec-advisory-guardian/lib/
• local_file_io.mjs · hooks/clawsec-advisory-guardian/lib/
• matching.ts · hooks/clawsec-advisory-guardian/lib/
• state.ts · hooks/clawsec-advisory-guardian/lib/
• suppression.mjs · hooks/clawsec-advisory-guardian/lib/
• types.ts · hooks/clawsec-advisory-guardian/lib/
• utils.mjs · hooks/clawsec-advisory-guardian/lib/
• version.mjs · hooks/clawsec-advisory-guardian/lib/
• discover_skill_catalog.mjs · scripts/
• generate_checksums_json.mjs · scripts/
• guarded_skill_install.mjs · scripts/
• local_file_io.mjs · scripts/
• setup_advisory_cron.mjs · scripts/
• setup_advisory_hook.mjs · scripts/
• sign_detached_ed25519.mjs · scripts/
• verify_detached_ed25519.mjs · scripts/
• skill.json
• advisory_application_scope.test.mjs · test/
• advisory_suppression.test.mjs · test/
• feed_verification.test.mjs · test/
• fuzz_properties.js · test/
• fuzz_properties.test.mjs · test/
• fuzz_semver_scope_suppression.test.mjs · test/
• guarded_install.test.mjs · test/
• heartbeat_version_check.test.mjs · test/
• .gitkeep · test/lib/
• test_harness.mjs · test/lib/
• path_resolution.test.mjs · test/
• setup_disclosure.test.mjs · test/
• skill_catalog_discovery.test.mjs · test/

SKILL.md (first lines)

# ClawSec Suite

## Vercel Skills Installation

Install with the Vercel Skills CLI for this harness:

```bash
npx skills add prompt-security/clawsec --skill clawsec-suite -a openclaw -y
```

## Operational Notes

- Required runtime: `node`, `npx`, `openclaw`, `curl`, `jq`, `shasum`, `openssl`, `unzip`
- Side effects: setup scripts install an advisory hook under `~/.openclaw/hooks`, optionally create an unattended `openclaw cron` job, and use `npx clawhub@latest install` for guarded installs
- Network behavior: fetches signed advisory feed artifacts and remote catalog metadata unless you pin local paths
- Trust model: the suite can recommend removal or block risky installs, but removal/install overrides stay approval-gated

This means `clawsec-suite` can:
- monitor the ClawSec advisory feed,
- track which advisories are new since last check,
- cross-reference advisories against locally installed skills,
- recommend removal for malicious-skill advisories and require explicit user approval first,
- and still act as the setup/management entrypoint for other ClawSec protections.

## Included vs Optional Protections

### Built into clawsec-suite
- Embedded signed advisory trust set: `advisories/feed.json`, `feed.json.sig`, `checksums.json`, `checksums.json.sig`, and `feed-signing-public.pem`
- Portable heartbeat workflow in `HEARTBEAT.md`
- Advisory polling + state tracking + affected-skill checks
- OpenClaw advisory guardian hook package: `hooks/clawsec-advisory-guardian/`
- Setup scripts for hook and optional cron scheduling: `scripts/`
- Guarded installer: `scripts/guarded_skill_install.mjs`
- Dynamic catalog discovery for installable skills: `scripts/discover_skill_catalog.mjs`

### Installed separately (dynamic catalog)
`clawsec-suite` does not hard-code add-on skill names in this document.

Discover the current catalog from the authoritative index (`https://clawsec.prompt.security/skills/index.json`) at runtime:

```bash
SUITE_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-suite"
node "$SUITE_DIR/scripts/discover_skill_catalog.mjs"
```

Fallback behavior:
- If the remote catalog index is reachable and valid, the suite uses it.
- If the remote index is unavailable or malformed, the script falls back to suite-local catalog metadata in `skill.json`.

## Installation

### Cross-shell path note

- In `bash`/`zsh`, keep path variables expandable (for example, `INSTALL_ROOT="$HOME/.openclaw/skills"`).
- Do not single-quote home-variable paths (avoid `'$HOME/.openclaw/skills'`).
- In PowerShell, set an explicit path:
  - `$env:INSTALL_ROOT = Join-Path $HOME ".openclaw\\skills"`
- If a path is passed with unresolved tokens (like `\$HOME/...`), suite scripts now fail fast with a clear error.

### Option A: Via clawhub (recommended)

```bash
npx clawhub@latest install clawsec-suite
```

### Option B: Manual download with signature + checksum verification

```bash
set -euo pipefail

VERSION="${SKILL_VERSION:?Set SKILL_VERSION (e.g. 0.0.8)}"
INSTALL_ROOT="${INSTALL_ROOT:-$HOME/.openclaw/skills}"
DEST="$INSTALL_ROOT/clawsec-suite"
BASE="https://github.com/prompt-security/clawsec/releases/download/clawsec-suite-v${VERSION}"

TEMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TEMP_DIR"' EXIT

# Pinned release-signing public key (verify fingerprint out-of-band on first use)
# Fingerprint (SHA-256 of SPKI DER): 711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8
RELEASE_PUBKEY_SHA256="711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8"
cat > "$TEMP_DIR/release-signing-public.pem" <<'PEM'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAS7nijfMcUoOBCj4yOXJX+GYGv2pFl2Yaha1P4v5Cm6A=
-----END PUBLIC KEY-----
PEM

ACTUAL_KEY_SHA256="$(openssl pkey -pubin -in "$TEMP_DIR/release-signing-public.pem" -outform DER | shasum -a 256 | awk '{print $1}')"
if [ "$ACTUAL_KEY_SHA256" != "$RELEASE_PUBKEY_SHA256" ]; then
  echo "ERROR: Release public key fingerprint mismatch" >&2
  exit 1
fi

ZIP_NAME="clawsec-suite-v${VERSION}.zip"

# 1) Download release archive + signed checksums manifest + signing public key
curl -fsSL "$BASE/$ZIP_NAME" -o "$TEMP_DIR/$ZIP_NAME"
curl -fsSL "$BASE/checksums.json" -o "$TEMP_DIR/checksums.json"
curl -fsSL "$BASE/checksums.sig" -o "$TEMP_DIR/checksums.sig"

# 2) Verify checksums manifest signature before trusting any hashes
openssl base64 -d -A -in "$TEMP_DIR/checksums.sig" -out "$TEMP_DIR/checksums.sig.bin"
if ! openssl pkeyutl -verify \
  -pubin \
  -inkey "$TEMP_DIR/release-signing-public.pem" \
  -sigfile "$TEMP_DIR/checksums.sig.bin" \
  -rawin \
  -in "$TEMP_DIR/checksums.json" >/dev/null 2>&1; then
  echo "ERROR: checksums.json signature verification failed" >&2
  exit 1
fi

EXPECTED_ZIP_SHA="$(jq -r '.archive.sha256 // empty' "$TEMP_DIR/checksums.json")"
if [ -z "$EXPECTED_ZIP_SHA" ]; then
  echo "ERROR: checksums.json missing archive.sha256" >&2
  exit 1
fi

if command -v shasum >/dev/null 2>&1; then

From prompt-security/clawsec, AGPL-3.0.

More from prompt-security/clawsec