This is an automated email from the ASF dual-hosted git repository.

jbonofre pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/karaf.git


The following commit(s) were added to refs/heads/main by this push:
     new 3a795cd4fa Document the Karaf security model in SECURITY.md (#3057)
3a795cd4fa is described below

commit 3a795cd4fa324e69877c6c457ddb88a18a007fe1
Author: JB Onofré <[email protected]>
AuthorDate: Wed Nov 4 15:17:12 2026 +0000

    Document the Karaf security model in SECURITY.md (#3057)
    
    Describe what Karaf trusts, the default network endpoints and roles, how
    command and JMX ACLs work, and what is treated as a vulnerability, as
    hardening, or as expected behavior.
---
 SECURITY.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/SECURITY.md b/SECURITY.md
index 63a6ca8c74..3b016699a5 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -33,3 +33,102 @@
 
 For information on how to report a new security problem please see 
[here](https://www.apache.org/security/).
 Our existing security advisories are published 
[here](https://karaf.apache.org/documentation.html).
+
+Before you report, please check the security model below: it describes what we 
consider a vulnerability.
+
+## Security Model
+
+This section describes what Apache Karaf assumes and guarantees about 
security. It helps you deploy Karaf safely,
+and it helps us decide whether a report is a vulnerability. It covers the 
Karaf runtime built from this repository.
+Features and applications that you install on Karaf (for example Apache Camel 
or Apache CXF) have their own security
+model. Report vulnerabilities in them, and in the projects Karaf uses (for 
example Apache Felix, OPS4J Pax or
+Apache MINA SSHD), to those projects.
+
+### What Karaf trusts
+
+- **The Karaf installation.** Anyone who can write to the Karaf directories 
(`bin`, `etc`, `deploy`, `lib`, `system`
+  and `data`) controls Karaf: they can drop a bundle into `deploy`, or change 
users and ACLs in `etc`. Protect these
+  directories with file system permissions. Passwords in 
`etc/users.properties` are stored in clear text unless you
+  set `encryption.enabled = true` in `etc/org.apache.karaf.jaas.cfg`.
+- **The local console.** The console started by `bin/karaf` doesn't ask for a 
password. It runs as the
+  `karaf.local.user` user with the `karaf.local.roles` roles set in 
`etc/system.properties` (by default `admin`,
+  `manager`, `viewer` and `systembundles`).
+- **The code you install.** Bundles, features, KAR files and the repositories 
they come from are trusted. Karaf
+  doesn't sandbox bundles: they all run in the same JVM, with the permissions 
of the Karaf process. Only install
+  artifacts from repositories you trust (see `etc/org.ops4j.pax.url.mvn.cfg`; 
the default repositories use HTTPS).
+
+### Network access
+
+Karaf ships with no enabled user. Add users to `etc/users.properties`, or 
configure another JAAS login module, before
+you log in remotely.
+
+| Endpoint                    | Default address                                
                                  | Access                                      
                           |
+| --------------------------- | 
--------------------------------------------------------------------------------
 | ---------------------------------------------------------------------- |
+| SSH console                 | `0.0.0.0:8101` 
(`etc/org.apache.karaf.shell.cfg`)                                | `karaf` 
JAAS realm, the user needs the `ssh` role                      |
+| JMX (RMI)                   | `127.0.0.1:1099` and `127.0.0.1:44444` 
(`etc/org.apache.karaf.management.cfg`)   | `karaf` JAAS realm. TLS is off by 
default (`secured` property)         |
+| WebConsole (when installed) | HTTP service, port `8181`                      
                                  | `karaf` JAAS realm, the user needs the 
`admin` role                    |
+
+Karaf doesn't throttle failed logins or lock accounts. Don't expose the SSH or 
JMX ports to untrusted networks.
+Applications that you deploy on the HTTP service are responsible for their own 
security.
+
+### Roles and ACLs
+
+Karaf authorizes users with their JAAS roles. The default roles mean:
+
+- `admin`: full control of Karaf. An admin can run code and operating system 
commands (for example with
+  `shell:exec`), and read or write any file that the Karaf process can access.
+- `manager`: changes the runtime. A manager can manage bundles that aren't 
system bundles, and edit most
+  configurations. Karaf restricts the most direct ways to run code to `admin`, 
but a manager can still run code in
+  other ways, for example by installing or updating a bundle. Only give the 
`manager` role to users you trust as
+  much as admins.
+- `viewer`: reads the state of Karaf, for example bundles, features, 
configurations and logs.
+- `systembundles`: needed to start, stop, update or uninstall system bundles, 
the bundles with a start level below
+  `karaf.systemBundlesStartLevel` (50 by default, set in 
`etc/custom.properties`).
+- `ssh`: needed to open an SSH console session.
+
+The default `admingroup` in `etc/users.properties` has all of these roles.
+
+ACLs decide which roles can run each console command 
(`etc/org.apache.karaf.command.acl.<scope>.cfg`) and each JMX
+MBean operation (`etc/jmx.acl*.cfg`). A rule can match the command or 
operation name only, or also its arguments.
+A command that has no ACL can be run by any user who can log in to the 
console, including a viewer. Karaf ships ACLs
+for the most sensitive commands (installing features, bundles and KAR files, 
running operating system commands,
+changing users and ACLs), but not for every command that changes state (for 
example `log:set`). To restrict the
+commands that have no ACL, set `karaf.secured.command.compulsory.roles` in 
`etc/system.properties`. See the
+[security section of the user 
guide](manual/src/main/asciidoc/user-guide/security.adoc) for details.
+
+### What we treat as a vulnerability
+
+- A client that isn't authenticated runs a command, calls an MBean operation 
or reads data through the SSH, JMX or
+  WebConsole endpoints. This includes flaws in the JAAS login modules that 
Karaf ships.
+- An authenticated user runs a command or MBean operation that the ACLs deny 
to their roles. This includes getting
+  around an argument rule in the ACLs that Karaf ships, for example to change 
an ACL configuration without the
+  `admin` role.
+- A user with only the `viewer` role (and `ssh`) installs or runs code, 
changes users, roles or ACLs, or gets the
+  effect of an operation that the shipped ACLs reserve to `manager` or `admin` 
through a command or operation open
+  to them.
+- A user without the `systembundles` role starts, stops, updates or uninstalls 
a system bundle through the bundle
+  commands or MBean operations.
+
+### What we treat as hardening
+
+These aren't vulnerabilities. We welcome reports and fix them as regular bugs:
+
+- A `manager` gets `admin` capabilities, such as running code, through the 
operations that `manager` is allowed to
+  use.
+- A user gets around an argument rule that you added to an ACL. An argument 
rule matches the text of each argument
+  against a regular expression, and many commands accept the same resource in 
several forms (an id, a name, an alias
+  or a pattern). Karaf doesn't guarantee that your rule covers all of them: 
test your rules, or use rules on the
+  command name when you need a strict limit.
+- A command with no ACL changes the state of Karaf, as long as it doesn't give 
the effect of an operation that the
+  shipped ACLs reserve to a higher role.
+
+### What isn't a vulnerability
+
+- Anything a user with the `admin` role can do, including running code or 
operating system commands, and reading
+  or writing files.
+- Anything that needs write access to the Karaf installation, or access to the 
local console.
+- Harm done by code that you install (bundles, features or KAR files): it runs 
with the permissions of the Karaf
+  process.
+- Users who can log in reading logs and configurations, including any 
credentials stored in them. Don't give console
+  or JMX access to users who must not see them.
+- Guessing passwords: Karaf doesn't throttle failed logins, so limit who can 
reach the SSH and JMX ports.

Reply via email to