[8.18] Update plugins documentation for Entitlements #125292

docs/plugins/development/creating-classic-plugins.asciidoc

@@ -49,42 +49,140 @@ to install your plugin for testing. The Java plugin is auto-loaded only if it's
 `plugins/` directory.
 
 [discrete]
-[[plugin-authors-jsm]]
-==== Java Security permissions
-
-Some plugins may need additional security permissions. A plugin can include
-the optional `plugin-security.policy` file containing `grant` statements for
-additional permissions. Any additional permissions will be displayed to the user
-with a large warning, and they will have to confirm them when installing the
-plugin interactively. So if possible, it is best to avoid requesting any
-spurious permissions!
-
-If you are using the {es} Gradle build system, place this file in
-`src/main/plugin-metadata` and it will be applied during unit tests as well.
-
-The Java security model is stack-based, and additional
-permissions are granted to the jars in your plugin, so you have to
-write proper security code around operations requiring elevated privileges.
-You might add a check to prevent unprivileged code (such as scripts)
-from gaining escalated permissions. For example:
-
-[source,java]
---------------------------------------------------
-// ES permission you should check before doPrivileged() blocks
-import org.elasticsearch.SpecialPermission;
-
-SecurityManager sm = System.getSecurityManager();
-if (sm != null) {
-  // unprivileged code such as scripts do not have SpecialPermission
-  sm.checkPermission(new SpecialPermission());
-}
-AccessController.doPrivileged(
-  // sensitive operation
-);
---------------------------------------------------
-
-Check https://www.oracle.com/technetwork/java/seccodeguide-139067.html[Secure Coding Guidelines for Java SE]
-for more information.
+[[_entitlements_policy]]
+==== Entitlements policy
+
+Some plugins may need additional _entitlements_.
+
+{es} limits the ability to perform certain security-sensitive actions as part of its _Entitlement_ security mechanism (e.g. to limit the potential fallout from remote code execution (RCE) vulnerabilities).
+
+The Entitlement model is based on Java modules.
+An _entitlement_ granted to a Java module allows the module's code to perform the security-sensitive action associated with that entitlement. For example, the ability to create threads is limited to modules that have the `manage_threads` entitlement; likewise, the ability to read a file from the filesystem is limited to modules that have the `files` entitlement for that particular file.
+
+In practice, an entitlement allows plugin code to call a well-defined set of corresponding JDK methods; without the entitlement calls to those JDK methods are denied and throw a `NotEntitledException`. Plugin can include the optional `entitlement-policy.yaml` file to define modules and required entitlements. Any additional entitlement requested by the plugin will be displayed to the user with a large warning, and users will have to confirm them when installing the plugin interactively. Therefore, it is best to avoid requesting any spurious entitlement!
+
+If you are using the {es} Gradle build system, place this file in `src/main/plugin-metadata` and it will be applied during unit tests as well.
+
+An entitlement policy applies to all of your plugin jars (your own code and third party dependencies). You have to write your policy file accordingly. For example, if a plugin uses the Example API client to perform network operations, it will need a policy that may look like this:
+
+```YAML
+org.elasticsearch.example-plugin:
+  - manage_threads
+com.example.api.client:
+  - set_https_connection_properties
+  - outbound_network
+```
+
+Note how the network related entitlements are granted to the `com.example.api.client` module, as the code performing the sensitive network operations is in the `example-api-client` dependency.
+
+If your plugin is not modular, all entitlements must be specified under the catch-all `ALL-UNNAMED` module name:
+
+```YAML
+ALL-UNNAMED:
+  - manage_threads
+  - set_https_connection_properties
+  - outbound_network
+```
+==== Entitlements
+
+The entitlements currently implemented and enforced in {es} that are available to plugins are the following ones:
+
+===== `manage_threads`
+
+Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`. In general, setting the name, priority, daemon state and context class loader are things no plugins should do when executing on
+{es} threadpools; however, many 3rd party libraries that support async operations (e.g. Apache HTTP client) need to manage their own threads. In this case it is justifiable to request this entitlement.
+
+Example:
+```yaml
+org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
+  - manage_threads
+```
+
+===== `outbound_network`
+
+Allows code to call methods to make a network connection. {es} does not grant any network access by default; each plugin that needs to directly connect to an external resource (e.g. to upload or download data) must request this entitlement.
+
+Example:
+```yaml
+org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
+  - outbound_network
+```
+
+===== `set_https_connection_properties`
+Allows code to call methods to change properties on an established HTTPS connection. While this is generally innocuous (e.g. the google API client uses it to modify the HTTPS connections they just created), these methods can allow code to change arbitrary connections.
+
+Example:
+```yaml
+org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
+  - set_https_connection_properties
+```
+
+===== `inbound_network` (deprecated)
+Allows code to call methods to listen for incoming connections, so external resources can connect directly to your plugin. This entitlement should only be used when absolutely necessary (e.g. if a library you depend on requires it for authentication). Granting it makes the {es} node more vulnerable to attacks. This entitlement is deprecated, and can be removed in a future version of {es}.
+
+Example:
+```yaml
+org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
+  - inbound_network
+```
+
+===== `load_native_libraries`
+Allows code to load native libraries and call https://docs.oracle.com/en/java/javase/24/core/restricted-methods.html[restricted methods]. This entitlement also enables native access for modules it is granted to. Native code may alter the JVM or circumvent access checks such as file or network restrictions.
+
+Example:
+```yaml
+org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
+  - load_native_libraries
+```
+
+===== `files`
+
+Allows code to access the filesystem, to read or write paths as specified by the entitlement's fields. The filesystem of the OS hosting {es} may contain sensitive files, for example credentials. Some files are meant to be always accessible to {es}, but plugins can not access them directly: {es} enforces that certain files can only be read by its core code, while some other files can not be read or written at all. A plugin is always granted `read` access to the {es} config directory and `read_write` access to the temp directory; if the plugin requires to read, write or access additional files or directories, it must specify them via this entitlement.
+
+It is possible to specify 3 different types of file entitlement:
+
+* `path` to specify an absolute path
+* `relative_path` to specify a relative path. The path will be resolved via the `relative_to` field, which is used to qualify the relative path. It can be a specific {es} directory (`config` or `data`), or to the user home directory (`home`) (the home of the user running {es})
+* `relative_path` to specify a path resolved via the `relative_to` field, which can have the following values:
+  - `config`: the {es} https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html#config-files-location[config directory]
+  - `data`: the {es} https://www.elastic.co/guide/en/elasticsearch/reference/current/path-settings-overview.html[data directory]
+  - `home`: the home directory of the user running {es}
+  - `path_setting` to specify a path defined via an {es} setting. The path can be absolute or relative; in the latter case, the path will be resolved using the `basedir_if_relative` path (which can assume the same values as `relative_to`)
+
+Each of the 3 types has some additional fields:
+
+* `mode` (required): can be either `read` or `read_write`
+* `platform` (optional): indicates this item applies only to one platform, which can be one of `linux`, `macos` or `windows`. On other platforms, the item is ignored. If this field is not specified, the item applies to all platforms.
+* `exclusive`: access to this path is exclusive for this plugin; this means that other plugins will not be able to access to it, not even if they have an entitlement that would normally grant access to that path.
+
+Example:
+```yaml
+org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
+  - files:
+    - path: "/absolute/path"
+      mode: read
+    - relative_path: "relative/file.txt"
+      relative_to: data
+      mode: read_write
+    - path_setting: setting.name
+      basedir_if_relative: data
+      mode: read
+```
+
+
+===== `write_system_properties`
+Allows code to set one or more system properties (e.g. by calling `System#setProperty`). The code to which this entitlement is granted can change the properties listed in the `properties` field. In general, it's best to avoid changing a system property dynamically as this can have effects on code which later reads the property. The global nature of system properties means one plugin could then affect another, depending on load order.
+
+Example:
+```yaml
+org.example.module: # or 'ALL-UNNAMED' if the plugin is non-modular
+  - write_system_properties:
+      properties:
+        - property.one
+        - property.two
+```
+Check the Entitlements {es-repo}tree/main/libs/entitlement/README.md[README in the elasticsearch repository] for more information.
+
 
 [[plugin-descriptor-file-classic]]
 ==== The plugin descriptor file for classic plugins