14 Securing Coherence RAG

Protect optional RAG administration, model downloads, and document imports with their component-specific policies.

This chapter applies when the Coherence RAG component is installed. Its REST policy is distinct from the general Coherence REST cache API. RAG REST accepts configured bearer tokens and API keys. Basic authentication is rejected at this API layer; an approved proxy can authenticate and forward a supported identity form. Cookie/session authentication is not currently part of this contract.

Sensitive operations require authentication. Configuration, model, and store mutations and document imports require the configured admin role. _config reads require authentication and return 404 for sensitive keys. Test both authorization and redaction; do not depend on hiding a UI control.

Use RAG Configuration and Model Download Policy and Restricting RAG Document Imports. Protect API keys and provider secrets using the supported runtime credential sources and network architecture. Do not put secrets into example URLs or log complete authorization headers.

• RAG Configuration and Model Download Policy
  Limit mutable RAG settings and approve the local model artifacts that may be downloaded.
• Restricting RAG Document Imports
  Approve import schemes and locations and preserve the validated destination through HTTP and filesystem access.

RAG Configuration and Model Download Policy

Limit mutable RAG settings and approve the local model artifacts that may be downloaded.

The default administrative role is admin. Restrict runtime configuration writes to the explicit allowlist; sensitive fields and protected security/import controls retain their own deny policy. The following values illustrate the shipped defaults:

coherence.rag.security.admin-role=admin
coherence.rag.config.write.allowed-properties=model.embedding,model.chat,model.scoring,coherence.rag.default.parser

Test an authenticated non-admin, an allowed admin update, a forbidden property, and sensitive readback. A valid administrative role does not authorize arbitrary property names or provider-secret disclosure. Apply corresponding tests to sibling model/store mutations rather than only _config.

Local model downloads

The download allowlist applies to local ONNX embedding/scoring models obtained from HuggingFace. JAR-wired CDI ModelProvider implementations do not use this gate, and chat-model selectors are not validated by this download policy.

coherence.rag.security.huggingface.allowed-models=sentence-transformers/all-MiniLM-L6-v2,cross-encoder/ms-marco-TinyBERT-L-2-v2

Use exact model names or a deliberately approved owner-wide trailing wildcard. With an empty allowlist, compatibility permits downloads and emits a bounded startup warning; hardened mode rejects downloads until an allowlist is configured. Once non-empty, the allowlist constrains values in either profile.

Approval of a model name is not a general integrity guarantee for all downloaded artifacts. Control provider versions, network egress, artifact storage, and the deployment's model provenance process. Verify an approved model and an unapproved name before rollout.

Restricting RAG Document Imports

Approve import schemes and locations and preserve the validated destination through HTTP and filesystem access.

Document imports are denied until allowed schemes and locations are configured. Use the narrowest locations needed by the ingestion job. The defaults include empty scheme/location allowlists, private-address rejection, a 10-second connect timeout, a 30-second read timeout, and a 50 MiB response bound.

coherence.rag.import.allowed-schemes=https
coherence.rag.import.http.allowed-hosts=documents.example.com
coherence.rag.import.http.allow-private-addresses=false
coherence.rag.import.connect-timeout-ms=10000
coherence.rag.import.read-timeout-ms=30000
coherence.rag.import.max-bytes=52428800

HTTP destination binding

HTTP(S) imports use direct connections. JVM-selected HTTP, HTTPS-tunnel, and SOCKS proxy routes are rejected with proxy-not-allowed. A deployment requiring those proxies needs another import mechanism under this contract.

For every initial request and redirect hop, the entire DNS answer is validated. The connection uses only an accepted address without resolving the origin again or reusing a connection from another hop. HTTPS retains the logical hostname for Host, SNI, and certificate verification. A mixed allowed/forbidden DNS answer is rejected before connection.

Loopback, link-local, metadata, and private destinations are rejected by default. The private-address opt-in still requires an allowed host and does not permit link-local metadata targets. Redirects are bounded and revalidated at every hop. Test a disallowed redirect, mixed DNS answers, wrong certificate name, selected proxy, timeout, and oversized response in an isolated ingestion environment.

Local files and cloud locations

For local imports, explicitly allow file and configure coherence.rag.import.file.allowed-roots. Canonical containment, secure parent traversal, and no-follow channel opening constrain filesystem access. Filesystem providers without SecureDirectoryStream support fail closed. A pre-open regular-file check rejects stable special files, including FIFOs.

The Java channel APIs used here do not expose the final file's type attributes through the returned channel. Replacing the final entry between its type check and open remains a race. Keep the allowed tree writable only by trusted ingestion principals. Do not present secure parent traversal as a complete guarantee against a hostile writer of the final entry.

Cloud-source allowlists are provider-specific: s3.allowed-buckets, azure.blob.allowed-containers, gcs.allowed-buckets, and oci.os.allowed-locations under coherence.rag.import. Allow the matching scheme as well as its location, and configure the provider's least-privilege credentials. A location allowlist does not grant cloud IAM permission, and IAM permission does not waive the import allowlist.