fix(saved-objects): guard against source commands in ComposerQuery pipeline

rudolf · cursoragent · rudolf · commit 6f2330f53951 · 2026-05-22T21:15:52.000+02:00
Restores the runtime check that rejects pipelines starting with FROM, ROW,
SHOW, METRICS, or TS. The check now runs against toRequest().query rather
than the raw string, since pipeline is now always a ComposerQuery.

Without this a developer writing esql`FROM .kibana | LIMIT 10` would get
an opaque ES|QL syntax error from Elasticsearch instead of a clear message.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/dev_docs/tutorials/saved_objects_esql.mdx b/dev_docs/tutorials/saved_objects_esql.mdx
@@ -7,178 +7,97 @@ date: 2026-03-02
 tags: ['kibana', 'dev', 'tutorials', 'saved-objects', 'esql']
 ---
 
-`SavedObjectsClientContract.esql` allows you to query Saved Objects using [ES|QL (Elasticsearch Query Language)](https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql). It returns tabular results (columns and values) directly from Elasticsearch, which can be useful for analytics, aggregations, and cross-type queries that don't fit the `find` or `search` methods.
-
-## Relationship to `find` and `search`
+`SavedObjectsClientContract.esql` allows you to query Saved Objects using [ES|QL (Elasticsearch Query Language)](https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql). It returns tabular results (columns and values) directly from Elasticsearch, useful for analytics, aggregations, and cross-type queries that don't fit `find` or `search`.
 
 | Method | Use case | Response format |
 |--------|----------|----------------|
-| `find` | Simple filtering and pagination of saved objects | Structured `SavedObject[]` |
-| `search` | Complex queries using Elasticsearch Query DSL | Raw Elasticsearch search hits |
-| `esql` | Tabular queries using ES|QL syntax | Tabular columns + values |
-
-Use `esql` when you need ES|QL-specific features like `STATS`, `EVAL`, `ENRICH`, or pipe-based query composition.
+| `find` | Simple filtering and pagination | Structured `SavedObject[]` |
+| `search` | Elasticsearch Query DSL | Raw search hits |
+| `esql` | ES|QL — `STATS`, `EVAL`, `ENRICH`, pipes | Tabular columns + values |
 
 <DocCallOut title="With great power comes great responsibility">
-  While the `esql` method is powerful, it can increase code complexity, introduce performance issues and introduce security risks (like injection attacks). Carefully consider how you would like to use this method in your plugin to unlock value for users.
+  The `esql` method gives direct access to saved object indices and executes with elevated `kibana_system` privileges. Always construct pipelines server-side and use parameterized values for any user-supplied input.
 </DocCallOut>
 
-## The `pipeline` concept
+## Basic usage
 
-Like `search` and `find`, you specify saved object **types** as a dedicated parameter — you never need to know or write index names. The `esql` method resolves the correct Elasticsearch indices from the `type` parameter and auto-generates the `FROM` clause. Security filters (namespace + type restriction) are injected via the `filter` parameter, so you don't need `WHERE type ==` either.
+You specify saved object **types** — never index names. The `FROM` clause, namespace filter, and type restriction are all injected automatically. You write only the ES|QL **processing pipeline**.
 
-You write only the ES|QL **processing pipeline** — everything after `FROM`:
+Build the pipeline with the `esql` tagged template from `@elastic/esql`:
 
 ```ts
+import { esql } from '@elastic/esql';
 import { isResponseError } from '@kbn/es-errors';
 import { MY_TYPE } from './saved_objects';
 
-/** ...inside a route handler: */
-async (ctx, req, res) => {
-  const core = await ctx.core;
-  const savedObjectsClient = core.savedObjects.client;
-  try {
-    const result = await savedObjectsClient.esql({
-      type: [MY_TYPE],
-      namespaces: ['default'],
-      pipeline: `| KEEP ${MY_TYPE}.title, ${MY_TYPE}.description
-        | SORT ${MY_TYPE}.title
-        | LIMIT 100`,
-    });
-    return res.ok({ body: { columns: result.columns, values: result.values } });
-  } catch (e) {
-    if (isResponseError(e)) {
-      log.error(JSON.stringify(e.meta.body, null, 2));
-    }
-    throw e;
-  }
-}
-```
-
-To include METADATA fields on the auto-generated FROM clause, use the `metadata` option:
+const titleCol = esql.col(`${MY_TYPE}.title`);
+const descCol = esql.col(`${MY_TYPE}.description`);
 
-```ts
 const result = await savedObjectsClient.esql({
   type: [MY_TYPE],
   namespaces: ['default'],
-  metadata: ['_id', '_source'],
-  // generates: FROM .kibana METADATA _id, _source | WHERE ...
-  pipeline: '| WHERE my_type.title LIKE "test*" | LIMIT 100',
+  pipeline: esql`
+    KEEP ${titleCol}, ${descCol}
+    | SORT ${titleCol}
+    | LIMIT 100
+  `,
 });
 ```
 
-See the full example in the Kibana repository at `examples/saved_objects`.
-
-## Safe pipeline construction with the `esql` composer
-
-Instead of a raw pipeline string, you can pass a `ComposerQuery` built with the `esql` tagged
-template from `@elastic/esql`. Template holes (`${{ name: value }}`) are automatically promoted
-to ES|QL named parameters — values are passed to Elasticsearch at the protocol level and never
-appear in the query string.
+To include `METADATA` fields (e.g. `_id`, `_source`), use the `metadata` option:
 
 ```ts
-import { esql } from '@elastic/esql';
-
-const searchTerm = req.body.title; // user-supplied input
-
 const result = await savedObjectsClient.esql({
   type: [MY_TYPE],
   namespaces: ['default'],
-  // ${{ title }} → ?title param; value sent separately over the wire
-  // The esql tag does not take a leading '|' — the pipe is added when joining with FROM.
-  pipeline: esql`WHERE my_type.title LIKE ${{ title: searchTerm }} | LIMIT 100`,
+  metadata: ['_id', '_source'],
+  pipeline: esql`KEEP _id, ${esql.col(`${MY_TYPE}.title`)} | LIMIT 100`,
 });
 ```
 
-The `esql` tag accepts a pipeline-only template (no `FROM` required). It temporarily wraps the
-template in `FROM a | …` to satisfy the parser, then strips the source command, leaving a
-`ComposerQuery` whose `.toRequest()` returns the `?param` placeholder string alongside a
-`params` array. The SO client calls `.toRequest()` internally.
-
-You can also mix composer params with a raw `params` array — they are merged before the request
-is sent, with composer params first.
-
-## Safe pipeline construction with ES|QL params
-
-When interpolating user input into ES|QL pipelines, **never** use string concatenation. Instead, use ES|QL's native parameterization — named params (`?paramName`) or positional params (`?`) — to separate code from data at the protocol level.
+See the full example in the Kibana repository at `examples/saved_objects`.
 
-### Named params `?paramName` (recommended for user input)
+## Handling user input safely
 
-Use `?paramName` placeholders in the pipeline string and pass the values via the `params` array as `{ name: value }` entries. This is true parameterization — the values are never interpolated into the query string, preventing injection attacks.
+Use `${{ name: value }}` holes in the `esql` template for any user-supplied value. The value becomes a named ES|QL parameter — it is forwarded to Elasticsearch separately and never appears in the query string.
 
 ```ts
-import type { estypes } from '@elastic/elasticsearch';
-
-const userInput = req.body.searchTerm;
+const searchTerm = req.body.title; // user-supplied input
+const titleCol = esql.col(`${MY_TYPE}.title`);
 
 const result = await savedObjectsClient.esql({
-  type: ['my_type'],
+  type: [MY_TYPE],
   namespaces: ['default'],
-  pipeline: '| WHERE my_type.title LIKE ?searchTerm | LIMIT 100',
-  // Named params are supported by ES at runtime, but the ES client TypeScript types
-  // only define positional params — cast through unknown to bridge the type gap.
-  params: [{ searchTerm: userInput }] as unknown as estypes.EsqlESQLParam[],
+  pipeline: esql`
+    WHERE ${titleCol} LIKE ${{ title: searchTerm }}
+    | LIMIT 100
+  `,
 });
 ```
 
-The pipeline sent to Elasticsearch will be `| WHERE my_type.title LIKE ?searchTerm | LIMIT 100` — with `searchTerm` as a separate parameter, never interpolated into the pipeline string.
-
-### Positional params `?` (alternative)
-
-ES|QL also supports positional `?` placeholders. Params are plain values (string, number, boolean, or null) matched by position:
-
-```ts
-const result = await savedObjectsClient.esql({
-  type: ['my_type'],
-  namespaces: ['default'],
-  pipeline: '| WHERE my_type.title LIKE ? | LIMIT 100',
-  params: [userInput],
-});
-```
+**Never pass user input via `esql.exp(userInput)`** — that injects a raw ES|QL expression and bypasses parameterization entirely.
 
 ## Security model
 
-### Execution context — `kibana_system` user
-
-The ES|QL pipeline executes with the privileges of the `kibana_system` Elasticsearch user, which has elevated access including `manage_enrich` and broad index monitoring permissions. This means the pipeline can access resources that the end user may not be authorized to see.
-
-**Never inject arbitrary or untrusted user input directly into the pipeline string.** If a user can control the full pipeline, they could use commands like `ENRICH` to join against enrich policies whose source data they would not normally have access to — this is a privilege escalation. Always construct the pipeline server-side and use parameterized values (see [Safe pipeline construction](#safe-pipeline-construction-with-esql-params)) for any user-provided input.
-
-Using `ENRICH` in your pipeline is perfectly fine when you control the pipeline and are enriching from a policy whose data is appropriate for all users who will see the results.
-
-### Index resolution from types
+### Execution context
 
-Like `search` (which passes `index: getIndicesForTypes(types)` internally), the `esql` method resolves the correct Elasticsearch indices from the `type` parameter and auto-generates the `FROM` clause. You never need to know the index name — it is an implementation detail handled by the saved objects system.
+The pipeline executes as the `kibana_system` Elasticsearch user, which has elevated privileges. A user who controls the pipeline could use `ENRICH` to access data they are not authorized to see. Always construct the pipeline server-side; never let user input determine the pipeline structure.
 
 ### Space and type filtering
 
-When you call `esql()`, namespace (space) and type filters are automatically injected into the `filter` parameter of the ES|QL request. The filter restricts results to the specified types and namespaces, so you don't need `WHERE type == "..."` in your pipeline. This works the same way as the `search` method:
+Namespace and type filters are automatically injected into every request. You never need `WHERE type == "..."` in your pipeline. If the caller is not authorized to access the requested namespaces or types, an empty response is returned.
 
-1. `spacesExtension.getSearchableNamespaces()` resolves which namespaces the user can access
-2. `securityExtension.authorizeFind()` checks RBAC permissions
-3. A namespace bool filter (including type restriction) is constructed and merged with any user-provided `filter`
+### User-provided filters
 
-If the user is not authorized to access any of the requested namespaces or types, an empty response is returned.
-
-### User-provided filters are merged, not replaced
-
-If you provide a `filter` in the options, it is merged with the security filter using `{ bool: { must: [securityFilter, yourFilter] } }`. Your filter is never used in isolation.
+If you supply a `filter` option it is merged with the security filter as `{ bool: { must: [securityFilter, yourFilter] } }` — never used in isolation.
 
 ## Encrypted attributes
 
-Encrypted saved object attributes are handled differently depending on whether `_source` is present in the response:
-
-- **With `_source` (via `metadata: ['_id', '_source']`):** The full document in `_source` contains all attributes needed for AAD (Additional Authenticated Data) reconstruction. Encrypted attributes are by default stripped from `_source`, or are **decrypted** in `_source`, using the same path as `find` and `search`, if registered with the `dangerouslyExposeValue` option. If decryption fails (e.g., key rotation), all encrypted attributes are stripped from `_source`.
-- **Standalone scalar columns (e.g., `connector.secrets`):** Always replaced with `null`, regardless of `_source` decryption. These columns contain raw ciphertext that cannot be used outside the document context.
-
-For example, if a `connector` type has an encrypted `secrets` attribute:
-- `connector.secrets` column → always `null`
-- `_source` column → contains the full document with `secrets` decrypted (or stripped on failure)
+- **Standalone scalar columns** (e.g. `connector.secrets`): always replaced with `null`.
+- **`_source` column** (requires `metadata: ['_id', '_source']`): encrypted attributes are decrypted using the same path as `find` and `search`. If decryption fails, encrypted attributes are stripped from that row's `_source`.
 
 ## Response structure
 
-The `esql` method returns the raw ES|QL response with `columns` and `values`:
-
 ```json
 {
   "columns": [
@@ -194,13 +113,12 @@ The `esql` method returns the raw ES|QL response with `columns` and `values`:
 
 ## When to use
 
-- You need ES|QL-specific operations like `STATS`, `EVAL`, `ENRICH`, `DISSECT`, or `GROK`
-- You want tabular results for analytics or reporting
-- You need to compute aggregations across saved object types
+- ES|QL-specific operations: `STATS`, `EVAL`, `ENRICH`, `DISSECT`, `GROK`
+- Tabular results for analytics or reporting
+- Aggregations across saved object types
 
 ## When not to use
 
-- You want structured `SavedObject` instances with `id`, `attributes`, `references` - use `find` instead
-- You need Elasticsearch Query DSL features like runtime mappings or aggregation trees - use `search` instead
-- Simple filtering and pagination - use `find` instead
-- You need ES|QL source commands like `ROW`, `SHOW`, or `METRICS` - use the raw Elasticsearch client directly
+- You want structured `SavedObject` instances — use `find`
+- You need Elasticsearch Query DSL — use `search`
+- You need ES|QL source commands like `ROW` or `SHOW` — use the raw Elasticsearch client
diff --git a/examples/saved_objects/server/esql_example_routes.ts b/examples/saved_objects/server/esql_example_routes.ts
@@ -43,7 +43,11 @@ export function registerEsqlExampleRoutes(router: IRouter, log: Logger) {
           const result = await savedObjectsClient.esql({
             type: [TYPE_A, TYPE_B],
             namespaces: ['default'],
-            pipeline: esql`KEEP type, \`type-a.myField\`, \`type-b.anotherField\` | SORT type | LIMIT 100`,
+            pipeline: esql`
+              KEEP type, \`type-a.myField\`, \`type-b.anotherField\`
+              | SORT type
+              | LIMIT 100
+            `,
           });
           return res.ok({
             body: {
@@ -89,7 +93,10 @@ export function registerEsqlExampleRoutes(router: IRouter, log: Logger) {
           const result = await savedObjectsClient.esql({
             type: TYPE_A,
             namespaces: ['default'],
-            pipeline: esql`WHERE ${esql.exp(`${TYPE_A}.myField`)} == ${{ searchTerm }} | LIMIT 10`,
+            pipeline: esql`
+              WHERE ${esql.exp(`${TYPE_A}.myField`)} == ${{ searchTerm }}
+              | LIMIT 10
+            `,
           });
           return res.ok({
             body: {
diff --git a/src/core/packages/saved-objects/api-server-internal/src/lib/apis/esql.test.ts b/src/core/packages/saved-objects/api-server-internal/src/lib/apis/esql.test.ts
@@ -136,6 +136,22 @@ describe('esql', () => {
     expect(request.query).toMatch(/^FROM .+ METADATA _id, _source \| LIMIT 10$/);
   });
 
+  it('should throw if pipeline starts with a source command', async () => {
+    await expect(
+      repository.esql({ ...options, pipeline: esql`FROM .kibana | LIMIT 10` })
+    ).rejects.toThrowError('options.pipeline must not start with a source command');
+
+    await expect(repository.esql({ ...options, pipeline: esql`ROW x = 1` })).rejects.toThrowError(
+      'options.pipeline must not start with a source command'
+    );
+
+    await expect(repository.esql({ ...options, pipeline: esql`SHOW INFO` })).rejects.toThrowError(
+      'options.pipeline must not start with a source command'
+    );
+
+    expect(client.esql.query).not.toHaveBeenCalled();
+  });
+
   it('should merge user-provided filter with namespace filter', async () => {
     const userFilter = { term: { 'index-pattern.title': 'my-pattern' } };
     await repository.esql({ ...options, filter: userFilter });
diff --git a/src/core/packages/saved-objects/api-server-internal/src/lib/apis/esql.ts b/src/core/packages/saved-objects/api-server-internal/src/lib/apis/esql.ts
@@ -104,6 +104,14 @@ export async function performEsql(
       : esql.from(indices).print();
 
   const req = pipeline.toRequest();
+
+  if (/^\s*(FROM|ROW|SHOW|METRICS|TS)\b/i.test(req.query)) {
+    throw SavedObjectsErrorHelpers.createBadRequestError(
+      'options.pipeline must not start with a source command (FROM, ROW, SHOW, METRICS, TS). ' +
+        'The FROM clause is auto-generated from the type parameter.'
+    );
+  }
+
   // toRequest() prints pipeline-only queries without a leading '|';
   // we supply the separator when joining with the FROM clause.
   const query = `${fromClause} | ${req.query}`;
diff --git a/src/core/packages/saved-objects/api-server/src/apis/esql.ts b/src/core/packages/saved-objects/api-server/src/apis/esql.ts
@@ -24,7 +24,8 @@ import type { ComposerQuery } from '@elastic/esql';
  * @remarks
  * **Security:** Template holes (`${{ name: value }}`) in the `esql` tag are automatically
  * promoted to ES|QL named parameters — values are forwarded to Elasticsearch at the protocol
- * level and never appear in the query string.
+ * level and never appear in the query string. Never pass user input via `esql.exp(userInput)`,
+ * which injects a raw expression and bypasses parameterization entirely.
  *
  * Standalone encrypted scalar columns are always replaced with `null`. When `_source` is
  * present (via `metadata: ['_id', '_source']`), encrypted attributes within `_source` are
@@ -52,7 +53,10 @@ export interface SavedObjectsEsqlOptions
    * ```ts
    * import { esql } from '@elastic/esql';
    *
-   * pipeline: esql`WHERE dashboard.title LIKE ${{ title: searchTerm }} | LIMIT 100`,
+   * pipeline: esql`
+   *   WHERE dashboard.title LIKE ${{ title: searchTerm }}
+   *   | LIMIT 100
+   * `,
    * ```
    */
   pipeline: ComposerQuery;
diff --git a/src/core/server/integration_tests/saved_objects/service/lib/esql.test.ts b/src/core/server/integration_tests/saved_objects/service/lib/esql.test.ts
@@ -213,6 +213,24 @@ describe('SOR - esql API', () => {
     expect(result.values[0][0]).toBe('charlie.brown@example.com');
   });
 
+  it('should reject pipelines starting with a source command', async () => {
+    await expect(
+      savedObjectsRepository.esql({
+        type: 'esql-test-type',
+        namespaces: ['default'],
+        pipeline: esql`FROM .kibana | LIMIT 10`,
+      })
+    ).rejects.toThrow('options.pipeline must not start with a source command');
+
+    await expect(
+      savedObjectsRepository.esql({
+        type: 'esql-test-type',
+        namespaces: ['default'],
+        pipeline: esql`ROW x = 1`,
+      })
+    ).rejects.toThrow('options.pipeline must not start with a source command');
+  });
+
   it('should return empty response for unknown types', async () => {
     const result = await savedObjectsRepository.esql({
       type: 'unknown-type',
