clawarmor 3.1.0 → 3.4.0

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+## [3.4.0] — 2026-03-08
+
+### New Features
+
+#### `clawarmor harden --report` — Structured Hardening Reports
+Export a portable, structured summary of every hardening run — what was hardened, what was
+skipped, why, and what was already good. The #1 feature gap for enterprise adoption.
+
+**Flags:**
+- `--report [path]` — Write JSON report (default: `~/.openclaw/clawarmor-harden-report-YYYY-MM-DD.json`)
+- `--report-format text` — Write Markdown report instead of JSON
+
+**JSON report structure:**
+```json
+{
+  "version": "3.4.0",
+  "timestamp": "...",
+  "system": { "os": "...", "openclaw_version": "..." },
+  "summary": { "total_checks": N, "hardened": N, "already_good": N, "skipped": N },
+  "items": [
+    { "check": "exec.ask.off", "status": "hardened", "before": "off", "after": "on-miss", "action": "..." },
+    { "check": "gateway.host.open", "status": "skipped", "skipped_reason": "Breaking fix..." }
+  ]
+}
+```
+
+**Examples:**
+```bash
+clawarmor harden --report
+clawarmor harden --report /tmp/my-report.json
+clawarmor harden --report /tmp/report.md --report-format text
+clawarmor harden --auto --report
+```
+
+Existing `clawarmor harden` behavior unchanged when `--report` is not passed.
+
+---
+
+## [3.3.0] — 2026-03-07
+
+### New Features
+
+#### `clawarmor invariant sync` — Invariant Deep Integration
+The Invariant integration in v3.0 detected presence of `invariant-ai`. v3.3.0 does the real work:
+it reads your latest audit findings and generates severity-tiered Invariant DSL policies that
+actually enforce behavioral guardrails at runtime.
+
+**Severity tiers:**
+- `CRITICAL`/`HIGH` findings → `raise "..."` hard enforcement rules (blocks the trace)
+- `MEDIUM` findings → `warn "..."` monitoring/alerting rules (logs but allows)
+- `LOW`/`INFO` findings → `# informational` comments (guidance only)
+
+**Policy mappings (finding → Invariant rule):**
+| Finding type | Generated policy |
+|---|---|
+| `exec.ask=off` / unrestricted exec | `raise` on any `exec` tool call |
+| Credential files world-readable | `raise` on `read_file` to sensitive paths (`.ssh`, `.aws`, `agent-accounts`, `.openclaw`) |
+| Open channel policy (no `allowFrom`) | `raise`/`warn` on `read_file → send_message` without channel restriction |
+| Elevated tool calls unrestricted | `raise`/`warn` on elevated calls with no `allowFrom_restricted` metadata |
+| Skill supply chain / unpinned | `raise`/`warn` on tool calls lacking `skill_verified` or `skill_pinned` metadata |
+| API key/secret in config files | `raise`/`warn` on `read_file` output containing secret patterns → `send_message` |
+| Baseline: prompt injection | `raise` on web content → outbound message (always included) |
+
+**New commands:**
+```
+clawarmor invariant sync                  # generate tiered policies from latest audit
+clawarmor invariant sync --dry-run        # preview without writing
+clawarmor invariant sync --push           # generate + validate + push to Invariant instance
+clawarmor invariant sync --push --host <host> --port <port>
+clawarmor invariant sync --json           # machine-readable output
+clawarmor invariant status                # show current policy file + last sync report
+```
+
+**Policy output:**
+- Policy file: `~/.clawarmor/invariant-policies/clawarmor.inv`
+- Sync report: `~/.clawarmor/invariant-policies/sync-report.json`
+
+**`--push` behavior:**
+1. Validates policy syntax via `LocalPolicy.from_file()` (requires `pip3 install invariant-ai`)
+2. If Invariant instance running on `localhost:8000` → live-reloads policy immediately
+3. If not running → policy written to disk, enforces on next Invariant start
+
+**Relationship to `clawarmor stack`:**
+- `stack deploy/sync` generates basic `.inv` rules in `~/.clawarmor/invariant-rules.inv`
+- `invariant sync` generates richer severity-tiered policies in `~/.clawarmor/invariant-policies/clawarmor.inv`
+- They are complementary; `invariant sync` is the recommended path for serious deployments
+
+---
+
+## [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/README.md

@@ -51,9 +51,11 @@ ClawArmor sits at the foundation and orchestrates the layers above it:
 |---|---|
 | `audit` | Score your OpenClaw config (0–100), live gateway probes, plain-English verdict |
 | `scan` | Scan all installed skill files for malicious code and SKILL.md instructions |
+| `scan --json` | Machine-readable scan output — pipe to CI, scripts, or dashboards |
 | `prescan <skill>` | Pre-scan a skill before installing — blocks on CRITICAL findings |
+| `skill verify <name>` | Deep-verify a specific installed skill — checks SKILL.md + all referenced scripts |
 | `fix` | Auto-apply safe fixes (--dry-run to preview, --apply to run) |
-| `harden` | Interactive hardening wizard (--dry-run, --auto, --monitor) |
+| `harden` | Interactive hardening wizard (--dry-run, --auto, --monitor, --report) |
 | `status` | One-screen security posture dashboard |
 | `verify` | Re-run only previously-failed checks (CI-friendly, exit 0 = all fixed) |
 
@@ -67,6 +69,31 @@ ClawArmor sits at the foundation and orchestrates the layers above it:
 | `stack sync` | Regenerate stack configs from latest audit — run after harden/fix |
 | `stack teardown` | Remove deployed stack components |
 
+### Invariant Deep Integration (v3.3.0)
+
+| Command | Description |
+|---|---|
+| `invariant sync` | Generate severity-tiered Invariant policies from latest audit findings |
+| `invariant sync --dry-run` | Preview policies without writing |
+| `invariant sync --push` | Generate + validate + push to running Invariant instance |
+| `invariant sync --json` | Machine-readable output for scripting |
+| `invariant status` | Show current policy file and last sync report |
+
+**Severity tiers:**
+- `CRITICAL`/`HIGH` findings → `raise "..."` (hard enforcement — blocks trace)
+- `MEDIUM` findings → `warn "..."` (monitoring/alerting — logged)
+- `LOW`/`INFO` findings → `# comment` (informational only)
+
+Policies are written to `~/.clawarmor/invariant-policies/clawarmor.inv`. With `--push`, ClawArmor validates the policy syntax via `invariant-ai` and live-reloads a running Invariant instance. If no instance is running, the policy is written to disk and enforces on next start.
+
+```bash
+pip3 install invariant-ai           # required for --push validation
+clawarmor audit                     # run audit to capture findings
+clawarmor invariant sync            # generate tiered policies
+clawarmor invariant sync --push     # push to running Invariant instance
+clawarmor invariant status          # check what's deployed
+```
+
 ### History & Monitoring
 
 | Command | Description |
@@ -76,6 +103,9 @@ ClawArmor sits at the foundation and orchestrates the layers above it:
 | `log` | View the audit event log |
 | `digest` | Show weekly security digest |
 | `watch` | Monitor config and skill changes in real time |
+| `baseline save` | Save current scan results as baseline |
+| `baseline diff` | Compare current scan against saved baseline — see what changed |
+| `incident create` | Log a security incident with timestamp, findings, and remediation notes |
 | `protect --install` | Install guard hook, shell intercept (zsh/bash/fish), and watch daemon |
 | `snapshot` | Save a config snapshot manually (auto-saved before every harden/fix) |
 | `rollback` | Restore config from auto-snapshot (--list, --id <id>) |
@@ -116,6 +146,24 @@ clawarmor harden --monitor-report # see what it observed
 clawarmor harden --monitor-off    # stop monitoring
 ```
 
+**Hardening reports** (v3.4.0) — Export a structured report after hardening:
+
+```bash
+# Write JSON report to default location (~/.openclaw/clawarmor-harden-report-YYYY-MM-DD.json)
+clawarmor harden --report
+
+# Write JSON report to a custom path
+clawarmor harden --report /path/to/report.json
+
+# Write Markdown report (human-readable, shareable)
+clawarmor harden --report /path/to/report.md --report-format text
+
+# Combine with auto mode
+clawarmor harden --auto --report
+```
+
+Report structure includes: version, timestamp, OS/OpenClaw info, summary counts (hardened/skipped/already-good), and per-check action details with before/after values.
+
 ## Philosophy
 
 ClawArmor runs entirely on your machine — no telemetry, no cloud, no accounts.

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