docs(security): clarify insecure transport policy

[Ching Wei Kang (WilliamK112)]

Description

Corrects the Recommended hardening guidance so it matches APM's current transport and policy behavior.

The previous sentence said organizations could forbid allow_insecure: true “via the policy allow list.” That is not a control the policy engine provides: dependency allow/deny patterns match scheme-blind canonical package identities. The default github.com host is omitted while non-default hosts are retained, so policy can restrict package and host identity but cannot distinguish an HTTP source from an HTTPS source for the same canonical host and path.

This update:

• states that apm-policy.yml has no dedicated allow_insecure field
• documents the manifest plus CLI two-gate model for direct HTTP dependencies and the separate transitive-host flag
• recommends rejecting allow_insecure: true and insecure CLI flags in standard CI when an organization wants an HTTPS-only rule
• explains the scheme-blind, host-preserving canonical identity used by dependency policy
• explains that registry_source.allow_non_registry controls source routing, not transport security
• adds a restrictive allow-list example while explicitly warning that it is identity-based, not HTTPS enforcement
• adds a docs contract test to prevent the misleading transport-aware policy claim from returning

Fixes #2346

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• Added tests for the corrected documentation contract
• pytest -q tests/unit/test_tls_docs_scope.py (9 passed)
• Ruff lint and format checks for the changed test
• Astro production build (124 pages)
• Internal link check (1,032 relative links, no broken links)
• git diff --check

Spec conformance (OpenAPM v0.1)

• N/A -- this corrects implementation-specific hardening guidance and does not change an OpenAPM v0.1 normative requirement.

[Copilot]

🟡 Changes recommended

The new docs contract test is brittle to Markdown formatting and doesn’t explicitly guard against the original misleading sentence reappearing.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates APM enterprise security documentation to accurately describe how insecure HTTP dependencies are governed (manifest + CLI gating, not policy transport enforcement), and adds a unit test to prevent the previously misleading claim from reappearing.

Changes:

• Clarifies in enterprise/security.md that apm-policy.yml has no dedicated allow_insecure field and that dependency allow/deny patterns are identity-based (not HTTPS enforcement).
• Adds an example restrictive dependency allow list with an explicit warning that it does not enforce HTTPS.
• Adds a docs contract test to lock in the corrected guidance.

File summaries

File	Description
docs/src/content/docs/enterprise/security.md	Rewrites “Recommended hardening” guidance to correctly separate policy identity controls from insecure-transport (HTTP) approvals.
tests/unit/test_tls_docs_scope.py	Adds a regression/contract test that asserts the corrected security-doc wording remains present.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Ching Wei Kang (WilliamK112)]

A duplicate-PR audit surfaced one terminology issue, now corrected in 7f87ac1b: canonical dependency identities are scheme-blind, but they retain non-default hosts (only the default github.com host is omitted). The docs and regression test now state that precise boundary, and the PR description is updated accordingly. The focused 9-test suite, Ruff, and whitespace checks pass. I also closed older duplicate #2636 so this is the single review target.