Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Security Solution] Bundle root level tags #183375

Closed
maximpn opened this issue May 14, 2024 · 5 comments
Closed

[Security Solution] Bundle root level tags #183375

maximpn opened this issue May 14, 2024 · 5 comments
Assignees
@maximpn
Labels
8.16 candidate docs Team:Detection Rule Management Security Detection Rule Management Team Team:Detections and Resp Security Detection Response Team Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. v8.16.0

Comments

@maximpn
Copy link
Contributor

maximpn commented May 14, 2024 •
edited
Loading

Epic: https://github.com/elastic/security-team/issues/9401 (internal)

Summary

We need to make sure each API domain has a unique tag assigned to have it properly represented at the API documentation platform. Since we bundle OpenAPI specs by domains it's possible to facilitate by making little adjustments to the OpenAPI bundler @kbn/openapi-bundler to assign tags automatically.

Details

Bump.sh (our new API reference documentation platform) uses OpenAPI tags for grouping API endpoints. It supports only a single tag per endpoint. We need to make sure relevant tags are set so we can achieve desired API endpoints grouping.

To facilitate the process of tagging it can be solved by @kbn/openapi-bundler via configuration. Since we bundle our OpenAPI specs per domain it makes sense to use a single domain tag and let the OpenAPI bundler assign it automatically. It could be achieved via the following example config

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

bundle({
  // ...
  options: {
    prototypeDocument: {
      tags: [{
        name: 'Some Domain API tag name',
        description: 'Some Domain API description',
        externalDocs: {
          url: 'https://some-external-documentation-url',
          description: 'External documentation description',
      }]
    }
  },
});
@maximpn maximpn added docs Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. Project:Serverless Work as part of the Serverless project for its initial release 8.15 candidate labels May 14, 2024
@elasticmachine
Copy link
Contributor

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

@maximpn maximpn changed the title [Security Solution] Bundle tags [Security Solution] Bundle root level tags May 14, 2024
@banderror banderror mentioned this issue May 17, 2024
Open
30 tasks
This was referenced May 20, 2024
Closed
Closed
Open
Closed
Closed
Open
Open
@banderror banderror added Team:Detections and Resp Security Detection Response Team Team:Detection Rule Management Security Detection Rule Management Team labels May 31, 2024
@elasticmachine
Copy link
Contributor

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

@elasticmachine
Copy link
Contributor

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

@banderror
Copy link
Contributor

@maximpn Could you please add more details to the description and:

  • Explain what root level tags are, give some examples.
  • Explain how tags may be used for API grouping.
  • Give an example of Operation Object's tags

@banderror banderror removed the Project:Serverless Work as part of the Serverless project for its initial release label Jun 4, 2024
@maximpn maximpn mentioned this issue Jul 31, 2024
Merged
maximpn added a commit that referenced this issue Aug 2, 2024
@maximpn
[Security Solution] Add tags by OpenAPI bundler (#189621)
845dd1f 
**Resolves:** #183375

## Summary

This PR implements functionality assigning a provided tag to OpenAPI `Operation object`s in the result bundle. Specified tag is also added as the only root level OpenAPI tag. This approach allows to produce domain bundles having a single tag assigned. At the next step domain bundles are merged together into single Kibana bundle where tags will allow to properly display grouping at Bump.sh (API reference documentation platform).

## Details

Bump.sh (our new API reference documentation platform) uses OpenAPI tags for grouping API endpoints. It supports only one tag per endpoint.

This PR facilitates preparation of Kibana OpenAPI bundle to be uploaded to Bump.sh by implementing functionality assigning a provided tag to OpenAPI `Operation object`s in the result domain bundles. It's implemented by providing an optional configuration option `assignTag` whose format is OpenAPI Tag Object. When `assignTag` isn't specified the bundler merges existing tags.

## Example

Consider the following bundling configuration

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

bundle({
  // ...
  options: {
    assignTag: {
      name: 'Some Domain API tag name',
      description: 'Some Domain API description',
      externalDocs: {
        url: 'https://some-external-documentation-url',
        description: 'External documentation description',
    }
  },
});
```

and source OpenAPI specs

**spec1.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec1
  version: '2023-10-31'
paths:
  /api/some_api:
    get:
      tags: ['Some local tag']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
```

**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec2
  version: '2023-10-31'
paths:
  /api/some_api:
    post:
      tags: ['Some global tag']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
tags:
  - name: Some global tag
```

**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec3
  version: '2023-10-31'
paths:
  /api/another_api:
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
```

After bundling above OpenAPI specs with the provided bundling script we'll get the following

**domain-bundle.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Bundled document
  version: '2023-10-31'
paths:
  /api/some_api:
    get:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
    post:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
  /api/another_api:
    get:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
tags:
  - name: Some Domain API tag name
    description: Some Domain API description
    externalDocs:
      url: 'https://some-external-documentation-url'
      description: External documentation description
```
@maximpn
Copy link
Contributor Author

maximpn commented Aug 2, 2024

The functionality was implemented #189621.

@maximpn maximpn closed this as completed Aug 2, 2024
@maximpn maximpn mentioned this issue Aug 7, 2024
Closed
6 tasks
lcawl pushed a commit to lcawl/kibana that referenced this issue Aug 20, 2024
@maximpn @lcawl
[Security Solution] Add tags by OpenAPI bundler (elastic#189621)
df10c8a 
**Resolves:** elastic#183375

This PR implements functionality assigning a provided tag to OpenAPI `Operation object`s in the result bundle. Specified tag is also added as the only root level OpenAPI tag. This approach allows to produce domain bundles having a single tag assigned. At the next step domain bundles are merged together into single Kibana bundle where tags will allow to properly display grouping at Bump.sh (API reference documentation platform).

Bump.sh (our new API reference documentation platform) uses OpenAPI tags for grouping API endpoints. It supports only one tag per endpoint.

This PR facilitates preparation of Kibana OpenAPI bundle to be uploaded to Bump.sh by implementing functionality assigning a provided tag to OpenAPI `Operation object`s in the result domain bundles. It's implemented by providing an optional configuration option `assignTag` whose format is OpenAPI Tag Object. When `assignTag` isn't specified the bundler merges existing tags.

Consider the following bundling configuration

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

bundle({
  // ...
  options: {
    assignTag: {
      name: 'Some Domain API tag name',
      description: 'Some Domain API description',
      externalDocs: {
        url: 'https://some-external-documentation-url',
        description: 'External documentation description',
    }
  },
});
```

and source OpenAPI specs

**spec1.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec1
  version: '2023-10-31'
paths:
  /api/some_api:
    get:
      tags: ['Some local tag']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
```

**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec2
  version: '2023-10-31'
paths:
  /api/some_api:
    post:
      tags: ['Some global tag']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
tags:
  - name: Some global tag
```

**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec3
  version: '2023-10-31'
paths:
  /api/another_api:
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
```

After bundling above OpenAPI specs with the provided bundling script we'll get the following

**domain-bundle.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Bundled document
  version: '2023-10-31'
paths:
  /api/some_api:
    get:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
    post:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
  /api/another_api:
    get:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
tags:
  - name: Some Domain API tag name
    description: Some Domain API description
    externalDocs:
      url: 'https://some-external-documentation-url'
      description: External documentation description
```
@maximpn maximpn mentioned this issue Sep 16, 2024
Merged
maximpn added a commit that referenced this issue Sep 19, 2024
@maximpn
[Security Solution] Add a missing domain tag to Endpoint Exceptions A…
09374ad 
…PI (#193019)

**Addresses:** #183375

## Summary

This PR adds a missing domain tag to Endpoint Exceptions API. The rest API endpoints got their tags in #189621.
maximpn added a commit to maximpn/kibana that referenced this issue Sep 25, 2024
@maximpn
[Security Solution] Add a missing domain tag to Endpoint Exceptions A…
773b785 
…PI (elastic#193019)

**Addresses:** elastic#183375

## Summary

This PR adds a missing domain tag to Endpoint Exceptions API. The rest API endpoints got their tags in elastic#189621.

(cherry picked from commit 09374ad)

# Conflicts:
#	packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml
#	packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml
maximpn referenced this issue Sep 25, 2024
@maximpn @kibanamachine
[8.x] [Security Solution] Add a missing domain tag to Endpoint Except…
21e02f7 
…ions API (#193019) (#193984)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[Security Solution] Add a missing domain tag to Endpoint Exceptions
API (#193019)](#193019)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Maxim
Palenov","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-09-19T11:23:11Z","message":"[Security
Solution] Add a missing domain tag to Endpoint Exceptions API
(#193019)\n\n**Addresses:**
https://github.com/elastic/kibana/issues/183375\r\n\r\n##
Summary\r\n\r\nThis PR adds a missing domain tag to Endpoint Exceptions
API. The rest API endpoints got their tags in
https://github.com/elastic/kibana/pull/189621.","sha":"09374ad2ce5ba96b61a1d300264d2465f34e2326","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","docs","Team:Detections
and Resp","Team: SecuritySolution","backport:prev-minor","Team:Detection
Engine","v8.16.0"],"number":193019,"url":"https://github.com/elastic/kibana/pull/193019","mergeCommit":{"message":"[Security
Solution] Add a missing domain tag to Endpoint Exceptions API
(#193019)\n\n**Addresses:**
https://github.com/elastic/kibana/issues/183375\r\n\r\n##
Summary\r\n\r\nThis PR adds a missing domain tag to Endpoint Exceptions
API. The rest API endpoints got their tags in
https://github.com/elastic/kibana/pull/189621.","sha":"09374ad2ce5ba96b61a1d300264d2465f34e2326"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/193019","number":193019,"mergeCommit":{"message":"[Security
Solution] Add a missing domain tag to Endpoint Exceptions API
(#193019)\n\n**Addresses:**
https://github.com/elastic/kibana/issues/183375\r\n\r\n##
Summary\r\n\r\nThis PR adds a missing domain tag to Endpoint Exceptions
API. The rest API endpoints got their tags in
https://github.com/elastic/kibana/pull/189621.","sha":"09374ad2ce5ba96b61a1d300264d2465f34e2326"}},{"branch":"8.x","label":"v8.16.0","labelRegex":"^v8.16.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

---------

Co-authored-by: kibanamachine <[email protected]>
maximpn added a commit to maximpn/kibana that referenced this issue Nov 12, 2024
@maximpn
[Security Solution] Add a missing domain tag to Endpoint Exceptions A…
c055507 
…PI (elastic#193019)

**Addresses:** elastic#183375

This PR adds a missing domain tag to Endpoint Exceptions API. The rest API endpoints got their tags in elastic#189621.

(cherry picked from commit 09374ad)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@maximpn maximpn

Labels
8.16 candidate docs Team:Detection Rule Management Security Detection Rule Management Team Team:Detections and Resp Security Detection Response Team Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. v8.16.0
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@maximpn @banderror @elasticmachine