[Security Solution] Allow to specify custom servers and security for the result OpenAPI bundle

[maximpn]

Resolves: #189269
Resolves: #189270

Summary

This PR adds an ability to specify OpenAPI servers and security requirements (security) to be used in the result bundle. servers and/or security in the source OpenAPI specs are be dropped when custom servers and/or security provided.

Details

Kibana is usually deployed at a single access point and manages authentication in a central way. That way it's much more convenient to have control on what servers and security are present in the result bundles. It will help to avoid conflicts, duplicates and update them in centralized way.

This PR extends OpenAPI bundler configuration options with prototypeDocument. "Prototype" in the name means it's a prototype for the result. The bundler uses certain properties from that prototype OpenAPI document to add them to the result OpenAPI bundle. The following properties are used

• info representing OpenAPI Info object (former options.specInfo)
• servers OpenAPI Server Object Array
• security + components.securitySchemes OpenAPI Security Requirement Object Array + OpenAPI Security Schemes Object (validation checks that both fields are set otherwise an error is thrown)

For convenience prototypeDocument could be specified as a string path to a file containing prototype OpenAPI document.

How to test?

prototypeDocument can be specified for bundle and merge utilities like the following

bundle

const { bundle } = require('@kbn/openapi-bundler');

(async () => {
  await bundle({
    sourceGlob: 'source/glob/*.yaml',
    outputFilePath: 'output/bundle.yaml,
    options: {
      prototypeDocument: {
        info: {
          title: 'Some title',
          description: 'Some description',
        },
        servers: [{
          url: 'https://{kibana_url}',
          variables: {
            kibana_url: {
              default: 'localhost:5601',
            }
          }
        }],
        security: [{ ApiKeyAuth: [] }],
        components: {
          securitySchemes: {
            ApiKeyAuth: {
              type: 'apiKey',
              in: 'header',
              name: 'Authorization',
            }
          }
        }
      },
    },
  });

bundle with external prototype document

const { bundle } = require('@kbn/openapi-bundler');

(async () => {
  await bundle({
    sourceGlob: 'source/glob/*.yaml',
    outputFilePath: 'output/bundle.yaml,
    options: {
      prototypeDocument: 'path/to/prototype_document.yaml',,
    },
  });

merge

const { merge } = require('@kbn/openapi-bundler');

(async () => {
  await merge({
    sourceGlobs: [
      'absolute/path/to/file.yaml`,
      'some/glob/*.schema.yaml',
    ],
    outputFilePath: 'output/file/path/bundle.yaml',
    options: {
      prototypeDocument: {
        info: {
          title: 'Some title',
          description: 'Some description',
        },
        servers: [{
          url: 'https://{kibana_url}',
          variables: {
            kibana_url: {
              default: 'localhost:5601',
            }
          }
        }],
        security: [{ ApiKeyAuth: [] }],
        components: {
          securitySchemes: {
            ApiKeyAuth: {
              type: 'apiKey',
              in: 'header',
              name: 'Authorization',
            }
          }
        }
      },
    },
  });
})();

merge with external prototype document

const { merge } = require('@kbn/openapi-bundler');

(async () => {
  await merge({
    sourceGlobs: [
      'absolute/path/to/file.yaml`,
      'some/glob/*.schema.yaml',
    ],
    outputFilePath: 'output/file/path/bundle.yaml',
    options: {
      prototypeDocument: 'path/to/prototype_document.yaml',
    },
  });
})();

The result bundles will contain specified servers and security while source servers and security will be dropped.

[elasticmachine]

Pinging @elastic/security-detections-response (Team:Detections and Resp)

[elasticmachine]

Pinging @elastic/security-solution (Team: SecuritySolution)

[elasticmachine]

Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management)

[e40pud]

DE changes LGTM

[xcrzx]

LGTM 👍 Left just a couple of nits.

[xcrzx]

Should these two bundler calls also be wrapped in an IIFE?

[xcrzx]

It looks the same as in bundler, tet's deduplicate this logic

[xcrzx]

Is this condition relevant? It doesn't look like anything other than an object can be returned from readFile.

[maximpn]

Generally JSON/YAML files may contain an array, primitive values or an empty string. These files are invalid OpenAPI documents. Even not all objects are valid OpenAPI documents but that validation is omitted here since it looks for specific keys in that object.

[xcrzx]

Shouldn't version be overridable by the prototypeDoc.info.version?

[maximpn]

bundle utility groups OpenAPI specs by info.version. blankOasDocumentFactory constructs a blank OpenAPI document with a desired info.vesion.

merge utility on the other hand should produce result bundles with specified version.

[kibana-ci]

💛 Build succeeded, but was flaky

• Buildkite Build
• Commit: 42ba973

Failed CI Steps

• Jest Tests #3

Metrics [docs]

Unknown metric groups

ESLint disabled in files

id	before	after	diff
@kbn/openapi-bundler	1	2	+1

Total ESLint disabled count

id	before	after	diff
@kbn/openapi-bundler	3	4	+1

History

• 💛 Build #224517 was flaky d22c1d7c121a6a4667368d5ead9768360b3b7e05
• 💔 Build #224308 failed e3d3681d484259ab0516ca10e408512d5b81a449

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @maximpn