docs(readme): include full published skills catalog

fix(release): enforce changelog match for tagged skill releases (#118 )
Automated Vulnerability Scanner Skill (clawsec-scanner) (#101 )
2026-06-20 17:01:20 +03:00 · 2026-03-09 22:09:50 +02:00 · 2026-03-09 21:30:52 +02:00 · 2026-03-09 21:16:22 +02:00 · 2026-03-09 19:30:22 +02:00 · 2026-03-09 10:10:59 +02:00
136 changed files with 16890 additions and 1413 deletions
@@ -1,2 +1,2 @@
-ruff==0.15.1
+ruff==0.15.2
 bandit==1.9.3
@@ -3,8 +3,7 @@ name: CI
 on:
  pull_request:
    branches: [main]
-  push:
-    branches: [main]
+  workflow_dispatch:

 permissions: read-all

@@ -31,6 +30,7 @@ jobs:
      - name: TypeScript Check
        run: npx tsc --noEmit
      - name: Build Check
+        if: matrix.os == 'ubuntu-latest'
        run: npm run build

  lint-python:
@@ -63,7 +63,7 @@ jobs:
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Trivy FS Scan
-        uses: aquasecurity/trivy-action@c1824fd6edce30d7ab345a9989de00bbd46ef284 # 0.34.0
+        uses: aquasecurity/trivy-action@e368e328979b113139d6f9068e03accaed98a518 # 0.34.1
        with:
          scan-type: 'fs'
          scan-ref: '.'
@@ -71,7 +71,7 @@ jobs:
          exit-code: '1'
          ignore-unfixed: true
      - name: Trivy Config Scan
-        uses: aquasecurity/trivy-action@c1824fd6edce30d7ab345a9989de00bbd46ef284 # 0.34.0
+        uses: aquasecurity/trivy-action@e368e328979b113139d6f9068e03accaed98a518 # 0.34.1
        with:
          scan-type: 'config'
          scan-ref: '.'
@@ -101,6 +101,8 @@ jobs:
      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
        with:
          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
      - name: Feed Verification Tests
        run: node skills/clawsec-suite/test/feed_verification.test.mjs
      - name: Guarded Install Tests
@@ -109,6 +111,10 @@ jobs:
        run: node skills/clawsec-suite/test/advisory_suppression.test.mjs
      - name: Path Resolution Tests
        run: node skills/clawsec-suite/test/path_resolution.test.mjs
+      - name: Fuzz Property Tests
+        run: node skills/clawsec-suite/test/fuzz_properties.test.mjs
+      - name: Semver/Scope/Suppression Fuzz Tests
+        run: node skills/clawsec-suite/test/fuzz_semver_scope_suppression.test.mjs
      - name: Advisory Application Scope Tests
        run: node skills/clawsec-suite/test/advisory_application_scope.test.mjs

@@ -120,7 +126,11 @@ jobs:
      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
        with:
          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
      - name: Suppression Config Tests
        run: node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
+      - name: Suppression Config Fuzz Tests
+        run: node skills/openclaw-audit-watchdog/test/suppression_config_fuzz.test.mjs
      - name: Render Report Suppression Tests
        run: node skills/openclaw-audit-watchdog/test/render_report_suppression.test.mjs
@@ -1,10 +1,9 @@
 name: CodeQL

 on:
-  push:
-    branches: [main]
  pull_request:
    branches: [main]
+  workflow_dispatch:
  schedule:
    - cron: "17 3 * * 1"

@@ -28,7 +27,7 @@ jobs:
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Initialize CodeQL
-        uses: github/codeql-action/init@9e907b5e64f6b83e7804b09294d44122997950d6 # v4
+        uses: github/codeql-action/init@89a39a4e59826350b863aa6b6252a07ad50cf83e # v4
        with:
          languages: ${{ matrix.language }}

@@ -38,4 +37,4 @@ jobs:
      - name: Build project
        run: npm run build
      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@9e907b5e64f6b83e7804b09294d44122997950d6 # v4
+        uses: github/codeql-action/analyze@89a39a4e59826350b863aa6b6252a07ad50cf83e # v4
@@ -20,10 +20,6 @@ jobs:
  process-advisory:
    if: github.event.label.name == 'advisory-approved'
    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      issues: write
-      pull-requests: write
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -117,6 +113,32 @@ jobs:
          fi
          echo "Affected: $AFFECTED"

+          # Build platforms array
+          OPENCLAW_SELECTED="false"
+          if echo "$ISSUE_BODY" | grep -qi '^[[:space:]]*-[[:space:]]*\[[xX]\][[:space:]]*OpenClaw'; then
+            OPENCLAW_SELECTED="true"
+          fi
+
+          OTHER_PLATFORM_RAW=$(echo "$ISSUE_BODY" | sed -n 's/^[[:space:]]*-[[:space:]]*\[[xX]\][[:space:]]*Other:[[:space:]]*\(.*\)$/\1/p' | head -1 | xargs)
+          OTHER_PLATFORM=""
+          if [ -n "$OTHER_PLATFORM_RAW" ]; then
+            OTHER_PLATFORM=$(echo "$OTHER_PLATFORM_RAW" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9._-]+/-/g; s/^-+//; s/-+$//')
+            if echo "$OTHER_PLATFORM" | grep -q 'nanoclaw'; then
+              OTHER_PLATFORM="nanoclaw"
+            fi
+          fi
+
+          PLATFORMS=$(jq -n --arg open "$OPENCLAW_SELECTED" --arg other "$OTHER_PLATFORM" '
+            [
+              (if $open == "true" then "openclaw" else empty end),
+              (if ($other | length) > 0 then $other else empty end)
+            ] | unique
+          ')
+          if [ "$PLATFORMS" = "[]" ]; then
+            PLATFORMS='["openclaw","nanoclaw"]'
+          fi
+          echo "Platforms: $PLATFORMS"
+
          # Parse recommended action
          ACTION=$(echo "$ISSUE_BODY" | sed -n '/^## Recommended Action/,/^---/p' | grep -v '^## Recommended Action' | grep -v '^---' | grep -v '^<!--' | sed '/^\s*$/d' | tr '\n' ' ' | xargs)
          if [ -z "$ACTION" ]; then
@@ -142,6 +164,7 @@ jobs:
            --arg title "$TITLE" \
            --arg description "$DESCRIPTION" \
            --argjson affected "$AFFECTED" \
+            --argjson platforms "$PLATFORMS" \
            --arg action "$ACTION" \
            --arg published "$PUBLISHED" \
            --arg source "Community Report" \
@@ -155,6 +178,7 @@ jobs:
              title: $title,
              description: $description,
              affected: $affected,
+              platforms: $platforms,
              action: $action,
              published: $published,
              references: [],
@@ -169,6 +193,27 @@ jobs:
          echo "Created advisory JSON:"
          cat tmp_advisory.json

+      - name: Set up Python for exploitability analysis
+        if: steps.parse.outputs.already_exists != 'true'
+        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+        with:
+          python-version: '3.10'
+
+      - name: Analyze exploitability for community advisory
+        if: steps.parse.outputs.already_exists != 'true'
+        run: |
+          set -euo pipefail
+
+          echo "=== Analyzing exploitability for community advisory ==="
+
+          scripts/ci/enrich_exploitability.sh \
+            --mode single \
+            --input tmp_advisory.json \
+            --output tmp_advisory.json
+
+          echo "=== Exploitability analysis complete ==="
+          echo "Exploitability score: $(jq -r '.exploitability_score // "unknown"' tmp_advisory.json)"
+
      - name: Update feed
        if: steps.parse.outputs.already_exists != 'true'
        run: |
@@ -216,12 +261,21 @@ jobs:
        if: steps.parse.outputs.already_exists != 'true'
        run: cp "$FEED_SIG_PATH" "$SKILL_FEED_SIG_PATH"

+      - name: Require automation token for write operations
+        env:
+          AUTOMATION_TOKEN: ${{ secrets.POLL_NVD_CVES_PAT }}
+        run: |
+          if [ -z "$AUTOMATION_TOKEN" ]; then
+            echo "::error::Set POLL_NVD_CVES_PAT with repo write permissions."
+            exit 1
+          fi
+
      - name: Create Pull Request
        if: steps.parse.outputs.already_exists != 'true'
        id: create-pr
        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.POLL_NVD_CVES_PAT }}
          branch: automated/community-advisory-${{ github.event.issue.number }}
          delete-branch: true
          title: "chore: add community advisory ${{ steps.parse.outputs.advisory_id }}"
@@ -250,6 +304,7 @@ jobs:
        if: steps.parse.outputs.already_exists != 'true'
        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
        with:
+          github-token: ${{ secrets.POLL_NVD_CVES_PAT }}
          script: |
            const advisoryId = '${{ steps.parse.outputs.advisory_id }}';
            const pullRequestUrl = '${{ steps.create-pr.outputs.pull-request-url }}';
@@ -275,6 +330,7 @@ jobs:
        if: steps.parse.outputs.already_exists == 'true'
        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
        with:
+          github-token: ${{ secrets.POLL_NVD_CVES_PAT }}
          script: |
            const advisoryId = '${{ steps.parse.outputs.advisory_id }}';
            await github.rest.issues.createComment({
@@ -1,10 +1,11 @@
 name: Deploy to GitHub Pages

 on:
+  push:
+    branches: [main]
  workflow_run:
-    workflows: ["CI", "Skill Release"]
+    workflows: ["Skill Release"]
    types: [completed]
-    # Note: No branch restriction - must trigger on both main branch CI runs AND tag-based Skill Releases
  workflow_dispatch:

 permissions:
@@ -19,8 +20,20 @@ concurrency:
 jobs:
  build:
    runs-on: ubuntu-latest
-    # Only run if workflow_dispatch OR the triggering workflow succeeded
-    if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
+    # Production build only: manual dispatch, push to main, or trusted release workflows.
+    # PR validation runs in .github/workflows/pages-verify.yml.
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event_name == 'push' &&
+        github.ref_name == 'main'
+      ) ||
+      (
+        github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.name == 'Skill Release' &&
+        github.event.workflow_run.event != 'pull_request'
+      )
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -401,7 +414,19 @@ jobs:
          path: ./dist

  deploy:
-    # Deploy after build succeeds (CI or Skill Release must pass first, or manual dispatch)
+    # Deploy after a production build succeeds.
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event_name == 'push' &&
+        github.ref_name == 'main'
+      ) ||
+      (
+        github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.name == 'Skill Release' &&
+        github.event.workflow_run.event != 'pull_request'
+      )
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
@@ -0,0 +1,111 @@
+name: Pages Verify
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-verify-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify-pages-build:
+    name: Verify Pages Build (No Publish)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Verify signing key consistency (repo + docs)
+        run: ./scripts/ci/verify_signing_key_consistency.sh
+
+      - name: Prepare advisory artifacts for pre-deploy checks
+        run: |
+          set -euo pipefail
+          mkdir -p public/advisories
+          cp advisories/feed.json public/advisories/feed.json
+
+      - name: Generate advisory checksums manifest
+        run: |
+          set -euo pipefail
+
+          FEED_FILE="public/advisories/feed.json"
+          FEED_SHA=$(sha256sum "$FEED_FILE" | awk '{print $1}')
+          FEED_SIZE=$(stat -c%s "$FEED_FILE" 2>/dev/null || stat -f%z "$FEED_FILE")
+
+          jq -n \
+            --arg schema_version "1" \
+            --arg algorithm "sha256" \
+            --arg version "1.1.0" \
+            --arg generated "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --arg repo "${{ github.repository }}" \
+            --arg sha "$FEED_SHA" \
+            --argjson size "$FEED_SIZE" \
+            '{
+              schema_version: $schema_version,
+              algorithm: $algorithm,
+              version: $version,
+              generated_at: $generated,
+              repository: $repo,
+              files: {
+                "advisories/feed.json": {
+                  sha256: $sha,
+                  size: $size,
+                  path: "advisories/feed.json",
+                  url: "https://clawsec.prompt.security/advisories/feed.json"
+                }
+              }
+            }' > public/checksums.json
+
+      - name: Generate ephemeral signing key for PR verification
+        id: test_key
+        run: |
+          set -euo pipefail
+          KEY_FILE=$(mktemp)
+          openssl genpkey -algorithm Ed25519 -out "$KEY_FILE"
+          {
+            echo "private_key<<EOF"
+            cat "$KEY_FILE"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+          rm -f "$KEY_FILE"
+
+      - name: Sign advisory feed and verify
+        uses: ./.github/actions/sign-and-verify
+        with:
+          private_key: ${{ steps.test_key.outputs.private_key }}
+          input_file: public/advisories/feed.json
+          signature_file: public/advisories/feed.json.sig
+          public_key_output: public/signing-public.pem
+
+      - name: Sign checksums and verify
+        uses: ./.github/actions/sign-and-verify
+        with:
+          private_key: ${{ steps.test_key.outputs.private_key }}
+          input_file: public/checksums.json
+          signature_file: public/checksums.sig
+
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: npm run build
+        env:
+          NODE_ENV: production
+
+      - name: Sanity-check generated artifacts
+        run: |
+          set -euo pipefail
+          test -f dist/index.html
+          test -f public/advisories/feed.json.sig
+          test -f public/checksums.sig
+          test -f public/signing-public.pem
@@ -7,7 +7,7 @@ on:
  workflow_dispatch:
    inputs:
      force_full_scan:
-        description: 'Ignore last poll date and scan all CVEs'
+        description: 'Ignore feed state and rebuild CVE advisories from full NVD history'
        required: false
        default: 'false'
        type: boolean
@@ -30,6 +30,7 @@ jobs:
  poll-and-update:
    runs-on: ubuntu-latest
    permissions:
+      actions: write
      contents: write
      pull-requests: write
    steps:
@@ -85,6 +86,7 @@ jobs:
        run: |
          set -euo pipefail
          mkdir -p tmp
+          FORCE_FULL_SCAN="${{ inputs.force_full_scan }}"
          
          START_DATE="${{ steps.dates.outputs.start_date }}"
          END_DATE="${{ steps.dates.outputs.end_date }}"
@@ -100,35 +102,93 @@ jobs:
          # Fetch for each keyword
          for KEYWORD in $KEYWORDS; do
            echo "Fetching keyword: $KEYWORD"
-            
-            URL="https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=${KEYWORD}&lastModStartDate=${START_ENC}&lastModEndDate=${END_ENC}"
-            echo "URL: $URL"
-            
-            # Fetch with retry logic
+
            keyword_ok=false
            last_http_code=""
-            for i in 1 2 3; do
-              HTTP_CODE=$(curl -sS -w "%{http_code}" -o "tmp/nvd_${KEYWORD}.json" "$URL" || true)
-              if [ -z "$HTTP_CODE" ]; then
-                HTTP_CODE="000"
-              fi
-              last_http_code="$HTTP_CODE"
-              if [ "$HTTP_CODE" = "200" ]; then
-                if jq -e . "tmp/nvd_${KEYWORD}.json" >/dev/null 2>&1; then
-                  echo "Success for $KEYWORD"
+
+            if [ "$FORCE_FULL_SCAN" = "true" ]; then
+              echo "Full scan mode enabled: paginating complete NVD history for keyword '$KEYWORD'"
+              echo '{"vulnerabilities":[]}' > "tmp/nvd_${KEYWORD}.json"
+              START_INDEX=0
+              RESULTS_PER_PAGE=2000
+
+              while true; do
+                URL="https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=${KEYWORD}&startIndex=${START_INDEX}&resultsPerPage=${RESULTS_PER_PAGE}"
+                PAGE_FILE="tmp/nvd_${KEYWORD}_${START_INDEX}.json"
+                echo "URL: $URL"
+
+                page_ok=false
+                for i in 1 2 3; do
+                  HTTP_CODE=$(curl -sS -w "%{http_code}" -o "$PAGE_FILE" "$URL" || true)
+                  if [ -z "$HTTP_CODE" ]; then
+                    HTTP_CODE="000"
+                  fi
+                  last_http_code="$HTTP_CODE"
+                  if [ "$HTTP_CODE" = "200" ]; then
+                    if jq -e . "$PAGE_FILE" >/dev/null 2>&1; then
+                      page_ok=true
+                      break
+                    fi
+                    echo "Invalid JSON for $KEYWORD page $START_INDEX, retry $i..."
+                    sleep 5
+                  elif [ "$HTTP_CODE" = "403" ] || [ "$HTTP_CODE" = "429" ]; then
+                    echo "Rate limited, waiting 30s before retry $i..."
+                    sleep 30
+                  else
+                    echo "HTTP $HTTP_CODE for $KEYWORD page $START_INDEX, retry $i..."
+                    sleep 5
+                  fi
+                done
+
+                if [ "$page_ok" != "true" ]; then
+                  break
+                fi
+
+                jq -s '.[0].vulnerabilities += .[1].vulnerabilities | .[0]' \
+                  "tmp/nvd_${KEYWORD}.json" "$PAGE_FILE" > "tmp/nvd_${KEYWORD}_merged.json"
+                mv "tmp/nvd_${KEYWORD}_merged.json" "tmp/nvd_${KEYWORD}.json"
+
+                PAGE_COUNT=$(jq '.vulnerabilities | length' "$PAGE_FILE")
+                TOTAL_RESULTS=$(jq '.totalResults // 0' "$PAGE_FILE")
+                echo "Fetched $PAGE_COUNT results at startIndex=$START_INDEX (totalResults=$TOTAL_RESULTS)"
+
+                START_INDEX=$((START_INDEX + RESULTS_PER_PAGE))
+                if [ "$START_INDEX" -ge "$TOTAL_RESULTS" ] || [ "$PAGE_COUNT" -eq 0 ]; then
                  keyword_ok=true
                  break
                fi
-                echo "Invalid JSON for $KEYWORD, retry $i..."
-                sleep 5
-              elif [ "$HTTP_CODE" = "403" ] || [ "$HTTP_CODE" = "429" ]; then
-                echo "Rate limited, waiting 30s before retry $i..."
-                sleep 30
-              else
-                echo "HTTP $HTTP_CODE for $KEYWORD, retry $i..."
-                sleep 5
-              fi
-            done
+
+                # NVD recommends 6 second delay between requests
+                sleep 6
+              done
+            else
+              URL="https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=${KEYWORD}&lastModStartDate=${START_ENC}&lastModEndDate=${END_ENC}"
+              echo "URL: $URL"
+
+              # Fetch with retry logic
+              for i in 1 2 3; do
+                HTTP_CODE=$(curl -sS -w "%{http_code}" -o "tmp/nvd_${KEYWORD}.json" "$URL" || true)
+                if [ -z "$HTTP_CODE" ]; then
+                  HTTP_CODE="000"
+                fi
+                last_http_code="$HTTP_CODE"
+                if [ "$HTTP_CODE" = "200" ]; then
+                  if jq -e . "tmp/nvd_${KEYWORD}.json" >/dev/null 2>&1; then
+                    echo "Success for $KEYWORD"
+                    keyword_ok=true
+                    break
+                  fi
+                  echo "Invalid JSON for $KEYWORD, retry $i..."
+                  sleep 5
+                elif [ "$HTTP_CODE" = "403" ] || [ "$HTTP_CODE" = "429" ]; then
+                  echo "Rate limited, waiting 30s before retry $i..."
+                  sleep 30
+                else
+                  echo "HTTP $HTTP_CODE for $KEYWORD, retry $i..."
+                  sleep 5
+                fi
+              done
+            fi

            if [ "$keyword_ok" != "true" ]; then
              echo "::error::Failed to fetch valid NVD response for keyword '$KEYWORD' (last HTTP code: ${last_http_code:-unknown})."
@@ -175,7 +235,7 @@ jobs:
          echo "Total unique CVEs from NVD: $TOTAL"
          
          # Post-filter: keep only CVEs where description contains keywords OR references contain github pattern
-          KEYWORDS_PATTERN="OpenClaw|clawdbot|Moltbot|openclaw"
+          KEYWORDS_PATTERN="OpenClaw|clawdbot|Moltbot|openclaw|NanoClaw|nanoclaw|WhatsApp-bot|baileys"
          GITHUB_PATTERN="${GITHUB_REF_PATTERN}"
          
          jq --arg kw "$KEYWORDS_PATTERN" --arg gh "$GITHUB_PATTERN" '
@@ -211,6 +271,14 @@ jobs:
      - name: Check for updates to existing advisories
        id: updates
        run: |
+          if [ "${{ inputs.force_full_scan }}" = "true" ]; then
+            echo "Full scan mode enabled: skipping delta update detection."
+            echo '[]' > tmp/updated_advisories.json
+            echo "Advisories to update: 0"
+            echo "update_count=0" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
          # Compare existing CVE advisories against NVD data for changes
          # Only check advisories that start with "CVE-" (NVD-sourced)

@@ -297,6 +365,51 @@ jobs:
                  end
              );

+            def cpe_criteria:
+              (
+                [.cve.configurations[]? | .. | objects | .criteria? | strings | select(startswith("cpe:2.3:"))]
+                | unique
+              );
+
+            def context_blob:
+              (
+                [
+                  (.cve.descriptions[]? | select(.lang == "en") | .value),
+                  (.cve.references[]?.url // empty)
+                ]
+                | map(strings | ascii_downcase)
+                | join(" ")
+              );
+
+            def inferred_targets:
+              (
+                context_blob as $blob
+                | (
+                    (if ($blob | test("github\\.com/openclaw/openclaw|\\bopenclaw\\b|\\bclawdbot\\b|\\bmoltbot\\b")) then ["openclaw@*"] else [] end)
+                    + (if ($blob | test("github\\.com/qwibitai/nanoclaw|\\bnanoclaw\\b|whatsapp-bot|\\bbaileys\\b")) then ["nanoclaw@*"] else [] end)
+                  )
+              );
+
+            def normalized_affected:
+              (
+                (cpe_criteria + inferred_targets)
+                | unique
+                | .[0:5]
+                | if length == 0 then ["openclaw@*", "nanoclaw@*"] else . end
+              );
+
+            def normalized_platforms:
+              (
+                inferred_targets as $targets
+                | ($targets | map(select(startswith("openclaw@"))) | length > 0) as $has_openclaw
+                | ($targets | map(select(startswith("nanoclaw@"))) | length > 0) as $has_nanoclaw
+                | if $has_openclaw and $has_nanoclaw then ["openclaw", "nanoclaw"]
+                  elif $has_openclaw then ["openclaw"]
+                  elif $has_nanoclaw then ["nanoclaw"]
+                  else ["openclaw", "nanoclaw"]
+                  end
+              );
+
            [.[] | {
              id: .cve.id,
              severity: (get_cvss_score | map_severity),
@@ -305,7 +418,11 @@ jobs:
              cvss_score: get_cvss_score,
              description: (.cve.descriptions[] | select(.lang == "en") | .value),
              title: (.cve.descriptions[] | select(.lang == "en") | .value | .[0:100] + (if length > 100 then "..." else "" end)),
-              references: [.cve.references[]?.url // empty] | unique | .[0:3]
+              affected: normalized_affected,
+              platforms: normalized_platforms,
+              references: [.cve.references[]?.url // empty] | unique | .[0:3],
+              exploitability_score: null,
+              exploitability_rationale: null
            }]
          ' tmp/filtered_cves.json > tmp/nvd_current_state.json

@@ -325,6 +442,8 @@ jobs:
                   ($existing_entry.type != $nvd_entry.type) or
                   ($existing_entry.nvd_category_id != $nvd_entry.nvd_category_id) or
                   ($existing_entry.cvss_score != $nvd_entry.cvss_score) or
+                   ($existing_entry.affected != $nvd_entry.affected) or
+                   ($existing_entry.platforms != $nvd_entry.platforms) or
                   ($existing_entry.description != $nvd_entry.description) then
                  {
                    id: $nvd_entry.id,
@@ -334,6 +453,8 @@ jobs:
                      + (if $existing_entry.type != $nvd_entry.type then ["type: \($existing_entry.type // "null") → \($nvd_entry.type // "null")"] else [] end)
                      + (if $existing_entry.nvd_category_id != $nvd_entry.nvd_category_id then ["nvd_category_id: \($existing_entry.nvd_category_id // "null") → \($nvd_entry.nvd_category_id // "null")"] else [] end)
                      + (if $existing_entry.cvss_score != $nvd_entry.cvss_score then ["cvss_score: \($existing_entry.cvss_score // "null") → \($nvd_entry.cvss_score // "null")"] else [] end)
+                      + (if $existing_entry.affected != $nvd_entry.affected then ["affected targets updated"] else [] end)
+                      + (if $existing_entry.platforms != $nvd_entry.platforms then ["platforms updated"] else [] end)
                      + (if $existing_entry.description != $nvd_entry.description then ["description updated"] else [] end)
                    ),
                    updated_fields: {
@@ -341,6 +462,8 @@ jobs:
                      type: $nvd_entry.type,
                      nvd_category_id: $nvd_entry.nvd_category_id,
                      cvss_score: $nvd_entry.cvss_score,
+                      affected: $nvd_entry.affected,
+                      platforms: $nvd_entry.platforms,
                      description: $nvd_entry.description,
                      title: $nvd_entry.title,
                      references: $nvd_entry.references
@@ -368,7 +491,12 @@ jobs:
        id: transform
        run: |
          # Read existing IDs into a jq-friendly format
-          EXISTING_IDS=$(cat tmp/existing_ids.txt | jq -R -s 'split("\n") | map(select(length > 0))')
+          if [ "${{ inputs.force_full_scan }}" = "true" ]; then
+            echo "Full scan mode enabled: rebuilding CVE advisories from scratch."
+            EXISTING_IDS='[]'
+          else
+            EXISTING_IDS=$(cat tmp/existing_ids.txt | jq -R -s 'split("\n") | map(select(length > 0))')
+          fi
          
          # Transform NVD CVEs to our advisory format
          jq --argjson existing "$EXISTING_IDS" '
@@ -453,8 +581,53 @@ jobs:
                  else (cwe_name_map($id) // ("unknown_cwe_" + $id))
                  end
              );
+
+            def cpe_criteria:
+              (
+                [.cve.configurations[]? | .. | objects | .criteria? | strings | select(startswith("cpe:2.3:"))]
+                | unique
+              );
+
+            def context_blob:
+              (
+                [
+                  (.cve.descriptions[]? | select(.lang == "en") | .value),
+                  (.cve.references[]?.url // empty)
+                ]
+                | map(strings | ascii_downcase)
+                | join(" ")
+              );
+
+            def inferred_targets:
+              (
+                context_blob as $blob
+                | (
+                    (if ($blob | test("github\\.com/openclaw/openclaw|\\bopenclaw\\b|\\bclawdbot\\b|\\bmoltbot\\b")) then ["openclaw@*"] else [] end)
+                    + (if ($blob | test("github\\.com/qwibitai/nanoclaw|\\bnanoclaw\\b|whatsapp-bot|\\bbaileys\\b")) then ["nanoclaw@*"] else [] end)
+                  )
+              );
+
+            def normalized_affected:
+              (
+                (cpe_criteria + inferred_targets)
+                | unique
+                | .[0:5]
+                | if length == 0 then ["openclaw@*", "nanoclaw@*"] else . end
+              );
+
+            def normalized_platforms:
+              (
+                inferred_targets as $targets
+                | ($targets | map(select(startswith("openclaw@"))) | length > 0) as $has_openclaw
+                | ($targets | map(select(startswith("nanoclaw@"))) | length > 0) as $has_nanoclaw
+                | if $has_openclaw and $has_nanoclaw then ["openclaw", "nanoclaw"]
+                  elif $has_openclaw then ["openclaw"]
+                  elif $has_nanoclaw then ["nanoclaw"]
+                  else ["openclaw", "nanoclaw"]
+                  end
+              );
            
-            [.[] | 
+            [.[] |
              select(.cve.id as $id | $existing | index($id) | not) |
              {
                id: .cve.id,
@@ -463,12 +636,15 @@ jobs:
                nvd_category_id: nvd_category_raw,
                title: (.cve.descriptions[] | select(.lang == "en") | .value | .[0:100] + (if length > 100 then "..." else "" end)),
                description: (.cve.descriptions[] | select(.lang == "en") | .value),
-                affected: [.cve.configurations[]?.nodes[]?.cpeMatch[]?.criteria // empty] | unique | .[0:5],
+                affected: normalized_affected,
+                platforms: normalized_platforms,
                action: "Review and update affected components. See NVD for remediation details.",
                published: .cve.published,
                references: [.cve.references[]?.url // empty] | unique | .[0:3],
                cvss_score: get_cvss_score,
-                nvd_url: ("https://nvd.nist.gov/vuln/detail/" + .cve.id)
+                nvd_url: ("https://nvd.nist.gov/vuln/detail/" + .cve.id),
+                exploitability_score: null,
+                exploitability_rationale: null
              }
            ]
          ' tmp/filtered_cves.json > tmp/new_advisories.json
@@ -482,12 +658,63 @@ jobs:
            jq '.[].id' tmp/new_advisories.json
          fi

+      - name: Set up Python for exploitability analysis
+        if: steps.transform.outputs.new_count != '0'
+        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+        with:
+          python-version: '3.10'
+
+      - name: Analyze exploitability for new advisories
+        if: steps.transform.outputs.new_count != '0'
+        run: |
+          set -euo pipefail
+
+          echo "=== Analyzing exploitability for new advisories ==="
+
+          # Extract CVSS vectors from filtered CVEs to merge with advisories
+          jq '
+            [.[] | {
+              id: .cve.id,
+              cvss_vector: (
+                .cve.metrics.cvssMetricV31[0]?.cvssData.vectorString //
+                .cve.metrics.cvssMetricV30[0]?.cvssData.vectorString //
+                .cve.metrics.cvssMetricV2[0]?.vectorString //
+                ""
+              )
+            }] | map({(.id): .cvss_vector}) | add
+          ' tmp/filtered_cves.json > tmp/cvss_vectors.json
+
+          scripts/ci/enrich_exploitability.sh \
+            --mode batch \
+            --input tmp/new_advisories.json \
+            --output tmp/new_advisories.json \
+            --cvss-vectors tmp/cvss_vectors.json
+
+          echo "=== Exploitability analysis complete ==="
+
+          # Show summary of exploitability scores
+          echo "Exploitability score distribution:"
+          jq -r '.[] | "\(.id): \(.exploitability_score // "unknown")"' tmp/new_advisories.json | \
+            awk -F': ' '{scores[$2]++} END {for (s in scores) print "  " s ": " scores[s]}'
+
      - name: Update feed.json
        if: steps.transform.outputs.new_count != '0' || steps.updates.outputs.update_count != '0'
        run: |
          NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          FORCE_FULL_SCAN="${{ inputs.force_full_scan }}"

-          if [ -f "$FEED_PATH" ]; then
+          if [ -f "$FEED_PATH" ] && [ "$FORCE_FULL_SCAN" = "true" ]; then
+            # Full scan mode: replace all CVE advisories with rebuilt set and keep non-CVE entries.
+            jq --argjson rebuilt "$(cat tmp/new_advisories.json)" --arg now "$NOW" '
+              .updated = $now |
+              .advisories = (
+                ((.advisories // []) | map(select((.id // "") | startswith("CVE-") | not)))
+                + $rebuilt
+                | sort_by(.published)
+                | reverse
+              )
+            ' "$FEED_PATH" > tmp/updated_feed.json
+          elif [ -f "$FEED_PATH" ]; then
            # Step 1: Apply updates to existing advisories
            jq --slurpfile updates tmp/updated_advisories.json '
              .advisories = [
@@ -571,6 +798,7 @@ jobs:
            ## Summary
            Automated update from NVD CVE feed.

+            - **Mode:** ${{ inputs.force_full_scan == true && 'full-rebuild (ignore feed state)' || 'delta (incremental)' }}
            - **New advisories:** ${{ steps.transform.outputs.new_count }}
            - **Updated advisories:** ${{ steps.updates.outputs.update_count }}
            - **Poll window:** ${{ steps.dates.outputs.start_date }} → ${{ steps.dates.outputs.end_date }}
@@ -590,12 +818,57 @@ jobs:
            ${{ env.SKILL_FEED_PATH }}
            ${{ env.SKILL_FEED_SIG_PATH }}

+      - name: Run CodeQL on generated PR branch
+        if: steps.create-pr.outputs.pull-request-number != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          BRANCH="${{ steps.create-pr.outputs.pull-request-branch }}"
+          if [ -z "$BRANCH" ]; then
+            echo "::error::Missing pull-request-branch output from create-pull-request"
+            exit 1
+          fi
+
+          echo "Dispatching CodeQL for branch: $BRANCH"
+          gh workflow run codeql.yml --ref "$BRANCH"
+
+          RUN_ID=""
+          for _ in $(seq 1 30); do
+            RUN_ID=$(gh run list \
+              --workflow "CodeQL" \
+              --branch "$BRANCH" \
+              --event workflow_dispatch \
+              --json databaseId,createdAt \
+              --jq 'sort_by(.createdAt) | last | .databaseId // empty')
+            if [ -n "$RUN_ID" ]; then
+              break
+            fi
+            sleep 5
+          done
+
+          if [ -z "$RUN_ID" ]; then
+            echo "::error::Unable to locate dispatched CodeQL run for branch $BRANCH"
+            exit 1
+          fi
+
+          echo "Waiting for CodeQL run id: $RUN_ID"
+          gh run watch "$RUN_ID" --exit-status
+
      - name: Summary
        run: |
+          if [ "${{ inputs.force_full_scan }}" = "true" ]; then
+            MODE="full-rebuild (ignore feed state)"
+          else
+            MODE="delta (incremental)"
+          fi
+
          echo "## NVD CVE Poll Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Metric | Value |" >> $GITHUB_STEP_SUMMARY
          echo "|--------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Mode | $MODE |" >> $GITHUB_STEP_SUMMARY
          echo "| Poll Window | ${{ steps.dates.outputs.start_date }} → ${{ steps.dates.outputs.end_date }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Keywords | $KEYWORDS |" >> $GITHUB_STEP_SUMMARY
          echo "| CVEs Found (filtered) | ${{ steps.process.outputs.filtered_count }} |" >> $GITHUB_STEP_SUMMARY
@@ -11,8 +11,6 @@ on:
  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
  schedule:
    - cron: '19 23 * * 0'
-  push:
-    branches: [ "main" ]

 # Declare default permissions as read only.
 permissions: read-all
@@ -73,6 +71,6 @@ jobs:
      # Upload the results to GitHub's code scanning dashboard (optional).
      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@9e907b5e64f6b83e7804b09294d44122997950d6 # v4.32.3
+        uses: github/codeql-action/upload-sarif@89a39a4e59826350b863aa6b6252a07ad50cf83e # v4.32.4
        with:
          sarif_file: results.sarif
@@ -17,6 +17,9 @@ on:

 permissions: read-all

+env:
+  CLAWHUB_CLI_VERSION: 0.7.0
+
 concurrency:
  group: skill-release-${{ github.ref }}
  cancel-in-progress: false
@@ -849,9 +852,8 @@ jobs:
          VERSION="${{ steps.parse.outputs.version }}"

          if [ ! -f "$SKILL_PATH/CHANGELOG.md" ]; then
-            echo "No CHANGELOG.md found"
-            echo "changelog=" >> $GITHUB_OUTPUT
-            exit 0
+            echo "::error::Missing required changelog file: $SKILL_PATH/CHANGELOG.md"
+            exit 1
          fi

          # Extract the changelog section for this version
@@ -865,18 +867,19 @@ jobs:
          ' "$SKILL_PATH/CHANGELOG.md" | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}')

          if [ -z "$CHANGELOG_ENTRY" ]; then
-            echo "No changelog entry found for version $VERSION"
-            echo "changelog=" >> $GITHUB_OUTPUT
-          else
-            echo "Found changelog entry for version $VERSION"
-            # Use multiline output format for GitHub Actions
-            {
-              echo "changelog<<EOF"
-              echo "$CHANGELOG_ENTRY"
-              echo "EOF"
-            } >> $GITHUB_OUTPUT
+            echo "::error::No changelog entry found for version $VERSION in $SKILL_PATH/CHANGELOG.md"
+            echo "::error::Expected heading format: ## [$VERSION] - YYYY-MM-DD"
+            exit 1
          fi

+          echo "Found changelog entry for version $VERSION"
+          # Use multiline output format for GitHub Actions
+          {
+            echo "changelog<<EOF"
+            echo "$CHANGELOG_ENTRY"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+
      - name: Create GitHub Release
        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
        with:
@@ -1006,7 +1009,51 @@ jobs:

      - name: Install clawhub CLI
        if: needs.release-tag.outputs.publishable == 'true' && env.CLAWHUB_TOKEN != ''
-        run: npm install -g clawhub@0.7.0
+        run: npm install -g clawhub@${CLAWHUB_CLI_VERSION}
+
+      - name: Patch clawhub publish payload workaround
+        # Temporary: clawhub@0.7.0 publish payload is missing acceptLicenseTerms.
+        if: needs.release-tag.outputs.publishable == 'true' && env.CLAWHUB_TOKEN != ''
+        run: |
+          node <<'NODE'
+          const { execSync } = require("node:child_process");
+          const fs = require("node:fs");
+          const path = require("node:path");
+
+          const npmRoot = execSync("npm root -g", { encoding: "utf8" }).trim();
+          const publishScriptPath = path.join(
+            npmRoot,
+            "clawhub",
+            "dist",
+            "cli",
+            "commands",
+            "publish.js"
+          );
+
+          if (!fs.existsSync(publishScriptPath)) {
+            throw new Error(`clawhub publish script not found: ${publishScriptPath}`);
+          }
+
+          const original = fs.readFileSync(publishScriptPath, "utf8");
+          if (original.includes("acceptLicenseTerms: true")) {
+            console.log(`[patch-clawhub] Already patched: ${publishScriptPath}`);
+            process.exit(0);
+          }
+
+          const payloadPattern = /changelog,\r?\n(\s*)tags,/;
+          if (!payloadPattern.test(original)) {
+            throw new Error(
+              `[patch-clawhub] Could not find expected publish payload pattern in ${publishScriptPath}`
+            );
+          }
+
+          const patched = original.replace(
+            payloadPattern,
+            (_, indent) => `changelog,\n${indent}acceptLicenseTerms: true,\n${indent}tags,`
+          );
+          fs.writeFileSync(publishScriptPath, patched, "utf8");
+          console.log(`[patch-clawhub] Patched: ${publishScriptPath}`);
+          NODE

      - name: Login to ClawHub
        if: needs.release-tag.outputs.publishable == 'true' && env.CLAWHUB_TOKEN != ''
@@ -1117,7 +1164,50 @@ jobs:
          node-version: 20

      - name: Install clawhub CLI
-        run: npm install -g clawhub@0.7.0
+        run: npm install -g clawhub@${CLAWHUB_CLI_VERSION}
+
+      - name: Patch clawhub publish payload workaround
+        # Temporary: clawhub@0.7.0 publish payload is missing acceptLicenseTerms.
+        run: |
+          node <<'NODE'
+          const { execSync } = require("node:child_process");
+          const fs = require("node:fs");
+          const path = require("node:path");
+
+          const npmRoot = execSync("npm root -g", { encoding: "utf8" }).trim();
+          const publishScriptPath = path.join(
+            npmRoot,
+            "clawhub",
+            "dist",
+            "cli",
+            "commands",
+            "publish.js"
+          );
+
+          if (!fs.existsSync(publishScriptPath)) {
+            throw new Error(`clawhub publish script not found: ${publishScriptPath}`);
+          }
+
+          const original = fs.readFileSync(publishScriptPath, "utf8");
+          if (original.includes("acceptLicenseTerms: true")) {
+            console.log(`[patch-clawhub] Already patched: ${publishScriptPath}`);
+            process.exit(0);
+          }
+
+          const payloadPattern = /changelog,\r?\n(\s*)tags,/;
+          if (!payloadPattern.test(original)) {
+            throw new Error(
+              `[patch-clawhub] Could not find expected publish payload pattern in ${publishScriptPath}`
+            );
+          }
+
+          const patched = original.replace(
+            payloadPattern,
+            (_, indent) => `changelog,\n${indent}acceptLicenseTerms: true,\n${indent}tags,`
+          );
+          fs.writeFileSync(publishScriptPath, patched, "utf8");
+          console.log(`[patch-clawhub] Patched: ${publishScriptPath}`);
+          NODE

      - name: Login to ClawHub
        run: |
@@ -0,0 +1,73 @@
+name: Sync Wiki
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'wiki/**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: wiki-sync
+  cancel-in-progress: false
+
+jobs:
+  sync-wiki:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Sync wiki folder to repository wiki
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          if [ ! -d wiki ]; then
+            echo "::error::wiki/ directory not found"
+            exit 1
+          fi
+
+          # GitHub Wiki root (/wiki) renders Home.md, not INDEX.md.
+          # INDEX.md is the canonical source; generate Home.md from it.
+          if [ ! -f wiki/INDEX.md ]; then
+            echo "::error::wiki/INDEX.md not found. It is required to generate wiki/Home.md."
+            exit 1
+          fi
+          cp wiki/INDEX.md wiki/Home.md
+
+          WIKI_REMOTE="https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.wiki.git"
+          if ! git ls-remote "$WIKI_REMOTE" >/dev/null 2>&1; then
+            echo "::warning::Wiki remote unavailable (repository wiki may be disabled). Skipping sync."
+            exit 0
+          fi
+
+          WIKI_TMP="$(mktemp -d)"
+          trap 'rm -rf "$WIKI_TMP"' EXIT
+
+          git clone --depth 1 "$WIKI_REMOTE" "$WIKI_TMP"
+          rsync -a --delete --exclude '.git/' wiki/ "$WIKI_TMP/"
+
+          cd "$WIKI_TMP"
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "No wiki changes to sync."
+            exit 0
+          fi
+
+          WIKI_HEAD_REF="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+          if [ -n "$WIKI_HEAD_REF" ]; then
+            WIKI_BRANCH="${WIKI_HEAD_REF#origin/}"
+          else
+            WIKI_BRANCH="master"
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "docs(wiki): sync from ${GITHUB_SHA}"
+          # Clone may sanitize credentials from origin URL; push with explicit auth URL.
+          git push "$WIKI_REMOTE" HEAD:"$WIKI_BRANCH"
@@ -1,4 +1,5 @@
 .claude
+.auto-claude/
 .codex
 _bmad
 _bmad-output
@@ -24,6 +25,7 @@ dist-ssr
 # Derived public assets (copied during build)
 public/advisories
 public/skills
+public/wiki/

 # Python bytecode
 __pycache__/
@@ -39,3 +41,13 @@ __pycache__/
 *.njsproj
 *.sln
 *.sw?
+clawsec-signing-private.pem
+
+# Auto Claude generated files
+.auto-claude/
+.auto-claude-security.json
+.auto-claude-status
+.claude_settings.json
+.worktrees/
+.security-key
+logs/security/
@@ -5,6 +5,8 @@ ClawSec combines a Vite + React frontend with security skill packages and releas
 - Frontend entrypoints: `index.tsx`, `App.tsx`
 - UI and routes: `components/`, `pages/`
 - Shared types/constants: `types.ts`, `constants.ts`
+- Wiki source docs: `wiki/` (synced to GitHub Wiki by `.github/workflows/wiki-sync.yml`)
+- Generated wiki exports: `public/wiki/` (`llms.txt` outputs; generated locally/CI and gitignored)
 - Skills: `skills/<skill-name>/` (`skill.json`, `SKILL.md`, optional `scripts/`, `test/`)
 - Advisory feed: `advisories/feed.json`, `advisories/feed.json.sig`
 - Automation: `scripts/`, `.github/workflows/`
@@ -15,7 +17,9 @@ ClawSec combines a Vite + React frontend with security skill packages and releas
 - `npm run dev`: run local Vite server.
 - `npm run build`: create production build (CI gate).
 - `npm run preview`: preview built app.
+- `npm run gen:wiki-llms`: generate wiki `llms.txt` exports from `wiki/` into `public/wiki/`.
 - `./scripts/prepare-to-push.sh [--fix]`: run lint, types, build, and security checks.
+- `./scripts/populate-local-wiki.sh`: regenerate local wiki `llms.txt` exports for preview.
 - `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0`: lint JS/TS.
 - `npx tsc --noEmit`: type-check TypeScript.
 - `node skills/clawsec-suite/test/feed_verification.test.mjs`: run a skill-local Node test.
@@ -31,6 +35,7 @@ ClawSec combines a Vite + React frontend with security skill packages and releas
 There is no root `npm test`; tests are mostly skill-local.
 - Run changed tests directly: `node skills/<skill>/test/<name>.test.mjs`.
 - For frontend/config changes, run ESLint, `npx tsc --noEmit`, and `npm run build`.
+- For wiki rendering/export changes, run `npm run gen:wiki-llms` and `npm run build`.
 - For Python utility updates, run `ruff check utils/` and `bandit -r utils/ -ll`.

 ## Pull Request Guidelines
@@ -39,6 +44,7 @@ There is no root `npm test`; tests are mostly skill-local.
 - Keep PRs focused and include summary, security benefit, and testing performed.
 - Keep versions aligned between `skills/<skill>/skill.json` and `skills/<skill>/SKILL.md`.
 - Do not push release tags from PR branches; releases are tagged from `main`.
+- Do not commit generated `public/wiki/` artifacts; edit `wiki/` source files instead.

 ## Agent Collaboration & Git Safety
 - Delete unused or obsolete files only when your changes make them irrelevant; revert files only when the change is yours or explicitly requested. If a git operation creates uncertainty about another agent’s in-flight work, stop and coordinate instead of deleting.
@@ -6,6 +6,8 @@ import { FeedSetup } from './pages/FeedSetup';
 import { SkillsCatalog } from './pages/SkillsCatalog';
 import { SkillDetail } from './pages/SkillDetail';
 import { AdvisoryDetail } from './pages/AdvisoryDetail';
+import { WikiBrowser } from './pages/WikiBrowser';
+import { ProductDemo } from './pages/ProductDemo';

 const App: React.FC = () => {
  return (
@@ -17,10 +19,12 @@ const App: React.FC = () => {
          <Route path="/skills/:skillId" element={<SkillDetail />} />
          <Route path="/feed" element={<FeedSetup />} />
          <Route path="/feed/:advisoryId" element={<AdvisoryDetail />} />
+          <Route path="/demo" element={<ProductDemo />} />
+          <Route path="/wiki/*" element={<WikiBrowser />} />
        </Routes>
      </Layout>
    </Router>
  );
 };

-export default App;
+export default App;
@@ -2,8 +2,13 @@

 Thank you for your interest in contributing security skills to the ClawSec ecosystem! This guide will walk you through creating, testing, and submitting new skills.

+## Wiki Documentation Source of Truth
+
+For contributor-facing wiki docs, treat `wiki/` in this repository as the single source of truth. Do not edit the GitHub Wiki directly; `.github/workflows/wiki-sync.yml` publishes `wiki/` to `<repo>.wiki.git` when `wiki/**` changes on `main`.
+
 ## Table of Contents

+- [Wiki Documentation Source of Truth](#wiki-documentation-source-of-truth)
 - [Getting Started](#getting-started)
 - [Skill Structure](#skill-structure)
 - [Creating a New Skill](#creating-a-new-skill)
@@ -649,7 +654,7 @@ Wait for a verified patched version.

 Once your advisory is published:

-1. **Agents receive it** - The feed is served from raw GitHub, so agents see it on their next feed check
+1. **Agents receive it** - The feed is served at `https://clawsec.prompt.security/advisories/feed.json` (with signature/checksum artifacts), so agents see it on their next feed check
 2. **You're credited** - Your issue is linked in the advisory
 3. **Community is protected** - Agents using ClawSec Feed will be alerted

@@ -6,7 +6,7 @@

 <div align="center">

-## Secure Your OpenClaw Bots with a Complete Security Skill Suite
+## Secure Your OpenClaw and NanoClaw Agents with a Complete Security Skill Suite

 <h4>Brought to you by <a href="https://prompt.security">Prompt Security</a>, the Platform for AI Security</h4>

@@ -37,7 +37,7 @@ ClawSec is a **complete security skill suite for AI agent platforms**. It provid

 ### Supported Platforms

- **OpenClaw** (Moltbot, Clawdbot, and clones) - Full suite with skill installer, file integrity protection, and security audits
+- **OpenClaw** (MoltBot, Clawdbot, and clones) - Full suite with skill installer, file integrity protection, and security audits
 - **NanoClaw** - Containerized WhatsApp bot security with MCP tools for advisory monitoring, signature verification, and file integrity

 ### Core Capabilities
@@ -51,26 +51,48 @@ ClawSec is a **complete security skill suite for AI agent platforms**. It provid

 ---

+## 🎬 Product Demos
+
+Animated previews below are GIFs (no audio). Click any preview to open the full MP4 with audio.
+
+### Install Demo (`clawsec-suite`)
+
+[![Install demo animated preview](public/video/install-demo-preview.gif)](public/video/install-demo.mp4)
+
+Direct link: [install-demo.mp4](public/video/install-demo.mp4)
+
+### Drift Detection Demo (`soul-guardian`)
+
+[![Drift detection animated preview](public/video/soul-guardian-demo-preview.gif)](public/video/soul-guardian-demo.mp4)
+
+Direct link: [soul-guardian-demo.mp4](public/video/soul-guardian-demo.mp4)
+
+---
+
 ## 🚀 Quick Start

 ### For AI Agents

 ```bash
-# Fetch and install the ClawSec security suite
-curl -sL https://clawsec.prompt.security/releases/latest/download/SKILL.md
+# Install the ClawSec security suite
+npx clawhub@latest install clawsec-suite
 ```

-The skill file contains deployment instructions. Your agent will:
-1. Detect its agent family (OpenClaw/MoltBot/ClawdBot or other)
-2. Install appropriate skills from the catalog
-3. Verify integrity using checksums
-4. Set up cron update checks
+After install, the suite can:
+1. Discover installable protections from the published skills catalog
+2. Verify release integrity using signed checksums
+3. Set up advisory monitoring and hook-based protection flows
+4. Add optional scheduled checks
+
+Manual/source-first option:
+
+> Read https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md and follow the installation instructions.

 ### For Humans

 Copy this instruction to your AI agent:

-> Read https://clawsec.prompt.security/releases/latest/download/SKILL.md and follow the instructions to install the protection skill suite.
+> Install ClawSec with `npx clawhub@latest install clawsec-suite`, then complete the setup steps from the generated instructions.

 ### Shell and OS Notes

@@ -137,18 +159,26 @@ See [`skills/clawsec-nanoclaw/INSTALL.md`](skills/clawsec-nanoclaw/INSTALL.md) f

 The **clawsec-suite** is a skill-of-skills manager that installs, verifies, and maintains security skills from the ClawSec catalog.

-### Skills in the Suite
+### Skills in the ClawSec Catalog
+
+All currently published skills in this repository:

 | Skill | Description | Installation | Compatibility |
 |-------|-------------|--------------|---------------|
-| 📡 **clawsec-feed** | Security advisory feed monitoring with live CVE updates | ✅ Included by default | All agents |
-| 🔭 **openclaw-audit-watchdog** | Automated daily audits with email reporting | ⚙️ Optional (install separately) | OpenClaw/MoltBot/ClawdBot |
-| 👻 **soul-guardian** | Drift detection and file integrity guard with auto-restore | ⚙️ Optional | All agents |
+| 📦 **clawsec-suite** | Suite manager with advisory monitoring, signature verification, and guarded skill install flows | `npx clawhub@latest install clawsec-suite` | OpenClaw/MoltBot/Clawdbot |
+| 📡 **clawsec-feed** | Security advisory feed monitoring with live CVE updates | ✅ Included by default via `clawsec-suite` | All agents |
+| 🧪 **clawsec-clawhub-checker** | ClawHub reputation checker with VirusTotal Code Insight integration | ⚙️ Optional (install separately) | OpenClaw/MoltBot/Clawdbot |
+| 🔍 **clawsec-scanner** | Automated vulnerability scanner (dependency scan, CVE enrichment, SAST, basic DAST) | ⚙️ Optional (install separately) | Agent platforms (OpenClaw first-class support) |
+| 📱 **clawsec-nanoclaw** | NanoClaw security suite with MCP tools, advisory checks, and signature verification | ⚙️ Optional (install separately) | NanoClaw |
+| 👻 **soul-guardian** | Drift detection and file integrity guard with auto-restore | ⚙️ Optional (install separately) | All agents |
+| 🔭 **openclaw-audit-watchdog** | Automated daily audits with email reporting | ⚙️ Optional (install separately) | OpenClaw/MoltBot/Clawdbot |
 | 🤝 **clawtributor** | Community incident reporting | ❌ Optional (Explicit request) | All agents |
+| 🧠 **prompt-agent** | Security audit enforcement and prompt hardening workflows | ⚙️ Optional (install separately) | Agent platforms |
+| 🚀 **claw-release** | Release automation for Claw skills and website | ⚙️ Optional (install separately) | Maintainer workflow tooling |

 > ⚠️ **clawtributor** is not installed by default as it may share anonymized incident data. Install only on explicit user request.

-> ⚠️ **openclaw-audit-watchdog** is tailored for the OpenClaw/MoltBot/ClawdBot agent family. Other agents receive the universal skill set.
+> ⚠️ **openclaw-audit-watchdog** is tailored for the OpenClaw/MoltBot/Clawdbot agent family. Other agents receive the universal skill set.

 ### Suite Features

@@ -170,6 +200,9 @@ ClawSec maintains a continuously updated security advisory feed, automatically p
 curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'
 ```

+Canonical endpoint: `https://clawsec.prompt.security/advisories/feed.json`  
+Compatibility mirror (legacy): `https://clawsec.prompt.security/releases/latest/download/feed.json`
+
 ### Monitored Keywords

 The feed polls CVEs related to:
@@ -178,6 +211,17 @@ The feed polls CVEs related to:
 - Prompt injection patterns
 - Agent security vulnerabilities

+### Exploitability Context
+
+ClawSec enriches CVE advisories with **exploitability context** to help agents assess real-world risk beyond raw CVSS scores. Newly analyzed advisories can include:
+
+- **Exploit Evidence**: Whether public exploits exist in the wild
+- **Weaponization Status**: If exploits are integrated into common attack frameworks
+- **Attack Requirements**: Prerequisites needed for successful exploitation (network access, authentication, user interaction)
+- **Risk Assessment**: Contextualized risk level combining technical severity with exploitability
+
+This feature helps agents prioritize vulnerabilities that pose immediate threats versus theoretical risks, enabling smarter security decisions.
+
 ### Advisory Schema

 **NVD CVE Advisory:**
@@ -192,6 +236,8 @@ The feed polls CVEs related to:
  "published": "2026-02-01T00:00:00Z",
  "cvss_score": 8.8,
  "nvd_url": "https://nvd.nist.gov/vuln/detail/CVE-2026-XXXXX",
+  "exploitability_score": "high|medium|low|unknown",
+  "exploitability_rationale": "Why this CVE is or is not likely exploitable in agent deployments",
  "references": ["..."],
  "action": "Recommended remediation"
 }
@@ -215,7 +261,7 @@ The feed polls CVEs related to:
 ```

 **Platform values:**
- `"openclaw"` - OpenClaw/ClawdBot/MoltBot only
+- `"openclaw"` - OpenClaw/Clawdbot/MoltBot only
 - `"nanoclaw"` - NanoClaw only
 - `["openclaw", "nanoclaw"]` - Both platforms
 - (empty/missing) - All platforms (backward compatible)
@@ -230,10 +276,13 @@ ClawSec uses automated pipelines for continuous security updates and skill distr

 | Workflow | Trigger | Description |
 |----------|---------|-------------|
+| **ci.yml** | PRs to `main`, pushes to `main` | Lint/type/build + skill test suites |
+| **pages-verify.yml** | PRs to `main` | Verifies Pages build and signing outputs without publishing |
 | **poll-nvd-cves.yml** | Daily cron (06:00 UTC) | Polls NVD for new CVEs, updates feed |
 | **community-advisory.yml** | Issue labeled `advisory-approved` | Processes community reports into advisories |
-| **skill-release.yml** | `<skill>-v*.*.*` tags | Packages individual skills with checksums to GitHub Releases |
-| **deploy-pages.yml** | Push to main | Builds and deploys the web interface to GitHub Pages |
+| **skill-release.yml** | Skill tags + metadata PR changes | Validates version parity in PRs and publishes signed skill releases on tags |
+| **deploy-pages.yml** | `workflow_run` after successful trusted CI/release or manual dispatch | Builds and deploys the web interface to GitHub Pages |
+| **wiki-sync.yml** | Pushes to `main` touching `wiki/**` | Syncs `wiki/` to the GitHub Wiki mirror |

 ### Skill Release Pipeline

@@ -244,7 +293,7 @@ When a skill is tagged (e.g., `soul-guardian-v1.0.0`), the pipeline:
 3. **Generates Checksums** - Creates `checksums.json` with SHA256 hashes for all SBOM files
 4. **Signs + verifies** - Signs `checksums.json` and validates the generated `signing-public.pem` fingerprint against canonical repo key material
 5. **Releases** - Publishes to GitHub Releases with all artifacts
-6. **Supersedes Old Releases** - Marks older versions (same major) as pre-releases
+6. **Supersedes Old Releases** - Deletes older versions within the same major line (tags remain)
 7. **Triggers Pages Update** - Refreshes the skills catalog on the website

 ### Signing Key Consistency Guardrails
@@ -295,8 +344,8 @@ Each skill release includes:
 ### Signing Operations Documentation

 For feed/release signing rollout and operations guidance:
- [`docs/SECURITY-SIGNING.md`](docs/SECURITY-SIGNING.md) - key generation, GitHub secrets, rotation/revocation, incident response
- [`docs/MIGRATION-SIGNED-FEED.md`](docs/MIGRATION-SIGNED-FEED.md) - phased migration from unsigned feed, enforcement gates, rollback plan
+- [`wiki/security-signing-runbook.md`](wiki/security-signing-runbook.md) - key generation, GitHub secrets, rotation/revocation, incident response
+- [`wiki/migration-signed-feed.md`](wiki/migration-signed-feed.md) - phased migration from unsigned feed, enforcement gates, rollback plan

 ---

@@ -357,8 +406,18 @@ npm run dev

 # Populate advisory feed with real NVD CVE data
 ./scripts/populate-local-feed.sh --days 120
+
+# Generate wiki llms exports from wiki/ (for local preview)
+./scripts/populate-local-wiki.sh
+
+# Direct generator entrypoint (used by predev/prebuild)
+npm run gen:wiki-llms
 ```

+Notes:
+- `npm run dev` and `npm run build` automatically regenerate wiki `llms.txt` exports (`predev`/`prebuild` hooks).
+- `public/wiki/` is generated output (local + CI) and is intentionally gitignored.
+
 ### Build

 ```bash
@@ -374,24 +433,36 @@ npm run build
 │   └── feed.json              # Main advisory feed (auto-updated from NVD)
 ├── components/                 # React components
 ├── pages/                      # Page components
+├── wiki/                       # Source-of-truth docs (synced to GitHub Wiki)
 ├── scripts/
+│   ├── generate-wiki-llms.mjs # wiki/*.md -> public/wiki/**/llms.txt
 │   ├── populate-local-feed.sh # Local CVE feed populator
 │   ├── populate-local-skills.sh # Local skills catalog populator
+│   ├── populate-local-wiki.sh # Local wiki llms export populator
 │   └── release-skill.sh       # Manual skill release helper
 ├── skills/
-│   ├── clawsec-suite/       # 📦 Suite installer (skill-of-skills)
-│   ├── clawsec-feed/        # 📡 Advisory feed skill
-│   ├── clawtributor/           # 🤝 Community reporting skill
+│   ├── clawsec-suite/          # 📦 Suite installer (skill-of-skills)
+│   ├── clawsec-feed/           # 📡 Advisory feed skill
+│   ├── clawsec-clawhub-checker/ # 🧪 ClawHub reputation checks
+│   ├── clawsec-scanner/        # 🔍 Automated vulnerability scanner
+│   ├── clawsec-nanoclaw/       # 📱 NanoClaw platform security suite
+│   ├── soul-guardian/          # 👻 File integrity skill
 │   ├── openclaw-audit-watchdog/ # 🔭 Automated audit skill
-│   └── soul-guardian/         # 👻 File integrity skill
+│   ├── clawtributor/           # 🤝 Community reporting skill
+│   ├── prompt-agent/           # 🧠 Prompt-focused protection workflows
+│   └── claw-release/           # 🚀 Release automation skill
 ├── utils/
 │   ├── package_skill.py       # Skill packager utility
 │   └── validate_skill.py      # Skill validator utility
 ├── .github/workflows/
+│   ├── ci.yml                 # Cross-platform lint/type/build + tests
+│   ├── pages-verify.yml       # PR-only pages build verification
 │   ├── poll-nvd-cves.yml      # CVE polling pipeline
+│   ├── community-advisory.yml # Approved issue -> advisory PR
 │   ├── skill-release.yml      # Skill release pipeline
+│   ├── wiki-sync.yml          # Sync repo wiki/ to GitHub Wiki
 │   └── deploy-pages.yml       # Pages deployment
-└── public/                     # Static assets and published skills
+└── public/                     # Static assets + generated publish artifacts
 ```

 ---
@@ -419,6 +490,14 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#submitting-security-advisories) for detail
 4. Validate with `python utils/validate_skill.py skills/your-skill`
 5. Submit a PR for review

+## 📚 Documentation Source of Truth
+
+For all wiki content, edit files under `wiki/` in this repository. The GitHub Wiki (`<repo>.wiki.git`) is synced from `wiki/` by `.github/workflows/wiki-sync.yml` when `wiki/**` changes on `main`.
+
+LLM exports are generated from `wiki/` into `public/wiki/`:
+- `/wiki/llms.txt` is the LLM-ready export for `wiki/INDEX.md` (or a generated fallback index if `INDEX.md` is missing).
+- `/wiki/<page>/llms.txt` is the LLM-ready export for that single wiki page.
+
 ---

 ## 📄 License
@@ -1 +1 @@
-Rs++ntJvBvX4zVTJ/DsrfXOQG3VTUc2x4esSURSMonesmYzSm9U9kd3rBz5d+DemJOVJ/esH21VACpdE+T34AA==
+qNd1mJmbXNyIP+5CjBppoCIDu0PNRWYNFWpmzgtIFPJ6P62epcDaQKgi+dTDRUbk8jANIb+Ukf8vk+iz3CrIDg==
@@ -4,7 +4,7 @@ export const Footer: React.FC = () => {
  return (
    <footer className="text-center py-6 mt-auto">
      <p className="text-gray-300 text-sm italic">
-        ClawSec is a project by Prompt Security, a SentinelOne company. It's not affiliated with OpenClaw. Designed for security research and agentic workflow hardening.
+        ClawSec is a project by Prompt Security, a SentinelOne company. It's not affiliated with OpenClaw or NanoClaw. Designed for security research and agentic workflow hardening.
      </p>
      <div className="flex justify-center gap-4 mt-4">
        <span className="text-2xl animate-pulse">🦞</span>
@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { NavLink } from 'react-router-dom';
-import { Menu, X, Terminal, Layers, Rss, Home, Github } from 'lucide-react';
+import { Menu, X, Terminal, Layers, Rss, Home, Github, BookOpenText, PlayCircle } from 'lucide-react';

 export const Header: React.FC = () => {
  const [isOpen, setIsOpen] = useState(false);
@@ -9,6 +9,8 @@ export const Header: React.FC = () => {
    { label: 'Home', path: '/', icon: Home },
    { label: 'Skills', path: '/skills', icon: Layers },
    { label: 'Security Feed', path: '/feed', icon: Rss },
+    { label: 'Product Demo', path: '/demo', icon: PlayCircle },
+    { label: 'Wiki', path: '/wiki', icon: BookOpenText },
  ];

  const baseLink =
@@ -1,7 +1,9 @@

-// Feed URL for fetching live advisories
-export const ADVISORY_FEED_URL = 'https://clawsec.prompt.security/releases/latest/download/feed.json';
+// Canonical hosted feed endpoint for fetching live advisories
+export const ADVISORY_FEED_URL = 'https://clawsec.prompt.security/advisories/feed.json';
+
+// Compatibility mirror for legacy clients; keep as last-resort fallback only
+export const LEGACY_ADVISORY_FEED_URL = 'https://clawsec.prompt.security/releases/latest/download/feed.json';

 // Local feed path for development
 export const LOCAL_FEED_PATH = '/advisories/feed.json';
-
@@ -85,7 +85,8 @@ export default [
      }
    },
    rules: {
-      'no-empty': ['error', { allowEmptyCatch: true }]
+      'no-empty': ['error', { allowEmptyCatch: true }],
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]
    }
  },
  // Node.js scripts (.js files in scripts directory)
@@ -113,6 +114,6 @@ export default [
    }
  },
  {
-    ignores: ['dist/', 'node_modules/', '*.config.js', 'public/']
+    ignores: ['dist/', 'node_modules/', '*.config.js', 'public/', '.venv/']
  }
 ];
@@ -1,4 +1,4 @@
 {
  "name": "ClawSec",
-  "description": "A security-first skill distribution platform for OpenClaw agents (and some clones), featuring verified audit skills, hardening feeds, and guardian mode protocols."
-}
+  "description": "A security-first skill distribution platform for OpenClaw and NanoClaw agents, featuring verified audit skills, hardening feeds, and guardian mode protocols."
+}
@@ -5,16 +5,20 @@
  "version": "0.0.0",
  "type": "module",
  "scripts": {
+    "gen:wiki-llms": "node scripts/generate-wiki-llms.mjs",
+    "populate-local-wiki": "./scripts/populate-local-wiki.sh",
+    "predev": "npm run gen:wiki-llms",
    "dev": "vite",
+    "prebuild": "npm run gen:wiki-llms",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
-    "lucide-react": "^0.564.0",
+    "lucide-react": "^0.575.0",
    "react": "^19.2.4",
    "react-dom": "^19.2.4",
    "react-markdown": "^10.1.0",
-    "react-router-dom": "^7.13.0",
+    "react-router-dom": "^7.13.1",
    "remark-gfm": "^4.0.1"
  },
  "devDependencies": {
@@ -26,6 +30,7 @@
    "eslint": "^9.39.2",
    "eslint-plugin-react": "^7.37.5",
    "eslint-plugin-react-hooks": "^7.0.1",
+    "fast-check": "^4.5.3",
    "typescript": "~5.8.2",
    "vite": "^7.3.1"
  },
@@ -33,6 +38,6 @@
    "ajv": "6.14.0",
    "balanced-match": "4.0.3",
    "brace-expansion": "5.0.2",
-    "minimatch": "10.2.1"
+    "minimatch": "10.2.4"
  }
 }
@@ -3,7 +3,11 @@ import { useParams, Link } from 'react-router-dom';
 import { ArrowLeft, ExternalLink, Shield, AlertTriangle, Github, User, Bot } from 'lucide-react';
 import { Footer } from '../components/Footer';
 import { Advisory, AdvisoryFeed } from '../types';
-import { ADVISORY_FEED_URL, LOCAL_FEED_PATH } from '../constants';
+import {
+  ADVISORY_FEED_URL,
+  LEGACY_ADVISORY_FEED_URL,
+  LOCAL_FEED_PATH,
+} from '../constants';

 export const AdvisoryDetail: React.FC = () => {
  const { advisoryId } = useParams<{ advisoryId: string }>();
@@ -16,13 +20,17 @@ export const AdvisoryDetail: React.FC = () => {
      if (!advisoryId) return;

      try {
-        // Try local feed first (for development), then fall back to GitHub releases
+        // Try local feed first (dev), then canonical hosted endpoint, then legacy mirror.
        let response = await fetch(LOCAL_FEED_PATH);

        if (!response.ok) {
          response = await fetch(ADVISORY_FEED_URL);
        }

+        if (!response.ok) {
+          response = await fetch(LEGACY_ADVISORY_FEED_URL);
+        }
+
        if (!response.ok) {
          throw new Error(`Failed to fetch feed: ${response.status}`);
        }
@@ -1,19 +1,59 @@
-import React, { useState, useEffect } from 'react';
+import React, { useState, useEffect, useMemo } from 'react';
 import { Rss, RefreshCw, Loader2, AlertTriangle, ChevronLeft, ChevronRight, Download, Users, AlertCircle } from 'lucide-react';
 import { Link } from 'react-router-dom';
 import { Footer } from '../components/Footer';
 import { AdvisoryCard } from '../components/AdvisoryCard';
 import { Advisory, AdvisoryFeed } from '../types';
-import { ADVISORY_FEED_URL, LOCAL_FEED_PATH } from '../constants';
+import {
+  ADVISORY_FEED_URL,
+  LEGACY_ADVISORY_FEED_URL,
+  LOCAL_FEED_PATH,
+} from '../constants';

 const ITEMS_PER_PAGE = 9;

+const SEVERITY_TABS = [
+  { value: 'all',      label: 'All',      active: 'bg-clawd-accent text-white',                                    inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-clawd-accent/50' },
+  { value: 'critical', label: 'Critical', active: 'bg-red-500/20 text-red-400 border-2 border-red-400',            inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-red-400/50' },
+  { value: 'high',     label: 'High',     active: 'bg-orange-500/20 text-orange-400 border-2 border-orange-400',   inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-orange-400/50' },
+  { value: 'medium',   label: 'Medium',   active: 'bg-yellow-500/20 text-yellow-400 border-2 border-yellow-400',   inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-yellow-400/50' },
+  { value: 'low',      label: 'Low',      active: 'bg-blue-500/20 text-blue-400 border-2 border-blue-400',         inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-blue-400/50' },
+] as const;
+
+const PLATFORM_TABS = [
+  { value: 'all',      label: 'All Platforms', active: 'bg-clawd-accent text-white',                                         inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-clawd-accent/50' },
+  { value: 'openclaw', label: 'OpenClaw',      active: 'bg-clawd-accent/20 text-clawd-accent border-2 border-clawd-accent',  inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-clawd-accent/50' },
+  { value: 'nanoclaw', label: 'NanoClaw',      active: 'bg-clawd-secondary/20 text-clawd-secondary border-2 border-clawd-secondary', inactive: 'bg-clawd-800 text-gray-400 border border-clawd-700 hover:border-clawd-secondary/50' },
+] as const;
+
+const FilterTabs: React.FC<{
+  tabs: ReadonlyArray<{ value: string; label: string; active: string; inactive: string }>;
+  selected: string;
+  onSelect: (value: string) => void;
+}> = ({ tabs, selected, onSelect }) => (
+  <div className="flex flex-wrap justify-center gap-3 mb-8">
+    {tabs.map(({ value, label, active, inactive }) => (
+      <button
+        key={value}
+        onClick={() => onSelect(value)}
+        className={`px-4 py-2 rounded-lg text-sm font-semibold transition-all ${
+          selected === value ? active : inactive
+        }`}
+      >
+        {label}
+      </button>
+    ))}
+  </div>
+);
+
 export const FeedSetup: React.FC = () => {
  const [advisories, setAdvisories] = useState<Advisory[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [lastUpdated, setLastUpdated] = useState<string | null>(null);
  const [currentPage, setCurrentPage] = useState(1);
+  const [selectedSeverity, setSelectedSeverity] = useState<string>('all');
+  const [selectedPlatform, setSelectedPlatform] = useState<string>('all');

  useEffect(() => {
    const fetchAdvisories = async () => {
@@ -21,13 +61,17 @@ export const FeedSetup: React.FC = () => {
      setError(null);

      try {
-        // Try local feed first (for development), then fall back to GitHub releases
+        // Try local feed first (dev), then canonical hosted endpoint, then legacy mirror.
        let response = await fetch(LOCAL_FEED_PATH);
-        
+
        if (!response.ok) {
          response = await fetch(ADVISORY_FEED_URL);
        }

+        if (!response.ok) {
+          response = await fetch(LEGACY_ADVISORY_FEED_URL);
+        }
+
        if (!response.ok) {
          throw new Error(`Failed to fetch feed: ${response.status}`);
        }
@@ -47,6 +91,18 @@ export const FeedSetup: React.FC = () => {
    fetchAdvisories();
  }, []);

+  const filteredAdvisories = useMemo(
+    () => advisories.filter((a) =>
+      (selectedSeverity === 'all' || a.severity === selectedSeverity) &&
+      (selectedPlatform === 'all' || !a.platforms?.length || a.platforms.includes(selectedPlatform))
+    ),
+    [advisories, selectedSeverity, selectedPlatform],
+  );
+
+  useEffect(() => {
+    setCurrentPage(1);
+  }, [advisories, selectedSeverity, selectedPlatform]);
+
  const formatDate = (dateStr: string) => {
    try {
      return new Date(dateStr).toLocaleDateString('en-US', {
@@ -60,10 +116,10 @@ export const FeedSetup: React.FC = () => {
  };

  // Pagination calculations
-  const totalPages = Math.ceil(advisories.length / ITEMS_PER_PAGE);
+  const totalPages = Math.ceil(filteredAdvisories.length / ITEMS_PER_PAGE);
  const startIndex = (currentPage - 1) * ITEMS_PER_PAGE;
  const endIndex = startIndex + ITEMS_PER_PAGE;
-  const currentAdvisories = advisories.slice(startIndex, endIndex);
+  const currentAdvisories = filteredAdvisories.slice(startIndex, endIndex);

  const goToPage = (page: number) => {
    setCurrentPage(Math.max(1, Math.min(page, totalPages)));
@@ -76,7 +132,7 @@ export const FeedSetup: React.FC = () => {
        <h1 className="text-3xl md:text-4xl text-white">Security Hardening Feed</h1>
        <p className="text-gray-400 max-w-2xl mx-auto">
          A continuous stream of security advisories from NVD CVE data and staff-approved community reports. 
-          This feed is automatically updated with OpenClaw-related vulnerabilities and verified security incidents.
+          This feed is automatically updated with OpenClaw and NanoClaw-related vulnerabilities and verified security incidents.
        </p>
        {lastUpdated && (
          <p className="text-xs text-gray-500">
@@ -86,6 +142,9 @@ export const FeedSetup: React.FC = () => {
      </section>

      <section>
+        <FilterTabs tabs={SEVERITY_TABS} selected={selectedSeverity} onSelect={setSelectedSeverity} />
+        <FilterTabs tabs={PLATFORM_TABS} selected={selectedPlatform} onSelect={setSelectedPlatform} />
+
        {loading ? (
          <div className="flex items-center justify-center py-12">
            <Loader2 className="w-8 h-8 text-clawd-accent animate-spin" />
@@ -96,9 +155,13 @@ export const FeedSetup: React.FC = () => {
            <AlertTriangle className="w-6 h-6 text-orange-400 mr-2" />
            <span className="text-gray-400">{error}</span>
          </div>
-        ) : advisories.length === 0 ? (
+        ) : filteredAdvisories.length === 0 ? (
          <div className="text-center py-12">
-            <p className="text-gray-400">No security advisories at this time. Check back later.</p>
+            <p className="text-gray-400">
+              {advisories.length === 0
+                ? 'No security advisories at this time. Check back later.'
+                : 'No advisories found for the selected filters.'}
+            </p>
          </div>
        ) : (
          <>
@@ -133,9 +196,10 @@ export const FeedSetup: React.FC = () => {
              </div>
            )}

-            {advisories.length > 0 && (
+            {filteredAdvisories.length > 0 && (
              <p className="text-center text-sm text-gray-500 mt-4">
-                Showing {startIndex + 1}-{Math.min(endIndex, advisories.length)} of {advisories.length} advisories
+                Showing {startIndex + 1}-{Math.min(endIndex, filteredAdvisories.length)} of {filteredAdvisories.length} advisories
+                {(selectedSeverity !== 'all' || selectedPlatform !== 'all') && ` (${advisories.length} total)`}
              </p>
            )}
          </>
@@ -1,14 +1,17 @@
 import React, { useState, useEffect } from 'react';
-import { User, Bot, Copy, Check } from 'lucide-react';
+import { User, Bot, Copy, Check, Lock } from 'lucide-react';
 import { Footer } from '../components/Footer';

 const FILE_NAMES = ['SOUL.md', 'AGENTS.md', 'USER.md', 'TOOLS.md', 'IDENTITY.md', 'HEARTBEAT.md', 'MEMORY.md'];
+const PLATFORM_NAMES = ['OpenClaw', 'NanoClaw'];
+const FILE_LOCK_REVEAL_DELAY_MS = 1600;

 export const Home: React.FC = () => {
  const [isAgent, setIsAgent] = useState(true);
  const [copiedCurl, setCopiedCurl] = useState(false);
  const [copiedHuman, setCopiedHuman] = useState(false);
  const [currentFileIndex, setCurrentFileIndex] = useState(0);
+  const [currentPlatformIndex, setCurrentPlatformIndex] = useState(0);

  const curlCommand = `npx clawhub@latest install clawsec-suite`;

@@ -20,6 +23,27 @@ export const Home: React.FC = () => {
    return () => clearInterval(interval);
  }, []);

+  // Rotate platform names every 4-6 seconds
+  useEffect(() => {
+    let timeoutId: number | undefined;
+
+    const scheduleNextRotation = () => {
+      const delay = 4000 + Math.floor(Math.random() * 2001);
+      timeoutId = window.setTimeout(() => {
+        setCurrentPlatformIndex((prev) => (prev + 1) % PLATFORM_NAMES.length);
+        scheduleNextRotation();
+      }, delay);
+    };
+
+    scheduleNextRotation();
+
+    return () => {
+      if (timeoutId !== undefined) {
+        window.clearTimeout(timeoutId);
+      }
+    };
+  }, []);
+
  const humanInstruction = `Please install clawsec-suite from clawhubnpx clawhub@latest install clawsec-suite`;

  const handleCopyCurl = () => {
@@ -44,24 +68,20 @@ export const Home: React.FC = () => {
      {/* Hero Section */}
      <section className="text-center space-y-6 max-w-3xl mx-auto mb-12 md:mb-16">
        <h2 className="text-3xl md:text-4xl tracking-tight text-white">
-          Secure your <span className="text-clawd-accent">OpenClaw</span> agents
-        </h2>
-        <p className="text-lg md:text-xl text-gray-400 leading-relaxed">
-          A complete security skill suite for OpenClaw's family of agents. Protect your{' '}
+          Secure your{' '}
          <code
-            key={currentFileIndex}
-            className="px-2 py-1 rounded text-clawd-accent inline-block align-baseline relative text-base"
+            key={currentPlatformIndex}
+            className="px-2 py-1 rounded text-clawd-accent inline-block align-baseline relative"
            style={{
-              width: '165px',
+              minWidth: '9ch',
              textAlign: 'center',
-              verticalAlign: 'baseline',
              backgroundColor: 'rgb(30 27 75 / 1)',
              animation: 'bgFade 0.4s ease-out 1.2s 1 forwards'
            }}
          >
-            {FILE_NAMES[currentFileIndex].split('').map((char, index) => (
+            {PLATFORM_NAMES[currentPlatformIndex].split('').map((char, index) => (
              <span
-                key={`${currentFileIndex}-${index}`}
+                key={`platform-${currentPlatformIndex}-${index}`}
                className="inline-block"
                style={{
                  animation: `flipChar 0.3s ease-in-out ${index * 0.05}s 1 forwards`,
@@ -73,6 +93,47 @@ export const Home: React.FC = () => {
                {char}
              </span>
            ))}
+          </code>{' '}
+          agents
+        </h2>
+        <p className="text-lg md:text-xl text-gray-400 leading-relaxed">
+          A complete security skill suite for OpenClaw and NanoClaw agents. Protect your{' '}
+          <code
+            key={currentFileIndex}
+            className="px-2 py-1 rounded text-clawd-accent inline-block align-baseline relative text-base"
+            style={{
+              width: '188px',
+              textAlign: 'center',
+              verticalAlign: 'baseline',
+              backgroundColor: 'rgb(30 27 75 / 1)',
+              animation: 'bgFade 0.4s ease-out 1.2s 1 forwards'
+            }}
+          >
+            <span className="inline-block w-full pr-5">
+              {FILE_NAMES[currentFileIndex].split('').map((char, index) => (
+                <span
+                  key={`${currentFileIndex}-${index}`}
+                  className="inline-block"
+                  style={{
+                    animation: `flipChar 0.3s ease-in-out ${index * 0.05}s 1 forwards`,
+                    transformStyle: 'preserve-3d',
+                    perspective: '400px',
+                    opacity: 0
+                  }}
+                >
+                  {char}
+                </span>
+              ))}
+            </span>
+            <Lock
+              size={14}
+              className="text-clawd-accent absolute right-2 top-1/2 -translate-y-1/2"
+              style={{
+                opacity: 0,
+                animation: `lockReveal ${FILE_LOCK_REVEAL_DELAY_MS}ms steps(1, end) 1 forwards`
+              }}
+              aria-hidden="true"
+            />
          </code>
          {' '}with drift detection, live security recommendations, automated audits, and skill integrity verification. All from one installable suite.
        </p>
@@ -102,6 +163,14 @@ export const Home: React.FC = () => {
              background-color: rgb(191 107 42 / 0.15);
            }
          }
+          @keyframes lockReveal {
+            0% {
+              opacity: 0;
+            }
+            100% {
+              opacity: 0.85;
+            }
+          }
          @keyframes mascotHover {
            0%, 100% { transform: translateY(0); }
            50% { transform: translateY(-12px); }
@@ -0,0 +1,92 @@
+import React from 'react';
+import { ExternalLink, PlayCircle } from 'lucide-react';
+import { Footer } from '../components/Footer';
+
+interface DemoVideo {
+  id: string;
+  title: string;
+  description: string;
+  videoSrc: string;
+  posterSrc: string;
+  videoContainerClassName?: string;
+}
+
+const demoVideos: DemoVideo[] = [
+  {
+    id: 'drift-demo',
+    title: 'Drift Detection Demo (soul-guardian)',
+    description:
+      'Shows integrity monitoring in action: tamper detection, alerting, and restoration-oriented behavior for protected files.',
+    videoSrc: '/video/soul-guardian-demo.mp4',
+    posterSrc: '/video/soul-guardian-demo-poster.jpg',
+  },
+  {
+    id: 'install-demo',
+    title: 'Install Demo (clawsec-suite)',
+    description:
+      'Walkthrough of the one-command suite install flow and what gets configured for advisory monitoring and protection.',
+    videoSrc: '/video/install-demo.mp4',
+    posterSrc: '/video/install-demo-poster.jpg',
+    videoContainerClassName: 'md:max-w-[50%]',
+  },
+];
+
+export const ProductDemo: React.FC = () => {
+  return (
+    <div className="max-w-5xl mx-auto pt-[52px] space-y-10">
+      <section className="text-center space-y-4">
+        <h1 className="text-3xl md:text-4xl text-white flex items-center justify-center gap-3">
+          <PlayCircle className="text-clawd-accent" />
+          Watch It in Action
+        </h1>
+        <p className="text-gray-400 max-w-3xl mx-auto">
+          Product demos for ClawSec installation and runtime protection behavior. These are the
+          same demo assets referenced in the repository README, presented as playable videos.
+        </p>
+      </section>
+
+      <section className="space-y-8">
+        {demoVideos.map((demo) => (
+          <article
+            key={demo.id}
+            className="bg-clawd-900 border border-clawd-700 rounded-xl overflow-hidden"
+          >
+            <div className="px-6 pt-6 pb-4 space-y-3">
+              <h2 className="text-xl text-white">{demo.title}</h2>
+              <p className="text-gray-400">{demo.description}</p>
+            </div>
+            <div className="px-6 pb-6 space-y-4">
+              <div
+                className={`rounded-lg overflow-hidden border border-clawd-700 bg-black ${
+                  demo.videoContainerClassName ?? ''
+                }`}
+              >
+                <video
+                  className="w-full h-auto"
+                  controls
+                  playsInline
+                  preload="metadata"
+                  poster={demo.posterSrc}
+                >
+                  <source src={demo.videoSrc} type="video/mp4" />
+                  Your browser does not support the video tag.
+                </video>
+              </div>
+              <a
+                href={demo.videoSrc}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="inline-flex items-center gap-2 text-sm text-clawd-accent hover:underline"
+              >
+                <ExternalLink size={15} />
+                Open video in new tab
+              </a>
+            </div>
+          </article>
+        ))}
+      </section>
+
+      <Footer />
+    </div>
+  );
+};
@@ -5,11 +5,12 @@ import Markdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { Footer } from '../components/Footer';
 import type { SkillJson, SkillChecksums } from '../types';
+import { defaultMarkdownComponents } from '../utils/markdownComponents';
+import { stripFrontmatter } from '../utils/markdownHelpers.mjs';

-// Strip YAML frontmatter from markdown content
-const stripFrontmatter = (content: string): string => {
-  const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
-  return content.replace(frontmatterRegex, '');
+const isProbablyHtmlDocument = (text: string): boolean => {
+  const start = text.trimStart().slice(0, 200).toLowerCase();
+  return start.startsWith('<!doctype html') || start.startsWith('<html');
 };

 export const SkillDetail: React.FC = () => {
@@ -29,19 +30,44 @@ export const SkillDetail: React.FC = () => {
        setDoc(null);

        // Fetch skill.json
-        const skillResponse = await fetch(`./skills/${skillId}/skill.json`);
+        const skillResponse = await fetch(`/skills/${skillId}/skill.json`, {
+          headers: { Accept: 'application/json' }
+        });
        if (!skillResponse.ok) {
          throw new Error('Skill not found');
        }
-        const skill = await skillResponse.json();
+
+        const skillContentType = skillResponse.headers.get('content-type') ?? '';
+        const skillRaw = await skillResponse.text();
+        if (skillContentType.includes('text/html') || isProbablyHtmlDocument(skillRaw)) {
+          throw new Error('Skill not found');
+        }
+
+        let skill: SkillJson;
+        try {
+          skill = JSON.parse(skillRaw) as SkillJson;
+        } catch {
+          throw new Error('Invalid skill metadata');
+        }
+
        setSkillData(skill);

        // Fetch checksums.json
        try {
-          const checksumsResponse = await fetch(`./skills/${skillId}/checksums.json`);
+          const checksumsResponse = await fetch(`/skills/${skillId}/checksums.json`, {
+            headers: { Accept: 'application/json' }
+          });
          if (checksumsResponse.ok) {
-            const checksumsData = await checksumsResponse.json();
-            setChecksums(checksumsData);
+            const checksumsContentType = checksumsResponse.headers.get('content-type') ?? '';
+            const checksumsRaw = await checksumsResponse.text();
+            if (!checksumsContentType.includes('text/html') && !isProbablyHtmlDocument(checksumsRaw)) {
+              try {
+                const checksumsData = JSON.parse(checksumsRaw) as SkillChecksums;
+                setChecksums(checksumsData);
+              } catch {
+                // Checksums malformed, ignore.
+              }
+            }
          }
        } catch {
          // Checksums not available
@@ -51,18 +77,8 @@ export const SkillDetail: React.FC = () => {
        // Note: Dev servers may fall back to serving index.html with 200 for missing files;
        // guard against accidentally rendering HTML as docs.
        try {
-          const isProbablyHtmlDocument = (text: string) => {
-            const start = text.trimStart().slice(0, 200).toLowerCase();
-            return start.startsWith('<!doctype html') || start.startsWith('<html');
-          };
-
-          const stripYamlFrontmatter = (text: string) => {
-            const match = text.match(/^---\\s*\\n[\\s\\S]*?\\n---\\s*\\n/);
-            return match ? text.slice(match[0].length) : text;
-          };
-
          const fetchDocFile = async (filename: string) => {
-            const response = await fetch(`./skills/${skillId}/${filename}`, {
+            const response = await fetch(`/skills/${skillId}/${filename}`, {
              headers: { Accept: 'text/plain' }
            });
            if (!response.ok) return null;
@@ -73,7 +89,7 @@ export const SkillDetail: React.FC = () => {
            if (contentType.includes('text/html') || isProbablyHtmlDocument(rawText)) return null;

            const text =
-              filename === 'SKILL.md' ? stripYamlFrontmatter(rawText).trim() : rawText.trim();
+              filename === 'SKILL.md' ? stripFrontmatter(rawText).trim() : rawText.trim();

            return text.length > 0 ? text : null;
          };
@@ -300,102 +316,7 @@ export const SkillDetail: React.FC = () => {
          <div className="skill-docs bg-clawd-800/50 border border-clawd-700 rounded-xl p-4 sm:p-6 md:p-8 overflow-x-hidden">
            <Markdown
              remarkPlugins={[remarkGfm]}
-              components={{
-                h1: ({ children }) => (
-                  <h1 className="text-2xl font-bold text-white border-b border-clawd-700 pb-3 mb-6 mt-0">
-                    {children}
-                  </h1>
-                ),
-                h2: ({ children }) => (
-                  <h2 className="text-xl font-bold text-white mt-8 mb-4">{children}</h2>
-                ),
-                h3: ({ children }) => (
-                  <h3 className="text-lg font-semibold text-white mt-6 mb-3">{children}</h3>
-                ),
-                h4: ({ children }) => (
-                  <h4 className="text-base font-semibold text-white mt-4 mb-2">{children}</h4>
-                ),
-                p: ({ children }) => (
-                  <p className="text-gray-300 leading-relaxed mb-4">{children}</p>
-                ),
-                a: ({ href, children }) => (
-                  <a
-                    href={href}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="text-clawd-accent hover:underline"
-                  >
-                    {children}
-                  </a>
-                ),
-                ul: ({ children }) => (
-                  <ul className="list-disc list-inside text-gray-300 space-y-2 mb-4 ml-4">
-                    {children}
-                  </ul>
-                ),
-                ol: ({ children }) => (
-                  <ol className="list-decimal list-inside text-gray-300 space-y-2 mb-4 ml-4">
-                    {children}
-                  </ol>
-                ),
-                li: ({ children }) => (
-                  <li className="text-gray-300">{children}</li>
-                ),
-                blockquote: ({ children }) => (
-                  <blockquote className="border-l-4 border-clawd-accent pl-4 py-2 my-4 bg-clawd-900/50 rounded-r text-gray-400 italic">
-                    {children}
-                  </blockquote>
-                ),
-                code: ({ className, children }) => {
-                  const isInline = !className;
-                  if (isInline) {
-                    return (
-                      <code className="text-orange-300 bg-clawd-900 px-1.5 py-0.5 rounded text-sm font-mono">
-                        {children}
-                      </code>
-                    );
-                  }
-                  return (
-                    <code className="text-gray-200 text-sm font-mono">{children}</code>
-                  );
-                },
-                pre: ({ children }) => (
-                  <pre className="bg-clawd-900 border border-clawd-700 rounded-lg p-3 sm:p-4 overflow-x-auto mb-4 text-xs sm:text-sm max-w-full">
-                    {children}
-                  </pre>
-                ),
-                table: ({ children }) => (
-                  <div className="overflow-x-auto mb-6 -mx-4 sm:mx-0 px-4 sm:px-0">
-                    <table className="w-full border-collapse text-xs sm:text-sm min-w-[300px]">
-                      {children}
-                    </table>
-                  </div>
-                ),
-                thead: ({ children }) => (
-                  <thead className="bg-clawd-900 border-b border-clawd-600">
-                    {children}
-                  </thead>
-                ),
-                tbody: ({ children }) => <tbody>{children}</tbody>,
-                tr: ({ children }) => (
-                  <tr className="border-b border-clawd-700/50">{children}</tr>
-                ),
-                th: ({ children }) => (
-                  <th className="text-left px-4 py-3 text-gray-300 font-semibold">
-                    {children}
-                  </th>
-                ),
-                td: ({ children }) => (
-                  <td className="px-4 py-3 text-gray-300">{children}</td>
-                ),
-                hr: () => <hr className="border-clawd-700 my-6" />,
-                strong: ({ children }) => (
-                  <strong className="text-white font-semibold">{children}</strong>
-                ),
-                em: ({ children }) => (
-                  <em className="text-gray-200">{children}</em>
-                ),
-              }}
+              components={defaultMarkdownComponents}
            >
              {stripFrontmatter(doc.content)}
            </Markdown>
@@ -4,6 +4,27 @@ import { SkillCard } from '../components/SkillCard';
 import { Footer } from '../components/Footer';
 import type { SkillMetadata, SkillsIndex } from '../types';

+const SKILLS_INDEX_PATH = '/skills/index.json';
+
+const isProbablyHtmlDocument = (text: string): boolean => {
+  const start = text.trimStart().slice(0, 200).toLowerCase();
+  return start.startsWith('<!doctype html') || start.startsWith('<html');
+};
+
+const parseSkillsIndex = (raw: string): SkillsIndex | null => {
+  try {
+    const parsed = JSON.parse(raw) as Partial<SkillsIndex> | null;
+    if (!parsed || !Array.isArray(parsed.skills)) return null;
+    return {
+      version: typeof parsed.version === 'string' ? parsed.version : '1.0.0',
+      updated: typeof parsed.updated === 'string' ? parsed.updated : '',
+      skills: parsed.skills as SkillMetadata[],
+    };
+  } catch {
+    return null;
+  }
+};
+
 export const SkillsCatalog: React.FC = () => {
  const [skills, setSkills] = useState<SkillMetadata[]>([]);
  const [filteredSkills, setFilteredSkills] = useState<SkillMetadata[]>([]);
@@ -15,15 +36,41 @@ export const SkillsCatalog: React.FC = () => {
  useEffect(() => {
    const fetchSkills = async () => {
      try {
-        const response = await fetch('./skills/index.json');
+        const response = await fetch(SKILLS_INDEX_PATH, {
+          headers: { Accept: 'application/json' },
+        });
+
+        // Missing index file is a valid "empty catalog" state.
+        if (response.status === 404) {
+          setSkills([]);
+          setFilteredSkills([]);
+          return;
+        }
+
        if (!response.ok) {
          throw new Error('Failed to fetch skills index');
        }
-        const data: SkillsIndex = await response.json();
-        setSkills(data.skills || []);
-        setFilteredSkills(data.skills || []);
+
+        const contentType = response.headers.get('content-type') ?? '';
+        const raw = await response.text();
+
+        // Some SPA setups return index.html with 200 for missing JSON files.
+        if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(raw)) {
+          setSkills([]);
+          setFilteredSkills([]);
+          return;
+        }
+
+        const data = parseSkillsIndex(raw);
+        if (!data) {
+          throw new Error('Invalid skills index format');
+        }
+
+        setSkills(data.skills);
+        setFilteredSkills(data.skills);
      } catch (err) {
-        setError(err instanceof Error ? err.message : 'Failed to load skills');
+        console.error('Failed to load skills index:', err);
+        setError('Failed to load skills catalog');
      } finally {
        setLoading(false);
      }
@@ -0,0 +1,375 @@
+import React, { useMemo } from 'react';
+import { BookOpenText, ExternalLink, FileText } from 'lucide-react';
+import { Link, useParams } from 'react-router-dom';
+import Markdown from 'react-markdown';
+import type { Components } from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { Footer } from '../components/Footer';
+import { defaultMarkdownComponents } from '../utils/markdownComponents';
+import {
+  extractTitleFromMarkdown,
+  fallbackTitleFromPath,
+  stripFrontmatter,
+} from '../utils/markdownHelpers.mjs';
+import {
+  isWikiIndexSlug,
+  toWikiLlmsPath,
+  toWikiRoute,
+} from '../utils/wikiPathHelpers.mjs';
+
+interface WikiDoc {
+  filePath: string;
+  slug: string;
+  title: string;
+  content: string;
+}
+
+const normalizePath = (path: string): string => {
+  const clean = path.replace(/\\/g, '/');
+  const parts: string[] = [];
+  for (const part of clean.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      if (parts.length > 0) parts.pop();
+      continue;
+    }
+    parts.push(part);
+  }
+  return parts.join('/');
+};
+
+const dirname = (path: string): string => {
+  const idx = path.lastIndexOf('/');
+  return idx === -1 ? '' : path.slice(0, idx);
+};
+
+const resolveFromFile = (currentFilePath: string, targetPath: string): string => {
+  if (!targetPath) return currentFilePath;
+  if (targetPath.startsWith('/')) return normalizePath(targetPath.slice(1));
+  const baseDir = dirname(currentFilePath);
+  const joined = baseDir ? `${baseDir}/${targetPath}` : targetPath;
+  return normalizePath(joined);
+};
+
+const splitHash = (href: string): { path: string; hash: string } => {
+  const idx = href.indexOf('#');
+  if (idx === -1) return { path: href, hash: '' };
+  return { path: href.slice(0, idx), hash: href.slice(idx) };
+};
+
+const toWikiRelativePath = (globPath: string): string =>
+  globPath.replace(/^\.\.\/wiki\//, '').replace(/\\/g, '/');
+
+const isExternalHref = (href: string): boolean =>
+  /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(href) || href.startsWith('//');
+
+const ALLOWED_LINK_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:']);
+const ALLOWED_IMAGE_SCHEMES = new Set(['http:', 'https:']);
+
+const sanitizeHref = (href: string): string | null => {
+  const trimmed = href.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith('//')) return null;
+
+  const schemeMatch = trimmed.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:)/);
+  if (!schemeMatch) return trimmed;
+
+  return ALLOWED_LINK_SCHEMES.has(schemeMatch[1].toLowerCase()) ? trimmed : null;
+};
+
+const sanitizeImageSrc = (src: string): string | null => {
+  const trimmed = src.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith('//')) return null;
+
+  const schemeMatch = trimmed.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:)/);
+  if (!schemeMatch) return trimmed;
+
+  return ALLOWED_IMAGE_SCHEMES.has(schemeMatch[1].toLowerCase()) ? trimmed : null;
+};
+
+const markdownModules = import.meta.glob('../wiki/**/*.md', {
+  eager: true,
+  query: '?raw',
+  import: 'default',
+}) as Record<string, string>;
+
+const assetModules = import.meta.glob('../wiki/**/*.{png,jpg,jpeg,gif,svg,webp,avif}', {
+  eager: true,
+  import: 'default',
+}) as Record<string, string>;
+
+const wikiDocs: WikiDoc[] = Object.entries(markdownModules)
+  .map(([globPath, content]) => {
+    const filePath = toWikiRelativePath(globPath);
+    return {
+      filePath,
+      slug: filePath.replace(/\.md$/i, ''),
+      title: extractTitleFromMarkdown(content, filePath),
+      content: stripFrontmatter(content).trim(),
+    };
+  })
+  .sort((a, b) => {
+    const aIndex = a.slug.toLowerCase() === 'index';
+    const bIndex = b.slug.toLowerCase() === 'index';
+    if (aIndex && !bIndex) return -1;
+    if (!aIndex && bIndex) return 1;
+
+    const aModule = a.filePath.startsWith('modules/');
+    const bModule = b.filePath.startsWith('modules/');
+    if (aModule !== bModule) return aModule ? 1 : -1;
+
+    return a.title.localeCompare(b.title, 'en', { sensitivity: 'base' });
+  });
+
+const wikiDocBySlug = new Map<string, WikiDoc>(
+  wikiDocs.map((doc) => [doc.slug.toLowerCase(), doc]),
+);
+
+const wikiDocByFilePath = new Map<string, WikiDoc>(
+  wikiDocs.map((doc) => [doc.filePath.toLowerCase(), doc]),
+);
+
+const wikiAssetByPath = new Map<string, string>(
+  Object.entries(assetModules).map(([globPath, assetUrl]) => [
+    toWikiRelativePath(globPath).toLowerCase(),
+    assetUrl,
+  ]),
+);
+
+const defaultDoc = wikiDocBySlug.get('index') ?? wikiDocs[0] ?? null;
+
+const toGroupName = (filePath: string): string => {
+  if (!filePath.includes('/')) return 'Core';
+  if (filePath.startsWith('modules/')) return 'Modules';
+  const [firstSegment] = filePath.split('/');
+  return fallbackTitleFromPath(firstSegment);
+};
+
+export const WikiBrowser: React.FC = () => {
+  const params = useParams<{ '*': string }>();
+  const wildcard = params['*'] ?? '';
+  const normalizedWildcard = wildcard.replace(/^\/+|\/+$/g, '');
+  let requested = '';
+  let decodeFailed = false;
+  try {
+    requested = decodeURIComponent(normalizedWildcard);
+  } catch (error) {
+    decodeFailed = normalizedWildcard.length > 0;
+    console.warn('Failed to decode wiki route segment', { wildcard, error });
+    requested = '';
+  }
+  const requestedSlug = requested || 'INDEX';
+
+  const selectedDoc = wikiDocBySlug.get(requestedSlug.toLowerCase()) ?? defaultDoc;
+  const notFound =
+    (decodeFailed && normalizedWildcard.length > 0) ||
+    (requested.length > 0 && !wikiDocBySlug.has(requestedSlug.toLowerCase()));
+
+  const groupedDocs = useMemo(() => {
+    const map = new Map<string, WikiDoc[]>();
+    for (const doc of wikiDocs) {
+      const group = toGroupName(doc.filePath);
+      const existing = map.get(group) ?? [];
+      existing.push(doc);
+      map.set(group, existing);
+    }
+
+    const preferredOrder = ['Core', 'Modules'];
+    return Array.from(map.entries())
+      .sort(([a], [b]) => {
+        const idxA = preferredOrder.indexOf(a);
+        const idxB = preferredOrder.indexOf(b);
+        if (idxA !== -1 || idxB !== -1) {
+          if (idxA === -1) return 1;
+          if (idxB === -1) return -1;
+          return idxA - idxB;
+        }
+        return a.localeCompare(b, 'en', { sensitivity: 'base' });
+      })
+      .map(([name, docs]) => ({
+        name,
+        docs: docs.sort((a, b) =>
+          a.title.localeCompare(b.title, 'en', { sensitivity: 'base' }),
+        ),
+      }));
+  }, []);
+
+  if (!selectedDoc) {
+    return (
+      <div className="pt-[52px] py-20 text-center space-y-4">
+        <BookOpenText className="w-12 h-12 text-gray-500 mx-auto" />
+        <h1 className="text-2xl text-white">Wiki unavailable</h1>
+        <p className="text-gray-400">No markdown files were found in the wiki source.</p>
+      </div>
+    );
+  }
+
+  const activeSlug = selectedDoc.slug.toLowerCase();
+  const pageLlmsPath = toWikiLlmsPath(activeSlug);
+  const showWikiLlmsIndexLink = !isWikiIndexSlug(activeSlug);
+
+  const resolveWikiRouteFromHref = (href: string): string | null => {
+    if (!href || isExternalHref(href) || href.startsWith('mailto:') || href.startsWith('tel:')) {
+      return null;
+    }
+    const { path, hash } = splitHash(href);
+    if (!path || !path.toLowerCase().endsWith('.md')) return null;
+
+    const resolvedFilePath = resolveFromFile(selectedDoc.filePath, path).toLowerCase();
+    const targetDoc = wikiDocByFilePath.get(resolvedFilePath);
+    if (!targetDoc) return null;
+    return `${toWikiRoute(targetDoc.slug)}${hash}`;
+  };
+
+  const resolveAssetUrl = (srcOrHref: string): string | null => {
+    if (!srcOrHref || isExternalHref(srcOrHref) || srcOrHref.startsWith('/')) return null;
+    const { path } = splitHash(srcOrHref);
+    if (!path) return null;
+    const resolvedAssetPath = resolveFromFile(selectedDoc.filePath, path).toLowerCase();
+    return wikiAssetByPath.get(resolvedAssetPath) ?? null;
+  };
+
+  const wikiMarkdownComponents: Components = {
+    ...defaultMarkdownComponents,
+    a: ({ href, children }) => {
+      if (!href) return <span className="text-gray-300">{children}</span>;
+
+      const wikiRoute = resolveWikiRouteFromHref(href);
+      if (wikiRoute) {
+        return (
+          <Link to={wikiRoute} className="text-clawd-accent hover:underline">
+            {children}
+          </Link>
+        );
+      }
+
+      const assetHref = resolveAssetUrl(href);
+      const finalHref = assetHref ?? href;
+      const safeHref = sanitizeHref(finalHref);
+      if (!safeHref) {
+        return <span className="text-gray-300">{children}</span>;
+      }
+      const external = isExternalHref(safeHref);
+
+      return (
+        <a
+          href={safeHref}
+          target={external ? '_blank' : undefined}
+          rel={external ? 'noopener noreferrer' : undefined}
+          className="text-clawd-accent hover:underline"
+        >
+          {children}
+        </a>
+      );
+    },
+    img: ({ src, alt }) => {
+      const resolvedSrc = src ? resolveAssetUrl(src) : null;
+      const finalSrc = resolvedSrc ?? (src ? sanitizeImageSrc(src) : null);
+      if (!finalSrc) {
+        return <span className="text-gray-500 text-sm">[image blocked]</span>;
+      }
+      return (
+        <img
+          src={finalSrc}
+          alt={alt ?? ''}
+          className="max-w-full h-auto rounded-lg border border-clawd-700 bg-clawd-900/40 p-2 my-4"
+          loading="lazy"
+        />
+      );
+    },
+  };
+
+  return (
+    <div className="pt-[52px] space-y-8">
+      <section className="space-y-3">
+        <h1 className="text-3xl md:text-4xl text-white flex items-center gap-3">
+          <BookOpenText className="text-clawd-accent" />
+          Wiki
+        </h1>
+        <p className="text-gray-400 max-w-3xl">
+          Full repository wiki rendered from markdown in <code className="text-gray-300">wiki/</code>.
+          This is the same source synced to GitHub Wiki.
+        </p>
+        <div className="flex flex-wrap gap-3">
+          <a
+            href={pageLlmsPath}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-2 px-3 py-1.5 rounded-md bg-clawd-700 hover:bg-clawd-600 text-white text-sm transition-colors"
+          >
+            <FileText size={15} />
+            Page llms.txt
+          </a>
+          {showWikiLlmsIndexLink && (
+            <a
+              href="/wiki/llms.txt"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-2 px-3 py-1.5 rounded-md bg-clawd-800 border border-clawd-700 hover:border-clawd-accent text-white text-sm transition-colors"
+            >
+              <FileText size={15} />
+              Wiki llms.txt Index
+            </a>
+          )}
+          <a
+            href="https://github.com/prompt-security/clawsec/wiki"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-2 px-3 py-1.5 rounded-md border border-clawd-700 hover:border-clawd-accent text-gray-200 text-sm transition-colors"
+          >
+            <ExternalLink size={15} />
+            GitHub Wiki
+          </a>
+        </div>
+      </section>
+
+      <div className="grid lg:grid-cols-[280px_minmax(0,1fr)] gap-6 items-start">
+        <aside className="bg-clawd-800/50 border border-clawd-700 rounded-xl p-4 lg:sticky lg:top-20 max-h-[calc(100vh-7rem)] overflow-auto">
+          <div className="space-y-5">
+            {groupedDocs.map((group) => (
+              <section key={group.name} className="space-y-2">
+                <h2 className="text-xs uppercase tracking-wide text-gray-400">{group.name}</h2>
+                <div className="space-y-1">
+                  {group.docs.map((doc) => {
+                    const isActive = activeSlug === doc.slug.toLowerCase();
+                    return (
+                      <Link
+                        key={doc.filePath}
+                        to={toWikiRoute(doc.slug)}
+                        className={`block px-3 py-2 rounded-md text-sm transition-colors ${
+                          isActive
+                            ? 'bg-white/10 text-white border border-white/10'
+                            : 'text-gray-300 hover:text-white hover:bg-white/5'
+                        }`}
+                      >
+                        {doc.title}
+                      </Link>
+                    );
+                  })}
+                </div>
+              </section>
+            ))}
+          </div>
+        </aside>
+
+        <section className="bg-clawd-800/50 border border-clawd-700 rounded-xl p-4 sm:p-6 md:p-8 overflow-x-hidden">
+          {notFound && (
+            <div className="mb-6 p-3 rounded-md border border-orange-800 bg-orange-900/20 text-orange-200 text-sm">
+              Wiki page not found for <code>{requested}</code>. Showing <strong>{selectedDoc.title}</strong> instead.
+            </div>
+          )}
+
+          <Markdown
+            remarkPlugins={[remarkGfm]}
+            components={wikiMarkdownComponents}
+          >
+            {selectedDoc.content}
+          </Markdown>
+        </section>
+      </div>
+
+      <Footer />
+    </div>
+  );
+};
@@ -0,0 +1,281 @@
+#!/bin/bash
+# backfill-exploitability.sh
+# Adds exploitability scoring to existing advisories in feed.json that don't have it yet.
+# Historical maintenance utility: normal advisory generation should use
+# poll-nvd workflow (init/reset when rebuilding) or populate-local-feed.sh.
+#
+# Usage: ./scripts/backfill-exploitability.sh [--dry-run] [--feed PATH]
+#   --dry-run   Show what would be updated without making changes
+#   --feed PATH Use specified feed file (default: advisories/feed.json)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=./feed-utils.sh
+source "$SCRIPT_DIR/feed-utils.sh"
+
+# Configuration
+init_feed_paths "$PROJECT_ROOT"
+ANALYZER="$PROJECT_ROOT/utils/analyze_exploitability.py"
+SIGNING_PRIVATE_KEY="${CLAWSEC_FEED_SIGNING_PRIVATE_KEY_PATH:-${CLAWSEC_SIGNING_PRIVATE_KEY_PATH:-$PROJECT_ROOT/clawsec-signing-private.pem}}"
+SIGNING_PUBLIC_KEY="${CLAWSEC_FEED_SIGNING_PUBLIC_KEY_PATH:-${CLAWSEC_SIGNING_PUBLIC_KEY_PATH:-$PROJECT_ROOT/clawsec-signing-public.pem}}"
+SIGNING_PASSPHRASE="${CLAWSEC_FEED_SIGNING_PRIVATE_KEY_PASSPHRASE:-${CLAWSEC_SIGNING_PRIVATE_KEY_PASSPHRASE:-}}"
+
+sign_and_verify_feed_signature() {
+  local feed_file="$1"
+  local signature_file="$2"
+  local tmp_dir
+  local tmp_signature
+  local signature_bin
+  local passin_file
+
+  tmp_dir=$(mktemp -d)
+  tmp_signature="${signature_file}.tmp.$$"
+  signature_bin="$tmp_dir/signature.bin"
+  passin_file="$tmp_dir/passin.txt"
+
+  if [ -n "$SIGNING_PASSPHRASE" ]; then
+    printf '%s' "$SIGNING_PASSPHRASE" > "$passin_file"
+    chmod 600 "$passin_file"
+
+    if ! openssl pkeyutl -sign -rawin -inkey "$SIGNING_PRIVATE_KEY" -passin "file:$passin_file" -in "$feed_file" \
+      | openssl base64 -A > "$tmp_signature"; then
+      rm -rf "$tmp_dir"
+      rm -f "$tmp_signature"
+      echo "Error: Failed to sign $feed_file" >&2
+      return 1
+    fi
+  elif ! openssl pkeyutl -sign -rawin -inkey "$SIGNING_PRIVATE_KEY" -in "$feed_file" \
+    | openssl base64 -A > "$tmp_signature"; then
+    rm -rf "$tmp_dir"
+    rm -f "$tmp_signature"
+    echo "Error: Failed to sign $feed_file" >&2
+    return 1
+  fi
+
+  if ! openssl base64 -d -A -in "$tmp_signature" -out "$signature_bin"; then
+    rm -rf "$tmp_dir"
+    rm -f "$tmp_signature"
+    echo "Error: Failed to decode generated signature for $feed_file" >&2
+    return 1
+  fi
+
+  if ! openssl pkeyutl -verify -rawin -pubin -inkey "$SIGNING_PUBLIC_KEY" -sigfile "$signature_bin" -in "$feed_file" >/dev/null; then
+    rm -rf "$tmp_dir"
+    rm -f "$tmp_signature"
+    echo "Error: Signature verification failed after signing $feed_file" >&2
+    return 1
+  fi
+
+  mv "$tmp_signature" "$signature_file"
+  rm -rf "$tmp_dir"
+  echo "✓ Re-signed and verified: $signature_file"
+}
+
+# Parse args
+DRY_RUN=false
+REQUIRE_SIGNING=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --feed)
+      FEED_PATH="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: $0 [--dry-run] [--feed PATH]"
+      exit 1
+      ;;
+  esac
+done
+
+echo "=== ClawSec Exploitability Backfill ==="
+echo "Feed path: $FEED_PATH"
+echo "Dry run: $DRY_RUN"
+echo ""
+
+# Verify prerequisites
+if [ ! -f "$FEED_PATH" ]; then
+  echo "Error: Feed file not found: $FEED_PATH"
+  exit 1
+fi
+
+if [ ! -f "$ANALYZER" ]; then
+  echo "Error: Analyzer script not found: $ANALYZER"
+  exit 1
+fi
+
+# Check Python availability
+if ! command -v python3 &> /dev/null; then
+  echo "Error: python3 is required but not found in PATH"
+  exit 1
+fi
+
+# Verify analyzer works
+if ! python3 "$ANALYZER" --help &> /dev/null; then
+  echo "Error: Analyzer script failed to run. Check Python environment."
+  exit 1
+fi
+
+# Determine whether detached signatures must be regenerated.
+# Runtime agents that only have public keys should run in dry-run mode.
+if [ "$DRY_RUN" = "false" ]; then
+  if [ -f "${FEED_PATH}.sig" ]; then
+    REQUIRE_SIGNING=true
+  fi
+fi
+
+if [ "$REQUIRE_SIGNING" = "true" ]; then
+  if ! command -v openssl &> /dev/null; then
+    echo "Error: openssl is required for detached signature signing/verification"
+    exit 1
+  fi
+
+  if [ ! -f "$SIGNING_PRIVATE_KEY" ]; then
+    echo "Error: Signing private key not found: $SIGNING_PRIVATE_KEY"
+    echo "This backfill updates signed feed artifacts. Use --dry-run in public-key-only environments."
+    exit 1
+  fi
+
+  if [ ! -f "$SIGNING_PUBLIC_KEY" ]; then
+    echo "Error: Signing public key not found: $SIGNING_PUBLIC_KEY"
+    exit 1
+  fi
+fi
+
+# Create temp directory
+TEMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+echo "=== Analyzing Feed ==="
+
+# Extract advisories without exploitability_score
+jq '.advisories | map(select(.exploitability_score == null or .exploitability_score == ""))' \
+  "$FEED_PATH" > "$TEMP_DIR/missing_exploitability.json"
+
+MISSING_COUNT=$(jq 'length' "$TEMP_DIR/missing_exploitability.json")
+TOTAL_COUNT=$(jq '.advisories | length' "$FEED_PATH")
+ALREADY_DONE=$((TOTAL_COUNT - MISSING_COUNT))
+
+echo "Total advisories: $TOTAL_COUNT"
+echo "Already have exploitability: $ALREADY_DONE"
+echo "Missing exploitability: $MISSING_COUNT"
+echo ""
+
+if [ "$MISSING_COUNT" -eq 0 ]; then
+  echo "✓ All advisories already have exploitability scores!"
+  exit 0
+fi
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo "=== Dry Run - Would Update These Advisories ==="
+  jq -r '.[] | .id' "$TEMP_DIR/missing_exploitability.json"
+  echo ""
+  echo "Total advisories to update: $MISSING_COUNT"
+  exit 0
+fi
+
+echo "=== Processing Advisories ==="
+
+# Process each advisory
+PROCESSED=0
+FAILED=0
+
+# Read original feed to preserve all metadata
+cp "$FEED_PATH" "$TEMP_DIR/feed_working.json"
+
+while IFS= read -r advisory; do
+  CVE_ID=$(echo "$advisory" | jq -r '.id')
+
+  echo -n "Processing $CVE_ID... "
+
+  # Prepare input for analyzer
+  ANALYZER_INPUT=$(echo "$advisory" | jq '{
+    cve_id: .id,
+    cvss_score: (.cvss_score // 0.0),
+    type: .type,
+    description: .description,
+    references: (.references // [])
+  }')
+
+  # Run analyzer
+  if ANALYSIS=$(echo "$ANALYZER_INPUT" | python3 "$ANALYZER" --json --check-exploits 2>/dev/null); then
+    # Extract exploitability fields
+    EXPL_SCORE=$(echo "$ANALYSIS" | jq -r '.exploitability_score // "unknown"')
+    EXPL_RATIONALE=$(echo "$ANALYSIS" | jq -r '.exploitability_rationale // "No rationale available"')
+
+    # Update advisory in working feed
+    jq --arg id "$CVE_ID" \
+       --arg score "$EXPL_SCORE" \
+       --arg rationale "$EXPL_RATIONALE" \
+       '(.advisories[] | select(.id == $id)) |= (. + {
+         exploitability_score: $score,
+         exploitability_rationale: $rationale
+       })' "$TEMP_DIR/feed_working.json" > "$TEMP_DIR/feed_updated.json"
+
+    mv "$TEMP_DIR/feed_updated.json" "$TEMP_DIR/feed_working.json"
+
+    echo "✓ $EXPL_SCORE"
+    PROCESSED=$((PROCESSED + 1))
+  else
+    echo "✗ Failed"
+    FAILED=$((FAILED + 1))
+  fi
+done < <(jq -c '.[]' "$TEMP_DIR/missing_exploitability.json")
+
+# Check if loop executed successfully
+if [ ! -f "$TEMP_DIR/feed_working.json" ]; then
+  echo "Error: Feed processing failed"
+  exit 1
+fi
+
+echo ""
+echo "=== Processing Complete ==="
+echo "Processed: $PROCESSED"
+echo "Failed: $FAILED"
+echo ""
+
+# Write updated feed
+echo "Writing updated feed to: $FEED_PATH"
+cp "$TEMP_DIR/feed_working.json" "$FEED_PATH"
+
+# Update feed version and timestamp
+CURRENT_VERSION=$(jq -r '.version' "$FEED_PATH")
+UPDATED_TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+jq --arg ts "$UPDATED_TS" '.updated = $ts' "$FEED_PATH" > "$TEMP_DIR/feed_final.json"
+mv "$TEMP_DIR/feed_final.json" "$FEED_PATH"
+
+echo "✓ Updated feed version: $CURRENT_VERSION"
+echo "✓ Updated timestamp: $UPDATED_TS"
+echo ""
+
+if [ "$REQUIRE_SIGNING" = "true" ]; then
+  echo ""
+  echo "=== Re-signing Advisory Feed ==="
+
+  if [ -f "${FEED_PATH}.sig" ]; then
+    if ! sign_and_verify_feed_signature "$FEED_PATH" "${FEED_PATH}.sig"; then
+      exit 1
+    fi
+  fi
+fi
+
+echo ""
+echo "=== Summary ==="
+echo "✓ Backfill complete!"
+echo "✓ $PROCESSED advisories updated with exploitability scores"
+
+if [ "$FAILED" -gt 0 ]; then
+  echo "⚠ $FAILED advisories failed analysis (kept original data)"
+fi
+
+# Verify final state
+FINAL_MISSING=$(jq '.advisories | map(select(.exploitability_score == null or .exploitability_score == "")) | length' "$FEED_PATH")
+echo "✓ Advisories still missing exploitability: $FINAL_MISSING"
@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/ci/enrich_exploitability.sh --mode single|batch --input <path> --output <path> [--cvss-vectors <path>] [--analyzer <path>]
+
+Options:
+  --mode           Processing mode: single advisory object or batch advisory array
+  --input          Input JSON path
+  --output         Output JSON path
+  --cvss-vectors   Optional JSON object mapping advisory id -> CVSS vector
+  --analyzer       Optional analyzer path (default: utils/analyze_exploitability.py)
+  --help           Show this help
+EOF
+}
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+MODE=""
+INPUT_PATH=""
+OUTPUT_PATH=""
+CVSS_VECTORS_PATH=""
+ANALYZER_PATH="utils/analyze_exploitability.py"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      MODE="${2:-}"
+      shift 2
+      ;;
+    --input)
+      INPUT_PATH="${2:-}"
+      shift 2
+      ;;
+    --output)
+      OUTPUT_PATH="${2:-}"
+      shift 2
+      ;;
+    --cvss-vectors)
+      CVSS_VECTORS_PATH="${2:-}"
+      shift 2
+      ;;
+    --analyzer)
+      ANALYZER_PATH="${2:-}"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "ERROR: Unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ "$MODE" != "single" && "$MODE" != "batch" ]]; then
+  echo "ERROR: --mode must be one of: single, batch" >&2
+  exit 1
+fi
+
+if [[ -z "$INPUT_PATH" || -z "$OUTPUT_PATH" ]]; then
+  echo "ERROR: --input and --output are required" >&2
+  exit 1
+fi
+
+if [[ ! -f "$INPUT_PATH" ]]; then
+  echo "ERROR: input file not found: $INPUT_PATH" >&2
+  exit 1
+fi
+
+if [[ ! -f "$ANALYZER_PATH" ]]; then
+  echo "ERROR: analyzer file not found: $ANALYZER_PATH" >&2
+  exit 1
+fi
+
+if [[ -n "$CVSS_VECTORS_PATH" && ! -f "$CVSS_VECTORS_PATH" ]]; then
+  echo "ERROR: --cvss-vectors file not found: $CVSS_VECTORS_PATH" >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "ERROR: jq is required" >&2
+  exit 1
+fi
+
+if command -v python >/dev/null 2>&1; then
+  PYTHON_BIN="python"
+elif command -v python3 >/dev/null 2>&1; then
+  PYTHON_BIN="python3"
+else
+  echo "ERROR: python or python3 is required" >&2
+  exit 1
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+resolve_cvss_vector() {
+  local advisory_json="$1"
+  local advisory_id
+  advisory_id="$(echo "$advisory_json" | jq -r '.id // ""')"
+
+  if [[ -n "$CVSS_VECTORS_PATH" ]]; then
+    jq -r --arg id "$advisory_id" '.[$id] // ""' "$CVSS_VECTORS_PATH"
+  else
+    echo "$advisory_json" | jq -r '.cvss_vector // ""'
+  fi
+}
+
+severity_to_cvss() {
+  case "$1" in
+    critical) echo "9.5" ;;
+    high) echo "7.5" ;;
+    medium) echo "5.5" ;;
+    low) echo "3.0" ;;
+    *) echo "5.0" ;;
+  esac
+}
+
+build_analysis_input() {
+  local advisory_json="$1"
+  local mode="$2"
+  local cve_id cvss_score cvss_vector vuln_type description references severity
+
+  cve_id="$(echo "$advisory_json" | jq -r '.id // ""')"
+  vuln_type="$(echo "$advisory_json" | jq -r '.type // ""')"
+  description="$(echo "$advisory_json" | jq -r '.description // ""')"
+  references="$(echo "$advisory_json" | jq -c '.references // []')"
+  cvss_vector="$(resolve_cvss_vector "$advisory_json")"
+
+  if [[ "$mode" == "single" ]]; then
+    severity="$(echo "$advisory_json" | jq -r '.severity // "medium"')"
+    cvss_score="$(severity_to_cvss "$severity")"
+  else
+    cvss_score="$(echo "$advisory_json" | jq -r '.cvss_score // 0')"
+  fi
+
+  jq -n \
+    --arg cve_id "$cve_id" \
+    --argjson cvss_score "$cvss_score" \
+    --arg cvss_vector "$cvss_vector" \
+    --arg type "$vuln_type" \
+    --arg description "$description" \
+    --argjson references "$references" \
+    '{
+      cve_id: $cve_id,
+      cvss_score: $cvss_score,
+      cvss_vector: $cvss_vector,
+      type: $type,
+      description: $description,
+      references: $references
+    }'
+}
+
+run_analysis() {
+  local advisory_json="$1"
+  local mode="$2"
+  local output_file="$3"
+  local advisory_id analysis_input analysis
+
+  advisory_id="$(echo "$advisory_json" | jq -r '.id // "unknown"')"
+  analysis_input="$(build_analysis_input "$advisory_json" "$mode")"
+
+  if analysis="$(echo "$analysis_input" | "$PYTHON_BIN" "$ANALYZER_PATH" --json --check-exploits 2>/dev/null)"; then
+    echo "$analysis" > "$output_file"
+    return 0
+  fi
+
+  echo "::warning::Failed to analyze exploitability for $advisory_id, continuing without enrichment"
+  return 1
+}
+
+enrich_single() {
+  if ! jq -e 'type == "object"' "$INPUT_PATH" >/dev/null; then
+    echo "ERROR: single mode expects JSON object at $INPUT_PATH" >&2
+    exit 1
+  fi
+
+  local advisory analysis_file output_tmp
+  advisory="$(cat "$INPUT_PATH")"
+  analysis_file="$tmpdir/analysis_single.json"
+  output_tmp="$tmpdir/output_single.json"
+
+  if run_analysis "$advisory" "single" "$analysis_file"; then
+    jq --slurpfile analysis "$analysis_file" '
+      . + {
+        exploitability_score: $analysis[0].exploitability_score,
+        exploitability_rationale: $analysis[0].exploitability_rationale,
+        attack_vector_analysis: $analysis[0].attack_vector_analysis,
+        exploit_detection: $analysis[0].exploit_detection
+      }
+    ' "$INPUT_PATH" > "$output_tmp"
+  else
+    cp "$INPUT_PATH" "$output_tmp"
+  fi
+
+  mv "$output_tmp" "$OUTPUT_PATH"
+  echo "Exploitability enrichment complete (single): $OUTPUT_PATH"
+}
+
+enrich_batch() {
+  if ! jq -e 'type == "array"' "$INPUT_PATH" >/dev/null; then
+    echo "ERROR: batch mode expects JSON array at $INPUT_PATH" >&2
+    exit 1
+  fi
+
+  local analyzed_count failed_count index advisory analysis_file output_tmp analyses_json
+  analyzed_count=0
+  failed_count=0
+  index=0
+  analyses_json="$tmpdir/analyses.json"
+  output_tmp="$tmpdir/output_batch.json"
+
+  while IFS= read -r advisory; do
+    analysis_file="$tmpdir/analysis_${index}.json"
+    if run_analysis "$advisory" "batch" "$analysis_file"; then
+      analyzed_count=$((analyzed_count + 1))
+    else
+      failed_count=$((failed_count + 1))
+      rm -f "$analysis_file"
+    fi
+    index=$((index + 1))
+  done < <(jq -c '.[]' "$INPUT_PATH")
+
+  if ls "$tmpdir"/analysis_*.json >/dev/null 2>&1; then
+    jq -s '.' "$tmpdir"/analysis_*.json > "$analyses_json"
+  else
+    echo '[]' > "$analyses_json"
+  fi
+
+  jq --slurpfile analyses "$analyses_json" '
+    map(
+      . as $advisory |
+      ($analyses[0] | map(select(.cve_id == $advisory.id)) | first) as $analysis |
+      if $analysis then
+        $advisory + {
+          exploitability_score: $analysis.exploitability_score,
+          exploitability_rationale: $analysis.exploitability_rationale,
+          attack_vector_analysis: $analysis.attack_vector_analysis,
+          exploit_detection: $analysis.exploit_detection
+        }
+      else
+        $advisory
+      end
+    )
+  ' "$INPUT_PATH" > "$output_tmp"
+
+  mv "$output_tmp" "$OUTPUT_PATH"
+  echo "Exploitability enrichment complete (batch): $OUTPUT_PATH"
+  echo "Analyzed: $analyzed_count, failed: $failed_count"
+}
+
+if [[ "$MODE" == "single" ]]; then
+  enrich_single
+else
+  enrich_batch
+fi
@@ -0,0 +1,37 @@
+#!/bin/bash
+# feed-utils.sh
+# Shared advisory feed path and sync helpers for local/maintenance scripts.
+
+init_feed_paths() {
+  local project_root="$1"
+
+  : "${FEED_PATH:=$project_root/advisories/feed.json}"
+  : "${SKILL_FEED_PATH:=$project_root/skills/clawsec-feed/advisories/feed.json}"
+  : "${PUBLIC_FEED_PATH:=$project_root/public/advisories/feed.json}"
+}
+
+sync_feed_to_mirrors() {
+  local source_feed="$1"
+  local mode="${2:-create}"
+
+  local target
+  for target in "$SKILL_FEED_PATH" "$PUBLIC_FEED_PATH"; do
+    case "$mode" in
+      create)
+        mkdir -p "$(dirname "$target")"
+        cp "$source_feed" "$target"
+        echo "✓ Updated: $target"
+        ;;
+      existing-only)
+        if [ -f "$target" ]; then
+          cp "$source_feed" "$target"
+          echo "✓ Updated: $target"
+        fi
+        ;;
+      *)
+        echo "Error: unsupported mirror sync mode: $mode" >&2
+        return 1
+        ;;
+    esac
+  done
+}
@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  extractTitleFromMarkdown,
+  stripFrontmatter,
+} from '../utils/markdownHelpers.mjs';
+import {
+  isWikiIndexSlug,
+  toWikiLlmsPath,
+  toWikiRoute,
+} from '../utils/wikiPathHelpers.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const WIKI_ROOT = path.join(REPO_ROOT, 'wiki');
+const PUBLIC_WIKI_ROOT = path.join(REPO_ROOT, 'public', 'wiki');
+const LLM_INDEX_FILE = path.join(PUBLIC_WIKI_ROOT, 'llms.txt');
+
+const WEBSITE_BASE = 'https://clawsec.prompt.security';
+const REPO_BASE = 'https://github.com/prompt-security/clawsec';
+const RAW_BASE = 'https://raw.githubusercontent.com/prompt-security/clawsec/main';
+
+const toPosix = (inputPath) => inputPath.split(path.sep).join('/');
+const toLlmsPageUrl = (slug) => `${WEBSITE_BASE}${toWikiLlmsPath(slug)}`;
+
+const walkMarkdownFiles = async (dir) => {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await walkMarkdownFiles(fullPath);
+      files.push(...nested);
+      continue;
+    }
+    if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+};
+
+const sortDocs = (a, b) => {
+  if (a.slug === 'index' && b.slug !== 'index') return -1;
+  if (a.slug !== 'index' && b.slug === 'index') return 1;
+  return a.slug.localeCompare(b.slug, 'en', { sensitivity: 'base' });
+};
+
+const buildPageBody = (doc) => {
+  const pageRoute = toWikiRoute(doc.slug);
+  const pageUrl = `${WEBSITE_BASE}/#${pageRoute}`;
+  const sourceUrl = `${RAW_BASE}/wiki/${doc.relativePath}`;
+  const llmsUrl = toLlmsPageUrl(doc.slug);
+
+  return [
+    `# ClawSec Wiki · ${doc.title}`,
+    '',
+    'LLM-ready export for a single wiki page.',
+    '',
+    '## Canonical',
+    `- Wiki page: ${pageUrl}`,
+    `- LLM export: ${llmsUrl}`,
+    `- Source markdown: ${sourceUrl}`,
+    '',
+    '## Markdown',
+    '',
+    doc.content.trim(),
+    '',
+  ].join('\n');
+};
+
+const buildFallbackIndexBody = (docs) => {
+  const lines = [
+    '# ClawSec Wiki llms.txt',
+    '',
+    'LLM-readable index for wiki pages.',
+    '',
+    `Website wiki root: ${WEBSITE_BASE}/#/wiki`,
+    `GitHub wiki mirror: ${REPO_BASE}/wiki`,
+    `Canonical source of truth: ${REPO_BASE}/tree/main/wiki`,
+    '',
+    '## Generated Page Exports',
+  ];
+
+  for (const doc of docs) {
+    const pageRoute = toWikiRoute(doc.slug);
+    const pageUrl = `${WEBSITE_BASE}/#${pageRoute}`;
+    const llmsUrl = toLlmsPageUrl(doc.slug);
+    lines.push(`- ${doc.title}: ${llmsUrl} (page: ${pageUrl})`);
+  }
+
+  return `${lines.join('\n')}\n`;
+};
+
+const main = async () => {
+  try {
+    const wikiStat = await fs.stat(WIKI_ROOT).catch(() => null);
+    if (!wikiStat || !wikiStat.isDirectory()) {
+      throw new Error('wiki/ directory not found.');
+    }
+
+    const markdownFiles = await walkMarkdownFiles(WIKI_ROOT);
+    const docs = [];
+
+    for (const fullPath of markdownFiles) {
+      const relativePath = toPosix(path.relative(WIKI_ROOT, fullPath));
+      const slug = relativePath.replace(/\.md$/i, '').toLowerCase();
+      const rawContent = await fs.readFile(fullPath, 'utf8');
+      const content = stripFrontmatter(rawContent);
+      const title = extractTitleFromMarkdown(rawContent, relativePath);
+      docs.push({ relativePath, slug, title, content });
+    }
+
+    docs.sort(sortDocs);
+    const pageDocs = docs.filter((doc) => !isWikiIndexSlug(doc.slug));
+    const indexDoc = docs.find((doc) => isWikiIndexSlug(doc.slug));
+
+    // `public/wiki/` is fully generated; wipe stale output before regenerating.
+    await fs.rm(PUBLIC_WIKI_ROOT, { recursive: true, force: true });
+    await fs.mkdir(PUBLIC_WIKI_ROOT, { recursive: true });
+
+    for (const doc of pageDocs) {
+      const outputFile = path.join(PUBLIC_WIKI_ROOT, doc.slug, 'llms.txt');
+      await fs.mkdir(path.dirname(outputFile), { recursive: true });
+      await fs.writeFile(outputFile, buildPageBody(doc), 'utf8');
+    }
+
+    const indexBody = indexDoc ? buildPageBody(indexDoc) : buildFallbackIndexBody(pageDocs);
+    await fs.writeFile(LLM_INDEX_FILE, indexBody, 'utf8');
+
+    // Keep logs short for CI readability.
+    console.log(`Generated ${pageDocs.length} page llms.txt exports and /wiki/llms.txt`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Failed to generate wiki llms exports: ${message}`);
+    process.exit(1);
+  }
+};
+
+await main();
@@ -11,13 +11,14 @@ set -euo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=./feed-utils.sh
+source "$SCRIPT_DIR/feed-utils.sh"

 # Configuration - same as pipeline
-FEED_PATH="$PROJECT_ROOT/advisories/feed.json"
-SKILL_FEED_PATH="$PROJECT_ROOT/skills/clawsec-feed/advisories/feed.json"
-PUBLIC_FEED_PATH="$PROJECT_ROOT/public/advisories/feed.json"
-KEYWORDS="OpenClaw clawdbot Moltbot"
-GITHUB_REF_PATTERN="github.com/openclaw/openclaw"
+init_feed_paths "$PROJECT_ROOT"
+KEYWORDS="OpenClaw clawdbot Moltbot NanoClaw WhatsApp-bot baileys"
+GITHUB_REF_PATTERN="github.com/openclaw/openclaw github.com/qwibitai/NanoClaw"
+ENRICH_SCRIPT="$PROJECT_ROOT/scripts/ci/enrich_exploitability.sh"

 # Parse args
 DAYS_BACK=120
@@ -46,6 +47,12 @@ echo "Days back: $DAYS_BACK"
 echo "Force mode: $FORCE"
 echo ""

+# Verify enrichment helper exists (it validates Python/analyzer prerequisites internally).
+if [ ! -x "$ENRICH_SCRIPT" ]; then
+  echo "Error: Exploitability enrichment helper not found or not executable: $ENRICH_SCRIPT"
+  exit 1
+fi
+
 # Create temp directory
 TEMP_DIR=$(mktemp -d)
 trap 'rm -rf "$TEMP_DIR"' EXIT
@@ -62,7 +69,7 @@ fi
 if [ -z "${START_DATE:-}" ]; then
  # macOS vs Linux date compatibility
  if date -v-1d > /dev/null 2>&1; then
-    START_DATE=$(date -u -v-${DAYS_BACK}d +%Y-%m-%dT%H:%M:%S.000Z)
+    START_DATE=$(date -u -v-"${DAYS_BACK}"d +%Y-%m-%dT%H:%M:%S.000Z)
  else
    START_DATE=$(date -u -d "${DAYS_BACK} days ago" +%Y-%m-%dT%H:%M:%S.000Z)
  fi
@@ -74,8 +81,8 @@ echo "End date: $END_DATE"
 echo ""

 # URL encode dates
-START_ENC=$(echo "$START_DATE" | sed 's/:/%3A/g')
-END_ENC=$(echo "$END_DATE" | sed 's/:/%3A/g')
+START_ENC=${START_DATE//:/%3A}
+END_ENC=${END_DATE//:/%3A}

 echo "=== Fetching CVEs from NVD ==="

@@ -128,7 +135,7 @@ TOTAL=$(jq 'length' "$TEMP_DIR/unique_cves.json")
 echo "Total unique CVEs from NVD: $TOTAL"

 # Post-filter: keep only CVEs matching our criteria
-KEYWORDS_PATTERN="OpenClaw|clawdbot|Moltbot|openclaw"
+KEYWORDS_PATTERN="OpenClaw|clawdbot|Moltbot|openclaw|NanoClaw|nanoclaw|WhatsApp-bot|baileys"

 jq --arg kw "$KEYWORDS_PATTERN" --arg gh "$GITHUB_REF_PATTERN" '
  [.[] | select(
@@ -236,8 +243,38 @@ jq --argjson existing "$EXISTING_JSON" '
        else (cwe_name_map($id) // ("unknown_cwe_" + $id))
        end
    );
+
+  def cpe_criteria:
+    (
+      [.cve.configurations[]? | .. | objects | .criteria? | strings | select(startswith("cpe:2.3:"))]
+      | unique
+    );
+
+  def inferred_targets:
+    (
+      (
+        [
+          (.cve.descriptions[]? | select(.lang == "en") | .value),
+          (.cve.references[]?.url // empty)
+        ]
+        | map(strings | ascii_downcase)
+        | join(" ")
+      ) as $blob
+      | (
+          (if ($blob | test("github\\.com/openclaw/openclaw|\\bopenclaw\\b|\\bclawdbot\\b|\\bmoltbot\\b")) then ["openclaw@*"] else [] end)
+          + (if ($blob | test("github\\.com/qwibitai/nanoclaw|\\bnanoclaw\\b|whatsapp-bot|\\bbaileys\\b")) then ["nanoclaw@*"] else [] end)
+        )
+    );
+
+  def normalized_affected:
+    (
+      (cpe_criteria + inferred_targets)
+      | unique
+      | .[0:5]
+      | if length == 0 then ["openclaw@*", "nanoclaw@*"] else . end
+    );
  
-  [.[] | 
+  [.[] |
    select(.cve.id as $id | $existing | index($id) | not) |
    {
      id: .cve.id,
@@ -246,12 +283,14 @@ jq --argjson existing "$EXISTING_JSON" '
      nvd_category_id: nvd_category_raw,
      title: (.cve.descriptions[] | select(.lang == "en") | .value | .[0:100] + (if length > 100 then "..." else "" end)),
      description: (.cve.descriptions[] | select(.lang == "en") | .value),
-      affected: [.cve.configurations[]?.nodes[]?.cpeMatch[]?.criteria // empty] | unique | .[0:5],
+      affected: normalized_affected,
      action: "Review and update affected components. See NVD for remediation details.",
      published: .cve.published,
      references: [.cve.references[]?.url // empty] | unique | .[0:3],
      cvss_score: get_cvss_score,
-      nvd_url: ("https://nvd.nist.gov/vuln/detail/" + .cve.id)
+      nvd_url: ("https://nvd.nist.gov/vuln/detail/" + .cve.id),
+      exploitability_score: null,
+      exploitability_rationale: null
    }
  ]
 ' "$TEMP_DIR/filtered_cves.json" > "$TEMP_DIR/new_advisories.json"
@@ -266,6 +305,28 @@ if [ "$NEW_COUNT" -eq 0 ]; then
  exit 0
 fi

+echo ""
+echo "=== Analyzing Exploitability ==="
+
+# Build CVSS vector lookup for enriched analysis inputs.
+jq '
+  [.[] | {
+    id: .cve.id,
+    cvss_vector: (
+      .cve.metrics.cvssMetricV31[0]?.cvssData.vectorString //
+      .cve.metrics.cvssMetricV30[0]?.cvssData.vectorString //
+      .cve.metrics.cvssMetricV2[0]?.vectorString //
+      ""
+    )
+  }] | map({(.id): .cvss_vector}) | add
+' "$TEMP_DIR/filtered_cves.json" > "$TEMP_DIR/cvss_vectors.json"
+
+"$ENRICH_SCRIPT" \
+  --mode batch \
+  --input "$TEMP_DIR/new_advisories.json" \
+  --output "$TEMP_DIR/new_advisories.json" \
+  --cvss-vectors "$TEMP_DIR/cvss_vectors.json"
+
 echo ""
 echo "=== New Advisories ==="
 jq -r '.[] | "  \(.id) [\(.severity)] - \(.title)"' "$TEMP_DIR/new_advisories.json"
@@ -298,7 +359,7 @@ else
  jq -n --argjson advisories "$(cat "$TEMP_DIR/new_advisories.json")" --arg now "$NOW" '{
    version: "1.0.0",
    updated: $now,
-    description: "Community-driven security advisory feed for ClawSec. Automatically updated with OpenClaw-related CVEs from NVD.",
+    description: "Community-driven security advisory feed for ClawSec. Automatically updated with OpenClaw and NanoClaw-related CVEs from NVD.",
    advisories: ($advisories | sort_by(.published) | reverse)
  }' > "$TEMP_DIR/updated_feed.json"
 fi
@@ -308,16 +369,9 @@ if jq empty "$TEMP_DIR/updated_feed.json" 2>/dev/null; then
  # Update main feed
  cp "$TEMP_DIR/updated_feed.json" "$FEED_PATH"
  echo "✓ Updated: $FEED_PATH"
-  
-  # Update skill feed
-  mkdir -p "$(dirname "$SKILL_FEED_PATH")"
-  cp "$FEED_PATH" "$SKILL_FEED_PATH"
-  echo "✓ Updated: $SKILL_FEED_PATH"
-  
-  # Update public feed for local dev
-  mkdir -p "$(dirname "$PUBLIC_FEED_PATH")"
-  cp "$FEED_PATH" "$PUBLIC_FEED_PATH"
-  echo "✓ Updated: $PUBLIC_FEED_PATH"
+
+  # Sync feed mirrors for local skill/public consumers.
+  sync_feed_to_mirrors "$FEED_PATH" "create"
  
  echo ""
  TOTAL_ADVISORIES=$(jq '.advisories | length' "$FEED_PATH")
@@ -0,0 +1,31 @@
+#!/bin/bash
+# populate-local-wiki.sh
+# Generates wiki-derived public assets for local preview and CI parity.
+#
+# Usage: ./scripts/populate-local-wiki.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+WIKI_DIR="$PROJECT_ROOT/wiki"
+PUBLIC_WIKI_DIR="$PROJECT_ROOT/public/wiki"
+
+if [ ! -d "$WIKI_DIR" ]; then
+  echo "Error: wiki directory not found at $WIKI_DIR"
+  exit 1
+fi
+
+echo "=== ClawSec Local Wiki Populator ==="
+echo "Project root: $PROJECT_ROOT"
+
+node "$PROJECT_ROOT/scripts/generate-wiki-llms.mjs"
+
+PAGE_COUNT=0
+if [ -d "$PUBLIC_WIKI_DIR" ]; then
+  PAGE_COUNT=$(find "$PUBLIC_WIKI_DIR" -type f -path '*/llms.txt' ! -path "$PUBLIC_WIKI_DIR/llms.txt" | wc -l | tr -d ' ')
+fi
+
+echo "Wiki llms index: $PUBLIC_WIKI_DIR/llms.txt"
+echo "Wiki llms pages: $PAGE_COUNT files under $PUBLIC_WIKI_DIR/<page>/llms.txt"
@@ -76,13 +76,13 @@ fi
 # ESLint
 echo -e "\n${YELLOW}Running ESLint...${NC}"
 if $FIX_MODE; then
-  if npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --fix; then
+  if npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --ignore-pattern '.auto-claude/**' --fix; then
    check_pass "ESLint (with auto-fix)"
  else
    check_fail "ESLint found unfixable issues"
  fi
 else
-  if npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0; then
+  if npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --ignore-pattern '.auto-claude/**' --max-warnings 0; then
    check_pass "ESLint"
  else
    check_fail "ESLint found issues (run with --fix to auto-fix)"
@@ -190,7 +190,7 @@ print_header "Security"
 # Trivy FS Scan
 if command -v trivy &> /dev/null; then
  echo -e "\n${YELLOW}Running Trivy filesystem scan...${NC}"
-  if trivy fs . --severity CRITICAL,HIGH --exit-code 1 --ignore-unfixed; then
+  if trivy fs . --severity CRITICAL,HIGH --exit-code 1 --ignore-unfixed --skip-dirs .auto-claude --skip-files clawsec-signing-private.pem; then
    check_pass "Trivy filesystem scan"
  else
    check_fail "Trivy found CRITICAL/HIGH vulnerabilities"
@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to the ClawSec Feed skill will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.5] - 2026-02-28
+
+### Added
+
+- Exploitability-focused advisory guidance, including filtering and prioritization examples.
+- Notification examples that include exploitability context and rationale.
+
+### Changed
+
+- Clarified exploitability scoring guidance to match runtime values (`high|medium|low|unknown`).
+- Updated response-priority guidance to align with exploitability-first triage.
+- De-duplicated exploitability filtering guidance in `SKILL.md` by pointing to canonical docs in `wiki/exploitability-scoring.md` and `clawsec-suite`.
@@ -1,6 +1,6 @@
 ---
 name: clawsec-feed
-version: 0.0.4
+version: 0.0.5
 description: Security advisory feed with automated NVD CVE polling for OpenClaw-related vulnerabilities. Updated daily.
 homepage: https://clawsec.prompt.security
 metadata: {"openclaw":{"emoji":"📡","category":"security"}}
@@ -318,7 +318,9 @@ curl -sSL --fail --show-error --retry 3 --retry-delay 1 "$FEED_URL"
      "description": "Skill sends user data to external server",
      "affected": ["helper-plus@1.0.0", "helper-plus@1.0.1"],
      "action": "Remove immediately",
-      "published": "2026-02-01T10:00:00Z"
+      "published": "2026-02-01T10:00:00Z",
+      "exploitability_score": "critical",
+      "exploitability_rationale": "Trivially exploitable through normal skill usage; no special conditions required. Active exploitation observed in the wild."
    }
  ]
 }
@@ -385,6 +387,42 @@ fi
 echo "$RECENT"
 ```

+### Filter by exploitability score
+
+Shared exploitability prioritization guidance is maintained in:
+
+- [`wiki/exploitability-scoring.md`](../../wiki/exploitability-scoring.md)
+- [`skills/clawsec-suite/SKILL.md`](../clawsec-suite/SKILL.md) ("Quick feed check")
+
+### Get exploitability context for an advisory
+
+```bash
+# Show exploitability details for a specific CVE
+CVE_ID="CVE-2026-27488"
+echo "$FEED" | jq --arg cve "$CVE_ID" '.advisories[] | select(.id == $cve) | {
+  id: .id,
+  severity: .severity,
+  exploitability_score: .exploitability_score,
+  exploitability_rationale: .exploitability_rationale,
+  title: .title
+}'
+```
+
+### Prioritize advisories by exploitability
+
+```bash
+# Sort advisories by exploitability (critical → high → medium → low)
+# This helps agents focus on the most immediately actionable threats
+echo "$FEED" | jq '[.advisories[] | select(.exploitability_score != null)] |
+  sort_by(
+    if .exploitability_score == "critical" then 0
+    elif .exploitability_score == "high" then 1
+    elif .exploitability_score == "medium" then 2
+    elif .exploitability_score == "low" then 3
+    else 4 end
+  )'
+```
+
 ---

 ## Cross-Reference Installed Skills
@@ -476,23 +514,75 @@ done

 ---

+## Prioritizing High-Exploitability Threats
+
+**IMPORTANT:** When reviewing advisories, always prioritize by **exploitability score** in addition to severity. The exploitability score indicates how easily a vulnerability can be exploited in practice, helping you focus on the most actionable threats.
+
+### Exploitability Priority Levels
+
+| Exploitability | Meaning | Action Priority |
+|----------------|---------|-----------------|
+| `high` | Trivially or easily exploitable with public tooling | **Immediate notification** |
+| `medium` | Exploitable but requires specific conditions | **Standard notification** |
+| `low` | Difficult to exploit or theoretical | **Low priority notification** |
+
+### How to Use Exploitability in Notifications
+
+1. **Filter for high-exploitability first:**
+   ```bash
+   # Get high exploitability advisories
+   echo "$FEED" | jq '.advisories[] | select(.exploitability_score == "high")'
+   ```
+
+2. **Include exploitability in notifications:**
+   ```
+   📡 ClawSec Feed: High-exploitability alert
+
+   CRITICAL - CVE-2026-27488 (Exploitability: HIGH)
+     → Trivially exploitable RCE in skill-loader v2.1.0
+     → Public exploit code available
+     → Recommended action: Immediate removal or upgrade to v2.1.1
+   ```
+
+3. **Prioritize by both severity AND exploitability:**
+   - A HIGH severity + HIGH exploitability CVE is more urgent than a CRITICAL severity + LOW exploitability CVE
+   - Focus user attention on threats that are both severe and easily exploitable
+   - Include the exploitability rationale to help users understand the risk context
+
+### Example Notification Priority Order
+
+When multiple advisories exist, present them in this order:
+1. **Critical severity + High exploitability** - most urgent
+2. **High severity + High exploitability**
+3. **Critical severity + Medium/Low exploitability**
+4. **High severity + Medium/Low exploitability**
+5. **Medium/Low severity** (any exploitability)
+
+This ensures you alert users to the most actionable, immediately dangerous threats first.
+
+---
+
 ## When to Notify Your User

 **Notify Immediately (Critical):**
 - New critical advisory affecting an installed skill
 - Active exploitation detected
+- **High exploitability score** (regardless of severity)

 **Notify Soon (High):**
 - New high-severity advisory affecting installed skills
 - Failed to fetch advisory feed (network issue?)
+- Medium exploitability with high severity

 **Notify at Next Interaction (Medium):**
 - New medium-severity advisories
 - General security updates
+- Low exploitability advisories

 **Log Only (Low/Info):**
 - Low-severity advisories (mention if user asks)
 - Feed checked, no new advisories
+- Theoretical vulnerabilities (low exploitability, low severity)

 ---

@@ -503,11 +593,13 @@ done
 ```
 📡 ClawSec Feed: 2 new advisories since last check

-CRITICAL - GA-2026-015: Malicious prompt pattern "ignore-all"
+CRITICAL - GA-2026-015: Malicious prompt pattern "ignore-all" (Exploitability: HIGH)
  → Detected prompt injection technique. Update your system prompt defenses.
+  → Exploitability: Easily exploitable with publicly documented techniques.

-HIGH - GA-2026-016: Vulnerable skill "data-helper" v1.2.0
+HIGH - GA-2026-016: Vulnerable skill "data-helper" v1.2.0 (Exploitability: MEDIUM)
  → You have this installed! Recommended action: Update to v1.2.1 or remove.
+  → Exploitability: Requires specific configuration; not trivially exploitable.
 ```

 ### If nothing new:
@@ -1 +1 @@
-Rs++ntJvBvX4zVTJ/DsrfXOQG3VTUc2x4esSURSMonesmYzSm9U9kd3rBz5d+DemJOVJ/esH21VACpdE+T34AA==
+qNd1mJmbXNyIP+5CjBppoCIDu0PNRWYNFWpmzgtIFPJ6P62epcDaQKgi+dTDRUbk8jANIb+Ukf8vk+iz3CrIDg==
@@ -1,6 +1,6 @@
 {
  "name": "clawsec-feed",
-  "version": "0.0.4",
+  "version": "0.0.5",
  "description": "Security advisory feed monitoring for AI agents. Subscribe to community-driven threat intelligence.",
  "author": "prompt-security",
  "license": "AGPL-3.0-or-later",
@@ -21,6 +21,11 @@
        "required": true,
        "description": "Advisory feed skill documentation"
      },
+      {
+        "path": "CHANGELOG.md",
+        "required": true,
+        "description": "Version history for advisory feed updates"
+      },
      {
        "path": "advisories/feed.json",
        "required": true,
@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the ClawSec NanoClaw compatibility skill will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.3] - 2026-03-09
+
+### Security
+
+- Removed runtime public-key override from host-side package signature verification; verification now always uses the pinned ClawSec key.
+- Removed unsigned-package override path in host-side verification flow.
+- Added strict package/signature path policy for signature verification (`/tmp`, `/var/tmp`, `/workspace/ipc`, `/workspace/project/data`, `/workspace/project/tmp`, `/workspace/project/downloads`) with absolute-path, extension, symlink, and realpath boundary checks.
+- Added policy-bound path enforcement for integrity approvals: approvals now require normalized paths that are explicitly present in non-ignored integrity policy targets.
+
+### Changed
+
+- Updated MCP signature verification tool docs and behavior to align with bounded path policy and pinned-key-only verification.
+- Added regression tests for signature-verification and integrity-approval hardening invariants.
+
+## [0.0.2] - 2026-02-28
+
+### Added
+
+- Exploitability-aware advisory output in NanoClaw MCP tools (`exploitability_score`, `exploitability_rationale`).
+- Exploitability filtering (`exploitabilityScore`) for `clawsec_list_advisories`.
+
+### Changed
+
+- Updated NanoClaw advisory sorting and pre-install safety recommendation logic to prioritize exploitability context.
+- Updated NanoClaw integration docs to match current host/container integration points (`src/ipc.ts`, `src/index.ts`) and current cache schema.
+- Removed duplicate exploitability normalization logic from MCP advisory tools and now reuse `normalizeExploitabilityScore` from `lib/risk.ts`.
+- Reused `matchesAffectedSpecifier` from `lib/advisories.ts` in MCP advisory tools to keep skill/version matching logic centralized and consistent.
@@ -8,7 +8,7 @@ ClawSec provides security advisory monitoring for NanoClaw through:
 - **MCP Tools**: Agents can check for vulnerabilities via `clawsec_check_advisories`
 - **Advisory Feed**: Automatic monitoring of https://clawsec.prompt.security/advisories/feed.json
 - **Signature Verification**: Ed25519-signed feeds ensure integrity
- **Platform Targeting**: Advisories can be NanoClaw-specific or cross-platform
+- **Exploitability Context**: Advisories include exploitability score and rationale for triage

 ## Prerequisites

@@ -57,18 +57,30 @@ in each tool file).

 Add the host-side IPC handlers for ClawSec operations.

-**File**: `host/ipc-handler.ts`
+**File**: `src/ipc.ts`

 ```typescript
-// Add this import at the top
-import { registerClawSecHandlers } from '../skills/clawsec-nanoclaw/host-services/ipc-handlers.js';
+// Add these imports at the top
+import { handleAdvisoryIpc } from '../skills/clawsec-nanoclaw/host-services/ipc-handlers.js';
+import { AdvisoryCacheManager } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';
+import { SkillSignatureVerifier } from '../skills/clawsec-nanoclaw/host-services/skill-signature-handler.js';

-// In your IPC handler setup function
-export function setupIpcHandlers() {
-  // ... your existing handlers ...
+// Initialize these once in host startup and pass through deps
+const advisoryCacheManager = new AdvisoryCacheManager('/workspace/project/data', logger);
+const signatureVerifier = new SkillSignatureVerifier();

-  // Register ClawSec handlers
-  registerClawSecHandlers();
+// In processTaskIpc switch:
+case 'refresh_advisory_cache':
+case 'verify_skill_signature':
+  await handleAdvisoryIpc(
+    data,
+    { advisoryCacheManager, signatureVerifier },
+    logger,
+    sourceGroup
+  );
+  break;
+default:
+  // existing task handling
 }
 ```

@@ -76,23 +88,25 @@ export function setupIpcHandlers() {

 Add the advisory cache manager to your host services.

-**File**: `host/index.ts` (or your main entry point)
+**File**: `src/index.ts` (or your main entry point)

 ```typescript
-// Add this import
-import { startAdvisoryCache } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';
+import { AdvisoryCacheManager } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';

 // Start the service when your host process starts
 async function main() {
  // ... your existing initialization ...

-  // Start ClawSec advisory cache (fetches feed every 6 hours)
-  startAdvisoryCache({
-    cacheFile: '/workspace/project/data/clawsec-advisory-cache.json',
-    feedUrl: 'https://clawsec.prompt.security/advisories/feed.json',
-    publicKeyPath: '/workspace/project/skills/clawsec-nanoclaw/advisories/feed-signing-public.pem',
-    refreshInterval: 6 * 60 * 60 * 1000, // 6 hours
-  });
+  // Initialize cache manager and prime it at startup
+  const advisoryCacheManager = new AdvisoryCacheManager('/workspace/project/data', logger);
+  await advisoryCacheManager.initialize();
+
+  // Recommended refresh cadence (6h)
+  setInterval(() => {
+    advisoryCacheManager.refresh().catch((error) => {
+      logger.error({ error }, 'Periodic advisory cache refresh failed');
+    });
+  }, 6 * 60 * 60 * 1000);

  // ... rest of your startup ...
 }
@@ -126,6 +140,8 @@ From within a NanoClaw agent session, the following tools should be available:

 **Signature Verification** (mcp-tools/signature-verification.ts):
 - `clawsec_verify_skill_package` - Verify Ed25519 signature on skill packages
+  - Uses pinned ClawSec public key (no runtime key override)
+  - Accepts staged package/signature paths only under `/tmp`, `/var/tmp`, `/workspace/ipc`, `/workspace/project/data`, `/workspace/project/tmp`, `/workspace/project/downloads`

 **Integrity Monitoring** (mcp-tools/integrity-tools.ts):
 - `clawsec_check_integrity` - Check protected files for unauthorized changes
@@ -151,9 +167,9 @@ cat /workspace/project/data/clawsec-advisory-cache.json

 You should see:
 - `feed`: Array of advisories
- `signature`: Ed25519 signature
- `lastFetch`: Timestamp of last update
+- `fetchedAt`: Timestamp of last update
 - `verified`: Should be `true`
+- `publicKeyFingerprint`: SHA-256 fingerprint of the pinned signing key

 ## Usage Examples

@@ -183,13 +199,13 @@ You can also call the MCP tools directly from agent code:
 ```typescript
 // Check all installed skills
 const result = await tools.clawsec_check_advisories({
-  skillsRoot: '/workspace/project/skills'
+  installRoot: '/home/node/.claude/skills'
 });

 // Check specific skill before installation
 const safetyCheck = await tools.clawsec_check_skill_safety({
  skillName: 'risky-skill',
-  version: '1.0.0'
+  skillVersion: '1.0.0'
 });
 ```

@@ -199,19 +215,19 @@ const safetyCheck = await tools.clawsec_check_skill_safety({

 Default: `/workspace/project/data/clawsec-advisory-cache.json`

-To change, update the `cacheFile` parameter in `startAdvisoryCache()`.
+To change, pass a different data directory path to `new AdvisoryCacheManager(dataDir, logger)`.

 ### Refresh Interval

 Default: 6 hours

-To change, update the `refreshInterval` parameter (in milliseconds).
+To change, update the `setInterval(...)` duration (in milliseconds) in host startup.

 ### Feed URL

 Default: `https://clawsec.prompt.security/advisories/feed.json`

-To use a mirror or custom feed, update the `feedUrl` parameter.
+To use a mirror or custom feed, update `FEED_URL` in `skills/clawsec-nanoclaw/host-services/advisory-cache.ts`.

 ## Platform-Specific Advisories

@@ -222,7 +238,7 @@ ClawSec advisories can target specific platforms:
 - **`platforms: ["openclaw", "nanoclaw"]`**: Affects both
 - **No `platforms` field**: Applies to all platforms

-The MCP tools automatically filter advisories based on your platform.
+Platform metadata is preserved in advisory records and can be filtered by your policy layer.

 ## Security

@@ -260,7 +276,7 @@ Never manually edit the cache file - it will break signature verification.
 **Problem**: Advisory cache is empty or stale

 **Solution**:
-1. Check that `startAdvisoryCache()` is called in your host entry point
+1. Check that `AdvisoryCacheManager.initialize()` is called in your host entry point
 2. Verify network access to `clawsec.prompt.security`
 3. Check host logs for fetch errors
 4. Manually trigger: `curl https://clawsec.prompt.security/advisories/feed.json`
@@ -280,7 +296,7 @@ Never manually edit the cache file - it will break signature verification.
 **Problem**: Tools return errors about IPC

 **Solution**:
-1. Verify IPC handlers are registered in `host/ipc-handler.ts`
+1. Verify IPC handlers are registered in `src/ipc.ts`
 2. Check that IPC directory exists and is writable
 3. Ensure host process is running
 4. Check host logs for handler errors
@@ -290,8 +306,8 @@ Never manually edit the cache file - it will break signature verification.
 To remove ClawSec from NanoClaw:

 1. Remove MCP tool registration from `ipc-mcp-stdio.ts`
-2. Remove IPC handler registration from `host/ipc-handler.ts`
-3. Remove `startAdvisoryCache()` call from host entry point
+2. Remove IPC handler registration from `src/ipc.ts`
+3. Remove `AdvisoryCacheManager` initialization from host entry point
 4. Delete the skill directory: `rm -rf skills/clawsec-nanoclaw`
 5. Delete the cache file: `rm /workspace/project/data/clawsec-advisory-cache.json`
 6. Restart NanoClaw
@@ -56,9 +56,9 @@ ClawSec provides a complete security skill for NanoClaw deployments:
  - `clawsec_integrity_status` - View file baseline status
  - `clawsec_verify_audit` - Verify audit log hash chain

- **Advisory Cache Service**: Automatic feed fetching every 6 hours
+- **Advisory Cache Service**: Host-managed feed fetching with signature validation
 - **Signature Verification**: Ed25519-signed feeds ensure integrity
- **Platform Filtering**: Shows only relevant advisories for NanoClaw
+- **Exploitability Context**: Surfaces `exploitability_score` and rationale to reduce alert fatigue
 - **IPC Communication**: Container-safe host communication

 ### Installation
@@ -77,19 +77,19 @@ The skill integrates into three places:
 **1. MCP Tools** (container):
 ```typescript
 // container/agent-runner/src/ipc-mcp-stdio.ts
-import { clawsecTools } from '../../../skills/clawsec-nanoclaw/mcp-tools/advisory-tools.js';
+import '../../../skills/clawsec-nanoclaw/mcp-tools/advisory-tools.js';
 ```

 **2. IPC Handlers** (host):
 ```typescript
-// host/ipc-handler.ts
-import { registerClawSecHandlers } from '../skills/clawsec-nanoclaw/host-services/ipc-handlers.js';
+// src/ipc.ts
+import { handleAdvisoryIpc } from '../skills/clawsec-nanoclaw/host-services/ipc-handlers.js';
 ```

 **3. Cache Service** (host):
 ```typescript
-// host/index.ts
-import { startAdvisoryCache } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';
+// src/index.ts
+import { AdvisoryCacheManager } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';
 ```

 ### Advisory Feed
@@ -142,10 +142,10 @@ Planned features for future releases:
 - [Skill Documentation](skills/clawsec-nanoclaw/SKILL.md) - Features and architecture
 - [Installation Guide](skills/clawsec-nanoclaw/INSTALL.md) - Detailed setup instructions
 - [ClawSec Main README](README.md) - Overall ClawSec documentation
- [Security & Signing](../../docs/SECURITY-SIGNING.md) - Signature verification details
+- [Security & Signing](../../wiki/security-signing-runbook.md) - Signature verification details

 ## Support

 - **Issues**: https://github.com/prompt-security/clawsec/issues
 - **Security**: security@prompt.security
- NanoClaw Repository: (link TBD)
+- NanoClaw Repository: https://github.com/qwibitai/nanoclaw
@@ -1,6 +1,6 @@
 ---
 name: clawsec-nanoclaw
-version: 0.0.1
+version: 0.0.3
 description: Use when checking for security vulnerabilities in NanoClaw skills, before installing new skills, or when asked about security advisories affecting the bot
 ---

@@ -10,7 +10,7 @@ Security advisory monitoring that protects your WhatsApp bot from known vulnerab

 ## Overview

-ClawSec provides MCP tools that check installed skills against a curated feed of security advisories. It prevents installation of vulnerable skills and alerts you to issues in existing ones.
+ClawSec provides MCP tools that check installed skills against a curated feed of security advisories. It prevents installation of vulnerable skills, includes exploitability context for triage, and alerts you to issues in existing ones.

 **Core principle:** Check before you install. Monitor what's running.

@@ -36,7 +36,7 @@ Do NOT use for:
 // Before installing any skill
 const safety = await tools.clawsec_check_skill_safety({
  skillName: 'new-skill',
-  version: '1.0.0'  // optional
+  skillVersion: '1.0.0'  // optional
 });

 if (!safety.safe) {
@@ -48,14 +48,16 @@ if (!safety.safe) {
 ### Security Audit

 ```typescript
-// Check all installed skills
+// Check all installed skills (defaults to ~/.claude/skills in the container)
 const result = await tools.clawsec_check_advisories({
-  skillsRoot: '/workspace/project/skills'  // optional
+  installRoot: '/home/node/.claude/skills'  // optional
 });

-if (result.criticalCount > 0) {
+if (result.matches.some((m) =>
+  m.advisory.severity === 'critical' || m.advisory.exploitability_score === 'high'
+)) {
  // Alert user immediately
-  console.error('CRITICAL vulnerabilities found!');
+  console.error('Urgent advisories found!');
 }
 ```

@@ -64,8 +66,8 @@ if (result.criticalCount > 0) {
 ```typescript
 // List advisories with filters
 const advisories = await tools.clawsec_list_advisories({
-  platform: 'nanoclaw',    // optional: nanoclaw, openclaw, or both
-  severity: 'critical'     // optional: critical, high, medium, low
+  severity: 'high',               // optional
+  exploitabilityScore: 'high'     // optional
 });
 ```

@@ -75,7 +77,7 @@ const advisories = await tools.clawsec_list_advisories({
 |------|------|---------------|
 | Pre-install check | `clawsec_check_skill_safety` | `skillName` |
 | Audit all skills | `clawsec_check_advisories` | `installRoot` (optional) |
-| Browse feed | `clawsec_list_advisories` | `severity`, `type` (optional) |
+| Browse feed | `clawsec_list_advisories` | `severity`, `type`, `exploitabilityScore` (optional) |
 | Verify package signature | `clawsec_verify_skill_package` | `packagePath` |
 | Refresh advisory cache | `clawsec_refresh_cache` | (none) |
 | Check file integrity | `clawsec_check_integrity` | `mode`, `autoRestore` (optional) |
@@ -110,7 +112,7 @@ if (safety.safe) {
 ```typescript
 // Add to scheduled tasks
 schedule_task({
-  prompt: "Check for security advisories using clawsec_check_advisories and alert if any critical issues found",
+  prompt: "Check advisories using clawsec_check_advisories and alert when critical or high-exploitability matches appear",
  schedule_type: "cron",
  schedule_value: "0 9 * * *"  // Daily at 9am
 });
@@ -125,8 +127,8 @@ You: I'll check installed skills for known vulnerabilities.
 [Use clawsec_check_advisories]

 Response:
-✅ No critical issues found.
- 2 low-severity advisories (not urgent)
+✅ No urgent issues found.
+- 2 low-severity/low-exploitability advisories
 - All skills up to date
 ```

@@ -146,30 +148,33 @@ const safety = await tools.clawsec_check_skill_safety({
 if (safety.safe) await installSkill('untrusted-skill');
 ```

-### ❌ Ignoring platform filters
+### ❌ Ignoring exploitability context
 ```typescript
-// DON'T: Check OpenClaw advisories on NanoClaw
-const advisories = await tools.clawsec_list_advisories({
-  platform: 'openclaw'  // Wrong platform!
-});
+// DON'T: Use severity only
+if (advisory.severity === 'high') {
+  notifyNow(advisory);
+}
 ```

 ```typescript
-// DO: Use correct platform or let it auto-filter
-const advisories = await tools.clawsec_list_advisories({
-  platform: 'nanoclaw'  // Correct
-});
+// DO: Use exploitability + severity
+if (
+  advisory.exploitability_score === 'high' ||
+  advisory.severity === 'critical'
+) {
+  notifyNow(advisory);
+}
 ```

 ### ❌ Skipping critical severity
 ```typescript
-// DON'T: Only check low severity
-if (result.lowCount > 0) alert();
+// DON'T: Ignore high exploitability in medium severity advisories
+if (advisory.severity === 'critical') alert();
 ```

 ```typescript
-// DO: Prioritize critical and high
-if (result.criticalCount > 0 || result.highCount > 0) {
+// DO: Prioritize exploitability and severity together
+if (advisory.exploitability_score === 'high' || advisory.severity === 'critical') {
  // Alert immediately
 }
 ```
@@ -181,8 +186,9 @@ if (result.criticalCount > 0 || result.highCount > 0) {
 **Update Frequency**: Every 6 hours (automatic)

 **Signature Verification**: Ed25519 signed feeds
+**Package Verification Policy**: pinned key only, bounded package/signature paths

-**Cache Location**: `/workspace/project/data/clawsec-cache.json`
+**Cache Location**: `/workspace/project/data/clawsec-advisory-cache.json`

 See [INSTALL.md](./INSTALL.md) for setup and [docs/](./docs/) for advanced usage.

@@ -130,16 +130,21 @@ console.log('Safe to proceed with installation.');
 ### MCP Tool: `clawsec_verify_skill_package`

 **Parameters:**
- `packagePath` (required): Absolute path to skill package (`.tar.gz` or `.zip`)
+- `packagePath` (required): Absolute path to skill package (`.tar.gz`, `.tar`, `.tgz`, or `.zip`)
 - `signaturePath` (optional): Path to signature file (auto-detects `.sig` if omitted)

+Path policy:
+- Files must be under one of: `/tmp`, `/var/tmp`, `/workspace/ipc`, `/workspace/project/data`, `/workspace/project/tmp`, `/workspace/project/downloads`
+- Symlinks are rejected
+- Signatures must use `.sig`
+
 **Returns:**
 ```typescript
 {
  success: boolean,           // Operation completed without errors
  valid: boolean,             // Signature is cryptographically valid
  recommendation: string,     // "install" | "block" | "review"
-  signer: string,             // "clawsec" or custom signer
+  signer: string,             // "clawsec"
  algorithm: "Ed25519",       // Signature algorithm
  verifiedAt: string,         // ISO timestamp
  packageInfo: {
@@ -335,22 +340,10 @@ openssl pkey -pubin -in feed-signing-public.pem -outform DER | \
 # Expected: <will be filled in after key generation>
 ```

-### Using Custom Public Keys
+### Public Key Policy

-For organizational deployments with custom skill publishers:
-
-```typescript
-// Load custom public key
-const customPublicKey = fs.readFileSync('/path/to/org-public.pem', 'utf8');
-
-// Verify with custom key (not pinned ClawSec key)
-const verification = await tools.clawsec_verify_skill_package({
-  packagePath: '/tmp/org-skill.tar.gz',
-  publicKeyPath: '/path/to/org-public.pem'  // Custom key
-});
-```
-
-**Note**: The MCP tool currently uses the pinned key. Custom key support via `publicKeyPem` parameter requires host-side implementation.
+The verifier always uses the pinned ClawSec public key from this skill package.
+Runtime public-key overrides are intentionally not supported.

 ### Key Rotation

@@ -312,7 +312,7 @@ export class IntegrityMonitor {
      if (target.path) {
        // Direct path
        targets.push({
-          path: target.path,
+          path: path.resolve(target.path),
          mode: target.mode,
          priority: target.priority
        });
@@ -336,6 +336,18 @@ export class IntegrityMonitor {
    return targets;
  }

+  private normalizeBaselines(manifest: BaselinesManifest): BaselinesManifest {
+    const normalizedFiles: Record<string, FileBaseline> = {};
+    for (const [filePath, baseline] of Object.entries(manifest.files || {})) {
+      normalizedFiles[path.resolve(filePath)] = baseline;
+    }
+
+    return {
+      ...manifest,
+      files: normalizedFiles,
+    };
+  }
+
  // --------------------------------------------------------------------------
  // Baseline Management
  // --------------------------------------------------------------------------
@@ -343,7 +355,7 @@ export class IntegrityMonitor {
  private loadBaselines(): BaselinesManifest {
    if (fs.existsSync(this.baselinesPath)) {
      const raw = fs.readFileSync(this.baselinesPath, 'utf-8');
-      return JSON.parse(raw);
+      return this.normalizeBaselines(JSON.parse(raw));
    }

    return {
@@ -585,37 +597,43 @@ export class IntegrityMonitor {
      throw new Error('Baselines not loaded');
    }

-    if (!fs.existsSync(filePath)) {
-      throw new Error(`File not found: ${filePath}`);
+    const normalizedFilePath = path.resolve(filePath);
+
+    if (!fs.existsSync(normalizedFilePath)) {
+      throw new Error(`File not found: ${normalizedFilePath}`);
    }

-    refuseSymlink(filePath);
+    refuseSymlink(normalizedFilePath);

-    const previousSha = this.baselines.files[filePath]?.sha256;
-    const currentSha = sha256File(filePath);
+    const targets = this.resolveTargets();
+    const target = targets.find(t => t.path === normalizedFilePath);
+    if (!target || target.mode === 'ignore') {
+      throw new Error(`File ${normalizedFilePath} not in policy`);
+    }
+
+    const previousSha = this.baselines.files[normalizedFilePath]?.sha256;
+    const currentSha = sha256File(normalizedFilePath);

    // Generate diff
-    const snapshot = path.join(this.approvedDir, path.basename(filePath));
+    const snapshot = path.join(this.approvedDir, path.basename(normalizedFilePath));
    const oldText = fs.existsSync(snapshot) ? fs.readFileSync(snapshot, 'utf-8') : '';
-    const newText = fs.readFileSync(filePath, 'utf-8');
-    const diff = unifiedDiff(oldText, newText, `approved/${path.basename(filePath)}`, path.basename(filePath));
+    const newText = fs.readFileSync(normalizedFilePath, 'utf-8');
+    const diff = unifiedDiff(
+      oldText,
+      newText,
+      `approved/${path.basename(normalizedFilePath)}`,
+      path.basename(normalizedFilePath)
+    );

    const patchPath = path.join(
      this.patchesDir,
-      `${new Date().toISOString().replace(/[:.]/g, '-')}-approve-${safePatchTag(path.basename(filePath))}.patch`
+      `${new Date().toISOString().replace(/[:.]/g, '-')}-approve-${safePatchTag(path.basename(normalizedFilePath))}.patch`
    );
    fs.writeFileSync(patchPath, diff);

    // Update baseline
-    if (!this.baselines.files[filePath]) {
-      // Find mode from policy
-      const targets = this.resolveTargets();
-      const target = targets.find(t => t.path === filePath);
-      if (!target) {
-        throw new Error(`File ${filePath} not in policy`);
-      }
-
-      this.baselines.files[filePath] = {
+    if (!this.baselines.files[normalizedFilePath]) {
+      this.baselines.files[normalizedFilePath] = {
        sha256: currentSha,
        approved_at: utcNowIso(),
        approved_by: actor,
@@ -623,13 +641,13 @@ export class IntegrityMonitor {
        priority: target.priority
      };
    } else {
-      this.baselines.files[filePath].sha256 = currentSha;
-      this.baselines.files[filePath].approved_at = utcNowIso();
-      this.baselines.files[filePath].approved_by = actor;
+      this.baselines.files[normalizedFilePath].sha256 = currentSha;
+      this.baselines.files[normalizedFilePath].approved_at = utcNowIso();
+      this.baselines.files[normalizedFilePath].approved_by = actor;
    }

    // Update snapshot
-    fs.copyFileSync(filePath, snapshot);
+    fs.copyFileSync(normalizedFilePath, snapshot);

    // Save and audit
    this.saveBaselines();
@@ -639,7 +657,7 @@ export class IntegrityMonitor {
      event: 'approve',
      actor,
      note,
-      path: filePath,
+      path: normalizedFilePath,
      expected_sha: previousSha,
      found_sha: currentSha,
      patch_path: patchPath
@@ -656,8 +674,9 @@ export class IntegrityMonitor {
      throw new Error('Baselines not loaded');
    }

-    const files = filePath
-      ? { [filePath]: this.baselines.files[filePath] }
+    const normalizedFilePath = filePath ? path.resolve(filePath) : null;
+    const files = normalizedFilePath
+      ? { [normalizedFilePath]: this.baselines.files[normalizedFilePath] }
      : this.baselines.files;

    return {
@@ -16,6 +16,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import https from 'node:https';
 import path from 'node:path';
+import { evaluateAdvisoryRisk } from '../lib/risk.js';

 // ClawSec public key (from clawsec-signing-public.pem)
 const PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
@@ -35,6 +36,8 @@ export interface Advisory {
  action?: string;
  published?: string;
  updated?: string;
+  exploitability_score?: 'high' | 'medium' | 'low' | 'unknown' | string;
+  exploitability_rationale?: string;
  affected: string[];
 }

@@ -376,42 +379,5 @@ export function evaluateSkillSafety(advisories: Advisory[]): {
  recommendation: 'install' | 'block' | 'review';
  reason: string;
 } {
-  if (advisories.length === 0) {
-    return { safe: true, recommendation: 'install', reason: 'No advisories found' };
-  }
-
-  const hasMalicious = advisories.some((a) => a.type === 'malicious');
-  const hasRemoveAction = advisories.some((a) => a.action === 'remove');
-  const hasCritical = advisories.some((a) => a.severity === 'critical');
-  const hasHigh = advisories.some((a) => a.severity === 'high');
-
-  if (hasMalicious || hasRemoveAction) {
-    return {
-      safe: false,
-      recommendation: 'block',
-      reason: 'Malicious skill or removal recommended',
-    };
-  }
-
-  if (hasCritical) {
-    return {
-      safe: false,
-      recommendation: 'block',
-      reason: 'Critical security advisory',
-    };
-  }
-
-  if (hasHigh) {
-    return {
-      safe: false,
-      recommendation: 'review',
-      reason: 'High severity advisory - user review recommended',
-    };
-  }
-
-  return {
-    safe: false,
-    recommendation: 'review',
-    reason: 'Advisory found - review before installing',
-  };
+  return evaluateAdvisoryRisk(advisories);
 }
@@ -61,7 +61,7 @@ export async function handleAdvisoryIpc(

    case 'verify_skill_signature': {
      // Skill signature verification (Phase 1)
-      const { requestId, packagePath, signaturePath, publicKeyPem, allowUnsigned } = task;
+      const { requestId, packagePath, signaturePath } = task;

      logger.info({ sourceGroup, requestId, packagePath }, 'Verifying skill signature');

@@ -73,8 +73,6 @@ export async function handleAdvisoryIpc(
        const result = await deps.signatureVerifier.verify({
          packagePath,
          signaturePath,
-          publicKeyPem,
-          allowUnsigned: allowUnsigned || false,
        });

        await writeResponse(requestId, {
@@ -40,8 +40,81 @@ export interface VerificationResult {
 export interface VerifyParams {
  packagePath: string;
  signaturePath: string;
-  publicKeyPem?: string;      // Optional override of pinned key
-  allowUnsigned?: boolean;    // Allow missing signature (default: false)
+}
+
+const ALLOWED_PACKAGE_ROOTS = [
+  '/tmp',
+  '/var/tmp',
+  '/workspace/ipc',
+  '/workspace/project/data',
+  '/workspace/project/tmp',
+  '/workspace/project/downloads',
+] as const;
+
+const ALLOWED_PACKAGE_EXTENSIONS = ['.zip', '.tar', '.tgz', '.tar.gz'] as const;
+
+function isWithinAllowedRoots(filePath: string): boolean {
+  return ALLOWED_PACKAGE_ROOTS.some((root) => filePath === root || filePath.startsWith(`${root}/`));
+}
+
+function hasAllowedPackageExtension(filePath: string): boolean {
+  return ALLOWED_PACKAGE_EXTENSIONS.some((ext) => filePath.endsWith(ext));
+}
+
+function normalizeAndValidatePath(rawPath: string, kind: 'package' | 'signature'): string {
+  if (!path.isAbsolute(rawPath)) {
+    throw new SecurityPolicyError(`${kind} path must be absolute`);
+  }
+
+  const resolved = path.resolve(rawPath);
+  if (!isWithinAllowedRoots(resolved)) {
+    throw new SecurityPolicyError(
+      `${kind} path must be under allowed roots: ${ALLOWED_PACKAGE_ROOTS.join(', ')}`
+    );
+  }
+
+  if (kind === 'package' && !hasAllowedPackageExtension(resolved)) {
+    throw new SecurityPolicyError(
+      `package path must use one of: ${ALLOWED_PACKAGE_EXTENSIONS.join(', ')}`
+    );
+  }
+
+  if (kind === 'signature' && !resolved.endsWith('.sig')) {
+    throw new SecurityPolicyError('signature path must end with .sig');
+  }
+
+  return resolved;
+}
+
+function ensureExistingRegularFile(filePath: string, kind: 'package' | 'signature'): string {
+  if (!fs.existsSync(filePath)) {
+    throw new SecurityPolicyError(`${kind} file not found: ${filePath}`);
+  }
+
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    throw new SecurityPolicyError(`${kind} path cannot be a symlink`);
+  }
+  if (!stat.isFile()) {
+    throw new SecurityPolicyError(`${kind} path must be a regular file`);
+  }
+
+  const realPath = fs.realpathSync(filePath);
+  if (!isWithinAllowedRoots(realPath)) {
+    throw new SecurityPolicyError(`${kind} real path escapes allowed roots`);
+  }
+
+  return realPath;
+}
+
+function validatePackagePath(rawPackagePath: string): string {
+  const resolved = normalizeAndValidatePath(rawPackagePath, 'package');
+  return ensureExistingRegularFile(resolved, 'package');
+}
+
+function validateSignaturePath(rawSignaturePath: string): string {
+  const resolved = normalizeAndValidatePath(rawSignaturePath, 'signature');
+  return ensureExistingRegularFile(resolved, 'signature');
 }

 /**
@@ -68,70 +141,40 @@ export class SkillSignatureVerifier {
    const {
      packagePath,
      signaturePath,
-      publicKeyPem,
-      allowUnsigned = false
    } = params;

-    // Validate package file exists
-    if (!fs.existsSync(packagePath)) {
+    let validatedPackagePath: string;
+    let validatedSignaturePath: string;
+    try {
+      validatedPackagePath = validatePackagePath(packagePath);
+      validatedSignaturePath = validateSignaturePath(signaturePath);
+    } catch (error) {
      return {
        valid: false,
        signer: null,
        packageHash: '',
        verifiedAt: new Date().toISOString(),
        algorithm: 'Ed25519',
-        error: `Package file not found: ${packagePath}`
+        error: error instanceof Error ? error.message : String(error),
      };
    }

-    // Check signature file exists
-    if (!fs.existsSync(signaturePath)) {
-      if (allowUnsigned) {
-        // Unsigned allowed - compute hash but mark invalid
-        const packageHash = sha256File(packagePath);
-        return {
-          valid: false,
-          signer: null,
-          packageHash,
-          verifiedAt: new Date().toISOString(),
-          algorithm: 'Ed25519',
-          error: 'No signature file found (unsigned package)'
-        };
-      } else {
-        // Unsigned not allowed - fail
+    // Load pinned ClawSec key only
+    let keyPem: string;
+    try {
+      if (!fs.existsSync(this.publicKeyPath)) {
        return {
          valid: false,
          signer: null,
          packageHash: '',
          verifiedAt: new Date().toISOString(),
          algorithm: 'Ed25519',
-          error: `Signature file not found: ${signaturePath}`
+          error: `Public key file not found: ${this.publicKeyPath}`
        };
      }
-    }

-    // Load public key (either custom or pinned)
-    let keyPem: string;
-    try {
-      if (publicKeyPem) {
-        // Custom key provided - validate format
-        loadPublicKey(publicKeyPem); // Throws if invalid
-        keyPem = publicKeyPem;
-      } else {
-        // Load pinned ClawSec key
-        if (!fs.existsSync(this.publicKeyPath)) {
-          return {
-            valid: false,
-            signer: null,
-            packageHash: '',
-            verifiedAt: new Date().toISOString(),
-            algorithm: 'Ed25519',
-            error: `Public key file not found: ${this.publicKeyPath}`
-          };
-        }
-        keyPem = fs.readFileSync(this.publicKeyPath, 'utf8');
-        loadPublicKey(keyPem); // Validate pinned key
-      }
+      keyPem = fs.readFileSync(this.publicKeyPath, 'utf8');
+      loadPublicKey(keyPem); // Validate pinned key
    } catch (error) {
      if (error instanceof SecurityPolicyError) {
        return {
@@ -156,7 +199,7 @@ export class SkillSignatureVerifier {
    // Compute package hash (always, for integrity tracking)
    let packageHash: string;
    try {
-      packageHash = sha256File(packagePath);
+      packageHash = sha256File(validatedPackagePath);
    } catch (error) {
      return {
        valid: false,
@@ -170,8 +213,8 @@ export class SkillSignatureVerifier {

    // Verify signature
    const verificationResult = verifyDetachedSignatureWithDetails(
-      packagePath,
-      signaturePath,
+      validatedPackagePath,
+      validatedSignaturePath,
      keyPem
    );

@@ -121,6 +121,34 @@ export function versionMatches(version: string, versionSpec: string): boolean {
  return false;
 }

+/**
+ * Checks whether an affected specifier matches a skill name/version.
+ * Optionally matches against a skill directory name as alias.
+ */
+export function matchesAffectedSpecifier(
+  affected: string,
+  skillName: string,
+  skillVersion: string | null,
+  skillDirName?: string
+): boolean {
+  const parsed = parseAffectedSpecifier(affected);
+  if (!parsed) return false;
+
+  const normalizedTarget = normalizeSkillName(parsed.name);
+  const normalizedSkillName = normalizeSkillName(skillName);
+  const normalizedDirName = skillDirName ? normalizeSkillName(skillDirName) : null;
+
+  if (normalizedTarget !== normalizedSkillName && normalizedTarget !== normalizedDirName) {
+    return false;
+  }
+
+  if (!skillVersion) {
+    return true;
+  }
+
+  return versionMatches(skillVersion, parsed.versionSpec);
+}
+
 /**
 * Loads advisory feed from a remote URL with signature verification.
 */
@@ -269,10 +297,12 @@ export async function loadFeed(
 export function advisoryLooksHighRisk(advisory: Advisory): boolean {
  const type = advisory.type.toLowerCase();
  const severity = advisory.severity.toLowerCase();
+  const exploitability = (advisory.exploitability_score || 'unknown').toLowerCase();
  const combined = `${advisory.title} ${advisory.description} ${advisory.action}`.toLowerCase();

-  if (type === 'malicious_skill' || type === 'malicious_plugin') return true;
+  if (type.includes('malicious')) return true;
  if (severity === 'critical') return true;
+  if (exploitability === 'high') return true;
  if (/\b(malicious|exfiltrate|exfiltration|backdoor|trojan|stealer|credential theft)\b/.test(combined)) return true;
  if (/\b(remove|uninstall|disable|do not use|quarantine)\b/.test(combined)) return true;

@@ -294,15 +324,7 @@ export function findAdvisoryMatches(
    if (affected.length === 0) continue;

    for (const specifier of affected) {
-      const parsed = parseAffectedSpecifier(specifier);
-      if (!parsed) continue;
-
-      if (normalizeSkillName(parsed.name) !== normalizeSkillName(skillName)) {
-        continue;
-      }
-
-      // If version specified, check if it matches
-      if (version && !versionMatches(version, parsed.versionSpec)) {
+      if (!matchesAffectedSpecifier(specifier, skillName, version)) {
        continue;
      }

@@ -0,0 +1,88 @@
+/**
+ * Shared advisory risk evaluation for NanoClaw host + MCP layers.
+ */
+
+export type SkillSafetyRecommendation = 'install' | 'block' | 'review';
+
+export interface AdvisoryRiskInput {
+  severity?: string;
+  type?: string;
+  action?: string;
+  exploitability_score?: string;
+}
+
+export interface AdvisoryRiskEvaluation {
+  safe: boolean;
+  recommendation: SkillSafetyRecommendation;
+  reason: string;
+}
+
+export function normalizeExploitabilityScore(score: unknown): 'high' | 'medium' | 'low' | 'unknown' {
+  const value = String(score || '').toLowerCase().trim();
+  if (value === 'high' || value === 'medium' || value === 'low') {
+    return value;
+  }
+  return 'unknown';
+}
+
+export function evaluateAdvisoryRisk(advisories: AdvisoryRiskInput[]): AdvisoryRiskEvaluation {
+  if (advisories.length === 0) {
+    return { safe: true, recommendation: 'install', reason: 'No advisories found' };
+  }
+
+  const hasMalicious = advisories.some((a) => String(a.type || '').toLowerCase().includes('malicious'));
+  const hasRemoveAction = advisories.some((a) =>
+    /\b(remove|uninstall|disable|quarantine|block)\b/i.test(String(a.action || ''))
+  );
+  const hasCritical = advisories.some((a) => String(a.severity || '').toLowerCase() === 'critical');
+  const hasHigh = advisories.some((a) => String(a.severity || '').toLowerCase() === 'high');
+  const hasHighExploitability = advisories.some(
+    (a) => normalizeExploitabilityScore(a.exploitability_score) === 'high'
+  );
+
+  if (hasMalicious || hasRemoveAction) {
+    return {
+      safe: false,
+      recommendation: 'block',
+      reason: 'Malicious skill or removal recommended by ClawSec',
+    };
+  }
+
+  if (hasCritical && hasHighExploitability) {
+    return {
+      safe: false,
+      recommendation: 'block',
+      reason: 'Critical advisory with high exploitability context - do not install',
+    };
+  }
+
+  if (hasCritical) {
+    return {
+      safe: false,
+      recommendation: 'block',
+      reason: 'Critical security advisory - do not install',
+    };
+  }
+
+  if (hasHighExploitability) {
+    return {
+      safe: false,
+      recommendation: 'review',
+      reason: 'High exploitability advisory - urgent user review strongly recommended',
+    };
+  }
+
+  if (hasHigh) {
+    return {
+      safe: false,
+      recommendation: 'review',
+      reason: 'High severity advisory - user review strongly recommended',
+    };
+  }
+
+  return {
+    safe: false,
+    recommendation: 'review',
+    reason: 'Advisory found - review details before installing',
+  };
+}
@@ -15,6 +15,8 @@ export interface Advisory {
  references: string[];
  cvss_score?: number;
  nvd_url?: string;
+  exploitability_score?: 'high' | 'medium' | 'low' | 'unknown';
+  exploitability_rationale?: string;
  source?: string;
  github_issue_url?: string;
  reporter?: {
@@ -222,8 +224,6 @@ export interface VerifySkillSignatureRequest {
  timestamp: string;
  packagePath: string;
  signaturePath: string;
-  publicKeyPem?: string;      // Optional: override default public key
-  allowUnsigned?: boolean;    // Optional: allow missing signature (default: false)
 }

 /**
@@ -11,6 +11,8 @@
 import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
+import { evaluateAdvisoryRisk, normalizeExploitabilityScore } from '../lib/risk.js';
+import { matchesAffectedSpecifier } from '../lib/advisories.js';

 // These variables are provided by the host environment (ipc-mcp-stdio.ts)
 // when this code is integrated into the NanoClaw container agent.
@@ -18,8 +20,10 @@ declare const server: { tool: (...args: any[]) => void };
 declare function writeIpcFile(dir: string, data: any): void;
 declare const TASKS_DIR: string;
 declare const groupFolder: string;
+const CACHE_FILE = '/workspace/project/data/clawsec-advisory-cache.json';

-// Add these helper functions to the file:
+const severityOrder: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
+const exploitabilityOrder: Record<string, number> = { high: 0, medium: 1, low: 2, unknown: 3 };

 /**
 * Discover installed skills in a directory
@@ -84,10 +88,7 @@ function findAdvisoryMatches(
      const matchedAffected: string[] = [];

      for (const affected of advisory.affected || []) {
-        const atIndex = affected.lastIndexOf('@');
-        const affectedName = atIndex > 0 ? affected.slice(0, atIndex) : affected;
-
-        if (affectedName === skill.name || affectedName === skill.dirName) {
+        if (matchesAffectedSpecifier(affected, skill.name, skill.version, skill.dirName)) {
          matchedAffected.push(affected);
        }
      }
@@ -123,10 +124,8 @@ server.tool(
    }

    // Read cache from shared mount
-    const cacheFile = '/workspace/project/data/clawsec-advisory-cache.json';
-
    try {
-      const cacheData = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      const cacheData = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
      const installRoot = args.installRoot || path.join(process.env.HOME || '~', '.claude', 'skills');

      // Discover installed skills
@@ -153,6 +152,8 @@ server.tool(
            description: m.advisory.description,
            action: m.advisory.action,
            published: m.advisory.published,
+            exploitability_score: normalizeExploitabilityScore(m.advisory.exploitability_score),
+            exploitability_rationale: m.advisory.exploitability_rationale || null,
          },
          skill: m.skill,
          matchedAffected: m.matchedAffected,
@@ -187,17 +188,13 @@ server.tool(
    skillVersion: z.string().optional().describe('Version of skill (optional, for version-specific checks)'),
  },
  async (args) => {
-    const cacheFile = '/workspace/project/data/clawsec-advisory-cache.json';
-
    try {
-      const cacheData = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      const cacheData = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));

      // Find matching advisories for this skill
      const matchingAdvisories = cacheData.feed.advisories.filter((advisory: any) =>
        advisory.affected.some((affected: string) => {
-          const atIndex = affected.lastIndexOf('@');
-          const affectedName = atIndex > 0 ? affected.slice(0, atIndex) : affected;
-          return affectedName === args.skillName;
+          return matchesAffectedSpecifier(affected, args.skillName, args.skillVersion || null);
        })
      );

@@ -215,34 +212,13 @@ server.tool(
        };
      }

-      // Evaluate severity
-      const hasMalicious = matchingAdvisories.some((a: any) => a.type === 'malicious');
-      const hasRemoveAction = matchingAdvisories.some((a: any) => a.action === 'remove');
-      const hasCritical = matchingAdvisories.some((a: any) => a.severity === 'critical');
-      const hasHigh = matchingAdvisories.some((a: any) => a.severity === 'high');
-
-      let recommendation: 'install' | 'block' | 'review';
-      let reason: string;
-
-      if (hasMalicious || hasRemoveAction) {
-        recommendation = 'block';
-        reason = 'Malicious skill or removal recommended by ClawSec';
-      } else if (hasCritical) {
-        recommendation = 'block';
-        reason = 'Critical security advisory - do not install';
-      } else if (hasHigh) {
-        recommendation = 'review';
-        reason = 'High severity advisory - user review strongly recommended';
-      } else {
-        recommendation = 'review';
-        reason = 'Advisory found - review details before installing';
-      }
+      const risk = evaluateAdvisoryRisk(matchingAdvisories);

      return {
        content: [{
          type: 'text' as const,
          text: JSON.stringify({
-            safe: false, // Always false when advisories exist
+            safe: risk.safe,
            advisories: matchingAdvisories.map((a: any) => ({
              id: a.id,
              severity: a.severity,
@@ -252,10 +228,13 @@ server.tool(
              action: a.action,
              published: a.published,
              affected: a.affected,
+              exploitability_score: normalizeExploitabilityScore(a.exploitability_score),
+              exploitability_rationale: a.exploitability_rationale || null,
            })),
-            recommendation,
-            reason,
+            recommendation: risk.recommendation,
+            reason: risk.reason,
            skillName: args.skillName,
+            skillVersion: args.skillVersion || null,
            advisoryCount: matchingAdvisories.length,
          }, null, 2),
        }],
@@ -280,18 +259,18 @@ server.tool(

 server.tool(
  'clawsec_list_advisories',
-  'List ClawSec advisories with optional filtering. Use this to browse security advisories, filter by severity/type, or search for specific affected skills.',
+  'List ClawSec advisories with optional filtering. Use this to browse security advisories, filter by severity/type/exploitability, or search for specific affected skills.',
  {
    severity: z.enum(['critical', 'high', 'medium', 'low']).optional().describe('Filter by severity level'),
-    type: z.enum(['vulnerability', 'malicious', 'deprecated']).optional().describe('Filter by advisory type'),
+    type: z.string().optional().describe('Filter by advisory type (for example: vulnerable_skill, malicious_skill, prompt_injection)'),
+    exploitabilityScore: z.enum(['high', 'medium', 'low', 'unknown']).optional()
+      .describe('Filter by exploitability score'),
    affectedSkill: z.string().optional().describe('Filter by affected skill name (partial match supported)'),
    limit: z.number().optional().describe('Maximum number of results (default: unlimited)'),
  },
  async (args) => {
-    const cacheFile = '/workspace/project/data/clawsec-advisory-cache.json';
-
    try {
-      const cacheData = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      const cacheData = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
      let advisories = [...cacheData.feed.advisories];

      // Apply filters
@@ -299,7 +278,13 @@ server.tool(
        advisories = advisories.filter((a: any) => a.severity === args.severity);
      }
      if (args.type) {
-        advisories = advisories.filter((a: any) => a.type === args.type);
+        const typeFilter = String(args.type).toLowerCase().trim();
+        advisories = advisories.filter((a: any) => String(a.type || '').toLowerCase().trim() === typeFilter);
+      }
+      if (args.exploitabilityScore) {
+        advisories = advisories.filter(
+          (a: any) => normalizeExploitabilityScore(a.exploitability_score) === args.exploitabilityScore
+        );
      }
      if (args.affectedSkill) {
        advisories = advisories.filter((a: any) =>
@@ -307,9 +292,13 @@ server.tool(
        );
      }

-      // Sort by severity (critical first) and published date (newest first)
-      const severityOrder: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
+      // Sort by exploitability first, then severity, then publish date (newest first).
      advisories.sort((a: any, b: any) => {
+        const exploitabilityDiff =
+          (exploitabilityOrder[normalizeExploitabilityScore(a.exploitability_score)] ?? 999) -
+          (exploitabilityOrder[normalizeExploitabilityScore(b.exploitability_score)] ?? 999);
+        if (exploitabilityDiff !== 0) return exploitabilityDiff;
+
        const severityDiff = (severityOrder[a.severity] || 999) - (severityOrder[b.severity] || 999);
        if (severityDiff !== 0) return severityDiff;
        return (b.published || '').localeCompare(a.published || '');
@@ -336,6 +325,8 @@ server.tool(
              action: a.action,
              published: a.published,
              affected: a.affected,
+              exploitability_score: normalizeExploitabilityScore(a.exploitability_score),
+              exploitability_rationale: a.exploitability_rationale || null,
            })),
            total: cacheData.feed.advisories.length,
            filtered: originalCount,
@@ -343,6 +334,7 @@ server.tool(
            filters: {
              severity: args.severity || null,
              type: args.type || null,
+              exploitabilityScore: args.exploitabilityScore || null,
              affectedSkill: args.affectedSkill || null,
              limit: args.limit || null,
            },
@@ -18,6 +18,55 @@ declare function writeIpcFile(dir: string, data: any): void;
 declare const TASKS_DIR: string;
 declare const groupFolder: string;

+const ALLOWED_VERIFICATION_ROOTS = [
+  '/tmp',
+  '/var/tmp',
+  '/workspace/ipc',
+  '/workspace/project/data',
+  '/workspace/project/tmp',
+  '/workspace/project/downloads',
+] as const;
+
+const ALLOWED_PACKAGE_EXTENSIONS = ['.zip', '.tar', '.tgz', '.tar.gz'] as const;
+
+function isWithinAllowedRoots(filePath: string): boolean {
+  return ALLOWED_VERIFICATION_ROOTS.some((root) => filePath === root || filePath.startsWith(`${root}/`));
+}
+
+function validatePackagePath(rawPath: string): string {
+  if (!path.isAbsolute(rawPath)) {
+    throw new Error('packagePath must be absolute');
+  }
+
+  const resolved = path.resolve(rawPath);
+  if (!isWithinAllowedRoots(resolved)) {
+    throw new Error(`packagePath must be under: ${ALLOWED_VERIFICATION_ROOTS.join(', ')}`);
+  }
+
+  if (!ALLOWED_PACKAGE_EXTENSIONS.some((ext) => resolved.endsWith(ext))) {
+    throw new Error(`packagePath must end with one of: ${ALLOWED_PACKAGE_EXTENSIONS.join(', ')}`);
+  }
+
+  return resolved;
+}
+
+function validateSignaturePath(rawPath: string): string {
+  if (!path.isAbsolute(rawPath)) {
+    throw new Error('signaturePath must be absolute');
+  }
+
+  const resolved = path.resolve(rawPath);
+  if (!isWithinAllowedRoots(resolved)) {
+    throw new Error(`signaturePath must be under: ${ALLOWED_VERIFICATION_ROOTS.join(', ')}`);
+  }
+
+  if (!resolved.endsWith('.sig')) {
+    throw new Error('signaturePath must end with .sig');
+  }
+
+  return resolved;
+}
+
 // Result waiting helper
 async function waitForResult(requestId: string, timeoutMs: number = 5000): Promise<any> {
  const resultDir = '/workspace/ipc/clawsec_results';
@@ -49,10 +98,13 @@ server.tool(
  },
  async (args: { packagePath: string; signaturePath?: string }) => {
    const requestId = `verify-signature-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    const sigPath = args.signaturePath || `${args.packagePath}.sig`;
+    let packagePath: string;
+    let sigPath: string;

-    // Validate package file exists
-    if (!fs.existsSync(args.packagePath)) {
+    try {
+      packagePath = validatePackagePath(args.packagePath);
+      sigPath = validateSignaturePath(args.signaturePath || `${packagePath}.sig`);
+    } catch (error) {
      return {
        content: [{
          type: 'text' as const,
@@ -60,7 +112,23 @@ server.tool(
            success: false,
            valid: false,
            recommendation: 'block',
-            error: `Package file not found: ${args.packagePath}`
+            error: error instanceof Error ? error.message : String(error),
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    // Validate package file exists
+    if (!fs.existsSync(packagePath)) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: false,
+            valid: false,
+            recommendation: 'block',
+            error: `Package file not found: ${packagePath}`
          }, null, 2)
        }],
        isError: true
@@ -73,7 +141,7 @@ server.tool(
      requestId,
      groupFolder,
      timestamp: new Date().toISOString(),
-      packagePath: args.packagePath,
+      packagePath,
      signaturePath: sigPath,
    });

@@ -90,7 +158,7 @@ server.tool(
              success: false,
              valid: false,
              recommendation: 'block',
-              packagePath: args.packagePath,
+              packagePath,
              signaturePath: sigPath,
              error: result.message || 'Verification failed',
              reason: result.error?.code || 'UNKNOWN_ERROR'
@@ -109,7 +177,7 @@ server.tool(
              success: true,
              valid: false,
              recommendation: 'block',
-              packagePath: args.packagePath,
+              packagePath,
              signaturePath: sigPath,
              reason: result.data?.error || 'Signature verification failed',
              packageInfo: {
@@ -128,13 +196,13 @@ server.tool(
            success: true,
            valid: true,
            recommendation: 'install',
-            packagePath: args.packagePath,
+            packagePath,
            signaturePath: sigPath,
            signer: result.data.signer,
            algorithm: result.data.algorithm,
            verifiedAt: result.data.verifiedAt,
            packageInfo: {
-              size: fs.statSync(args.packagePath).size,
+              size: fs.statSync(packagePath).size,
              sha256: result.data.packageHash
            }
          }, null, 2)
@@ -1,6 +1,6 @@
 {
  "name": "clawsec-nanoclaw",
-  "version": "0.0.1",
+  "version": "0.0.3",
  "description": "ClawSec security suite for NanoClaw - Advisory feed monitoring, MCP tools for vulnerability checking, and Ed25519 signature verification for containerized WhatsApp bot agents",
  "author": "prompt-security",
  "license": "AGPL-3.0-or-later",
@@ -27,6 +27,11 @@
        "required": true,
        "description": "NanoClaw skill documentation"
      },
+      {
+        "path": "CHANGELOG.md",
+        "required": true,
+        "description": "Version history and release notes"
+      },
      {
        "path": "INSTALL.md",
        "required": true,
@@ -62,6 +67,11 @@
        "required": true,
        "description": "TypeScript type definitions"
      },
+      {
+        "path": "lib/risk.ts",
+        "required": true,
+        "description": "Shared advisory risk evaluation logic for host and MCP tools"
+      },
      {
        "path": "advisories/feed-signing-public.pem",
        "required": true,
@@ -112,9 +122,10 @@
  "capabilities": [
    "Advisory feed monitoring from clawsec.prompt.security",
    "MCP tools for agent-initiated vulnerability scans",
+    "Exploitability-aware advisory prioritization for agent environments",
    "Pre-installation skill safety checks",
    "Ed25519 signature verification for advisory feeds",
-    "Platform-specific advisory filtering (nanoclaw vs openclaw)",
+    "Platform metadata preserved in advisory records for downstream filtering",
    "Containerized agent support with IPC communication"
  ],
  "nanoclaw": {
@@ -135,7 +146,7 @@
    },
    "integration": {
      "mcp_tools_file": "container/agent-runner/src/ipc-mcp-stdio.ts",
-      "ipc_handlers_file": "host/ipc-handler.ts",
+      "ipc_handlers_file": "src/ipc.ts",
      "cache_location": "/workspace/project/data/clawsec-advisory-cache.json"
    }
  }
@@ -0,0 +1,57 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SKILL_ROOT = path.resolve(__dirname, '..');
+
+function readSkillFile(relativePath) {
+  return fs.readFileSync(path.join(SKILL_ROOT, relativePath), 'utf8');
+}
+
+test('signature verifier enforces pinned key and path policy', () => {
+  const source = readSkillFile('host-services/skill-signature-handler.ts');
+
+  assert.ok(!source.includes('publicKeyPem?: string'), 'publicKeyPem override must be removed');
+  assert.ok(!source.includes('allowUnsigned?: boolean'), 'allowUnsigned override must be removed');
+
+  assert.ok(source.includes('const ALLOWED_PACKAGE_ROOTS'), 'must define allowed package roots');
+  assert.ok(source.includes('validatePackagePath('), 'must validate package path before hashing');
+  assert.ok(source.includes('validateSignaturePath('), 'must validate signature path before verification');
+});
+
+test('IPC advisory handler does not forward key or unsigned overrides', () => {
+  const source = readSkillFile('host-services/ipc-handlers.ts');
+
+  assert.ok(!source.includes('publicKeyPem'), 'IPC handler must not accept publicKeyPem override');
+  assert.ok(!source.includes('allowUnsigned'), 'IPC handler must not accept allowUnsigned override');
+});
+
+test('MCP signature tool validates filesystem boundaries', () => {
+  const source = readSkillFile('mcp-tools/signature-verification.ts');
+
+  assert.ok(source.includes('const ALLOWED_VERIFICATION_ROOTS'), 'must define allowed verification roots');
+  assert.ok(source.includes('validatePackagePath('), 'must validate package path in MCP layer');
+  assert.ok(source.includes('validateSignaturePath('), 'must validate signature path in MCP layer');
+});
+
+test('integrity approvals are restricted to policy targets', () => {
+  const source = readSkillFile('guardian/integrity-monitor.ts');
+
+  assert.ok(source.includes('const normalizedFilePath = path.resolve(filePath);'), 'must normalize approved path');
+  assert.ok(
+    source.includes("if (!target || target.mode === 'ignore')"),
+    'must require approved file to exist in non-ignored policy target list'
+  );
+});
+
+test('integrity targets and baselines use normalized absolute paths', () => {
+  const source = readSkillFile('guardian/integrity-monitor.ts');
+
+  assert.ok(source.includes('path: path.resolve(target.path)'), 'resolveTargets must normalize direct target paths');
+  assert.ok(source.includes('const normalizedFilePath = path.resolve(filePath);'), 'status/approval lookups must normalize file paths');
+  assert.ok(source.includes('normalizedFiles[path.resolve(filePath)] = baseline;'), 'loaded baselines must be normalized to absolute keys');
+});
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to the ClawSec Scanner will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-02-27
+
+### Added
+
+- Initial release of ClawSec Scanner skill
+- Automated vulnerability scanning for OpenClaw skill installations
+- Integration with advisory feed for real-time security alerts
+- Support for scanning skill dependencies and detecting known CVEs
+- Configurable scan policies and risk thresholds
+- Detailed vulnerability reporting with remediation guidance
@@ -0,0 +1,489 @@
+---
+name: clawsec-scanner
+version: 0.0.1
+description: Automated vulnerability scanner for agent platforms. Performs dependency scanning (npm audit, pip-audit), multi-database CVE lookup (OSV, NVD, GitHub Advisory), SAST analysis (Semgrep, Bandit), and basic DAST security testing for skill hooks.
+homepage: https://clawsec.prompt.security
+clawdis:
+  emoji: "🔍"
+  requires:
+    bins: [node, npm, python3, pip-audit, semgrep, bandit, jq, curl]
+---
+
+# ClawSec Scanner
+
+Comprehensive security scanner for agent platforms that automates vulnerability detection across multiple dimensions:
+
+- **Dependency Scanning**: Analyzes npm and Python dependencies using `npm audit` and `pip-audit` with structured JSON output parsing
+- **CVE Database Integration**: Queries OSV (primary), NVD 2.0, and GitHub Advisory Database for vulnerability enrichment
+- **SAST Analysis**: Static code analysis using Semgrep (JavaScript/TypeScript) and Bandit (Python) to detect hardcoded secrets, command injection, path traversal, and unsafe deserialization
+- **DAST Framework**: Basic dynamic analysis for skill hook security testing (input validation, timeout enforcement)
+- **Unified Reporting**: Consolidated vulnerability reports with severity classification and remediation guidance
+- **Continuous Monitoring**: OpenClaw hook integration for automated periodic scanning
+
+## Features
+
+### Multi-Engine Scanning
+
+The scanner orchestrates four complementary scan types to provide comprehensive vulnerability coverage:
+
+1. **Dependency Scanning**
+   - Executes `npm audit --json` and `pip-audit -f json` as subprocesses
+   - Parses structured output to extract CVE IDs, severity, affected versions
+   - Handles edge cases: missing package-lock.json, zero vulnerabilities, malformed JSON
+
+2. **CVE Database Queries**
+   - **OSV API** (primary): Free, no authentication, broad ecosystem support (npm, PyPI, Go, Maven)
+   - **NVD 2.0** (optional): Requires API key to avoid 6-second rate limiting
+   - **GitHub Advisory Database** (optional): GraphQL API with OAuth token
+   - Normalizes all API responses to unified `Vulnerability` schema
+
+3. **Static Analysis (SAST)**
+   - **Semgrep** for JavaScript/TypeScript: Detects security issues using `--config auto` or `--config p/security-audit`
+   - **Bandit** for Python: Leverages existing `pyproject.toml` configuration
+   - Identifies: hardcoded secrets (API keys, tokens), command injection (`eval`, `exec`), path traversal, unsafe deserialization
+
+4. **Dynamic Analysis (DAST)**
+   - Test framework for skill hook security validation
+   - Verifies: malicious input handling, timeout enforcement, resource limits
+   - Note: Traditional web DAST tools (ZAP, Burp) do not apply to agent platforms - this provides agent-specific testing
+
+### Unified Reporting
+
+All scan types emit a consistent `ScanReport` JSON schema:
+
+```typescript
+{
+  scan_id: string;         // UUID
+  timestamp: string;       // ISO 8601
+  target: string;          // Scanned path
+  vulnerabilities: Vulnerability[];
+  summary: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+  }
+}
+```
+
+Each `Vulnerability` object includes:
+- `id`: CVE-2023-12345 or GHSA-xxxx-yyyy-zzzz
+- `source`: npm-audit | pip-audit | osv | nvd | github | sast | dast
+- `severity`: critical | high | medium | low | info
+- `package`: Package name (or 'N/A' for SAST/DAST)
+- `version`: Affected version
+- `fixed_version`: First version with fix (if available)
+- `title`: Short description
+- `description`: Full advisory text
+- `references`: URLs for more info
+- `discovered_at`: ISO 8601 timestamp
+
+### OpenClaw Integration
+
+Automated continuous monitoring via hook:
+
+- Runs scanner on configurable interval (default: 86400s / 24 hours)
+- Triggers on `agent:bootstrap` and `command:new` events
+- Posts findings to `event.messages` array with severity summary
+- Rate-limited by `CLAWSEC_SCANNER_INTERVAL` environment variable
+
+## Installation
+
+### Prerequisites
+
+Verify required binaries are available:
+
+```bash
+# Core runtimes
+node --version  # v20+
+npm --version
+python3 --version  # 3.10+
+
+# Scanning tools
+pip-audit --version  # Install: uv pip install pip-audit
+semgrep --version    # Install: pip install semgrep OR brew install semgrep
+bandit --version     # Install: uv pip install bandit
+
+# Utilities
+jq --version
+curl --version
+```
+
+### Option A: Via clawhub (recommended)
+
+```bash
+npx clawhub@latest install clawsec-scanner
+```
+
+### Option B: Manual installation with verification
+
+```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
+
+# Pinned release-signing public key
+# Fingerprint (SHA-256 of SPKI DER): 711424e4535f84093fefb024cd1ca4ec87439e53907b305b79a631d5befba9c8
+cat > "$TEMP_DIR/release-signing-public.pem" <<'PEM'
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAS7nijfMcUoOBCj4yOXJX+GYGv2pFl2Yaha1P4v5Cm6A=
+-----END PUBLIC KEY-----
+PEM
+
+ZIP_NAME="clawsec-scanner-v${VERSION}.zip"
+
+# Download release archive + signed checksums
+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"
+
+# Verify checksums manifest signature
+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_SHA="$(jq -r '.archive.sha256 // empty' "$TEMP_DIR/checksums.json")"
+if [ -z "$EXPECTED_SHA" ]; then
+  echo "ERROR: checksums.json missing archive.sha256" >&2
+  exit 1
+fi
+
+ACTUAL_SHA="$(shasum -a 256 "$TEMP_DIR/$ZIP_NAME" | awk '{print $1}')"
+if [ "$EXPECTED_SHA" != "$ACTUAL_SHA" ]; then
+  echo "ERROR: Archive checksum mismatch" >&2
+  exit 1
+fi
+
+echo "Checksums verified. Installing..."
+
+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-scanner v${VERSION} to: $DEST"
+echo "Next step: Run a scan or set up continuous monitoring"
+```
+
+## Usage
+
+### On-Demand CLI Scanning
+
+```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
+```
+
+**CLI Flags:**
+- `--target <path>`: Directory to scan (required)
+- `--output <file>`: Write results to file (optional, defaults to stdout)
+- `--format <json|text>`: Output format (default: json)
+- `--check`: Verify all required binaries are installed
+
+### OpenClaw Hook Setup (Continuous Monitoring)
+
+Enable automated periodic scanning:
+
+```bash
+SCANNER_DIR="${INSTALL_ROOT:-$HOME/.openclaw/skills}/clawsec-scanner"
+node "$SCANNER_DIR/scripts/setup_scanner_hook.mjs"
+```
+
+This creates a hook that:
+- Scans on `agent:bootstrap` and `command:new` events
+- Respects `CLAWSEC_SCANNER_INTERVAL` rate limiting (default: 86400 seconds / 24 hours)
+- Posts findings to conversation with severity summary
+- Recommends remediation for high/critical vulnerabilities
+
+Restart the OpenClaw gateway after enabling the hook, then run `/new` to trigger an immediate scan.
+
+### Environment Variables
+
+```bash
+# Optional - NVD API key to avoid rate limiting (6-second delays without key)
+export CLAWSEC_NVD_API_KEY="your-nvd-api-key"
+
+# Optional - GitHub OAuth token for Advisory Database queries
+export GITHUB_TOKEN="ghp_your_token_here"
+
+# Optional - Scanner hook interval in seconds (default: 86400 / 24 hours)
+export CLAWSEC_SCANNER_INTERVAL="86400"
+
+# Optional - Allow unsigned advisory feed during development (from clawsec-suite)
+export CLAWSEC_ALLOW_UNSIGNED_FEED="1"
+```
+
+## Architecture
+
+### Modular Design
+
+Each scan type is an independent module that can run standalone or as part of unified scan:
+
+```
+scripts/runner.sh              # Orchestration layer
+├── scan_dependencies.mjs      # npm audit + pip-audit
+├── query_cve_databases.mjs    # OSV/NVD/GitHub API queries
+├── sast_analyzer.mjs          # Semgrep + Bandit static analysis
+└── dast_runner.mjs            # Dynamic security testing
+
+lib/
+├── report.mjs                 # Result aggregation and formatting
+├── utils.mjs                  # Subprocess exec, JSON parsing, error handling
+└── types.ts                   # TypeScript schema definitions
+
+hooks/clawsec-scanner-hook/
+├── HOOK.md                    # OpenClaw hook metadata
+└── handler.ts                 # Periodic scan trigger
+```
+
+### Fail-Open Philosophy
+
+The scanner prioritizes availability over strict failure propagation:
+
+- Network failures → emit partial results, log warnings
+- Missing tools → skip that scan type, continue with others
+- Malformed JSON → parse what's valid, log errors
+- API rate limits → implement exponential backoff, fallback to other sources
+- Zero vulnerabilities → emit success report with empty array
+
+**Critical failures** that exit immediately:
+- Target path does not exist
+- No scanning tools available (all bins missing)
+- Concurrent scan detected (lockfile present)
+
+### Subprocess Execution Pattern
+
+All external tools run as subprocesses with structured JSON output:
+
+```javascript
+import { spawn } from 'node:child_process';
+
+// Example: npm audit execution
+const proc = spawn('npm', ['audit', '--json'], {
+  cwd: targetPath,
+  stdio: ['ignore', 'pipe', 'pipe']
+});
+
+// Handle non-zero exit codes gracefully
+// npm audit exits 1 when vulnerabilities found (not an error!)
+proc.on('close', code => {
+  if (code !== 0 && stderr.includes('ERR!')) {
+    // Actual error
+    reject(new Error(stderr));
+  } else {
+    // Vulnerabilities found or success
+    resolve(JSON.parse(stdout));
+  }
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"Missing package-lock.json" warning**
+- `npm audit` requires lockfile to run
+- Run `npm install` in target directory to generate
+- Scanner continues with other scan types if npm audit fails
+
+**"NVD API rate limit exceeded"**
+- Set `CLAWSEC_NVD_API_KEY` environment variable
+- Without API key: 6-second delays enforced between requests
+- OSV API used as primary source (no rate limits)
+
+**"pip-audit not found"**
+- Install: `uv pip install pip-audit` or `pip install pip-audit`
+- Verify: `which pip-audit`
+- Add to PATH if installed in non-standard location
+
+**"Semgrep binary missing"**
+- Install: `pip install semgrep` OR `brew install semgrep`
+- Requires Python 3.8+ runtime
+- Alternative: use Docker image `returntocorp/semgrep`
+
+**"Concurrent scan detected"**
+- Lockfile exists: `/tmp/clawsec-scanner.lock`
+- Wait for running scan to complete or manually remove lockfile
+- Prevents overlapping scans that could produce inconsistent results
+
+### Verification
+
+Check scanner is working correctly:
+
+```bash
+# Verify required binaries
+./scripts/runner.sh --check
+
+# Run unit tests
+node test/dependency_scanner.test.mjs
+node test/cve_integration.test.mjs
+node test/sast_engine.test.mjs
+
+# Validate skill structure
+python ../../utils/validate_skill.py .
+
+# Scan test fixtures (should detect known vulnerabilities)
+./scripts/runner.sh --target test/fixtures/ --format text
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests (vanilla Node.js, no framework)
+for test in test/*.test.mjs; do
+  node "$test" || exit 1
+done
+
+# Individual test suites
+node test/dependency_scanner.test.mjs  # Dependency scanning
+node test/cve_integration.test.mjs     # CVE database APIs
+node test/sast_engine.test.mjs         # Static analysis
+```
+
+### Linting
+
+```bash
+# JavaScript/TypeScript
+npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
+
+# Python (Bandit already configured in pyproject.toml)
+ruff check .
+bandit -r . -ll
+
+# Shell scripts
+shellcheck scripts/*.sh
+```
+
+### Adding Custom Semgrep Rules
+
+Create custom rules in `.semgrep/rules/`:
+
+```yaml
+rules:
+  - id: custom-security-rule
+    pattern: dangerous_function($ARG)
+    message: Avoid dangerous_function - use safe_alternative instead
+    severity: WARNING
+    languages: [javascript, typescript]
+```
+
+Update `scripts/sast_analyzer.mjs` to include custom rules:
+
+```javascript
+const proc = spawn('semgrep', [
+  'scan',
+  '--config', 'auto',
+  '--config', '.semgrep/rules/',  // Add custom rules
+  '--json',
+  targetPath
+]);
+```
+
+## Integration with ClawSec Suite
+
+The scanner works standalone or as part of the ClawSec ecosystem:
+
+- **clawsec-suite**: Meta-skill that can install and manage clawsec-scanner
+- **clawsec-feed**: Advisory feed for malicious skill detection (complementary)
+- **openclaw-audit-watchdog**: Cron-based audit automation (similar pattern)
+
+Install the full ClawSec suite:
+
+```bash
+npx clawhub@latest install clawsec-suite
+# Then use clawsec-suite to discover and install clawsec-scanner
+```
+
+## Security Considerations
+
+### Scanner Security
+
+- No hardcoded secrets in scanner code
+- API keys read from environment variables only (never logged or committed)
+- Subprocess arguments use arrays to prevent shell injection
+- All external tool output parsed with try/catch error handling
+
+### Vulnerability Prioritization
+
+**Critical/High severity findings** should be addressed immediately:
+- Known exploits in dependencies (CVSS 9.0+)
+- Hardcoded API keys or credentials in code
+- Command injection vulnerabilities
+- Path traversal without validation
+
+**Medium/Low severity findings** can be addressed in normal sprint cycles:
+- Outdated dependencies without known exploits
+- Missing security headers
+- Weak cryptography usage
+
+**Info findings** are advisory only:
+- Deprecated API usage
+- Code quality issues flagged by linters
+
+## Roadmap
+
+### v0.1.0 (Current)
+- [x] Dependency scanning (npm audit, pip-audit)
+- [x] CVE database integration (OSV, NVD, GitHub Advisory)
+- [x] SAST analysis (Semgrep, Bandit)
+- [x] Basic DAST framework for skill hooks
+- [x] Unified JSON reporting
+- [x] OpenClaw hook integration
+
+### Future Enhancements
+- [ ] Automatic remediation (dependency upgrades, code fixes)
+- [ ] SARIF output format for GitHub Code Scanning integration
+- [ ] Web dashboard for vulnerability tracking over time
+- [ ] CI/CD GitHub Action for PR blocking on high-severity findings
+- [ ] Container image scanning (Docker, OCI)
+- [ ] Infrastructure-as-Code scanning (Terraform, CloudFormation)
+- [ ] Comprehensive agent workflow DAST (requires deeper platform integration)
+
+## Contributing
+
+Found a security issue? Please report privately to security@prompt.security.
+
+For feature requests and bug reports, open an issue at:
+https://github.com/prompt-security/clawsec/issues
+
+## License
+
+AGPL-3.0-or-later
+
+See LICENSE file in repository root for full text.
+
+## Resources
+
+- **ClawSec Homepage**: https://clawsec.prompt.security
+- **Documentation**: https://clawsec.prompt.security/scanner
+- **GitHub Repository**: https://github.com/prompt-security/clawsec
+- **OSV API Docs**: https://osv.dev/docs/
+- **NVD API Docs**: https://nvd.nist.gov/developers/vulnerabilities
+- **Semgrep Registry**: https://semgrep.dev/explore
+- **Bandit Documentation**: https://bandit.readthedocs.io/
@@ -0,0 +1,74 @@
+---
+name: clawsec-scanner-hook
+description: Periodic vulnerability scanning for installed skills and dependencies with configurable scan intervals.
+metadata: { "openclaw": { "events": ["agent:bootstrap", "command:new"] } }
+---
+
+# ClawSec Scanner Hook
+
+This hook performs comprehensive vulnerability scanning on installed skills and their dependencies on:
+
+- `agent:bootstrap`
+- `command:new`
+
+When triggered, it runs all configured scanning engines (dependency scan, SAST, DAST, CVE database lookup) and posts findings as conversation messages. Scans are rate-limited by configurable interval to avoid performance impact.
+
+## Scanning Capabilities
+
+The hook orchestrates four independent scanning engines:
+
+1. **Dependency Scanning**: Executes `npm audit` and `pip-audit` to detect known vulnerabilities in JavaScript and Python dependencies
+2. **SAST (Static Analysis)**: Runs Semgrep (JS/TS) and Bandit (Python) to detect security issues like hardcoded secrets, command injection, and path traversal
+3. **CVE Database Lookup**: Queries OSV API (primary), NVD 2.0 (optional), and GitHub Advisory Database (optional) for vulnerability enrichment
+4. **DAST (Dynamic Analysis)**: Tests skill hook security including input validation, timeout enforcement, and resource limits
+
+## Safety Contract
+
+- The hook does not modify or delete skills.
+- It only reports findings and provides remediation guidance.
+- Scanning is non-blocking and runs on a configurable interval (default 24 hours).
+- Failed scans (network errors, missing tools) produce warnings but do not block execution.
+- Findings are deduplicated to avoid alert fatigue.
+
+## Optional Environment Variables
+
+### Core Configuration
+
+- `CLAWSEC_SCANNER_INTERVAL`: Minimum interval between hook scans in seconds (default `86400` / 24 hours).
+- `CLAWSEC_SCANNER_TARGET`: Override default scan target path (default: installed skills root).
+- `CLAWSEC_SCANNER_STATE_FILE`: Override state file path for deduplication (default `~/.openclaw/clawsec-scanner-state.json`).
+- `CLAWSEC_INSTALL_ROOT`: Override installed skills root directory.
+
+### CVE Database Integration
+
+- `CLAWSEC_NVD_API_KEY`: NVD API key for rate-limit-free access (without this, 6-second delays apply).
+- `GITHUB_TOKEN`: GitHub OAuth token for GitHub Advisory Database queries (optional enhancement).
+
+### Selective Scanning
+
+- `CLAWSEC_SKIP_DEPENDENCY_SCAN`: Set to `1` to disable dependency scanning (npm audit, pip-audit).
+- `CLAWSEC_SKIP_SAST`: Set to `1` to disable static analysis (Semgrep, Bandit).
+- `CLAWSEC_SKIP_DAST`: Set to `1` to disable dynamic analysis (hook security tests).
+- `CLAWSEC_SKIP_CVE_LOOKUP`: Set to `1` to disable CVE database enrichment.
+
+### Advanced Options
+
+- `CLAWSEC_SCANNER_TIMEOUT`: Maximum scan duration in seconds before timeout (default `300` / 5 minutes).
+- `CLAWSEC_SCANNER_FORMAT`: Output format for findings (`json` or `text`, default `text`).
+- `CLAWSEC_SCANNER_MIN_SEVERITY`: Minimum severity to report (`critical`, `high`, `medium`, `low`, `info`, default `medium`).
+- `CLAWSEC_SCANNER_OUTPUT_FILE`: Optional path to write full scan report JSON (default: conversation only).
+
+## Required Binaries
+
+The hook requires the following binaries to be available on `PATH`:
+
+- `node` (20+) - JavaScript runtime
+- `npm` - For npm audit execution
+- `python3` (3.10+) - Python runtime
+- `pip-audit` - Python dependency scanner
+- `semgrep` - JavaScript/TypeScript static analysis
+- `bandit` - Python static analysis
+- `jq` - JSON parsing and merging
+- `curl` - API requests (fallback)
+
+Missing binaries will be logged as warnings; available tools will still run.
@@ -0,0 +1,308 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execCommand, safeJsonParse } from "../../lib/utils.mjs";
+import { formatReportText } from "../../lib/report.mjs";
+import type { HookEvent, HookContext, ScanReport } from "../../lib/types.ts";
+
+const DEFAULT_SCAN_INTERVAL_SECONDS = 86400; // 24 hours
+const DEFAULT_SCANNER_TIMEOUT = 300; // 5 minutes
+const DEFAULT_MIN_SEVERITY = "medium";
+let unsignedModeWarningShown = false;
+
+interface ScannerState {
+  last_hook_scan: string | null;
+  last_full_scan: string | null;
+  known_vulnerabilities: string[];
+}
+
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function toEventName(event: HookEvent): string {
+  const eventType = String(event.type ?? "").trim();
+  const action = String(event.action ?? "").trim();
+  if (!eventType || !action) return "";
+  return `${eventType}:${action}`;
+}
+
+function shouldHandleEvent(event: HookEvent): boolean {
+  const eventName = toEventName(event);
+  return eventName === "agent:bootstrap" || eventName === "command:new";
+}
+
+function epochMs(isoTimestamp: string | null): number {
+  if (!isoTimestamp) return 0;
+  const parsed = Date.parse(isoTimestamp);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+function scannedRecently(lastScan: string | null, minIntervalSeconds: number): boolean {
+  const sinceMs = Date.now() - epochMs(lastScan);
+  return sinceMs >= 0 && sinceMs < minIntervalSeconds * 1000;
+}
+
+function configuredPath(
+  explicit: string | undefined,
+  fallback: string,
+  label: string,
+): string {
+  if (!explicit) return fallback;
+
+  const resolved = path.resolve(explicit);
+  try {
+    // Basic validation - check if path is a string
+    if (typeof resolved === "string" && resolved.length > 0) {
+      return resolved;
+    }
+  } catch (error) {
+    console.warn(
+      `[clawsec-scanner-hook] invalid ${label} path "${explicit}", using default "${fallback}": ${String(error)}`,
+    );
+  }
+
+  return fallback;
+}
+
+async function loadState(stateFile: string): Promise<ScannerState> {
+  try {
+    const content = await fs.readFile(stateFile, "utf8");
+    const parsed = safeJsonParse(content, { fallback: {}, label: "scanner state" });
+    const parsedState =
+      parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+
+    return {
+      last_hook_scan:
+        typeof parsedState.last_hook_scan === "string" ? parsedState.last_hook_scan : null,
+      last_full_scan:
+        typeof parsedState.last_full_scan === "string" ? parsedState.last_full_scan : null,
+      known_vulnerabilities: Array.isArray(parsedState.known_vulnerabilities)
+        ? parsedState.known_vulnerabilities.filter((v): v is string => typeof v === "string")
+        : [],
+    };
+  } catch {
+    // State file doesn't exist yet - return empty state
+    return {
+      last_hook_scan: null,
+      last_full_scan: null,
+      known_vulnerabilities: [],
+    };
+  }
+}
+
+async function persistState(stateFile: string, state: ScannerState): Promise<void> {
+  try {
+    const dir = path.dirname(stateFile);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(stateFile, JSON.stringify(state, null, 2), "utf8");
+  } catch (error) {
+    console.warn(`[clawsec-scanner-hook] failed to persist state: ${String(error)}`);
+  }
+}
+
+async function runScanner(
+  targetPath: string,
+  options: {
+    skipDeps: boolean;
+    skipSast: boolean;
+    skipDast: boolean;
+    skipCve: boolean;
+    timeout: number;
+  },
+): Promise<ScanReport | null> {
+  try {
+    const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), "../../scripts/runner.sh");
+
+    const args = ["--target", targetPath, "--format", "json"];
+
+    if (options.skipDeps) args.push("--skip-deps");
+    if (options.skipSast) args.push("--skip-sast");
+    if (options.skipDast) args.push("--skip-dast");
+    if (options.skipCve) args.push("--skip-cve");
+
+    const { stdout, stderr } = await execCommand("bash", [scriptPath, ...args]);
+
+    if (stderr && !stdout) {
+      console.warn(`[clawsec-scanner-hook] scanner warning: ${stderr}`);
+    }
+
+    const report = safeJsonParse(stdout, { fallback: null, label: "scanner report" });
+
+    if (!report || typeof report !== "object") {
+      console.warn("[clawsec-scanner-hook] scanner produced invalid report");
+      return null;
+    }
+
+    return report as ScanReport;
+  } catch (error) {
+    console.warn(`[clawsec-scanner-hook] scanner execution failed: ${String(error)}`);
+    return null;
+  }
+}
+
+function shouldReportSeverity(severity: string, minSeverity: string): boolean {
+  const severityOrder = ["info", "low", "medium", "high", "critical"];
+  const minIndex = severityOrder.indexOf(minSeverity.toLowerCase());
+  const vulnIndex = severityOrder.indexOf(severity.toLowerCase());
+
+  if (minIndex === -1 || vulnIndex === -1) return true;
+
+  return vulnIndex >= minIndex;
+}
+
+function deduplicateVulnerabilities(
+  report: ScanReport,
+  knownVulnIds: string[],
+): ScanReport {
+  const knownSet = new Set(knownVulnIds);
+  const newVulnerabilities = report.vulnerabilities.filter(
+    (vuln) => !knownSet.has(vuln.id),
+  );
+
+  // Recalculate summary for new vulnerabilities
+  const summary = {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    info: 0,
+  };
+
+  for (const vuln of newVulnerabilities) {
+    const severity = vuln.severity;
+    if (severity in summary) {
+      summary[severity]++;
+    }
+  }
+
+  return {
+    ...report,
+    vulnerabilities: newVulnerabilities,
+    summary,
+  };
+}
+
+function buildAlertMessage(report: ScanReport, format: string): string {
+  if (format === "json") {
+    return JSON.stringify(report, null, 2);
+  }
+
+  return formatReportText(report);
+}
+
+const handler = async (event: HookEvent, _context: HookContext): Promise<void> => {
+  if (!shouldHandleEvent(event)) return;
+
+  const installRoot = configuredPath(
+    process.env.CLAWSEC_INSTALL_ROOT || process.env.INSTALL_ROOT,
+    path.join(os.homedir(), ".openclaw", "skills"),
+    "CLAWSEC_INSTALL_ROOT",
+  );
+
+  const targetPath = configuredPath(
+    process.env.CLAWSEC_SCANNER_TARGET,
+    installRoot,
+    "CLAWSEC_SCANNER_TARGET",
+  );
+
+  const stateFile = configuredPath(
+    process.env.CLAWSEC_SCANNER_STATE_FILE,
+    path.join(os.homedir(), ".openclaw", "clawsec-scanner-state.json"),
+    "CLAWSEC_SCANNER_STATE_FILE",
+  );
+
+  const scanIntervalSeconds = parsePositiveInteger(
+    process.env.CLAWSEC_SCANNER_INTERVAL,
+    DEFAULT_SCAN_INTERVAL_SECONDS,
+  );
+
+  const scanTimeout = parsePositiveInteger(
+    process.env.CLAWSEC_SCANNER_TIMEOUT,
+    DEFAULT_SCANNER_TIMEOUT,
+  );
+
+  const minSeverity = process.env.CLAWSEC_SCANNER_MIN_SEVERITY || DEFAULT_MIN_SEVERITY;
+  const outputFormat = process.env.CLAWSEC_SCANNER_FORMAT || "text";
+  const allowUnsigned = process.env.CLAWSEC_ALLOW_UNSIGNED_FEED === "1";
+
+  const skipDeps = process.env.CLAWSEC_SKIP_DEPENDENCY_SCAN === "1";
+  const skipSast = process.env.CLAWSEC_SKIP_SAST === "1";
+  const skipDast = process.env.CLAWSEC_SKIP_DAST === "1";
+  const skipCve = process.env.CLAWSEC_SKIP_CVE_LOOKUP === "1";
+
+  if (allowUnsigned && !unsignedModeWarningShown) {
+    unsignedModeWarningShown = true;
+    console.warn(
+      "[clawsec-scanner-hook] CLAWSEC_ALLOW_UNSIGNED_FEED=1 is enabled. " +
+        "This bypass is for development only.",
+    );
+  }
+
+  const forceScan = toEventName(event) === "command:new";
+  const state = await loadState(stateFile);
+
+  if (!forceScan && scannedRecently(state.last_hook_scan, scanIntervalSeconds)) {
+    return;
+  }
+
+  const report = await runScanner(targetPath, {
+    skipDeps,
+    skipSast,
+    skipDast,
+    skipCve,
+    timeout: scanTimeout,
+  });
+
+  const nowIso = new Date().toISOString();
+  state.last_hook_scan = nowIso;
+  state.last_full_scan = nowIso;
+
+  if (!report) {
+    await persistState(stateFile, state);
+    return;
+  }
+
+  // Filter by minimum severity
+  const filteredVulns = report.vulnerabilities.filter((vuln) =>
+    shouldReportSeverity(vuln.severity, minSeverity),
+  );
+
+  // Deduplicate against known vulnerabilities
+  const dedupedReport = deduplicateVulnerabilities(
+    { ...report, vulnerabilities: filteredVulns },
+    state.known_vulnerabilities,
+  );
+
+  // Update known vulnerabilities list
+  const allVulnIds = report.vulnerabilities.map((v) => v.id).filter((id) => id.trim() !== "");
+  state.known_vulnerabilities = Array.from(new Set([...state.known_vulnerabilities, ...allVulnIds]));
+
+  await persistState(stateFile, state);
+
+  // Write optional output file
+  const outputFile = process.env.CLAWSEC_SCANNER_OUTPUT_FILE;
+  if (outputFile) {
+    try {
+      await fs.writeFile(outputFile, JSON.stringify(report, null, 2), "utf8");
+    } catch (error) {
+      console.warn(`[clawsec-scanner-hook] failed to write output file: ${String(error)}`);
+    }
+  }
+
+  // Post findings to conversation if any new vulnerabilities
+  if (dedupedReport.vulnerabilities.length > 0) {
+    const alertMessage = buildAlertMessage(dedupedReport, outputFormat);
+
+    event.messages?.push({
+      role: "system",
+      content: `🔍 ClawSec Scanner detected ${dedupedReport.vulnerabilities.length} new vulnerabilities:\n\n${alertMessage}`,
+    });
+  }
+};
+
+export default handler;
@@ -0,0 +1,251 @@
+import { generateUuid, getTimestamp } from "./utils.mjs";
+
+/**
+ * @typedef {import('./types.ts').Vulnerability} Vulnerability
+ * @typedef {import('./types.ts').ScanReport} ScanReport
+ * @typedef {import('./types.ts').SeverityLevel} SeverityLevel
+ */
+
+/**
+ * Generate a unified vulnerability report from scan results.
+ *
+ * @param {Vulnerability[]} vulnerabilities - Array of detected vulnerabilities
+ * @param {string} target - Target path that was scanned
+ * @returns {ScanReport}
+ */
+export function generateReport(vulnerabilities, target = ".") {
+  const summary = {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    info: 0,
+  };
+
+  // Count vulnerabilities by severity
+  for (const vuln of vulnerabilities) {
+    const severity = vuln.severity;
+    if (severity in summary) {
+      summary[severity]++;
+    }
+  }
+
+  return {
+    scan_id: generateUuid(),
+    timestamp: getTimestamp(),
+    target,
+    vulnerabilities,
+    summary,
+  };
+}
+
+/**
+ * Format a scan report as JSON string.
+ *
+ * @param {ScanReport} report - Scan report to format
+ * @param {boolean} pretty - Whether to pretty-print JSON
+ * @returns {string}
+ */
+export function formatReportJson(report, pretty = true) {
+  return pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
+}
+
+/**
+ * Format a scan report as human-readable text.
+ *
+ * @param {ScanReport} report - Scan report to format
+ * @returns {string}
+ */
+export function formatReportText(report) {
+  const lines = [];
+
+  // Header
+  lines.push("═══════════════════════════════════════════════════════════════");
+  lines.push("                  VULNERABILITY SCAN REPORT");
+  lines.push("═══════════════════════════════════════════════════════════════");
+  lines.push("");
+  lines.push(`Scan ID:   ${report.scan_id}`);
+  lines.push(`Timestamp: ${report.timestamp}`);
+  lines.push(`Target:    ${report.target}`);
+  lines.push("");
+
+  // Summary
+  lines.push("───────────────────────────────────────────────────────────────");
+  lines.push("SUMMARY");
+  lines.push("───────────────────────────────────────────────────────────────");
+  lines.push("");
+
+  const total = report.vulnerabilities.length;
+  const { critical, high, medium, low, info } = report.summary;
+
+  lines.push(`Total Vulnerabilities: ${total}`);
+  lines.push("");
+
+  if (critical > 0) {
+    lines.push(`  🔴 Critical: ${critical}`);
+  }
+  if (high > 0) {
+    lines.push(`  🟠 High:     ${high}`);
+  }
+  if (medium > 0) {
+    lines.push(`  🟡 Medium:   ${medium}`);
+  }
+  if (low > 0) {
+    lines.push(`  🔵 Low:      ${low}`);
+  }
+  if (info > 0) {
+    lines.push(`  ⚪ Info:     ${info}`);
+  }
+
+  if (total === 0) {
+    lines.push("  ✓ No vulnerabilities detected");
+  }
+
+  lines.push("");
+
+  // Detailed findings
+  if (report.vulnerabilities.length > 0) {
+    lines.push("───────────────────────────────────────────────────────────────");
+    lines.push("DETAILED FINDINGS");
+    lines.push("───────────────────────────────────────────────────────────────");
+    lines.push("");
+
+    // Group vulnerabilities by severity
+    const bySeverity = {
+      critical: [],
+      high: [],
+      medium: [],
+      low: [],
+      info: [],
+    };
+
+    for (const vuln of report.vulnerabilities) {
+      bySeverity[vuln.severity].push(vuln);
+    }
+
+    // Display in order: critical -> high -> medium -> low -> info
+    const severityOrder = ["critical", "high", "medium", "low", "info"];
+
+    for (const severity of severityOrder) {
+      const vulns = bySeverity[severity];
+      if (vulns.length === 0) continue;
+
+      const severityIcon = getSeverityIcon(severity);
+      lines.push(`${severityIcon} ${severity.toUpperCase()}`);
+      lines.push("");
+
+      for (const vuln of vulns) {
+        lines.push(`  ID:      ${vuln.id}`);
+        lines.push(`  Package: ${vuln.package} @ ${vuln.version}`);
+        if (vuln.fixed_version) {
+          lines.push(`  Fix:     ${vuln.fixed_version}`);
+        }
+        lines.push(`  Source:  ${vuln.source}`);
+        lines.push(`  Title:   ${vuln.title}`);
+
+        // Wrap description at 60 chars
+        const descLines = wrapText(vuln.description, 60);
+        lines.push("  Description:");
+        for (const line of descLines) {
+          lines.push(`    ${line}`);
+        }
+
+        if (vuln.references.length > 0) {
+          lines.push("  References:");
+          for (const ref of vuln.references.slice(0, 3)) {
+            lines.push(`    - ${ref}`);
+          }
+          if (vuln.references.length > 3) {
+            lines.push(`    ... and ${vuln.references.length - 3} more`);
+          }
+        }
+
+        lines.push("");
+      }
+    }
+  }
+
+  // Recommendations
+  lines.push("───────────────────────────────────────────────────────────────");
+  lines.push("RECOMMENDATIONS");
+  lines.push("───────────────────────────────────────────────────────────────");
+  lines.push("");
+
+  if (critical > 0 || high > 0) {
+    lines.push("⚠️  URGENT: Critical or high severity vulnerabilities detected!");
+    lines.push("");
+    lines.push("Recommended actions:");
+    lines.push("  1. Review all critical and high severity findings immediately");
+    lines.push("  2. Update vulnerable dependencies to fixed versions");
+    lines.push("  3. Run scanner again to verify remediation");
+    lines.push("");
+  } else if (medium > 0) {
+    lines.push("⚠️  Medium severity vulnerabilities detected.");
+    lines.push("");
+    lines.push("Recommended actions:");
+    lines.push("  1. Review findings and assess impact on your use case");
+    lines.push("  2. Plan updates during next maintenance window");
+    lines.push("");
+  } else if (low > 0 || info > 0) {
+    lines.push("✓ No critical or high severity vulnerabilities detected.");
+    lines.push("");
+    lines.push("Recommended actions:");
+    lines.push("  1. Review low/info findings for awareness");
+    lines.push("  2. Consider updates when convenient");
+    lines.push("");
+  } else {
+    lines.push("✓ No vulnerabilities detected. Your code is clean!");
+    lines.push("");
+  }
+
+  lines.push("═══════════════════════════════════════════════════════════════");
+
+  return lines.join("\n");
+}
+
+/**
+ * Get emoji icon for severity level.
+ *
+ * @param {SeverityLevel} severity - Severity level
+ * @returns {string}
+ */
+function getSeverityIcon(severity) {
+  const icons = {
+    critical: "🔴",
+    high: "🟠",
+    medium: "🟡",
+    low: "🔵",
+    info: "⚪",
+  };
+  return icons[severity] || "⚪";
+}
+
+/**
+ * Wrap text to specified width.
+ *
+ * @param {string} text - Text to wrap
+ * @param {number} width - Maximum line width
+ * @returns {string[]}
+ */
+function wrapText(text, width) {
+  const words = text.split(/\s+/);
+  const lines = [];
+  let currentLine = "";
+
+  for (const word of words) {
+    if (currentLine.length + word.length + 1 <= width) {
+      currentLine += (currentLine ? " " : "") + word;
+    } else {
+      if (currentLine) {
+        lines.push(currentLine);
+      }
+      currentLine = word;
+    }
+  }
+
+  if (currentLine) {
+    lines.push(currentLine);
+  }
+
+  return lines.length > 0 ? lines : [""];
+}
@@ -0,0 +1,45 @@
+export type VulnerabilitySource = 'npm-audit' | 'pip-audit' | 'osv' | 'nvd' | 'github' | 'sast' | 'dast';
+
+export type SeverityLevel = 'critical' | 'high' | 'medium' | 'low' | 'info';
+
+export interface Vulnerability {
+  id: string;
+  source: VulnerabilitySource;
+  severity: SeverityLevel;
+  package: string;
+  version: string;
+  fixed_version?: string;
+  title: string;
+  description: string;
+  references: string[];
+  discovered_at: string;
+}
+
+export interface ScanReport {
+  scan_id: string;
+  timestamp: string;
+  target: string;
+  vulnerabilities: Vulnerability[];
+  summary: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+  };
+}
+
+export type HookEvent = {
+  type?: string;
+  action?: string;
+  messages?: Array<{
+    role: string;
+    content: string;
+  }>;
+};
+
+export type HookContext = {
+  skillPath?: string;
+  agentPlatform?: string;
+  [key: string]: unknown;
+};
@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Execute a command as a subprocess and return its output.
+ *
+ * NOTE: npm audit exits non-zero when vulnerabilities are found.
+ * Check stderr for actual errors vs. normal vulnerability reports.
+ *
+ * @param {string} cmd - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {{env?: Record<string, string>, cwd?: string}} [options] - Execution options
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+export function execCommand(cmd, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...options.env },
+      cwd: options.cwd,
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (d) => {
+      stdout += d;
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d;
+    });
+
+    proc.on("close", (code) => {
+      // npm audit and other security tools exit non-zero when vulnerabilities found
+      // Check stderr for actual errors (ERR! pattern) vs. normal findings
+      if (code !== 0 && stderr.includes("ERR!")) {
+        reject(new Error(stderr));
+      } else {
+        resolve({ code, stdout, stderr });
+      }
+    });
+
+    proc.on("error", (error) => {
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Safely parse JSON string with error handling.
+ *
+ * @param {string} jsonString - JSON string to parse
+ * @param {{fallback?: unknown, label?: string}} [options] - Parse options
+ * @returns {unknown}
+ */
+export function safeJsonParse(jsonString, { fallback = null, label = "JSON" } = {}) {
+  const raw = String(jsonString ?? "").trim();
+  if (!raw) return fallback;
+
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.warn(`Failed to parse ${label}: ${error.message}`);
+    }
+    return fallback;
+  }
+}
+
+/**
+ * Normalize severity levels from different security tools to standard levels.
+ *
+ * @param {string} severity - Severity string from security tool
+ * @returns {'critical' | 'high' | 'medium' | 'low' | 'info'}
+ */
+export function normalizeSeverity(severity) {
+  const normalized = String(severity ?? "")
+    .trim()
+    .toLowerCase();
+
+  if (normalized.includes("critical")) return "critical";
+  if (normalized.includes("high")) return "high";
+  if (normalized.includes("moderate") || normalized.includes("medium")) return "medium";
+  if (normalized.includes("low")) return "low";
+
+  return "info";
+}
+
+/**
+ * @param {string[]} values
+ * @returns {string[]}
+ */
+export function uniqueStrings(values) {
+  return Array.from(new Set(values));
+}
+
+/**
+ * Generate a simple UUID v4.
+ *
+ * @returns {string}
+ */
+export function generateUuid() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * Get current ISO 8601 timestamp.
+ *
+ * @returns {string}
+ */
+export function getTimestamp() {
+  return new Date().toISOString();
+}
+
+/**
+ * Check if a command exists in PATH.
+ *
+ * @param {string} command - Command name to check
+ * @returns {Promise<boolean>}
+ */
+export async function commandExists(command) {
+  try {
+    const { code } = await execCommand("which", [command]);
+    return code === 0;
+  } catch {
+    return false;
+  }
+}
@@ -0,0 +1,498 @@
+#!/usr/bin/env node
+
+/**
+ * DAST (Dynamic Application Security Testing) Runner for ClawSec Scanner.
+ *
+ * v1 Scope: Basic framework for testing skill hook security
+ * - Load and execute predefined security test cases
+ * - Test hook handlers with malicious inputs
+ * - Enforce timeout limits (30s default)
+ * - Validate input sanitization and resource limits
+ *
+ * Future: Full agent workflow DAST requires deeper platform integration
+ *
+ * Run: node skills/clawsec-scanner/scripts/dast_runner.mjs --target ./skills/
+ */
+
+import { generateReport, formatReportJson, formatReportText } from "../lib/report.mjs";
+import { getTimestamp } from "../lib/utils.mjs";
+
+/**
+ * @typedef {import('../lib/types.ts').Vulnerability} Vulnerability
+ * @typedef {import('../lib/types.ts').ScanReport} ScanReport
+ * @typedef {import('../lib/types.ts').HookEvent} HookEvent
+ */
+
+/**
+ * @typedef {Object} TestCase
+ * @property {string} id - Test case identifier
+ * @property {string} name - Human-readable test name
+ * @property {string} description - Test description
+ * @property {'critical' | 'high' | 'medium' | 'low' | 'info'} severity - Severity if test fails
+ * @property {(context: TestContext) => Promise<TestResult>} execute - Test execution function
+ */
+
+/**
+ * @typedef {Object} TestContext
+ * @property {string} targetPath - Path to target skill/hook
+ * @property {number} timeout - Timeout in milliseconds
+ */
+
+/**
+ * @typedef {Object} TestResult
+ * @property {boolean} passed - Whether test passed
+ * @property {string} [message] - Result message
+ * @property {unknown} [details] - Additional details
+ */
+
+const DEFAULT_TIMEOUT_MS = 30000; // 30 seconds
+
+/**
+ * Security test cases for hook handlers.
+ * @type {TestCase[]}
+ */
+const TEST_CASES = [
+  {
+    id: "DAST-001",
+    name: "Hook Handler Malicious Input Test",
+    description: "Tests hook handler behavior with malicious message inputs (XSS, command injection patterns)",
+    severity: "high",
+    execute: async (context) => {
+      const maliciousInputs = [
+        // XSS patterns
+        "<script>alert('XSS')</script>",
+        "'; DROP TABLE users; --",
+        // Command injection patterns
+        "; rm -rf /",
+        "$(whoami)",
+        "`cat /etc/passwd`",
+        // Path traversal
+        "../../../etc/passwd",
+        "..\\..\\..\\windows\\system32\\config\\sam",
+        // Null bytes
+        "test\0malicious",
+        // Unicode exploits
+        "\u202e\u202d",
+        // Large payload (potential DoS)
+        "A".repeat(1000000),
+      ];
+
+      const vulnerabilities = [];
+
+      for (const input of maliciousInputs) {
+        try {
+          // Test: Create mock hook event with malicious content
+          const mockEvent = {
+            type: "test",
+            action: "security-test",
+            messages: [
+              {
+                role: "user",
+                content: input,
+              },
+            ],
+          };
+
+          // In a real implementation, this would invoke the actual hook handler
+          // For v1, we simulate by checking if the input would cause issues
+          const result = await testHookHandlerSafety(mockEvent, context.timeout);
+
+          if (!result.safe) {
+            vulnerabilities.push({
+              pattern: input.substring(0, 50),
+              reason: result.reason,
+            });
+          }
+        } catch (error) {
+          if (error instanceof Error) {
+            vulnerabilities.push({
+              pattern: input.substring(0, 50),
+              reason: `Exception thrown: ${error.message}`,
+            });
+          }
+        }
+      }
+
+      return {
+        passed: vulnerabilities.length === 0,
+        message:
+          vulnerabilities.length === 0
+            ? "Hook handler safely processes malicious inputs"
+            : `Hook handler vulnerable to ${vulnerabilities.length} input patterns`,
+        details: { vulnerabilities },
+      };
+    },
+  },
+  {
+    id: "DAST-002",
+    name: "Hook Handler Timeout Enforcement",
+    description: "Tests whether hook handlers respect timeout limits and prevent infinite loops",
+    severity: "medium",
+    execute: async (_context) => {
+      const startTime = Date.now();
+      const testTimeout = 5000; // 5 second test timeout
+
+      try {
+        // Simulate a long-running operation
+        const result = await Promise.race([
+          simulateLongRunningHook(),
+          new Promise((resolve) =>
+            setTimeout(() => resolve({ timedOut: true }), testTimeout),
+          ),
+        ]);
+
+        const elapsed = Date.now() - startTime;
+
+        if (result && typeof result === "object" && "timedOut" in result && result.timedOut) {
+          return {
+            passed: true,
+            message: `Timeout correctly enforced (${elapsed}ms < ${testTimeout}ms)`,
+          };
+        }
+
+        return {
+          passed: elapsed < testTimeout,
+          message:
+            elapsed < testTimeout
+              ? `Operation completed within timeout (${elapsed}ms)`
+              : `Operation exceeded timeout (${elapsed}ms > ${testTimeout}ms)`,
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          return {
+            passed: false,
+            message: `Timeout test failed: ${error.message}`,
+          };
+        }
+        return {
+          passed: false,
+          message: "Timeout test failed with unknown error",
+        };
+      }
+    },
+  },
+  {
+    id: "DAST-003",
+    name: "Hook Handler Resource Limits",
+    description: "Tests whether hook handlers respect memory and CPU resource limits",
+    severity: "medium",
+    execute: async (context) => {
+      const initialMemory = process.memoryUsage().heapUsed;
+      const maxMemoryIncreaseMB = 50; // Alert if memory increases by more than 50MB
+
+      try {
+        // Simulate resource-intensive operation
+        await simulateResourceIntensiveHook(context.timeout);
+
+        const finalMemory = process.memoryUsage().heapUsed;
+        const memoryIncreaseMB = (finalMemory - initialMemory) / 1024 / 1024;
+
+        return {
+          passed: memoryIncreaseMB < maxMemoryIncreaseMB,
+          message:
+            memoryIncreaseMB < maxMemoryIncreaseMB
+              ? `Memory usage within limits (${memoryIncreaseMB.toFixed(2)}MB increase)`
+              : `Memory usage exceeded limits (${memoryIncreaseMB.toFixed(2)}MB increase)`,
+          details: {
+            initialMemoryMB: (initialMemory / 1024 / 1024).toFixed(2),
+            finalMemoryMB: (finalMemory / 1024 / 1024).toFixed(2),
+            increaseMB: memoryIncreaseMB.toFixed(2),
+          },
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          return {
+            passed: false,
+            message: `Resource limit test failed: ${error.message}`,
+          };
+        }
+        return {
+          passed: false,
+          message: "Resource limit test failed with unknown error",
+        };
+      }
+    },
+  },
+  {
+    id: "DAST-004",
+    name: "Hook Handler Event Mutation Safety",
+    description: "Tests whether hook handlers properly mutate event.messages without side effects",
+    severity: "low",
+    execute: async (_context) => {
+      const originalEvent = {
+        type: "test",
+        action: "mutation-test",
+        messages: [{ role: "user", content: "test message" }],
+      };
+
+      // Clone for comparison
+      const originalMessagesCount = originalEvent.messages.length;
+      const originalMessageContent = originalEvent.messages[0].content;
+
+      try {
+        // Simulate hook handler mutation
+        const mockHandler = async (event) => {
+          // Proper hook pattern: mutate event.messages
+          event.messages.push({
+            role: "system",
+            content: "Hook handler response",
+          });
+          // No return value (correct pattern)
+        };
+
+        await mockHandler(originalEvent);
+
+        const messagesIncreased = originalEvent.messages.length > originalMessagesCount;
+        const originalMessageIntact =
+          originalEvent.messages[0].content === originalMessageContent;
+
+        return {
+          passed: messagesIncreased && originalMessageIntact,
+          message: messagesIncreased
+            ? "Hook correctly mutates event.messages"
+            : "Hook does not mutate event.messages",
+          details: {
+            originalCount: originalMessagesCount,
+            finalCount: originalEvent.messages.length,
+            originalIntact: originalMessageIntact,
+          },
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          return {
+            passed: false,
+            message: `Event mutation test failed: ${error.message}`,
+          };
+        }
+        return {
+          passed: false,
+          message: "Event mutation test failed with unknown error",
+        };
+      }
+    },
+  },
+];
+
+/**
+ * Test hook handler safety with malicious input.
+ * In v1, this is a simple simulation. Future versions will invoke actual handlers.
+ *
+ * @param {HookEvent} event - Mock hook event
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<{safe: boolean, reason?: string}>}
+ */
+async function testHookHandlerSafety(event, timeout) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      resolve({ safe: true, reason: "Handler completed within timeout" });
+    }, timeout);
+
+    try {
+      // v1: Basic safety checks (pattern matching)
+      const content = event.messages?.[0]?.content ?? "";
+
+      // Check for unsafe patterns
+      if (content.includes("<script>") || content.includes("</script>")) {
+        clearTimeout(timer);
+        resolve({ safe: false, reason: "Detected XSS pattern" });
+        return;
+      }
+
+      if (
+        content.includes("rm -rf") ||
+        content.includes("$(") ||
+        content.includes("`")
+      ) {
+        clearTimeout(timer);
+        resolve({ safe: false, reason: "Detected command injection pattern" });
+        return;
+      }
+
+      if (content.includes("../") || content.includes("..\\")) {
+        clearTimeout(timer);
+        resolve({ safe: false, reason: "Detected path traversal pattern" });
+        return;
+      }
+
+      if (content.includes("\0")) {
+        clearTimeout(timer);
+        resolve({ safe: false, reason: "Detected null byte injection" });
+        return;
+      }
+
+      // Check for excessive payload size
+      if (content.length > 100000) {
+        clearTimeout(timer);
+        resolve({ safe: false, reason: "Excessive payload size (potential DoS)" });
+        return;
+      }
+
+      clearTimeout(timer);
+      resolve({ safe: true });
+    } catch (error) {
+      clearTimeout(timer);
+      if (error instanceof Error) {
+        resolve({ safe: false, reason: `Exception: ${error.message}` });
+      } else {
+        resolve({ safe: false, reason: "Unknown exception" });
+      }
+    }
+  });
+}
+
+/**
+ * Simulate a long-running hook operation.
+ *
+ * @returns {Promise<{completed: boolean}>}
+ */
+async function simulateLongRunningHook() {
+  return new Promise((resolve) => {
+    // Simulate operation that would take too long
+    setTimeout(() => {
+      resolve({ completed: true });
+    }, 60000); // 60 seconds - should be timed out before this
+  });
+}
+
+/**
+ * Simulate a resource-intensive hook operation.
+ *
+ * @param {number} _timeout - Timeout in milliseconds
+ * @returns {Promise<void>}
+ */
+async function simulateResourceIntensiveHook(_timeout) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      // Simulate some memory usage (small allocation for testing)
+      const tempData = new Array(1000).fill("test data");
+      tempData.length = 0; // Clean up
+      resolve();
+    }, 100);
+  });
+}
+
+/**
+ * Execute all DAST test cases.
+ *
+ * @param {string} targetPath - Path to target skill/hook
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<Vulnerability[]>}
+ */
+async function runDastTests(targetPath, timeout) {
+  const vulnerabilities = [];
+
+  const context = {
+    targetPath,
+    timeout,
+  };
+
+  for (const testCase of TEST_CASES) {
+    try {
+      const result = await testCase.execute(context);
+
+      if (!result.passed) {
+        vulnerabilities.push({
+          id: testCase.id,
+          source: "dast",
+          severity: testCase.severity,
+          package: "N/A",
+          version: "N/A",
+          title: testCase.name,
+          description: `${testCase.description}\n\nResult: ${result.message}`,
+          references: [],
+          discovered_at: getTimestamp(),
+        });
+      }
+    } catch (error) {
+      // Test execution failure is itself a vulnerability
+      vulnerabilities.push({
+        id: testCase.id,
+        source: "dast",
+        severity: "high",
+        package: "N/A",
+        version: "N/A",
+        title: `${testCase.name} (Test Failed)`,
+        description: `Test execution failed: ${error instanceof Error ? error.message : String(error)}`,
+        references: [],
+        discovered_at: getTimestamp(),
+      });
+    }
+  }
+
+  return vulnerabilities;
+}
+
+/**
+ * CLI entry point.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  let targetPath = ".";
+  let format = "json";
+  let timeout = DEFAULT_TIMEOUT_MS;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--target" && args[i + 1]) {
+      targetPath = args[i + 1];
+      i++;
+    } else if (args[i] === "--format" && args[i + 1]) {
+      format = args[i + 1];
+      i++;
+    } else if (args[i] === "--timeout" && args[i + 1]) {
+      timeout = parseInt(args[i + 1], 10);
+      if (isNaN(timeout) || timeout <= 0) {
+        timeout = DEFAULT_TIMEOUT_MS;
+      }
+      i++;
+    } else if (args[i] === "--help") {
+      console.log(`
+Usage: dast_runner.mjs [options]
+
+Options:
+  --target <path>   Target skill/hook directory to test (default: .)
+  --format <type>   Output format: json or text (default: json)
+  --timeout <ms>    Test timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})
+  --help            Show this help message
+
+Examples:
+  node dast_runner.mjs --target ./skills/my-skill
+  node dast_runner.mjs --target ./skills/ --format text
+  node dast_runner.mjs --target ./skills/ --timeout 60000
+`);
+      process.exit(0);
+    }
+  }
+
+  try {
+    const vulnerabilities = await runDastTests(targetPath, timeout);
+    const report = generateReport(vulnerabilities, targetPath);
+
+    if (format === "text") {
+      console.log(formatReportText(report));
+    } else {
+      console.log(formatReportJson(report));
+    }
+
+    // Exit with non-zero if critical or high severity vulnerabilities found
+    const hasCriticalOrHigh =
+      report.summary.critical > 0 || report.summary.high > 0;
+    process.exit(hasCriticalOrHigh ? 1 : 0);
+  } catch (error) {
+    console.error("DAST runner failed:");
+    if (error instanceof Error) {
+      console.error(error.message);
+    } else {
+      console.error(String(error));
+    }
+    process.exit(1);
+  }
+}
+
+// Export for testing
+export { runDastTests, testHookHandlerSafety, TEST_CASES };
+
+// Run if invoked directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
@@ -0,0 +1,291 @@
+import { normalizeSeverity, getTimestamp, uniqueStrings } from '../lib/utils.mjs';
+
+/**
+ * Query OSV API for vulnerability data.
+ * OSV is the primary CVE source (free, no auth, broad ecosystem support).
+ *
+ * @param {string} packageName - Package name (e.g., 'lodash')
+ * @param {string} ecosystem - Ecosystem identifier (e.g., 'npm', 'PyPI')
+ * @param {string} [version] - Optional specific version to check
+ * @returns {Promise<import('../lib/types.ts').Vulnerability[]>}
+ */
+export async function queryOSV(packageName, ecosystem, version = undefined) {
+  const url = 'https://api.osv.dev/v1/query';
+
+  const requestBody = {
+    package: {
+      name: packageName,
+      ecosystem: ecosystem,
+    },
+  };
+
+  if (version) {
+    requestBody.version = version;
+  }
+
+  try {
+    const controller = new globalThis.AbortController();
+    const timeout = globalThis.setTimeout(() => controller.abort(), 10000);
+
+    const response = await globalThis.fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(requestBody),
+      signal: controller.signal,
+    });
+
+    globalThis.clearTimeout(timeout);
+
+    if (!response.ok) {
+      console.warn(`OSV API returned status ${response.status} for ${packageName}`);
+      return [];
+    }
+
+    const data = await response.json();
+    const vulns = data.vulns || [];
+
+    return vulns.map((vuln) => normalizeOSVVulnerability(vuln, packageName, version || '*'));
+  } catch (error) {
+    if (error instanceof Error) {
+      console.warn(`OSV API error for ${packageName}: ${error.message}`);
+    }
+    return [];
+  }
+}
+
+/**
+ * Query NVD API 2.0 for CVE data.
+ * Gated behind CLAWSEC_NVD_API_KEY environment variable.
+ * Enforces 6-second rate limiting without API key.
+ *
+ * @param {string} cveId - CVE identifier (e.g., 'CVE-2023-12345')
+ * @returns {Promise<import('../lib/types.ts').Vulnerability | null>}
+ */
+export async function queryNVD(cveId) {
+  const apiKey = process.env.CLAWSEC_NVD_API_KEY;
+  const url = `https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=${cveId}`;
+
+  const headers = {};
+  if (apiKey) {
+    headers['apiKey'] = apiKey;
+  }
+
+  try {
+    const controller = new globalThis.AbortController();
+    const timeout = globalThis.setTimeout(() => controller.abort(), 15000);
+
+    const response = await globalThis.fetch(url, {
+      method: 'GET',
+      headers,
+      signal: controller.signal,
+    });
+
+    globalThis.clearTimeout(timeout);
+
+    // Rate limiting: 6-second delay required WITHOUT API key
+    if (!apiKey) {
+      await new Promise((r) => globalThis.setTimeout(r, 6000));
+    }
+
+    if (!response.ok) {
+      console.warn(`NVD API returned status ${response.status} for ${cveId}`);
+      return null;
+    }
+
+    const data = await response.json();
+
+    if (!data.vulnerabilities || data.vulnerabilities.length === 0) {
+      return null;
+    }
+
+    const cveItem = data.vulnerabilities[0].cve;
+    return normalizeNVDVulnerability(cveItem);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.warn(`NVD API error for ${cveId}: ${error.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Query GitHub Advisory Database (optional - requires OAuth token).
+ * Currently a placeholder for future implementation.
+ *
+ * @param {string} _packageName - Package name
+ * @param {string} _ecosystem - Ecosystem (e.g., 'npm', 'pip')
+ * @returns {Promise<import('../lib/types.ts').Vulnerability[]>}
+ */
+export async function queryGitHub(_packageName, _ecosystem) {
+  const token = process.env.GITHUB_TOKEN;
+
+  if (!token) {
+    console.warn('GitHub Advisory Database query skipped: GITHUB_TOKEN not set');
+    return [];
+  }
+
+  // TODO: Implement GitHub GraphQL advisory query
+  // This requires GraphQL API integration with oauth token
+  // Placeholder for future enhancement
+  console.warn('GitHub Advisory Database integration not yet implemented');
+  return [];
+}
+
+/**
+ * Normalize OSV vulnerability data to unified schema.
+ *
+ * @param {any} osvVuln - Raw OSV vulnerability object
+ * @param {string} packageName - Package name
+ * @param {string} version - Package version
+ * @returns {import('../lib/types.ts').Vulnerability}
+ */
+function normalizeOSVVulnerability(osvVuln, packageName, version) {
+  const id = osvVuln.id || 'UNKNOWN';
+  const summary = osvVuln.summary || 'No description available';
+  const details = osvVuln.details || summary;
+
+  // Extract severity from database_specific or severity array
+  let severity = 'info';
+  if (osvVuln.severity && Array.isArray(osvVuln.severity) && osvVuln.severity.length > 0) {
+    severity = normalizeSeverity(osvVuln.severity[0].type || 'info');
+  } else if (osvVuln.database_specific && osvVuln.database_specific.severity) {
+    severity = normalizeSeverity(osvVuln.database_specific.severity);
+  }
+
+  // Extract references
+  const references = [];
+  if (Array.isArray(osvVuln.references)) {
+    references.push(...osvVuln.references.map((ref) => ref.url).filter(Boolean));
+  }
+
+  // Extract fixed version from affected ranges
+  let fixedVersion = undefined;
+  if (Array.isArray(osvVuln.affected)) {
+    for (const affected of osvVuln.affected) {
+      if (Array.isArray(affected.ranges)) {
+        for (const range of affected.ranges) {
+          if (Array.isArray(range.events)) {
+            for (const event of range.events) {
+              if (event.fixed) {
+                fixedVersion = event.fixed;
+                break;
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    id,
+    source: 'osv',
+    severity,
+    package: packageName,
+    version,
+    fixed_version: fixedVersion,
+    title: summary,
+    description: details,
+    references: uniqueStrings(references),
+    discovered_at: getTimestamp(),
+  };
+}
+
+/**
+ * Normalize NVD vulnerability data to unified schema.
+ *
+ * @param {any} nvdCve - Raw NVD CVE object
+ * @returns {import('../lib/types.ts').Vulnerability}
+ */
+function normalizeNVDVulnerability(nvdCve) {
+  const id = nvdCve.id || 'UNKNOWN';
+
+  // Extract description
+  let description = 'No description available';
+  if (nvdCve.descriptions && Array.isArray(nvdCve.descriptions)) {
+    const englishDesc = nvdCve.descriptions.find((d) => d.lang === 'en');
+    if (englishDesc && englishDesc.value) {
+      description = englishDesc.value;
+    }
+  }
+
+  // Extract severity from CVSS metrics
+  let severity = 'info';
+  if (nvdCve.metrics) {
+    // Try CVSS v3.1 first, then v3.0, then v2.0
+    const cvssV31 = nvdCve.metrics.cvssMetricV31?.[0];
+    const cvssV30 = nvdCve.metrics.cvssMetricV30?.[0];
+    const cvssV2 = nvdCve.metrics.cvssMetricV2?.[0];
+
+    const cvssData = cvssV31?.cvssData || cvssV30?.cvssData || cvssV2?.cvssData;
+    if (cvssData && cvssData.baseSeverity) {
+      severity = normalizeSeverity(cvssData.baseSeverity);
+    }
+  }
+
+  // Extract references
+  const references = [];
+  if (nvdCve.references && Array.isArray(nvdCve.references)) {
+    references.push(...nvdCve.references.map((ref) => ref.url).filter(Boolean));
+  }
+
+  return {
+    id,
+    source: 'nvd',
+    severity,
+    package: 'N/A',
+    version: '*',
+    fixed_version: undefined,
+    title: description.slice(0, 100),
+    description,
+    references: uniqueStrings(references),
+    discovered_at: getTimestamp(),
+  };
+}
+
+/**
+ * Enrich vulnerability data by querying multiple CVE databases.
+ * OSV is primary, NVD is fallback for additional details.
+ *
+ * @param {string} packageName - Package name
+ * @param {string} ecosystem - Ecosystem (e.g., 'npm', 'PyPI')
+ * @param {string} [version] - Optional version
+ * @returns {Promise<import('../lib/types.ts').Vulnerability[]>}
+ */
+export async function enrichVulnerability(packageName, ecosystem, version = undefined) {
+  const results = [];
+
+  // Query OSV first (primary source)
+  const osvResults = await queryOSV(packageName, ecosystem, version);
+  results.push(...osvResults);
+
+  // Optionally query NVD for each CVE ID found in OSV results
+  const nvdApiKey = process.env.CLAWSEC_NVD_API_KEY;
+  if (nvdApiKey && results.length > 0) {
+    for (const vuln of results) {
+      if (vuln.id.startsWith('CVE-')) {
+        const nvdData = await queryNVD(vuln.id);
+        if (nvdData) {
+          // Merge NVD references into OSV vulnerability
+          vuln.references = uniqueStrings([...vuln.references, ...nvdData.references]);
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+// CLI entry point for testing
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const packageName = args[0] || 'lodash';
+  const ecosystem = args[1] || 'npm';
+  const version = args[2];
+
+  console.log(`Querying OSV for ${packageName}@${ecosystem}${version ? ` version ${version}` : ''}...`);
+
+  const results = await queryOSV(packageName, ecosystem, version);
+  console.log(JSON.stringify(results, null, 2));
+  console.log(`\nFound ${results.length} vulnerabilities`);
+}
@@ -0,0 +1,288 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Runner for clawsec-scanner - orchestrates all vulnerability scanning engines.
+# - Runs dependency scan (npm audit + pip-audit)
+# - Enriches findings with CVE database lookups (OSV, NVD)
+# - Runs SAST analysis (Semgrep + Bandit)
+# - Runs DAST security tests (hook handler validation)
+# - Generates unified vulnerability report
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Default values
+TARGET=""
+OUTPUT=""
+FORMAT="json"
+RUN_DEPS=1
+RUN_CVE=1
+RUN_SAST=1
+RUN_DAST=1
+
+# Parse CLI arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)
+      TARGET="${2:-}"
+      shift 2
+      ;;
+    --output)
+      OUTPUT="${2:-}"
+      shift 2
+      ;;
+    --format)
+      FORMAT="${2:-json}"
+      shift 2
+      ;;
+    --skip-deps)
+      RUN_DEPS=0
+      shift
+      ;;
+    --skip-cve)
+      RUN_CVE=0
+      shift
+      ;;
+    --skip-sast)
+      RUN_SAST=0
+      shift
+      ;;
+    --skip-dast)
+      RUN_DAST=0
+      shift
+      ;;
+    --help|-h)
+      cat <<'EOF'
+Usage: runner.sh --target <path> [options]
+
+Orchestrates vulnerability scanning across dependency, SAST, DAST, and CVE engines.
+
+Required:
+  --target <path>        Target directory to scan (e.g., ./skills/)
+
+Optional:
+  --output <file>        Write report to file (default: stdout)
+  --format <json|text>   Output format (default: json)
+  --skip-deps            Skip dependency scanning (npm audit, pip-audit)
+  --skip-cve             Skip CVE database enrichment
+  --skip-sast            Skip static analysis (Semgrep, Bandit)
+  --skip-dast            Skip dynamic analysis (hook security tests)
+  --help, -h             Show this help message
+
+Examples:
+  # Scan all skills with JSON output to file
+  ./runner.sh --target ./skills/ --output report.json
+
+  # Scan with human-readable output
+  ./runner.sh --target ./skills/ --format text
+
+  # Quick scan: dependencies only
+  ./runner.sh --target ./skills/ --skip-sast --skip-dast --skip-cve
+
+Environment Variables:
+  CLAWSEC_NVD_API_KEY           Optional NVD API key (avoids rate limiting)
+  GITHUB_TOKEN                  Optional GitHub token for Advisory Database
+  CLAWSEC_SCANNER_INTERVAL      Hook scan interval in seconds (default: 86400)
+  CLAWSEC_ALLOW_UNSIGNED_FEED   Allow unsigned advisory feed (dev only)
+
+EOF
+      exit 0
+      ;;
+    *)
+      echo "Unknown flag: $1" >&2
+      echo "Run with --help for usage information" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required arguments
+if [[ -z "$TARGET" ]]; then
+  echo "Error: Missing required --target flag" >&2
+  echo "Run with --help for usage information" >&2
+  exit 1
+fi
+
+# Validate target exists
+if [[ ! -e "$TARGET" ]]; then
+  echo "Error: Target path does not exist: $TARGET" >&2
+  exit 1
+fi
+
+# Validate format
+if [[ "$FORMAT" != "json" && "$FORMAT" != "text" ]]; then
+  echo "Error: Invalid --format value. Use 'json' or 'text'." >&2
+  exit 1
+fi
+
+# Temporary files for intermediate results
+TEMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+DEPS_REPORT="$TEMP_DIR/deps.json"
+SAST_REPORT="$TEMP_DIR/sast.json"
+DAST_REPORT="$TEMP_DIR/dast.json"
+MERGED_REPORT="$TEMP_DIR/merged.json"
+
+# Run dependency scan
+if [[ "$RUN_DEPS" -eq 1 ]]; then
+  if command -v node >/dev/null 2>&1; then
+    node "$SCRIPT_DIR/scan_dependencies.mjs" --target "$TARGET" --format json > "$DEPS_REPORT" 2>/dev/null || {
+      echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$DEPS_REPORT"
+    }
+  else
+    echo "Warning: node not found, skipping dependency scan" >&2
+    echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$DEPS_REPORT"
+  fi
+else
+  echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$DEPS_REPORT"
+fi
+
+# Run SAST analysis
+if [[ "$RUN_SAST" -eq 1 ]]; then
+  if command -v node >/dev/null 2>&1; then
+    node "$SCRIPT_DIR/sast_analyzer.mjs" --target "$TARGET" --format json > "$SAST_REPORT" 2>/dev/null || {
+      echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$SAST_REPORT"
+    }
+  else
+    echo "Warning: node not found, skipping SAST analysis" >&2
+    echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$SAST_REPORT"
+  fi
+else
+  echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$SAST_REPORT"
+fi
+
+# Run DAST tests
+if [[ "$RUN_DAST" -eq 1 ]]; then
+  if command -v node >/dev/null 2>&1; then
+    if ! node "$SCRIPT_DIR/dast_runner.mjs" --target "$TARGET" --format json > "$DAST_REPORT" 2>/dev/null; then
+      # dast_runner exits non-zero when high/critical findings exist.
+      # Preserve a valid JSON report in that case; only fall back to empty on true execution errors.
+      if [[ -s "$DAST_REPORT" ]] && jq -e '.vulnerabilities and .summary' "$DAST_REPORT" >/dev/null 2>&1; then
+        echo "Warning: DAST runner exited non-zero; preserving generated findings report" >&2
+      else
+        echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$DAST_REPORT"
+      fi
+    fi
+  else
+    echo "Warning: node not found, skipping DAST tests" >&2
+    echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$DAST_REPORT"
+  fi
+else
+  echo '{"scan_id":"","timestamp":"","target":"","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}' > "$DAST_REPORT"
+fi
+
+# Merge reports using jq
+if command -v jq >/dev/null 2>&1; then
+  # Extract vulnerabilities from all reports and merge
+  jq -s '
+    {
+      scan_id: (.[0].scan_id // ""),
+      timestamp: (.[0].timestamp // (now | todate)),
+      target: (.[0].target // ""),
+      vulnerabilities: (map(.vulnerabilities // []) | flatten),
+      summary: {
+        critical: (map(.summary.critical // 0) | add),
+        high: (map(.summary.high // 0) | add),
+        medium: (map(.summary.medium // 0) | add),
+        low: (map(.summary.low // 0) | add),
+        info: (map(.summary.info // 0) | add)
+      }
+    }
+  ' "$DEPS_REPORT" "$SAST_REPORT" "$DAST_REPORT" > "$MERGED_REPORT"
+else
+  echo "Error: jq not found. Required for report merging." >&2
+  exit 1
+fi
+
+# CVE enrichment (if enabled and vulnerabilities found)
+if [[ "$RUN_CVE" -eq 1 ]]; then
+  VULN_COUNT=$(jq '.vulnerabilities | length' "$MERGED_REPORT")
+  if [[ "$VULN_COUNT" -gt 0 ]] && command -v node >/dev/null 2>&1; then
+    # Note: CVE enrichment is done inline by scan_dependencies.mjs for efficiency
+    # Future enhancement: implement post-scan enrichment for SAST/DAST findings
+    :
+  fi
+fi
+
+# Output final report
+if [[ "$FORMAT" == "json" ]]; then
+  FINAL_OUTPUT=$(cat "$MERGED_REPORT")
+elif [[ "$FORMAT" == "text" ]]; then
+  # Convert JSON to human-readable text using Node.js
+  if command -v node >/dev/null 2>&1; then
+    FINAL_OUTPUT=$(node -e "
+      const fs = require('fs');
+      const report = JSON.parse(fs.readFileSync('$MERGED_REPORT', 'utf8'));
+
+      console.log('='.repeat(80));
+      console.log('ClawSec Vulnerability Scan Report');
+      console.log('='.repeat(80));
+      console.log('');
+      console.log('Scan ID:   ' + report.scan_id);
+      console.log('Target:    ' + report.target);
+      console.log('Timestamp: ' + report.timestamp);
+      console.log('');
+      console.log('Summary:');
+      console.log('  Critical: ' + report.summary.critical);
+      console.log('  High:     ' + report.summary.high);
+      console.log('  Medium:   ' + report.summary.medium);
+      console.log('  Low:      ' + report.summary.low);
+      console.log('  Info:     ' + report.summary.info);
+      console.log('  Total:    ' + report.vulnerabilities.length);
+      console.log('');
+
+      if (report.vulnerabilities.length === 0) {
+        console.log('✓ No vulnerabilities detected');
+        console.log('');
+      } else {
+        console.log('Vulnerabilities by Severity:');
+        console.log('');
+
+        const bySeverity = {
+          critical: [],
+          high: [],
+          medium: [],
+          low: [],
+          info: []
+        };
+
+        report.vulnerabilities.forEach(v => {
+          const sev = v.severity || 'info';
+          if (bySeverity[sev]) {
+            bySeverity[sev].push(v);
+          }
+        });
+
+        ['critical', 'high', 'medium', 'low', 'info'].forEach(severity => {
+          const vulns = bySeverity[severity];
+          if (vulns.length > 0) {
+            console.log(severity.toUpperCase() + ':');
+            vulns.forEach((v, idx) => {
+              console.log('  ' + (idx + 1) + '. [' + v.source + '] ' + v.id + ' - ' + v.title);
+              console.log('     Package: ' + v.package + '@' + v.version);
+              if (v.fixed_version) {
+                console.log('     Fix: Upgrade to ' + v.fixed_version);
+              }
+              console.log('');
+            });
+          }
+        });
+      }
+
+      console.log('='.repeat(80));
+    ")
+  else
+    echo "Error: node required for text format output" >&2
+    exit 1
+  fi
+else
+  FINAL_OUTPUT=$(cat "$MERGED_REPORT")
+fi
+
+# Write output
+if [[ -n "$OUTPUT" ]]; then
+  printf '%s\n' "$FINAL_OUTPUT" > "$OUTPUT"
+else
+  printf '%s\n' "$FINAL_OUTPUT"
+fi
@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  execCommand,
+  safeJsonParse,
+  normalizeSeverity,
+  getTimestamp,
+  commandExists,
+} from "../lib/utils.mjs";
+import { generateReport, formatReportJson, formatReportText } from "../lib/report.mjs";
+
+/**
+ * @typedef {import('../lib/types.ts').Vulnerability} Vulnerability
+ * @typedef {import('../lib/types.ts').ScanReport} ScanReport
+ */
+
+/**
+ * Parse CLI arguments.
+ *
+ * @param {string[]} argv - Command line arguments
+ * @returns {{target: string, format: 'json' | 'text'}}
+ */
+function parseArgs(argv) {
+  const parsed = {
+    target: "",
+    format: "json",
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === "--target") {
+      parsed.target = String(argv[i + 1] ?? "").trim();
+      i += 1;
+      continue;
+    }
+    if (token === "--format") {
+      const formatValue = String(argv[i + 1] ?? "").trim();
+      if (formatValue !== "json" && formatValue !== "text") {
+        throw new Error("Invalid --format value. Use 'json' or 'text'.");
+      }
+      parsed.format = formatValue;
+      i += 1;
+      continue;
+    }
+    if (token === "--help" || token === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  if (!parsed.target) {
+    throw new Error("Missing required argument: --target");
+  }
+
+  return parsed;
+}
+
+/**
+ * Print usage information.
+ */
+function printUsage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  node scripts/sast_analyzer.mjs --target <path> [--format json|text]",
+      "",
+      "Examples:",
+      "  node scripts/sast_analyzer.mjs --target ./skills/clawsec-suite",
+      "  node scripts/sast_analyzer.mjs --target ./skills/ --format json",
+      "",
+      "Flags:",
+      "  --target   Path to scan (required)",
+      "  --format   Output format: json or text (default: json)",
+      "",
+    ].join("\n"),
+  );
+}
+
+/**
+ * Check if a file exists.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run Semgrep for JavaScript/TypeScript analysis.
+ *
+ * @param {string} targetPath - Path to scan
+ * @returns {Promise<Vulnerability[]>}
+ */
+async function runSemgrep(targetPath) {
+  const vulnerabilities = [];
+
+  // Check if semgrep is available
+  const hasSemgrep = await commandExists("semgrep");
+  if (!hasSemgrep) {
+    process.stderr.write("[semgrep] semgrep command not found, skipping JavaScript/TypeScript SAST\n");
+    return vulnerabilities;
+  }
+
+  try {
+    // Run Semgrep with security-focused rules
+    // NOTE: Semgrep exits non-zero when findings are present
+    const { stdout } = await execCommand("semgrep", [
+      "scan",
+      "--config", "auto",
+      "--json",
+      targetPath,
+    ]);
+
+    const semgrepData = safeJsonParse(stdout, {
+      fallback: { results: [] },
+      label: "semgrep output",
+    });
+
+    // Semgrep format: { results: [ {check_id, path, extra: {message, severity, ...}, ...} ] }
+    if (semgrepData && typeof semgrepData === "object" && "results" in semgrepData) {
+      const results = Array.isArray(semgrepData.results) ? semgrepData.results : [];
+
+      for (const result of results) {
+        if (!result || typeof result !== "object") continue;
+
+        const checkId = String(result.check_id || "semgrep-unknown");
+        const filePath = String(result.path || "unknown");
+        const extra = result.extra || {};
+
+        // Extract metadata
+        const message = String(extra.message || "Security issue detected");
+        const severity = normalizeSeverity(extra.severity || "info");
+        const metadata = extra.metadata || {};
+
+        // Build references from metadata
+        const references = [];
+        if (metadata.references && Array.isArray(metadata.references)) {
+          references.push(...metadata.references.map((r) => String(r)));
+        }
+        if (metadata.source && typeof metadata.source === "string") {
+          references.push(metadata.source);
+        }
+
+        const vuln = {
+          id: checkId,
+          source: "sast",
+          severity,
+          package: path.basename(filePath),
+          version: `${filePath}:${result.start?.line || 0}`,
+          fixed_version: "",
+          title: message.slice(0, 150),
+          description: message,
+          references,
+          discovered_at: getTimestamp(),
+        };
+
+        vulnerabilities.push(vuln);
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stderr.write(`[semgrep] Warning: ${error.message}\n`);
+    }
+    // Continue with partial results
+  }
+
+  return vulnerabilities;
+}
+
+/**
+ * Run Bandit for Python analysis.
+ *
+ * @param {string} targetPath - Path to scan
+ * @returns {Promise<Vulnerability[]>}
+ */
+async function runBandit(targetPath) {
+  const vulnerabilities = [];
+
+  // Check if bandit is available
+  const hasBandit = await commandExists("bandit");
+  if (!hasBandit) {
+    process.stderr.write("[bandit] bandit command not found, skipping Python SAST\n");
+    return vulnerabilities;
+  }
+
+  // Check if pyproject.toml exists in the project root
+  const pyprojectPath = path.join(process.cwd(), "pyproject.toml");
+  const hasPyproject = await fileExists(pyprojectPath);
+
+  try {
+    // Run Bandit with JSON output
+    // NOTE: Bandit exits non-zero when findings are present
+    const args = ["-r", targetPath, "-f", "json"];
+
+    // Only add -c flag if pyproject.toml exists
+    if (hasPyproject) {
+      args.push("-c", pyprojectPath);
+    }
+
+    const { stdout } = await execCommand("bandit", args);
+
+    const banditData = safeJsonParse(stdout, {
+      fallback: { results: [] },
+      label: "bandit output",
+    });
+
+    // Bandit format: { results: [ {issue_text, issue_severity, issue_confidence, test_id, filename, line_number, ...} ] }
+    if (banditData && typeof banditData === "object" && "results" in banditData) {
+      const results = Array.isArray(banditData.results) ? banditData.results : [];
+
+      for (const result of results) {
+        if (!result || typeof result !== "object") continue;
+
+        const testId = String(result.test_id || "bandit-unknown");
+        const filePath = String(result.filename || "unknown");
+        const lineNumber = result.line_number || 0;
+        const issueText = String(result.issue_text || "Security issue detected");
+        const issueSeverity = String(result.issue_severity || "LOW");
+
+        // Map Bandit severity (HIGH, MEDIUM, LOW) to normalized severity
+        const severity = normalizeSeverity(issueSeverity);
+
+        const vuln = {
+          id: testId,
+          source: "sast",
+          severity,
+          package: path.basename(filePath),
+          version: `${filePath}:${lineNumber}`,
+          fixed_version: "",
+          title: issueText.slice(0, 150),
+          description: issueText,
+          references: [
+            `https://bandit.readthedocs.io/en/latest/plugins/${testId.toLowerCase().replace(/_/g, '-')}.html`,
+          ],
+          discovered_at: getTimestamp(),
+        };
+
+        vulnerabilities.push(vuln);
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stderr.write(`[bandit] Warning: ${error.message}\n`);
+    }
+    // Continue with partial results
+  }
+
+  return vulnerabilities;
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+
+    // Verify target path exists
+    const targetExists = await fileExists(args.target);
+    if (!targetExists) {
+      throw new Error(`Target path does not exist: ${args.target}`);
+    }
+
+    // Run SAST tools
+    const semgrepVulns = await runSemgrep(args.target);
+    const banditVulns = await runBandit(args.target);
+
+    // Combine all vulnerabilities
+    const allVulnerabilities = [...semgrepVulns, ...banditVulns];
+
+    // Generate unified report
+    const report = generateReport(allVulnerabilities, args.target);
+
+    // Output report
+    if (args.format === "json") {
+      process.stdout.write(formatReportJson(report));
+      process.stdout.write("\n");
+    } else {
+      process.stdout.write(formatReportText(report));
+    }
+
+    // Exit 0 even if vulnerabilities found (advisory only)
+    process.exit(0);
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stderr.write(`Error: ${error.message}\n`);
+    }
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  execCommand,
+  safeJsonParse,
+  normalizeSeverity,
+  getTimestamp,
+  commandExists,
+} from "../lib/utils.mjs";
+import { generateReport, formatReportJson, formatReportText } from "../lib/report.mjs";
+
+/**
+ * @typedef {import('../lib/types.ts').Vulnerability} Vulnerability
+ * @typedef {import('../lib/types.ts').ScanReport} ScanReport
+ */
+
+/**
+ * Parse CLI arguments.
+ *
+ * @param {string[]} argv - Command line arguments
+ * @returns {{target: string, format: 'json' | 'text'}}
+ */
+function parseArgs(argv) {
+  const parsed = {
+    target: "",
+    format: "json",
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === "--target") {
+      parsed.target = String(argv[i + 1] ?? "").trim();
+      i += 1;
+      continue;
+    }
+    if (token === "--format") {
+      const formatValue = String(argv[i + 1] ?? "").trim();
+      if (formatValue !== "json" && formatValue !== "text") {
+        throw new Error("Invalid --format value. Use 'json' or 'text'.");
+      }
+      parsed.format = formatValue;
+      i += 1;
+      continue;
+    }
+    if (token === "--help" || token === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  if (!parsed.target) {
+    throw new Error("Missing required argument: --target");
+  }
+
+  return parsed;
+}
+
+/**
+ * Print usage information.
+ */
+function printUsage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  node scripts/scan_dependencies.mjs --target <path> [--format json|text]",
+      "",
+      "Examples:",
+      "  node scripts/scan_dependencies.mjs --target ./skills/clawsec-suite",
+      "  node scripts/scan_dependencies.mjs --target ./skills/ --format json",
+      "",
+      "Flags:",
+      "  --target   Path to scan (required)",
+      "  --format   Output format: json or text (default: json)",
+      "",
+    ].join("\n"),
+  );
+}
+
+/**
+ * Check if a file exists.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run npm audit and parse vulnerabilities.
+ *
+ * @param {string} targetPath - Path to scan
+ * @returns {Promise<Vulnerability[]>}
+ */
+async function scanNpmAudit(targetPath) {
+  const vulnerabilities = [];
+
+  // Check if package-lock.json exists
+  const packageLockPath = path.join(targetPath, "package-lock.json");
+  const hasPackageLock = await fileExists(packageLockPath);
+
+  if (!hasPackageLock) {
+    process.stderr.write(`[npm-audit] No package-lock.json found in ${targetPath}, skipping npm audit\n`);
+    return vulnerabilities;
+  }
+
+  // Check if npm is available
+  const hasNpm = await commandExists("npm");
+  if (!hasNpm) {
+    process.stderr.write("[npm-audit] npm command not found, skipping npm audit\n");
+    return vulnerabilities;
+  }
+
+  try {
+    // Run npm audit with JSON output
+    // NOTE: npm audit exits non-zero when vulnerabilities are found
+    const { stdout } = await execCommand("npm", ["audit", "--json"], { cwd: targetPath });
+
+    const auditData = safeJsonParse(stdout, {
+      fallback: { vulnerabilities: {} },
+      label: "npm audit output",
+    });
+
+    // npm audit v7+ format: { vulnerabilities: { [package]: {...} } }
+    if (auditData && typeof auditData === "object" && "vulnerabilities" in auditData) {
+      const vulnsMap = auditData.vulnerabilities;
+
+      if (vulnsMap && typeof vulnsMap === "object") {
+        for (const [packageName, vulnData] of Object.entries(vulnsMap)) {
+          if (!vulnData || typeof vulnData !== "object") continue;
+
+          // Extract vulnerability data
+          const severity = normalizeSeverity(vulnData.severity || "info");
+          const version = String(vulnData.range || vulnData.version || "unknown");
+          const via = Array.isArray(vulnData.via) ? vulnData.via : [];
+
+          // npm audit can have multiple advisories via the 'via' field
+          for (const viaItem of via) {
+            if (typeof viaItem === "object" && viaItem !== null) {
+              const vuln = {
+                id: String(viaItem.source || viaItem.cve || `npm-${packageName}`),
+                source: "npm-audit",
+                severity,
+                package: packageName,
+                version,
+                fixed_version: String(vulnData.fixAvailable?.version || ""),
+                title: String(viaItem.title || `Vulnerability in ${packageName}`),
+                description: String(viaItem.title || viaItem.name || "No description available"),
+                references: viaItem.url ? [String(viaItem.url)] : [],
+                discovered_at: getTimestamp(),
+              };
+
+              vulnerabilities.push(vuln);
+            }
+          }
+
+          // If 'via' doesn't have objects, create a generic entry
+          if (via.length === 0 || via.every((v) => typeof v !== "object")) {
+            const vuln = {
+              id: `npm-${packageName}`,
+              source: "npm-audit",
+              severity,
+              package: packageName,
+              version,
+              fixed_version: String(vulnData.fixAvailable?.version || ""),
+              title: `Vulnerability in ${packageName}`,
+              description: String(vulnData.name || `Vulnerability detected in ${packageName}`),
+              references: [],
+              discovered_at: getTimestamp(),
+            };
+
+            vulnerabilities.push(vuln);
+          }
+        }
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stderr.write(`[npm-audit] Warning: ${error.message}\n`);
+    }
+    // Continue with partial results
+  }
+
+  return vulnerabilities;
+}
+
+/**
+ * Run pip-audit and parse vulnerabilities.
+ *
+ * @param {string} targetPath - Path to scan
+ * @returns {Promise<Vulnerability[]>}
+ */
+async function scanPipAudit(targetPath) {
+  const vulnerabilities = [];
+
+  // Check if pip-audit is available
+  const hasPipAudit = await commandExists("pip-audit");
+  if (!hasPipAudit) {
+    process.stderr.write("[pip-audit] pip-audit command not found, skipping Python dependency scan\n");
+    return vulnerabilities;
+  }
+
+  // Check if requirements.txt or setup.py exists
+  const requirementsTxt = path.join(targetPath, "requirements.txt");
+  const setupPy = path.join(targetPath, "setup.py");
+  const pyprojectToml = path.join(targetPath, "pyproject.toml");
+
+  const hasRequirements = await fileExists(requirementsTxt);
+  const hasSetupPy = await fileExists(setupPy);
+  const hasPyprojectToml = await fileExists(pyprojectToml);
+
+  if (!hasRequirements && !hasSetupPy && !hasPyprojectToml) {
+    process.stderr.write(
+      `[pip-audit] No Python dependency files found in ${targetPath}, skipping pip-audit\n`,
+    );
+    return vulnerabilities;
+  }
+
+  try {
+    // Prefer requirements.txt when present; otherwise scan project context in target dir.
+    const pipAuditArgs = hasRequirements ? ["-f", "json", "-r", "requirements.txt"] : ["-f", "json"];
+    const { stdout } = await execCommand("pip-audit", pipAuditArgs, { cwd: targetPath });
+
+    const auditData = safeJsonParse(stdout, {
+      fallback: { dependencies: [] },
+      label: "pip-audit output",
+    });
+
+    // pip-audit format: { dependencies: [ {name, version, vulns: [{id, fix_versions, description, ...}]} ] }
+    if (auditData && typeof auditData === "object" && "dependencies" in auditData) {
+      const deps = Array.isArray(auditData.dependencies) ? auditData.dependencies : [];
+
+      for (const dep of deps) {
+        if (!dep || typeof dep !== "object") continue;
+
+        const packageName = String(dep.name || "unknown");
+        const version = String(dep.version || "unknown");
+        const vulns = Array.isArray(dep.vulns) ? dep.vulns : [];
+
+        for (const vulnData of vulns) {
+          if (!vulnData || typeof vulnData !== "object") continue;
+
+          const fixVersions = Array.isArray(vulnData.fix_versions) ? vulnData.fix_versions : [];
+          const vuln = {
+            id: String(vulnData.id || `pip-${packageName}`),
+            source: "pip-audit",
+            severity: normalizeSeverity(vulnData.severity || "info"),
+            package: packageName,
+            version,
+            fixed_version: fixVersions.length > 0 ? String(fixVersions[0]) : "",
+            title: String(vulnData.description || `Vulnerability in ${packageName}`).slice(0, 150),
+            description: String(vulnData.description || "No description available"),
+            references: vulnData.link ? [String(vulnData.link)] : [],
+            discovered_at: getTimestamp(),
+          };
+
+          vulnerabilities.push(vuln);
+        }
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stderr.write(`[pip-audit] Warning: ${error.message}\n`);
+    }
+    // Continue with partial results
+  }
+
+  return vulnerabilities;
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+
+    // Verify target path exists
+    const targetExists = await fileExists(args.target);
+    if (!targetExists) {
+      throw new Error(`Target path does not exist: ${args.target}`);
+    }
+
+    // Run dependency scanners
+    const npmVulns = await scanNpmAudit(args.target);
+    const pipVulns = await scanPipAudit(args.target);
+
+    // Combine all vulnerabilities
+    const allVulnerabilities = [...npmVulns, ...pipVulns];
+
+    // Generate unified report
+    const report = generateReport(allVulnerabilities, args.target);
+
+    // Output report
+    if (args.format === "json") {
+      process.stdout.write(formatReportJson(report));
+      process.stdout.write("\n");
+    } else {
+      process.stdout.write(formatReportText(report));
+    }
+
+    // Exit 0 even if vulnerabilities found (advisory only)
+    process.exit(0);
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stderr.write(`Error: ${error.message}\n`);
+    }
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_NAME = "clawsec-scanner-hook";
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCANNER_DIR = path.resolve(SCRIPT_DIR, "..");
+const SOURCE_HOOK_DIR = path.join(SCANNER_DIR, "hooks", HOOK_NAME);
+const HOOKS_ROOT = path.join(os.homedir(), ".openclaw", "hooks");
+const TARGET_HOOK_DIR = path.join(HOOKS_ROOT, HOOK_NAME);
+
+function sh(cmd, args) {
+  const result = spawnSync(cmd, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const details = (result.stderr || result.stdout || "").trim();
+    throw new Error(`${cmd} ${args.join(" ")} failed${details ? `: ${details}` : ""}`);
+  }
+
+  return result.stdout;
+}
+
+function requireOpenClawCli() {
+  try {
+    sh("openclaw", ["--version"]);
+  } catch (error) {
+    throw new Error(
+      "openclaw CLI is required. Install OpenClaw and ensure `openclaw` is available in PATH. " +
+        `Original error: ${String(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+function assertSourceHookExists() {
+  const requiredFiles = [
+    "HOOK.md",
+    "handler.ts",
+  ];
+  for (const file of requiredFiles) {
+    const fullPath = path.join(SOURCE_HOOK_DIR, file);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Missing required hook file: ${fullPath}`);
+    }
+  }
+
+  // Verify lib files exist in parent skill directory
+  const requiredLibFiles = [
+    "lib/utils.mjs",
+    "lib/report.mjs",
+    "lib/types.ts",
+  ];
+  for (const file of requiredLibFiles) {
+    const fullPath = path.join(SCANNER_DIR, file);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Missing required lib file: ${fullPath}`);
+    }
+  }
+
+  // Verify scanner scripts exist
+  const requiredScripts = [
+    "scripts/runner.sh",
+    "scripts/scan_dependencies.mjs",
+    "scripts/sast_analyzer.mjs",
+    "scripts/dast_runner.mjs",
+    "scripts/query_cve_databases.mjs",
+  ];
+  for (const file of requiredScripts) {
+    const fullPath = path.join(SCANNER_DIR, file);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Missing required scanner script: ${fullPath}`);
+    }
+  }
+}
+
+function installHookFiles() {
+  fs.mkdirSync(HOOKS_ROOT, { recursive: true });
+  fs.rmSync(TARGET_HOOK_DIR, { recursive: true, force: true });
+  fs.cpSync(SOURCE_HOOK_DIR, TARGET_HOOK_DIR, { recursive: true });
+
+  // Copy lib files to hook directory
+  const targetLibDir = path.join(TARGET_HOOK_DIR, "lib");
+  const sourceLibDir = path.join(SCANNER_DIR, "lib");
+  fs.mkdirSync(targetLibDir, { recursive: true });
+  fs.cpSync(sourceLibDir, targetLibDir, { recursive: true });
+
+  // Copy scanner scripts to hook directory
+  const targetScriptsDir = path.join(TARGET_HOOK_DIR, "scripts");
+  const sourceScriptsDir = path.join(SCANNER_DIR, "scripts");
+  fs.mkdirSync(targetScriptsDir, { recursive: true });
+  fs.cpSync(sourceScriptsDir, targetScriptsDir, { recursive: true });
+}
+
+function enableHook() {
+  sh("openclaw", ["hooks", "enable", HOOK_NAME]);
+}
+
+function main() {
+  assertSourceHookExists();
+  requireOpenClawCli();
+  installHookFiles();
+  enableHook();
+
+  process.stdout.write(`Installed hook files to: ${TARGET_HOOK_DIR}\n`);
+  process.stdout.write(`Enabled hook: ${HOOK_NAME}\n`);
+  process.stdout.write("Restart your OpenClaw gateway process so the hook is loaded.\n");
+  process.stdout.write("After restart, run /new once to trigger an immediate vulnerability scan.\n");
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`${String(error)}\n`);
+  process.exit(1);
+}
@@ -0,0 +1,137 @@
+{
+  "name": "clawsec-scanner",
+  "version": "0.0.1",
+  "description": "Automated vulnerability scanner for agent platforms. Performs dependency scanning (npm audit, pip-audit), multi-database CVE lookup (OSV, NVD, GitHub Advisory), SAST analysis (Semgrep, Bandit), and basic DAST security testing for skill hooks.",
+  "author": "prompt-security",
+  "license": "AGPL-3.0-or-later",
+  "homepage": "https://clawsec.prompt.security/",
+  "keywords": [
+    "security",
+    "vulnerability",
+    "scanner",
+    "dependency",
+    "cve",
+    "sast",
+    "dast",
+    "audit",
+    "agents",
+    "ai",
+    "openclaw",
+    "semgrep",
+    "bandit",
+    "osv",
+    "nvd"
+  ],
+  "sbom": {
+    "files": [
+      {
+        "path": "SKILL.md",
+        "required": true,
+        "description": "Scanner skill documentation and usage guide"
+      },
+      {
+        "path": "CHANGELOG.md",
+        "required": true,
+        "description": "Version history and feature changelog"
+      },
+      {
+        "path": "scripts/runner.sh",
+        "required": true,
+        "description": "Main orchestration script for running all scanner engines"
+      },
+      {
+        "path": "scripts/scan_dependencies.mjs",
+        "required": true,
+        "description": "Dependency scanner using npm audit and pip-audit with JSON parsing"
+      },
+      {
+        "path": "scripts/query_cve_databases.mjs",
+        "required": true,
+        "description": "Multi-database CVE lookup (OSV primary, NVD/GitHub fallback)"
+      },
+      {
+        "path": "scripts/sast_analyzer.mjs",
+        "required": true,
+        "description": "Static analysis engine running Semgrep and Bandit as subprocesses"
+      },
+      {
+        "path": "scripts/dast_runner.mjs",
+        "required": true,
+        "description": "Dynamic analysis framework for skill hook security testing"
+      },
+      {
+        "path": "scripts/setup_scanner_hook.mjs",
+        "required": false,
+        "description": "Hook installer for continuous monitoring integration"
+      },
+      {
+        "path": "lib/report.mjs",
+        "required": true,
+        "description": "Unified vulnerability report generator (JSON and human-readable formats)"
+      },
+      {
+        "path": "lib/utils.mjs",
+        "required": true,
+        "description": "Shared utility functions for subprocess execution and JSON parsing"
+      },
+      {
+        "path": "lib/types.ts",
+        "required": true,
+        "description": "TypeScript type definitions for Vulnerability and ScanReport schemas"
+      },
+      {
+        "path": "hooks/clawsec-scanner-hook/HOOK.md",
+        "required": false,
+        "description": "OpenClaw hook metadata for continuous scanning integration"
+      },
+      {
+        "path": "hooks/clawsec-scanner-hook/handler.ts",
+        "required": false,
+        "description": "OpenClaw hook handler for periodic vulnerability scanning"
+      },
+      {
+        "path": "test/dependency_scanner.test.mjs",
+        "required": false,
+        "description": "Unit tests for dependency scanning (npm audit, pip-audit)"
+      },
+      {
+        "path": "test/cve_integration.test.mjs",
+        "required": false,
+        "description": "Integration tests for CVE database API queries"
+      },
+      {
+        "path": "test/sast_engine.test.mjs",
+        "required": false,
+        "description": "Unit tests for SAST analysis (Semgrep, Bandit)"
+      }
+    ]
+  },
+  "openclaw": {
+    "emoji": "🔍",
+    "category": "security",
+    "requires": {
+      "bins": [
+        "node",
+        "npm",
+        "python3",
+        "pip-audit",
+        "semgrep",
+        "bandit",
+        "jq",
+        "curl"
+      ]
+    },
+    "triggers": [
+      "vulnerability scan",
+      "security scan",
+      "dependency scan",
+      "cve scan",
+      "sast scan",
+      "run scanner",
+      "scan vulnerabilities",
+      "check vulnerabilities",
+      "audit dependencies",
+      "security check"
+    ]
+  }
+}
@@ -0,0 +1,571 @@
+#!/usr/bin/env node
+
+/**
+ * CVE integration tests for clawsec-scanner.
+ *
+ * Tests cover:
+ * - OSV API query and normalization
+ * - NVD API query and normalization
+ * - GitHub Advisory Database query (placeholder)
+ * - Multi-source enrichment
+ * - Error handling and timeouts
+ * - Rate limiting behavior
+ *
+ * Run: node skills/clawsec-scanner/test/cve_integration.test.mjs
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pass, fail, report, exitWithResults, withEnv } from "./lib/test_harness.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCRIPTS_PATH = path.resolve(__dirname, "..", "scripts");
+
+// Dynamic import to ensure we test the actual modules
+const { queryOSV, queryNVD, queryGitHub, enrichVulnerability } = await import(
+  `${SCRIPTS_PATH}/query_cve_databases.mjs`
+);
+
+// -----------------------------------------------------------------------------
+// Test: queryOSV - successful query with results
+// -----------------------------------------------------------------------------
+async function testQueryOSV_Success() {
+  const testName = "queryOSV: successful query returns vulnerabilities";
+  try {
+    // Query a known vulnerable package (lodash has known vulnerabilities)
+    const results = await queryOSV("lodash", "npm", "4.17.19");
+
+    // lodash 4.17.19 has known vulnerabilities
+    if (Array.isArray(results) && results.length > 0) {
+      // Verify structure of first result
+      const vuln = results[0];
+      if (
+        vuln.id &&
+        vuln.source === "osv" &&
+        vuln.severity &&
+        vuln.package === "lodash" &&
+        vuln.title &&
+        vuln.description &&
+        Array.isArray(vuln.references)
+      ) {
+        pass(testName);
+      } else {
+        fail(testName, `Invalid vulnerability structure: ${JSON.stringify(vuln)}`);
+      }
+    } else {
+      // If no results, package may have been patched - that's also valid
+      pass(testName);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryOSV - returns empty array for non-existent package
+// -----------------------------------------------------------------------------
+async function testQueryOSV_NotFound() {
+  const testName = "queryOSV: returns empty array for non-existent package";
+  try {
+    const results = await queryOSV("nonexistent-package-that-does-not-exist-12345", "npm");
+
+    if (Array.isArray(results) && results.length === 0) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected empty array, got ${results.length} results`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryOSV - handles network errors gracefully
+// -----------------------------------------------------------------------------
+async function testQueryOSV_NetworkError() {
+  const testName = "queryOSV: handles network errors gracefully";
+  try {
+    // This will likely timeout or fail, but should return empty array
+    const results = await queryOSV("test-pkg", "invalid-ecosystem-999");
+
+    if (Array.isArray(results)) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected array, got ${typeof results}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryOSV - version-specific query
+// -----------------------------------------------------------------------------
+async function testQueryOSV_WithVersion() {
+  const testName = "queryOSV: handles version-specific queries";
+  try {
+    const results = await queryOSV("express", "npm", "4.16.0");
+
+    // Express 4.16.0 may or may not have vulnerabilities
+    // Just verify it returns an array
+    if (Array.isArray(results)) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected array, got ${typeof results}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryOSV - normalizes severity correctly
+// -----------------------------------------------------------------------------
+async function testQueryOSV_SeverityNormalization() {
+  const testName = "queryOSV: normalizes severity from API response";
+  try {
+    const results = await queryOSV("lodash", "npm", "4.17.19");
+
+    if (results.length > 0) {
+      const validSeverities = ["critical", "high", "medium", "low", "info"];
+      const allValid = results.every((vuln) => validSeverities.includes(vuln.severity));
+
+      if (allValid) {
+        pass(testName);
+      } else {
+        fail(
+          testName,
+          `Invalid severity found: ${results.map((v) => v.severity).join(", ")}`,
+        );
+      }
+    } else {
+      // No results is valid
+      pass(testName);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryNVD - requires API key or respects rate limiting
+// -----------------------------------------------------------------------------
+async function testQueryNVD_RateLimiting() {
+  const testName = "queryNVD: respects rate limiting without API key";
+  try {
+    await withEnv("CLAWSEC_NVD_API_KEY", undefined, async () => {
+      const startTime = Date.now();
+
+      // Query should add 6-second delay when no API key (if request succeeds)
+      await queryNVD("CVE-2021-44228");
+
+      const elapsed = Date.now() - startTime;
+
+      // If the request failed quickly (network issue), skip the test
+      if (elapsed < 100) {
+        pass(testName + " (skipped - network unavailable)");
+      } else if (elapsed >= 5900) {
+        // Should take at least 6 seconds if successful
+        pass(testName);
+      } else {
+        fail(testName, `Expected ~6s delay, got ${elapsed}ms`);
+      }
+    });
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryNVD - handles non-existent CVE
+// -----------------------------------------------------------------------------
+async function testQueryNVD_NotFound() {
+  const testName = "queryNVD: returns null for non-existent CVE";
+  try {
+    await withEnv("CLAWSEC_NVD_API_KEY", undefined, async () => {
+      const result = await queryNVD("CVE-9999-99999");
+
+      if (result === null) {
+        pass(testName);
+      } else {
+        fail(testName, `Expected null, got ${JSON.stringify(result)}`);
+      }
+    });
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryNVD - valid CVE returns structured data
+// -----------------------------------------------------------------------------
+async function testQueryNVD_ValidCVE() {
+  const testName = "queryNVD: valid CVE returns structured vulnerability";
+  try {
+    // Only run if API key is set (to avoid rate limiting in CI)
+    const apiKey = process.env.CLAWSEC_NVD_API_KEY;
+    if (!apiKey) {
+      pass(testName + " (skipped - no API key)");
+      return;
+    }
+
+    const result = await queryNVD("CVE-2021-44228");
+
+    if (result && result.id === "CVE-2021-44228" && result.source === "nvd") {
+      pass(testName);
+    } else if (result === null) {
+      // API might be down or rate limited
+      pass(testName + " (API returned null)");
+    } else {
+      fail(testName, `Unexpected result: ${JSON.stringify(result)}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryGitHub - returns empty array when token not set
+// -----------------------------------------------------------------------------
+async function testQueryGitHub_NoToken() {
+  const testName = "queryGitHub: returns empty array when token not set";
+  try {
+    await withEnv("GITHUB_TOKEN", undefined, async () => {
+      const results = await queryGitHub("test-package", "npm");
+
+      if (Array.isArray(results) && results.length === 0) {
+        pass(testName);
+      } else {
+        fail(testName, `Expected empty array, got ${results.length} results`);
+      }
+    });
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: queryGitHub - placeholder implementation
+// -----------------------------------------------------------------------------
+async function testQueryGitHub_Placeholder() {
+  const testName = "queryGitHub: placeholder returns empty array with token";
+  try {
+    await withEnv("GITHUB_TOKEN", "fake-token-for-testing", async () => {
+      const results = await queryGitHub("test-package", "npm");
+
+      // Current implementation is a placeholder
+      if (Array.isArray(results) && results.length === 0) {
+        pass(testName);
+      } else {
+        fail(testName, `Expected empty array, got ${results.length} results`);
+      }
+    });
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: enrichVulnerability - combines OSV results
+// -----------------------------------------------------------------------------
+async function testEnrichVulnerability_OSVOnly() {
+  const testName = "enrichVulnerability: returns OSV results";
+  try {
+    await withEnv("CLAWSEC_NVD_API_KEY", undefined, async () => {
+      const results = await enrichVulnerability("lodash", "npm", "4.17.19");
+
+      if (Array.isArray(results)) {
+        pass(testName);
+      } else {
+        fail(testName, `Expected array, got ${typeof results}`);
+      }
+    });
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: enrichVulnerability - enriches with NVD when API key present
+// -----------------------------------------------------------------------------
+async function testEnrichVulnerability_WithNVD() {
+  const testName = "enrichVulnerability: enriches with NVD when API key present";
+  try {
+    const apiKey = process.env.CLAWSEC_NVD_API_KEY;
+    if (!apiKey) {
+      pass(testName + " (skipped - no API key)");
+      return;
+    }
+
+    // Query a package with known CVE
+    const results = await enrichVulnerability("lodash", "npm", "4.17.19");
+
+    // If results contain CVE IDs, they should have enriched references
+    const hasCVE = results.some((v) => v.id.startsWith("CVE-"));
+
+    if (hasCVE) {
+      // Check if references were enriched (should have more than original OSV refs)
+      const hasReferences = results.some((v) => v.references.length > 0);
+      if (hasReferences) {
+        pass(testName);
+      } else {
+        fail(testName, "Expected enriched references from NVD");
+      }
+    } else {
+      // No CVEs found, which is valid
+      pass(testName + " (no CVEs to enrich)");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: enrichVulnerability - handles empty results
+// -----------------------------------------------------------------------------
+async function testEnrichVulnerability_Empty() {
+  const testName = "enrichVulnerability: handles packages with no vulnerabilities";
+  try {
+    const results = await enrichVulnerability(
+      "nonexistent-package-12345",
+      "npm",
+      "1.0.0",
+    );
+
+    if (Array.isArray(results) && results.length === 0) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected empty array, got ${results.length} results`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: OSV normalization - extracts severity
+// -----------------------------------------------------------------------------
+async function testOSVNormalization_Severity() {
+  const testName = "OSV normalization: extracts severity correctly";
+  try {
+    // Query real data and check normalization
+    const results = await queryOSV("lodash", "npm", "4.17.19");
+
+    if (results.length > 0) {
+      const vuln = results[0];
+      const validSeverities = ["critical", "high", "medium", "low", "info"];
+
+      if (validSeverities.includes(vuln.severity)) {
+        pass(testName);
+      } else {
+        fail(testName, `Invalid severity: ${vuln.severity}`);
+      }
+    } else {
+      pass(testName + " (no results to test)");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: OSV normalization - extracts references
+// -----------------------------------------------------------------------------
+async function testOSVNormalization_References() {
+  const testName = "OSV normalization: extracts references";
+  try {
+    const results = await queryOSV("lodash", "npm", "4.17.19");
+
+    if (results.length > 0) {
+      const vuln = results[0];
+
+      if (Array.isArray(vuln.references)) {
+        // References should be URLs
+        const allUrls = vuln.references.every((ref) => ref.startsWith("http"));
+        if (allUrls) {
+          pass(testName);
+        } else {
+          fail(testName, `Non-URL reference found: ${vuln.references.join(", ")}`);
+        }
+      } else {
+        fail(testName, "References is not an array");
+      }
+    } else {
+      pass(testName + " (no results to test)");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: OSV normalization - extracts fixed version
+// -----------------------------------------------------------------------------
+async function testOSVNormalization_FixedVersion() {
+  const testName = "OSV normalization: extracts fixed version";
+  try {
+    const results = await queryOSV("lodash", "npm", "4.17.19");
+
+    if (results.length > 0) {
+      const hasFixedVersion = results.some((v) => v.fixed_version !== undefined);
+
+      if (hasFixedVersion) {
+        pass(testName);
+      } else {
+        // Some vulnerabilities may not have a fixed version yet
+        pass(testName + " (no fixed versions available)");
+      }
+    } else {
+      pass(testName + " (no results to test)");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: OSV normalization - includes timestamp
+// -----------------------------------------------------------------------------
+async function testOSVNormalization_Timestamp() {
+  const testName = "OSV normalization: includes discovery timestamp";
+  try {
+    const results = await queryOSV("lodash", "npm", "4.17.19");
+
+    if (results.length > 0) {
+      const vuln = results[0];
+      const iso8601Pattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+      if (vuln.discovered_at && iso8601Pattern.test(vuln.discovered_at)) {
+        pass(testName);
+      } else {
+        fail(testName, `Invalid timestamp: ${vuln.discovered_at}`);
+      }
+    } else {
+      pass(testName + " (no results to test)");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Vulnerability structure - required fields present
+// -----------------------------------------------------------------------------
+async function testVulnerabilityStructure() {
+  const testName = "Vulnerability structure: has all required fields";
+  try {
+    const results = await queryOSV("lodash", "npm", "4.17.19");
+
+    if (results.length > 0) {
+      const vuln = results[0];
+      const hasAllFields =
+        "id" in vuln &&
+        "source" in vuln &&
+        "severity" in vuln &&
+        "package" in vuln &&
+        "version" in vuln &&
+        "title" in vuln &&
+        "description" in vuln &&
+        "references" in vuln &&
+        "discovered_at" in vuln;
+
+      if (hasAllFields) {
+        pass(testName);
+      } else {
+        fail(testName, `Missing required fields: ${JSON.stringify(vuln)}`);
+      }
+    } else {
+      pass(testName + " (no results to test)");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Multiple ecosystems - PyPI support
+// -----------------------------------------------------------------------------
+async function testMultipleEcosystems_PyPI() {
+  const testName = "Multiple ecosystems: PyPI packages";
+  try {
+    // Query a known vulnerable Python package
+    const results = await queryOSV("requests", "PyPI", "2.6.0");
+
+    // Verify it returns valid results
+    if (Array.isArray(results)) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected array, got ${typeof results}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Multiple ecosystems - npm support
+// -----------------------------------------------------------------------------
+async function testMultipleEcosystems_npm() {
+  const testName = "Multiple ecosystems: npm packages";
+  try {
+    const results = await queryOSV("express", "npm");
+
+    if (Array.isArray(results)) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected array, got ${typeof results}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Main test runner
+// -----------------------------------------------------------------------------
+async function main() {
+  console.log("Running CVE integration tests...\n");
+
+  // OSV API tests
+  await testQueryOSV_Success();
+  await testQueryOSV_NotFound();
+  await testQueryOSV_NetworkError();
+  await testQueryOSV_WithVersion();
+  await testQueryOSV_SeverityNormalization();
+
+  // NVD API tests
+  await testQueryNVD_RateLimiting();
+  await testQueryNVD_NotFound();
+  await testQueryNVD_ValidCVE();
+
+  // GitHub Advisory tests
+  await testQueryGitHub_NoToken();
+  await testQueryGitHub_Placeholder();
+
+  // Enrichment tests
+  await testEnrichVulnerability_OSVOnly();
+  await testEnrichVulnerability_WithNVD();
+  await testEnrichVulnerability_Empty();
+
+  // Normalization tests
+  await testOSVNormalization_Severity();
+  await testOSVNormalization_References();
+  await testOSVNormalization_FixedVersion();
+  await testOSVNormalization_Timestamp();
+
+  // Structure tests
+  await testVulnerabilityStructure();
+
+  // Ecosystem tests
+  await testMultipleEcosystems_PyPI();
+  await testMultipleEcosystems_npm();
+
+  // Final report
+  report();
+  exitWithResults();
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
@@ -0,0 +1,597 @@
+#!/usr/bin/env node
+
+/**
+ * Dependency scanner tests for clawsec-scanner.
+ *
+ * Tests cover:
+ * - Utility functions (normalizeSeverity, safeJsonParse, commandExists)
+ * - Report generation and formatting
+ * - Argument parsing
+ * - Integration with temp directory setup
+ *
+ * Run: node skills/clawsec-scanner/test/dependency_scanner.test.mjs
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pass, fail, report, exitWithResults, createTempDir } from "./lib/test_harness.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LIB_PATH = path.resolve(__dirname, "..", "lib");
+
+// Dynamic import to ensure we test the actual modules
+const { normalizeSeverity, safeJsonParse, getTimestamp, generateUuid, commandExists } =
+  await import(`${LIB_PATH}/utils.mjs`);
+const { generateReport, formatReportJson, formatReportText } = await import(
+  `${LIB_PATH}/report.mjs`
+);
+
+// -----------------------------------------------------------------------------
+// Test: normalizeSeverity - critical variations
+// -----------------------------------------------------------------------------
+async function testNormalizeSeverity_Critical() {
+  const testName = "normalizeSeverity: recognizes critical";
+  try {
+    const test1 = normalizeSeverity("critical");
+    const test2 = normalizeSeverity("CRITICAL");
+    const test3 = normalizeSeverity("  Critical  ");
+
+    if (test1 === "critical" && test2 === "critical" && test3 === "critical") {
+      pass(testName);
+    } else {
+      fail(testName, `Expected 'critical', got ${test1}, ${test2}, ${test3}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: normalizeSeverity - high variations
+// -----------------------------------------------------------------------------
+async function testNormalizeSeverity_High() {
+  const testName = "normalizeSeverity: recognizes high";
+  try {
+    const test1 = normalizeSeverity("high");
+    const test2 = normalizeSeverity("HIGH");
+
+    if (test1 === "high" && test2 === "high") {
+      pass(testName);
+    } else {
+      fail(testName, `Expected 'high', got ${test1}, ${test2}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: normalizeSeverity - medium variations (moderate, medium)
+// -----------------------------------------------------------------------------
+async function testNormalizeSeverity_Medium() {
+  const testName = "normalizeSeverity: recognizes medium/moderate";
+  try {
+    const test1 = normalizeSeverity("medium");
+    const test2 = normalizeSeverity("moderate");
+    const test3 = normalizeSeverity("MODERATE");
+
+    if (test1 === "medium" && test2 === "medium" && test3 === "medium") {
+      pass(testName);
+    } else {
+      fail(testName, `Expected 'medium', got ${test1}, ${test2}, ${test3}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: normalizeSeverity - low variations
+// -----------------------------------------------------------------------------
+async function testNormalizeSeverity_Low() {
+  const testName = "normalizeSeverity: recognizes low";
+  try {
+    const test1 = normalizeSeverity("low");
+    const test2 = normalizeSeverity("LOW");
+
+    if (test1 === "low" && test2 === "low") {
+      pass(testName);
+    } else {
+      fail(testName, `Expected 'low', got ${test1}, ${test2}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: normalizeSeverity - defaults to info for unknown
+// -----------------------------------------------------------------------------
+async function testNormalizeSeverity_Unknown() {
+  const testName = "normalizeSeverity: defaults to info for unknown";
+  try {
+    const test1 = normalizeSeverity("unknown");
+    const test2 = normalizeSeverity("");
+    const test3 = normalizeSeverity("garbage");
+
+    if (test1 === "info" && test2 === "info" && test3 === "info") {
+      pass(testName);
+    } else {
+      fail(testName, `Expected 'info', got ${test1}, ${test2}, ${test3}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: safeJsonParse - valid JSON
+// -----------------------------------------------------------------------------
+async function testSafeJsonParse_Valid() {
+  const testName = "safeJsonParse: parses valid JSON";
+  try {
+    const json = '{"foo": "bar", "num": 42}';
+    const result = safeJsonParse(json);
+
+    if (
+      result &&
+      typeof result === "object" &&
+      result.foo === "bar" &&
+      result.num === 42
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, `Unexpected result: ${JSON.stringify(result)}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: safeJsonParse - invalid JSON returns fallback
+// -----------------------------------------------------------------------------
+async function testSafeJsonParse_Invalid() {
+  const testName = "safeJsonParse: returns fallback for invalid JSON";
+  try {
+    const invalid = "{not valid json}";
+    const fallback = { error: true };
+    const result = safeJsonParse(invalid, { fallback });
+
+    if (result && result.error === true) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected fallback object, got ${JSON.stringify(result)}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: safeJsonParse - empty string returns fallback
+// -----------------------------------------------------------------------------
+async function testSafeJsonParse_Empty() {
+  const testName = "safeJsonParse: returns fallback for empty string";
+  try {
+    const result = safeJsonParse("", { fallback: null });
+
+    if (result === null) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected null, got ${JSON.stringify(result)}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: getTimestamp - returns ISO 8601 format
+// -----------------------------------------------------------------------------
+async function testGetTimestamp() {
+  const testName = "getTimestamp: returns ISO 8601 format";
+  try {
+    const timestamp = getTimestamp();
+    const iso8601Pattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+    if (iso8601Pattern.test(timestamp)) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected ISO 8601 format, got ${timestamp}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: generateUuid - returns valid UUID v4 format
+// -----------------------------------------------------------------------------
+async function testGenerateUuid() {
+  const testName = "generateUuid: returns valid UUID v4 format";
+  try {
+    const uuid = generateUuid();
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+    if (uuidPattern.test(uuid)) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected UUID v4 format, got ${uuid}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: generateUuid - generates unique IDs
+// -----------------------------------------------------------------------------
+async function testGenerateUuid_Unique() {
+  const testName = "generateUuid: generates unique IDs";
+  try {
+    const uuid1 = generateUuid();
+    const uuid2 = generateUuid();
+    const uuid3 = generateUuid();
+
+    if (uuid1 !== uuid2 && uuid2 !== uuid3 && uuid1 !== uuid3) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected unique UUIDs, got ${uuid1}, ${uuid2}, ${uuid3}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: generateReport - empty vulnerabilities
+// -----------------------------------------------------------------------------
+async function testGenerateReport_Empty() {
+  const testName = "generateReport: handles empty vulnerabilities";
+  try {
+    const report = generateReport([], "/test/path");
+
+    if (
+      report &&
+      report.vulnerabilities.length === 0 &&
+      report.summary.critical === 0 &&
+      report.summary.high === 0 &&
+      report.summary.medium === 0 &&
+      report.summary.low === 0 &&
+      report.summary.info === 0 &&
+      report.target === "/test/path"
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, `Unexpected report structure: ${JSON.stringify(report)}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: generateReport - counts vulnerabilities by severity
+// -----------------------------------------------------------------------------
+async function testGenerateReport_Counts() {
+  const testName = "generateReport: counts vulnerabilities by severity";
+  try {
+    const vulnerabilities = [
+      {
+        id: "TEST-001",
+        source: "test",
+        severity: "critical",
+        package: "test-pkg",
+        version: "1.0.0",
+        fixed_version: "1.1.0",
+        title: "Test Critical",
+        description: "Test",
+        references: [],
+        discovered_at: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        id: "TEST-002",
+        source: "test",
+        severity: "high",
+        package: "test-pkg",
+        version: "1.0.0",
+        fixed_version: "1.1.0",
+        title: "Test High",
+        description: "Test",
+        references: [],
+        discovered_at: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        id: "TEST-003",
+        source: "test",
+        severity: "high",
+        package: "test-pkg-2",
+        version: "2.0.0",
+        fixed_version: "2.1.0",
+        title: "Test High 2",
+        description: "Test",
+        references: [],
+        discovered_at: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        id: "TEST-004",
+        source: "test",
+        severity: "medium",
+        package: "test-pkg-3",
+        version: "3.0.0",
+        fixed_version: "3.1.0",
+        title: "Test Medium",
+        description: "Test",
+        references: [],
+        discovered_at: "2026-01-01T00:00:00.000Z",
+      },
+    ];
+
+    const report = generateReport(vulnerabilities, ".");
+
+    if (
+      report.summary.critical === 1 &&
+      report.summary.high === 2 &&
+      report.summary.medium === 1 &&
+      report.summary.low === 0 &&
+      report.summary.info === 0 &&
+      report.vulnerabilities.length === 4
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, `Unexpected counts: ${JSON.stringify(report.summary)}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: formatReportJson - produces valid JSON
+// -----------------------------------------------------------------------------
+async function testFormatReportJson() {
+  const testName = "formatReportJson: produces valid JSON";
+  try {
+    const report = generateReport([], "/test/path");
+    const jsonString = formatReportJson(report);
+    const parsed = JSON.parse(jsonString);
+
+    if (parsed && parsed.target === "/test/path" && Array.isArray(parsed.vulnerabilities)) {
+      pass(testName);
+    } else {
+      fail(testName, `Invalid JSON structure: ${jsonString}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: formatReportText - produces text output
+// -----------------------------------------------------------------------------
+async function testFormatReportText() {
+  const testName = "formatReportText: produces text output";
+  try {
+    const report = generateReport([], "/test/path");
+    const text = formatReportText(report);
+
+    if (
+      text.includes("VULNERABILITY SCAN REPORT") &&
+      text.includes("Target:    /test/path") &&
+      text.includes("No vulnerabilities detected")
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, "Missing expected text output sections");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: formatReportText - includes vulnerability details
+// -----------------------------------------------------------------------------
+async function testFormatReportText_WithVulnerabilities() {
+  const testName = "formatReportText: includes vulnerability details";
+  try {
+    const vulnerabilities = [
+      {
+        id: "CVE-2026-1234",
+        source: "npm-audit",
+        severity: "high",
+        package: "test-package",
+        version: "1.0.0",
+        fixed_version: "1.1.0",
+        title: "Test Vulnerability",
+        description: "This is a test vulnerability description",
+        references: ["https://example.com/cve-2026-1234"],
+        discovered_at: "2026-01-01T00:00:00.000Z",
+      },
+    ];
+
+    const report = generateReport(vulnerabilities, ".");
+    const text = formatReportText(report);
+
+    if (
+      text.includes("CVE-2026-1234") &&
+      text.includes("test-package") &&
+      text.includes("1.0.0") &&
+      text.includes("1.1.0") &&
+      text.includes("Test Vulnerability") &&
+      text.includes("HIGH")
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, "Missing expected vulnerability details in text output");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: commandExists - detects existing command
+// -----------------------------------------------------------------------------
+async function testCommandExists_Found() {
+  const testName = "commandExists: detects existing command (node)";
+  try {
+    // 'node' should always exist in the test environment
+    const result = await commandExists("node");
+
+    if (result === true) {
+      pass(testName);
+    } else {
+      fail(testName, "Expected true for 'node' command");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: commandExists - returns false for non-existent command
+// -----------------------------------------------------------------------------
+async function testCommandExists_NotFound() {
+  const testName = "commandExists: returns false for non-existent command";
+  try {
+    // Use a command that definitely doesn't exist
+    const result = await commandExists("definitely-not-a-real-command-12345");
+
+    if (result === false) {
+      pass(testName);
+    } else {
+      fail(testName, "Expected false for non-existent command");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Report structure - has required fields
+// -----------------------------------------------------------------------------
+async function testReportStructure() {
+  const testName = "Report structure: has all required fields";
+  try {
+    const report = generateReport([], ".");
+
+    const hasAllFields =
+      "scan_id" in report &&
+      "timestamp" in report &&
+      "target" in report &&
+      "vulnerabilities" in report &&
+      "summary" in report &&
+      "critical" in report.summary &&
+      "high" in report.summary &&
+      "medium" in report.summary &&
+      "low" in report.summary &&
+      "info" in report.summary;
+
+    if (hasAllFields) {
+      pass(testName);
+    } else {
+      fail(testName, `Missing required fields in report: ${JSON.stringify(report)}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Temp directory creation
+// -----------------------------------------------------------------------------
+async function testTempDirCreation() {
+  const testName = "createTempDir: creates and cleans up temp directory";
+  try {
+    const { path: tmpPath, cleanup } = await createTempDir();
+
+    // Verify directory exists
+    const stat = await fs.stat(tmpPath);
+    if (!stat.isDirectory()) {
+      fail(testName, "Created path is not a directory");
+      return;
+    }
+
+    // Create a test file
+    const testFilePath = path.join(tmpPath, "test.txt");
+    await fs.writeFile(testFilePath, "test content");
+
+    // Verify file exists
+    const fileExists = await fs
+      .access(testFilePath)
+      .then(() => true)
+      .catch(() => false);
+
+    if (!fileExists) {
+      fail(testName, "Test file was not created");
+      return;
+    }
+
+    // Cleanup
+    await cleanup();
+
+    // Verify cleanup
+    const dirExists = await fs
+      .access(tmpPath)
+      .then(() => true)
+      .catch(() => false);
+
+    if (dirExists) {
+      fail(testName, "Temp directory was not cleaned up");
+    } else {
+      pass(testName);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Main test runner
+// -----------------------------------------------------------------------------
+async function main() {
+  console.log("Running dependency scanner tests...\n");
+
+  // Utility function tests
+  await testNormalizeSeverity_Critical();
+  await testNormalizeSeverity_High();
+  await testNormalizeSeverity_Medium();
+  await testNormalizeSeverity_Low();
+  await testNormalizeSeverity_Unknown();
+
+  await testSafeJsonParse_Valid();
+  await testSafeJsonParse_Invalid();
+  await testSafeJsonParse_Empty();
+
+  await testGetTimestamp();
+  await testGenerateUuid();
+  await testGenerateUuid_Unique();
+
+  await testCommandExists_Found();
+  await testCommandExists_NotFound();
+
+  // Report generation tests
+  await testGenerateReport_Empty();
+  await testGenerateReport_Counts();
+  await testReportStructure();
+
+  // Report formatting tests
+  await testFormatReportJson();
+  await testFormatReportText();
+  await testFormatReportText_WithVulnerabilities();
+
+  // Infrastructure tests
+  await testTempDirCreation();
+
+  // Final report
+  report();
+  exitWithResults();
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
@@ -0,0 +1,101 @@
+/**
+ * Shared test harness for clawsec-scanner tests.
+ * Provides consistent test reporting and runner utilities.
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+let passCount = 0;
+let failCount = 0;
+
+/**
+ * Records a passing test.
+ * @param {string} name - Test name
+ */
+export function pass(name) {
+  passCount++;
+  console.log(`✓ ${name}`);
+}
+
+/**
+ * Records a failing test.
+ * @param {string} name - Test name
+ * @param {Error|string} error - Error details
+ */
+export function fail(name, error) {
+  failCount++;
+  console.error(`✗ ${name}`);
+  console.error(`  ${String(error)}`);
+}
+
+/**
+ * Gets current test statistics.
+ * @returns {{passCount: number, failCount: number}}
+ */
+export function getStats() {
+  return { passCount, failCount };
+}
+
+/**
+ * Reports final test results to console.
+ */
+export function report() {
+  console.log(`\n=== Results: ${passCount} passed, ${failCount} failed ===`);
+}
+
+/**
+ * Exits with appropriate code based on test results.
+ * Exit code 0 for success, 1 for failures.
+ */
+export function exitWithResults() {
+  if (failCount > 0) {
+    process.exit(1);
+  }
+}
+
+/**
+ * Creates a temporary directory for test use.
+ * @returns {Promise<{path: string, cleanup: Function}>} Object with temp dir path and cleanup function
+ */
+export async function createTempDir() {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawsec-scanner-test-"));
+
+  return {
+    path: tmpDir,
+    cleanup: async () => {
+      try {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors
+      }
+    },
+  };
+}
+
+/**
+ * Temporarily sets an environment variable for the duration of a function.
+ * Restores the original value (or deletes the variable) after the function completes.
+ * @param {string} key - Environment variable name
+ * @param {string|undefined} value - Value to set (undefined to delete)
+ * @param {Function} fn - Function to execute with the modified environment
+ * @returns {Promise<*>} Result of the function
+ */
+export async function withEnv(key, value, fn) {
+  const oldValue = process.env[key];
+  try {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+    return await fn();
+  } finally {
+    if (oldValue === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = oldValue;
+    }
+  }
+}
@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+/**
+ * Regression tests for Baz review findings on PR #101.
+ *
+ * These tests enforce:
+ * - execCommand supports cwd and runs tools in the target directory
+ * - scan_dependencies chooses pip-audit invocation correctly when requirements.txt is absent
+ * - runner.sh preserves DAST findings even when dast_runner exits non-zero
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { pass, fail, report, exitWithResults, createTempDir } from "./lib/test_harness.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(__dirname, "..");
+const SCRIPTS_DIR = path.join(SKILL_ROOT, "scripts");
+const { execCommand } = await import(path.join(SKILL_ROOT, "lib", "utils.mjs"));
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{cwd?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+async function runProcess(cmd, args, options = {}) {
+  return new Promise((resolve) => {
+    const proc = spawn(cmd, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    proc.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} content
+ */
+async function writeExecutable(filePath, content) {
+  await fs.writeFile(filePath, content, "utf8");
+  await fs.chmod(filePath, 0o755);
+}
+
+async function testExecCommandRespectsCwd() {
+  const testName = "execCommand: respects cwd option";
+  const tmp = await createTempDir();
+  try {
+    const result = await execCommand("node", ["-e", "process.stdout.write(process.cwd())"], {
+      cwd: tmp.path,
+    });
+
+    const expectedPath = await fs.realpath(tmp.path);
+    const actualPath = await fs.realpath(result.stdout.trim());
+
+    if (actualPath === expectedPath) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected cwd ${expectedPath}, got ${actualPath}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  } finally {
+    await tmp.cleanup();
+  }
+}
+
+async function testScanDependenciesUsesTargetCwdAndSmartPipArgs() {
+  const testName = "scan_dependencies: runs npm in target cwd and avoids -r when requirements.txt missing";
+
+  const tmp = await createTempDir();
+  try {
+    const targetDir = path.join(tmp.path, "target");
+    const binDir = path.join(tmp.path, "bin");
+    const npmLogPath = path.join(tmp.path, "npm.log");
+    const pipLogPath = path.join(tmp.path, "pip.log");
+
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.mkdir(binDir, { recursive: true });
+
+    await fs.writeFile(path.join(targetDir, "package-lock.json"), "{}\n", "utf8");
+    await fs.writeFile(path.join(targetDir, "pyproject.toml"), "[project]\nname='demo'\nversion='0.1.0'\n", "utf8");
+
+    await writeExecutable(
+      path.join(binDir, "npm"),
+      `#!/usr/bin/env node
+const fs = require("node:fs");
+const logPath = process.env.CLAWSEC_TEST_NPM_LOG;
+fs.appendFileSync(logPath, JSON.stringify({ cwd: process.cwd(), args: process.argv.slice(2) }) + "\\n");
+process.stdout.write(JSON.stringify({ vulnerabilities: {} }));
+`,
+    );
+
+    await writeExecutable(
+      path.join(binDir, "pip-audit"),
+      `#!/usr/bin/env node
+const fs = require("node:fs");
+const logPath = process.env.CLAWSEC_TEST_PIP_LOG;
+fs.appendFileSync(logPath, JSON.stringify({ cwd: process.cwd(), args: process.argv.slice(2) }) + "\\n");
+process.stdout.write(JSON.stringify({ dependencies: [] }));
+`,
+    );
+
+    const env = {
+      ...process.env,
+      PATH: `${binDir}:${process.env.PATH}`,
+      CLAWSEC_TEST_NPM_LOG: npmLogPath,
+      CLAWSEC_TEST_PIP_LOG: pipLogPath,
+    };
+
+    const result = await runProcess(
+      "node",
+      [path.join(SCRIPTS_DIR, "scan_dependencies.mjs"), "--target", targetDir, "--format", "json"],
+      { cwd: SKILL_ROOT, env },
+    );
+
+    if (result.code !== 0) {
+      fail(testName, `scan_dependencies exited ${result.code}: ${result.stderr}`);
+      return;
+    }
+
+    const npmLog = JSON.parse((await fs.readFile(npmLogPath, "utf8")).trim());
+    const pipLog = JSON.parse((await fs.readFile(pipLogPath, "utf8")).trim());
+
+    const expectedTargetPath = await fs.realpath(targetDir);
+    const actualNpmCwd = await fs.realpath(npmLog.cwd);
+    const npmCwdOk = actualNpmCwd === expectedTargetPath;
+    const pipArgsOk = !pipLog.args.includes("-r");
+
+    if (npmCwdOk && pipArgsOk) {
+      pass(testName);
+    } else {
+      fail(
+        testName,
+        `npm cwd=${actualNpmCwd}, expected=${expectedTargetPath}; pip args=${JSON.stringify(pipLog.args)}`,
+      );
+    }
+  } catch (error) {
+    fail(testName, error);
+  } finally {
+    await tmp.cleanup();
+  }
+}
+
+async function testRunnerPreservesDastReportOnNonZeroExit() {
+  const testName = "runner.sh: preserves DAST findings when dast_runner exits 1";
+
+  const tmp = await createTempDir();
+  try {
+    const targetDir = path.join(tmp.path, "target");
+    const binDir = path.join(tmp.path, "bin");
+
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.mkdir(binDir, { recursive: true });
+
+    await writeExecutable(
+      path.join(binDir, "node"),
+      `#!/usr/bin/env bash
+set -euo pipefail
+
+script="\${1:-}"
+target="."
+while [[ $# -gt 0 ]]; do
+  if [[ "$1" == "--target" ]]; then
+    target="\${2:-.}"
+    break
+  fi
+  shift
+done
+
+if [[ "$script" == *"scan_dependencies.mjs" ]] || [[ "$script" == *"sast_analyzer.mjs" ]]; then
+  cat <<JSON
+{"scan_id":"test-scan","timestamp":"2026-03-09T00:00:00.000Z","target":"$target","vulnerabilities":[],"summary":{"critical":0,"high":0,"medium":0,"low":0,"info":0}}
+JSON
+  exit 0
+fi
+
+if [[ "$script" == *"dast_runner.mjs" ]]; then
+  cat <<JSON
+{"scan_id":"test-scan","timestamp":"2026-03-09T00:00:00.000Z","target":"$target","vulnerabilities":[{"id":"DAST-001","source":"dast","severity":"high","package":"N/A","version":"N/A","title":"DAST finding","description":"Synthetic high severity finding","references":[],"discovered_at":"2026-03-09T00:00:00.000Z"}],"summary":{"critical":0,"high":1,"medium":0,"low":0,"info":0}}
+JSON
+  exit 1
+fi
+
+echo "Unexpected node invocation: $*" >&2
+exit 2
+`,
+    );
+
+    const env = {
+      ...process.env,
+      PATH: `${binDir}:${process.env.PATH}`,
+    };
+
+    const result = await runProcess(
+      "bash",
+      [path.join(SCRIPTS_DIR, "runner.sh"), "--target", targetDir, "--format", "json"],
+      { cwd: SKILL_ROOT, env },
+    );
+
+    if (result.code !== 0) {
+      fail(testName, `runner.sh exited ${result.code}: ${result.stderr}`);
+      return;
+    }
+
+    const merged = JSON.parse(result.stdout.trim());
+    const hasDastFinding = Array.isArray(merged.vulnerabilities)
+      && merged.vulnerabilities.some((v) => v.id === "DAST-001" && v.source === "dast" && v.severity === "high");
+
+    if (hasDastFinding && merged.summary.high >= 1) {
+      pass(testName);
+    } else {
+      fail(testName, `Expected DAST high finding to be preserved. Output: ${result.stdout}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  } finally {
+    await tmp.cleanup();
+  }
+}
+
+async function main() {
+  await testExecCommandRespectsCwd();
+  await testScanDependenciesUsesTargetCwdAndSmartPipArgs();
+  await testRunnerPreservesDastReportOnNonZeroExit();
+
+  report();
+  exitWithResults();
+}
+
+await main();
@@ -0,0 +1,570 @@
+#!/usr/bin/env node
+
+/**
+ * SAST engine tests for clawsec-scanner.
+ *
+ * Tests cover:
+ * - Semgrep output parsing and normalization
+ * - Bandit output parsing and normalization
+ * - File existence checking
+ * - Vulnerability data structure validation
+ * - Error handling for malformed tool outputs
+ *
+ * Run: node skills/clawsec-scanner/test/sast_engine.test.mjs
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pass, fail, report, exitWithResults } from "./lib/test_harness.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LIB_PATH = path.resolve(__dirname, "..", "lib");
+
+// Dynamic import to ensure we test the actual modules
+const { normalizeSeverity, safeJsonParse, getTimestamp } = await import(`${LIB_PATH}/utils.mjs`);
+
+// -----------------------------------------------------------------------------
+// Test: Parse valid Semgrep JSON output
+// -----------------------------------------------------------------------------
+async function testParseSemgrepOutput_Valid() {
+  const testName = "SAST: parse valid Semgrep JSON output";
+  try {
+    const semgrepOutput = JSON.stringify({
+      results: [
+        {
+          check_id: "javascript.lang.security.audit.unsafe-regex.unsafe-regex",
+          path: "test/file.js",
+          start: { line: 42 },
+          extra: {
+            message: "Potential ReDoS vulnerability detected",
+            severity: "WARNING",
+            metadata: {
+              references: ["https://owasp.org/redos"],
+              source: "semgrep-rules",
+            },
+          },
+        },
+      ],
+    });
+
+    const parsed = safeJsonParse(semgrepOutput, {
+      fallback: { results: [] },
+      label: "semgrep output",
+    });
+
+    if (
+      parsed &&
+      parsed.results &&
+      parsed.results.length === 1 &&
+      parsed.results[0].check_id === "javascript.lang.security.audit.unsafe-regex.unsafe-regex"
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to parse valid Semgrep output correctly");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Parse Semgrep output with missing fields
+// -----------------------------------------------------------------------------
+async function testParseSemgrepOutput_MissingFields() {
+  const testName = "SAST: handle Semgrep output with missing fields";
+  try {
+    const semgrepOutput = JSON.stringify({
+      results: [
+        {
+          // Missing check_id, path, extra
+          start: { line: 10 },
+        },
+      ],
+    });
+
+    const parsed = safeJsonParse(semgrepOutput, {
+      fallback: { results: [] },
+      label: "semgrep output",
+    });
+
+    // Should parse successfully even with missing fields
+    if (parsed && parsed.results && parsed.results.length === 1) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to handle Semgrep output with missing fields");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Parse empty Semgrep results
+// -----------------------------------------------------------------------------
+async function testParseSemgrepOutput_Empty() {
+  const testName = "SAST: handle empty Semgrep results";
+  try {
+    const semgrepOutput = JSON.stringify({ results: [] });
+
+    const parsed = safeJsonParse(semgrepOutput, {
+      fallback: { results: [] },
+      label: "semgrep output",
+    });
+
+    if (parsed && Array.isArray(parsed.results) && parsed.results.length === 0) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to handle empty Semgrep results");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Parse malformed Semgrep JSON
+// -----------------------------------------------------------------------------
+async function testParseSemgrepOutput_Malformed() {
+  const testName = "SAST: handle malformed Semgrep JSON gracefully";
+  try {
+    const malformedJson = "{ results: [{ invalid json }] }";
+
+    const parsed = safeJsonParse(malformedJson, {
+      fallback: { results: [] },
+      label: "semgrep output",
+    });
+
+    // Should fall back to default value
+    if (parsed && Array.isArray(parsed.results) && parsed.results.length === 0) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to use fallback for malformed JSON");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Parse valid Bandit JSON output
+// -----------------------------------------------------------------------------
+async function testParseBanditOutput_Valid() {
+  const testName = "SAST: parse valid Bandit JSON output";
+  try {
+    const banditOutput = JSON.stringify({
+      results: [
+        {
+          test_id: "B201",
+          filename: "/path/to/file.py",
+          line_number: 15,
+          issue_text: "A possibly insecure use of pickle detected.",
+          issue_severity: "HIGH",
+          issue_confidence: "HIGH",
+        },
+      ],
+    });
+
+    const parsed = safeJsonParse(banditOutput, {
+      fallback: { results: [] },
+      label: "bandit output",
+    });
+
+    if (
+      parsed &&
+      parsed.results &&
+      parsed.results.length === 1 &&
+      parsed.results[0].test_id === "B201"
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to parse valid Bandit output correctly");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Parse Bandit output with missing fields
+// -----------------------------------------------------------------------------
+async function testParseBanditOutput_MissingFields() {
+  const testName = "SAST: handle Bandit output with missing fields";
+  try {
+    const banditOutput = JSON.stringify({
+      results: [
+        {
+          // Missing test_id, issue_text, etc.
+          filename: "/path/to/file.py",
+        },
+      ],
+    });
+
+    const parsed = safeJsonParse(banditOutput, {
+      fallback: { results: [] },
+      label: "bandit output",
+    });
+
+    // Should parse successfully even with missing fields
+    if (parsed && parsed.results && parsed.results.length === 1) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to handle Bandit output with missing fields");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Parse empty Bandit results
+// -----------------------------------------------------------------------------
+async function testParseBanditOutput_Empty() {
+  const testName = "SAST: handle empty Bandit results";
+  try {
+    const banditOutput = JSON.stringify({ results: [] });
+
+    const parsed = safeJsonParse(banditOutput, {
+      fallback: { results: [] },
+      label: "bandit output",
+    });
+
+    if (parsed && Array.isArray(parsed.results) && parsed.results.length === 0) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to handle empty Bandit results");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Normalize Semgrep severity levels
+// -----------------------------------------------------------------------------
+async function testNormalizeSeverity_Semgrep() {
+  const testName = "SAST: normalize Semgrep severity levels";
+  try {
+    const errorLevel = normalizeSeverity("ERROR");
+    const warningLevel = normalizeSeverity("WARNING");
+    const infoLevel = normalizeSeverity("INFO");
+
+    // Semgrep uses ERROR, WARNING, INFO
+    // normalizeSeverity uses substring matching, so these map to 'info' (default)
+    // since they don't contain 'critical', 'high', 'medium', 'moderate', or 'low'
+    if (errorLevel === "info" && warningLevel === "info" && infoLevel === "info") {
+      pass(testName);
+    } else {
+      fail(
+        testName,
+        `Unexpected normalization: ERROR=${errorLevel}, WARNING=${warningLevel}, INFO=${infoLevel}`,
+      );
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Normalize Bandit severity levels
+// -----------------------------------------------------------------------------
+async function testNormalizeSeverity_Bandit() {
+  const testName = "SAST: normalize Bandit severity levels";
+  try {
+    const highLevel = normalizeSeverity("HIGH");
+    const mediumLevel = normalizeSeverity("MEDIUM");
+    const lowLevel = normalizeSeverity("LOW");
+
+    if (
+      (highLevel === "high" || highLevel === "critical") &&
+      mediumLevel === "medium" &&
+      lowLevel === "low"
+    ) {
+      pass(testName);
+    } else {
+      fail(
+        testName,
+        `Unexpected normalization: HIGH=${highLevel}, MEDIUM=${mediumLevel}, LOW=${lowLevel}`,
+      );
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Validate vulnerability data structure from Semgrep
+// -----------------------------------------------------------------------------
+async function testVulnerabilityStructure_Semgrep() {
+  const testName = "SAST: validate Semgrep vulnerability data structure";
+  try {
+    // Simulate vulnerability object created from Semgrep output
+    const vuln = {
+      id: "javascript.lang.security.audit.unsafe-regex.unsafe-regex",
+      source: "sast",
+      severity: normalizeSeverity("WARNING"),
+      package: "file.js",
+      version: "test/file.js:42",
+      fixed_version: "",
+      title: "Potential ReDoS vulnerability detected",
+      description: "Potential ReDoS vulnerability detected",
+      references: ["https://owasp.org/redos", "semgrep-rules"],
+      discovered_at: getTimestamp(),
+    };
+
+    // Validate required fields
+    const hasRequiredFields =
+      typeof vuln.id === "string" &&
+      vuln.id.length > 0 &&
+      vuln.source === "sast" &&
+      typeof vuln.severity === "string" &&
+      typeof vuln.package === "string" &&
+      typeof vuln.discovered_at === "string" &&
+      Array.isArray(vuln.references);
+
+    if (hasRequiredFields) {
+      pass(testName);
+    } else {
+      fail(testName, "Vulnerability object missing required fields");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Validate vulnerability data structure from Bandit
+// -----------------------------------------------------------------------------
+async function testVulnerabilityStructure_Bandit() {
+  const testName = "SAST: validate Bandit vulnerability data structure";
+  try {
+    // Simulate vulnerability object created from Bandit output
+    const vuln = {
+      id: "B201",
+      source: "sast",
+      severity: normalizeSeverity("HIGH"),
+      package: "file.py",
+      version: "/path/to/file.py:15",
+      fixed_version: "",
+      title: "A possibly insecure use of pickle detected.",
+      description: "A possibly insecure use of pickle detected.",
+      references: ["https://bandit.readthedocs.io/en/latest/plugins/b201.html"],
+      discovered_at: getTimestamp(),
+    };
+
+    // Validate required fields
+    const hasRequiredFields =
+      typeof vuln.id === "string" &&
+      vuln.id.length > 0 &&
+      vuln.source === "sast" &&
+      typeof vuln.severity === "string" &&
+      typeof vuln.package === "string" &&
+      typeof vuln.discovered_at === "string" &&
+      Array.isArray(vuln.references) &&
+      vuln.references.length > 0;
+
+    if (hasRequiredFields) {
+      pass(testName);
+    } else {
+      fail(testName, "Vulnerability object missing required fields");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Timestamp format validation
+// -----------------------------------------------------------------------------
+async function testTimestampFormat() {
+  const testName = "SAST: validate timestamp format";
+  try {
+    const timestamp = getTimestamp();
+
+    // Should be ISO 8601 format
+    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+    if (iso8601Regex.test(timestamp)) {
+      pass(testName);
+    } else {
+      fail(testName, `Invalid timestamp format: ${timestamp}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Handle Semgrep results with metadata variations
+// -----------------------------------------------------------------------------
+async function testSemgrepMetadata_Variations() {
+  const testName = "SAST: handle Semgrep metadata variations";
+  try {
+    // Test with missing metadata
+    const output1 = JSON.stringify({
+      results: [
+        {
+          check_id: "test-rule",
+          path: "test.js",
+          extra: {
+            message: "Test message",
+            severity: "ERROR",
+          },
+        },
+      ],
+    });
+
+    // Test with metadata but no references
+    const output2 = JSON.stringify({
+      results: [
+        {
+          check_id: "test-rule",
+          path: "test.js",
+          extra: {
+            message: "Test message",
+            severity: "ERROR",
+            metadata: {
+              source: "custom-rule",
+            },
+          },
+        },
+      ],
+    });
+
+    const parsed1 = safeJsonParse(output1, {
+      fallback: { results: [] },
+      label: "semgrep output",
+    });
+    const parsed2 = safeJsonParse(output2, {
+      fallback: { results: [] },
+      label: "semgrep output",
+    });
+
+    if (
+      parsed1 &&
+      parsed1.results &&
+      parsed1.results.length === 1 &&
+      parsed2 &&
+      parsed2.results &&
+      parsed2.results.length === 1
+    ) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to handle metadata variations");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Validate reference URL formats
+// -----------------------------------------------------------------------------
+async function testReferenceUrlFormats() {
+  const testName = "SAST: validate reference URL formats";
+  try {
+    // Bandit reference format
+    const testId = "B201";
+    const banditRef = `https://bandit.readthedocs.io/en/latest/plugins/${testId.toLowerCase().replace(/_/g, "-")}.html`;
+
+    // Should follow expected pattern
+    const expectedRef = "https://bandit.readthedocs.io/en/latest/plugins/b201.html";
+
+    if (banditRef === expectedRef) {
+      pass(testName);
+    } else {
+      fail(testName, `Reference URL mismatch: ${banditRef} !== ${expectedRef}`);
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Handle non-object results gracefully
+// -----------------------------------------------------------------------------
+async function testHandleNonObjectResults() {
+  const testName = "SAST: handle non-object results in array";
+  try {
+    const output = JSON.stringify({
+      results: [null, undefined, "string", 123, { valid: "object" }],
+    });
+
+    const parsed = safeJsonParse(output, {
+      fallback: { results: [] },
+      label: "test output",
+    });
+
+    // Should parse successfully and include all items
+    if (parsed && parsed.results && parsed.results.length === 5) {
+      pass(testName);
+    } else {
+      fail(testName, "Failed to preserve all array elements");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Test: Severity normalization edge cases
+// -----------------------------------------------------------------------------
+async function testSeverityNormalization_EdgeCases() {
+  const testName = "SAST: handle severity normalization edge cases";
+  try {
+    const unknown = normalizeSeverity("UNKNOWN_SEVERITY");
+    const empty = normalizeSeverity("");
+    const whitespace = normalizeSeverity("  ");
+
+    // Should handle unknown severities gracefully
+    const allValid =
+      typeof unknown === "string" && typeof empty === "string" && typeof whitespace === "string";
+
+    if (allValid) {
+      pass(testName);
+    } else {
+      fail(testName, "Severity normalization returned non-string values");
+    }
+  } catch (error) {
+    fail(testName, error);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Main test runner
+// -----------------------------------------------------------------------------
+async function main() {
+  // Semgrep output parsing tests
+  await testParseSemgrepOutput_Valid();
+  await testParseSemgrepOutput_MissingFields();
+  await testParseSemgrepOutput_Empty();
+  await testParseSemgrepOutput_Malformed();
+
+  // Bandit output parsing tests
+  await testParseBanditOutput_Valid();
+  await testParseBanditOutput_MissingFields();
+  await testParseBanditOutput_Empty();
+
+  // Severity normalization tests
+  await testNormalizeSeverity_Semgrep();
+  await testNormalizeSeverity_Bandit();
+  await testSeverityNormalization_EdgeCases();
+
+  // Vulnerability structure tests
+  await testVulnerabilityStructure_Semgrep();
+  await testVulnerabilityStructure_Bandit();
+
+  // Utility tests
+  await testTimestampFormat();
+  await testSemgrepMetadata_Variations();
+  await testReferenceUrlFormats();
+  await testHandleNonObjectResults();
+
+  // Report results
+  report();
+  exitWithResults();
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
@@ -5,6 +5,21 @@ All notable changes to the ClawSec Suite will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [0.1.4] - 2026-02-28
+
+### Added
+
+- Advisory output snippets now include exploitability context in suite quick-check and heartbeat examples.
+
+### Changed
+
+- Clarified exploitability guidance to match runtime score values (`high|medium|low|unknown`).
+- Prioritization guidance now emphasizes high-exploitability advisories for immediate handling.
+
+### Fixed
+
+- Kept exploitability enrichment in advisory workflows non-fatal per item so a single analysis failure does not abort feed updates.
+
 ## [0.1.3]

 ### Added
@@ -121,6 +121,7 @@ else
    while IFS= read -r id; do
      [ -z "$id" ] && continue
      jq -r --arg id "$id" '.advisories[] | select(.id == $id) | "- [\(.severity | ascii_upcase)] \(.id): \(.title)"' "$FEED_TMP"
+      jq -r --arg id "$id" '.advisories[] | select(.id == $id) | "  Exploitability: \(.exploitability_score // "unknown" | ascii_upcase)"' "$FEED_TMP"
      jq -r --arg id "$id" '.advisories[] | select(.id == $id) | "  Action: \(.action // "Review advisory details")"' "$FEED_TMP"
    done < "$NEW_IDS_FILE"
  else
@@ -194,8 +195,18 @@ fi
 Heartbeat output should include:
 - suite version status,
 - advisory feed status,
- new advisory list (if any),
+- new advisory list (if any) with exploitability scores,
 - installed skills that appear in advisory `affected` lists,
 - and a double-confirmation reminder before risky install/remove actions.

-If your runtime sends alerts, treat `critical` and `high` advisories affecting installed skills as immediate notifications.
+### Exploitability-Based Prioritization
+
+When alerting on advisories, prioritize by **exploitability score** in addition to severity:
+
+- `high` exploitability: Trivially or easily exploitable with public tooling, immediate action required
+- `medium` exploitability: Exploitable with specific conditions, standard priority
+- `low` exploitability: Difficult to exploit or theoretical, low priority
+
+**Priority Rule**: A HIGH severity + HIGH exploitability CVE should be treated more urgently than a CRITICAL severity + LOW exploitability CVE.
+
+If your runtime sends alerts, treat `high` exploitability advisories affecting installed skills as immediate notifications, regardless of severity rating.
@@ -1,6 +1,6 @@
 ---
 name: clawsec-suite
-version: 0.1.3
+version: 0.1.4
 description: ClawSec suite manager with embedded advisory-feed monitoring, cryptographic signature verification, approval-gated malicious-skill response, and guided setup for additional security skills.
 homepage: https://clawsec.prompt.security
 clawdis:
@@ -234,12 +234,25 @@ if [ -s "$NEW_IDS_FILE" ]; then
  while IFS= read -r id; do
    [ -z "$id" ] && continue
    jq -r --arg id "$id" '.advisories[] | select(.id == $id) | "- [\(.severity | ascii_upcase)] \(.id): \(.title)"' "$TMP/feed.json"
+    jq -r --arg id "$id" '.advisories[] | select(.id == $id) | "  Exploitability: \(.exploitability_score // "unknown" | ascii_upcase)"' "$TMP/feed.json"
  done < "$NEW_IDS_FILE"
 else
  echo "FEED_OK - no new advisories"
 fi
 ```

+## Exploitability Context
+
+Advisories in the feed can include `exploitability_score` and `exploitability_rationale` fields to help agents prioritize real-world threats:
+
+- **Exploitability scores**: `high`, `medium`, `low`, or `unknown`
+- **Context-aware assessment**: Considers attack vector, authentication requirements, and AI agent deployment patterns
+- **Exploit availability**: Detects public exploits and weaponization status
+
+When processing advisories, prioritize by exploitability in addition to severity. A HIGH severity + HIGH exploitability CVE is more urgent than a CRITICAL severity + LOW exploitability CVE.
+
+For detailed methodology, see the [exploitability scoring documentation](../../wiki/exploitability-scoring.md).
+
 ## Heartbeat Integration

 Use the suite heartbeat script as the single periodic security check entrypoint:
@@ -1,6 +1,6 @@
 {
  "name": "clawsec-suite",
-  "version": "0.1.3",
+  "version": "0.1.4",
  "description": "ClawSec suite manager with embedded advisory-feed monitoring, cryptographic signature verification, approval-gated malicious-skill response, and guided setup for additional security skills.",
  "author": "prompt-security",
  "license": "AGPL-3.0-or-later",
@@ -11,25 +11,12 @@

 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { pass, fail, report, exitWithResults } from "./lib/test_harness.mjs";

 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const LIB_PATH = path.resolve(__dirname, "..", "hooks", "clawsec-advisory-guardian", "lib");
 const { advisoryAppliesToOpenclaw } = await import(`${LIB_PATH}/advisory_scope.mjs`);

-let passCount = 0;
-let failCount = 0;
-
-function pass(name) {
-  passCount += 1;
-  console.log(`\u2713 ${name}`);
-}
-
-function fail(name, error) {
-  failCount += 1;
-  console.error(`\u2717 ${name}`);
-  console.error(`  ${String(error)}`);
-}
-
 function testFindMatchesFiltersByApplicationScope() {
  const testName = "advisoryAppliesToOpenclaw: openclaw + legacy advisories are considered";

@@ -89,10 +76,8 @@ function runTests() {
  testFindMatchesAcceptsApplicationArray();
  testInvalidApplicationValueFallsBackCompat();

-  console.log(`\n=== Results: ${passCount} passed, ${failCount} failed ===`);
-  if (failCount > 0) {
-    process.exit(1);
-  }
+  report();
+  exitWithResults();
 }

 runTests();
@@ -15,9 +15,9 @@
 */

 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { pass, fail, report, exitWithResults, createTempDir } from "./lib/test_harness.mjs";

 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const LIB_PATH = path.resolve(__dirname, "..", "hooks", "clawsec-advisory-guardian", "lib");
@@ -27,29 +27,6 @@ const { isAdvisorySuppressed, loadAdvisorySuppression } = await import(
 );

 let tempDir;
-let passCount = 0;
-let failCount = 0;
-
-function pass(name) {
-  passCount++;
-  console.log(`\u2713 ${name}`);
-}
-
-function fail(name, error) {
-  failCount++;
-  console.error(`\u2717 ${name}`);
-  console.error(`  ${String(error)}`);
-}
-
-async function setupTestDir() {
-  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "advisory-suppression-test-"));
-}
-
-async function cleanupTestDir() {
-  if (tempDir) {
-    await fs.rm(tempDir, { recursive: true, force: true });
-  }
-}

 function makeMatch(advisoryId, skillName, version = "1.0.0") {
  return {
@@ -190,7 +167,7 @@ async function testMissingAdvisoryId() {
 async function testLoadWithAdvisorySentinel() {
  const testName = "loadAdvisorySuppression: loads config with advisory sentinel";
  try {
-    const configFile = path.join(tempDir, "advisory-config.json");
+    const configFile = path.join(tempDir.path, "advisory-config.json");
    await fs.writeFile(configFile, JSON.stringify({
      enabledFor: ["advisory"],
      suppressions: [{
@@ -215,7 +192,7 @@ async function testLoadWithAdvisorySentinel() {
 async function testLoadWithMissingSentinel() {
  const testName = "loadAdvisorySuppression: missing sentinel returns empty config";
  try {
-    const configFile = path.join(tempDir, "no-sentinel.json");
+    const configFile = path.join(tempDir.path, "no-sentinel.json");
    await fs.writeFile(configFile, JSON.stringify({
      suppressions: [{
        checkId: "CVE-2026-25593",
@@ -239,7 +216,7 @@ async function testLoadWithMissingSentinel() {
 async function testLoadWithAuditOnlySentinel() {
  const testName = "loadAdvisorySuppression: audit-only sentinel returns empty for advisory";
  try {
-    const configFile = path.join(tempDir, "audit-only.json");
+    const configFile = path.join(tempDir.path, "audit-only.json");
    await fs.writeFile(configFile, JSON.stringify({
      enabledFor: ["audit"],
      suppressions: [{
@@ -264,7 +241,7 @@ async function testLoadWithAuditOnlySentinel() {
 async function testLoadWithBothSentinels() {
  const testName = "loadAdvisorySuppression: both audit+advisory sentinels activates advisory";
  try {
-    const configFile = path.join(tempDir, "both-sentinel.json");
+    const configFile = path.join(tempDir.path, "both-sentinel.json");
    await fs.writeFile(configFile, JSON.stringify({
      enabledFor: ["audit", "advisory"],
      suppressions: [{
@@ -289,7 +266,7 @@ async function testLoadWithBothSentinels() {
 async function testLoadNonexistentExplicitPath() {
  const testName = "loadAdvisorySuppression: explicit nonexistent path throws";
  try {
-    await loadAdvisorySuppression(path.join(tempDir, "does-not-exist.json"));
+    await loadAdvisorySuppression(path.join(tempDir.path, "does-not-exist.json"));
    fail(testName, "Expected error for nonexistent explicit path");
  } catch (error) {
    if (String(error).includes("not found")) {
@@ -328,7 +305,7 @@ async function testLoadNoConfigReturnsEmpty() {
 async function testEnvPathHomeExpansion() {
  const testName = "loadAdvisorySuppression: OPENCLAW_AUDIT_CONFIG expands $HOME";
  try {
-    const configFile = path.join(tempDir, "env-home.json");
+    const configFile = path.join(tempDir.path, "env-home.json");
    await fs.writeFile(configFile, JSON.stringify({
      enabledFor: ["advisory"],
      suppressions: [{
@@ -341,7 +318,7 @@ async function testEnvPathHomeExpansion() {

    const savedConfig = process.env.OPENCLAW_AUDIT_CONFIG;
    const savedHome = process.env.HOME;
-    process.env.HOME = tempDir;
+    process.env.HOME = tempDir.path;
    process.env.OPENCLAW_AUDIT_CONFIG = "$HOME/env-home.json";
    try {
      const config = await loadAdvisorySuppression();
@@ -390,7 +367,7 @@ async function testEscapedHomeTokenRejected() {
 async function runAllTests() {
  console.log("=== Advisory Suppression Tests ===\n");

-  await setupTestDir();
+  tempDir = await createTempDir();

  try {
    // isAdvisorySuppressed tests
@@ -412,15 +389,11 @@ async function runAllTests() {
    await testEnvPathHomeExpansion();
    await testEscapedHomeTokenRejected();
  } finally {
-    await cleanupTestDir();
+    await tempDir.cleanup();
  }

-  console.log("");
-  console.log(`=== Results: ${passCount} passed, ${failCount} failed ===`);
-
-  if (failCount > 0) {
-    process.exit(1);
-  }
+  report();
+  exitWithResults();
 }

 runAllTests().catch((err) => {
@@ -14,9 +14,17 @@

 import crypto from "node:crypto";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  pass,
+  fail,
+  report,
+  exitWithResults,
+  generateEd25519KeyPair,
+  signPayload,
+  createTempDir,
+} from "./lib/test_harness.mjs";

 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const LIB_PATH = path.resolve(__dirname, "..", "hooks", "clawsec-advisory-guardian", "lib");
@@ -26,33 +34,7 @@ const { verifySignedPayload, loadLocalFeed, isValidFeedPayload } = await import(
  `${LIB_PATH}/feed.mjs`
 );

-let tempDir;
-let passCount = 0;
-let failCount = 0;
-
-function pass(name) {
-  passCount++;
-  console.log(`✓ ${name}`);
-}
-
-function fail(name, error) {
-  failCount++;
-  console.error(`✗ ${name}`);
-  console.error(`  ${String(error)}`);
-}
-
-function generateEd25519KeyPair() {
-  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
-  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
-  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
-  return { publicKeyPem, privateKeyPem };
-}
-
-function signPayload(data, privateKeyPem) {
-  const privateKey = crypto.createPrivateKey(privateKeyPem);
-  const signature = crypto.sign(null, Buffer.from(data, "utf8"), privateKey);
-  return signature.toString("base64");
-}
+let tempDirCleanup;

 function createValidFeed() {
  return JSON.stringify(
@@ -88,16 +70,6 @@ function createChecksumManifest(files) {
  );
 }

-async function setupTestDir() {
-  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawsec-test-"));
-}
-
-async function cleanupTestDir() {
-  if (tempDir) {
-    await fs.rm(tempDir, { recursive: true, force: true });
-  }
-}
-
 // -----------------------------------------------------------------------------
 // Test: verifySignedPayload - valid signature
 // -----------------------------------------------------------------------------
@@ -252,11 +224,11 @@ async function testLoadLocalFeed_ValidSignedFeed() {
    const checksumSignature = signPayload(checksumManifest, privateKeyPem);

    // Write files
-    const feedPath = path.join(tempDir, "feed.json");
-    const sigPath = path.join(tempDir, "feed.json.sig");
-    const checksumPath = path.join(tempDir, "checksums.json");
-    const checksumSigPath = path.join(tempDir, "checksums.json.sig");
-    const keyPath = path.join(tempDir, "feed-signing-public.pem");
+    const feedPath = path.join(globalThis.__testTempDir, "feed.json");
+    const sigPath = path.join(globalThis.__testTempDir, "feed.json.sig");
+    const checksumPath = path.join(globalThis.__testTempDir, "checksums.json");
+    const checksumSigPath = path.join(globalThis.__testTempDir, "checksums.json.sig");
+    const keyPath = path.join(globalThis.__testTempDir, "feed-signing-public.pem");

    await fs.writeFile(feedPath, feedContent);
    await fs.writeFile(sigPath, feedSignature + "\n");
@@ -293,7 +265,7 @@ async function testLoadLocalFeed_AdvisoriesPrefixedChecksumKeys() {
    const feedContent = createValidFeed();
    const feedSignature = signPayload(feedContent, privateKeyPem);

-    const advisoriesDir = path.join(tempDir, "advisories");
+    const advisoriesDir = path.join(globalThis.__testTempDir, "advisories");
    await fs.mkdir(advisoriesDir, { recursive: true });

    const checksumManifest = createChecksumManifest({
@@ -347,8 +319,8 @@ async function testLoadLocalFeed_TamperedFeedFails() {
    // Tamper with feed after signing
    const tamperedFeed = feedContent.replace("TEST-001", "TAMPERED-001");

-    const feedPath = path.join(tempDir, "tampered-feed.json");
-    const sigPath = path.join(tempDir, "tampered-feed.json.sig");
+    const feedPath = path.join(globalThis.__testTempDir, "tampered-feed.json");
+    const sigPath = path.join(globalThis.__testTempDir, "tampered-feed.json.sig");

    await fs.writeFile(feedPath, tamperedFeed);
    await fs.writeFile(sigPath, feedSignature + "\n");
@@ -383,8 +355,8 @@ async function testLoadLocalFeed_MissingSignatureFails() {
    const { publicKeyPem } = generateEd25519KeyPair();
    const feedContent = createValidFeed();

-    const feedPath = path.join(tempDir, "nosig-feed.json");
-    const sigPath = path.join(tempDir, "nosig-feed.json.sig");
+    const feedPath = path.join(globalThis.__testTempDir, "nosig-feed.json");
+    const sigPath = path.join(globalThis.__testTempDir, "nosig-feed.json.sig");

    await fs.writeFile(feedPath, feedContent);
    // Don't write signature file
@@ -418,7 +390,7 @@ async function testLoadLocalFeed_AllowUnsignedBypasses() {
  try {
    const feedContent = createValidFeed();

-    const feedPath = path.join(tempDir, "unsigned-feed.json");
+    const feedPath = path.join(globalThis.__testTempDir, "unsigned-feed.json");
    await fs.writeFile(feedPath, feedContent);

    const feed = await loadLocalFeed(feedPath, {
@@ -462,10 +434,10 @@ async function testLoadLocalFeed_ChecksumMismatchFails() {
    );
    const checksumSignature = signPayload(badChecksumManifest, privateKeyPem);

-    const feedPath = path.join(tempDir, "badcs-feed.json");
-    const sigPath = path.join(tempDir, "badcs-feed.json.sig");
-    const checksumPath = path.join(tempDir, "badcs-checksums.json");
-    const checksumSigPath = path.join(tempDir, "badcs-checksums.json.sig");
+    const feedPath = path.join(globalThis.__testTempDir, "badcs-feed.json");
+    const sigPath = path.join(globalThis.__testTempDir, "badcs-feed.json.sig");
+    const checksumPath = path.join(globalThis.__testTempDir, "badcs-checksums.json");
+    const checksumSigPath = path.join(globalThis.__testTempDir, "badcs-checksums.json.sig");

    await fs.writeFile(feedPath, feedContent);
    await fs.writeFile(sigPath, feedSignature + "\n");
@@ -580,7 +552,11 @@ async function testIsValidFeedPayload_AdvisoryMissingId() {
 async function runTests() {
  console.log("=== ClawSec Feed Verification Tests ===\n");

-  await setupTestDir();
+  const tempDir = await createTempDir();
+  tempDirCleanup = tempDir.cleanup;
+
+  // Store temp dir path in module scope for tests to access
+  globalThis.__testTempDir = tempDir.path;

  try {
    // Signature verification tests
@@ -604,14 +580,11 @@ async function runTests() {
    await testIsValidFeedPayload_MissingVersion();
    await testIsValidFeedPayload_AdvisoryMissingId();
  } finally {
-    await cleanupTestDir();
+    await tempDirCleanup();
  }

-  console.log(`\n=== Results: ${passCount} passed, ${failCount} failed ===`);
-
-  if (failCount > 0) {
-    process.exit(1);
-  }
+  report();
+  exitWithResults();
 }

 runTests().catch((error) => {
@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import fc from "fast-check";
+import { parseAffectedSpecifier } from "../hooks/clawsec-advisory-guardian/lib/feed.mjs";
+import { normalizeSkillName, resolveConfiguredPath, uniqueStrings } from "../hooks/clawsec-advisory-guardian/lib/utils.mjs";
+
+const SAFE_SEGMENT = fc
+  .array(fc.constantFrom(...("abcdefghijklmnopqrstuvwxyz0123456789-_")), { minLength: 1, maxLength: 24 })
+  .map((chars) => chars.join(""));
+
+/**
+ * Runs property-based fuzz checks for advisory parsing and utility behavior.
+ */
+export function runFuzzProperties() {
+  fc.assert(
+    fc.property(fc.string(), (raw) => {
+      const expected = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+      assert.equal(normalizeSkillName(raw), expected);
+    }),
+    { numRuns: 300 },
+  );
+
+  fc.assert(
+    fc.property(fc.array(fc.string(), { maxLength: 40 }), (values) => {
+      const deduped = uniqueStrings(values);
+      assert.deepEqual(deduped, Array.from(new Set(values)));
+    }),
+    { numRuns: 200 },
+  );
+
+  fc.assert(
+    fc.property(fc.string(), fc.string(), (left, right) => {
+      const rawSpecifier = `${left}@${right}`;
+      const specifier = rawSpecifier.trim();
+      const parsed = parseAffectedSpecifier(rawSpecifier);
+      assert.ok(parsed !== null);
+
+      const atIndex = specifier.lastIndexOf("@");
+      if (atIndex <= 0) {
+        assert.equal(parsed.name, specifier);
+        assert.equal(parsed.versionSpec, "*");
+      } else {
+        assert.equal(parsed.name, specifier.slice(0, atIndex));
+        assert.equal(parsed.versionSpec, specifier.slice(atIndex + 1));
+      }
+    }),
+    { numRuns: 300 },
+  );
+
+  fc.assert(
+    fc.property(SAFE_SEGMENT, (suffix) => {
+      const fallback = `/tmp/clawsec-suite/${suffix}`;
+      const resolved = resolveConfiguredPath(`\\$HOME/${suffix}`, fallback, {
+        label: "FUZZ_PATH",
+      });
+      assert.equal(resolved, path.normalize(fallback));
+    }),
+    { numRuns: 200 },
+  );
+}
@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Property-based fuzzing checks for core advisory parsing/path helpers.
+ *
+ * Run: node skills/clawsec-suite/test/fuzz_properties.test.mjs
+ */
+
+import { pass, fail, report, exitWithResults } from "./lib/test_harness.mjs";
+import { runFuzzProperties } from "./fuzz_properties.js";
+
+console.log("=== ClawSec Fast-Check Fuzz Properties ===\n");
+
+try {
+  runFuzzProperties();
+  pass("Property-based fuzz tests");
+} catch (error) {
+  fail("Property-based fuzz tests", error);
+}
+
+report();
+exitWithResults();
@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/**
+ * Property-based fuzz tests for semver matching, advisory scope, and suppression matching.
+ *
+ * Run: node skills/clawsec-suite/test/fuzz_semver_scope_suppression.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import fc from "fast-check";
+import { advisoryAppliesToOpenclaw } from "../hooks/clawsec-advisory-guardian/lib/advisory_scope.mjs";
+import { isAdvisorySuppressed } from "../hooks/clawsec-advisory-guardian/lib/suppression.mjs";
+import { compareSemver, parseSemver, versionMatches } from "../hooks/clawsec-advisory-guardian/lib/version.mjs";
+
+const semverCoreArb = fc.tuple(
+  fc.integer({ min: 0, max: 999 }),
+  fc.integer({ min: 0, max: 999 }),
+  fc.integer({ min: 0, max: 999 }),
+);
+
+const semverArb = semverCoreArb.map(([major, minor, patch]) => `${major}.${minor}.${patch}`);
+const idArb = fc.string({ minLength: 1, maxLength: 24 });
+const skillArb = fc.string({ minLength: 1, maxLength: 24 });
+
+function runSemverProperties() {
+  fc.assert(
+    fc.property(semverCoreArb, ([major, minor, patch]) => {
+      const version = `v${major}.${minor}.${patch}`;
+      assert.deepEqual(parseSemver(version), [major, minor, patch]);
+    }),
+    { numRuns: 250 },
+  );
+
+  fc.assert(
+    fc.property(semverArb, semverArb, (left, right) => {
+      const leftVsRight = compareSemver(left, right);
+      const rightVsLeft = compareSemver(right, left);
+      assert.notEqual(leftVsRight, null);
+      assert.notEqual(rightVsLeft, null);
+      assert.equal(leftVsRight, -rightVsLeft);
+    }),
+    { numRuns: 250 },
+  );
+
+  fc.assert(
+    fc.property(semverArb, semverArb, (left, right) => {
+      const compared = compareSemver(left, right);
+      assert.notEqual(compared, null);
+
+      assert.equal(versionMatches(left, `>=${right}`), compared >= 0);
+      assert.equal(versionMatches(left, `<=${right}`), compared <= 0);
+      assert.equal(versionMatches(left, `>${right}`), compared > 0);
+      assert.equal(versionMatches(left, `<${right}`), compared < 0);
+      assert.equal(versionMatches(left, `=${right}`), compared === 0);
+    }),
+    { numRuns: 250 },
+  );
+}
+
+function runAdvisoryScopeProperties() {
+  fc.assert(
+    fc.property(fc.string(), (application) => {
+      const normalized = application.trim().toLowerCase();
+      const expected = normalized === "" || normalized === "openclaw" || normalized === "all";
+      assert.equal(advisoryAppliesToOpenclaw({ application }), expected);
+    }),
+    { numRuns: 250 },
+  );
+
+  fc.assert(
+    fc.property(fc.array(fc.string(), { maxLength: 8 }), (applications) => {
+      const normalized = applications
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean);
+      const expected =
+        normalized.length === 0 || normalized.includes("openclaw") || normalized.includes("all");
+      assert.equal(advisoryAppliesToOpenclaw({ application: applications }), expected);
+    }),
+    { numRuns: 250 },
+  );
+
+  assert.equal(advisoryAppliesToOpenclaw({}), true);
+  assert.equal(advisoryAppliesToOpenclaw({ application: null }), true);
+}
+
+function runSuppressionProperties() {
+  fc.assert(
+    fc.property(idArb, skillArb, (id, skill) => {
+      const match = {
+        advisory: { id },
+        skill: { name: skill.toUpperCase() },
+      };
+      const suppressions = [
+        {
+          checkId: id,
+          skill: skill.toLowerCase(),
+          reason: "fuzz",
+          suppressedAt: "2026-02-25",
+        },
+      ];
+      assert.equal(isAdvisorySuppressed(match, suppressions), true);
+    }),
+    { numRuns: 250 },
+  );
+
+  fc.assert(
+    fc.property(idArb, idArb, skillArb, (targetId, otherId, skill) => {
+      const differentId = targetId === otherId ? `${otherId}-x` : otherId;
+      const match = {
+        advisory: { id: targetId },
+        skill: { name: skill },
+      };
+      const suppressions = [
+        {
+          checkId: differentId,
+          skill,
+          reason: "fuzz",
+          suppressedAt: "2026-02-25",
+        },
+      ];
+      assert.equal(isAdvisorySuppressed(match, suppressions), false);
+    }),
+    { numRuns: 250 },
+  );
+}
+
+try {
+  console.log("=== ClawSec Semver/Scope/Suppression Fuzz Properties ===\n");
+  runSemverProperties();
+  runAdvisoryScopeProperties();
+  runSuppressionProperties();
+  console.log("=== Results: all fuzz properties passed ===");
+} catch (error) {
+  console.error("Fuzz property test failed:");
+  console.error(error);
+  process.exit(1);
+}
@@ -18,37 +18,19 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import {
+  pass,
+  fail,
+  report,
+  exitWithResults,
+  generateEd25519KeyPair,
+  signPayload,
+} from "./lib/test_harness.mjs";

 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCRIPT_PATH = path.resolve(__dirname, "..", "scripts", "guarded_skill_install.mjs");

 let tempDir;
-let passCount = 0;
-let failCount = 0;
-
-function pass(name) {
-  passCount++;
-  console.log(`✓ ${name}`);
-}
-
-function fail(name, error) {
-  failCount++;
-  console.error(`✗ ${name}`);
-  console.error(`  ${String(error)}`);
-}
-
-function generateEd25519KeyPair() {
-  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
-  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
-  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
-  return { publicKeyPem, privateKeyPem };
-}
-
-function signPayload(data, privateKeyPem) {
-  const privateKey = crypto.createPrivateKey(privateKeyPem);
-  const signature = crypto.sign(null, Buffer.from(data, "utf8"), privateKey);
-  return signature.toString("base64");
-}

 function createFeed(advisories) {
  return JSON.stringify(
@@ -416,11 +398,8 @@ async function runTests() {
    await cleanupTestDir();
  }

-  console.log(`\n=== Results: ${passCount} passed, ${failCount} failed ===`);
-
-  if (failCount > 0) {
-    process.exit(1);
-  }
+  report();
+  exitWithResults();
 }

 runTests().catch((error) => {
--- a/Show More
+++ b/Show More