Adds Elastic Endpoint command reference

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]
+====
+* The service 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—as the root user on POSIX systems, or as Administrator on Windows.
+====
+
+The following {elastic-endpoint} commands are available:
+
+* <<elastic-endpoint-diagnostics-command, diagnostics>>
+* <<elastic-endpoint-help-command, help>>
+* <<elastic-endpoint-inspect-command, inspect>>
+* <<elastic-endpoint-install-command, install>>
+* <<elastic-endpoint-memorydump-command, memorydump>>
+* <<elastic-endpoint-run-command, run>>
+* <<elastic-endpoint-send-command, send>>
+* <<elastic-endpoint-status-command, status>>
+* <<elastic-endpoint-test-command, test>>
+* <<elastic-endpoint-top-command, top>>
+* <<elastic-endpoint-uninstall-command, uninstall>>
+* <<elastic-endpoint-version-command, version>>
+
+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]
+------
+sudo /Library/Elastic/Endpoint/elastic-endpoint diagnostics
+------
+
+[discrete]
+[[elastic-endpoint-help-command]]
+== elastic-endpoint help
+
+Show help for the available commands.
+
+[discrete]
+=== Example
+
+[source,shell]
+------
+sudo /Library/Elastic/Endpoint/elastic-endpoint help
+------
+
+[discrete]
+[[elastic-endpoint-inspect-command]]
+== elastic-endpoint inspect
+
+Show the current {elastic-endpoint} configuration.
+
+[discrete]
+=== Example
+
+[source,shell]
+------
+sudo /Library/Elastic/Endpoint/elastic-endpoint inspect
+------
+
+[discrete]
+[[elastic-endpoint-install-command]]
+== elastic-endpoint install
+
+Install {elastic-endpoint} as a system service.
+
+NOTE: Elastic doesn't publish independent {elastic-endpoint} packages since {elastic-endpoint} is managed by {agent}.
+
+[discrete]
+=== Options
+
+`--resources <string>`::
+Specify a resources `.zip` file to be used during the installation.
+
+`--upgrade`::
+Upgrade the existing installation.
+
+[discrete]
+=== Example
+
+[source,shell]
+------
+sudo /Library/Elastic/Endpoint/elastic-endpoint install --upgrade
+------
+
+[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 <duration>`::
+Specify the memory collection timeout, in seconds; the default is 60 seconds.
+
+[discrete]
+=== Example
+
+[source,shell]
+------
+sudo /Library/Elastic/Endpoint/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]
+------
+sudo /Library/Elastic/Endpoint/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]
+------
+sudo /Library/Elastic/Endpoint/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]
+------
+sudo /Library/Elastic/Endpoint/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]
+------
+sudo /Library/Elastic/Endpoint/elastic-endpoint test output
+------
+
+[discrete]
+=== Example output
+
+[source,txt]
+----
+Testing output connections using config file: [C:\Program Files\Elastic\Endpoint\elastic-endpoint.yaml]
+
+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 utility 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 <duration>`::
+Specify the data collection interval, in seconds; the default is 5 seconds.
+
+`--limit <number>`::
+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]
+------
+sudo /Library/Elastic/Endpoint/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 <<uninstall-agent,elastic-agent uninstall>> command also uninstalls {elastic-endpoint}; therefore, in practice, the `elastic-endpoint uninstall` command is used only to troubleshoot broken installations.
+
+[discrete]
+=== Options
+
+`--uninstall-token <string>`::
+Provide the uninstall token. The token is required if <<agent-tamper-protection,agent tamper protection>> is enabled.
+
+[discrete]
+=== Example
+
+[source,shell]
+------
+sudo /Library/Elastic/Endpoint/elastic-endpoint uninstall --uninstall-token 12345678901234567890123456789012
+------
+
+[discrete]
+[[elastic-endpoint-version-command]]
+== elastic-endpoint version
+
+Show the version of {elastic-endpoint}.
+
+[discrete]
+=== Example
+
+[source,shell]
+------
+sudo /Library/Elastic/Endpoint/elastic-endpoint version
+------
+

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]