feat(ruflo-security-audit): adopt plugin contract — AIDefence static/runtime layered integration (ADR-0001)

Plugin already at v0.2.0 with 1 agent + 2 skills + 1 command. The contract pieces were missing. Notable: this plugin's static analysis layer complements ruflo-aidefence's runtime 3-gate pattern. ADR-0001 documents the layered story: | Layer | Owner | What it catches | |------------------|------------------------|------------------------------------------------------------------| | Static analysis | ruflo-security-audit | Shell-injection patterns, CVEs, plaintext secrets, loader-hijack | | Runtime 3-gate | ruflo-aidefence ADR-1 | PII pre-storage, sanitization, prompt-injection | Static analysis finds the patterns; the runtime gates catch what slipped through. The audit_1776853149979 pattern catalog (already in README) is the regression-prevention contract for the shell-injection class the 3.6.25 release closed. - ADR-0001 (Proposed) at docs/adrs/0001-security-audit-contract.md - README adds Compatibility (pin v3.6), AIDefence integration block (static/runtime layered table; cross-reference to ruflo-aidefence ADR-0001), Namespace coordination (claims security-findings; defers to ruflo-agentdb ADR-0001), Verification + Architecture Decisions - plugin.json keywords add mcp, cve-monitoring, policy-gates, shell-injection (already at v0.2.0) - scripts/smoke.sh — 10 structural checks: version + keywords, both skills + agent + command present, v3.6 pin, namespace coordination, security-findings claimed, AIDefence 3-gate cross-reference, audit_1776853149979 pattern catalog intact (execSync, execFileSync, loader-hijack, isSafePackageSpec), ADR-096 encryption cross-reference, ADR Proposed, no wildcard tools Verification: bash plugins/ruflo-security-audit/scripts/smoke.sh → 10/10 Co-Authored-By: RuFlo <ruv@ruv.net>
2026-11-09 22:13:39 +09:00 · 2026-05-04 20:37:35 -04:00
1 parent 414a79d56c
commit c203bc5d88
@@ -13,6 +13,10 @@
    "security",
    "audit",
    "cve",
-    "scanning"
+    "scanning",
+    "mcp",
+    "cve-monitoring",
+    "policy-gates",
+    "shell-injection"
  ]
 }
@@ -34,3 +34,36 @@ A `ruflo verify` round-trip confirms 55 witnesses (27 regression-fix + 28 per-so
 ## Requires

 - `ruflo-core` plugin (provides MCP server)
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-security-audit/scripts/smoke.sh` is the contract.
+
+## AIDefence integration
+
+This plugin's **static** scanning (CVE / dependency / shell-injection patterns) complements the **runtime** gates owned by [ruflo-aidefence ADR-0001](../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md):
+
+| Layer | Owner | What it catches |
+|-------|-------|----------------|
+| **Static analysis** (this plugin) | `ruflo-security-audit` | Shell-injection patterns, dependency CVEs, plaintext secrets at rest, loader-hijack env vars |
+| **Runtime gates** (3-gate pattern) | `ruflo-aidefence` ADR-0001 | PII pre-storage gate, sanitization gate, prompt-injection gate |
+
+The two layers are complementary: static analysis finds the patterns; the 3-gate runtime catches what slipped through.
+
+## Namespace coordination
+
+This plugin owns the `security-findings` AgentDB namespace (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 §"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+`security-findings` indexes scan results by file + commit + severity. Accessed via `memory_*` (namespace-routed).
+
+## Verification
+
+```bash
+bash plugins/ruflo-security-audit/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` — ruflo-security-audit plugin contract (AIDefence integration, audit_1776853149979 pattern catalog as regression-prevention contract)](./docs/adrs/0001-security-audit-contract.md)
@@ -0,0 +1,47 @@
+---
+id: ADR-0001
+title: ruflo-security-audit plugin contract — pinning, namespace coordination, AIDefence + audit_1776853149979 cross-references, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+  - reviewer (Claude Code)
+tags: [plugin, security, audit, cve, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-security-audit` (v0.2.0) — security review + dependency scanning + policy gates + CVE monitoring. 1 agent (`security-auditor`), 2 skills (`security-scan`, `dependency-check`), 1 command (`/audit`).
+
+Drives `npx @claude-flow/cli@latest security scan|audit|cve|threats|validate|report` (CLI commands, not dedicated MCP tools — the security CLI command surface lives in `v3/@claude-flow/cli/src/commands/security.ts`).
+
+Pairs with two sibling contracts:
+
+- **AIDefence** ([ruflo-aidefence ADR-0001](../../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md)) — owns the canonical 3-gate pattern (PII pre-storage, sanitization, prompt-injection). This plugin adds CVE / dependency / shell-injection scanning on top of those runtime gates.
+- **audit_1776853149979 patterns** (existing README block) — class of shell-injection bugs the 3.6.25 release closed. The scanner is the regression-prevention mechanism for that class.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6); Namespace coordination (claims `security-findings`); AIDefence cross-reference block; Verification + Architecture Decisions sections.
+3. Plugin metadata stays at `0.2.0` (already at the cadence). Keywords add `mcp`, `cve-monitoring`, `policy-gates`, `shell-injection`.
+4. `scripts/smoke.sh` — 10 structural checks: version + keywords; both skills + agent + command with valid frontmatter; v3.6 pin; namespace coordination; AIDefence 3-gate cross-reference; audit_1776853149979 pattern catalog intact (execSync template-literals, numeric MCP inputs, package specs, loader-hijack env, plaintext secrets, MCP stdin DoS); ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:** the audit_1776853149979 pattern catalog is now smoke-checked as a regression-prevention contract. Plugin joins the cadence.
+
+**Negative:** none material.
+
+## Verification
+
+```bash
+bash plugins/ruflo-security-audit/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-aidefence/docs/adrs/0001-aidefence-contract.md` — canonical 3-gate runtime pattern this plugin's static analysis complements
+- `plugins/ruflo-jujutsu/docs/adrs/0001-jujutsu-contract.md` — diff analysis substrate this plugin runs on for PR-time auditing
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` — namespace convention
+- `v3/@claude-flow/cli/src/commands/security.ts` — `security scan|audit|cve|threats|validate|report` CLI command surface
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+step() { printf "→ %s ... " "$1"; }
+ok()   { printf "PASS\n"; PASS=$((PASS+1)); }
+bad()  { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
+
+step "1. plugin.json declares 0.2.0 with new keywords"
+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.2.0" ]]; then bad "expected 0.2.0, got '$v'"; else
+  miss=""
+  for k in mcp cve-monitoring policy-gates shell-injection; do
+    grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+  done
+  [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. both skills + agent + command present with valid frontmatter"
+miss=""
+for s in security-scan dependency-check; do
+  f="$ROOT/skills/$s/SKILL.md"
+  [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+  for k in 'name:' 'description:'; do
+    grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+  done
+done
+[[ -f "$ROOT/agents/security-auditor.md" ]] || miss="$miss missing-agent"
+[[ -f "$ROOT/commands/audit.md" ]] || miss="$miss missing-command"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. README pins @claude-flow/cli to v3.6"
+grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md" \
+  && ok || bad "v3.6 pin missing"
+
+step "4. README defers to ruflo-agentdb namespace convention"
+grep -q "ruflo-agentdb" "$ROOT/README.md" \
+  && grep -q "Namespace convention" "$ROOT/README.md" \
+  && ok || bad "namespace coordination block incomplete"
+
+step "5. security-findings namespace claimed"
+grep -q "security-findings" "$ROOT/README.md" \
+  && ok || bad "security-findings namespace not claimed"
+
+step "6. AIDefence integration cross-reference (3-gate pattern)"
+F="$ROOT/README.md"
+grep -q "ruflo-aidefence" "$F" \
+  && grep -qE "3-gate|3 gates|three gates" "$F" \
+  && ok || bad "AIDefence 3-gate cross-reference missing"
+
+step "7. audit_1776853149979 shell-injection pattern catalog intact"
+F="$ROOT/README.md"
+miss=""
+grep -q "execSync" "$F" || miss="$miss execSync"
+grep -q "execFileSync" "$F" || miss="$miss execFileSync"
+grep -qE "loader-hijack|LD_PRELOAD|DYLD_" "$F" || miss="$miss loader-hijack"
+grep -q "isSafePackageSpec" "$F" || miss="$miss package-spec"
+[[ -z "$miss" ]] && ok || bad "pattern catalog incomplete:$miss"
+
+step "8. ADR-096 encryption-at-rest cross-reference"
+grep -q "ADR-096" "$ROOT/README.md" \
+  && grep -qE "CLAUDE_FLOW_ENCRYPT_AT_REST|encryption" "$ROOT/README.md" \
+  && ok || bad "ADR-096 encryption cross-reference missing"
+
+step "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-security-audit-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+  && ok || bad "ADR missing or status != Proposed"
+
+step "10. no wildcard tool grants in skills"
+bad_skills=""
+for f in "$ROOT"/skills/*/SKILL.md; do
+  grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"
+done
+[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1