Admin UI Guide
Introduction to the ExtraHop Admin UI
The Admin UI Guide provides detailed information about the administrator features and functionality of ExtraHop sensors and consoles. This guide provides an overview of the global navigation and information about the controls, fields, and options available throughout the UI.
Video: | See the related training: RevealX Enterprise Administration UI |
We value your feedback. Please let us know how we can improve this document. Send your comments or suggestions to documentation@extrahop.com.
Supported browsers
The following browsers are compatible with all ExtraHop systems. Apply the accessibility and compatibility features provided by your browser to access content through assistive technology tools.
- Firefox
- Google Chrome
- Microsoft Edge
- Safari
Important: | Internet Explorer 11 is no longer supported. We recommend that you install the latest version of any supported browser. |
Status and Diagnostics
The Status and Diagnostics section provides metrics about the overall health of your ExtraHop system.
Health
The Health page provides a collection of metrics that helps you to monitor the operation of your ExtraHop system and enables ExtraHop Support to troubleshoot system errors if necessary.
- System
- Reports the following information about the system CPU usage and hard disk.
- CPU User
- The percentage of CPU usage associated with the ExtraHop system user.
- CPU System
- The percentage of CPU usage associated with the ExtraHop system.
- CPU Idle
- The CPU Idle percentage associated with the ExtraHop system.
- CPU IO
- The percentage of CPU usage associated with the ExtraHop system IO functions.
- Bridge Status
- Reports the following information about the ExtraHop system bridge component.
- VM RSS
- The bridge process physical memory in use.
- VM Data
- The bridge process heap virtual memory in use.
- VM Size
- The bridge process total virtual memory in use.
- Start Time
- Specifies the start time for the ExtraHop system bridge component.
- Capture Status
- Reports the following information about the ExtraHop system network capture status.
- VM RSS
- The network capture process physical memory in use.
- VM Data
- The network capture process heap virtual memory in use.
- VM Size
- The network capture process total virtual memory in use.
- Start Time
- The start time for the ExtraHop network capture.
- Service Status
- Reports the status of ExtraHop system services.
- exalerts
- The amount of time the ExtraHop system alert service has been running.
- extrend
- The amount of time the ExtraHop system trend service has been running.
- exconfig
- The amount of time the ExtraHop system config service has been running.
- exportal
- The amount of time the ExtraHop system web portal service has been running.
- exshell
- The amount of time the ExtraHop system shell service has been running.
- Interfaces
- Reports the status of ExtraHop system interfaces.
- RX packets
- The number of packets received by the specified interface on the ExtraHop system.
- RX Errors
- The number of received packet errors on the specified interface.
- RX Drops
- The number of received packets dropped by the specified interface.
- TX Packets
- The number of packets transmitted by the specified interface on the ExtraHop system.
- TX Errors
- The number of transmitted packet errors on the specified interface.
- TX Drops
- The number of transmitted packets dropped by the specified interface.
- RX Bytes
- The number of bytes received by the specified interface on the ExtraHop system.
- TX Bytes
- The number of bytes transmitted by the specified interface on the ExtraHop system.
- Partitions
- Reports the memory that has been allocated to system components for the ExtraHop system.
- Name
- The system components that have a memory partition in NVRAM.
- Options
- The read-write options for the system components.
- Size
- The partition size in gigabytes that is allocated for the system component.
- Utilization
- The amount of memory that is currently consumed by the system components, as a quantity and as a percentage of the total partition.
Active device count and limit
The Active Device Count and Limit chart enables you to monitor whether your active device count has exceeded the licensed limit. For example, an ExtraHop system with a 20,000-50,000 devices band is allowed up to 50,000 devices.
Click System Settings and then click All Administration. From the Status and Diagnostics section, click Active Device Count and Limit to view the chart.
The Active Device Count and Limit chart displays the following metrics:
- The dashed red line represents the licensed device limit.
- The solid black line represents the 95th percentile of active devices observed each day for the last 30 days.
- The blue bars represent the maximum number of active devices observed each day for the last 30 days.
This page also displays the following metrics:
- The licensed device limit for the previous day and for the last 30 days.
- The number of active devices observed the previous day.
- The 95th percentile of active devices observed over the last 30 days.
- The utilization percentage of the licensed device limit for the previous day and for the last 30 days. Utilization is the active device count divided by the licensed limit.
You can create a system notification rule to warn you if utilization is near (exceeds 80%) or over (exceeds 100%) your licensed device limit. Limit percentages are customizable when you create a rule. If you find that you are consistently approaching or over your licensed limit, we recommend that you work with your sales team to move to the next available capacity band.
Verify active device count
You can view the Active Device Count and Limit chart to monitor whether your active device count has exceeded the licensed limit.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- From the Status and Diagnostics section, click Active Device Count and Limit to view the chart.
Audit Log
The audit log provides data about the operations of your ExtraHop system, broken down by component. The audit log lists all known events by timestamp, in reverse chronological order.
Send audit log data to a remote syslog server
The audit log collects data about ExtraHop system operations, broken down by component. The log stored on the system has a capacity of 10,000 entries, and entries older than 90 days are automatically removed. You can view these entries in the Administration settings, or you can send the audit log events to a syslog server for long-term storage, monitoring, and advanced analysis. All logged events are listed in the table below.
The following steps show you how to configure the ExtraHop system to send audit log data to a remote syslog server.
Next steps
After you confirm that your new settings are working as expected, preserve your configuration changes by saving the running configuration file.Audit log events
The following events on an ExtraHop system generate an entry in the audit log.
Category | Event |
---|---|
Agreements |
|
API |
|
Sensor Migration |
|
Browser sessions |
|
Cloud Services |
|
Console |
|
Dashboards |
|
Datastore |
|
Detections |
|
Exception files |
|
ExtraHop recordstore records |
|
ExtraHop recordstore cluster |
|
ExtraHop Update Service |
|
Firmware |
|
Global Policies |
|
Integrations |
|
License |
|
Login to the ExtraHop system |
|
Login from SSH or REST API |
|
Modules |
|
Network |
|
Offline capture |
|
PCAP |
|
Remote Access |
|
RPCAP |
|
Running Config |
|
SAML Identity Provider |
|
SAML login |
|
SAML privileges |
|
Sensor tags |
|
SSL decryption |
|
SSL session keys |
|
Support account |
|
Support Script |
|
Syslog |
|
System and service status |
|
System time |
|
System user |
|
TAXII feeds |
|
Threat briefings |
|
ExtraHop packetstore |
|
Trends |
|
Triggers |
|
User Groups |
|
Fingerprint
Fingerprints help secure appliances from machine-in-the-middle attacks by providing a unique identifier that can be verified when connecting ExtraHop appliances.
When connecting an ExtraHop recordstore or packetstore with a packet sensor or console, make sure that the fingerprint displayed is exactly the same as the fingerprint shown on the join or pairing page.
If the fingerprints do not match, communications between the devices might have been intercepted and altered.
Exception Files
Exception files are a core file of the data stored in memory. When you enable the Exception File setting, the core file is written to the disk if the system unexpectedly stops or restarts. This file can help ExtraHop Support diagnose the issue.
Click Enable Exception Files or Disable Exception Files to enable or disable the saving of exception files.
Support Scripts
ExtraHop Support might provide a support script that can apply a special setting, make a small adjustment to the ExtraHop system, or provide help with remote support or enhanced settings. The Administration settings enable you to upload and run support scripts.
Network Settings
The Network Settings section provides configuration settings for your ExtraHop system. These settings enable you to set a hostname, configure notifications, and manage connections to your system.
Connect to ExtraHop Cloud Services
ExtraHop Cloud Services provides access to ExtraHop cloud-based services through an encrypted connection.
After the connection is established, information about the available services appear on the ExtraHop Cloud Services page.
- By sharing data with ExtraHop Machine Learning Service, you can enable features that
enhance the ExtraHop system and your user experience.
- Enable AI Search Assistant to find devices with natural language user prompts, which
are shared with ExtraHop Cloud Services for product improvement. See the AI Search Assistant FAQ for more
information. AI Search Assistant cannot currently be enabled for the following
regions:
- Asia Pacific (Singapore, Sydney, Tokyo)
- Europe (Frankfurt, Paris)
- Opt in to Expanded Threat Intelligence to enable the Machine Learning Service to review data such as IP addresses and hostnames against threat intelligence provided by CrowdStrike, benign endpoints, and other network traffic information. See the Expanded Threat Intelligence FAQ for more information.
- Contribute data such as file hashes and external IP addresses to Collective Threat Analysis to improve the accuracy of detections. See the Collective Threat Analysis FAQ for more information.
- Enable AI Search Assistant to find devices with natural language user prompts, which
are shared with ExtraHop Cloud Services for product improvement. See the AI Search Assistant FAQ for more
information. AI Search Assistant cannot currently be enabled for the following
regions:
- ExtraHop Update Service enables automatic updates of resources to the ExtraHop system, such as ransomware packages.
- ExtraHop Remote Access enables you to allow ExtraHop account team members and ExtraHop Support to connect to your ExtraHop system for configuration help. See the Remote Access FAQ for more information about remote access users.
Video: | See the related training: Connect to ExtraHop Cloud Services |
Before you begin
- RevealX 360 systems are automatically connected to ExtraHop Cloud Services, however, you might need to allow access through network firewalls.
- You must apply the relevant license on the ExtraHop system before you can connect to ExtraHop Cloud Services. See the License FAQ for more information.
- You must have setup or system and access administration privileges to access Administration settings.
Configure your firewall rules
If your ExtraHop system is deployed in an environment with a firewall, you must open access to ExtraHop Cloud Services. For RevealX 360 systems that are connected to self-managed sensors, you must also open access to the cloud-based recordstore included with RevealX Standard Investigation
Open access to Cloud Services
For access to ExtraHop Cloud Services, your sensors must be able to resolve DNS queries for *.extrahop.com and access TCP 443 (HTTPS) at one of the following IP addresses that correspond to your sensor license. We recommend opening access to both IP addresses to safeguard against service interruption.
Region | IP Addresses |
---|---|
North, Central, South America (AMER) | 35.161.154.247 54.191.189.22 |
Asia, Pacific (APAC) | 54.66.242.25 13.239.224.80 |
Europe, Middle East, Africa (EMEA) | 52.59.110.168 18.198.13.99 |
United States Federal (US-FED) | 3.135.6.11 3.139.111.240 |
Open access to RevealX 360 Standard Investigation
For access to RevealX 360 Standard Investigation, your sensors must be able to access outbound TCP 443 (HTTPS) to these fully-qualified domain names:
- bigquery.googleapis.com
- bigquerystorage.googleapis.com
- oauth2.googleapis.com
- www.googleapis.com
- www.mtls.googleapis.com
- iamcredentials.googleapis.com
You can also review the public guidance from Google about computing possible IP address ranges for googleapis.com.
In addition to configuring access to these domains, you must also configure the global proxy server settings.
Connect to ExtraHop Cloud Services through a proxy
If you do not have a direct internet connection, you can try connecting to ExtraHop Cloud Services through an explicit proxy.
Before you begin
Verify whether your proxy vendor is configured to perform machine-in-the-middle (MITM) when tunneling SSH over HTTP CONNECT to localhost:22. ExtraHop Cloud Services deploys an encrypted inner SSH tunnel, so traffic will not be visible to MITM inspection. We recommend that you create a security exception and disable MITM inspection for this traffic.Important: | If you are unable to disable MITM on your proxy, you must disable certificate validation in the ExtraHop system running configuration file. For more information, see Bypass certificate validation. |
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click Connectivity.
- Click Enable ExtraHop Cloud Proxy.
- In the Hostname field, type the hostname for your proxy server, such as proxyhost.
- In the Port field, type the port for your proxy server, such as 8080.
- (Optional): If required, in the Username and Password fields, type a user name and password for your proxy server.
- Click Save.
Bypass certificate validation
Some environments are configured so that encrypted traffic cannot leave the network without inspection by a third-party device. This device can act as an TLS endpoint that decrypts and re-encrypts the traffic before sending the packets to ExtraHop Cloud Services.
Note: | The following procedure requires familiarity with modifying the ExtraHop running configuration file. |
Disconnect from ExtraHop Cloud Services
You can disconnect an ExtraHop system from ExtraHop Cloud Services.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click ExtraHop Cloud Services.
- In the Cloud Services Connection section, click Disconnect.
Manage ExtraHop Cloud Services enrollment
If you want to move an existing license from one ExtraHop system to another, you can manage system enrollment from the ExtraHop Cloud Services page. Unenrolling a system deletes all data and historical analysis for the Machine Learning Service from the system and will no longer be available.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click ExtraHop Cloud Services.
- In the Cloud Services Connection section, click Unenroll.
Connectivity
The Connectivity page contains controls for your appliance connections and network settings.
- Interface Status
- On physical appliances, a diagram of interface connections appears, which updates
dynamically based on the port status.
- The blue Ethernet port is for management
- A black Ethernet port indicates a licensed and enabled port that is currently down
- A green Ethernet port indicates an active, connected port
- A gray Ethernet port indicates a disabled or unlicensed port
- Network Settings
-
- Click Change Settings to add a hostname for your ExtraHop appliance or to add DNS servers.
- Proxy Settings
-
- Enable a global proxy to connect to an ExtraHop console
- Enable a cloud proxy to connect to ExtraHop Cloud Services
- Bond Interface Settings
-
- Create a bond interface to bond multiple interfaces together into one logical interface with a single IP address.
- Interfaces
- View and configure your management and monitoring interfaces. Click any interface to display setting options.
- Packet Ingest Settings
-
- Configure the source of packets ingested by this sensor. You can enable the sensor to ingest packets from a direct feed or packets forwarded from a third-party.
Configure an interface
Set a static route
Before you begin
You must disable DHCPv4 before you can add a static route.- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click Connectivity.
- In the Interfaces section, click the name of the interface you want to configure.
- On the Network Settings for Interface <interface number> page, ensure that the IPv4 Address and Netmask fields are complete and saved, and click Edit Routes.
- In the Add Route section, type a network address range in CIDR notation in the Network field and IPv4 address in the Via IP field and then click Add.
- Repeat the previous step for each route you want to add.
- Click Save.
Interface throughput
ExtraHop sensor models EDA 6100, EDA 8100, and EDA 9100 are optimized to capture traffic exclusively on 10GbE ports.
Enabling the 1GbE interfaces for monitoring traffic can impact performance, depending on the ExtraHop sensor. While you can optimize these sensors to capture traffic simultaneously on both the 10GbE ports and the three non-management 1GbE ports, we recommend that you contact ExtraHop Support for assistance to avoid reduced throughput.
Note: | EDA 6200, EDA 8200, EDA 9200, and EDA 10200 sensors are not susceptible to reduced throughput if you enable 1GbE interfaces for monitoring traffic. |
ExtraHop Sensor | Throughput | Details |
---|---|---|
EDA 9100 | Standard 40Gbps throughput | If the non-management 1GbE interfaces are disabled, you can use up to four of the 10GbE interfaces for a combined throughput of up to 40Gbps. |
EDA 8100 | Standard 20Gbps throughput | If the non-management 1GbE interfaces are disabled, you can use either one or both of the 10GbE interfaces for a combined throughput of up to 20Gbps. |
EDA 6100 | Standard 10Gbps throughput | If the non-management 1GbE interfaces are disabled, the maximum total combined throughput is 10Gbps. |
EDA 3100 | Standard 3Gbps throughput | No 10GbE interface |
EDA 1100 | Standard 1Gbps throughput | No 10GbE interface |
Sensor throughput for multiple modules
Some ExtraHop sensor models support enabling the IDS module, as long as the sensor is licensed for the NDR module. Enabling IDS on these sensors might affect sensor throughput.
ExtraHop Sensor Model | IDS Support | Throughput w/o IDS (Gbps) | Throughput w/IDS (Gbps) |
---|---|---|---|
1200 | No | 1 | N/A |
4200 | No | 5 | N/A |
6200 | Yes | 10 | 4 |
8200 | Yes | 25 | 10 |
8320 | Yes | 25 | 25 |
9200 | Yes | 50 | 20 |
9300 | Yes | 50 | 30 |
10200 | Yes | 100 | 40 |
10300 | Yes | 100 | TBD |
Global proxy server
If your network topology requires a proxy server to enable your ExtraHop system to communicate either with a console or with other devices outside of the local network, you can enable your ExtraHop system to connect to a proxy server you already have on your network. Internet connectivity is not required for the global proxy server.
Configure a global proxy
Important: | You can configure only one global proxy server per ExtraHop system. |
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click Connectivity.
- In the Proxy Settings section, click Enable Global Proxy.
- In the Hostname field, enter the hostname or IP address for your global proxy server
- In the Port field, enter the port number for your proxy server.
- In the Username field, enter the name of a user that has privileged access to your global proxy server.
- In the Password field, enter the password for the user specified above.
ExtraHop Cloud proxy
If your ExtraHop system does not have a direct internet connection, you can connect to the internet through a proxy server specifically designated for ExtraHop Cloud services connectivity. Only one proxy can be configured per system.
Complete the following fields and click Save to enable a cloud proxy.
Hostname: The hostname or IP address for your cloud proxy server.
Port: The port number for your cloud proxy server.
Username: The name of a user that has for access to your cloud proxy server.
Password: The password for the user specified above.
Bond interfaces
You can bond multiple interfaces on your ExtraHop system together into a single logical interface that has one IP address for the combined bandwidth of the member interfaces. Bonding interfaces enable a larger throughput with a single IP address. This configuration is also known as link aggregation, port channeling, link bundling, Ethernet/network/NIC bonding, or NIC teaming. Bond interfaces cannot be set to monitoring mode.
Note: | When you modify bond interface settings, you lose connectivity to your ExtraHop system. You must make changes to your network switch configuration to restore connectivity. The changes required are dependent on your switch. Contact ExtraHop Support for assistance before you create a bond interface. |
- Bonding is only configurable on Management or Management + interfaces.
- Port channeling on traffic monitoring ports is supported on the ExtraHop sensors.
Interfaces chosen as members of a bond interface are no longer independently configurable and are shown as Disabled (bond member) in the Interfaces section of the Connectivity page. After a bond interface is created, you cannot add more members or delete existing members. The bond interface must be destroyed and recreated.
Create a bond interface
You can create a bond interface with at least one interface member and up to the number of members that are available for bonding.
Modify bond interface settings
After a bond interface is created, you can modify most settings as if the bond interface is a single interface.
Destroy a bond interface
When a bond interface is destroyed, the separate interface members of the bond interface return to independent interface functionality. One member interface is selected to retain the interface settings for the bond interface and all other member interfaces are disabled. If no member interface is selected to retain the settings, the settings are lost and all member interfaces are disabled.
Packet Ingest Settings
You can configure an ExtraHop sensor to ingest packets from a direct feed or to ingest packets forwarded from a third-party.
Before you begin
- Your user account must have full write privileges or higher on RevealX Enterprise or System and Access Administration privileges on RevealX 360.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click Connectivity.
-
In the Packet Ingest Settings section, select one of the
following options:
Option Description Ingest packets from direct traffic feed Only available if you configure at least one interface with a mode that includes GENEVE encapsulation. Ingest packets forwarded from Netskope Only available if you configure at least one interface with a mode that includes GENEVE encapsulation. See the Netskope integration guide for RevealX Enterprise or RevealX 360 to configure packet ingest from your Netskope solution.
- Click Save.
Flow Networks
You must configure network interface and port settings on the ExtraHop system before you can collect NetFlow or sFlow data from remote flow networks (flow exporters). Flow networks cannot be configured on RevealX Enterprise systems. The ExtraHop system supports the following flow technologies: Cisco NetFlow Version 5 (v5) and Version 9 (v9), AppFlow, IPFIX, and sFlow.
In addition to configuring the ExtraHop system, you must configure your network devices to send sFlow or NetFlow traffic. Refer to your vendor documentation or see sample Cisco configurations in the appendix.
Collect traffic from NetFlow and sFlow devices
You must configure network interface and port settings on the ExtraHop system before you can collect NetFlow or sFlow data from remote flow networks (flow exporters). Flow networks cannot be configured on RevealX Enterprise systems. The ExtraHop system supports the following flow technologies: Cisco NetFlow v5 and v9, AppFlow, IPFIX, and sFlow.
Note: | For information on the EFC 1292v NetFlow sensor virtual appliance, see Deploy the ExtraHop EFC 1292v NetFlow Sensor. |
You must log in as a user with System and Access Administration privileges to complete the following steps.
Configure the interface on your ExtraHop system
Add the pending flow networks
You can now add pending flow networks.
Before you begin
You must log in as a user with System and Access Administration privileges to complete the following steps.- Log in to the ExtraHop system through https://<extrahop-hostname-or-IP-address>.
- In the Network Settings section, click Flow Networks.
- In the Pending Flow Networks section, click Add Flow Network.
- In the Flow Network ID field, type a name to identify this flow network.
- Select the Automatic records checkbox to send records from this flow network to a connected recordstore.
- Select the Enable SNMP polling checkbox to enable SNMP polling.
-
If you enable SNMP polling, select one of the following options from the SNMP
credentials drop-down list:
- Inherit from CIDR. If you select this option, the SNMP credentials are applied based on the Shared SNMP Credentials settings.
- Custom credentials. Select v1, v2, or v3 from the SNMP version drop-down list, and then configure the remaining settings for the specific polling type.
- Click Save.
Configure Cisco NetFlow devices
The following examples of basic Cisco router configuration for NetFlow. NetFlow is configured on a per-interface basis. When NetFlow is configured on the interface, IP packet flow information is exported to the ExtraHop system.
Important: | NetFlow takes advantage of the SNMP ifIndex value to represent ingress and egress interface information in flow records. To ensure consistency of interface reporting, enable SNMP ifIndex persistence on devices sending NetFlow to the ExtraHop system. For more information on how to enable SNMP ifIndex persistence on your network devices, refer to the configuration guide provided by the device manufacturer. |
For more information on configuring NetFlow on Cisco switches, see your Cisco router documentation or the Cisco website at www.cisco.com.
Set up shared SNMP credentials for your NetFlow or sFlow networks
If you enable SNMP polling on your flow network configuration, you must specify the credentials that allow you to poll the network device. The SNMP authentication credentials apply to all flow networks in a CIDR block and are automatically applied to every discovered flow network unless custom credentials are configured.
Manually refresh SNMP information
Notifications
The ExtraHop system can send notifications about configured alerts through email, SNMP traps, and syslog exports to remote servers. If an email notification group is specified, then emails are sent to the groups assigned to the alert.
Configure email settings for notifications
You must configure an email server and sender before the ExtraHop system can send alert notifications or scheduled reports.
Next steps
After you confirm that your new settings are working as expected, preserve your configuration changes through system restart and shutdown events by saving the running configuration file.Configure an email notification group
Add a list of email addresses to a group, then select the group when you configure email settings for an alert or scheduled report. Although you can specify individual email addresses, email groups are an effective way to manage your recipient list.
Configure settings to send notifications to an SNMP manager
The state of the network can be monitored through the Simple Network Management Protocol (SNMP). SNMP collects information by polling devices on the network. SNMP enabled devices can also send alerts to SNMP management stations. SNMP communities define the group where devices and management stations running SNMP belong, which specifies where information is sent. The community name identifies the group.
Note: | Most organizations have an established system for collecting and displaying SNMP traps in a central location that can be monitored by their operations teams. For example, SNMP traps are sent to an SNMP manager, and the SNMP management console displays them. |
Download the ExtraHop SNMP MIB
SNMP does not provide a database of information that an SNMP-monitored network reports. SNMP information is defined by third-party management information bases (MIBs) that describe the structure of the collected data.
Extract the ExtraHop vendor object OID
Before you can monitor a device with SNMP, you need the sysObjectID, which contains an OID that is the vendor-reported identity of the device.
Send system notifications to a remote syslog server
The syslog export option enables you to send alerts from an ExtraHop system to any remote system that receives syslog input for long-term archiving and correlation with other sources.
Next steps
After you confirm that your new settings are working as expected, preserve your configuration changes through system restart and shutdown events by saving the running configuration file.TLS Certificate
TLS certificates provide secure authentication to the ExtraHop system.
You can designate a self-signed certificate for authentication instead of a certificate signed by a Certificate Authority. However, be aware that a self-signed certificate generates an error in the client browser, which reports that the signing certificate authority is unknown. The browser provides a set of confirmation pages to trust the certificate, even though the certificate is self-signed. Self-signed certificates can also degrade performance by preventing caching in some browsers. We recommend that you create a certificate-signing request from your ExtraHop system and upload the signed certificate instead.
Important: | When replacing an TLS certificate, the web server service is restarted. Tunneled connections from ExtraHop sensors to ExtraHop consoles are lost but then re-established automatically. |
Upload a TLS certificate
You must upload a .pem file that includes both a private key and either a self-signed certificate or a certificate-authority certificate.
Note: | The .pem file must not be password protected. |
Note: | You can also automate this task through the REST API. |
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click TLS Certificate.
- Click Manage certificates to expand the section.
- Click Choose File and navigate to the certificate that you want to upload.
- Click Open.
- Click Upload.
- Save the running configuration file
Create a certificate signing request from your ExtraHop system
A certificate signing request (CSR) is a block of encoded text that is given to your Certificate Authority (CA) when you apply for an TLS certificate. The CSR is generated on the ExtraHop system where the TLS certificate will be installed and contains information that will be included in the certificate such as the common name (domain name), organization, locality, and country. The CSR also contains the public key that will be included in the certificate. The CSR is created with the private key from the ExtraHop system, making a key pair.
Next steps
Send the CSR file to your certificate authority (CA) to have the CSR signed. When you receive the TLS certificate from the CA, return to the TLS Certificate page in the Administration settings and upload the certificate to the ExtraHop system.Tip: | If your organization requires that the CSR contains a new public key, generate a self-signed certificate to create new key pairs before creating the CSR. |
Trusted Certificates
Trusted certificates enable you to validate SMTP, LDAP, HTTPS ODS and MongoDB ODS targets, as well as Splunk recordstore connections from your ExtraHop system.
Add a trusted certificate to your ExtraHop system
Your ExtraHop system only trusts peers who present a Transport Layer Security (TLS) certificate that is signed by one of the built-in system certificates and any certificates that you upload. SMTP, LDAP, HTTPS ODS and MongoDB ODS targets, as well as Splunk recordstore connections can be validated through these certificates.
Before you begin
You must log in as a user with setup or system and access administration privileges to add or remove trusted certificates.Important: | To trust the built-in system certificates and any uploaded certificates, you must also enable TLS or STARTTLS encryption and certificate validation when configuring the settings for the external server. |
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Network Settings section, click Trusted Certificates.
- (Optional): If you want to trust the built-in certificates included in the ExtraHop system, select Trust System Certificates, click Save, and then save the running configuration file.
- To add your own certificate, click Add Certificate and then in the Certificate field, paste the contents of the PEM-encoded certificate chain.
- In the Name field, type a name.
- Click Add.
Access Settings
In the Access Settings section, you can change user passwords, enable the support account, manage local users and user groups, configure remote authentication, and manage API access.
Global Policies
Administrators can configure global policies that apply to all users who access the system.
Password policy
- Choose between two password policies; the default password policy of 5 or more
characters or a more secure strict password policy that has the following
restrictions:
- 8 or more characters
- Upper and lowercase characters
- At least one number
- At least one symbol
Note: If you select the strict password policy of 8 or more characters, passwords will expire every 60 days.
Device Group Edit Control
- Control whether users with limited write privileges can create and edit device groups. When this policy is selected, all limited write users can create device groups and add other limited write users as editors to their device groups.
Default Dashboard
- Specify the dashboard that users see when they log in to the system. Only dashboards shared with all users can be set as a global default. Users can override this default setting from the command menu of any dashboard.
File Extraction Password
- (NDR module only) Specify a required password that you can share with approved users to unzip files extracted and downloaded from a packet query.
Passwords
Users with privileges to the Administration page can change the password for local user accounts.
- Select any user and change their password
- You can only change passwords for local users. You cannot change passwords for users authenticated through LDAP or other remote authentication servers.
For more information about privileges for specific Administration page users and groups, see the Users section.
Change the default password for the setup user
It is recommended that you change the default password for the setup user on the ExtraHop system after you log in for the first time. To remind administrators to make this change, there is a blue Change Password button at the top of the page while the setup user is accessing the Administration settings. After the setup user password is changed, the button at the top of the page no longer appears.
Note: | The password must be a minimum of 5 characters. |
Support Access
Support accounts provide access for the ExtraHop Support team to help customers troubleshoot issues with the ExtraHop system.
These settings should be enabled only if the ExtraHop system administrator requests hands-on assistance from the ExtraHop Support team.
Generate SSH key
- In the Access Settings section, click Support Access.
- Click Generate SSH Key.
- Copy the encrypted key from the text box and email the key to your ExtraHop representative.
- Click Done.
Regenerate or revoke the SSH key
To prevent SSH access to the ExtraHop system with an existing SSH key, you can revoke the current SSH key. A new SSH key can also be regenerated if needed.
- In the Access Settings section, click Support Access.
- Click Generate SSH Key.
-
Choose one of the following options:
- Click Regenerate SSH Key and then click
Regenerate.
Copy the encrypted key from the text box and email the key to your ExtraHop representative and then click Done.
- Click Revoke SSH Key to prevent SSH access to the system with the current key.
- Click Regenerate SSH Key and then click
Regenerate.
Users
The Users page enables you to control local access to the ExtraHop appliance.
Users and user groups
Users can access the ExtraHop system in three ways: through a set of pre-configured user accounts, through local user accounts configured on the appliance, or through remote user accounts configured on existing authentication servers, such as LDAP, SAML, Radius, and TACACS+.
Video: | See the related trainings: |
Local users
This topic is about default and local accounts. See Remote Authentication to learn how to configure remote accounts.
- setup
- This account provides full system read and write privileges to the browser-based user interface and to the ExtraHop command-line interface (CLI). On physical sensors, the default password for this account is the service tag number on the front of the appliance. On virtual sensors, the default password is default.
- shell
- The shell account, by default, has access to non-administrative shell commands in the ExtraHop CLI. On physical sensors, the default password for this account is the service tag number on the front of the appliance. On virtual sensors, the default password is default.
Note: | The default ExtraHop password for either account when deployed in Amazon Web Services (AWS) and Google Cloud Platform (GCP) is the instance ID of the virtual machine. |
Next steps
Remote Authentication
The ExtraHop system supports remote authentication for user access. Remote authentication enables organizations that have authentication systems such as LDAP (OpenLDAP or Active Directory, for example) to enable all or a subset of their users to log in to the system with their existing credentials.
Centralized authentication provides the following benefits:
- User password synchronization.
- Automatic creation of ExtraHop accounts for users without administrator intervention.
- Management of ExtraHop privileges based on user groups.
- Administrators can grant access to all known users or restrict access by applying LDAP filters.
Remote users
If your ExtraHop system is configured for SAML or LDAP remote authentication, you can create an account for those remote users. Preconfiguring accounts on the ExtraHop system for remote users enables you to share system customizations with those users before they log in.
If you choose to auto-provision users when you configure SAML authentication, then the user is automatically added to the list of local users when they log in for the first time. However, you can create a remote SAML user account on the ExtraHop system when you want to provision a remote user before that user has logged in to the system. Privileges are assigned to the user by the provider. After the user is created, you can add them to local user groups.
Next steps
User groups
User groups enable you to manage access to shared content by group instead of by individual user. Customized objects such as activity maps can be shared with a user group, and any user who is added to the group automatically has access. You can create a local user group—which can include remote and local users. Alternatively, if your ExtraHop system is configured for remote authentication through LDAP, you can configure settings to import your LDAP user groups.
- Click Create User Group to create a local group. The user group appears in the list. Then, select the checkbox next to the user group name and select users from the Filter users... drop-down list. Click Add Users to Group.
- (LDAP only) Click Refresh All User Groups or select multiple LDAP user groups and click Refresh Users in Groups.
- Click Reset User Group to remove all shared content from a selected user group. If the group no longer exists on the remote LDAP server, the group is removed from the user group list.
- Click Enable User Group or Disable User Group to control whether any group member can access shared content for the selected user group.
- Click Delete User Group to remove the selected user group from the system.
- View the following properties for listed user groups:
- Group Name
- Displays the name of the group. To view the members in the group, click the group name.
- Type
- Displays Local or Remote as the type of user group.
- Members
- Displays the number of users in the group.
- Shared Content
- Displays the number of user-created objects that are shared with the group.
- Status
- Displays whether the group is enabled or disabled on the system. When the status is Disabled, the user group is considered empty when performing membership checks; however, the user group can still be specified when sharing content.
- Members Refreshed (LDAP only)
- Displays the amount of time elapsed since the group membership was refreshed. User
groups are refreshed under the following conditions:
- Once per hour, by default. The refresh interval setting can be modified on the page.
- An administrator refreshes a group by clicking Refresh All User Groups or Refresh Users in Group, or programmatically through the REST API. You can refresh a group from the User Group page or from within the Member List page.
- A remote user logs in to the ExtraHop system for the first time.
- A user attempts to load a shared dashboard that they do not have access to.
User privileges
Administrators determine the module access level for users in the ExtraHop system.
For information about user privileges for the REST API, see the REST API Guide.
For information about remote user privileges, see the configuration guides for LDAP, RADIUS, SAML, and TACACS+.
Privilege Levels
Set the privilege level for your user to determine which areas of the ExtraHop system they can access.
- NDR Module Access
- Allows the user to access security features such as attack detections, investigations, and threat briefings.
- NPM Module Access
- Allows the user to access performance features such as operations detections and the ability to create custom dashboards.
- Packet and Session Key Access
- Allows the user to view and download packets and session keys, packets only, packet headers only, or packet slices only. Also allows the user to extract files associated with packets.
These privileges determine the level of functionality users have within the modules where they have been granted access.
For RevealX Enterprise, users with system access and administration privileges can access all features, packets, and session keys for their licensed modules.
For RevealX 360, system access and administration privileges, access to licensed modules, packets, and session keys must be assigned separately. RevealX 360 also offers an additional System Administration account that grants full system privileges except for the ability to manage users and API access.
The following table contains ExtraHop features and their required privileges. If no module requirement is noted, the feature is available in both the NDR and NDM modules.
System and Access Administration | System Administration (RevealX 360 only) | Full Write | Limited Write | Personal Write | Full Read-Only | Restricted Read-Only | |
---|---|---|---|---|---|---|---|
Activity Maps | |||||||
Create, view, and load shared activity maps | Y | Y | Y | Y | Y | Y | N |
Save activity maps | Y | Y | Y | Y | Y | N | N |
Share activity maps | Y | Y | Y | Y | N | N | N |
Alerts | NPM module license and access required. | ||||||
View alerts | Y | Y | Y | Y | Y | Y | Y |
Create and modify alerts | Y | Y | Y | N | N | N | N |
Analysis Priorities | |||||||
View Analysis Priorities page | Y | Y | Y | Y | Y | Y | N |
Add and modify analysis levels for groups | Y | Y | Y | N | N | N | N |
Add devices to a watchlist | Y | Y | Y | N | N | N | N |
Transfer priorities management | Y | Y | Y | N | N | N | N |
Bundles | |||||||
Create a bundle | Y | Y | Y | N | N | N | N |
Upload and apply a bundle | Y | Y | Y | N | N | N | N |
Download a bundle | Y | Y | Y | Y | Y | N | N |
View list of bundles | Y | Y | Y | Y | Y | Y | N |
Dashboards | NPM module license and access required to create and modify dashboards. | ||||||
View and organize dashboards | Y | Y | Y | Y | Y | Y | Y |
Create and modify dashboards | Y | Y | Y | Y | Y | N | N |
Share dashboards | Y | Y | Y | Y | N | N | N |
Detections | NDR module license and access required
to view and tune security detections and create
investigations. NPM module license and access required to view and tune performance detections. |
||||||
View detections | Y | Y | Y | Y | Y | Y | Y |
Acknowledge Detections | Y | Y | Y | Y | Y | N | N |
Modify detection status and notes | Y | Y | Y | Y | N | N | N |
Create and modify investigations | Y | Y | Y | Y | N | N | N |
Create and modify tuning rules | Y | Y | Y | N | N | N | N |
Device Groups | Administrators can configure the Device Group Edit Control global policy to specify whether users with limited write privileges can create and edit device groups. | ||||||
Create and modify device groups | Y | Y | Y | Y (If the global privilege policy is enabled) | N | N | N |
Integrations | RevealX 360 only | ||||||
Configure and modify integrations | Y | Y | N | N | N | N | N |
Metrics | |||||||
View metrics | Y | Y | Y | Y | Y | Y | N |
Notification Rules | NDR module license and access required
to create and modify notifications for security detections, security
detection catalog, and threat briefings. NPM module license and access required to create and modify notifications for performance detections and performance detection catalog. |
||||||
Create and modify detection notification rules | Y | Y | Y | N | N | N | N |
Create and modify detection notification rules for SIEM integrations (RevealX 360 only) | Y | Y | N | N | N | N | N |
Create and modify detection catalog notification rules | Y | Y | Y | N | N | N | N |
Create and modify threat briefing notification rules | Y | Y | Y | N | N | N | N |
Create and modify system notification rules | Y | Y | N | N | N | N | N |
Records | Recordstore required. | ||||||
View record queries | Y | Y | Y | Y | Y | Y | N |
View record formats | Y | Y | Y | Y | Y | Y | N |
Create, modify, and save record queries | Y | Y | Y | N | N | N | N |
Create, modify, and save record formats | Y | Y | Y | N | N | N | N |
Scheduled Reports | Console required. | ||||||
Create, view, and manage scheduled reports | Y | Y | Y | Y | N | N | N |
Threat Intelligence | NDR module license and access required. | ||||||
Configure file hashing filters | Y | Y | N | N | N | N | N |
Manage threat collections | Y | Y | N | N | N | N | N |
Manage TAXII feeds | Y | Y | N | N | N | N | N |
View threat intelligence information | Y | Y | Y | Y | Y | Y | N |
Triggers | |||||||
Create and modify triggers | Y | Y | Y | N | N | N | N |
Administrative Privileges | |||||||
Access the ExtraHop Administration settings | Y | Y | N | N | N | N | N |
Connect to other appliances | Y | Y | N | N | N | N | N |
Manage other appliances (Console) | Y | Y | N | N | N | N | N |
Manage users and API access | Y | N | N | N | N | N | N |
Add a local user account
By adding a local user account, you can provide users with direct access to your ExtraHop system and restrict their privileges as needed by their role in your organization.
Tip: |
|
Add an account for a remote user
Add a user account for LDAP or SAML users when you want to provision the remote user before that user logs in to the ExtraHop system. After the user is added to the system, you can add them to local groups or share items directly with them before they log in through the LDAP or SAML provider.
Sessions
The ExtraHop system provides controls to view and delete user connections to the web interface. The Sessions list is sorted by expiration date, which corresponds to the date the sessions were established. If a session expires or is deleted, the user must log in again to access the web interface.
Remote Authentication
The ExtraHop system supports remote authentication for user access. Remote authentication enables organizations that have authentication systems such as LDAP (OpenLDAP or Active Directory, for example) to enable all or a subset of their users to log in to the system with their existing credentials.
Centralized authentication provides the following benefits:
- User password synchronization.
- Automatic creation of ExtraHop accounts for users without administrator intervention.
- Management of ExtraHop privileges based on user groups.
- Administrators can grant access to all known users or restrict access by applying LDAP filters.
Next steps
Configure remote authentication through LDAP
The ExtraHop system supports the Lightweight Directory Access Protocol (LDAP) for authentication and authorization. Instead of storing user credentials locally, you can configure your ExtraHop system to authenticate users remotely with an existing LDAP server. Note that ExtraHop LDAP authentication only queries for user accounts; it does not query for any other entities that might be in the LDAP directory.
Before you begin
- This procedure requires familiarity with configuring LDAP.
- Ensure that each user is in a permission-specific group on the LDAP server before beginning this procedure.
- If you want to configure nested LDAP groups, you must modify the Running Configuration file. Contact ExtraHop Support for help.
When a user attempts to log onto an ExtraHop system, the ExtraHop system tries to authenticate the user in the following ways:
- Attempts to authenticate the user locally.
- Attempts to authenticate the user through the LDAP server if the user does not exist locally and if the ExtraHop system is configured for remote authentication with LDAP.
- Logs the user onto the ExtraHop system if the user exists and the password is validated either locally or through LDAP. The LDAP password is not stored locally on the ExtraHop system. Note that you must enter the username and password in the format that your LDAP server is configured for. The ExtraHop system only forwards the information to the LDAP server.
- If the user does not exist or an incorrect password is entered, an error message appears on the login page.
Important: | If you change LDAP authentication at a later time to a different remote authentication method, the users, user groups, and associated customizations that were created through remote authentication are removed. Local users are unaffected. |
Configure user privileges for remote authentication
You can assign user privileges to individual users on your ExtraHop system or configure and manage privileges through your LDAP server.
The ExtraHop system supports both Active Directory and POSIX group memberships. For Active Directory, memberOf is supported. For POSIX, memberuid, posixGroups, groupofNames, and groupofuniqueNames are supported.
-
Choose one of the following options from the Privilege assignment
options drop-down list:
- Obtain privileges level from remote server
This option assigns privileges through your remote authentication server. You must complete at least one of the following distinguished name (DN) fields.
System and Access Administration DN: Create and modify all objects and settings on the ExtraHop system, including Administration settings.
Full Write DN: Create and modify objects on the ExtraHop system, not including Administration settings.
Limited Write DN: Create, modify, and share dashboards.
Personal Write DN: Create personal dashboards and modify dashboards shared with the logged-in user.
Full read-only DN: View objects in the ExtraHop system.
Restricted Read-only DN: View dashboards shared with the logged-in user.
Packet Slices Access DN: View and download the first 64 bytes of packets captured through the ExtraHop Trace appliance.
Packet Access DN: View and download packets captured through the ExtraHop Trace appliance.
Packet and Session Keys Access DN: View and download packets and any associated TLS session keys captured through the ExtraHop Trace appliance.
NDR Module Access DN: View, acknowledge, and hide security detections that appear in the ExtraHop system.
NPM Module Access DN: View, acknowledge, and hide performance detections that appear in the ExtraHop system.
- Remote users have full write access
This option grants remote users full write access to the ExtraHop system. In addition, you can grant additional access for packet downloads, TLS session keys, NDR module access, and NPM module access.
- Remote users have full read-only access
This option grants remote users read-only access to the ExtraHop system. In addition, you can grant additional access for packet downloads, TLS session keys, NDR module access, and NPM module access.
- Obtain privileges level from remote server
- (Optional):
Configure packet and session key access. Select one of the following options to
allow remote users to download packet captures and TLS session keys.
- No access
- Packet slices only
- Packets only
- Packets and session keys
- (Optional):
Configure NDR and NPM module access.
- No access
- Full access
- Click Save and Finish.
- Click Done.
Configure remote authentication through SAML
You can configure secure, single sign-on (SSO) authentication to the ExtraHop system through one or more security assertion markup language (SAML) identity providers.
Video: | See the related training: SSO Authentication |
When a user logs in to an ExtraHop system that is configured as a service provider (SP) for SAML SSO authentication, the ExtraHop system requests authorization from the appropriate identity provider (IdP). The identity provider authenticates the user's credentials and then returns the authorization for the user to the ExtraHop system. The user is then able to access the ExtraHop system.
Configuration guides for specific identity providers are linked below. If your provider is not listed, apply the settings required by the ExtraHop system to your identity provider.
Identity providers must meet the following criteria:
- SAML 2.0
- Support SP-initiated login flows. IdP-initiated login flows are not supported.
- Support signed SAML Responses
- Support HTTP-Redirect binding
The example configuration in this procedure enables access to the ExtraHop system through group attributes.
If your identity provider does not support group attribute statements, configure user attributes with the appropriate privileges for module access, system access, and packet forensics.
Enable SAML remote authentication
Before you begin
Warning: | If your system is already configured with a remote authentication method, changing these settings will remove any users and associated customizations created through that method, and remote users will be unable to access the system. Local users are unaffected. |
User attribute mapping
You must configure the following set of user attributes in the application attribute mapping section on your identity provider. These attributes identify the user throughout the ExtraHop system. Refer to your identity provider documentation for the correct property names when mapping attributes.
ExtraHop Attribute Name | Friendly Name | Category | Identity Provider Attribute Name |
---|---|---|---|
urn:oid:0.9.2342.19200300.100.1.3 | Standard Attribute | Primary email address | |
urn:oid:2.5.4.4 | sn | Standard Attribute | Last name |
urn:oid:2.5.4.42 | givenName | Standard Attribute | First name |
Group attribute statements
The ExtraHop system supports group attribute statements to easily map user privileges to all members of a specific group. When you configure the ExtraHop application on your identity provider, specify a group attribute name. This name is then entered in the Attribute Name field when you configure the identity provider on the ExtraHop system.
If your identity provider does not support group attribute statements, configure user attributes with the appropriate privileges for module access, system access, and packet forensics.
Configure SAML single sign-on with Okta
You can configure your ExtraHop system to enable users to log in to the system through the Okta identity management service.
Before you begin
- You should be familiar with administering Okta. These procedures are based on the Okta Classic UI. If you are configuring Okta through the Developer Console, the procedure might be slightly different.
- You should be familiar with administering ExtraHop systems.
These procedures require you to copy and paste information between the ExtraHop system and the Okta Classic UI, so it is helpful to have each system open side-by-side.
Configure SAML settings in Okta
This procedure requires you to copy and paste information between the ExtraHop Administration settings and the Okta Classic UI, so it is helpful to have each UI open side-by-side.
Assign the ExtraHop system to Okta groups
- From the Directory menu, select Groups.
- Click the group name.
- Click Manage Apps.
- Locate the name of the application you configured for the ExtraHop system and click Assign.
- Click Done.
Configure SAML single sign-on with Google
You can configure your ExtraHop system to enable users to log in to the system through the Google identity management service.
Before you begin
- You should be familiar with administering Google Admin.
- You should be familiar with administering ExtraHop systems.
These procedures require you to copy and paste information between the ExtraHop system and Google Admin console, so it is helpful to have each system open side-by-side.
Add user custom attributes
- Log in to the Google Admin console.
- Click Users.
- Click the Manage custom attributes icon .
- Click Add Custom Attribute.
- In the Category field, type ExtraHop.
- (Optional): In the Description field, type a description.
-
In the Custom fields section, enter the following
information:
- In the Name field, type writelevel.
- From the Info Type drop-down list, select Text.
- From the Visibility drop-down list, select Visible to domain.
- From the No. of values drop-down list, select Single Value.
-
Enable NDR module access:
- In the Name field, type ndrlevel.
- From the Info Type drop-down list, select Text.
- From the Visibility drop-down list, select Visible to domain.
- From the No. of values drop-down list, select Single Value.
-
Enable NPM module access:
- In the Name field, type npmlevel.
- From the Info Type drop-down list, select Text.
- From the Visibility drop-down list, select Visible to domain.
- From the No. of values drop-down list, select Single Value.
- (Optional):
If you have connected packetstores, enable packet access by configuring a
custom field:
- In the Name field, type packetslevel.
- From the Info Type drop-down list, select Text.
- From the Visibility drop-down list, select Visible to domain.
- From the No. of values drop-down list, select Single Value.
- Click Add.
Configure remote authentication through RADIUS
The ExtraHop system supports Remote Authentication Dial In User Service (RADIUS) for remote authentication and local authorization only. For remote authentication, the ExtraHop system supports unencrypted RADIUS and plaintext formats.
Configure remote authentication through TACACS+
The ExtraHop system supports Terminal Access Controller Access-Control System Plus (TACACS+) for remote authentication and authorization.
Configure the TACACS+ server
In addition to configuring remote authentication on your ExtraHop system, you must configure your TACACS+ server with two attributes, one for the ExtraHop service and one for the permission level. If you have an ExtraHop packetstore, you can optionally add a third attribute for packet capture and session key logging.
API Access
The API Access page enables you to generate, view, and manage access for the API keys that are required to perform operations through the ExtraHop REST API.
Manage API key access
Users with system and access administration privileges can configure whether users can generate API keys for the ExtraHop system. You can allow only local users to generate keys, or you can also disable API key generation entirely.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Access Settings section, click API Access.
-
In the Manage API Access section, select one of the
following options:
- Allow all users to generate an API key: Local and remote users can generate API keys.
- Only local users can generate an API key: Remote users cannot generate API keys.
- No users can generate an API key: No API keys can be generated by any user.
- Click Save Settings.
Configure cross-origin resource sharing (CORS)
Cross-origin resource sharing (CORS) allows you to access the ExtraHop REST API across domain-boundaries and from specified web pages without requiring the request to travel through a proxy server.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Access Settings section, click API Access.
-
In the CORS Settings section, specify one of the following
access configurations.
- To add a specific URL, type an origin URL in the text box, and then
click the plus (+) icon or press ENTER.
The URL must include a scheme, such as HTTP or HTTPS, and the exact domain name. You cannot append a path; however, you can provide a port number.
- To allow access from any URL, select the Allow API requests
from any Origin checkbox.
Note: Allowing REST API access from any origin is less secure than providing a list of explicit origins.
- To add a specific URL, type an origin URL in the text box, and then
click the plus (+) icon or press ENTER.
- Click Save Settings and then click Done.
Generate an API key
You must generate an API key before you can perform operations through the ExtraHop REST API. Keys can be viewed only by the user who generated the key or by users with system and access administration privileges. After you generate an API key, add the key to your request headers or the ExtraHop REST API Explorer.
Before you begin
Make sure the ExtraHop system is configured to allow API key generation.- In the Access Settings section, click API Access.
- In the Generate an API Key section, type a description for the new key, and then click Generate.
- Scroll down to the API Keys section and copy the API key that matches your description.
Privilege levels
User privilege levels determine which ExtraHop system and administration tasks the user can perform through the ExtraHop REST API.
You can view the privilege levels for users through the granted_roles and effective_roles properties. The granted_roles property shows you which privilege levels are explicitly granted to the user. The effective_roles property shows you all privilege levels for a user, including those received outside of the granted role, such as through a user group.
The granted_roles and effective_roles properties are returned by the following operations:
- GET /users
- GET /users/{username}
The granted_roles and effective_roles properties support the following privilege levels. Note that the type of tasks for each ExtraHop system vary by the available resources listed in the REST API Explorer and depend on the modules enabled on the system and user module access privileges.
Privilege level | Actions allowed |
---|---|
"system": "full" |
|
"write": "full" |
|
"write": "limited" |
|
"write": "personal" |
|
"metrics": "full" |
|
"metrics": "restricted" |
|
"ndr": "full" |
This is a module access privilege that can be granted to a user in addition to one of the following system access privilege levels:
|
"ndr": "none" |
This is a module access privilege that can be granted to a user in addition to one of the following system access privilege levels:
|
"npm": "full" |
This is a module access privilege that can be granted to a user in addition to one of the following system access privilege levels:
|
"npm": "none" |
This is a module access privilege that can be granted to a user in addition to one of the following system access privilege levels:
|
"packets": "full" |
This is an add-on privilege that can be granted to a user with one of the following privilege levels:
|
"packets": "full_with_keys" |
This is an add-on privilege that can be granted to a user with one of the following privilege levels:
|
"packets": "slices_only" |
This is an add-on privilege that can be granted to a user with one of the following privilege levels:
|
System Configuration
In the System Configuration section, you can modify the following settings.
- Capture
- Configure the network capture settings. (Sensors only)
- Datastore
- Configure an extended datastore or reset the local datastore. (Sensors only)
- Device Naming
- Configure the order of precedence when multiple names are found for a device.
- Inactive Sources
- Remove devices and applications that have been inactive between 1 and 90 days from search results.
- Detection Tracking
- Select whether to track detection investigations with the ExtraHop system or from an external ticketing system.
- Endpoint Lookup
- Configure links to an external IP address lookup tool for endpoints in the ExtraHop system.
- Geomap Data Source
- Modify the information in mapped geolocations.
- Open Data Streams
- Send log data to a third-party system, such as a syslog system, MongoDB database, or HTTP server. (Sensors only)
- Trends
- Reset all trends and trend-based alerts. (Sensors only).
- Backup and Restore
- Create, view, or restore system backups.
Capture
The Capture page provides controls to adjust how the ExtraHop system collects your network traffic for analysis.
Exclude protocol modules
By default, all supported modules on the ExtraHop system are included in the capture unless you manually exclude them.
- Click .
- Click Excluded Protocol Modules.
- Add Module to Exclude.
- On the Select Protocol Module to Exclude page, from the Module Name drop-down list, select the module that you want to exclude from the capture.
- Click Add.
- On the Excluded Protocol Modules page, click Restart Capture.
- After the capture restarts, click OK.
Exclude MAC addresses
Add filters to exclude specific MAC addresses or vendor device traffic from the network capture
Exclude an IP address or range
Add filters to exclude specific IP addresses and IP ranges from the network capture on the ExtraHop system.
- Click .
- Click IP Address Filters.
- Click Add Filter.
- On the IP Address Filters page, type either a single IP address you want to exclude, or an IP address mask in CIDR format for a range of IP addresses you want to exclude.
- Click Add.
Exclude a port
Add filters to exclude traffic from specific ports from the network capture on the ExtraHop system.
- In the System Configuration section,click Capture.
- Click Port Filters.
- Click Add Filter.
-
On the Add Port Filter page, type the port you want to
exclude.
- To specify a source port you want to exclude, type the port number in the Source Port field.
- To specify a destination port you want to exclude, type the port number in the Destination Port field.
- From the IP Protocol drop-down list, select the protocol you want to exclude on the indicated port.
- Click Add.
Filtering and deduplication
Refer to the following table to view the effects of filtering and deduplication on metrics, packet capture, and device discovery. Deduplication is enabled by default on the system.
Packet Dropped by | MAC address filter | IP address filter | Port filter | L2 dedup | L3 dedup |
---|---|---|---|---|---|
Network VLAN L2 Metrics | Not collected | Not collected | Not fragmented*: Not collected Fragmented: Collected |
Not collected | Collected |
Network VLAN L3 Metrics | Not collected | Not collected | Not fragmented: Not collected Fragmented: Collected |
Not collected | Collected |
Device L2/L3 Metrics | Not collected | Not collected | Not fragmented: Not collected Fragmented, top-level: Collected Fragmented, detail: Not collected |
Not collected | Collected |
Global PCAP Packets | Captured | Captured | Captured | Captured | Captured |
Precision PCAP Packets | Not captured | Not captured | Not captured | Not captured | Captured |
L2 Device Discovery | No discovery | Discovery | Discovery | -- | -- |
L3 Device Discovery | No discovery | No discovery | Not fragmented: No discovery Fragmented: Discovery |
-- | -- |
*For port filters, when IP fragments are present in the data feed, a port number is not determined during fragment reassembly. The ExtraHop system might collect metrics, capture packets, or discover a device even if the port filtering rule otherwise precludes it.
L2 duplicates are identical Ethernet frames. The duplicate frames do not usually exist on the wire, but are an artifact of the data feed configuration. L3 duplicates are frames that differ only in L2 header and IP TTL. These frames usually result from tapping on both sides of a router. Because these frames exist on the monitored network, they are counted at L2 and L3 in the locations referenced above. L3 deduplication is targeted toward L4 and above, for example, to avoid counting the L3 duplicates as TCP retransmissions.
Protocol classification
Protocol classification relies on specific payloads to identify custom protocols over specific ports. These protocols are Layer 7 (application-layer) protocols that sit above the Layer 4 (TCP or UDP) protocol. These applications have their own custom protocol, and they also use the TCP protocol.
The Protocol Classification page provides an interface to perform the following functions:
- List applications and ports for the following network entities:
- Widely-known applications that are mapped to non-standard ports.
- Lesser-known and custom networking applications.
- Unnamed applications with TCP and UDP traffic (for example, TCP 1234).
- Add custom protocol-to-application mapping that includes the following information:
- Name
- The user-specified protocol name.
- Protocol
- The selected Layer 4 protocol (TCP or UDP).
- Source
- (Optional) The specified source port. Port 0 indicates any source port.
- Destination
- The destination port or range of ports.
- Loose Initiation
- Select this checkbox if you want the classifier to attempt to categorize the connection
without seeing the connection open. ExtraHop recommends selecting loose initiation for
long-lived flows.
By default, the ExtraHop system uses loosely-initiated protocol classification, so it attempts to classify flows even after the connection was initiated. You can turn off loose initiation for ports that do not always carry the protocol traffic (for example, the wildcard port 0).
- Delete protocols with the selected application name and port mapping from the list.
The application name and port do not display in the ExtraHop system or in reports based on any future data capture. The device will appear in reports with historical data, if the device was active and discoverable within the reported time period.
- Restart the network capture.
- You must restart the network capture before any protocol classification changes take effect.
- Previously-collected capture data is preserved.
The ExtraHop system recognizes most protocols on their standard ports with some exceptions. On the Performance edition, the following protocols are recognized on any port:
- AJP
- DTLS
- FIX
- HTTP
- HTTP2
- IIOP
- Java RMI
- LDAP
- RPC
- SSH
- TLS
On RevealX 360, the following protocols are recognized on any port:
- ethminer
- getblocktemplate
- RDP
- RFB
- Stratum
- LDAP
- Java RMI
- IIOP
In some cases, if a protocol is communicating over a non-standard port, it is necessary to add the non-standard port on the Protocol Classification page. In these cases, it is important to properly name the non-standard port. The table below lists the standard ports for each of the protocols, along with the protocol name that must be specified when adding the custom port numbers on the Protocol Classification page.
In most cases, the name you enter is the same as the name of the protocol. The most common exceptions to this rule are Oracle (where the protocol name is TNS) and Microsoft SQL (where the protocol name is TDS).
If you add a protocol name that has multiple destination ports, add the entire port range separated by a dash (-). For example, if your protocol requires adding ports 1434, 1467, and 1489 for database traffic, type 1434-1489 in the Destination Port field. Alternatively, add each of the three ports in three separate protocol classifications with the same name.
Canonical Name | Protocol Name | Transport | Default Source Port | Default Destination Port |
---|---|---|---|---|
ActiveMQ | ActiveMQ | TCP | 0 | 61616 |
AJP | AJP | TCP | 0 | 8009 |
DB2 | DB2 | TCP | 0 | 50000, 60000 |
DHCP | DHCP | TCP | 68 | 67 |
Diameter | AAA | TCP | 0 | 3868 |
DICOM | DICOM | TCP | 0 | 3868 |
DNS | DNS | TCP, UDP | 0 | 53 |
FIX | FIX | TCP | 0 | 0 |
FTP | FTP | TCP | 0 | 21 |
FTP-DATA | FTP-DATA | TCP | 0 | 20 |
HL7 | HL7 | TCP, UDP | 0 | 2575 |
HTTPS | HTTPS | TCP | 0 | 443 |
IBM MQ | IBMMQ | TCP, UDP | 0 | 1414 |
ICA | ICA | TCP | 0 | 1494, 2598 |
IKE | IKE | UDP | 0 | 500 |
IMAP | IMAP | TCP | 0 | 143 |
IMAPS | IMAPS | TCP | 0 | 993 |
Informix | Informix | TCP | 0 | 1526, 1585 |
IPSEC | IPSEC | TCP, UDP | 0 | 1293 |
IPX | IPX | TCP, UDP | 0 | 213 |
IRC | IRC | TCP | 0 | 6660-6669 |
ISAKMP | ISAKMP | UDP | 0 | 500 |
iSCSI | iSCSI | TCP | 0 | 3260 |
Kerberos | Kerberos | TCP, UDP | 0 | 88 |
LDAP | LDAP | TCP | 0 | 389, 390, 3268 |
LLDP | LLDP | Link Level | N/A | N/A |
L2TP | L2TP | UDP | 0 | 1701 |
Memcache | Memcache | TCP | 0 | 11210, 11211 |
Modbus | Modbus | TCP | 0 | 502 |
MongoDB | MongoDB | TCP | 0 | 27017 |
MS SQL Server | TDS | TCP | 0 | 1433 |
MSMQ | MSMQ | TCP | 0 | 1801 |
MSRPC | MSRPC | TCP | 0 | 135 |
MySQL | MySQL | TCP | 0 | 3306 |
NetFlow | NetFlow | UDP | 0 | 2055 |
NFS | NFS | TCP | 0 | 2049 |
NFS | NFS | UDP | 0 | 2049 |
NTP | NTP | UDP | 0 | 123 |
OpenVPN | OpenVPN | UDP | 0 | 1194 |
Oracle | TNS | TCP | 0 | 1521 |
PCoIP | PCoIP | UDP | 0 | 4172 |
POP3 | POP3 | TCP | 0 | 143 |
POP3S | POP3S | TCP | 0 | 995 |
PostgreSQL | PostgreSQL | TCP | 0 | 5432 |
RADIUS | AAA | TCP | 0 | 1812, 1813 |
RADIUS | AAA | UDP | 0 | 1645, 1646, 1812, 1813 |
RDP | RDP | TCP | 0 | 3389 |
Redis | Redis | TCP | 0 | 6397 |
RFB | RFB | TCP | 0 | 5900 |
SCCP | SCCP | TCP | 0 | 2000 |
SIP | SIP | TCP | 0 | 5060, 5061 |
SMB | SMB | TCP | 0 | 139, 445 |
SMPP | SMPP | TCP | 0 | 2775 |
SMTP | SMTP | TCP | 0 | 25 |
SNMP | SNMP | UDP | 0 | 162 |
SSH | SSH | TCP | 0 | 0 |
Sybase | Sybase | TCP | 0 | 10200 |
SybaseIQ | SybaseIQ | TCP | 0 | 2638 |
Syslog | Syslog | UDP | 0 | 514 |
Telnet | Telnet | TCP | 0 | 23 |
TLS | TLS | TCP | 0 | 443 |
VNC | VNC | TCP | 0 | 5900 |
WebSocket | WebSocket | TCP | 0 | 80, 443 |
Windows Update Delivery Optimization | Windows Update Delivery Optimization | TCP | 0 | 7860 |
The name specified in the Protocol Name column in the table appears on the Protocol Classification page to classify a common protocol that communicates over non-standard ports.
Protocols in the ExtraHop system that do not appear in this table include the following:
- HTTP
- The ExtraHop system classifies HTTP on all ports.
- HTTP-AMF
- This protocol runs on top of HTTP and is automatically classified.
Protocols in this table that do not appear in the ExtraHop system include the following:
- FTP-DATA
- The ExtraHop system does not handle FTP-DATA on non-standard ports.
- LLDP
- This is a link-level protocol, so port-based classification does not apply.
Add a custom protocol classification
The following procedure describes how to add custom protocol classification labels with the TDS (MS SQL Server) protocol as an example.
By default, the ExtraHop system looks for TDS traffic on TCP port 1433. To add MS SQL Server TDS parsing on another port, complete the following steps.
Configure Device Discovery
The ExtraHop system can discover and track devices by their MAC address (L2 Discovery) or by their IP addresses (L3 Discovery). L2 Discovery offers the advantage of tracking metrics for a device even if the IP address is changed or reassigned through a DHCP request. The system can also automatically discover VPN clients.
Before you begin
Learn how device discovery and L2 discovery works in the ExtraHop system. Changing these settings affects how metrics are associated with devices.Note: | Packet brokers can filter ARP requests. The ExtraHop system relies on ARP requests to associate L3 IP addresses with L2 MAC addresses. |
Discover local devices
If you enable L3 Discovery, local devices are tracked by their IP address. The system creates an L2 parent entry for the MAC address and an L3 child entry for the IP address. Over time, if the IP address changes for a device, you might see a single entry for an L2 parent with a MAC address with multiple L3 child entries with different IP addresses.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click Device Discovery.
-
In the Local Device Discovery section, select from the
following choices:
- Select the Enable local device discovery checkbox to enable L3 Discovery.
- Clear the Enable local device discovery checkbox to enable L2 Discovery.
- Click Save.
Discover remote devices by IP address
You can configure the ExtraHop system to automatically discover devices on remote subnets by adding a range of IP addresses.
Note: | If your ExtraHop system is configured for L2 Discovery and your remote devices request IP addresses through a DHCP relay agent, you can track devices by their MAC address, and you do not need to configure Remote L3 Discovery. Learn more about device discovery. |
- L2 information, such as device MAC address and L2 traffic, is not available if the device is on a different network from the one being monitored by the ExtraHop system. This information is not forwarded by routers, and therefore is not visible to the ExtraHop system.
- Exercise caution when specifying CIDR notation. A /24 subnet prefix might result in 255 new devices discovered by the ExtraHop system. A wide /16 subnet prefix might result in 65,535 new devices discovered, which might exceed your device limit.
- If an IP address is removed from the Remote L3 Device Discovery settings, the IP
address will persist in the ExtraHop system as a remote L3 device as long as
there are existing active flows for that IP address or until the capture is
restarted. After a restart, the device is listed as an inactive remote L3
device.
If the same IP address is later added through the local data feed, that remote L3 device can transition to a local L3 device, but only if the capture process is restarted and the Local Device Discovery setting is enabled.
Important: | The capture process must be restarted when removing IP address ranges before the changes take effect. We recommend deleting all entries before restarting the capture process. The capture process does not need to be restarted when adding IP address ranges. |
Discover VPN clients
Enable the discovery of internal IP addresses that are associated with VPN client devices.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click Device Discovery.
-
In the VPN Client Discovery section, select from the
following choices:
- Select the Enable VPN client discovery checkbox to enable VPN client discovery.
- Clear the Enable VPN client discovery checkbox to disable VPN client discovery.
- Click Save.
TLS decryption
The ExtraHop system supports real-time decryption of TLS traffic for analysis. Before the system can decrypt your traffic, you must configure session key forwarding or upload an TLS server certificate and private key. The server certificate and private keys are uploaded over an HTTPS connection from a web browser to the ExtraHop system.
Note: | Your server traffic must be encrypted through one of these supported cipher suites. |
Help on this page
- Decrypt TLS traffic with session key forwarding without private keys.
- Clear the checkbox for Require Private Keys.
- Install session key forwarding software on your Linux or Windows servers.
- Add a global port to protocol mapping for each protocol you want to decrypt.
- Decrypt TLS traffic by uploading a certificate and private key.
Note: | TLS decryption requires a license. However, if you have a license for MS SQL, you can also upload a TLS certificate to decrypt MS SQL traffic from these settings. |
Upload a PEM certificate and RSA private key
Tip: | You can export a password-protected key to add to your ExtraHop system
by running the following command on a program such as
OpenSSL:openssl rsa -in yourcert.pem -out new.key |
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click SSL Decryption.
- In the Private Key Decryption section, select the checkbox for Require Private Keys.
- Click Save.
- In the Private Keys section, click Add Keys.
- In the Name field, type a descriptive name to identify this certificate and key.
- Clear the Enabled checkbox if you want to disable this TLS certificate.
- In the Certificate field, paste the public key certificate.
- In the Private Key field, paste the RSA private key.
- Click Add.
Next steps
Add the encrypted protocols you want to decrypt with this certificate.Upload a PKCS#12/PFX file
PKCS#12/PFX files are archived in a secure container on the ExtraHop system and contains both public and private key pairs, which can only be accessed with a password.
Tip: | To export private keys from a Java KeyStore to a PKCS#12 file, run the
following command on your server, where javakeystore.jks is the
path of your Java
KeyStore:keytool -importkeystore -srckeystore javakeystore.jks -destkeystore pkcs.p12 -srcstoretype jks -deststoretype pkcs12 |
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click SSL Decryption.
- In the Private Key Decryption section, select the checkbox for Require Private Keys.
- Click Save.
- In the Private Keys section, click Add Keys.
- In the Add PKCS#12/PFX File With Password section, in the Description field, type a descriptive name to identify this certificate and key.
- Clear the Enabled checkbox if you want to disable this TLS certificate.
- For PKCS#12/PFX file, click Browse.
- Browse to the file and select it, then click Open.
- In the Password field, type the password for the PKCS#12/PFX file.
- Click Add.
- Click OK.
Next steps
Add the encrypted protocols you want to decrypt with this certificate.Add encrypted protocols
You must add each protocol that you want to decrypt for each uploaded certificate.
Add a global port to protocol mapping
Add each protocol for the traffic that you want to decrypt with your session key forwarders.
Install the ExtraHop session key forwarder on a Windows server
Perfect Forward Secrecy (PFS) is a property of secure communication protocols that enables short-term, completely private session key exchanges between clients and servers. ExtraHop offers session key forwarding software that can send session keys to the ExtraHop system for TLS decryption. Communication between the key forwarder and the sensor is encrypted with TLS 1.2 or TLS 1.3, and there is no limit to the number of session keys that the ExtraHop system can receive.
Note: | For more information about how the traffic feed or changes to the configuration might affect sensors, review the desync and capture drop rate metrics in the System Health dashboard. |
You must configure the ExtraHop system for session key forwarding and then install the forwarder software on the Windows and Linux servers that have the TLS traffic that you want to decrypt.
Before you begin- Read about TLS decryption and review the list of supported cipher suites.
- Make sure that the ExtraHop system is licensed for TLS Decryption and TLS Shared Secrets.
- Make sure that your server environment is supported by the ExtraHop session key
forwarder software:
- Microsoft Secure Channel (Schannel) security package
- Java TLS (Java versions 8 through 17). Do not upgrade to this version of the session key forwarder if you are currently monitoring Java 6 or Java 7 environments. Version 7.9 of the session key forwarder supports Java 6 and Java 7, and is compatible with the latest ExtraHop firmware.
- Dynamically linked OpenSSL (1.0.x and 1.1.x) libraries. OpenSSL is only supported on Linux systems with kernel versions 4.4 and later and RHEL 7.6 and later.
- Make sure the server where you install the session key forwarder trusts the TLS certificate of the ExtraHop sensor.
- Make sure your firewall rules allow connections to be initiated by the monitored server to TCP port 4873 on the sensor.
Important: | The ExtraHop system cannot decrypt TLS-encrypted TDS traffic through session key forwarding. Instead, you can upload an RSA private key. |
- Install the session key forwarder on one or more Windows 2016 or Windows 2019 servers that are running TLS-based services with the native Windows TLS framework. OpenSSL on Windows is not currently supported.
Important: | After you install the session key forwarder software, applications that
include TLS-enabled features, such as EDR agents and Windows Store applications, might fail to
function correctly. Validate the compatibility of the session key forwarder in your Windows test environment before deploying in your production environment. |
Install the software with the installation wizard
The following steps show you how to install the session key forwarder from a Windows command prompt or Windows PowerShell.
Enable the TLS session key receiver service
You must enable the session key receiver service on the ExtraHop system before the system can receive and decrypt session keys from the session key forwarder. By default, this service is disabled.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Appliance Settings section, click Services.
- Select the SSL Session Key Receiver checkbox.
- Click Save.
Add a global port to protocol mapping
Add each protocol for the traffic that you want to decrypt with your session key forwarders.
View connected session key forwarders
You can view recently connected session key forwarders after you install the session key forwarder on your server and enable the TLS session key receiver service on the ExtraHop system. Note that this page only displays session key forwarders that have connected over the last few minutes, not all session key forwarders that are currently connected.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click SSL Shared Secrets.
Validate session key forwarding
Perform these steps to make sure that the installation was successful and the session key forwarder is forwarding the keys to the ExtraHop system.
- Log in to the Windows server.
-
Open the Services MMC snap-in. Ensure both services, "ExtraHop Session Key Forwarder"
and ExtraHop Registry Service" show the status as "Running".
-
If either service is not running, troubleshoot the issue
by completing the following steps.
- Open the Event Viewer MMC snap-in and navigate to Windows Logs > Application.
- Locate the most recent entries for the ExtraHopAgent source. Common reasons for failure and their associated error messages are listed in the Troubleshoot common error messages section below.
- If the Services and Event Viewer snap-in do not indicate any issues, apply a workload to the monitored services and go to the ExtraHop system to verify that secret-based decryption is working.
In cases where you might have problems with the configuration, the session key forwarder binary includes a test mode you can access from the command line to test your configuration.
Key receiver system health metrics
The ExtraHop system provides key receiver metrics that you can add to a dashboard chart to monitor key receiver health and functionality.
To view a list of available metrics, click the System Settings icon and then click Metric Catalog. Type key receiver in the filter field to display all available key receiver metrics.
Tip: | To learn how to create a new dashboard chart, see Edit a chart with the Metric Explorer. |
Integrate the forwarder with the Java-based TLS application
As an example, Apache Tomcat supports customization of Java options in the Tomcat service manager properties. In the following example, adding the -javaagent option to the Java Options section causes the Java runtime to share TLS session secrets with the key forwarder process, which then relays the secrets to the ExtraHop system so that the secrets can be decrypted.
-javaagent:C:\Program Files\ExtraHop\exagent.jar
Note: | If your server is running Java 17 or later, you must also
allow the sun.security.ssl module to access all unnamed modules with the
--add-opens option, as shown in the following
example:--add-opens java.base/sun.security.ssl=ALL-UNNAMED |
Appendix
Error messages are saved to log files in the following locations, where TMP is the value of your TMP environment variable:
- TMP\ExtraHopSessionKeyForwarderSetup.log
- TMP\ExtraHopSessionKeyForwarderMsi.log
The following table shows common error messages that you can troubleshoot. If you see a different error or the proposed solution does not resolve your issue, contact ExtraHop Support.
Message | Cause | Solution |
---|---|---|
connect: dial tcp <IP address>:4873: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond | The monitored server cannot route any traffic to the sensor. | Ensure firewall rules allow connections to be initiated by the monitored server to TCP port 4873 on the sensor. |
connect: dial tcp <IP address>:4873: connectex: No connection could be made because the target machine actively refused it | The monitored server can route traffic to the sensor, but the receiving process is not listening. | Ensure that the sensor is licensed for both the TLS Decryption and TLS Shared Secrets features. |
connect: x509: certificate signed by unknown authority | The monitored server is not able to chain up the sensor certificate to a trusted Certificate Authority (CA). | Ensure that the Windows certificate store for the computer account has trusted root certificate authorities that establish a chain of trust for the sensor. |
connect: x509: cannot validate certificate for <IP address> because it doesn't contain any IP SANs | An IP address was supplied as the EDA_HOSTNAME parameter when installing the forwarder, but the TLS certificate presented by the sensor does not include an IP address as a Subject Alternate Name (SAN). | Select from the following three solutions.
|
|
||
|
If you no longer want the ExtraHop session key forwarder software installed, or if any of the original installation parameters have changed (sensor hostname or certificate) and you need to reinstall the software with new parameters, do the following:
Important: | You must restart the server for the configuration changes to take effect. |
- Log in to the Windows server.
- (Optional): If you integrated the session key forwarder with Apache Tomcat, remove the -javaagent:C:\Program Files\ExtraHop\exagent.jar entry from Tomcat to prevent the web service from stopping.
-
Choose one of the following options to remove the software:
- Open the Control Panel and click Uninstall a program. Select ExtraHop Session Key Forwarder from the list and then click Uninstall.
-
Open a PowerShell command prompt and run the following commands to remove the software and associated registry entries:
-
$app=Get-WMIObject -class win32_product | where-object {$_.name -eq "ExtraHop Session Key Forwarder"}
-
$app.Uninstall()
-
- Click Yes to confirm.
- After the software is removed, click Yes to restart the system
You can specify the following MSI parameters:
MSI Installation Parameter | EDA_HOSTNAME |
Registry Entry | HKEY_LOCAL_MACHINE\SOFTWARE\ExtraHop\EDAHost |
Description | The sensor hostname or IP address where TLS
session keys will be sent. This parameter is required. |
MSI Installation Parameter | EDA_CERTIFICATEPATH |
Registry Entry | N/A |
Description |
The monitored server must trust the issuer of the sensor TLS certificate through the server's certificate store. In some environments, the sensor works with the self-signed certificate that the ExtraHop firmware generates upon installation. In this case, the certificate must be added to the certificate store. The EDA_CERTIFICATEPATH parameter enables a file-based PEM-encoded certificate to be imported into the Windows certificate store at installation. If the parameter is not specified at installation and a self-signed or other CA certificate must be placed into the certificate store manually, the administrator must import the certificate to Certificates (Computer Account) > Trusted Root Certification Authorities on the monitored system. This parameter is optional if the monitored server was previously configured to trust the TLS certificate of the sensor through the Windows certificate store. |
MSI Installation Parameter | SERVERNAMEOVERRIDE |
Registry Entry | HKEY_LOCAL_MACHINE\SOFTWARE\ExtraHop\ServerNameOverride |
Description |
If there is a mismatch between the sensor hostname that the forwarder knows (EDA_HOSTNAME) and the common name (CN) that is presented in the TLS certificate of the sensor, then the forwarder must be configured with the correct CN. This parameter is optional. We recommend that you regenerate the TLS self-signed certificate based on the hostname from the TLS Certificate section of the Administration settings instead of specifying this parameter. |
MSI Installation Parameter | TCPLISTENPORT |
Registry Entry | HKEY_LOCAL_MACHINE\SOFTWARE\ExtraHop\TCPListenPort |
Description | The key forwarder receives session keys locally from the Java environment
through a TCP listener on localhost (127.0.0.1) and the port specified in the
TCPListenPort entry. We recommended that this port remain set to
the default of 598. This parameter is optional. |
The ExtraHop system can decrypt TLS traffic that has been encrypted with PFS or RSA cipher suites. All supported cipher suites can be decrypted by installing the session key forwarder on a server and configuring the ExtraHop system.
Cipher suites for RSA can also decrypt the traffic with a certificate and private key—with or without session key forwarding.
- PFS + GPP: the ExtraHop system can decrypt these cipher suites with session key forwarding and global protocol to port mapping
- PFS + Cert: the ExtraHop system can decrypt these cipher suites with session key forwarding and the certificate and private key
- RSA + Cert: the ExtraHop system can decrypt these cipher suites without session key forwarding as long as you have uploaded the certificate and private key
Hex Value | Name (IANA) | Name (OpenSSL) | Supported Decryption |
---|---|---|---|
0x04 | TLS_RSA_WITH_RC4_128_MD5 | RC4-MD5 | PFS + GPP PFS + Cert RSA + Cert |
0x05 | TLS_RSA_WITH_RC4_128_SHA | RC4-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x0A | TLS_RSA_WITH_3DES_EDE_CBC_SHA | DES-CBC3-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x16 | TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA | EDH-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0x2F | TLS_RSA_WITH_AES_128_CBC_SHA | AES128-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x33 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA | DHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0x35 | TLS_RSA_WITH_AES_256_CBC_SHA | AES256-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x39 | TLS_DHE_RSA_WITH_AES_256_CBC_SHA | DHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0x3C | TLS_RSA_WITH_AES_128_CBC_SHA256 | AES128-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x3D | TLS_RSA_WITH_AES_256_CBC_SHA256 | AES256-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x67 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 | DHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0x6B | TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 | DHE-RSA-AES256-SHA256 | PFS + GPP PFS + Cert |
0x9C | TLS_RSA_WITH_AES_128_GCM_SHA256 | AES128-GCM-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x9D | TLS_RSA_WITH_AES_256_GCM_SHA384 | AES256-GCM-SHA384 | PFS + GPP PFS + Cert RSA + Cert |
0x9E | TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | DHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0x9F | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | DHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0x1301 | TLS_AES_128_GCM_SHA256 | TLS_AES_128_GCM_SHA256 | PFS + GPP PFS + Cert |
0x1302 | TLS_AES_256_GCM_SHA384 | TLS_AES_256_GCM_SHA384 | PFS + GPP PFS + Cert |
0x1303 | TLS_CHACHA20_POLY1305_SHA256 | TLS_CHACHA20_POLY1305_SHA256 | PFS + GPP PFS + Cert |
0xC007 | TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | ECDHE-ECDSA-RC4-SHA | PFS + GPP |
0xC008 | TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | ECDHE-ECDSA-DES-CBC3-SHA | PFS + GPP |
0xC009 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ECDHE-ECDSA-AES128-SHA | PFS + GPP |
0xC00A | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ECDHE-ECDSA-AES256-SHA | PFS + GPP |
0xC011 | TLS_ECDHE_RSA_WITH_RC4_128_SHA | ECDHE-RSA-RC4-SHA | PFS + GPP PFS + Cert |
0xC012 | TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | ECDHE-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0xC013 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ECDHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0xC014 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ECDHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0xC023 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ECDHE-ECDSA-AES128-SHA256 | PFS + GPP |
0xC024 | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | ECDHE-ECDSA-AES256-SHA384 | PFS + GPP |
0xC027 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ECDHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0xC028 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | ECDHE-RSA-AES256-SHA384 | PFS + GPP PFS + Cert |
0xC02B | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | ECDHE-ECDSA-AES128-GCM-SHA256 | PFS + GPP |
0xC02C | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ECDHE-ECDSA-AES256-GCM-SHA384 | PFS + GPP |
0xC02F | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ECDHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0xC030 | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ECDHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0xCCA8 | TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
0xCCA9 | TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-ECDSA-CHACHA20-POLY1305 | PFS + GPP |
0xCCAA | TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | DHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
You can export the MSI file from the executable file to support a custom installation workflow.
ExtraHopSessionKeyForwarderSetup.exe -e
Note: | You can append <directory> to
the -e parameter to save the .msi file
to a directory other than the current working directory. For example, the
following command saves the file to the install_dir
directory:ExtraHopSessionKeyForwarderSetup.exe -e install_dir |
Install the ExtraHop session key forwarder on a Linux server
Perfect Forward Secrecy (PFS) is a property of secure communication protocols that enables short-term, completely private session key exchanges between clients and servers. ExtraHop offers session key forwarding software that can send session keys to the ExtraHop system for TLS decryption. Communication between the key forwarder and the sensor is encrypted with TLS 1.2 or TLS 1.3, and there is no limit to the number of session keys that the ExtraHop system can receive.
Note: | For more information about how the traffic feed or changes to the configuration might affect sensors, review the desync and capture drop rate metrics in the System Health dashboard. |
You must configure the ExtraHop system for session key forwarding and then install the forwarder software on the Windows and Linux servers that have the TLS traffic that you want to decrypt.
Before you begin- Read about TLS decryption and review the list of supported cipher suites.
- Make sure that the ExtraHop system is licensed for TLS Decryption and TLS Shared Secrets.
- Make sure that your server environment is supported by the ExtraHop session key
forwarder software:
- Microsoft Secure Channel (Schannel) security package
- Java TLS (Java versions 8 through 17). Do not upgrade to this version of the session key forwarder if you are currently monitoring Java 6 or Java 7 environments. Version 7.9 of the session key forwarder supports Java 6 and Java 7, and is compatible with the latest ExtraHop firmware.
- Dynamically linked OpenSSL (1.0.x and 1.1.x) libraries. OpenSSL is only supported on Linux systems with kernel versions 4.4 and later and RHEL 7.6 and later.
- Make sure the server where you install the session key forwarder trusts the TLS certificate of the ExtraHop sensor.
- Make sure your firewall rules allow connections to be initiated by the monitored server to TCP port 4873 on the sensor.
Important: | The ExtraHop system cannot decrypt TLS-encrypted TDS traffic through session key forwarding. Instead, you can upload an RSA private key. |
- Install the session key forwarder on RHEL, CentOS, Fedora, or Debian-Ubuntu Linux distributions. The session key forwarder might not function correctly on other distributions.
- The session key forwarder has not been extensively tested with SELinux and might not be compatible when enabled on some Linux distributions.
Enable the TLS session key receiver service
You must enable the session key receiver service on the ExtraHop system before the system can receive and decrypt session keys from the session key forwarder. By default, this service is disabled.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Appliance Settings section, click Services.
- Select the SSL Session Key Receiver checkbox.
- Click Save.
Add a global port to protocol mapping
Add each protocol for the traffic that you want to decrypt with your session key forwarders.
Install the software
Tip: | You can install the forwarder without user interaction by specifying environment variables in the installation command. |
Tip: | You can install the forwarder without user interaction by specifying environment variables in the installation command. |
As an example, many Tomcat environments support customization of Java options in the /etc/default/tomcat7 file. In the following example, adding the -javaagent option to the JAVA_OPTS line causes the Java runtime to share TLS session secrets with the key forwarder process, which then relays the secrets to the ExtraHop system so that the secrets can be decrypted.
JAVA_OPTS="... -javaagent:/opt/extrahop/lib/exagent.jar
If your server is running Java 17 or later, you must also allow the sun.security.ssl module to access all unnamed modules with the --add-opens option, as shown in the following example:
JAVA_OPTS="... -javaagent:/opt/extrahop/lib/exagent.jar --add-opens java.base/sun.security.ssl=ALL-UNNAMED
Validate and troubleshoot your installation
If your Linux server has network access to the ExtraHop system and the server TLS configuration trusts the certificate presented by the ExtraHop system that you specified when you installed the session key forwarder, then the configuration is complete.
In cases where you might have problems with the configuration, the session key forwarder binary includes a test mode you can access from the command-line to test your configuration.
If there is a mismatch between the ExtraHop system hostname that the forwarder knows (SERVER) and the common name (CN) that is presented in the TLS certificate of the ExtraHop system, then the forwarder must be configured with the correct CN.
Key receiver system health metrics
The ExtraHop system provides key receiver metrics that you can add to a dashboard chart to monitor key receiver health and functionality.
To view a list of available metrics, click the System Settings icon and then click Metric Catalog. Type key receiver in the filter field to display all available key receiver metrics.
Tip: | To learn how to create a new dashboard chart, see Edit a chart with the Metric Explorer. |
View connected session key forwarders
You can view recently connected session key forwarders after you install the session key forwarder on your server and enable the TLS session key receiver service on the ExtraHop system. Note that this page only displays session key forwarders that have connected over the last few minutes, not all session key forwarders that are currently connected.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click SSL Shared Secrets.
Uninstall the software
If you no longer want the ExtraHop session key forwarder software installed, complete the following steps.
- Log in to the Linux server.
-
Open a terminal application and choose one of the following options to remove
the software.
- For RPM-based servers, run the following
command:
sudo rpm --erase extrahop-key-forwarder
- For Debian and Ubuntu servers, run the following
command:
sudo apt-get --purge remove extrahop-key-forwarder
Type Y at the prompt to confirm the software removal and then press ENTER.
- For RPM-based servers, run the following
command:
- Click Yes to confirm.
- After the software is removed, click Yes to restart the system
Common error messages
Errors created by the session key forwarder are logged to the Linux system log file.
Message | Cause | Solution |
---|---|---|
connect: dial tcp <IP address>:4873: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond | The monitored server cannot route any traffic to the sensor. | Ensure firewall rules allow connections to be initiated by the monitored server to TCP port 4873 on the sensor. |
connect: dial tcp <IP address>:4873: connectex: No connection could be made because the target machine actively refused it | The monitored server can route traffic to the sensor, but the receiving process is not listening. | Ensure that the sensor is licensed for both the TLS Decryption and TLS Shared Secrets features. |
connect: x509: certificate signed by unknown authority | The monitored server is not able to chain up the sensor certificate to a trusted Certificate Authority (CA). | Ensure that the Linux certificate store for the computer account has trusted root certificate authorities that establish a chain of trust for the sensor. |
connect: x509: cannot validate certificate for <IP address> because it doesn't contain any IP SANs | An IP address was supplied as the SERVER parameter when installing the forwarder, but the TLS certificate presented by the sensor does not include an IP address as a Subject Alternate Name (SAN). | Select from the following three solutions.
|
|
||
|
Supported TLS cipher suites
The ExtraHop system can decrypt TLS traffic that has been encrypted with PFS or RSA cipher suites. All supported cipher suites can be decrypted by installing the session key forwarder on a server and configuring the ExtraHop system.
Cipher suites for RSA can also decrypt the traffic with a certificate and private key—with or without session key forwarding.
- PFS + GPP: the ExtraHop system can decrypt these cipher suites with session key forwarding and global protocol to port mapping
- PFS + Cert: the ExtraHop system can decrypt these cipher suites with session key forwarding and the certificate and private key
- RSA + Cert: the ExtraHop system can decrypt these cipher suites without session key forwarding as long as you have uploaded the certificate and private key
Hex Value | Name (IANA) | Name (OpenSSL) | Supported Decryption |
---|---|---|---|
0x04 | TLS_RSA_WITH_RC4_128_MD5 | RC4-MD5 | PFS + GPP PFS + Cert RSA + Cert |
0x05 | TLS_RSA_WITH_RC4_128_SHA | RC4-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x0A | TLS_RSA_WITH_3DES_EDE_CBC_SHA | DES-CBC3-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x16 | TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA | EDH-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0x2F | TLS_RSA_WITH_AES_128_CBC_SHA | AES128-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x33 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA | DHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0x35 | TLS_RSA_WITH_AES_256_CBC_SHA | AES256-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x39 | TLS_DHE_RSA_WITH_AES_256_CBC_SHA | DHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0x3C | TLS_RSA_WITH_AES_128_CBC_SHA256 | AES128-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x3D | TLS_RSA_WITH_AES_256_CBC_SHA256 | AES256-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x67 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 | DHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0x6B | TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 | DHE-RSA-AES256-SHA256 | PFS + GPP PFS + Cert |
0x9C | TLS_RSA_WITH_AES_128_GCM_SHA256 | AES128-GCM-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x9D | TLS_RSA_WITH_AES_256_GCM_SHA384 | AES256-GCM-SHA384 | PFS + GPP PFS + Cert RSA + Cert |
0x9E | TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | DHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0x9F | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | DHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0x1301 | TLS_AES_128_GCM_SHA256 | TLS_AES_128_GCM_SHA256 | PFS + GPP PFS + Cert |
0x1302 | TLS_AES_256_GCM_SHA384 | TLS_AES_256_GCM_SHA384 | PFS + GPP PFS + Cert |
0x1303 | TLS_CHACHA20_POLY1305_SHA256 | TLS_CHACHA20_POLY1305_SHA256 | PFS + GPP PFS + Cert |
0xC007 | TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | ECDHE-ECDSA-RC4-SHA | PFS + GPP |
0xC008 | TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | ECDHE-ECDSA-DES-CBC3-SHA | PFS + GPP |
0xC009 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ECDHE-ECDSA-AES128-SHA | PFS + GPP |
0xC00A | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ECDHE-ECDSA-AES256-SHA | PFS + GPP |
0xC011 | TLS_ECDHE_RSA_WITH_RC4_128_SHA | ECDHE-RSA-RC4-SHA | PFS + GPP PFS + Cert |
0xC012 | TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | ECDHE-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0xC013 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ECDHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0xC014 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ECDHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0xC023 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ECDHE-ECDSA-AES128-SHA256 | PFS + GPP |
0xC024 | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | ECDHE-ECDSA-AES256-SHA384 | PFS + GPP |
0xC027 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ECDHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0xC028 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | ECDHE-RSA-AES256-SHA384 | PFS + GPP PFS + Cert |
0xC02B | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | ECDHE-ECDSA-AES128-GCM-SHA256 | PFS + GPP |
0xC02C | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ECDHE-ECDSA-AES256-GCM-SHA384 | PFS + GPP |
0xC02F | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ECDHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0xC030 | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ECDHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0xCCA8 | TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
0xCCA9 | TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-ECDSA-CHACHA20-POLY1305 | PFS + GPP |
0xCCAA | TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | DHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
Session key forwarder options
You can configure the session key forwarder by editing the /opt/extrahop/etc/extrahop-key-forwarder.conf file.
Important: | If you add options to
extrahop-key-forwarder.conf that do not have dedicated variables, they
must be in the ADDITIONAL_ARGS field. For
example:ADDITIONAL_ARGS="-v=true -libcrypto=/some/path/libcrypto.so -libcrypto=/some/other/path/libcrypto.so" |
Option | Description |
---|---|
-cert <path> | Specifies the path to the server certificate. Only specify this option if the server certificate is not signed by a trusted certificate authority. |
-containerd-enable | Enables the enumeration of containers managed with the containerd runtime. This option is disabled by default. You must type -containerd-enable to enable containerd support. |
-containerd-socket <string> | The full path of the containerd socket file. |
-containerd-state <string> | The full path of the containerd state directory. |
-containerd-state-rootfs-subdir <string> | The relative path of the rootfs subdirectory of the containerd state directory. |
-docker-enable | Enables the enumeration of Docker containers. This option is enabled by default. You must type -docker-enable=false to disable Docker support. |
-docker-envoy <path> | Specifies additional Envoy paths within Docker containers. You can specify this option multiple times. |
-docker-go-binary <value> | Specifies glob patterns to find Go binaries within Docker containers. You can specify this option multiple times. |
-docker-libcrypto <path> | Specifies the path to libcrypto within Docker containers. You can specify this option multiple times. |
-envoy <path> | Specifies additional Envoy paths on the host. You can specify this option multiple times. |
-go-binary <value> | Specifies glob patterns to find Go binaries. You can specify this option multiple times. |
-hearbeat-interval | Specifies the time interval in seconds between heartbeat messages. The default interval is 30 seconds. |
-host-mount-path <path> | Specifies the path where the host file system is mounted when running the session key forwarder inside a container. |
-hosted <platform> | Specifies that the agent is running in the specified hosted platform. The platform is currently limited to aws. |
-ldconfig-cache <path> | Specifies the path to the ldconfig cache, ld.so.cache. The default path is /etc/ld.so.cache. You can specify this option multiple times. |
-libcrypto <path> | Specifies the path to the OpenSSL library, libcrypto. You can specify this option multiple times if you have multiple installations of OpenSSL. |
-no-docker-envoy | Disables Envoy support within Docker containers. |
-no-envoy | Disables Envoy support on the host. |
-openssl-discover | Automatically discovers libcrypto implementations. The default value is "true". You must type -openssl-discover=false to disable OpenSSL decryption. |
-pidfile <path> | Specifies the file where this server records its process ID (PID). |
-port <value> | Specifies the TCP port that the sensor is listening on for forwarded session keys. The default port is 4873. |
-server <string> | Specifies the fully qualified domain name of the packet sensor. |
-server-name-override <value> | Specifies the subject name from the sensor certificate. Specify this option if this server can only connect to the packet sensor by IP address. |
-syslog <facility> | Specifies the facility sent by the key forwarder. The default facility is local3. |
-t | Perform a connectivity test. You must type -t=true to run with this option. |
-tcp-listen-port <value> | Specifies the TCP port that the key forwarder is listening on for forwarded session keys. |
-username <string> | Specifies the user that the session key forwarder runs under after the forwarder software is installed. |
-v | Enable verbose logging. You must type -v=true to run with this option. |
The following environment variables enable you to install the session key forwarder without user interaction.
Variable | Description | Example |
---|---|---|
EXTRAHOP_CONNECTION_MODE | Specifies the connection mode to the session key receiver. Options are direct for self-managed sensors and hosted for ExtraHop-managed sensors. | sudo EXTRAHOP_CONNECTION_MODE=hosted rpm --install extrahop-key-forwarder.x86_64.rpm |
EXTRAHOP_EDA_HOSTNAME | Specifies the fully qualified domain name of the self-managed sensor. | sudo EXTRAHOP_CONNECTION_MODE=direct EXTRAHOP_EDA_HOSTNAME=host.example.com dpkg --install extrahop-key-forwarder_amd64.deb |
EXTRAHOP_LOCAL_LISTENER_PORT | The key forwarder receives session keys locally from the Java environment through a TCP listener on localhost (127.0.0.1) and the port specified in the LOCAL_LISTENER_PORT field. We recommended that this port remain set to the default of 598. If you change the port number, you must modify the -javaagent argument to account for the new port. | sudo EXTRAHOP_CONNECTION_MODE=direct EXTRAHOP_EDA_HOSTNAME=host.example.com EXTRAHOP_LOCAL_LISTENER_PORT=900 rpm --install extrahop-key-forwarder.x86_64.rpm |
EXTRAHOP_SYSLOG | Specifies the facility, or machine process, that created the syslog event. The default facility is local3, which is system daemon processes. | sudo EXTRAHOP_CONNECTION_MODE=direct EXTRAHOP_EDA_HOSTNAME=host.example.com EXTRAHOP_SYSLOG=local1 dpkg --install extrahop-key-forwarder_amd64.deb |
EXTRAHOP_ADDITIONAL_ARGS | Specifies additional key forwarder options. | sudo EXTRAHOP_CONNECTION_MODE=hosted EXTRAHOP_ADDITIONAL_ARGS="-v=true -libcrypto=/some/path/libcrypto.so libcrypto=/some/other/path/libcrypto.so" rpm --install extrahop-key-forwarder.x86_64.rpm |
Supported TLS cipher suites
The ExtraHop system can decrypt TLS traffic that has been encrypted with PFS or RSA cipher suites. All supported cipher suites can be decrypted by installing the session key forwarder on a server and configuring the ExtraHop system.
Cipher suites for RSA can also decrypt the traffic with a certificate and private key—with or without session key forwarding.
Decryption methods
- PFS + GPP: the ExtraHop system can decrypt these cipher suites with session key forwarding and global protocol to port mapping
- PFS + Cert: the ExtraHop system can decrypt these cipher suites with session key forwarding and the certificate and private key
- RSA + Cert: the ExtraHop system can decrypt these cipher suites without session key forwarding as long as you have uploaded the certificate and private key
Hex Value | Name (IANA) | Name (OpenSSL) | Supported Decryption |
---|---|---|---|
0x04 | TLS_RSA_WITH_RC4_128_MD5 | RC4-MD5 | PFS + GPP PFS + Cert RSA + Cert |
0x05 | TLS_RSA_WITH_RC4_128_SHA | RC4-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x0A | TLS_RSA_WITH_3DES_EDE_CBC_SHA | DES-CBC3-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x16 | TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA | EDH-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0x2F | TLS_RSA_WITH_AES_128_CBC_SHA | AES128-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x33 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA | DHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0x35 | TLS_RSA_WITH_AES_256_CBC_SHA | AES256-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x39 | TLS_DHE_RSA_WITH_AES_256_CBC_SHA | DHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0x3C | TLS_RSA_WITH_AES_128_CBC_SHA256 | AES128-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x3D | TLS_RSA_WITH_AES_256_CBC_SHA256 | AES256-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x67 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 | DHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0x6B | TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 | DHE-RSA-AES256-SHA256 | PFS + GPP PFS + Cert |
0x9C | TLS_RSA_WITH_AES_128_GCM_SHA256 | AES128-GCM-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x9D | TLS_RSA_WITH_AES_256_GCM_SHA384 | AES256-GCM-SHA384 | PFS + GPP PFS + Cert RSA + Cert |
0x9E | TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | DHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0x9F | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | DHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0x1301 | TLS_AES_128_GCM_SHA256 | TLS_AES_128_GCM_SHA256 | PFS + GPP PFS + Cert |
0x1302 | TLS_AES_256_GCM_SHA384 | TLS_AES_256_GCM_SHA384 | PFS + GPP PFS + Cert |
0x1303 | TLS_CHACHA20_POLY1305_SHA256 | TLS_CHACHA20_POLY1305_SHA256 | PFS + GPP PFS + Cert |
0xC007 | TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | ECDHE-ECDSA-RC4-SHA | PFS + GPP |
0xC008 | TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | ECDHE-ECDSA-DES-CBC3-SHA | PFS + GPP |
0xC009 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ECDHE-ECDSA-AES128-SHA | PFS + GPP |
0xC00A | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ECDHE-ECDSA-AES256-SHA | PFS + GPP |
0xC011 | TLS_ECDHE_RSA_WITH_RC4_128_SHA | ECDHE-RSA-RC4-SHA | PFS + GPP PFS + Cert |
0xC012 | TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | ECDHE-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0xC013 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ECDHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0xC014 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ECDHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0xC023 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ECDHE-ECDSA-AES128-SHA256 | PFS + GPP |
0xC024 | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | ECDHE-ECDSA-AES256-SHA384 | PFS + GPP |
0xC027 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ECDHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0xC028 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | ECDHE-RSA-AES256-SHA384 | PFS + GPP PFS + Cert |
0xC02B | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | ECDHE-ECDSA-AES128-GCM-SHA256 | PFS + GPP |
0xC02C | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ECDHE-ECDSA-AES256-GCM-SHA384 | PFS + GPP |
0xC02F | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ECDHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0xC030 | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ECDHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0xCCA8 | TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
0xCCA9 | TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-ECDSA-CHACHA20-POLY1305 | PFS + GPP |
0xCCAA | TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | DHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
Store TLS session keys on connected packetstores
When session key forwarding is configured on an ExtraHop system that is connected to a packetstore, the ExtraHop system can store encrypted session keys along with the collected packets.
Before you begin
Learn more about decrypting packets with stored keys.- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click SSL Session Key Storage.
- Select Enable SSL Session Key Storage.
- Click Save.
Next steps
For more information about downloading session keys, see Download session keys with packet captures.
View connected session key forwarders
You can view recently connected session key forwarders after you install the session key forwarder on your server and enable the TLS session key receiver service on the ExtraHop system. Note that this page only displays session key forwarders that have connected over the last few minutes, not all session key forwarders that are currently connected.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click SSL Shared Secrets.
Decrypt domain traffic with a Windows domain controller
The ExtraHop system can be configured to retrieve and store domain keys from one or more domain controllers. When the system observes encrypted traffic that matches the stored keys, all of the Kerberos-encrypted traffic in the domain is decrypted for supported protocols. The system only synchronizes Kerberos and NTLM decryption keys and does not modify any other properties in the domain.
A domain controller like Active Directory is a frequent target for attackers because a successful attack campaign yields high-value targets. Critical attacks can be obscured by Kerberos or NTLM decryption, such as Golden Ticket, PrintNightmare, and Bloodhound. Decrypting this type of traffic can provide deeper insight for security detections.
You can enable decryption on an individual sensor or through an integration on RevealX 360. You can add more than one domain controller connection from a sensor to decrypt traffic from multiple domains.
The following requirements must be met for decryption:
- You must have an Active Directory domain controller (DC) that is not configured as a Read-only Domain Controller (RODC).
- Only Windows Server 2016, Windows Server 2019, and Windows Server 2022 are supported.
- The ExtraHop system synchronizes keys for up to 50,000 accounts in a configured domain. If your DC has more than 50,000 accounts, some traffic will not be decrypted.
- The ExtraHop system must observe the network traffic between the DC and connected clients and servers.
- The ExtraHop system must be able to access the domain controller over the following ports: TCP 88 (Kerberos), TCP 445 (SMB), TCP 135 (RPC), and TCP ports 49152-65535 (RPC dynamic range).
Warning: | If you enable these settings, the ExtraHop system is granted access to
all of the account keys in the Windows domain. The ExtraHop system should be deployed at
the same security level as the domain controller. Here are some best practices to
consider:
|
Connect a domain controller to a sensor
Before you begin
You must have a user account with setup or system and access administration privileges on the sensor.Next steps
- Click Add Domain Controller Connection to connect to another domain controller.
- Click Change User Credentials from a saved connection to modify credentials associated with the connection.
- Click Remove Connection to delete all credentials associated with the connection and disconnect the domain controller from the sensor.
Connect a domain controller to a RevealX 360 sensor
Before you begin
Your user account must have privileges on RevealX 360 for System and Access Administration.Next steps
- Click Add Domain Controller Connection to connect to another domain controller.
- Click Change User Credentials from a saved connection to modify credentials associated with the connection.
- Click Delete Credentials to delete all credentials associated with the connection and disconnect the domain controller from the sensor.
Validate the configuration settings
To validate that the ExtraHop system is able to decrypt traffic with configured domain controllers, go to the built-in Microsoft Protocol Decryption dashboard to identify successful decryption attempts.
Each chart in the Microsoft Protocol Decryption dashboard contains visualizations of Kerberos decryption data that have been generated over the selected time interval, organized by region.
The Microsoft Protocol Decryption dashboard is a built-in, system dashboard that you cannot edit, delete, or add to a shared collection. However, you can copy a chart from the Microsoft Protocol Decryption dashboard and add it to a custom dashboard, or you can make a copy of the dashboard and edit it to monitor metrics that are relevant to you.
Note: | The Microsoft Protocol Decryption dashboard can only be viewed on a console. |
The following information summarizes each region and its charts.
- Kerberos Decryption Attempts
- Observe the number of Kerberos decryption attempts in your environment in the
following charts:
Successful Kerberos Decryption Attempts: Total number of successful Kerberos decryption attempts and when they occurred.
Total Successful Attempts: Total number of successful Kerberos decryption attempts.
Unsuccessful Kerberos Decryption Attempts: Total number of unsuccessful Kerberos decryption attempts and when they occurred, listed by the reason the attempt failed.
Total Unsuccessful Attempts: Total number of unsuccessful Kerberos decryption attempts, listed by the reason the attempt failed.
- Unsuccessful Kerberos Decryption Details
- Observe details about unsuccessful Kerberos decryption attempts in the following
charts:
Unrecognized Server Principal Names: Total number of Kerberos decryption attempts that failed due to an unrecognized server principal name (SPN), listed by the SPN. Displayed as a bar chart and a list chart.
Invalid Kerberos Keys: Total number of Kerberos decryption attempts that failed due to an invalid Kerberos key, listed by the SPN that made the attempt. Displayed as a bar chart and a list chart.
Kerberos Decryption Errors : Total number of Kerberos decryption attempts that failed due to an error, listed by the SPN that made the attempt. Displayed as a bar chart and a list chart.
- Server Principal Name Details
- Observe the top SPN that made Kerberos decryption attempts in the following
charts:
Top Server Principal Names: Top 50 SPNs that made Kerberos decryption attempts and the following details:
- The number of successful decryption attempts.
- The number of unsuccessful attempts due to an invalid Kerberos key.
- The number of unsuccessful attempts due to an error.
- The number of unsuccessful attempts due an unrecognized SPN.
Additional system health metrics
To view a list of available metrics, click the System Settings icon and then click Metric Catalog. Type DC-Assisted in the filter field to display all available DC-assisted decryption metrics.
Import external data to your ExtraHop system
The ExtraHop Open Data Context API enables you to import data from an external host into the session table on your ExtraHop sensor. That data can then be accessed to create custom metrics that you can add to ExtraHop charts, store in records on a recordstore, or export to a external analysis tool.
After you enable the Open Data Context API on your sensor, you can import data by running a Python script from a memcached client on an external host. That external data is stored in key-value pairs, and can be accessed by writing a trigger.
For example, you might run a memcached client script on an external host to import CPU load data into the session table on your sensor. Then, you can write a trigger that accesses the session table and commits the data as custom metrics.
Warning: | The connection between the external host and the ExtraHop system is not encrypted and should not transmit sensitive information. |
Enable the Open Data Context API
You must enable the Open Data Context API on your sensor before it can receive data from an external host.
Before you begin
- You must have setup or system and access administration privileges to access the Administration page on your ExtraHop system.
- If you have a firewall, your firewall rules must allow external hosts to access the specified TCP and UDP ports. The default port number is 11211.
Write a Python script to import external data
Before you can import external data into the session table on your sensor, you must write a Python script that identifies your sensor and contains the data you want to import into the session table. The script is then run from a memcached client on the external host.
This topic provides syntax guidance and best practices for writing the Python script. A complete script example is available at the end of this guide.
Before you begin
Ensure that you have a memcached client on the external host machine. You can install any standard memcached client library, such as http://libmemcached.org/ or https://pypi.python.org/pypi/pymemcache. The sensor acts as a memcached version 1.4 server.
Here are some important considerations about the Open Data Context API:- The Open Data Context API supports most memcached commands, such as get, set, and increment.
- All data must be inserted as strings that are readable by the sensor. Some
memcached clients attempt to store type information in the values. For example,
the Python memcache library stores floats as pickled values, which cause invalid
results when calling Session.lookup in triggers. The following
Python syntax correctly inserts a float as a
string:
mc.set("my_float", str(1.5))
- Although session table values can be almost unlimited in size, committing large values to the session table might cause performance degradation. In addition, metrics committed to the datastore must be 4096 bytes or fewer, and oversized table values might result in truncated or imprecise metrics.
- Basic statistics reporting is supported, but detailed statistics reporting by item size or key prefix is not supported.
- Setting item expiration when adding or updating items is supported, but bulk expiration through the flush command is not supported.
- Keys expire at 30-second intervals. For example, if a key is set to expire in 50 seconds, it can take from 50 to 79 seconds to expire.
- All keys set with the Open Data Context API are exposed through the SESSION_EXPIRE trigger event as they expire. This behavior is in contrast to the Trigger API, which does not expose expiring keys through the SESSION_EXPIRE event.
Write a trigger to access imported data
You must write a trigger before you can access the data in the session table.
Before you begin
This topic assumes experience with writing triggers. If you are unfamiliar with triggers, check out the following topics:Next steps
You must assign the trigger to a device or device group. The trigger will not run until it has been assigned.Open Data Context API example
In this example, you will learn how to check the reputation score and potential risk of domains that are communicating with devices on your network. First, the example Python script shows you how to import domain reputation data into the session table on your sensor. Then, the example trigger script shows you how to check IP addresses on DNS events against that imported domain reputation data and how to create a custom metric from the results.
Example Python script
This Python script contains a list of 20 popular domain names and can reference domain reputation scores obtained from a source such as DomainTools.
This script is a REST API that accepts a POST operation where the body is the domain name. Upon a POST operation, the memcached client updates the session table with the domain information.
#!/usr/bin/python import flask import flask_restful import memcache import sqlite3 top20 = { "google.com", "facebook.com", "youtube.com", "twitter.com", "microsoft.com", "wikipedia.org", "linkedin.com", "apple.com","adobe.com", "wordpress.org", "instagram.com", "wordpress.com", "vimeo.com", "blogspot.com", "youtu.be", "pinterest.com", "yahoo.com", "goo.gl", "amazon.com", "bit.ly} dnsnames = {} mc = memcache.Client(['10.0.0.115:11211']) for dnsname in top20: dnsnames[dnsname] = 0.0 dbc = sqlite3.Connection('./dnsreputation.db') cur = dbc.cursor() cur.execute('select dnsname, score from dnsreputation;') for row in cur: dnsnames[row[0]] = row[1] dbc.close() app = flask.Flask(__name__) api = flask_restful.Api(app) class DnsReputation(flask_restful.Resource): def post(self): dnsname = flask.request.get_data() #print dnsname mc.set(dnsname, str(dnsnames.get(dnsname, 50.0)), 120) return 'added to session table' api.add_resource(DnsReputation, '/dnsreputation') if __name__ == '__main__': app.run(debug=True,host='0.0.0.0')
Example trigger script
This example trigger script canonicalizes (or converts) IP addresses that are returned on DNS events into domain names, and then checks for the domain and its reputation score in the session table. If the score value is greater than 75, the trigger adds the domain to an application container called "DNSReputation" as a detail metric called "Bad DNS reputation".
//Configure the following trigger settings: //Name: DNSReputation //Debugging: Enabled //Events: DNS_REQUEST, DNS_RESPONSE if (DNS.errorNum != 0 || DNS.qname == null || DNS.qname.endsWith("in-addr.arpa") || DNS.qname.endsWith("local") || DNS.qname.indexOf('.') == -1 ) { // error or null or reverse lookup, or lookup of local namereturn return; } //var canonicalname = DNS.qname.split('.').slice(-2).join('.'); var canonicalname = DNS.qname.substring(DNS.qname.lastIndexOf('.', DNS.qname.lastIndexOf('.')-1)+1) //debug(canonicalname); //Look for this DNS name in the session table var score = Session.lookup(canonicalname) if (score === null) { // Send to the service for lookup Remote.HTTP("dnsrep").post({path: "/dnsreputation", payload: canonicalname}); } else { debug(canonicalname + ':' +score); if (parseFloat(score) > 75) { //Create an application in the ExtraHop system and add custom metrics //Note: The application is not displayed in the ExtraHop system after the //initial request, but is displayed after subsequent requests. Application('DNSReputation').metricAddDetailCount('Bad DNS reputation', canonicalname + ':' + score, 1); } }
Install the packet forwarder on a Linux server
You must install the packet forwarder software on each server to be monitored to forward packets to the ExtraHop system.
Download and install on other Linux systems
Install the packet forwarder on a Windows server
You must install the packet forwarder software on each server to be monitored in order to forward packets to the ExtraHop system.
Monitoring multiple interfaces on a Linux server
For servers with multiple interfaces, you can configure the packet forwarder to forward packets from a particular interface or from multiple interfaces by editing its configuration file on the server.
To edit the configuration file, complete the following steps.
Monitoring multiple interfaces on a Windows server
For servers with multiple interfaces, you can configure the packet forwarder to forward packets from a particular interface or from multiple interfaces by editing its configuration file on the server.
To edit the configuration file, complete the following steps.
Enable network overlay decapsulation
Network overlay encapsulation wraps standard network packets in outer protocol headers to perform specialized functions, such as smart routing and virtual machine networking management. Network overlay decapsulation enables the ExtraHop system to remove these outer encapsulating headers and then process the inner packets.
Note: | Enabling Generic Routing Encapsulation (GRE), Network Virtualization using Generic Routing Encapsulation (NVGRE), VXLAN, and GENEVE decapsulation on your ExtraHop system can increase your device count as virtual devices are discovered on the network. Discovery of these virtual devices can affect Advanced Analysis and Standard Analysis capacity and the additional metrics processing can cause performance to degrade in extreme cases. |
MPLS, TRILL, and Cisco FabricPath protocols are automatically decapsulated by the ExtraHop system.
Enable VXLAN decapsulation
VXLAN is a UDP tunneling protocol configured for specific destination ports. Decapsulation is not attempted unless the destination port in a packet matches the UDP destination port or ports listed in the VXLAN decapsulation settings.
Enable GENEVE decapsulation
Analyze a packet capture file
The offline capture mode enables administrators to upload and analyze a capture file recorded by packet analyzer software, such as Wireshark or tcpdump, in the ExtraHop system.
Here are some important considerations before enabling offline capture mode:
- When the capture is set to offline mode, the system datastore is reset. All previously recorded metrics are deleted from the datastore. When the system is set to online mode, the datastore is reset again.
- In offline mode, no metrics are collected from the capture interface until the system is set to online mode again.
- Only capture files in the pcap format are supported. Other formats such as pcpapng are not supported.
Set the offline capture mode
Return the system to live capture mode
- In the System Configuration section, click Capture (offline).
- Click Restart Capture.
- Select Live, and then click Save.
Datastore
The ExtraHop system includes a self-contained, streaming datastore for storing and retrieving performance and health metrics in real time. This local datastore bypasses the operating system and accesses the underlying block devices directly, rather than going through a conventional relational database.
Local and extended datastores
The ExtraHop system includes a self-contained, streaming datastore for storing and retrieving performance and health metrics in real time. This local datastore bypasses the operating system and accesses the underlying block devices directly, rather than going through a conventional relational database.
The local datastore maintains entries for all devices discovered by the ExtraHop system as well as metrics for those devices. By storing this information, the ExtraHop system is able to provide both quick access to the latest network capture and historic and trend-based information about selected devices.
Extended datastore
The ExtraHop system can connect to an external storage device to expand your metric storage. By default, the ExtraHop system stores fast (30-second), medium (5-minute), and slow (1-hour) metrics locally. However, you can store 5-minute, 1-hour, and 24-hour metrics on an extended datastore.
To store metrics externally, you must first mount an external datastore, and then configure the ExtraHop system to store data in the mounted directory. You can mount an external datastore through NFS v4 (with optional Kerberos authentication) or SMB (with optional authentication).
Note that you can configure only one active extended datastore at a time to collect all configured metric cycles. For example, if you configure your extended datastore to collect 5-minute, 1-hour, and 24-hour metrics, all three metric cycles are stored in the same extended datastore. In addition, you can archive an extended datastore and those metrics are available for read-only requests from multiple ExtraHop systems.
Here are some important things to know about configuring an external datastore:
- If an extended datastore contains multiple files with overlapping timestamps, the metrics will be incorrect.
- If an extended datastore has metrics committed by an ExtraHop system running a later firmware version, the system with the older firmware cannot read those metrics.
- If an extended datastore becomes unreachable, the ExtraHop system buffers metrics until the allocated memory is full. After the memory is full, the system overwrites older blocks until the connection is restored. When the mount reconnects, all of the metrics stored in memory are written to the mount.
- If an extended datastore file is lost or corrupted, metrics contained in that file are lost. Other files in the extended datastore remain intact.
- As a security measure, the system does not allow access to the stored plaintext password for the datastore.
Calculate the size needed for your extended datastore
The extended datastore must have enough space to contain the amount of data generated by the ExtraHop system. The following procedure explains how you can calculate approximately how much free space you need for your extended datastore.
Before you begin
Familiarize yourself with ExtraHop datastore concepts.Next steps
Configure an extended SMB or NFS datastore.Configure an extended SMB or NFS datastore
The following procedures show you how to configure an external datastore for the ExtraHop system.
Before you begin
Calculate the size needed for your extended datastore- First, you mount the NFS or SMB share where you want to store data.
- For NFS, optionally configure Kerberos authentication before you add the NFS mount.
- Finally, specify the newly added mount as the active datastore.
(Optional) Configure Kerberos for NFS
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Datastore and Customizations.
- In the System Configuration section, click Datastore.
- Click Add Kerberos Config.
- In the Admin Server field, type the IP address or hostname of the master Kerberos server that issues tickets.
- In the Key Distribution Center (KDC) field, type the IP address or hostname of the server that holds the keys.
- In the Realm field, type the name of the Kerberos realm for your configuration.
- In the Domain field, type the name of the Kerberos domain for your configuration.
- In the Keytab File section, click Choose File, select a saved keytab file, and then click Open.
- Click Upload.
Add an NFS mount
Before you begin
- Configure any applicable Kerberos authentication before you add an NFS mount.
- Either allow read/write access for all users on the share or assign the 'extrahop' user as the owner of the share and allow read/write access.
- You must have NFS version 4.
- In the System Configuration section, click Datastore.
- In the Extended Datastore Settings section, click Configure Extended Datastore.
- Click Add NFSv4 Mount.
- On the Configure NFSv4 Mount page, complete the following information:
- In the Mount Name field, type a name for the mount, such as EXDS.
- In the Remote Share Point field, type the path for the mount in the following format: host:/mountpoint, such as herring:/mnt/extended-datastore.
-
From the Authentication drop-down, select from the
following options:
- None, for no authentication.
- Kerberos, for krb5 security.
- Kerberos (Secure Auth and Data Integrity), for krb5i security.
- Kerberos (Secure Auth, Data Integrity, Privacy), for krb5p security.
- Click Save.
Specify a mount as an active extended datastore
Note: | If you decide to store 5-minute and 1-hour metrics on the extended datastore, this option causes any 5-minute and 1-hour metrics collected from the local ExtraHop system datastore to be migrated to the extended datastore. Migrating 5-minute and 1-hour metrics to an extended datastore leaves more room to store 30-second metrics on the local datastore, which increases the amount of high-resolution lookback available. |
Archive an extended datastore for read-only access
By disconnecting an active datastore from an ExtraHop system, you can create a read-only archive of the stored metrics data. Any number of ExtraHop systems can read from an archived datastore.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Datastore.
- In the Extended Datastore Settings section, click Configure Extended Datastore.
- Click the name of the mount that contains the datastore you want to archive.
- In the row of that datastore, click Disconnect Extended Datastore.
- Type YES to confirm.
- Click OK.
Connect your ExtraHop system to the archived datastore
Warning: | To connect to an archived datastore, the ExtraHop system must
scan through the data contained in the datastore. Depending on the amount of
data stored in the archived datastore, connecting to the archived datastore
might take a long time. When connecting to the archived datastore, the system
does not collect data and system performance is degraded. The connection process
takes more time under the following circumstances:
|
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Datastore.
- In the Extended Datastore Settings section, click Configure Extended Datastore.
- Click the name of the mount that contains the archived datastore.
- In the Datastore Directory field, type the path of the archived datastore directory.
- Click Archive (Read Only).
- Click Configure.
Import metrics from an extended datastore
If you stored metric data on an extended datastore that is connected to your ExtraHop system, you can move that data during an upgrade or datastore reset.
Reset the local datastore and remove all device metrics from the ExtraHop system
In certain circumstances, such as moving a sensor from one network to another, you might need to clear the metrics in the local and extended datastores. Resetting the local datastore removes all metrics, baselines, trend analyses, and discovered devices—and affects any customizations on your ExtraHop system.
Warning: | This procedure deletes device IDs and device metrics from the ExtraHop system. |
Here are some important considerations about resetting the local datastore:
- Familiarize yourself with ExtraHop database concepts.
- Customizations are changes that were made to the default settings on the system, such as triggers, dashboards, alerts, and custom metrics. These settings are stored in a file on the system, and this file is also deleted when the datastore is reset.
- The reset procedure includes an option to save and restore your customizations.
- Most customizations are applied to devices, which are identified by an ID on the system. When the local datastore is reset, those IDs might change and any device-based assignments must be re-assigned to the devices by their new IDs.
- If your device IDs are stored on the extended datastore, and that datastore is disconnected when the local datastore is reset and then later reconnected, those device IDs are restored to the local datastore and you do not need to reassign your restored customizations.
- The reset procedure preserves historical device count data to maintain the accuracy of metrics in the Active Device Count and Limit chart.
- Configured alerts are retained on the system, but they are disabled and must be enabled and reapplied to the correct network, device, or device group. System settings and user accounts are unaffected.
Troubleshoot issues with the extended datastore
To view the status for your mounts and datastores, and identify applicable troubleshooting steps, complete the following steps.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Datastore.
- In the Extended Datastore Settings section, click Configure Extended Datastore.
- In the Extended Datastores table, view the entry in the Status column for each mount or datastore.
Status | Description | User Action |
---|---|---|
Mounted | The mount configuration was successful. | None required |
NOT MOUNTED | The mount configuration was unsuccessful. |
|
NOT READABLE | The mount has permissions or network-related issues that prevent reading. |
|
NO SPACE AVAILABLE | The mount has no space remaining. | Detach the mount and create a new one. |
INSUFFICIENT SPACE |
|
Detach the mount and create a new one. |
AVAILABLE SPACE WARNING | Less than 1GB of space is available. | Detach the mount and create a new one. |
NOT WRITEABLE | The mount has permissions or network-related issues that prevent writing. |
|
Status | Description | User Action |
---|---|---|
Nominal | The datastore is in a normal state. | None required |
INSUFFICIENT SPACE on: <MOUNT NAME> | The datastore has insufficient space on the named mount and it cannot be written to. | Create a new datastore. For the new datastore, consider selecting the Overwrite option, if appropriate. |
NOT READABLE | The datastore has permissions or network-related issues that prevent reading. |
|
NOT WRITEABLE | The datastore has permissions or network-related issues that prevent writing. |
|
Device name precedence
Discovered devices are automatically named based on multiple sources of network data. When multiple names are found for a device, a default order of precedence is applied. You can change the order of precedence.
- Log in to the ExtraHop system through https://<extrahop-hostname-or-IP-address>.
- Click the System Settings icon and then click All Administration.
- In the System Configuration section, click Device Name Precedence.
- Click and drag device names to create a new order of precedence.
- Click Save.
- (Optional): Click Revert to Default to undo your changes.
Inactive sources
Devices and applications appear in search results until they are inactive for over 90 days. If you want to remove sources from search results before the 90-day expiration, you can remove all sources that have been inactive between 1 and 90 days, on-demand.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the inactive days field, type a value from 1 to 90.
- Click Remove.
Enable detection tracking
Detection tracking enables you to assign a detection to a user, set the status, and add notes. You can track detections directly in the ExtraHop system, with a third-party external ticketing system, or with both methods.
Note: | You must enable ticket tracking on all connected sensors. |
Before you begin
- You must have access to an ExtraHop system with a user account that has Administration privileges.
- After you enable external ticket tracking, you must configure third-party ticket tracking by writing a trigger to create and update tickets on your ticketing system, then enable ticket updates on your ExtraHop system through the REST API.
- If you disable external ticket tracking, previously stored status and assignee ticket information is converted to ExtraHop detection tracking. If detection tracking from within the ExtraHop system is enabled, you will be able to view tickets that already existed when you disabled external ticket tracking, but changes to that external ticket will not appear in the ExtraHop system.
Next steps
If you enabled external ticket tracking integrations, you must continue on to the following task:Configure third-party ticket tracking for detections
Ticket tracking enables you to connect tickets, alarms, or cases in your work-tracking system to ExtraHop detections. Any third-party ticketing system that can accept Open Data Stream (ODS) requests, such as Jira or Salesforce, can be linked to ExtraHop detections.
Before you begin
- You must have selected the third-party detection tracking option in Administration settings.
- You must have access to an ExtraHop system with a user account that has System and Access Administration privileges.
- You must be familiar with writing ExtraHop Triggers. See Triggers and the procedures in Build a trigger.
- You must create an ODS target for your ticket tracking server. See the following topics about configuring ODS targets: HTTP, Kafka, MongoDB, syslog, or raw data.
- You must be familiar with writing REST API scripts and have a valid API key to complete the procedures below. See Generate an API key.
Write a trigger to create and update tickets about detections on your ticketing system
This example shows you how to create a trigger that performs the following actions:
- Create a new ticket in the ticketing system every time a new detection appears on the ExtraHop system.
- Assign new tickets to a user named escalations_team in the ticketing system.
- Run every time a detection is updated on the ExtraHop system.
- Send detection updates over an HTTP Open Data Stream (ODS) to the ticketing system.
The complete example script is available at the end of this topic.
Thank you for your feedback. Can we contact you to ask follow up questions?