Status

Current state: Under Discussion

Discussion thread: https://lists.apache.org/thread/7qqknryoh4hxv2s7291j8g5shlcbock3

JIRA: SOLR-17767 - Getting issue details... STATUS

Released: Solr 10.x (TBD)

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast). Confluence supports inline comments that can also be used.

Motivation

Java Security Manager (JSM) was permanently removed in Java 24 (JEP 486). Solr previously relied on JSM to sandbox plugin code at runtime — restricting unauthorized file access, outbound network connections, System.exit() calls, and child process spawning. Without a replacement, Solr running on Java 24+ provides no runtime enforcement of these protections, leaving the JVM and any loaded plugin code unconstrained.

The OpenSearch project faced the same problem and solved it for OpenSearch 3.0 using a Java agent based on ByteBuddy instrumentation. See their write-up and the agent-sm source (Apache 2.0). This SIP proposes to use and adapt this approach.

Public Interfaces

The following new operator-facing interfaces are introduced:

• Agent JAR — server/lib/ext/solr-agent-sm-*.jar, loaded automatically via -javaagent: by the startup scripts when present.
• Default policy file — server/etc/agent-security.policy (JDK-style .policy syntax; ships with Solr; not intended for operator editing).
• Operator extension file — server/etc/agent-security-extra.policy (optional; absent is non-fatal; entries tagged source=OPERATOR in violation logs).
• Environment variables — SOLR_SECURITY_AGENT_MODE=warn|enforce (default: warn) and SOLR_SECURITY_AGENT_SKIP=true to disable.
• Violation metrics — per-type counters at /admin/metrics under security.agent.violations.file, .network, .exit, .exec.
• Deprecations — SolrPaths.assertPathAllowed() deprecated for new callers; existing JSM security.policy and solr-tests.policy files marked deprecated.

Proposed Changes

A new Gradle subproject solr/agent-sm/ will be created, producing a standalone Java agent JAR adapted from the Apache 2.0-licensed OpenSearch libs/agent-sm. The agent uses ByteBuddy @Advice instrumentation and StackWalker (Java 9+) to intercept JDK APIs at the bytecode level — applying to all code in the JVM including plugins, without requiring any code changes. It is virtual-thread safe (no thread-identity assumptions).

Four protection categories:

• File access — reads and writes restricted to configured Solr directories. Windows UNC paths (\\host\share) unconditionally blocked. Symlinks resolved to real path before policy check.
• Network access — outbound connections restricted to a permitted endpoint list. The default policy permits loopback addresses and all intra-cluster Solr and ZooKeeper traffic using port-based wildcards (*:<solr.port>, *:<zk-port>), covering all cluster nodes regardless of join order.
• JVM shutdown — System.exit() and Runtime.halt() restricted to an approved call-site list (SolrCLI, SolrDispatchFilter by default).
• Process execution — ProcessBuilder.start() and Runtime.exec() restricted to an approved call-site list (empty by default in production).

The initial release will use warn-only mode — violations are logged but operations are not blocked. Operators opt into enforce mode via SOLR_SECURITY_AGENT_MODE=enforce. A future release will flip the default.

Policy files use standard JDK .policy syntax extended with Solr variable substitution (${solr.home}, ${solr.port}, ${solr.zk.port}, etc.). The operator extension file ships with commented-out examples for all known modules that require external network access (jwt-auth, extraction/Tika, opentelemetry, s3-repository, gcs-repository, cross-dc-manager).

For a detailed specification and implementation plan - generated by Github's SpecKit, see http://cominvent.com/pub/jsm-spec.html.

Compatibility, Deprecation, and Migration Plan

• JSM removal in Java 24 is mandatory and outside Solr's control (see SOLR-17641 - Getting issue details... STATUS — startup scripts disable the security manager flag on Java ≥ 24).
• The default policy covers standard Solr directory layouts and intra-cluster traffic. Most deployments will require no configuration changes.
• Warn-only default ensures zero disruption on upgrade. Operators can review violation logs before enabling enforce mode.
• Modules that connect to external services (OIDC, OTLP, S3, GCS, Kafka, remote Tika) will require operator-added policy entries in enforce mode. Each module's reference guide page will include a ready-to-paste snippet.
• The existing server/etc/security.policy and solr-tests.policy JSM files are deprecated and retained as migration reference only; they are not enforced by the JVM on Java 24+.
• SolrPaths.assertPathAllowed() is deprecated for new callers; existing call sites are retained as defense-in-depth.

Security Considerations

This SIP restores runtime sandboxing for Solr on Java 24+ after JSM removal. Key points:

• All code in the JVM — including third-party plugins — is subject to enforcement without any plugin-side changes required.
• The agent runs in the JVM bootstrap classloader; it cannot be bypassed by application-level classloader manipulation.
• Intra-cluster network policy uses port-based wildcards rather than a host list, which is intentional: inter-node Solr HTTP is already PKI-authenticated, and a host list derived at startup would always be incomplete as nodes join incrementally.
• Warn-only default is a deliberate trade-off to avoid regressions in the plugin ecosystem; it does not reduce security versus the current state (no enforcement at all on Java 24+).

Test Plan

• Unit tests for PolicyLoader — variable substitution, merging, error handling.
• Interceptor unit tests for each protection category — permitted operations succeed, violations blocked/logged, counters increment.
• Full-stack integration test (SolrAgentIntegrationTest) running in enforce mode — all four protection categories exercised.
• Existing JSM-related tests repurposed where applicable.
• Virtual thread compatibility test suite — no false positives or negatives under Project Loom.
• Broader Solr integration suite run in warn mode to detect unexpected violations before the enforce-mode flip in a future release.

Rejected Alternatives

• Staying on Java < 24 — not viable long-term; Solr must support current Java LTS releases.
• Removing JSM protections without any replacement — unacceptable security regression.
• OS-level hardening only (systemd, seccomp) — not cross-platform; does not cover Windows or macOS.
• Dynamic ZK-watcher-based network policy — correct but significantly more complex; adds ZK client dependency to the agent JAR. Superseded by port-based wildcards for intra-cluster traffic.
• Building a Java agent from scratch — higher effort with no functional advantage over adapting the Apache 2.0-licensed OpenSearch implementation.