Skip to content

Elastic Defend advanced settings #1445

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.

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

Merged
merged 19 commits into from
Jun 24, 2025
Merged

Conversation

natasha-moore-elastic
Copy link
Contributor

@natasha-moore-elastic natasha-moore-elastic commented May 21, 2025

Resolves elastic/security-docs#2234 by documenting the Elastic Defend policy advanced settings in the Reference section.
The setting descriptions consist of the Kibana tooltip text (in italics) and, for most settings, an additional description. The Kibana tooltip text was kept because some settings don't have an additional description.

Preview: Elastic Defend advanced settings

@natasha-moore-elastic natasha-moore-elastic self-assigned this May 21, 2025
@natasha-moore-elastic natasha-moore-elastic added the Team:Experience Issues owned by the Experience Docs Team label May 21, 2025
@ferullo
Copy link
Contributor

ferullo commented May 29, 2025

Thanks. I'll review this as soon as I can. @joe-desimone @gabriellandau @magermark @nfritts you may want to review also and/or mention this to others.

@AsuNa-jp
Copy link
Contributor

AsuNa-jp commented May 30, 2025

Hi @natasha-moore-elastic @ferullo
Today I've opened the following advanced policy draft PR for 8.19/9.1 feature.
Should I add the advanced policy from the draft PR to this PR as well, or would it be better to request everyone’s review first?

@ferullo
Copy link
Contributor

ferullo commented May 30, 2025

I noticed the in-app help text is included along with additional information (which mirrors the format of the source Google doc). I wonder, now that this online documentation is being added, do we want to shorten the in-app text and provide a link to this page? Or merge the two types of documentation for each option here and then have the in-app text mirror that revised text? Something else? Just leave it as is?

I'm up for doing a pass at updating this or the in-app text if you'd like to do any of those things. Otherwise I'm also happy to review this as it is.

cc @roxana-gheorghe

@natasha-moore-elastic
Copy link
Contributor Author

I noticed the in-app help text is included along with additional information (which mirrors the format of the source Google doc). I wonder, now that this online documentation is being added, do we want to shorten the in-app text and provide a link to this page? Or merge the two types of documentation for each option here and then have the in-app text mirror that revised text? Something else? Just leave it as is?

I'm up for doing a pass at updating this or the in-app text if you'd like to do any of those things. Otherwise I'm also happy to review this as it is.

cc @roxana-gheorghe

Good question! I included the tooltip text since some settings don’t have any additional description and would have otherwise been blank.

Ideally, I’d lean toward keeping the tooltip text short in the UI, and linking from the tooltips to the public docs, where users can get the full context. A lot of the tooltips are already fairly concise (1–2 sentences), so it’s likely not all of them would need changes, if we decided to go that route.

That said, since the Docs team is currently going through a major reorg, we’re pretty limited with resources, and any significant edits to this page would need to take a lower priority compared to writing new feature docs for 8.19/9.1.

@natasha-moore-elastic
Copy link
Contributor Author

Hi @natasha-moore-elastic @ferullo Today I've opened the following advanced policy draft PR for 8.19/9.1 feature. Should I add the advanced policy from the draft PR to this PR as well, or would it be better to request everyone’s review first?

Hi @AsuNa-jp, I think you’re good to add the new advanced setting (along with its tooltip text and any additional description) to this PR, thanks!

@AsuNa-jp
Copy link
Contributor

AsuNa-jp commented Jun 5, 2025

Hi @natasha-moore-elastic
Thank you for your reply. I’ve added the advanced policy for disable_origin_info_collection in the following commit.
If there’s any part that needs correction or revision, please feel free to let me know.
e6125a7

Additionally, I realized that we need to add the following advanced policy config in 8.19/9.1, so I’ve created a new PR on the Kibana side.

I’ve added the same policy and tooltip text to this PR as well (in the commit below), but please feel free to let me know if there’s any issue. 4acd765


*PEM-encoded certificate for {{fleet}} Server certificate authority.*

Specifies the certificate used to verify the SSL/TLS connection to the {{fleet}} server. We typically recommend configuring this at the {{fleet}} level, so it applies consistently across {{elastic-agent}} and all integrations, rather than setting it specifically for {{elastic-endpoint}}.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This applies to all the cert fields, but do you think we should list the cert limitations here (versions that support EC certs being the main one that comes to mind)

Copy link
Contributor Author

@natasha-moore-elastic natasha-moore-elastic Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nfritts We could add the following note under the descriptions for artifacts.global.ca_cert, artifacts.user.ca_cert, and elasticsearch.tls.ca_cert:

"Elliptic Curve (EC) certificates are supported starting with Elastic Endpoint v8.19.0 and v9.1.0. Earlier versions either silently ignore unsupported EC certificates (pre-8.16.0) or report a policy response error (8.16.0–8.18.x). Use RSA certificates or upgrade Elastic Endpoint to a supported version."

Does that sound right?

@ferullo
Copy link
Contributor

ferullo commented Jun 6, 2025

That said, since the Docs team is currently going through a major reorg, we’re pretty limited with resources, and any significant edits to this page would need to take a lower priority compared to writing new feature docs for 8.19/9.1.

This taking a little longer is OK. I want to make the right long term decision. I spoke with @roxana-gheorghe and we'd like to do this

  1. Add a link to this new documentation within Kibana within the "Proceed with caution" message (see below)
  2. Shorten Kibana tooltips as appropriate since there will now be more thorough online documentation
  3. Condense documentation in this PR so there is only a single description

If you are ok with that, I can make a pass to accomplish (2) and (3) so you can mostly just accept suggestions in this PR. I realize this likely means this PR slips past 8.19/9.1.

image

@natasha-moore-elastic
Copy link
Contributor Author

That said, since the Docs team is currently going through a major reorg, we’re pretty limited with resources, and any significant edits to this page would need to take a lower priority compared to writing new feature docs for 8.19/9.1.

This taking a little longer is OK. I want to make the right long term decision. I spoke with @roxana-gheorghe and we'd like to do this

  1. Add a link to this new documentation within Kibana within the "Proceed with caution" message (see below)
  2. Shorten Kibana tooltips as appropriate since there will now be more thorough online documentation
  3. Condense documentation in this PR so there is only a single description

If you are ok with that, I can make a pass to accomplish (2) and (3) so you can mostly just accept suggestions in this PR. I realize this likely means this PR slips past 8.19/9.1.

image

Totally agree that would be a much better user experience – feel free to make edits to this PR and thanks for the help!

Copy link

github-actions bot commented Jun 13, 2025

🔍 Preview links for changed docs:

🔔 The preview site may take up to 3 minutes to finish building. These links will become live once it completes.

Copy link
Contributor

@alaudazzi alaudazzi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left a few minor suggestions on text that might be somehow generated.

Co-authored-by: Arianna Laudazzi <[email protected]>
@natasha-moore-elastic
Copy link
Contributor Author

Hey @ferullo, to avoid keeping a stale PR open, I'd propose that we merge this PR in its current state and make the edits in a later iteration. Since Caitlin and Janeen agreed that the Dev team would own this doc after it's published, the team could then work on shortening the Kibana tooltips and updating this doc in tandem whenever there's bandwidth. The Doc team would still be happy to support by reviewing any updates to the tooltips/descriptions. Let me know if this works!

@ferullo
Copy link
Contributor

ferullo commented Jun 23, 2025

Hey @ferullo, to avoid keeping a stale PR open, I'd propose that we merge this PR in its current state and make the edits in a later iteration. Since Caitlin and Janeen agreed that the Dev team would own this doc after it's published, the team could then work on shortening the Kibana tooltips and updating this doc in tandem whenever there's bandwidth. The Doc team would still be happy to support by reviewing any updates to the tooltips/descriptions. Let me know if this works!

That sounds good to me. I will watch for this PR to be merged then start work to make the changes we agreed to.

Copy link
Contributor

@ferullo ferullo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, but can we move this page from where it is currently located to somewhere around this page?

@natasha-moore-elastic
Copy link
Contributor Author

LGTM, but can we move this page from where it is currently located to somewhere around this page?

In our new docs IA we have a separate section for all reference-type content, but you've reminded me that in the sync with Caitlin we agreed to cross-link to this page from the https://www.elastic.co/docs/solutions/security/configure-elastic-defend/configure-an-integration-policy-for-elastic-defend#adv-policy-settings section so that it's easier to find. I've gone ahead and added that link now.

@natasha-moore-elastic natasha-moore-elastic merged commit eac2961 into main Jun 24, 2025
7 checks passed
@natasha-moore-elastic natasha-moore-elastic deleted the issue-2234-adv-settings branch June 24, 2025 08:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Team:Experience Issues owned by the Experience Docs Team
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[DOCS] Document endpoint policy advanced settings
7 participants