clawarmor 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## [3.2.0] — 2026-03-03
+
+### New Features
+
+#### `clawarmor scan --json`
+- Added `--json` flag to `clawarmor scan`
+- Outputs a clean JSON object to stdout with: `verdict` (PASS/WARN/BLOCK), `score`, `totalSkills`, `flaggedSkills`, `findings[]`, `scannedAt`
+- Verdict rules: BLOCK if any CRITICAL findings, WARN if any HIGH findings, PASS otherwise
+- Designed for scripting and CI/CD integration (pipe to `jq`, parse in shell scripts)
+
+#### `clawarmor baseline` command
+- New command: `clawarmor baseline save [--name <label>]` — saves current audit result as a named baseline to `~/.openclaw/workspace/memory/clawarmor-baselines/`
+- `clawarmor baseline list` — lists all saved baselines with date and score
+- `clawarmor baseline diff [--from <label>] [--to <label>]` — diffs two baselines showing score delta, new findings, and resolved findings
+- Enables tracking security posture over time and catching regressions after skill installs
+
+#### `clawarmor incident` command
+- New command: `clawarmor incident create --finding <description> --severity <CRITICAL|HIGH|MEDIUM> [--action <quarantine|rollback|notify>]`
+- Creates a structured markdown incident log at `~/.openclaw/workspace/memory/incidents/YYYY-MM-DD-<slug>.md`
+- `--action rollback` automatically triggers config rollback via existing snapshot system
+- `clawarmor incident list` — lists all logged incidents with date and severity
+
+#### `clawarmor skill verify <skill-dir>`
+- New command that validates a skill directory against ClawGear publishing standards
+- Checks: SKILL.md presence, no hardcoded credentials, no obfuscation, permissions declared if exec used, no fetches to unknown hosts, description in frontmatter
+- Exit codes: 0=VERIFIED, 1=WARN, 2=BLOCK
+- Human-readable output with emoji status per check
+
+### ClawGear Security Skills
+- Added 4 security skill SKILL.md files in `clawgear-skills/`:
+  - `clawarmor-live-monitor` — heartbeat monitoring with Telegram alerts on score drops
+  - `skill-security-scanner` — pre-install gate for skills using `scan --json`
+  - `hardened-operator-baseline` — 3-command full hardening sequence
+  - `incident-response-playbook` — automated incident response with rollback + alerting
+
+---
+
+## [3.1.0] — 2026-02-XX
+
+- Stack honesty fix + post-install audit + contextual profiles
+
+## [3.0.1] — 2026-02-XX
+
+- README rewrite — control plane positioning, stack orchestration docs
+
+## [3.0.0] — 2026-02-XX
+
+- Stack orchestrator — Invariant + IronCurtain integration
+
+## [2.2.1] — 2026-01-XX
+
+- Fix npm bloat (6.2MB→273KB), clean up README with v2.2 features
+
+## [2.2.0] — 2026-01-XX
+
+- Config snapshots + rollback, monitor mode for harden

package/clawgear-skills/clawarmor-live-monitor/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: clawarmor-live-monitor
+description: Monitors your OpenClaw agent security posture on every heartbeat. Diffs against a saved baseline and sends a Telegram alert if your score drops (e.g., after installing a new skill). Uses clawarmor baseline diff under the hood.
+category: security
+tags: [security, monitoring, heartbeat, clawarmor]
+requires: clawarmor >= 3.2.0
+---
+
+# clawarmor-live-monitor
+
+Monitors your OpenClaw agent's security posture on every heartbeat cycle. After a new skill is installed, your score can silently drop — this skill catches that and alerts you before it becomes a problem.
+
+## What it does
+
+On every heartbeat, this skill:
+1. Saves the current security posture as a `current` baseline
+2. Diffs it against the saved `initial` baseline
+3. If the score dropped by more than 5 points, fires a Telegram alert via `openclaw system event`
+
+It uses `clawarmor baseline diff` under the hood — no custom scoring logic, just wiring.
+
+## Why it matters
+
+You install a skill, it looks fine. But it quietly adds an exec call or an outbound network fetch that ClawArmor would flag. Without continuous monitoring, you'd never know until the next manual audit. This skill closes that gap.
+
+---
+
+## Scripts
+
+### `baseline-init.sh`
+
+Run this once on first install to save your initial baseline.
+
+```bash
+#!/usr/bin/env bash
+# baseline-init.sh — save initial security baseline
+set -e
+
+echo "[clawarmor-live-monitor] Saving initial baseline..."
+clawarmor baseline save --name initial
+echo "[clawarmor-live-monitor] Initial baseline saved."
+echo "Now paste heartbeat-fragment.md into your HEARTBEAT.md to enable continuous monitoring."
+```
+
+### `monitor.sh`
+
+Run on every heartbeat to check for score regressions.
+
+```bash
+#!/usr/bin/env bash
+# monitor.sh — diff current posture against initial baseline
+set -e
+
+SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Save current posture
+clawarmor baseline save --name current
+
+# Diff against initial
+DIFF_OUTPUT=$(clawarmor baseline diff --from initial --to current 2>&1)
+SCORE_DELTA=$(echo "$DIFF_OUTPUT" | grep -oP 'Delta:\s*\K[+-]?\d+' | head -1)
+
+echo "[clawarmor-live-monitor] Score delta: ${SCORE_DELTA:-0}"
+
+# Alert if score dropped more than 5 points
+if [ -n "$SCORE_DELTA" ] && [ "$SCORE_DELTA" -lt -5 ]; then
+  openclaw system event \
+    --text "⚠️ ClawArmor score dropped ${SCORE_DELTA} points since initial baseline. Run: clawarmor audit" \
+    --mode now
+  echo "[clawarmor-live-monitor] Alert sent."
+fi
+```
+
+### `heartbeat-fragment.md`
+
+Paste this snippet into your `HEARTBEAT.md` to enable automatic monitoring:
+
+```markdown
+## Security Monitor
+
+Run bash monitor.sh from skills/clawarmor-live-monitor/ — if score dropped, alert Alberto.
+```
+
+---
+
+## Setup
+
+1. **Install ClawArmor 3.2.0+**: `npm install -g clawarmor`
+2. **Save your initial baseline** (run once):
+   ```bash
+   bash ~/.openclaw/workspace/skills/clawarmor-live-monitor/baseline-init.sh
+   ```
+3. **Enable heartbeat monitoring** — paste the contents of `heartbeat-fragment.md` into your `HEARTBEAT.md`
+
+That's it. On every heartbeat, your score will be checked against the initial baseline.
+
+---
+
+## Manual usage
+
+```bash
+# Check current posture vs initial baseline
+bash ~/.openclaw/workspace/skills/clawarmor-live-monitor/monitor.sh
+
+# See all saved baselines
+clawarmor baseline list
+
+# Detailed diff
+clawarmor baseline diff --from initial --to current
+```
+
+---
+
+## Notes
+
+- Requires clawarmor 3.2.0+ for the `baseline` commands
+- The `current` baseline is overwritten on every heartbeat — it tracks the most recent posture only
+- The `initial` baseline persists until you re-run `baseline-init.sh`
+- Alert threshold is hardcoded at -5 points; edit `monitor.sh` to adjust
+- Telegram delivery requires `openclaw system event` to be configured with a Telegram channel

package/clawgear-skills/hardened-operator-baseline/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: hardened-operator-baseline
+description: Full ClawArmor hardening in 3 commands. Detects your operator role (coding/browsing/messaging), applies contextual hardening, deploys Invariant + IronCurtain stack, saves a security baseline, and writes a SECURITY_RUNBOOK.md to your workspace. One-time setup for production-grade security posture.
+category: security
+tags: [security, hardening, baseline, clawarmor, invariant, ironcurtain]
+requires: clawarmor >= 3.2.0
+---
+
+# hardened-operator-baseline
+
+Production-grade security hardening in 3 commands. Run this once to go from default OpenClaw config to a hardened, monitored, documented security posture.
+
+## What it does
+
+1. **Detects your operator role** (`clawarmor profile detect`) — coding, browsing, or messaging
+2. **Applies contextual hardening** (`clawarmor harden --profile <detected>`) — tightens the settings that matter for your role without breaking your workflow
+3. **Deploys the security stack and saves a baseline** (`clawarmor stack deploy && clawarmor baseline save --name post-harden`) — Invariant flow guardrails + IronCurtain instruction boundaries + a snapshot of your hardened posture
+
+After running, a `SECURITY_RUNBOOK.md` is written to your workspace documenting what was done and how to respond to incidents.
+
+---
+
+## The 3 commands
+
+```bash
+# Step 1: Detect your operator role
+clawarmor profile detect
+
+# Step 2: Apply contextual hardening (replace <profile> with detected value)
+clawarmor harden --profile <profile>
+
+# Step 3: Deploy security stack and save baseline
+clawarmor stack deploy && clawarmor baseline save --name post-harden
+```
+
+---
+
+## Script
+
+### `setup.sh`
+
+Runs all 3 steps in sequence and writes `SECURITY_RUNBOOK.md` to your workspace.
+
+```bash
+#!/usr/bin/env bash
+# setup.sh — full ClawArmor hardening sequence
+# Run once to set up production-grade security posture
+
+set -e
+
+WORKSPACE="$HOME/.openclaw/workspace"
+RUNBOOK="$WORKSPACE/SECURITY_RUNBOOK.md"
+
+echo ""
+echo "=== ClawArmor Hardened Operator Baseline ==="
+echo ""
+
+# Step 1: Detect profile
+echo "[1/3] Detecting operator profile..."
+PROFILE=$(clawarmor profile detect 2>/dev/null | grep -oP 'Detected:\s*\K\w+' | head -1)
+if [ -z "$PROFILE" ]; then
+  PROFILE="general"
+  echo "  Profile detection failed — using 'general'"
+else
+  echo "  Detected profile: $PROFILE"
+fi
+
+# Step 2: Apply hardening
+echo ""
+echo "[2/3] Applying contextual hardening (profile: $PROFILE)..."
+clawarmor harden --profile "$PROFILE" --auto
+echo "  Hardening applied."
+
+# Step 3: Deploy stack and save baseline
+echo ""
+echo "[3/3] Deploying security stack and saving baseline..."
+clawarmor stack deploy
+clawarmor baseline save --name post-harden
+SCORE=$(clawarmor baseline list 2>/dev/null | grep -A2 'post-harden' | grep -oP 'Score:\s*\K[\d]+' | head -1)
+SCORE="${SCORE:-unknown}"
+echo "  Stack deployed. Baseline saved. Score: $SCORE/100"
+
+# Write SECURITY_RUNBOOK.md
+DATE=$(date +%Y-%m-%d)
+mkdir -p "$WORKSPACE"
+
+cat > "$RUNBOOK" << EOF
+# Security Runbook
+**Hardened:** $DATE
+**Profile:** $PROFILE
+**Score:** $SCORE/100
+**Stack:** Invariant + IronCurtain
+
+## What's Protected
+- Config locked via clawarmor harden
+- Runtime guardrails via Invariant
+- Instruction boundaries via IronCurtain
+
+## Incident Response
+1. Run: clawarmor audit
+2. Check: clawarmor incident list
+3. If CRITICAL: clawarmor rollback && clawarmor incident create --finding "..." --severity CRITICAL
+
+## Contacts
+- ClawArmor docs: github.com/pinzasai/clawarmor
+- ClawGear support: clawgear.io
+EOF
+
+echo ""
+echo "=== Done ==="
+echo ""
+echo "  SECURITY_RUNBOOK.md written to: $RUNBOOK"
+echo "  Baseline saved as: post-harden"
+echo "  Score: $SCORE/100"
+echo ""
+echo "  Next steps:"
+echo "  - Review SECURITY_RUNBOOK.md"
+echo "  - Run 'clawarmor audit' anytime to check current posture"
+echo "  - Run 'clawarmor baseline diff --from post-harden --to <new>' to track changes"
+echo ""
+```
+
+---
+
+## After running
+
+Your workspace will contain:
+- **`SECURITY_RUNBOOK.md`** — incident response procedures, what's protected, contacts
+- **`post-harden` baseline** — snapshot of your hardened posture for future diffs
+
+```bash
+# Check posture after any config changes
+clawarmor baseline save --name $(date +%Y-%m-%d) && \
+  clawarmor baseline diff --from post-harden --to $(date +%Y-%m-%d)
+```
+
+---
+
+## SECURITY_RUNBOOK.md template
+
+The script generates this file automatically. You can also create it manually:
+
+```markdown
+# Security Runbook
+**Hardened:** <date>
+**Profile:** <profile>
+**Score:** <score>/100
+**Stack:** Invariant + IronCurtain
+
+## What's Protected
+- Config locked via clawarmor harden
+- Runtime guardrails via Invariant
+- Instruction boundaries via IronCurtain
+
+## Incident Response
+1. Run: clawarmor audit
+2. Check: clawarmor incident list
+3. If CRITICAL: clawarmor rollback && clawarmor incident create --finding "..." --severity CRITICAL
+
+## Contacts
+- ClawArmor docs: github.com/pinzasai/clawarmor
+- ClawGear support: clawgear.io
+```
+
+---
+
+## Notes
+
+- Run `clawarmor baseline save` after any significant config changes to keep your diff history meaningful
+- The `--auto` flag on harden applies SAFE and CAUTION fixes without prompting — omit it if you want to review each fix interactively
+- Stack deploy requires Invariant and IronCurtain to be available in your environment
+- Requires clawarmor 3.2.0+ for baseline commands

package/clawgear-skills/incident-response-playbook/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: incident-response-playbook
+description: Automated incident response for OpenClaw agents. When clawarmor audit finds a CRITICAL or HIGH finding, this playbook quarantines the affected extension, rolls back config to the last known-good snapshot, creates a structured incident log, and sends a Telegram alert. The action layer on top of ClawArmor detection.
+category: security
+tags: [security, incident-response, clawarmor, automation]
+requires: clawarmor >= 3.2.0
+---
+
+# incident-response-playbook
+
+ClawArmor detects security issues. This skill responds to them. Automatically.
+
+When a CRITICAL finding is detected, the playbook:
+1. **Quarantines** the affected extension
+2. **Rolls back** config to the last known-good snapshot
+3. **Creates a structured incident log** via `clawarmor incident create`
+4. **Sends a Telegram alert** via `openclaw system event`
+
+Designed to run from your HEARTBEAT.md so it fires automatically on every cycle.
+
+---
+
+## Scripts
+
+### `quarantine.sh`
+
+Disables a named extension and restarts the gateway.
+
+```bash
+#!/usr/bin/env bash
+# quarantine.sh — disable an extension immediately
+# Usage: bash quarantine.sh <extension-name>
+# requires: elevated
+
+EXTENSION="$1"
+
+if [ -z "$EXTENSION" ]; then
+  echo "Usage: bash quarantine.sh <extension-name>"
+  exit 1
+fi
+
+echo "[quarantine] Disabling extension: $EXTENSION"
+openclaw config set "extensions.${EXTENSION}.disabled" true
+openclaw gateway restart
+
+echo "[quarantine] Extension '$EXTENSION' quarantined. Gateway restarted."
+```
+
+### `respond.sh`
+
+Full automated incident response: rollback, incident log, Telegram alert.
+
+```bash
+#!/usr/bin/env bash
+# respond.sh — full incident response for a security finding
+# Usage: bash respond.sh "<finding-description>" <CRITICAL|HIGH|MEDIUM>
+# requires: clawarmor >= 3.2.0, elevated
+
+FINDING="$1"
+SEVERITY="${2:-CRITICAL}"
+
+if [ -z "$FINDING" ]; then
+  echo "Usage: bash respond.sh \"<finding-description>\" <CRITICAL|HIGH|MEDIUM>"
+  exit 1
+fi
+
+echo ""
+echo "[respond] Incident Response Triggered"
+echo "[respond] Finding: $FINDING"
+echo "[respond] Severity: $SEVERITY"
+echo ""
+
+# Step 1: Rollback config
+echo "[respond] Rolling back to last known-good snapshot..."
+ROLLBACK_OUTPUT=$(clawarmor rollback 2>&1)
+ROLLBACK_STATUS=$?
+
+if [ $ROLLBACK_STATUS -ne 0 ]; then
+  echo "[respond] WARNING: Rollback failed or no snapshots available."
+  echo "[respond] Operator must review config manually."
+  ROLLBACK_NOTE="Rollback failed — manual review required"
+else
+  echo "[respond] Config rolled back."
+  ROLLBACK_NOTE="Config rolled back via clawarmor rollback"
+fi
+
+# Step 2: Create incident log
+echo "[respond] Creating incident log..."
+INCIDENT_FILE=$(clawarmor incident create \
+  --finding "$FINDING" \
+  --severity "$SEVERITY" \
+  --action rollback \
+  2>&1 | grep "File:" | awk '{print $2}')
+echo "[respond] Incident logged: ${INCIDENT_FILE:-unknown}"
+
+# Step 3: Send Telegram alert
+echo "[respond] Sending alert..."
+openclaw system event \
+  --text "🚨 Security Incident: $FINDING (Severity: $SEVERITY) — Config rolled back. Check: clawarmor incident list" \
+  --mode now
+
+echo ""
+echo "[respond] Done. Incident response complete."
+echo ""
+```
+
+### `check-and-respond.sh`
+
+Runs `clawarmor audit --json`, finds CRITICAL findings, auto-triggers `respond.sh` for each.
+
+```bash
+#!/usr/bin/env bash
+# check-and-respond.sh — auto-respond to new CRITICAL findings
+# Add to HEARTBEAT.md to run automatically on every cycle
+# requires: clawarmor >= 3.2.0, elevated
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "[check-and-respond] Running security audit..."
+AUDIT_JSON=$(clawarmor audit --json 2>/dev/null || echo '{"failed":[]}')
+
+# Extract CRITICAL findings
+CRITICALS=$(echo "$AUDIT_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+failed = d.get('failed', [])
+for f in failed:
+    if f.get('severity') == 'CRITICAL' and not f.get('_profileExpected'):
+        print(f.get('title', f.get('id', 'Unknown finding')))
+" 2>/dev/null)
+
+if [ -z "$CRITICALS" ]; then
+  echo "[check-and-respond] No CRITICAL findings. Posture clean."
+  exit 0
+fi
+
+echo "[check-and-respond] CRITICAL findings detected — triggering response..."
+echo ""
+
+while IFS= read -r finding; do
+  if [ -n "$finding" ]; then
+    echo "[check-and-respond] Responding to: $finding"
+    bash "$SCRIPT_DIR/respond.sh" "$finding" "CRITICAL"
+  fi
+done <<< "$CRITICALS"
+
+echo "[check-and-respond] All findings processed."
+```
+
+---
+
+## Heartbeat integration
+
+Add this to your `HEARTBEAT.md` to auto-respond to new CRITICAL findings on every cycle:
+
+```markdown
+## Security Incident Response
+
+Run bash check-and-respond.sh from skills/incident-response-playbook/ — automatically respond to any CRITICAL security findings found during audit.
+```
+
+---
+
+## Manual usage
+
+```bash
+# Respond to a specific finding manually
+bash ~/.openclaw/workspace/skills/incident-response-playbook/respond.sh \
+  "Malicious skill detected: bad-skill-v2" \
+  CRITICAL
+
+# Quarantine a specific extension
+bash ~/.openclaw/workspace/skills/incident-response-playbook/quarantine.sh \
+  bad-extension-name
+
+# Run audit and auto-respond to everything critical
+bash ~/.openclaw/workspace/skills/incident-response-playbook/check-and-respond.sh
+```
+
+---
+
+## Notes
+
+- **Rollback** uses ClawArmor's snapshot system (`clawarmor rollback`). If no snapshot exists (e.g., hardening was never run), rollback is skipped and the operator is alerted to review manually
+- **Quarantine** requires `openclaw config set` and `openclaw gateway restart` to be available — these are standard OpenClaw commands
+- **Telegram delivery** requires `openclaw system event` to be configured with a Telegram channel
+- The `--action rollback` flag on `clawarmor incident create` also triggers rollback automatically — `respond.sh` calls both for belt-and-suspenders reliability
+- Requires clawarmor 3.2.0+ for `clawarmor incident` and `clawarmor audit --json`
+- The scripts use `set -e` for fail-fast behavior — if any step errors, the script exits immediately. Check logs if a step is skipped unexpectedly