ruvnet--ruflo/docs/security/socket-baseline.md

Socket.dev Alert Baseline — claude-flow

Last revised: 2026-06-09 against claude-flow@3.10.40 Source: https://socket.dev/npm/package/claude-flow/alerts/3.10.40 Tracking issue: ruvnet/ruflo#2339

TL;DR

Most of Socket's alerts on claude-flow describe legitimate behaviour of a CLI agent platform (network access, filesystem access, env-var reads, shell access, native modules, etc.) and cannot and should not be "fixed" — they are intrinsic to what the package does. This doc separates the inherent-and-expected categories from the small set that's actually actionable, so the next reviewer doesn't go down the same rabbit hole.

What's protected today

Layer	Mechanism	Status
Ruflo dev tree	overrides block in root package.json (lines 77-107) — pins protobufjs >=8.2.0, uuid >=14.0.0, plus 25+ other transitive forces	✅ npm audit returns 0 vulnerabilities on the working tree
Ruflo dev tree	supply-chain-audit CI job in .github/workflows/v3-ci.yml (line 629) — runs npm audit --audit-level=high, lockfile integrity, top-level allowlist, typosquat reject, publisher trust snapshot	✅ Gates every PR + push to main
Dependency review	dependency-review CI job (line 675) — GitHub's dependency-review-action checks new vulnerable deps in PRs	⚠️ Gated on Pages-style Dependency Graph being enabled at repo level; currently continue-on-error: true

What's NOT fully fixable from inside claude-flow

npm overrides in our root package.json only apply when we are the root of the dep tree. When a consumer runs npm install claude-flow@3.10.40, their root package.json is the one whose overrides apply — ours are ignored. This is the same trap documented in CLAUDE.md for the ruflo wrapper (#2112).

A clean install of claude-flow@3.10.40 therefore still pulls in:

Severity	Package	CVE summary	Root cause
Critical	protobufjs	Arbitrary code execution via bytes-field defaults in generated toObject code	Transitive of onnx-proto → onnxruntime-web → @xenova/transformers
Moderate	uuid	Missing buffer bounds check in v3/v5/v6 when buf is provided	Transitive — multiple paths
High (cascade)	onnx-proto, onnxruntime-web, @xenova/transformers, agentdb, agentic-flow, @claude-flow/memory, @claude-flow/neural, @claude-flow/plugin-gastown-bridge, claude-flow itself	All downstream of the protobufjs + uuid root causes	—

Why this can't be fixed in this PR: the upstream @xenova/transformers@2.17.2 (latest) still pins onnxruntime-web@1.14.0 which carries the bad onnx-proto → protobufjs chain. No clean upstream version exists today. Resolving consumer-side requires either:

1. A patched @xenova/transformers release (waiting on upstream), or migrating to @huggingface/transformers (the rebranded successor — needs evaluation), OR
2. Republishing the affected @claude-flow/* sub-packages with explicit transitive pins in their dependencies blocks (multi-PR coordinated effort), OR
3. Dropping the optional ML stack (agentic-flow, @xenova/transformers) — would lose ONNX-backed features

Tracked in #2339 as separate follow-up work.

Inherent flags — what they mean, why we keep them

Socket fires these on every release. They describe normal CLI/agent behaviour and are not signals of a bug.

Alert	Count	Why it's normal here
Network access	68 pkgs	HTTP clients (Anthropic SDK, MCP transports, fetch-based tools)
Filesystem access	82 pkgs	Universal — anything reading/writing files (memory backend, config, logs)
Environment variable access	84 pkgs	process.env.ANTHROPIC_API_KEY, CLAUDE_FLOW_*, etc. — configuration
Shell access	29 pkgs	child_process — used by every native-module installer, hook runners, npx-style spawning
Install scripts	7 pkgs	Native modules: better-sqlite3, hnswlib-node, onnxruntime-node, @ruvector/*
Native code	5 pkgs	Compiled binaries from the install-scripts row
URL strings	108 pkgs	Every HTTP client embeds endpoint URLs as string literals
Debug access	14 pkgs	The debug package and reflection-based helpers
Dynamic require	16 pkgs	Plugin system (mcp, hooks, agents) + conditional optional-dep loading
Minified code	10 pkgs	Some libraries ship pre-bundled (undici, axios internals, etc.)
Unpopular package	29 pkgs	Long-tail transitives — popularity is not a security signal
Unmaintained	64 pkgs	Long-tail transitives stale >5 years — checked against CVE/deprecation separately
New author	20 pkgs	Maintainer changes — informational, not a vuln

False positives we've explicitly triaged

Alert	What Socket said	Reality
AI-detected possible typosquat → "did you mean z-schema?"	Suggested zod is a typosquat of z-schema	zod is a 10M-weekly-download canonical TypeScript schema library, not a typosquat. Socket's AI guess is wrong.
AI-detected potential security risk	15 instances in 7 packages	Heuristic-only; none corroborated by an actual CVE or code review
AI-detected potential code anomaly	52 instances in 46 packages	Same — heuristic-only
Obfuscated code	17 instances in 11 packages	All match the "pre-bundled / minified" pattern (undici, axios internals); none match the active-obfuscation-malware pattern

Operational policy

1. Root tree must stay green. The supply-chain-audit job in v3-ci.yml enforces npm audit --audit-level=high on every PR. Adding a new direct dep that introduces a HIGH/CRITICAL fails CI.
2. Overrides are a first-line tool. If a new transitive CVE lands, add an overrides entry pinning to a patched version. The current set (root package.json lines 77-107) is the precedent.
3. Document gaps before merging. When a CVE can't be cleanly overridden (e.g., the protobufjs cascade documented above), update this file with the rationale rather than silently ignoring it.
4. Re-baseline this doc when claude-flow versions bump. The alert counts here are tied to 3.10.40 — when the version moves, re-run the audit (scripts/probe-nested-spawn-depth.mjs style) and update the tables.

When to revisit

• Quarterly: re-check upstream for @xenova/transformers / onnxruntime-web patched versions
• On Socket alert change: if Socket flags something new at critical severity for a direct dep, that's a real signal and warrants immediate triage
• On new direct dep addition: the supply-chain-audit job will catch this at PR time; no manual checklist needed

Related

• ADR-097 — federation budget circuit-breaker (cost-side supply chain)
• ADR-145 — plugin supply-chain integrity (install-time)
• ADR-144 — authorization propagation (action-time, ADR-131 is content-time)
• Issue #2046 — original supply-chain hardening (the source of supply-chain-audit job)
• Issue #2339 — this baseline + Socket alert response