### Install JS Dependencies and Start Dev Server

Source: https://github.com/prompt-security/clawsec/blob/main/CLAUDE.md

Installs JavaScript dependencies using npm and starts the Vite development server. This is typically the first step for frontend development.

```bash
npm install
npm run dev
```

--------------------------------

### Runtime Guarded Skill Installation (Node.js/Bash)

Source: https://github.com/prompt-security/clawsec/blob/main/wiki/data-flow.md

This example shows how to perform a guarded installation of a skill using the ClawSec suite. It highlights the use of environment variables to specify the local feed path and the public key for feed verification, ensuring that only trusted advisories are used during installation.

```bash
# Runtime guarded install uses signed feed paths
CLAWSEC_LOCAL_FEED=~/.openclaw/skills/clawsec-suite/advisories/feed.json \
CLAWSEC_FEED_PUBLIC_KEY=~/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
```

--------------------------------

### Local Development Setup Commands (Bash)

Source: https://context7.com/prompt-security/clawsec/llms.txt

Provides essential bash commands for setting up the ClawSec local development environment. This includes installing Node.js and Python prerequisites, installing npm dependencies, populating local data for skills, advisories, and wiki exports, and starting the development server.

```bash
# Prerequisites: Node.js 20+, Python 3.10+, npm

# Install dependencies
npm install

# Populate local data for development
./scripts/populate-local-skills.sh           # Skills catalog from local skills/
./scripts/populate-local-feed.sh --days 120  # Advisory feed with real NVD data
./scripts/populate-local-wiki.sh             # Wiki llms exports

# Start development server (auto-regenerates wiki exports)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Generate wiki llms exports manually
npm run gen:wiki-llms
```

--------------------------------

### Install and Setup ClawHub Checker

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-clawhub-checker/SKILL.md

Commands to install the ClawHub checker via npx, execute the reputation hook setup script, and restart the OpenClaw gateway.

```bash
npx clawhub@latest install clawsec-suite
npx clawhub@latest install clawsec-clawhub-checker
node ~/.openclaw/skills/clawsec-clawhub-checker/scripts/setup_reputation_hook.mjs
openclaw gateway restart
```

--------------------------------

### Execute Enhanced Guarded Installation

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-clawhub-checker/SKILL.md

Demonstrates how to run the enhanced installation wrapper or the direct enhanced script to install a skill with reputation checks.

```bash
node scripts/guarded_skill_install_wrapper.mjs --skill some-skill --version 1.0.0
node scripts/enhanced_guarded_install.mjs --skill some-skill --version 1.0.0
```

--------------------------------

### Python Environment Setup with uv

Source: https://github.com/prompt-security/clawsec/blob/main/CLAUDE.md

Sets up a Python virtual environment using 'uv', creates the environment in the repository root, and installs linters like ruff and bandit. It's recommended to use 'uv' instead of raw 'pip'.

```bash
uv venv                  # create .venv in repo root
source .venv/bin/activate
uv pip install ruff bandit   # linters configured in pyproject.toml
```

--------------------------------

### Manual Installation with Verification

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-suite/SKILL.md

Performs a secure manual installation by downloading the release archive, verifying the cryptographic signature of the checksum manifest, and validating the archive hash.

```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

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"

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"

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
  ACTUAL_ZIP_SHA="$(shasum -a 256 "$TEMP_DIR/$ZIP_NAME" | awk '{print $1}')"
else
  ACTUAL_ZIP_SHA="$(sha256sum "$TEMP_DIR/$ZIP_NAME" | awk '{print $1}')"
fi

if [ "$EXPECTED_ZIP_SHA" != "$ACTUAL_ZIP_SHA" ]; then
  echo "ERROR: Archive checksum mismatch for $ZIP_NAME" >&2
  exit 1
fi

echo "Checksums manifest signature and archive hash verified."
```

--------------------------------

### Install Suspicious Skill with Confirmation

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-clawhub-checker/SKILL.md

Example of attempting to install a skill that triggers a reputation warning and using the --confirm-reputation flag to bypass the block.

```bash
node scripts/guarded_skill_install_wrapper.mjs --skill suspicious-skill --version 1.0.0
node scripts/guarded_skill_install_wrapper.mjs --skill suspicious-skill --version 1.0.0 --confirm-reputation
```

--------------------------------

### Manual Installation Script

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-scanner/SKILL.md

A bash script to manually download and install the scanner from GitHub releases.

```bash
set -euo pipefail

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

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

--------------------------------

### Run Clawsec Scanner CLI Scans

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-scanner/SKILL.md

These examples demonstrate how to execute the Clawsec scanner from the command line for on-demand security analysis. They show how to specify the target directory, choose output formats (JSON or text), and get help on available flags.

```bash
SCANNER_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-scanner"

# Scan all skills with JSON output
"$SCANNER_DIR/scripts/runner.sh" --target ./skills/ --output report.json --format json

# Scan specific directory with human-readable output
"$SCANNER_DIR/scripts/runner.sh" --target ./my-skill/ --format text

# Check available flags
"$SCANNER_DIR/scripts/runner.sh" --help

```

--------------------------------

### Install ClawSec Skill Files

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-feed/SKILL.md

Automates the installation of skill files by creating the directory, copying contents, and setting appropriate file permissions for security.

```bash
echo "Installing from individual files..."
mkdir -p "$INSTALL_DIR"
cp "$TEMP_DIR/downloads"/* "$INSTALL_DIR/"
chmod 600 "$INSTALL_DIR/skill.json"
find "$INSTALL_DIR" -type f ! -name "skill.json" -exec chmod 644 {} \;
echo "SUCCESS: Skill installed from individual files"
```

--------------------------------

### Guarded Skill Installation Workflow

Source: https://context7.com/prompt-security/clawsec/llms.txt

Implements a two-step installation process where an advisory check is performed before installation. If a match is found, the user must explicitly confirm the installation.

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

# First request - check for advisories
node "$SUITE_DIR/scripts/guarded_skill_install.mjs" --skill helper-plus --version 1.0.1

# Second confirmation - proceed after user explicitly approves
node "$SUITE_DIR/scripts/guarded_skill_install.mjs" --skill helper-plus --version 1.0.1 --confirm-advisory
```

--------------------------------

### Bash Commands for OpenClaw Audit Setup

Source: https://github.com/prompt-security/clawsec/blob/main/skills/openclaw-audit-watchdog/examples/README.md

Provides bash commands for setting up and running OpenClaw security audits. This includes copying an example configuration file to a default location and executing the audit with deep scanning.

```bash
mkdir -p ~/.openclaw
cp security-audit-config.example.json ~/.openclaw/security-audit.json
openclaw security audit --deep
```

--------------------------------

### Download, Verify, and Install Skill Workflow

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-nanoclaw/docs/SKILL_SIGNING.md

Automates the process of downloading a skill package and its signature from a URL, verifying the signature, and then installing the skill. It includes cleanup steps to remove downloaded files after successful installation or verification failure.

```typescript
async function downloadAndInstallSkill(url: string) {
  const packagePath = `/tmp/${Date.now()}-skill.tar.gz`;
  const signaturePath = `${packagePath}.sig`;

  // Download package
  await fetch(url).then(r => r.arrayBuffer()).then(buf => {
    fs.writeFileSync(packagePath, Buffer.from(buf));
  });

  // Download signature
  await fetch(`${url}.sig`).then(r => r.text()).then(sig => {
    fs.writeFileSync(signaturePath, sig);
  });

  // Verify before installation
  const verification = await tools.clawsec_verify_skill_package({
    packagePath,
    signaturePath
  });

  const result = JSON.parse(verification.content[0].text);

  if (!result.valid) {
    fs.unlinkSync(packagePath);     // Delete tampered file
    fs.unlinkSync(signaturePath);
    throw new Error('Signature verification failed');
  }

  // Install verified package
  extractPackage(packagePath, '/workspace/project/skills/');

  // Cleanup
  fs.unlinkSync(packagePath);
  fs.unlinkSync(signaturePath);
}
```

--------------------------------

### Install via ClawHub

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-suite/SKILL.md

The recommended method for installing the ClawSec suite using the npx package runner.

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

--------------------------------

### Install Clawtributor from .skill Artifact (Shell)

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawtributor/SKILL.md

Attempts to download and install the Clawtributor skill from a compressed .skill artifact. Includes security checks for artifact size, path traversal, file count, and checksums before extraction and installation. Falls back to individual file download if artifact installation fails.

```shell
echo "Attempting .skill artifact installation..."
if curl -sSL --fail --show-error --retry 3 --retry-delay 1 \
   "$BASE_URL/clawtributor.skill" -o "$TEMP_DIR/clawtributor.skill" 2>/dev/null; then

  # Security: Check artifact size (prevent DoS)
  ARTIFACT_SIZE=$(stat -c%s "$TEMP_DIR/clawtributor.skill" 2>/dev/null || stat -f%z "$TEMP_DIR/clawtributor.skill")
  MAX_SIZE=$((50 * 1024 * 1024))  # 50MB

  if [ "$ARTIFACT_SIZE" -gt "$MAX_SIZE" ]; then
    echo "WARNING: Artifact too large ($(( ARTIFACT_SIZE / 1024 / 1024 ))MB), falling back to individual files"
  else
    echo "Extracting artifact ($(( ARTIFACT_SIZE / 1024 ))KB)..."

    # Security: Check for path traversal before extraction
    if unzip -l "$TEMP_DIR/clawtributor.skill" | grep -qE '\.\./|^/|~/'; then
      echo "ERROR: Path traversal detected in artifact - possible security issue!"
      exit 1
    fi

    # Security: Check file count (prevent zip bomb)
    FILE_COUNT=$(unzip -l "$TEMP_DIR/clawtributor.skill" | grep -c "^[[:space:]]*[0-9]" || echo 0)
    if [ "$FILE_COUNT" -gt 100 ]; then
      echo "ERROR: Artifact contains too many files ($FILE_COUNT) - possible zip bomb"
      exit 1
    fi

    # Extract to temp directory
    unzip -q "$TEMP_DIR/clawtributor.skill" -d "$TEMP_DIR/extracted"

    # Verify skill.json exists
    if [ ! -f "$TEMP_DIR/extracted/clawtributor/skill.json" ]; then
      echo "ERROR: skill.json not found in artifact"
      exit 1
    fi

    # Verify checksums for all extracted files
    echo "Verifying checksums..."
    CHECKSUM_FAILED=0
    for file in $(jq -r '.files | keys[]' "$TEMP_DIR/checksums.json"); do
      EXPECTED=$(jq -r --arg f "$file" '.files[$f].sha256' "$TEMP_DIR/checksums.json")
      FILE_PATH=$(jq -r --arg f "$file" '.files[$f].path' "$TEMP_DIR/checksums.json")

      # Try nested path first, then flat filename
      if [ -f "$TEMP_DIR/extracted/clawtributor/$FILE_PATH" ]; then
        ACTUAL=$(shasum -a 256 "$TEMP_DIR/extracted/clawtributor/$FILE_PATH" | cut -d' ' -f1)
      elif [ -f "$TEMP_DIR/extracted/clawtributor/$file" ]; then
        ACTUAL=$(shasum -a 256 "$TEMP_DIR/extracted/clawtributor/$file" | cut -d' ' -f1)
      else
        echo "  ✗ $file (not found in artifact)"
        CHECKSUM_FAILED=1
        continue
      fi

      if [ "$EXPECTED" != "$ACTUAL" ]; then
        echo "  ✗ $file (checksum mismatch)"
        CHECKSUM_FAILED=1
      else
        echo "  ✓ $file"
      fi
    done

    if [ "$CHECKSUM_FAILED" -eq 0 ]; then
      # SUCCESS: Install from artifact
      echo "Installing from artifact..."
      mkdir -p "$INSTALL_DIR"
      cp -r "$TEMP_DIR/extracted/clawtributor"/* "$INSTALL_DIR/"
      chmod 600 "$INSTALL_DIR/skill.json"
      find "$INSTALL_DIR" -type f ! -name "skill.json" -exec chmod 644 {} \;
      echo "SUCCESS: Skill installed from .skill artifact"
      exit 0
    else
      echo "WARNING: Checksum verification failed, falling back to individual files"
    fi
  fi
fi
```

--------------------------------

### Install Verified Clawsec Archive

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-suite/SKILL.md

This script installs the Clawsec suite from a verified archive. It creates the installation directory, extracts the archive, and sets appropriate file permissions for the skill JSON and other files. Finally, it echoes the installation path and the command to set up the advisory hook.

```bash
mkdir -p "$INSTALL_ROOT"
rm -rf "$DEST"
unzip -q "$TEMP_DIR/$ZIP_NAME" -d "$INSTALL_ROOT"

chmod 600 "$DEST/skill.json"
find "$DEST" -type f ! -name "skill.json" -exec chmod 644 {} \;

echo "Installed clawsec-suite v${VERSION} to: $DEST"
echo "Next step (OpenClaw): node \"$DEST/scripts/setup_advisory_hook.mjs\""
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/prompt-security/clawsec/blob/main/AGENTS.md

Installs all project dependencies required for development and building. This is typically the first command run after cloning the repository.

```bash
npm install
```

--------------------------------

### Install ClawSec Suite using npm or curl

Source: https://github.com/prompt-security/clawsec/blob/main/index.html

Provides instructions for installing the ClawSec security skill suite. Users can install it via npm using 'npx clawhub@latest install clawsec-suite' or by downloading the installation script using curl.

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

```bash
curl -sL https://clawsec.prompt.security/releases/latest/download/SKILL.md
```

--------------------------------

### Install ClawSec Scanner via ClawHub

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-scanner/SKILL.md

Recommended method for installing the scanner using the npx package runner.

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

--------------------------------

### ClawSec Suite Core - Example Snippets

Source: https://github.com/prompt-security/clawsec/blob/main/wiki/modules/clawsec-suite.md

Provides example code snippets demonstrating the usage of the ClawSec Suite Core.

```APIDOC
## ClawSec Suite Core - Example Snippets

### Description

This section provides example code snippets illustrating how to interact with or utilize components of the ClawSec Suite Core.

### Example 1: Hook Event Handling

```ts
// hook only handles selected events
function shouldHandleEvent(event: HookEvent): boolean {
  const eventName = toEventName(event);
  return eventName === 'agent:bootstrap' || eventName === 'command:new';
}
```

### Example 2: Guarded Installer Confirmation

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

--------------------------------

### Run Guarded Install with Local Feed Paths (Bash)

Source: https://github.com/prompt-security/clawsec/blob/main/wiki/configuration.md

This snippet demonstrates how to run the guarded skill installation script using explicit local paths for the feed, signature, and public key. It utilizes environment variables to specify these paths, ensuring a secure and controlled installation process. The `--dry-run` flag is used for a test execution.

```bash
CLAWSEC_LOCAL_FEED="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json" \
CLAWSEC_LOCAL_FEED_SIG="$HOME/.openclaw/skills/clawsec-suite/advisories/feed.json.sig" \
CLAWSEC_FEED_PUBLIC_KEY="$HOME/.openclaw/skills/clawsec-suite/advisories/feed-signing-public.pem" \
node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill clawtributor --dry-run
```

--------------------------------

### Implement Safe Skill Installation Pattern

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-nanoclaw/SKILL.md

A robust pattern for installing skills that includes a safety check and user confirmation workflow.

```typescript
const safety = await tools.clawsec_check_skill_safety({
  skillName: userRequestedSkill
});

if (safety.safe) {
  await installSkill(userRequestedSkill);
} else {
  await showSecurityWarning(safety.advisories);
  if (await getUserConfirmation()) {
    await installSkill(userRequestedSkill);
  }
}
```

--------------------------------

### Guarded Skill Install Flow (First Confirmation)

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-suite/SKILL.md

This script initiates a guarded skill installation process, requiring a first confirmation from the user. It checks for advisory matches for the specified skill and version. If an advisory is found, it prints the context and exits with a specific code (42) to prompt for a second confirmation.

```bash
SUITE_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-suite"
node "$SUITE_DIR/scripts/guarded_skill_install.mjs" --skill helper-plus --version 1.0.1
```

--------------------------------

### Usage Patterns

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-nanoclaw/docs/SKILL_SIGNING.md

Examples demonstrating how to use the `clawsec_verify_skill_package` tool in various scenarios.

```APIDOC
### Usage Patterns

#### Pattern 1: Basic Pre-Installation Check

```typescript
async function installSkill(packagePath: string) {
  // Verify signature first
  const verification = await tools.clawsec_verify_skill_package({ packagePath });
  const result = JSON.parse(verification.content[0].text);

  if (result.recommendation === 'block') {
    throw new Error(`Cannot install: ${result.reason || result.error}`);
  }

  // Signature valid - proceed with extraction
  extractPackage(packagePath, '/workspace/project/skills/');
}
```

#### Pattern 2: Combined Security Checks

```typescript
async function installSkillSafely(packagePath: string, skillName: string) {
  // Step 1: Verify signature
  const sigVerify = await tools.clawsec_verify_skill_package({ packagePath });
  const sigResult = JSON.parse(sigVerify.content[0].text);

  if (!sigResult.valid) {
    throw new Error(`Signature invalid: ${sigResult.reason}`);
  }

  // Step 2: Check advisories
  const advisory = await tools.clawsec_check_skill_safety({ skillName });
  const advResult = JSON.parse(advisory.content[0].text);

  if (!advResult.safe) {
    throw new Error(`Known vulnerabilities: ${advResult.advisories.map(a => a.id).join(', ')}`);
  }

  // Both checks passed - safe to install
  extractPackage(packagePath, '/workspace/project/skills/');
  console.log(`✓ Installed ${skillName} (verified + no advisories)`);
}
```

#### Pattern 3: Download and Verify Workflow

```typescript
async function downloadAndInstallSkill(url: string) {
  const packagePath = `/tmp/${Date.now()}-skill.tar.gz`;
  const signaturePath = `${packagePath}.sig`;

  // Download package
  await fetch(url).then(r => r.arrayBuffer()).then(buf => {
    fs.writeFileSync(packagePath, Buffer.from(buf));
  });

  // Download signature
  await fetch(`${url}.sig`).then(r => r.text()).then(sig => {
    fs.writeFileSync(signaturePath, sig);
  });

  // Verify before installation
  const verification = await tools.clawsec_verify_skill_package({
    packagePath,
    signaturePath
  });

  const result = JSON.parse(verification.content[0].text);

  if (!result.valid) {
    fs.unlinkSync(packagePath);     // Delete tampered file
    fs.unlinkSync(signaturePath);
    throw new Error('Signature verification failed');
  }

  // Install verified package
  extractPackage(packagePath, '/workspace/project/skills/');

  // Cleanup
  fs.unlinkSync(packagePath);
  fs.unlinkSync(signaturePath);
}
```
```

--------------------------------

### Install Clawsec .skill Artifact

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-feed/SKILL.md

Attempts to download and install a .skill artifact. Includes checks for artifact size, path traversal, zip bombs, and checksum verification. If checks pass, it extracts and installs the artifact; otherwise, it falls back to downloading individual files.

```bash
echo "Attempting .skill artifact installation..."
if curl -sSL --fail --show-error --retry 3 --retry-delay 1 \
   "$BASE_URL/clawsec-feed.skill" -o "$TEMP_DIR/clawsec-feed.skill" 2>/dev/null; then

  # Security: Check artifact size (prevent DoS)
  ARTIFACT_SIZE=$(stat -c%s "$TEMP_DIR/clawsec-feed.skill" 2>/dev/null || stat -f%z "$TEMP_DIR/clawsec-feed.skill")
  MAX_SIZE=$((50 * 1024 * 1024))  # 50MB

  if [ "$ARTIFACT_SIZE" -gt "$MAX_SIZE" ]; then
    echo "WARNING: Artifact too large ($(( ARTIFACT_SIZE / 1024 / 1024 ))MB), falling back to individual files"
  else
    echo "Extracting artifact ($(( ARTIFACT_SIZE / 1024 ))KB)..."

    # Security: Check for path traversal before extraction
    if unzip -l "$TEMP_DIR/clawsec-feed.skill" | grep -qE '\.\./|^/|~/'; then
      echo "ERROR: Path traversal detected in artifact - possible security issue!"
      exit 1
    fi

    # Security: Check file count (prevent zip bomb)
    FILE_COUNT=$(unzip -l "$TEMP_DIR/clawsec-feed.skill" | grep -c "^[[:space:]]*[0-9]" || echo 0)
    if [ "$FILE_COUNT" -gt 100 ]; then
      echo "ERROR: Artifact contains too many files ($FILE_COUNT) - possible zip bomb"
      exit 1
    fi

    # Extract to temp directory
    unzip -q "$TEMP_DIR/clawsec-feed.skill" -d "$TEMP_DIR/extracted"

    # Verify skill.json exists
    if [ ! -f "$TEMP_DIR/extracted/clawsec-feed/skill.json" ]; then
      echo "ERROR: skill.json not found in artifact"
      exit 1
    fi

    # Verify checksums for all extracted files
    echo "Verifying checksums..."
    CHECKSUM_FAILED=0
    for file in $(jq -r '.files | keys[]' "$TEMP_DIR/checksums.json"); do
      EXPECTED=$(jq -r --arg f "$file" '.files[$f].sha256' "$TEMP_DIR/checksums.json")
      FILE_PATH=$(jq -r --arg f "$file" '.files[$f].path' "$TEMP_DIR/checksums.json")

      # Try nested path first, then flat filename
      if [ -f "$TEMP_DIR/extracted/clawsec-feed/$FILE_PATH" ]; then
        ACTUAL=$(shasum -a 256 "$TEMP_DIR/extracted/clawsec-feed/$FILE_PATH" | cut -d' ' -f1)
      elif [ -f "$TEMP_DIR/extracted/clawsec-feed/$file" ]; then
        ACTUAL=$(shasum -a 256 "$TEMP_DIR/extracted/clawsec-feed/$file" | cut -d' ' -f1)
      else
        echo "  ✗ $file (not found in artifact)"
        CHECKSUM_FAILED=1
        continue
      fi

      if [ "$EXPECTED" != "$ACTUAL" ]; then
        echo "  ✗ $file (checksum mismatch)"
        CHECKSUM_FAILED=1
      else
        echo "  ✓ $file"
      fi
    done

    if [ "$CHECKSUM_FAILED" -eq 0 ]; then
      # Validate feed.json structure (skill-specific)
      if [ -f "$TEMP_DIR/extracted/clawsec-feed/advisories/feed.json" ]; then
        FEED_FILE="$TEMP_DIR/extracted/clawsec-feed/advisories/feed.json"
      elif [ -f "$TEMP_DIR/extracted/clawsec-feed/feed.json" ]; then
        FEED_FILE="$TEMP_DIR/extracted/clawsec-feed/feed.json"
      else
        echo "ERROR: feed.json not found in artifact"
        exit 1
      fi

      if ! jq -e '.version and .advisories' "$FEED_FILE" >/dev/null 2>&1; then
        echo "ERROR: feed.json missing required fields (version, advisories)"
        exit 1
      fi

      # SUCCESS: Install from artifact
      echo "Installing from artifact..."
      mkdir -p "$INSTALL_DIR"
      cp -r "$TEMP_DIR/extracted/clawsec-feed"/* "$INSTALL_DIR/"
      chmod 600 "$INSTALL_DIR/skill.json"
      find "$INSTALL_DIR" -type f ! -name "skill.json" -exec chmod 644 {} \;
      echo "SUCCESS: Skill installed from .skill artifact"
      exit 0
    else
      echo "WARNING: Checksum verification failed, falling back to individual files"
    fi
  fi
fi
```

--------------------------------

### Minimal ClawSec Skill Structure Example

Source: https://github.com/prompt-security/clawsec/blob/main/CONTRIBUTING.md

An example of the minimal directory structure for a ClawSec skill, containing only the essential skill.json and SKILL.md files.

```tree
skills/
  └── my-security-scanner/
      ├── skill.json
      └── SKILL.md
```

--------------------------------

### Execute Guarded Skill Installation

Source: https://github.com/prompt-security/clawsec/blob/main/wiki/modules/clawsec-suite.md

The guarded_skill_install.mjs script automates the secure installation of skills. It validates the environment and ensures that only authorized versions are deployed.

```javascript
import { install } from './lib/installer';

async function run() {
  await install(process.argv[2]);
}
run();
```

--------------------------------

### Discover and Install Clawsec Skills

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-suite/SKILL.md

This snippet demonstrates how to dynamically list available skills within the Clawsec suite and install specific skills using the clawhub CLI. It requires the suite directory to be defined and the clawhub package to be available.

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

# then install any discovered skill by name
npx clawhub@latest install <skill-name>
```

--------------------------------

### ClawSec Skill Metadata Example

Source: https://github.com/prompt-security/clawsec/blob/main/CONTRIBUTING.md

Example JSON structure for the 'sbom' field within a ClawSec skill's configuration. It lists all files included in the skill, their paths, and a brief description, crucial for integrity verification.

```json
{
  "sbom": {
    "files": [
      {
        "path": "SKILL.md",
        "required": true,
        "description": "Main skill file"
      },
      {
        "path": "config/rules.json",
        "required": false,
        "description": "Optional configuration rules"
      }
    ]
  }
}
```

--------------------------------

### Install Prompt Agent Skill Artifact

Source: https://github.com/prompt-security/clawsec/blob/main/skills/prompt-agent/SKILL.md

This script attempts to download and install the prompt-agent skill from a .skill artifact. It includes security checks for artifact size, path traversal, and file count before extraction and checksum verification. If verification fails, it falls back to downloading individual files.

```bash
echo "Attempting .skill artifact installation..."
if curl -sSL --fail --show-error --retry 3 --retry-delay 1 \
   "$BASE_URL/prompt-agent.skill" -o "$TEMP_DIR/prompt-agent.skill" 2>/dev/null; then

  ARTIFACT_SIZE=$(stat -c%s "$TEMP_DIR/prompt-agent.skill" 2>/dev/null || stat -f%z "$TEMP_DIR/prompt-agent.skill")
  MAX_SIZE=$((50 * 1024 * 1024))  # 50MB

  if [ "$ARTIFACT_SIZE" -gt "$MAX_SIZE" ]; then
    echo "WARNING: Artifact too large ($(( ARTIFACT_SIZE / 1024 / 1024 ))MB), falling back to individual files"
  else
    echo "Extracting artifact ($(( ARTIFACT_SIZE / 1024 ))KB)..."

    if unzip -l "$TEMP_DIR/prompt-agent.skill" | grep -qE '\.\./|^/|~/'; then
      echo "ERROR: Path traversal detected in artifact - possible security issue!"
      exit 1
    fi

    FILE_COUNT=$(unzip -l "$TEMP_DIR/prompt-agent.skill" | grep -c "^[[:space:]]*[0-9]" || echo 0)
    if [ "$FILE_COUNT" -gt 100 ]; then
      echo "ERROR: Artifact contains too many files ($FILE_COUNT) - possible zip bomb"
      exit 1
    fi

    unzip -q "$TEMP_DIR/prompt-agent.skill" -d "$TEMP_DIR/extracted"

    if [ ! -f "$TEMP_DIR/extracted/prompt-agent/skill.json" ]; then
      echo "ERROR: skill.json not found in artifact"
      exit 1
    fi

    echo "Verifying checksums..."
    CHECKSUM_FAILED=0
    for file in $(jq -r '.files | keys[]' "$TEMP_DIR/checksums.json"); do
      EXPECTED=$(jq -r --arg f "$file" '.files[$f].sha256' "$TEMP_DIR/checksums.json")
      FILE_PATH=$(jq -r --arg f "$file" '.files[$f].path' "$TEMP_DIR/checksums.json")

      if [ -f "$TEMP_DIR/extracted/prompt-agent/$FILE_PATH" ]; then
        ACTUAL=$(shasum -a 256 "$TEMP_DIR/extracted/prompt-agent/$FILE_PATH" | cut -d' ' -f1)
      elif [ -f "$TEMP_DIR/extracted/prompt-agent/$file" ]; then
        ACTUAL=$(shasum -a 256 "$TEMP_DIR/extracted/prompt-agent/$file" | cut -d' ' -f1)
      else
        echo "  ✗ $file (not found in artifact)"
        CHECKSUM_FAILED=1
        continue
      fi

      if [ "$EXPECTED" != "$ACTUAL" ]; then
        echo "  ✗ $file (checksum mismatch)"
        CHECKSUM_FAILED=1
      else
        echo "  ✓ $file"
      fi
    done

    if [ "$CHECKSUM_FAILED" -eq 0 ]; then
      echo "Installing from artifact..."
      mkdir -p "$INSTALL_DIR"
      cp -r "$TEMP_DIR/extracted/prompt-agent"/* "$INSTALL_DIR/"
      chmod 600 "$INSTALL_DIR/skill.json"
      find "$INSTALL_DIR" -type f ! -name "skill.json" -exec chmod 644 {} \;
      echo "SUCCESS: Skill installed from .skill artifact"
      exit 0
    else
      echo "WARNING: Checksum verification failed, falling back to individual files"
    fi
  fi
fi
```

--------------------------------

### Install and Run OpenClaw Audit Watchdog (Bash)

Source: https://github.com/prompt-security/clawsec/blob/main/skills/openclaw-audit-watchdog/README.md

This snippet shows how to install the OpenClaw Audit Watchdog skill, set necessary environment variables for email reporting and host labeling, and then run the audit script using bash.

```bash
# Install skill
mkdir -p ~/.openclaw/skills/openclaw-audit-watchdog
cd ~/.openclaw/skills/openclaw-audit-watchdog

# Download and extract
curl -sSL "https://github.com/prompt-security/clawsec/releases/download/$VERSION_TAG/openclaw-audit-watchdog.skill" -o watchdog.skill
unzip watchdog.skill

# Configure
export PROMPTSEC_EMAIL_TO="security@yourcompany.com"
export PROMPTSEC_HOST_LABEL="prod-agent-1"

# Run
./scripts/runner.sh
```

--------------------------------

### Initialize Local Development Environment

Source: https://github.com/prompt-security/clawsec/blob/main/wiki/overview.md

Commands to install dependencies, populate local security data feeds, and launch the development server. This is the standard workflow for previewing the UI with local data.

```bash
npm install
./scripts/populate-local-skills.sh
./scripts/populate-local-feed.sh --days 120
npm run dev
```

--------------------------------

### Quick Install Clawtributor Skill

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawtributor/README.md

This command downloads the latest Clawtributor skill using curl. It's a straightforward way to get the tool set up for reporting incidents.

```bash
curl -sLO https://clawsec.prompt.security/releases/latest/download/clawtributor.skill
```

--------------------------------

### Test Signing and Verification Workflow

Source: https://github.com/prompt-security/clawsec/blob/main/wiki/security-signing-runbook.md

Demonstrates the process of signing a sample JSON file and verifying the signature to ensure the keypair is functioning correctly.

```bash
echo '{"probe":"ok"}' > /tmp/probe.json
openssl pkeyutl -sign -rawin -inkey feed-signing-private.pem -in /tmp/probe.json -out /tmp/probe.sig.bin
openssl base64 -A -in /tmp/probe.sig.bin -out /tmp/probe.sig
openssl base64 -d -A -in /tmp/probe.sig -out /tmp/probe.sig.bin
openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/probe.json -sigfile /tmp/probe.sig.bin
```

--------------------------------

### Release Pre-release Versions

Source: https://github.com/prompt-security/clawsec/blob/main/skills/claw-release/SKILL.md

Examples of using the release script to deploy beta, alpha, or release candidate versions.

```bash
./scripts/release-skill.sh <skill-name> 1.2.0-beta1
./scripts/release-skill.sh <skill-name> 1.2.0-alpha1
./scripts/release-skill.sh <skill-name> 1.2.0-rc1
```

--------------------------------

### Local Development Setup

Source: https://context7.com/prompt-security/clawsec/llms.txt

Commands to initialize and run the ClawSec development environment.

```APIDOC
## Local Development Setup

### Description
Instructions for setting up the development environment, populating local data, and running the server.

### Commands
- `npm install`: Install dependencies
- `./scripts/populate-local-skills.sh`: Populate skills catalog
- `./scripts/populate-local-feed.sh --days 120`: Populate advisory feed
- `npm run dev`: Start development server
- `npm run build`: Build for production
```

--------------------------------

### Interact with NanoClaw MCP Security Tools via TypeScript

Source: https://context7.com/prompt-security/clawsec/llms.txt

Provides TypeScript examples for interacting with NanoClaw's MCP (Meta-Command Processor) security tools. This includes checking skill safety, auditing installed skills for vulnerabilities, listing advisories, verifying skill package signatures, refreshing the advisory cache, checking file integrity, approving baseline changes, and verifying audit logs.

```typescript
// Pre-installation safety check before installing any skill
const safety = await tools.clawsec_check_skill_safety({
  skillName: 'new-skill',
  skillVersion: '1.0.0'  // optional
});

if (!safety.safe) {
  console.warn(`Security issues: ${safety.advisories.map(a => a.id)}`);
}

// Audit all installed skills for vulnerabilities
const result = await tools.clawsec_check_advisories({
  installRoot: '/home/node/.claude/skills'  // optional, defaults to ~/.claude/skills
});

if (result.matches.some((m) =>
  m.advisory.severity === 'critical' || m.advisory.exploitability_score === 'high'
)) {
  console.error('Urgent advisories found!');
}

// List advisories with filters
const advisories = await tools.clawsec_list_advisories({
  severity: 'high',               // optional filter
  exploitabilityScore: 'high'     // optional filter
});

// Verify Ed25519 signature on skill package
const verification = await tools.clawsec_verify_skill_package({
  packagePath: '/tmp/skill-package.zip'
});

// Request immediate advisory cache refresh
await tools.clawsec_refresh_cache();

// Check file integrity for protected files
const integrity = await tools.clawsec_check_integrity({
  mode: 'check',      // 'check' or 'restore'
  autoRestore: true   // optional
});

// Approve intentional file modification as new baseline
await tools.clawsec_approve_change({
  path: 'SOUL.md'
});

// View current baseline status
const status = await tools.clawsec_integrity_status({
  path: 'SOUL.md'  // optional, omit for all files
});

// Verify audit log hash chain
const auditVerification = await tools.clawsec_verify_audit();
```

--------------------------------

### Preview Production Build

Source: https://github.com/prompt-security/clawsec/blob/main/AGENTS.md

Serves the production build locally, allowing you to preview the application as it would appear in a production environment. Useful for final checks before deployment.

```bash
npm run preview
```

--------------------------------

### Combined Security Checks for Skill Installation

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-nanoclaw/docs/SKILL_SIGNING.md

Performs a comprehensive security check before installing a skill. This involves verifying the skill package's signature and checking for known vulnerabilities through an advisory service. It ensures that only safe and authentic packages are installed.

```typescript
async function installSkillSafely(packagePath: string, skillName: string) {
  // Step 1: Verify signature
  const sigVerify = await tools.clawsec_verify_skill_package({ packagePath });
  const sigResult = JSON.parse(sigVerify.content[0].text);

  if (!sigResult.valid) {
    throw new Error(`Signature invalid: ${sigResult.reason}`);
  }

  // Step 2: Check advisories
  const advisory = await tools.clawsec_check_skill_safety({ skillName });
  const advResult = JSON.parse(advisory.content[0].text);

  if (!advResult.safe) {
    throw new Error(`Known vulnerabilities: ${advResult.advisories.map(a => a.id).join(', ')}`);
  }

  // Both checks passed - safe to install
  extractPackage(packagePath, '/workspace/project/skills/');
  console.log(`✓ Installed ${skillName} (verified + no advisories)`);
}
```

--------------------------------

### Check Installed Skills Against Security Advisories (Bash)

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-feed/SKILL.md

This script checks installed skills against a security advisory feed. It fetches the feed, parses it to identify affected skills, validates installed skill names to prevent injection, and then reports any installed skills that have matching advisories. It uses curl for fetching, jq for JSON parsing, and find/grep for file system operations and string matching.

```bash
# List your installed skills (adjust path for your platform)
INSTALL_DIR="${CLAWSEC_INSTALL_DIR:-$HOME/.openclaw/skills}"

# Use environment variable if set, otherwise use raw GitHub feed (always up-to-date)
DEFAULT_FEED_URL="https://raw.githubusercontent.com/prompt-security/ClawSec/main/advisories/feed.json"
FEED_URL="${CLAWSEC_FEED_URL:-$DEFAULT_FEED_URL}"

TEMP_FEED=$(mktemp)
trap "rm -f '$TEMP_FEED'" EXIT

if ! curl -sSL --fail --show-error --retry 3 --retry-delay 1 "$FEED_URL" -o "$TEMP_FEED"; then
  echo "Error: Failed to fetch advisory feed"
  exit 1
fi

# Validate and parse feed
if ! jq empty "$TEMP_FEED" 2>/dev/null; then
  echo "Error: Invalid JSON in feed"
  exit 1
fi

FEED=$(cat "$TEMP_FEED")
AFFECTED=$(echo "$FEED" | jq -r '.advisories[].affected[]?' 2>/dev/null | sort -u)
if [ $? -ne 0 ]; then
  echo "Error: Failed to parse affected skills from feed"
  exit 1
fi

# Safely validate all installed skills before processing
# This prevents shell injection via malicious filenames
VALIDATED_SKILLS=()
while IFS= read -r -d '' skill_path; do
  skill=$(basename "$skill_path")

  # Validate skill name BEFORE adding to array (prevents injection)
  if [[ "$skill" =~ ^[a-zA-Z0-9_-]+$ ]]; then
    VALIDATED_SKILLS+=("$skill")
  else
    echo "Warning: Skipping invalid skill name: $skill" >&2
  fi
done < <(find "$INSTALL_DIR" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null)

# Check each validated skill against affected list
# Use grep -qF for fixed string matching (prevents regex injection)
for skill in "${VALIDATED_SKILLS[@]}"; do
  # At this point, $skill is guaranteed to match ^[a-zA-Z0-9_-]+$
  if echo "$AFFECTED" | grep -qF "$skill"; then
    echo "WARNING: Installed skill '$skill' has a security advisory!"
    # Get advisory details for this skill
    echo "$FEED" | jq --arg s "$skill" '.advisories[] | select(.affected[] | contains($s))'
  fi
done
```

--------------------------------

### Detect Agent Environment and Initialize Directory

Source: https://github.com/prompt-security/clawsec/blob/main/skills/prompt-agent/SKILL.md

Scans the user's home directory for supported AI agent configurations (.openclaw, .moltbot, or .clawdbot) and creates the necessary skill directory structure.

```bash
AGENT_HOME=""
for folder in "$HOME/.openclaw" "$HOME/.moltbot" "$HOME/.clawdbot"; do
  if [ -d "$folder" ]; then
    AGENT_HOME="$folder"
    break
  fi
done

if [ -z "$AGENT_HOME" ]; then
  echo "ERROR: No agent folder found. Expected one of: ~/.openclaw, ~/.moltbot, ~/.clawdbot"
  echo "Please ensure your agent is properly installed."
  exit 1
fi

echo "Detected agent folder: $AGENT_HOME"
mkdir -p "$AGENT_HOME/skills/prompt-agent"
```

--------------------------------

### Guarded Skill Install Flow (Second Confirmation)

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-suite/SKILL.md

This script performs the second confirmation step for a guarded skill installation. After the initial check and advisory warning, this command is run with the --confirm-advisory flag to explicitly approve the installation, ensuring the user is aware of any associated advisories.

```bash
node "$SUITE_DIR/scripts/guarded_skill_install.mjs" --skill helper-plus --version 1.0.1 --confirm-advisory
```

--------------------------------

### Run Local Development Server with Vite

Source: https://github.com/prompt-security/clawsec/blob/main/AGENTS.md

Starts a local development server using Vite, enabling hot-reloading and quick iteration during frontend development. Access the application via the provided local URL.

```bash
npm run dev
```

--------------------------------

### Complex ClawSec Skill Structure Example

Source: https://github.com/prompt-security/clawsec/blob/main/CONTRIBUTING.md

An example of a more complex directory structure for a ClawSec skill, including additional configuration, scripts, and templates.

```tree
skills/
  └── advanced-analyzer/
      ├── skill.json
      ├── SKILL.md
      ├── README.md
      ├── templates/
      │   └── report-template.md
      ├── scripts/
      │   └── action.py
      └── config/
          └── rules.json
```

--------------------------------

### Configure OpenClaw Audit Watchdog Paths (Bash/PowerShell)

Source: https://github.com/prompt-security/clawsec/blob/main/skills/openclaw-audit-watchdog/README.md

Demonstrates how to correctly set installation directory and audit configuration paths, supporting environment variables and path expansion in both Bash and PowerShell to avoid issues with single quotes.

```bash
# In bash/zsh, use double quotes for expandable paths:
export PROMPTSEC_INSTALL_DIR="$HOME/.config/security-checkup"
# Avoid single-quoted literals such as '$HOME/.config/security-checkup'.
```

```powershell
# In PowerShell:
$env:PROMPTSEC_INSTALL_DIR = Join-Path $HOME ".config/security-checkup"
```

--------------------------------

### Execute Security Audit on Installed Skills

Source: https://github.com/prompt-security/clawsec/blob/main/skills/clawsec-nanoclaw/SKILL.md

Scans installed skills against the advisory database. It is recommended to filter results by severity and exploitability score to prioritize critical threats.

```typescript
const result = await tools.clawsec_check_advisories({
  installRoot: '/home/node/.claude/skills'
});

if (result.matches.some((m) =>
  m.advisory.severity === 'critical' || m.advisory.exploitability_score === 'high'
)) {
  console.error('Urgent advisories found!');
}
```