Skip to content

docs: expand security model with severity tiers and scope rules#23229

Merged
oscerd merged 2 commits into
apache:mainfrom
oscerd:docs/security-model-management-surface
May 15, 2026
Merged

docs: expand security model with severity tiers and scope rules#23229
oscerd merged 2 commits into
apache:mainfrom
oscerd:docs/security-model-management-surface

Conversation

@oscerd
Copy link
Copy Markdown
Contributor

@oscerd oscerd commented May 14, 2026

Summary

Documentation-only improvements to the Camel security model, driven by a
security-model review. No code, no API, no behaviour change.

1. Management-surface scope clarification (security-model.adoc)

  • Clarifies the existing "management surface" out-of-scope bullet so readers can
    tell which side of the trust boundary the JMX / Jolokia management API sits
    on. Names the MBean operations the bullet covers (ManagedCamelContext.sendBody
    / requestBody, ManagedBacklogDebugger.evaluateExpressionAtBreakpoint,
    addConditionalBreakpoint, BacklogTracer.setTraceFilter) and restates that
    the trust boundary is the JMX / Jolokia / management-HTTP surface itself
    (JVM JMX auth, the Jolokia restrictor policy, network exposure of the
    management port) — not the individual MBean method.

2. Security properties and violation severity (security-model.adoc, new subsection)

  • Adds an impact view that complements the existing mechanism-oriented
    "In-scope vulnerability classes": a table mapping each protective property the
    trust boundary commits to → the violation symptom a reporter/scanner observes
    → an indicative CVSS severity tier. Directly serves the "automated triage
    tooling" audience the document already names. Tiers are explicitly marked
    indicative; the PMC retains definitive per-report CVSS scoring.

3. Deprecated and removed components scope (security-model.adoc, new subsection)

  • Deprecated components are placed in limited scope (still triaged
    privately, but the primary remediation is the documented migration; hardening
    and defence-in-depth go to the supported replacement). Removed components
    are out of scope. Deprecation is defined by mechanically-verifiable markers
    ((deprecated) pom/title suffix, @Deprecated, catalog deprecated flag,
    upgrade-guide entry). Carve-out: a non-deprecated component that merely
    depends on a deprecated third-party library stays under the existing
    third-party-dependency item.

4. AGENTS.md → SECURITY.md bridge (AGENTS.md)

  • Completes the convention chain: the ## Security Model section now points to
    SECURITY.md as the report-intake entry point (scope → threat model,
    disclosure → ASF process) and instructs agents not to disclose suspected
    vulnerabilities publicly.

Reviewer note

The first commit (management-surface clarification) was approved by @davsclaus
and @Croway. The follow-up commit materially expands the changeset
(items 2–4 above), and those approvals predate it — re-requesting review so the
broader scope is consciously re-examined. The severity bands in item 2 and the
"deprecated → limited scope / primary remediation is migration" policy in
item 3 are PMC judgement calls and the parts that most warrant scrutiny.
Happy to split items 2–4 into a separate PR if preferred.

Test plan

  • Render the Antora page locally; confirm the new subsections and the
    severity table render without breaking list/table structure.
  • Verify no broken xref: or AsciiDoc cross-references are introduced.
  • Confirm AGENTS.md still renders as valid Markdown.

Claude Code (Opus 4.7) on behalf of Andrea Cosentino

Expand the "management surface" out-of-scope bullet in
security-model.adoc to name the MBean operations the bullet covers
(ManagedCamelContext.sendBody / requestBody,
ManagedBacklogDebugger.evaluateExpressionAtBreakpoint and
addConditionalBreakpoint, BacklogTracer.setTraceFilter) and to state
explicitly that the trust boundary is the JMX / Jolokia / management
HTTP surface itself - JVM JMX authentication, the Jolokia restrictor
policy and the network exposure of the management port - rather than
any individual MBean method.

These operations are intentionally as expressive as a route author's
DSL so that operator workflows (Camel JBang, Hawtio, JConsole,
monitoring agents) keep working. The clarification helps future readers
of the security model identify which side of the trust boundary the
management API sits on without having to derive the reasoning from the
trust-model section.

_Claude Code (Opus 4.7) on behalf of Andrea Cosentino_

Signed-off-by: Andrea Cosentino <ancosen@gmail.com>
@oscerd oscerd requested review from davsclaus and gnodet May 14, 2026 15:59
@github-actions
Copy link
Copy Markdown
Contributor

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

  • First-time contributors require MANUAL approval for the GitHub Actions to run
  • You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
  • You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
  • Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

@github-actions github-actions Bot added the docs label May 14, 2026
@davsclaus
Copy link
Copy Markdown
Contributor

yes ManagedBacklogDebugger is a development feature that is not enabled for production. End users can however choose to turn it on or in standby mode, but then that is on purpose.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 14, 2026

🧪 CI tested the following changed modules:

  • docs

⚙️ View full build and test results

Add a "Security properties and violation severity" subsection mapping each
protective property to its violation symptom and an indicative severity
tier (an impact view complementing the mechanism-oriented in-scope classes),
and a "Deprecated and removed components" subsection placing deprecated
components in limited scope and removed ones out of scope.

Bridge AGENTS.md to SECURITY.md so the vulnerability-reporting convention is
complete and agents are instructed not to disclose suspected issues publicly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@oscerd oscerd changed the title docs: clarify management-surface scope in security model docs: expand security model with severity tiers and scope rules May 15, 2026
@oscerd oscerd requested review from Croway and davsclaus May 15, 2026 09:01
@oscerd oscerd merged commit 5bbb510 into apache:main May 15, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants