Space awareness for Elastic Defend

[benironside]

Fixes #1514

Updates the Spaces for Elastic Security and Elastic Defend feature privileges pages (<- previews). Adds information about the space-awareness capabilities for Defend and other Security-specific Fleet features.

The biggest change is the creation of the Spaces and Elastic Security FAQ (preview)

[github-actions]

🔍 Preview links for changed docs:

• solutions/security/configure-elastic-defend/elastic-defend-feature-privileges.md
• solutions/security/get-started/spaces-elastic-security.md

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

[florent-leborgne]

Suggesting to use our built-in metadata system for outlining version-related changes.

Otherwise LGTM 👍

[karenzone]

LGTM!

[bmorelli25]

@benironside can we merge this?

[benironside]

@bmorelli25 no, after my meeting with Caitlin there's something else I need to add. Working on it now.

[github-actions]

🔍 Preview links for changed docs

• solutions/security/get-started/spaces-defend-faq.md
• solutions/security/configure-elastic-defend/elastic-defend-feature-privileges.md
• solutions/security/get-started/spaces-elastic-security.md

[paul-tavares]

Some initial feedback. I see that @natasha-moore-elastic has provided several comments to the FAQ page - some of which I was also going to provide - so I did not review that page. I will wait for the revised version to be available and will then do a full review on it.

[paul-tavares]

I got confused why we link to fleet page here for setting up per-space roles. I think we should link to our own docs on how to setup roles per space (if that exists... Or maybe that is what this page is for 🤔 ). When it comes to RBAC, we really have no dependency on Fleet. Our privileges for endpoint management will enable our functionality even if a user does not have access to fleet.

Also - and perhaps more important: the table below that lists all of the Endpoint Management related privileges is missing the new Global Artifact Management privilege which will be introduced with the availability of this spaces feature.

The new privilege is displayed in Kibana this way:

Global Artifact Management
Manage global assignment of endpoint artifacts (e.g., Trusted Applications, Event Filters) across all policies. This privilege controls global assignment rights only; privileges for each artifact type are required for full artifact management.

[benironside]

Thanks. Updated the link to go to our new FAQ, and added the new privilege to the table.

[paul-tavares]

Same comment here. Linking to the Fleet Roles and Privileges page does not make sense to me. You probably need to contact the fleet team and find out what page in their docs contains information specific around the Spaces feature implementation which hopefully includes the some instructions for existing customers to follow when wanting to take advantage of this feature.

I do think this page is missing some information around how spaces are managed/used from an Elastic Defend standpoint, which is different from how Elastic Security (ex. SIEM, Timelines, etc) are managed, so perhaps a sub-section here for Elastic Defend may be appropriate. Here is some info. I that I would suggest (@caitlinbetz please adjust if necessary)

---

Elastic Defend

Elastic Defend management support of spaces works in conjunction with Fleet support for spaces. The visibility of hosts running Elastic Defend in a given space is managed from Fleet by assigning Agent Policies to the given space (you could link to fleet specific documentation on this topic if that exists). Management and configuration of Elastic Defend policies and hosts functions as normal with a few caveats - see the FAQ for more information (<< Link to the new FAQ page).

---

[benironside]

Thanks for the feedback Paul. I updated the draft—now it links to the our new FAQ, which I think is the best content we have on this feature. Once you've reviewed the FAQ, please let me know if you think this makes sense.

[paul-tavares]

Thanks for all the updates. I did a full review this time and left comments.

A few general observations that you may want to consider (all of these general comments came out of my review of the FAQ):

• There seems to be inconsistencies on how we refer to Elastic Defend. We use "Endpoint" in some cases and "Elastic Defend" in others. Narrowing this down to just using one way to refer to it (IMO) would be best
• References to "Agent policies" are being reference in multiple ways: in some cases we call them "Elastic Agent policies" in others we call them only "Agent policies" and we also seem to refer to "agent" in with both capital A and lower case a.
  • I also noticed that we refer to them as "Elastic Agent policies". and wonder if the reference should be "Fleet Agent policies".
• Same goes for "integration" policies. In this case, we don't seem to be capitalizing the I in `integration" and we also just refer to it as "integration" instead of (maybe) "Fleet Integration policies".
• This may not be a valid comment, but I'll mention it: The use of 1st person grammar is used through and I'm wondering would all sound better when reading if we instead changed it to use 3rd person grammar instead
  • example of cases where 1st person is used: "You can see..."; "You can force..."; "you may need..."; "If you shared an integration policy..."
  • These could be reworded as: "The user can see"; "A user can force", "a user may need..."; "If an integration is policy is shared"

If possible, it would be best if we could use consistent names when referencing these in our docs as it will help with ensuring users are not further confused by the complex data models that are being used between Fleet and Security.

[paul-tavares]

The link to Fleet here should be to the documentation that details how a user "manually opt-in". Those docs are actually currently being updated - see this PR: elastic/ingest-docs#1830

you should be able to get the link to whatever page that PR is updating to use here.

[paul-tavares]

Below is my suggested change. Note that the owner space ID tag was defined incorrectly (letter casing), so please ensure that any other references are correctly displayed as ownerSpaceId:<space_id_here>

Suggested change

Each artifact has a `tag` field, whose value corresponds to the owner space's ID. The format of this tag is `ownerspaceId:<space_id_here>`, for example: `ownerspaceId:default`.

This information is not currently visible in the Kibana UI. It is, however, available on each artifact record returned by the API under the `tag` field. It will includes a value that corresponds to the owner space's ID in the format of `ownerSpaceId:<space_id_here>`, for example: `ownerSpaceId:default`. By default, each artifact will have at least 1 tag of this format, but multiples are also supported when wanting to have a per-policy artifact be managed by multiple spaces.

[paul-tavares]

Suggested change

	The **Policies** list displays only the policies associated with your current space. The endpoint count for each policy includes only the endpoints within that space.
	The **Policies** list displays only the policies associated with your current space. The endpoint agent count for each policy includes only the endpoints within that space.

[paul-tavares]

Suggested change

Artifact tags enable you to change the owning space of per-policy artifacts (those not assigned globally). When an artifact is created, a tag for the space it was created in is automatically added. The format of this tag is `ownerspaceId:<space_id_here>`, for example: `ownerspaceId:default`. Artifacts can have multiple owner space tags, which enables you to have multiple spaces where you can manage per-policy artifacts.

Artifact `tags` enable you to change the owning space of per-policy artifacts (those not assigned globally). When an artifact is created, a tag for the space it was created in is automatically added. The format of this tag is `ownerSpaceId:<space_id_here>`, for example: `ownerSpaceId:default`. Artifacts can have multiple owner space tags, which enables the management of per-policy artifacts from multiple spaces.

[paul-tavares]

Suggested change

	Updates to owner space tags are supported via API. This type of update requires that you have the **Global Artifact Management** privilege. Refer to the [Security endpoint management APIs]({{kib-apis}}/group/endpoint-security-endpoint-management-api) to learn how to use each artifact type's corresponding API.
	Updates to owner space `tags` are supported via API. This type of update requires that you have the **Global Artifact Management** privilege. Refer to the [Security endpoint management APIs]({{kib-apis}}/group/endpoint-security-endpoint-management-api) to learn how to use each artifact type's corresponding API.

[paul-tavares]

Extra ) at the end:

Suggested change

Response actions for both {{elastic-defend}} and third-party EDR solutions are associated with the {{fleet}} integration policy that's connected to the {{elastic-agent}} that executed the response action. A user authorized to view the response actions history log can only view items associated with integration policies that are accessible in the active space. If you share an integration policy with a new space, the associated response actions will automatically become visible in that space. There are some conditions that can result in response action history not being accessible by default—we call these ["orphan” response actions](#spaces-security-faq-orphan-response-actions)).

Response actions for both {{elastic-defend}} and third-party EDR solutions are associated with the {{fleet}} integration policy that's connected to the {{elastic-agent}} that executed the response action. A user authorized to view the response actions history log can only view items associated with integration policies that are accessible in the active space. If you share an integration policy with a new space, the associated response actions will automatically become visible in that space. There are some conditions that can result in response action history not being accessible by default—we call these ["orphan” response actions](#spaces-security-faq-orphan-response-actions).

[paul-tavares]

Suggested change

	When an {{agent}} moves to a new integration policy, its response actions history will continue to be visible as long as the prior integration policy is not deleted and continues remains accessible from the same spaces that the new integration policy is shared with.
	When an {{agent}} moves to a new integration policy, its response actions history will continue to be visible as long as the prior integration policy is not deleted and remains accessible from the same spaces that the new integration policy is shared with.

[paul-tavares]

Suggested change

* If you unenroll a host before the detection engine processes an event from that host, the response action will fail. The failed response action will not appear in the UI (either as part of the alert details, or in the response actions history log) because it won't be associated with the agent policy that was running on the host. These actions will become [orphans](#spaces-security-faq-orphan-response-actions).

* If you unenroll a host before the detection engine processes an event from that host, the response action will fail. The failed response action will not appear in the UI (either as part of the alert details, or in the response actions history log) because it won't be associated with the integration policy that was running on the host. These actions will become [orphans](#spaces-security-faq-orphan-response-actions).

[paul-tavares]

Suggested change

	To remove the space ID where orphan response actions appear, call the API with an empty string for `spaceId`.
	To remove the space ID where orphan response actions appear, call the API with an empty string for `spaceId`. At this time, only 1 space is supported for where orphan response actions can be made visible.

[paul-tavares]

Since the initial draft of the docs were provided, a few other things have been discovered. I think we should add the following here:

Suggested change

	**What happens with protection rules with a policy is shared (or moved) with a new space?**
	Sharing or moving a {{fleet}} Agent policy or associating an {{elastic-defend}} integration policy with additional {{fleet}} Agent policies may require that the new space(s) be configured with the necessary protection rules. Rules are space specific and can not be automatically created in the additional spaces that the policies were shared with.

[caitlinbetz]

should we provide guidance specifically on how to "customize the rule"? (updating the index to that with the appropriate namespace?)

[paul-tavares]

@caitlinbetz There are several ways you can customize the rule to narrow the data down to what the user wants to see in the space, so when I initially provided this content I opted to leave that out since a user familiar with SIEM rules should already know how to do that.

That being said, we could add an example on how the Fleet policy namespace could be used to active that - either by creating a Rule exception -or- customize the rule with index namespaces that match the desired namespace's.

If we did that, I probably would also then suggest that we link to Fleet documentation that details how users can restrict what namespaces policies can use in a given space. That further would assist them in the management of all this. It can get pretty ugly when we get down to attempting to suggest best practices with Policy Moves or association of policies to multiple spaces in Fleet (which I don't even know how they handle those cases... Maybe I'll ask them 😄 )

[caitlinbetz]

Yeah I don't think we have to get to specific, but I do think some mention of that would be helpful!

[paul-tavares]

Ok. In that case then: @benironside here is what I suggest we add to the paragraph directly under the "Endpoint protection rules" heading - perhaps at the end of the text on line 229:

One way that the rule could be customized is by adding a Rule exception that ensures only data whose data_stream.namespace matches the namespace's defined in Fleet policies that contain Elastic Defend integration policies. With the introduction of spaces, Fleet also allows configuring a space to restricting what namespace values can be used on policies which can facilitate the management of rules as new Fleet policies are created or existing policies updated (existing rules would not have to be adjusted to keep the namespace values in sync). {{we should add a link here to the Fleet docs where this is documented}}

Hope the above is not too confusing.