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.

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

[DOCS] Endpoint artifact docs clarification #2516

Merged
merged 24 commits into from
Oct 18, 2022
Merged
Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
e0d93dd
First draft
joepeeples Sep 28, 2022
cf85d76
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Sep 28, 2022
2301afe
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Sep 29, 2022
6ebfdaa
Rename file/URL
joepeeples Oct 3, 2022
23be388
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 3, 2022
5490a74
Enhance individual artifact descriptions
joepeeples Oct 3, 2022
128bf8a
Merge branch '2111-endpoint-artifacts' of https://github.com/elastic/…
joepeeples Oct 3, 2022
f65eb1c
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 3, 2022
3c0a7b1
Add xrefs from individual pages
joepeeples Oct 3, 2022
94eae31
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 6, 2022
38f4a7a
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 11, 2022
d64b7fc
Revise tip about endpoint network events
joepeeples Oct 11, 2022
07aa8f4
Initial suggestions from Ben's review
joepeeples Oct 11, 2022
0059a2e
Singular/plural agreement
joepeeples Oct 11, 2022
cdf31e4
Apply suggestions from code review
joepeeples Oct 11, 2022
731b90f
Apply suggestions from Janeen's review
joepeeples Oct 17, 2022
9b22c41
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 17, 2022
f7939ea
Additional edits, fixes
joepeeples Oct 17, 2022
10d338f
Explain preventions
joepeeples Oct 17, 2022
ed8d661
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 18, 2022
e8c774b
may --> might
joepeeples Oct 18, 2022
452c187
Update trusted apps screenshot
joepeeples Oct 18, 2022
46ff3e7
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 18, 2022
c87a9a5
Merge branch 'main' into 2111-endpoint-artifacts
joepeeples Oct 18, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/management/admin/blocklist.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@
[chapter]
= Blocklist

The blocklist allows you to prevent specified applications from running on hosts, extending the list of processes that {elastic-defend} considers malicious. This is especially useful for ensuring that known malicious processes aren't accidentally executed by end users.
The blocklist allows you to prevent specified applications from running on hosts, extending the list of processes that {elastic-defend} considers malicious. This helps ensure that known malicious processes aren't accidentally executed by end users.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

The blocklist is not intended to generically block applications assumed to be benign. To compare the blocklist with other endpoint artifacts, refer to <<endpoint-artifacts>>.
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm confused by the first sentence here. It seems like, of course a block list shouldn't block applications known to be benign — why would someone add a known benign application to the block list? So I'm not sure what info this is adding. Am I missing something here?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think this is responding specifically to some misconfigurations where admins might have tried to use the blocklist to block an app that isn't a security threat per se, but just something that admins didn't want end users to run. But other readers may have the same confusion you had; maybe there's a clearer way to say this?

Copy link
Contributor

Choose a reason for hiding this comment

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

What if you approached this from a different angle, for ex:

Suggested change
The blocklist is not intended to generically block applications assumed to be benign. To compare the blocklist with other endpoint artifacts, refer to <<endpoint-artifacts>>.
The blocklist fulfills the specific goal of blocking potentially harmful applications. Do not use it to broadly block non-permitted applications. To compare the blocklist with other endpoint artifacts, refer to <<endpoint-artifacts>>.

This is a lil wordy, but maybe that's needed to fully explain how users should and should not be using the blocklist.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@nastasha-solomon I'm trying out a twist on your suggestion. I'd like this paragraph to start with "the blocklist does NOT do this" as a contrast to the previous para, which is "the blocklist DOES do this," but otherwise I agree with y'all, a little more explanation is needed here.

Suggested change
The blocklist is not intended to generically block applications assumed to be benign. To compare the blocklist with other endpoint artifacts, refer to <<endpoint-artifacts>>.
The blocklist is not intended to broadly block benign applications for non-security reasons; only use it to block potentially harmful applications. To compare the blocklist with other endpoint artifacts, refer to <<endpoint-artifacts>>.

(Is "broadly block benign" too much of a tongue twister? 🤪)

Copy link
Contributor

Choose a reason for hiding this comment

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

I can agree with this approach.

Sidenote: If this were a Letterkenny episode, I'd applaud your admirable application of alliteration. 🥇


[NOTE]
=====
Expand Down
36 changes: 35 additions & 1 deletion docs/management/admin/endpoint-artifacts.asciidoc
Original file line number Diff line number Diff line change
@@ -1,4 +1,38 @@
[[endpoint-artifacts]]
[chapter]
= Optimize {elastic-defend}

This page is a placeholder for future documentation.
If you encounter problems like incompatibilities with other antivirus software, too many false positive alerts, or excessive storage or CPU usage, you can optimize {elastic-defend} to mitigate these issues.

Endpoint artifacts — such as trusted applications and event filters — and Endpoint exceptions let you modify the behavior and performance of _{elastic-endpoint}_, the component installed on each host that performs {elastic-defend}'s threat monitoring, prevention, and response actions.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

The following table explains the differences between several Endpoint artifacts and exceptions, and how to use them for specific purposes:
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

[cols="2"]
|===

| <<trusted-apps-ov,Trusted applications>>
joepeeples marked this conversation as resolved.
Show resolved Hide resolved
a| *_Prevents {elastic-endpoint} from monitoring a process._* Use to avoid conflicts with other software, usually other antivirus or endpoint security applications.

* Creates intentional blind spots in your security environment — use sparingly!
* Does not monitor the application for threats, and does not create alerts for the application, even if it behaves like malware, ransomware, etc.
Copy link
Contributor

Choose a reason for hiding this comment

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

Since you said "process" in the first part of this description, maybe it makes sense to continue with "process" instead of "application"?

joepeeples marked this conversation as resolved.
Show resolved Hide resolved
* Does not generate events for the application except process events for visualizations.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* Does not generate events for the application except process events for visualizations.
* Prevents the collection of events from the application, except process events for visualizations.

If I understand correctly, it's more that Trusted application artifacts prevent event collection for the specified apps, not that they don't generate events. They prevent endpoint from collecting, right?

Copy link
Contributor Author

@joepeeples joepeeples Oct 11, 2022

Choose a reason for hiding this comment

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

Someone on the dev side might answer this better (@kevinlog @ferullo ?), but I think a trusted app is about preventing event generation, not event collection. That's why it's such a blindspot: the event data just doesn't exist, because it's not getting created.

Copy link
Contributor

Choose a reason for hiding this comment

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

@joepeeples your comment is also my understanding, so I think we should leave it as is, unless @ferullo thinks otherwise.

* May improve performance, since {elastic-endpoint} monitors fewer processes.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved
* May still generate malicious behavior alerts, if the application's process events indicate malicious behavior.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* May still generate malicious behavior alerts, if the application's process events indicate malicious behavior.
* May not prevent malicious behavior alerts for applications whose process events indicate malicious behavior.

This is confusing to me since you said above "* Does not generate events for the application except process events for visualizations." Is this in reference to those process events for visualizations? I guess I thought that "for visualizations" would mean not for generating alerts. Also under what circumstances would that "May" come into play? If it only "May" generate alerts, I think we need to be specific about that "May", or else, if possible just remove this bullet entirely .

Copy link
Contributor Author

@joepeeples joepeeples Oct 11, 2022

Choose a reason for hiding this comment

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

Yes, the minimal process events that still get created could possibly trigger the malicious behavior protection feature, probably because it's looking more at behavior patterns in the data, regardless of the application/process doing the behavior. Malicious behavior protection is separate from other Elastic Defend features that presumably would NOT trigger for a trusted application (such as malware, ransomware, or memory threat protections, etc.), since they wouldn't be looking at process events in the same way.

The "for visualizations" detail might be unnecessary and distracting here; maybe we could just say "for internal use" or similar.

@caitlinbetz @kevinlog @ferullo Any additional details on what might trigger these malicious behavior alerts? I get the sense that we're mentioning this because it's happened to customers when they weren't expecting alerts, but any other info that would help?

Copy link
Contributor

@nastasha-solomon nastasha-solomon Oct 12, 2022

Choose a reason for hiding this comment

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

Do you think explaining what generates malicious behavior alerts and then contrasting that with what triggers other Elastic defend protection features (malware, ransomware, or memory threat protections, etc.) would help? Maybe something like:

Suggested change
* May still generate malicious behavior alerts, if the application's process events indicate malicious behavior.
* May still generate malicious behavior alerts, which are produced certain data patterns are noticed. The conditions the produce these alerts are different from those that other Elastic defend protection features (malware, ransomware, or memory threat protections, etc.) follow. <Brief explanation>

Copy link
Contributor

Choose a reason for hiding this comment

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

@joepeeples

Any additional details on what might trigger these malicious behavior alerts? I get the sense that we're mentioning this because it's happened to customers when they weren't expecting alerts, but any other info that would help?

It is true that we can still trigger alerts, although a particular process has been made into a trusted app. Think the important thing to add here is that if they want to suppress the alerts that still come through, they should create Endpoint Alert Exceptions.

Maybe something like the below works.

May still generate malicious behavior alerts, if the application's process events indicate malicious behavior. If you want to suppress alerts, create Endpoint Alert Exceptions

I know you already mention Endpoint Alert Exceptions earlier in this section, but maybe it's a good place to reiterate?

If we still want anything more specific, I would need @ferullo or someone else on Endpoint to chime in

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@kevinlog Thanks for the extra context! I'll add a cross-reference to Endpoint alert exceptions as you suggest.

@nastasha-solomon I think this will resolve the point of confusion that customers may be having; it sounds like they might not need the additional explanation of how the alerts are still being created, just how they can stop them (create an exception).


| <<event-filters,Event filters>>
joepeeples marked this conversation as resolved.
Show resolved Hide resolved
a| *_Prevents event documents from being written to {es}._* Use to reduce storage usage in {es}.

Does NOT lower CPU usage for {elastic-endpoint}. It still monitors event data for possible threats, but the event data just isn't being written to {es}.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

| <<blocklist,Blocklist>>
a| *_Prevents known malware from running._* Use to extend {elastic-defend}'s protection against malicious processes.

NOT intended to generically block applications assumed to be benign.
Copy link
Contributor

Choose a reason for hiding this comment

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

Still confused by this. Why would someone think the blocklist was intended for blocking benign applications? I think maybe the word "generically" is doing some heavy lifting here that is going over my head?

Copy link
Contributor Author

Choose a reason for hiding this comment

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


| <<endpoint-rule-exceptions,Endpoint alert exceptions>>
joepeeples marked this conversation as resolved.
Show resolved Hide resolved
a| *_Prevents {elastic-endpoint} from generating alerts or stopping processes._* Use to reduce false positive alerts or preventions.
Copy link
Contributor

Choose a reason for hiding this comment

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

Ignorant question here: what do you mean by "preventions"? If this is a common security term, ignore me. I've just never seen/heard the word used as a noun in this way. I've mainly seen it used a verb -- e.g., this feature prevents attacks.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@nastasha-solomon Here it's being used to refer to specific features of Elastic Defend, when the admin selects the "Prevent" option to have Elastic Defend/Endpoint stop certain processes. But I can see how that's not super clear; I'll tinker with this to be more specific.

image

Copy link
Contributor

Choose a reason for hiding this comment

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

Ah ok, I didn't know we were referring to this feature as "preventions". Thanks for the clarification!


May also improve performance: {elastic-endpoint} checks for exceptions _before_ most other processing, and stops monitoring a process if an exception allows it.

|===
2 changes: 2 additions & 0 deletions docs/management/admin/event-filters.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

Event filters allow you to filter endpoint events that you do not need or want stored in {es} -- for example, high-volume events. By creating event filters, you can optimize your storage in {es}. All endpoint events have the `endpoint.events.network` field.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

Event filters do not lower CPU usage on hosts; {elastic-endpoint} still monitors event data to detect and prevent possible threats, but the event data just isn't being written to {es}. To compare event filters with other endpoint artifacts, refer to <<endpoint-artifacts>>.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

NOTE: You must have the built-in `superuser` role to access this feature. For more information, refer to {ref}/built-in-users.html[Built-in users].

IMPORTANT: Since an event filter blocks an event from streaming to {es}, be conscious of event filter conditions you set and any existing rule conditions. If there is too much overlap, the rule may run less frequently than specified and, therefore, will not trigger the corresponding alert for that rule. This is the expected behavior of event filters.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
IMPORTANT: Since an event filter blocks an event from streaming to {es}, be conscious of event filter conditions you set and any existing rule conditions. If there is too much overlap, the rule may run less frequently than specified and, therefore, will not trigger the corresponding alert for that rule. This is the expected behavior of event filters.
IMPORTANT: Since an event filter blocks events from streaming to {es}, be conscious of event filter conditions you set and any existing rule conditions. If there is too much overlap, the rule may run less frequently than specified and therefore not trigger the corresponding alert for that rule. This is the expected behavior of event filters.

Expand Down
6 changes: 4 additions & 2 deletions docs/management/admin/trusted-apps.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@
[chapter, role="xpack"]
= Trusted applications

You can add Windows, macOS, and Linux applications that should be trusted. By adding these trusted applications, you can use {elastic-sec} without compatibility or performance issues with other installed applications on your system. Trusted applications apply only to hosts running {elastic-defend}.
You can add Windows, macOS, and Linux applications that should be trusted, such as other antivirus or endpoint security applications. Trusted applications are designed to help mitigate performance issues and incompatibilities with other endpoint software installed on your hosts. Trusted applications apply only to hosts running the {elastic-defend} integration.

NOTE: You must have the built-in `superuser` role to access this feature. For more information, refer to {ref}/built-in-users.html[Built-in users].

Trusted applications are designed to help mitigate performance issues and incompatibilities with other endpoint software. However, they create blindspots for {elastic-sec}. One avenue attackers use to exploit these blindspots is by DLL (Dynamic Link Library) side-loading, where they leverage processes signed by trusted vendors -- such as antivirus software -- to execute their malicious DLLs. Such activity appears to originate from the trusted vendor's process.
Trusted applications create blindspots for {elastic-defend}, because the applications are no longer monitored for threats. One avenue attackers use to exploit these blindspots is by DLL (Dynamic Link Library) side-loading, where they leverage processes signed by trusted vendors -- such as antivirus software -- to execute their malicious DLLs. Such activity appears to originate from the trusted vendor's process.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

Trusted applications may still generate alerts in some cases, such as if the application's process events indicate malicious behavior. To reduce false positive alerts, add an <<endpoint-rule-exceptions,Endpoint alert exception>>, which prevents {elastic-defend} from generating alerts. To compare trusted applications with other endpoint artifacts, refer to <<endpoint-artifacts>>.
joepeeples marked this conversation as resolved.
Show resolved Hide resolved

By default, a trusted application is recognized globally across all hosts running {elastic-defend}. If you have a https://www.elastic.co/pricing[Platinum or Enterprise subscription], you can also assign a trusted application to a specific {elastic-defend} integration policy, enabling the application to be trusted by only the hosts assigned to that policy.

Expand Down