This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new b0ba95bc0d3b chore: add user-facing security policy enforcement
documentation
b0ba95bc0d3b is described below
commit b0ba95bc0d3bb04f988f60fd0c4911a89ea3ae92
Author: Claus Ibsen <[email protected]>
AuthorDate: Mon Jun 22 22:58:24 2026 +0200
chore: add user-facing security policy enforcement documentation
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---
docs/user-manual/modules/ROOT/nav.adoc | 1 +
.../modules/ROOT/pages/security-policy.adoc | 171 +++++++++++++++++++++
docs/user-manual/modules/ROOT/pages/security.adoc | 4 +
3 files changed, 176 insertions(+)
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index 44cf813f4ab6..6ce6a33d4dfd 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -48,6 +48,7 @@
** xref:camel-4x-upgrade-guide.adoc[Camel 4.x Upgrade Guide]
* Security
** xref:security.adoc[Security]
+** xref:security-policy.adoc[Security Policy Enforcement]
** xref:security-model.adoc[Security Model]
* xref:architecture.adoc[Architecture]
** xref:backlog-debugger.adoc[Backlog debugger]
diff --git a/docs/user-manual/modules/ROOT/pages/security-policy.adoc
b/docs/user-manual/modules/ROOT/pages/security-policy.adoc
new file mode 100644
index 000000000000..f782fdc6d4c8
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/security-policy.adoc
@@ -0,0 +1,171 @@
+= Security Policy Enforcement
+
+Camel includes a built-in security policy enforcement mechanism that detects
insecure configuration
+at startup time — before your application processes any messages. It catches
common mistakes like
+plain-text passwords, disabled SSL verification, unsafe deserialization
settings, and development
+features left enabled in production.
+
+== Security categories
+
+The framework checks four categories of security concerns:
+
+[cols="1,3,2"]
+|===
+| Category | Description | Example properties
+
+| `secret`
+| Plain-text sensitive values that should use property placeholders, vault
references, or environment variables
+| `password`, `apiKey`, `token`, `secretKey`
+
+| `insecure:ssl`
+| SSL/TLS settings that weaken transport security
+| `trustAllCertificates=true`, `hostnameVerification=false`
+
+| `insecure:serialization`
+| Enabling Java object deserialization, a known attack vector
+| `allowJavaSerializedObject=true`, `transferException=true`
+
+| `insecure:dev`
+| Development or debug features that should not be enabled in production
+| `devConsoleEnabled=true`, `uploadEnabled=true`
+|===
+
+== Policy levels
+
+Each category can be set to one of three enforcement levels:
+
+[cols="1,4"]
+|===
+| Level | Behavior
+
+| `allow`
+| Silently permit the configuration — no warning, no error.
+
+| `warn`
+| Log a warning at startup but allow the application to start. This is the
*default*.
+
+| `fail`
+| Prevent the application from starting and report all violations.
+|===
+
+== Configuration
+
+Configure policies using the `camel.security.*` properties:
+
+[source,properties]
+----
+# Global policy applied to all categories unless overridden
+camel.security.policy = warn
+
+# Per-category overrides
+camel.security.secretPolicy = fail
+camel.security.insecureSslPolicy = fail
+camel.security.insecureSerializationPolicy = fail
+camel.security.insecureDevPolicy = allow
+
+# Exempt specific properties from all checks
+camel.security.allowedProperties = camel.component.http.trustAllCertificates
+----
+
+[cols="2,4,1"]
+|===
+| Property | Description | Default
+
+| `camel.security.policy`
+| Global security policy applied to all categories unless overridden.
+| `warn`
+
+| `camel.security.secretPolicy`
+| Overrides the global policy for plain-text secrets.
+|
+
+| `camel.security.insecureSslPolicy`
+| Overrides the global policy for insecure SSL/TLS settings.
+|
+
+| `camel.security.insecureSerializationPolicy`
+| Overrides the global policy for insecure deserialization settings.
+|
+
+| `camel.security.insecureDevPolicy`
+| Overrides the global policy for development-only features.
+|
+
+| `camel.security.allowedProperties`
+| Comma-separated list of property keys to exclude from all checks.
+|
+|===
+
+When a per-category policy is not set, it falls back to the global
`camel.security.policy` value.
+
+== Profile defaults
+
+The enforcement level changes automatically based on the active Camel profile:
+
+[cols="1,3"]
+|===
+| Profile | Behavior
+
+| No profile
+| Global policy defaults to `warn` — backward compatible.
+
+| `dev`
+| `insecureDevPolicy` defaults to `allow` so development features work without
warnings. Other categories remain at `warn`.
+
+| `prod`
+| Global policy defaults to `fail` — the application refuses to start with any
insecure configuration unless explicitly overridden.
+|===
+
+Set the profile with:
+
+[source,properties]
+----
+camel.main.profile = prod
+----
+
+== What is NOT flagged
+
+The `secret` category only flags values that look like plain-text literals.
The following patterns are
+considered safe and are not flagged:
+
+- `{{vault:...}}` — vault references
+- `${env:...}` or `${ENV:...}` — environment variables
+- `${sys:...}` or `${SYS:...}` — system properties
+- `{{...}}` — general property placeholders
+
+== Examples
+
+=== Production: strict enforcement
+
+[source,properties]
+----
+camel.main.profile = prod
+# Implicit: camel.security.policy = fail
+
+# Allow one specific exception where self-signed certs are needed
+camel.security.allowedProperties = camel.component.https.trustAllCertificates
+----
+
+With this configuration, the application will refuse to start if any
plain-text secret, insecure SSL
+setting, unsafe deserialization option, or dev feature is detected — except
the one explicitly
+allowed property.
+
+=== Development: relaxed
+
+[source,properties]
+----
+camel.main.profile = dev
+# Implicit: camel.security.insecureDevPolicy = allow
+# Other categories default to warn
+----
+
+=== Custom: strict secrets, warn on everything else
+
+[source,properties]
+----
+camel.security.policy = warn
+camel.security.secretPolicy = fail
+----
+
+The application will fail to start if any plain-text secret is detected, but
will only log warnings
+for insecure SSL, serialization, or dev feature settings.
diff --git a/docs/user-manual/modules/ROOT/pages/security.adoc
b/docs/user-manual/modules/ROOT/pages/security.adoc
index 9ea97369884c..17988006c867 100644
--- a/docs/user-manual/modules/ROOT/pages/security.adoc
+++ b/docs/user-manual/modules/ROOT/pages/security.adoc
@@ -10,6 +10,10 @@ This page describes the security *features* Camel offers to
route authors and
operators. For the project's *security model* - who is trusted, where the
trust boundaries sit, what counts as a framework vulnerability, and what is
operator responsibility - see xref:security-model.adoc[Security Model].
+
+Camel also includes a xref:security-policy.adoc[Security Policy Enforcement]
mechanism
+that detects insecure configuration (plain-text secrets, disabled SSL
verification,
+unsafe deserialization, dev features in production) at startup time.
====
The broad categories offered are:
