diff --git a/docs/management/admin/endpoint-command-ref.asciidoc b/docs/management/admin/endpoint-command-ref.asciidoc new file mode 100644 index 0000000000..89a4f66237 --- /dev/null +++ b/docs/management/admin/endpoint-command-ref.asciidoc @@ -0,0 +1,343 @@ +[[endpoint-command-ref]] += {elastic-endpoint} command reference + +This page lists the commands for management and troubleshooting of {elastic-endpoint}, the installed component that performs {elastic-defend}'s threat monitoring and prevention. + +[NOTE] +==== +* {elastic-endpoint} is not added to the `PATH` system variable, so you must prepend the commands with the full OS-dependent path: +** On Windows: `"C:\Program Files\Elastic\Endpoint\elastic-endpoint.exe"` +** On macOS: `/Library/Elastic/Endpoint/elastic-endpoint` +** On Linux: `/opt/Elastic/Endpoint/elastic-endpoint` + +* You must run the commands with elevated privileges—using `sudo` to run as the root user on Linux and macOS, or running as Administrator on Windows. +==== + +The following {elastic-endpoint} commands are available: + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +Each of the commands accepts the following logging options: + +* `--log [stdout,stderr,debugview,file]` +* `--log-level [error,info,debug]` + +[discrete] +[[elastic-endpoint-diagnostics-command]] +== elastic-endpoint diagnostics + +Gather diagnostics information from {elastic-endpoint}. This command produces an archive that contains: + +- `version.txt`: Version information +- `elastic-endpoint.yaml`: Current policy +- `metrics.json`: Metrics document +- `policy_response.json`: Last policy response +- `system_info.txt`: System information +- `analysis.txt`: Diagnostic analysis report +- `logs` directory: Copy of {elastic-endpoint} log files + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint diagnostics +------ + +[discrete] +[[elastic-endpoint-help-command]] +== elastic-endpoint help + +Show help for the available commands. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint help +------ + +[discrete] +[[elastic-endpoint-inspect-command]] +== elastic-endpoint inspect + +Show the current {elastic-endpoint} configuration. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint inspect +------ + +[discrete] +[[elastic-endpoint-install-command]] +== elastic-endpoint install + +Install {elastic-endpoint} as a system service. + +NOTE: We do not recommend installing {elastic-endpoint} using this command. {elastic-endpoint} is managed by {agent} and cannot function as a standalone service. Therefore, there is no separate installation package for {elastic-endpoint}, and it should not be installed independently. + +[discrete] +=== Options + +`--resources `:: +Specify a resources `.zip` file to be used during the installation. This option is required. + +`--upgrade`:: +Upgrade the existing installation. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint install --upgrade --resources endpoint-security-resources.zip +------ + +[discrete] +[[elastic-endpoint-memorydump-command]] +== elastic-endpoint memorydump + +Save a memory dump of the {elastic-endpoint} service. + +[discrete] +=== Options + +`--compress`:: +Compress the saved memory dump. + +`--timeout `:: +Specify the memory collection timeout, in seconds; the default is 60 seconds. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint memorydump --timeout 120 +------ + +[discrete] +[[elastic-endpoint-run-command]] +== elastic-endpoint run + +Run `elastic-endpoint` as a foreground process if no other instance is already running. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint run +------ + +[discrete] +[[elastic-endpoint-send-command]] +== elastic-endpoint send + +Send the requested document to the {stack}. + +[discrete] +=== Subcommands + +`metadata`:: +Send an off-schedule metrics document to the {stack}. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint send metadata +------ + +[discrete] +[[elastic-endpoint-status-command]] +== elastic-endpoint status + +Retrieve the current status of the running {elastic-endpoint} service. The command also returns the last known status of {agent}. + +[discrete] +=== Options + +`--output`:: +Control the level of detail and formatting of the information. Valid values are: + +* `human`: Returns limited information when {elastic-endpoint}'s status is `Healthy`. If any policy actions weren't successfully applied, the relevant details are displayed. +* `full`: Always returns the full status information. +* `json`: Always returns the full status information. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint status --output json +------ + +[discrete] +[[elastic-endpoint-test-command]] +== elastic-endpoint test + +Perform the requested test. + +[discrete] +=== Subcommands + +`output`:: +Test whether {elastic-endpoint} can connect to remote resources. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint test output +------ + +[discrete] +=== Example output + +[source,txt] +---- +Testing output connections + +Using proxy: + +Elasticsearch server: https://example.elastic.co:443 + Status: Success + +Global artifact server: https://artifacts.security.elastic.co + Status: Success + +Fleet server: https://fleet.example.elastic.co:443 + Status: Success +---- + +[discrete] +[[elastic-endpoint-top-command]] +== elastic-endpoint top + +Show a breakdown of the executables that triggered {elastic-endpoint} CPU usage within the last interval. This displays which {elastic-endpoint} features are resource-intensive for a particular executable. + +NOTE: The meaning and output of this command are similar, but not identical, to the POSIX `top` command. The `elastic-endpoint top` command aggregates multiple processes by executable. The utilization values aren't measured by the OS scheduler but by a wall clock in user mode. The output helps identify outliers causing excessive CPU utilization, allowing you to fine-tune the {elastic-defend} policy and exception lists in your deployment. + +[discrete] +=== Options + +`--interval `:: +Specify the data collection interval, in seconds; the default is 5 seconds. + +`--limit `:: +Specify the number of updates to collect; by default, data is collected until interrupted by **Ctrl+C**. + +`--normalized`:: +Normalize CPU usage values to a total of 100% across all CPUs on multi-CPU systems. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint top --interval 10 --limit 5 +------ + +[discrete] +=== Example output + +[source,txt] +---- +| PROCESS | OVERALL | API | BHVR | DIAG BHVR | DNS | FILE | LIB | MEM SCAN | MLWR | NET | PROC | RANSOM | REG | +============================================================================================================================================================= +| MSBuild.exe | 3146.0 | 0.0 | 0.8 | 0.7 | 0.0 | 2330.9 | 0.0 | 226.2 | 586.9 | 0.0 | 0.0 | 0.4 | 0.0 | +| Microsoft.Management.Services.IntuneWindowsAgen... | 30.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.2 | 29.8 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| svchost.exe | 27.3 | 0.0 | 0.1 | 0.1 | 0.0 | 0.4 | 0.2 | 0.0 | 26.6 | 0.0 | 0.0 | 0.0 | 0.0 | +| LenovoVantage-(LenovoServiceBridgeAddin).exe | 0.1 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.1 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Lenovo.Modern.ImController.PluginHost.Device.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| msedgewebview2.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| msedge.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| powershell.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| WmiPrvSE.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Lenovo.Modern.ImController.PluginHost.Device.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Slack.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| uhssvc.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| explorer.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| taskhostw.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Widgets.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| elastic-endpoint.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| sppsvc.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | + +Endpoint service (16 CPU): 113.0% out of 1600% + +Collecting data. Press Ctrl-C to cancel +---- + +[discrete] +==== Column abbreviations + +* `API`: Event Tracing for Windows (ETW) API events +* `AUTH`: Authentication events +* `BHVR`: Malicious behavior protection +* `CRED`: Credential access events +* `DIAG BHVR`: Diagnostic malicious behavior protection +* `DNS`: DNS events +* `FILE`: File events +* `LIB`: Library load events +* `MEM SCAN`: Memory scanning +* `MLWR`: Malware protection +* `NET`: Network events +* `PROC`: Process events +* `PROC INJ`: Process injection +* `RANSOM`: Ransomware protection +* `REG`: Registry events + +[discrete] +[[elastic-endpoint-uninstall-command]] +== elastic-endpoint uninstall + +Uninstall {elastic-endpoint}. + +NOTE: {elastic-endpoint} is managed by {agent}. To remove {elastic-endpoint} from the target machine permanently, remove the {elastic-defend} integration from the {fleet} policy. The <> command also uninstalls {elastic-endpoint}; therefore, in practice, the `elastic-endpoint uninstall` command is used only to troubleshoot broken installations. + +[discrete] +=== Options + +`--uninstall-token `:: +Provide the uninstall token. The token is required if <> is enabled. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint uninstall --uninstall-token 12345678901234567890123456789012 +------ + +[discrete] +[[elastic-endpoint-version-command]] +== elastic-endpoint version + +Show the version of {elastic-endpoint}. + +[discrete] +=== Example + +[source,shell] +------ +elastic-endpoint version +------ + diff --git a/docs/management/manage-intro.asciidoc b/docs/management/manage-intro.asciidoc index 13ae697a8f..45e8abcb1c 100644 --- a/docs/management/manage-intro.asciidoc +++ b/docs/management/manage-intro.asciidoc @@ -14,3 +14,4 @@ include::{security-docs-root}/docs/management/admin/endpoint-artifacts.asciidoc[ include::{security-docs-root}/docs/management/admin/endpoint-event-capture.asciidoc[leveloffset=+1] include::{security-docs-root}/docs/management/admin/allowlist-endpoint-3rd-party-av.asciidoc[leveloffset=+1] include::{security-docs-root}/docs/management/admin/endpoint-self-protection.asciidoc[leveloffset=+1] +include::{security-docs-root}/docs/management/admin/endpoint-command-ref.asciidoc[leveloffset=+1] diff --git a/docs/serverless/edr-manage/endpoint-command-ref.mdx b/docs/serverless/edr-manage/endpoint-command-ref.mdx new file mode 100644 index 0000000000..af115a15ba --- /dev/null +++ b/docs/serverless/edr-manage/endpoint-command-ref.mdx @@ -0,0 +1,296 @@ +--- +slug: /serverless/security/endpoint-command-ref +title: ((elastic-endpoint)) command reference +description: Manage and troubleshoot ((elastic-endpoint)) using CLI commands. +tags: ["security","reference","manage"] +status: in review +--- + + +
+ +This page lists the commands for management and troubleshooting of ((elastic-endpoint)), the installed component that performs ((elastic-defend))'s threat monitoring and prevention. + + + +* ((elastic-endpoint)) is not added to the `PATH` system variable, so you must prepend the commands with the full OS-dependent path: + * On Windows: `"C:\Program Files\Elastic\Endpoint\elastic-endpoint.exe"` + * On macOS: `/Library/Elastic/Endpoint/elastic-endpoint` + * On Linux: `/opt/Elastic/Endpoint/elastic-endpoint` + +* You must run the commands with elevated privileges—using `sudo` to run as the root user on Linux and macOS, or running as Administrator on Windows. + + + +The following ((elastic-endpoint)) commands are available: + +* diagnostics +* help +* inspect +* install +* memorydump +* run +* send +* status +* test +* top +* uninstall +* version + +Each of the commands accepts the following logging options: + +* `--log [stdout,stderr,debugview,file]` +* `--log-level [error,info,debug]` + +## elastic-endpoint diagnostics + +Gather diagnostics information from ((elastic-endpoint)). This command produces an archive that contains: + +- `version.txt`: Version information +- `elastic-endpoint.yaml`: Current policy +- `metrics.json`: Metrics document +- `policy_response.json`: Last policy response +- `system_info.txt`: System information +- `analysis.txt`: Diagnostic analysis report +- `logs` directory: Copy of ((elastic-endpoint)) log files + +### Example + +``` +elastic-endpoint diagnostics +``` + +## elastic-endpoint help + +Show help for the available commands. + +### Example + +``` +elastic-endpoint help +``` + +## elastic-endpoint inspect + +Show the current ((elastic-endpoint)) configuration. + +### Example + +``` +elastic-endpoint inspect +``` + +## elastic-endpoint install + +Install ((elastic-endpoint)) as a system service. + + +We do not recommend installing ((elastic-endpoint)) using this command. ((elastic-endpoint)) is managed by ((agent)) and cannot function as a standalone service. Therefore, there is no separate installation package for ((elastic-endpoint)), and it should not be installed independently. + +### Options + +`--resources ` + : Specify a resources `.zip` file to be used during the installation. This option is required. + +`--upgrade` + : Upgrade the existing installation. + +### Example + +``` +elastic-endpoint install --upgrade --resources endpoint-security-resources.zip +``` + +## elastic-endpoint memorydump + +Save a memory dump of the ((elastic-endpoint)) service. + +### Options + +`--compress` + : Compress the saved memory dump. + +`--timeout ` + : Specify the memory collection timeout, in seconds; the default is 60 seconds. + +### Example + +``` +elastic-endpoint memorydump --timeout 120 +``` + +## elastic-endpoint run + +Run `elastic-endpoint` as a foreground process if no other instance is already running. + +### Example + +``` +elastic-endpoint run +``` + +## elastic-endpoint send + +Send the requested document to the ((stack)). + +### Subcommands + +`metadata` + : Send an off-schedule metrics document to the ((stack)). + +### Example + +``` +elastic-endpoint send metadata +``` + +## elastic-endpoint status + +Retrieve the current status of the running ((elastic-endpoint)) service. The command also returns the last known status of ((agent)). + +### Options + +`--output` + : Control the level of detail and formatting of the information. Valid values are: + + * `human`: Returns limited information when ((elastic-endpoint))'s status is `Healthy`. If any policy actions weren't successfully applied, the relevant details are displayed. + * `full`: Always returns the full status information. + * `json`: Always returns the full status information. + +### Example + +``` +elastic-endpoint status --output json +``` + +## elastic-endpoint test + +Perform the requested test. + +### Subcommands + +`output` + : Test whether ((elastic-endpoint)) can connect to remote resources. + +### Example + +``` +elastic-endpoint test output +``` + +### Example output + +``` +Testing output connections + +Using proxy: + +Elasticsearch server: https://example.elastic.co:443 + Status: Success + +Global artifact server: https://artifacts.security.elastic.co + Status: Success + +Fleet server: https://fleet.example.elastic.co:443 + Status: Success +``` + +## elastic-endpoint top + +Show a breakdown of the executables that triggered ((elastic-endpoint)) CPU usage within the last interval. This displays which ((elastic-endpoint)) features are resource-intensive for a particular executable. + + +The meaning and output of this command are similar, but not identical, to the POSIX `top` command. The `elastic-endpoint top` command aggregates multiple processes by executable. The utilization values aren't measured by the OS scheduler but by a wall clock in user mode. The output helps identify outliers causing excessive CPU utilization, allowing you to fine-tune the ((elastic-defend)) policy and exception lists in your deployment. + + +### Options + +`--interval ` + : Specify the data collection interval, in seconds; the default is 5 seconds. + +`--limit ` + : Specify the number of updates to collect; by default, data is collected until interrupted by **Ctrl+C**. + +`--normalized` + : Normalize CPU usage values to a total of 100% across all CPUs on multi-CPU systems. + +### Example + +``` +elastic-endpoint top --interval 10 --limit 5 +``` + +### Example output + +``` +| PROCESS | OVERALL | API | BHVR | DIAG BHVR | DNS | FILE | LIB | MEM SCAN | MLWR | NET | PROC | RANSOM | REG | +============================================================================================================================================================= +| MSBuild.exe | 3146.0 | 0.0 | 0.8 | 0.7 | 0.0 | 2330.9 | 0.0 | 226.2 | 586.9 | 0.0 | 0.0 | 0.4 | 0.0 | +| Microsoft.Management.Services.IntuneWindowsAgen... | 30.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.2 | 29.8 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| svchost.exe | 27.3 | 0.0 | 0.1 | 0.1 | 0.0 | 0.4 | 0.2 | 0.0 | 26.6 | 0.0 | 0.0 | 0.0 | 0.0 | +| LenovoVantage-(LenovoServiceBridgeAddin).exe | 0.1 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.1 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Lenovo.Modern.ImController.PluginHost.Device.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| msedgewebview2.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| msedge.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| powershell.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| WmiPrvSE.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Lenovo.Modern.ImController.PluginHost.Device.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Slack.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| uhssvc.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| explorer.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| taskhostw.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| Widgets.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| elastic-endpoint.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | +| sppsvc.exe | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | + +Endpoint service (16 CPU): 113.0% out of 1600% + +Collecting data. Press Ctrl-C to cancel +``` + +#### Column abbreviations + +* `API`: Event Tracing for Windows (ETW) API events +* `AUTH`: Authentication events +* `BHVR`: Malicious behavior protection +* `CRED`: Credential access events +* `DIAG BHVR`: Diagnostic malicious behavior protection +* `DNS`: DNS events +* `FILE`: File events +* `LIB`: Library load events +* `MEM SCAN`: Memory scanning +* `MLWR`: Malware protection +* `NET`: Network events +* `PROC`: Process events +* `PROC INJ`: Process injection +* `RANSOM`: Ransomware protection +* `REG`: Registry events + +## elastic-endpoint uninstall + +Uninstall ((elastic-endpoint)). + + +((elastic-endpoint)) is managed by ((agent)). To remove ((elastic-endpoint)) from the target machine permanently, remove the ((elastic-defend)) integration from the ((fleet)) policy. The elastic-agent uninstall command also uninstalls ((elastic-endpoint)); therefore, in practice, the `elastic-endpoint uninstall` command is used only to troubleshoot broken installations. + + +### Options + +`--uninstall-token ` + : Provide the uninstall token. The token is required if agent tamper protection is enabled. + +### Example + +``` +elastic-endpoint uninstall --uninstall-token 12345678901234567890123456789012 +``` + +## elastic-endpoint version + +Show the version of ((elastic-endpoint)). + +### Example + +``` +elastic-endpoint version +``` diff --git a/docs/serverless/serverless-security.docnav.json b/docs/serverless/serverless-security.docnav.json index 747862bc78..d7497fde44 100644 --- a/docs/serverless/serverless-security.docnav.json +++ b/docs/serverless/serverless-security.docnav.json @@ -176,6 +176,9 @@ }, { "slug": "/serverless/security/endpoint-self-protection" + }, + { + "slug": "/serverless/security/endpoint-command-ref" } ] },