Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(metaharness): .harness/manifest.json β€” fingerprint security-critical files (iter 32)

ruv5acc51d74cb0
diff --git a/.harness/README.md b/.harness/README.md
new file mode 100644
index 0000000000..4be841f13c
--- /dev/null
+++ b/.harness/README.md
@@ -0,0 +1,68 @@
+# .harness/ β€” ruflo's MetaHarness lifecycle directory
+
+This directory holds the files that `harness <subcommand>` from `metaharness` reads to assess ruflo's governance posture. See [ADR-150](../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) for context.
+
+## Contents
+
+| File | Purpose | Iter |
+|---|---|---|
+| `mcp-policy.json` | MCP governance policy. ADR-022 default-deny, audit-log on, dangerous-pattern list, per-turn call budget. Required to clear the `no-policy` HIGH finding from `harness mcp-scan`. | 30 |
+| `manifest.json` | Hand-authored harness identity manifest: hosts + sha256 fingerprints of the security-relevant files (mcp-policy + .claude/settings). Required input for `harness sign` and for OIA-manifest's `mcpPolicyPath` field. | 32 |
+| `witness.json` | **NOT YET CREATED.** Ed25519-signed Merkle-style witness over the manifest. Would push OIA governance from "full / mcp-policy.json (witness missing)" to "full / mcp-policy.json + witness ADR-011". See below. | β€” |
+
+## Witness β€” what's needed to ship it
+
+`harness sign .` produces a witness from `.harness/manifest.json` BUT requires `WITNESS_SIGNING_KEY` (64-char hex Ed25519 private key) in the environment. Ruflo's existing `brain-signing-key` in GCP Secret Manager is in a different format (89 chars, not hex) and can't be reused.
+
+To enable witness signing, one of:
+
+1. **Create a new GCP secret `witness-signing-key`** (32 random bytes, hex-encoded). Fetched via Workload Identity Federation in CI; locally via `gcloud secrets versions access`. Pros: same auth path as the existing OPENROUTER_API_KEY workflow. Cons: requires explicit user authorization (creates a new sensitive secret).
+
+2. **Use a hardware key (YubiKey, Sigstore-style ephemeral identity)**. Pros: no long-lived private key on disk. Cons: more CI plumbing.
+
+3. **Skip the witness** and accept the "partial witness" note in the OIA manifest. The threat-model and mcp-scan are already CLEAN without it; the witness only signs the manifest, it doesn't itself add new security controls.
+
+Current state (option 3) gives ruflo:
+- βœ“ L7 governance alignment: **full** (per `harness oia-manifest`)
+- βœ“ threat-model worst severity: **info / clean**
+- βœ“ mcp-scan: **0 actionable findings**
+- The implementation note: `"mcp-policy.json (witness missing)"`
+
+The witness is genuinely optional unless an external party needs to verify the manifest hasn't been tampered with. For ruflo's internal use it's nice-to-have polish.
+
+## Verifying ruflo's current posture
+
+```bash
+# Full threat report
+npx -y -p metaharness@latest harness threat-model .
+
+# Per-server MCP scan
+npx -y -p metaharness@latest harness mcp-scan .
+
+# Full OIA layer alignment
+npx -y -p metaharness@latest harness oia-manifest .
+
+# Or via ruflo's wrappers (no metaharness install required if optional dep is present)
+npx ruflo metaharness threat-model
+npx ruflo metaharness mcp-scan
+npx ruflo metaharness oia-audit --dry-run
+```
+
+## Updating mcp-policy.json
+
+If you change `mcp-policy.json`, regenerate the manifest's sha256 entry:
+
+```bash
+node -e "
+const { readFileSync, writeFileSync } = require('node:fs');
+const { createHash } = require('node:crypto');
+const m = JSON.parse(readFileSync('.harness/manifest.json', 'utf-8'));
+m.files['.harness/mcp-policy.json'] = createHash('sha256').update(readFileSync('.harness/mcp-policy.json')).digest('hex');
+m.files['.claude/settings.json'] = createHash('sha256').update(readFileSync('.claude/settings.json')).digest('hex');
+m.generated_at = new Date().toISOString();
+writeFileSync('.harness/manifest.json', JSON.stringify(m, null, 2) + '\n');
+console.log('Manifest updated.');
+"
+```
+
+Smoke step 17t (in `plugins/ruflo-metaharness/scripts/smoke.sh`) locks the policy invariants. If you change the policy in a way that violates `defaultDeny:true / auditLog:true / requireApprovalForDangerous:true` or removes the `toolTimeoutMs`/`maxToolCallsPerTurn` positive-number requirements, CI will fail.
diff --git a/.harness/manifest.json b/.harness/manifest.json
new file mode 100644
index 0000000000..10a323c833
--- /dev/null
+++ b/.harness/manifest.json
@@ -0,0 +1,21 @@
+{
+ "schema": 1,
+ "generator": "ruflo-hand-authored",
+ "template": "ruflo-self",
+ "template_version": "3.11.0",
+ "vars": {
+ "name": "ruflo",
+ "description": "Ruflo β€” multi-agent orchestration platform built on @claude-flow/cli",
+ "host": "claude-code"
+ },
+ "hosts": ["claude-code"],
+ "files": {
+ ".harness/mcp-policy.json": "4b4c5826c9d1cdb8bd70a5c097a1d1b9a79b2d4850fdf05149b9ea84bfefa502",
+ ".claude/settings.json": "ba278b1f9ccf8e170e4cef3748a6bcb4efc0850b7ec66d34690fec328fdabeb1"
+ },
+ "generated_at": "2026-06-16T20:00:00.000Z",
+ "meta": {
+ "surface": "cli",
+ "adr_anchor": "ADR-150 β€” ruflo's metaharness integration; this manifest covers the security-relevant surface that mcp-policy.json governs"
+ }
+}
diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.sh
index ddb9887c60..3abb8bc56d 100755
--- a/plugins/ruflo-metaharness/scripts/smoke.sh
+++ b/plugins/ruflo-metaharness/scripts/smoke.sh
@@ -191,6 +191,28 @@ grep -q "execCli(\[\s*'-y'\s*,\s*'metaharness@latest'" "$F" 2>/dev/null || \
grep -q "cwd: opts" "$F" || miss="$miss no-cwd-passthrough"
[[ -z "$miss" ]] && ok || bad "$miss"
+step "17u. .harness/manifest.json + README documents witness gap (iter 32)"
+F="$ROOT/../../.harness/manifest.json"
+README="$ROOT/../../.harness/README.md"
+miss=""
+[[ -f "$F" ]] || miss="$miss missing-manifest"
+node -e "JSON.parse(require('fs').readFileSync('$F','utf-8'))" 2>/dev/null || miss="$miss invalid-json"
+# Manifest must list both security-critical files
+node -e "
+const m = JSON.parse(require('fs').readFileSync('$F','utf-8'));
+const files = m.files || {};
+if (!files['.harness/mcp-policy.json']) { console.error('no policy fingerprint'); process.exit(1); }
+if (!files['.claude/settings.json']) { console.error('no settings fingerprint'); process.exit(1); }
+// Sha256 hashes are 64 hex chars
+for (const [k, v] of Object.entries(files)) {
+ if (!/^[0-9a-f]{64}\$/.test(v)) { console.error('bad sha256 for', k); process.exit(1); }
+}
+" 2>/dev/null || miss="$miss manifest-shape-invalid"
+[[ -f "$README" ]] || miss="$miss missing-readme"
+grep -q "witness-signing-key\|witness signing\|WITNESS_SIGNING_KEY" "$README" 2>/dev/null || miss="$miss no-witness-doc"
+grep -q "ADR-150" "$README" 2>/dev/null || miss="$miss no-adr-anchor"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
step "17t. .harness/mcp-policy.json present + default-deny (iter 30 β€” closes no-policy HIGH)"
F="$ROOT/../../.harness/mcp-policy.json"
miss=""