Updates related_integrations field API docs #5183

maximpn · 2024-05-08T10:57:03Z

Relates to: elastic/kibana#173595
Epic: https://github.com/elastic/security-team/issues/1974

Summary

API updates for elastic/kibana#173595.

Updates related API docs for related_integration field changes made in elastic/kibana#178295.

github-actions · 2024-05-08T10:57:16Z

A documentation preview will be available soon.

🔨 Buildkite builds
📚 HTML diff
📙 Preview page

Request a new doc build by commenting

Rebuild this PR: run docs-build
Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

dplumlee

Left a few comments that apply to all the identical blocks as well but from a rules management definition pov, this looks good to me

dplumlee · 2024-05-08T15:59:02Z

docs/detections/api/rules/rules-api-create.asciidoc

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses
+* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.


We might want to sort these by required and optional, although this is a weird field where in some cases it's optional and in others it's not

@dplumlee Yeah, if this was strictly optional all the time, I'd say re-order the list, but since it's a little of both it's good ordered as it is.

dplumlee · 2024-05-08T16:01:19Z

docs/detections/api/rules/rules-api-create.asciidoc

+
+* `package` (String, required): Integration package's name EPR uses
+* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.
+* `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`.


For example, ~1.2.3 is from 1.2.3 to any patch version less than 1.3.0, and ^1.2.3 is from 1.2.3`` to any minor and patch version less than 2.0.0`.

Do we want to display this example inline with the API field description itself or is there a better way to frame this (like a note or something)? @joepeeples

I think it's OK inline as is. I tinkered with a note or new paragraph on my local build, but it looked kinda disruptive.

mergify · 2024-05-08T16:19:57Z

This pull request is now in conflicts. Could you fix it @maximpn? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b allow-editing-related-integrations upstream/allow-editing-related-integrations
git merge upstream/main
git push upstream allow-editing-related-integrations

joepeeples

Thanks @maximpn for creating these updates! Added a few suggestions and comments. I'm not sure what's causing the conflicts in the PR but will look at that next.

joepeeples · 2024-05-08T17:54:21Z

docs/detections/api/rules/rules-api-create.asciidoc

@@ -380,6 +380,12 @@ Required when `actions` are used to send notifications.

 * `field_names`: String[] , required

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:


Suggested change

|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:

|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields:

@joepeeples,

It seems vscode doesn't properly parse integrations-docs link and shows it as is. Is there a way to verify it locally?

@maximpn you can build the Security docs locally if you also have elastic/docs cloned on your machine. Run the command line build alias docbldsec --open to build the Security docs, and they'll open in a browser.

That can be a bit involved, so the PR preview from CI is another way to verify. I checked and the link resolves correctly.

joepeeples · 2024-05-08T18:13:43Z

docs/detections/api/rules/rules-api-create.asciidoc

@@ -380,6 +380,12 @@ Required when `actions` are used to send notifications.

 * `field_names`: String[] , required

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses


Some users might not know what EPR stands for, or maybe they're unfamiliar with Elastic Package Registry in general. I'm also wondering how they'd find out what a given package's name is; maybe we can add a link to help them find the integration/packages they're trying to add?

I tried looking for a list in elastic/package-registry but didn't find anything. Maybe elastic/integrations/tree/main/packages?

I don't think we have package name documented somewhere. For example this page shows integrations list. Package's name as well as integration's name are in fact identifies and hidden from users. UI fetches integrations list from EPR (of course not directly but via Fleet) and uses that ids for API requests. To be 100% sure about id correctness users should use EPR. EPR allows to search for a package while the package contains integrations. After that package or integration ids can be saved since these a stable.

@joepeeples what do you think the best approach to describe it?

@maximpn Simpler is probably better; we can link users to the EPR repo, which documents the API requests that can help them search for the right packages and integrations.

Suggested change

* `package` (String, required): Integration package's name EPR uses

* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry].

joepeeples · 2024-05-08T18:16:17Z

docs/detections/api/rules/rules-api-create.asciidoc

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses
+* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.


Suggested change

* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.

* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations.

joepeeples · 2024-05-08T18:17:27Z

docs/detections/api/rules/rules-api-update.asciidoc

@@ -278,6 +278,12 @@ rule's version number is incremented by 1.
 `PATCH` calls enabling and disabling the rule do not increment its version
 number.

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:


Suggested change

|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:

|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields:

joepeeples · 2024-05-08T18:17:59Z

docs/detections/api/rules/rules-api-update.asciidoc

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses
+* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.


Suggested change

* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.

* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations.

mergify · 2024-05-22T11:07:45Z

This pull request is now in conflicts. Could you fix it @maximpn? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b allow-editing-related-integrations upstream/allow-editing-related-integrations
git merge upstream/main
git push upstream allow-editing-related-integrations

maximpn · 2024-05-22T11:12:12Z

Hi @joepeeples,

I've updated the PR according to your comments. The last this left is to describe how to get a package name and a link to EPR documentation. Check my comment above.

joepeeples · 2024-05-22T21:08:26Z

docs/detections/api/rules/rules-api-update.asciidoc

@@ -286,6 +286,12 @@ rule's version number is incremented by 1.
 `PATCH` calls enabling and disabling the rule do not increment its version
 number.

+|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields:
+
+* `package` (String, required): Integration package's name EPR uses


Suggested change

* `package` (String, required): Integration package's name EPR uses

* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry].

maximpn · 2024-05-27T12:40:44Z

@joepeeples,

I've addressed your last comments. Could you review the recent changes?

maximpn added Team: Detections/Response Detections and Response API Feature: Rules Docset: ESS Issues that apply to docs in the Stack release v8.15.0 labels May 8, 2024

maximpn self-assigned this May 8, 2024

maximpn requested a review from a team as a code owner May 8, 2024 10:57

maximpn added this to In progress in Elastic Security Docs Board via automation May 8, 2024

maximpn removed this from In progress in Elastic Security Docs Board May 8, 2024

banderror requested review from a team and dplumlee May 8, 2024 11:09

banderror mentioned this pull request May 8, 2024

Edit related_integrations field for custom rules in UI and API #5099

Open

dplumlee previously approved these changes May 8, 2024

View reviewed changes

joepeeples reviewed May 8, 2024

View reviewed changes

joepeeples dismissed dplumlee’s stale review via acff659 May 8, 2024 18:59

allow editing related integrations

a1a5336

improve readability

e8dbbbb

maximpn force-pushed the allow-editing-related-integrations branch from acff659 to e8dbbbb Compare May 22, 2024 11:09

joepeeples reviewed May 22, 2024

View reviewed changes

add an EPR link

a191acc

maximpn requested a review from joepeeples May 27, 2024 12:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates related_integrations field API docs #5183

Updates related_integrations field API docs #5183

maximpn commented May 8, 2024 •

edited

github-actions bot commented May 8, 2024

dplumlee left a comment

dplumlee May 8, 2024

joepeeples May 8, 2024

dplumlee May 8, 2024

joepeeples May 8, 2024

mergify bot commented May 8, 2024

joepeeples left a comment

joepeeples May 8, 2024

maximpn May 22, 2024

joepeeples May 22, 2024

joepeeples May 8, 2024

maximpn May 22, 2024

joepeeples May 22, 2024

joepeeples May 8, 2024

joepeeples May 8, 2024

joepeeples May 8, 2024

mergify bot commented May 22, 2024

maximpn commented May 22, 2024

joepeeples May 22, 2024

maximpn commented May 27, 2024

		@@ -380,6 +380,12 @@ Required when `actions` are used to send notifications.

		* `field_names`: String[] , required

		\|related_integrations \|Object[] a\| Fleet integrations the rule depends on. The object has three fields:

	\|related_integrations \|Object[] a\| Fleet integrations the rule depends on. The object has three fields:
	\|related_integrations \|Object[] a\| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields:

	* `package` (String, required): Integration package's name EPR uses
	* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry].

	* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.
	* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations.

Updates related_integrations field API docs #5183

Are you sure you want to change the base?

Updates related_integrations field API docs #5183

Conversation

maximpn commented May 8, 2024 • edited

Summary

github-actions bot commented May 8, 2024

dplumlee left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mergify bot commented May 8, 2024

joepeeples left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mergify bot commented May 22, 2024

maximpn commented May 22, 2024

Choose a reason for hiding this comment

maximpn commented May 27, 2024

maximpn commented May 8, 2024 •

edited