Clarify network and plugin trust boundaries

[bomly-guy]

What changed

• Add a pipeline regression matrix proving that matchers are not prepared or run for plain, audit-only, analysis-only, or policy-only requests.
• Confirm that explicit enrichment and the internal matching signal still run the selected matcher.
• Describe remote Git cloning and build-tool detectors as network boundaries separate from matcher enrichment.
• Correct the built-in enrichment service inventory, including Scorecard and Grype database updates.
• State clearly that enabled native plugins run with the user's privileges and are not operating-system sandboxes.
• Regenerate the detector and matcher documentation from their source templates.

Why

The matcher gate already enforced explicit intent, but the repository lacked one test covering all neighboring pipeline options. Several public pages also used broad offline and sandbox wording that did not account for remote target cloning, build-tool subprocesses, or native plugin privileges.

This PR makes the tested guarantee narrow and accurate: network-backed matchers require explicit matching intent. Other network and host-access boundaries are documented independently.

User impact

There is no command or output contract change. Users get clearer guidance about when a scan may use the network and what enabling a native plugin authorizes.

Validation

• make generate
• make fmt-check
• make lint
• make test
• make build
• git diff --check

Summary by CodeRabbit

• Documentation

  • Clarified that network-backed matchers run only when enrichment is explicitly enabled.
  • Documented separate network behavior for remote repository cloning and build-tool dependency downloads.
  • Expanded guidance on matcher services, vulnerability database downloads, and external plugin network access.
  • Clarified that external plugins are trusted native processes rather than operating-system sandboxes.
  • Updated offline and air-gapped usage guidance to reflect these boundaries.

• Tests

  • Added coverage verifying that matcher execution requires explicit network-related intent.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: bfa6a591-cb4b-4444-bc63-690ec4378d78

📥 Commits

Reviewing files that changed from the base of the PR and between f3141ca and 262bb79.

📒 Files selected for processing (12)

• AGENTS.md
• CLAUDE.md
• dev-docs/ARCHITECTURE.md
• docs/ARCHITECTURE.md
• docs/DETECTORS.md
• docs/GLOSSARY.md
• docs/MATCHERS.md
• docs/PLUGINS.md
• docs/USE_CASES.md
• internal/engine/pipeline_network_intent_test.go
• internal/support/component_docs.go
• internal/support/generate_test.go

---

📝 Walkthrough

Walkthrough

The change clarifies that network-backed matchers require --enrich, documents separate network behavior for remote targets and detectors, expands permitted matcher services and plugin trust guidance, and adds pipeline tests covering explicit matcher intent.

Changes

Network intent model

Layer / File(s)	Summary
Matcher intent pipeline validation internal/engine/pipeline_network_intent_test.go	Adds tests verifying matcher lifecycle calls across audit, analysis, policy, enrichment, and explicit matching configurations.
Network policy and trust boundaries AGENTS.md, CLAUDE.md, dev-docs/ARCHITECTURE.md, docs/ARCHITECTURE.md, docs/PLUGINS.md	Documents --enrich matcher gating, remote cloning and detector behavior, enrichment services including Grype, and native plugin privileges.
Network behavior documentation rollout docs/DETECTORS.md, docs/GLOSSARY.md, docs/MATCHERS.md, docs/USE_CASES.md, internal/support/component_docs.go, internal/support/generate_test.go	Updates user-facing and generated documentation describing matcher endpoints, offline behavior, detector downloads, and corresponding documentation assertions.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: clarifying network behavior and plugin trust boundaries across docs and tests.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch security-network-assurance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Bomly Diff Summary

Compared f3141cadad15acb74db09fb8d63419ab564834af to 262bb79e76ffca154d8c165d109e75bafce38b3a.

Overview

Status	Manifests	Dependencies	Findings	Duration
✅ Pass	+0 / ~0 / -0	+0 / ~0 / -0	0 introduced / 0 persisted / 0 resolved	1m 17s

Dependency Changes

✅ No dependency changes.

Vulnerabilities

✅ No vulnerability changes.

License Changes

✅ No license changes.

Project Posture

✅ No project posture changes (--matchers +scorecard was not selected).

Policy Findings

✅ No policy differences were identified.

[bomly-guy]

Reviewed the docs sweep and the new pipeline matcher-gate test. The test is well-constructed — I verified it passes and that matcher.Ready in the engine is only reachable through the gated runMatch path, so the guarantee it encodes ("no matcher preparation or execution without explicit intent") is real, not just plausible.

One repo-consistency gap worth fixing in this PR:

CLAUDE.md and AGENTS.md network allowlists are now out of sync with the docs. This PR adds "Grype's vulnerability database distribution service" to the permitted enrichment-time services in dev-docs/ARCHITECTURE.md, but the normative "Network calls (--enrich) permitted only to: …" lists in CLAUDE.md (Non-Negotiables) and AGENTS.md still enumerate only the six HTTP hosts and omit the Grype DB endpoint. Since those lists are worded as exhaustive ("permitted only to"), the built-in Grype matcher's DB download now violates the letter of the repo's own contributor rules — the same kind of imprecision this PR fixes in the user docs. Suggest updating both files in this PR (they're the lists reviewers and agents actually enforce against). Relatedly, those lists still present ClearlyDefined and endoflife.date without the "external plugin" framing the user docs now use — worth aligning while you're in there.

Inline comments cover two smaller accuracy/consistency nits. No blocking issues.

[bomly-guy]

Nit on precision, since precision is this PR's stated goal: the builtin Grype adapter only downloads the DB when it's absent (needsDownload := !a.dbExists() in internal/matchers/grype/builtin.go, and LoadVulnerabilityDB is called with update=needsDownload), and ValidateAge is disabled — so Bomly never updates an existing DB, it only performs the initial download. "may download or update" overstates the network surface slightly. Consider "downloads its vulnerability database on first use" (here and in the internal/support/component_docs.go template). Being conservative is fine too, but the current wording implies a recurring update check that doesn't exist.

[bomly-guy]

Just above this hunk, line 395 still opens with "Matchers are offline-safe by default." — the exact phrase this PR retires everywhere else (and whose removal generate_test.go now asserts for the generated matcher overview). It's technically scoped to matchers so it isn't wrong, but leaving the retired slogan in the contributor deep-dive undercuts the sweep. Suggest rewording it to match the new "network-backed matchers are off by default" framing.

[bomly-guy]

Minor: the goal line still promises "zero outbound network calls" while the command comment right below it was reworded to "detector behavior varies" precisely because that promise doesn't always hold. Since the recipe's caveat paragraph already explains the detector exception, consider softening the goal to something like "analyze dependencies without contacting enrichment services" so the section doesn't open with the claim it then walks back.