From c203bc5d88be3c4df3e4370ba2e04d55e4394c19 Mon Sep 17 00:00:00 2001 From: Reuven Date: Mon, 4 May 2026 20:37:35 -0400 Subject: [PATCH] =?UTF-8?q?feat(ruflo-security-audit):=20adopt=20plugin=20?= =?UTF-8?q?contract=20=E2=80=94=20AIDefence=20static/runtime=20layered=20i?= =?UTF-8?q?ntegration=20(ADR-0001)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../.claude-plugin/plugin.json | 6 +- plugins/ruflo-security-audit/README.md | 33 ++++++++ .../docs/adrs/0001-security-audit-contract.md | 47 +++++++++++ plugins/ruflo-security-audit/scripts/smoke.sh | 79 +++++++++++++++++++ 4 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 plugins/ruflo-security-audit/docs/adrs/0001-security-audit-contract.md create mode 100755 plugins/ruflo-security-audit/scripts/smoke.sh diff --git a/plugins/ruflo-security-audit/.claude-plugin/plugin.json b/plugins/ruflo-security-audit/.claude-plugin/plugin.json index 2e6ec79538..298b0987ec 100644 --- a/plugins/ruflo-security-audit/.claude-plugin/plugin.json +++ b/plugins/ruflo-security-audit/.claude-plugin/plugin.json @@ -13,6 +13,10 @@ "security", "audit", "cve", - "scanning" + "scanning", + "mcp", + "cve-monitoring", + "policy-gates", + "shell-injection" ] } diff --git a/plugins/ruflo-security-audit/README.md b/plugins/ruflo-security-audit/README.md index b53ee16302..dce974b4d6 100644 --- a/plugins/ruflo-security-audit/README.md +++ b/plugins/ruflo-security-audit/README.md @@ -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) diff --git a/plugins/ruflo-security-audit/docs/adrs/0001-security-audit-contract.md b/plugins/ruflo-security-audit/docs/adrs/0001-security-audit-contract.md new file mode 100644 index 0000000000..c1b3dc9528 --- /dev/null +++ b/plugins/ruflo-security-audit/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 diff --git a/plugins/ruflo-security-audit/scripts/smoke.sh b/plugins/ruflo-security-audit/scripts/smoke.sh new file mode 100755 index 0000000000..0f6a5ae691 --- /dev/null +++ b/plugins/ruflo-security-audit/scripts/smoke.sh @@ -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