Ror Internals
Developmentror-internalsRor Internals is an Agent Skill for development published in the sscarduzio/elasticsearch-readonlyrest-plugin repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
ReadonlyREST internal architecture knowledge — kibana rule semantics and decision tree (BaseKibanaRule.shouldMatch, shared by the kibana and legacy kibana_access rules), FLS engine strategies, correlation-ID header contract, ROR admin API endpoints and their ES action names. Use when coding or reviewing changes to the kibana rules, FLS/fields rule, audit logging, or the _readonlyrest admin/metadata APIs.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/sscarduzio/elasticsearch-readonlyrest-plugin/blob/HEAD/.claude/skills/ror-internals/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ror-internals, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
ROR Internals (ES plugin)
Distilled from beshu-tech/readonlyrest-internal/architecture/ and api/. Treat as design intent; the code is authority (update this on discrepancy).
kibana rule
Shared decision tree (shouldMatch): core/.../blocks/rules/kibana/BaseKibanaRule.scala. Two concrete rules extend it:
- Current:
KibanaUserDataRule.scala— YAML namekibana. - Legacy:
KibanaAccessRule.scala— YAML namekibana_access,@deprecatedsince1.48.0.
Action groups are Scala PatternsMatcher vals in KibanaActionMatchers.scala (roActionPatternsMatcher, rwActionPatternsMatcher, clusterActionPatternsMatcher, adminActionPatternsMatcher, nonStrictActions, indicesWriteAction) — there is no Constants.java.
- Omitting
kibana_access≡unrestricted. The explicitunrestrictedvalue exists so YAML anchor/template blocks can override a templatedrwdefault. - Design intent of all restricted levels: the kibana index is writable (saved objects must work), all other "data indices" are read-only — protect against accidental data loss. Special-case writable indices exist (e.g. reporting).
admingrantsrw-level kibana access plus the fulladminActionPatternsMatcherset on no-index requests and the ROR config index / index-management / tags paths (step 9) — that includesindices:admin/create,indices:admin/ilm/*,cluster:admin/ingest/pipeline/put, etc., none of whichrwcan reach. It also gates the ROR settings/activation-keys APIs.
| level | kibana_index | data indices | reporting index | cluster mgmt | ROR settings API |
|---|---|---|---|---|---|
| admin | full | read only | full | read only | full |
| rw | full | read only | full | read only | none |
| ro | non-strict only¹ | read only | full | none | none |
| ro_strict | read only | read only | none | none | none |
| api_only² | non-strict only² | read only | none | none | none |
¹ ro cannot modify the kibana index in general (kibanaCanBeModified = false). It only permits a narrow allow-list of saved-object writes via isRoNonStrictCase (step 8) — discover UI state, short URLs, index-pattern/url/config doc updates. It is not full kibana-index write access.
² api_only (YAML value api_only) is its own KibanaAccess value, not an alias. On the kibana index it behaves like ro, not ro_strict: kibanaCanBeModified is false for RO | ROStrict | ApiOnly, but step 8 (isRoNonStrictCase) is gated by isAccessOtherThanRoStrictConfigured (access =!= ROStrict) — true for api_only, so it CAN reach the narrow non-strict kibana-write allow-branch (discover state / short URLs), which ro_strict never can. Its distinct restriction is the allowed_api_paths coupling (KibanaUserDataRuleDecoder.scala), a separate layer gating which ROR/ES API paths may be called.
Decision tree — shouldMatch is a short-circuit OR chain (first match → ALLOW; if none match → REJECT). Order below mirrors BaseKibanaRule.shouldMatch exactly:
isUnrestrictedAccessConfigured— access level isunrestricted.isUserMetadataRequest— ROR user-metadata path (login).isDevNullKibanaRelated— request targets the internal.kibana-devnullindex.isRoAction— action matchesroActionPatternsMatcher.isClusterAction— action matchesclusterActionPatternsMatcher.emptyIndicesMatch— request has no indices AND ((kibana writable AND RW action) OR (admin access AND admin action)). Not a blanket allow.isKibanaSimpleData— kibana writable AND request is a Kibana sample-data index/stream.isRoNonStrictCase— targets kibana index, level ≠ro_strict, kibana not modifiable, non-strict allowed path AND non-strict action (saves discover UI state / short URLs).isAdminAccessEligible— admin access configured AND admin action AND request allowed for admin (no-index, ROR index, index-management or tags path).isKibanaIndexRequest— kibana writable AND targeting kibana index AND (RO OR RW ORindices:data/write/*action).
Changing the order of these checks is a behavioral change — review accordingly.
Note: indices:data/write/* is not blanket-rejected — it's allowed via step 10 (writable kibana index) and is also a member of adminActionPatternsMatcher (step 9).
FLS (fields rule) engines
Code: FieldsFiltering.scala — per ES-version module, e.g. es94x/src/main/scala/tech/beshu/ror/es/handler/response/FieldsFiltering.scala (NOT core/; uses XContentMapValues.filter, same method as ES source filtering). The strategy types (FlsAtLuceneLevelApproach, BasedOnBlockContextOnly, RequestFieldsUsage) live in core/.../domain/elasticsearch.scala; strategy resolution is in the fields rule.
- Engines:
es_with_lucene(default — ES handles, lucene fallback),es(no fallback), and a hidden, undocumentedluceneengine: full old-style lucene handling, kept as an emergency escape hatch when the ES-level path has a bug. Never remove it; never document it publicly. - Request field usage trifurcation (
RequestFieldsUsage):NotUsingFields(best case),UsingFields(extractable → not-allowed fields get obfuscated, e.g.field1→field1_ROR_12Xb593a24),CannotExtractFields(query_string, function_score, wildcards, scripts — no way to enumerate fields → must fall back to lucene). - Resolved strategies:
FlsAtLuceneLevelApproach(thread-context header set per ES module),BasedOnBlockContextOnly.EverythingAllowed,BasedOnBlockContextOnly.NotAllowedFieldsUsed(query rewrite viaQueryWithModifiableFieldsin each ES module). The resolved strategy is logged underfls. - Lucene-level FLS requires ROR on all nodes and is slow; ES-level does not. Keep this constraint in mind when reviewing FLS changes.
Correlation ID contract
ROR ES is session-unaware; the x-ror-correlation-id request header (http.scala) correlates requests. If absent, ROR generates one as a bare UUID (CorrelationId.random, http.scala). The metadata endpoint (/_readonlyrest/metadata/user) echoes that CorrelationId back as the correlation_id JSON body field (MetadataResponse.scala), NOT as a response header — there is no x-ror-logging-id. Don't confuse it with RequestContext.Id (RequestContext.scala), the separate internal per-request id of the form <correlationId>-<hashCode>#<taskId> used in log output — that composite is NOT what the metadata endpoint returns. The ID goes into the audit log; Kibana relies on this contract for session-scoped log correlation.
ROR API endpoints ↔ ES actions
Every ROR REST endpoint maps to a dedicated ES action name (used in ACL actions rule and audit). The canonical names below are cluster:internal_ror/* — that is what RorAction declares (elasticsearch.scala) and what audit logs emit. The older cluster:ror/* spellings are legacy aliases still accepted in ACL YAML for backward compat (via rorActionByOutdatedName) but never appear in audit output — don't grep audit logs for them. Keep the mapping stable:
| Endpoint | Action (canonical; cluster:ror/* legacy alias) |
|---|---|
GET /_readonlyrest/metadata/user | cluster:internal_ror/user_metadata/get |
POST /_readonlyrest/admin/refreshconfig | cluster:internal_ror/config/refreshsettings |
GET/POST /_readonlyrest/admin/config (+ /config/file, /config/audit) | cluster:internal_ror/config/manage (all served by MainSettingsApi) |
POST/DELETE /_readonlyrest/admin/config/test | cluster:internal_ror/testconfig/manage; in-memory test config, TTL via the ttl field in the POST request body (TestSettingsApi) |
POST/DELETE /_readonlyrest/admin/config/test/authmock | cluster:internal_ror/authmock/manage; mocks persist until DELETE or plugin restart (no TTL in the current AuthMockApi) |
POST /_readonlyrest/admin/audit/event | cluster:internal_ror/audit_event/put |
Behavioral invariants:
- Audit event API: body ≤ 5,000 bytes (
MAX_AUDIT_EVENT_REQUEST_CONTENT_IN_BYTES = 5 * 1000, not 5,120 — 413 otherwise); request is always audited, but custom fields are added only if the request is ALLOWED; custom fields must never overwrite default serializer fields. - Auth mocks exist to support impersonation (
IMPERSONATE_ASheader) for rules backed by external services (LDAP, external authn/authz) — ROR can't query the real service with the impersonated user's credentials, so it answers from the mock. Mocks persist until an explicitDELETEor a plugin restart — there is no server-side TTL in the currentAuthMockApi(unlike the test config endpoint, which does take attl). - Cluster config summary (
cluster:internal_ror/config/manage): the handling node propagates to all nodes and compares each response against its own config; any difference is a warning (NODE_RETURNED_CONFIG_ERROR,NODE_FORCED_FILE_CONFIG, ...); an error loading the current node's config fails the whole request (nothing to compare against). - 403 body shape for all endpoints is the standard ROR forbidden JSON (
"reason":"forbidden"); don't invent new error shapes.