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: Reveal(x) 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.
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 |
|
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. The services you are connected to are determined by your system license.
- 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
- Reveal(x) 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 Reveal(x) 360 systems that are connected to self-managed sensors, you must also open access to the ExtraHop Cloud Recordstore.
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) on one of the following IP addresses that corresponds to your sensor license:
- 35.161.154.247 (Portland, U.S.A.)
- 54.66.242.25 (Sydney, Australia)
- 52.59.110.168 (Frankfurt, Germany)
Open access to Cloud Recordstore
For access to the ExtraHop Cloud Recordstore, 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.
- Type the hostname for your proxy server, such as proxyhost.
- Type the port for your proxy server, such as 8080.
- (Optional): If required, 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 SSL/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. |
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.
- Netskope Settings
-
- Enable Netskope packet ingest on your sensor to discover and monitor devices through a Netskope integration.
Configure an interface
Set a static route
Before you begin
You must disable DHCPv4 before you can add a static route.- On the Edit Interface 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.
Note: | Only one global proxy server can be configured per ExtraHop system. |
Complete the following fields and click Save to enable a global proxy.
Hostname : The hostname or IP address for your global proxy server.
Port : The port number for your global proxy server.
Username : The name of a user that has privileged access to your global proxy server.
Password : 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.
- In the Network Settings section, click Connectivity.
- In the Bond Interfaces section, click the red X next to the interface you want to destroy.
- On the Destroy Bond Interface <interface number> page, select the member interface to move the bond interface settings to. Only the member interface selected to retain the bond interface settings remains active, and all other member interfaces are disabled.
- Click Destroy.
Netskope settings
This integration enables you to configure ExtraHop sensors to ingest packets from your Netskope solution to detect threats, discover and monitor devices, and gain insight into traffic.
Before you begin
Important: | The Reveal(x) integration with Netskope Intelligent Security Service Edge (SSE) is currently only available to Netskope Cloud TAP Early Access Program participants. If you would like to learn more about this integration and be notified as soon as it is publicly available, reach out to your ExtraHop account team. |
- Your user account must have full write privileges or higher on Reveal(x) Enterprise or System and Access Administration privileges on Reveal(x) 360.
- Your Reveal(x) system must be connected to an ExtraHop sensor with firmware version 9.4 or later.
- Your ExtraHop sensor must be dedicated to ingesting Netskope packets only.
- You must configure at least one interface on your ExtraHop sensor; all interfaces must specify a mode that includes GENEVE encapsulation.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- From the Network Settings section, click Connectivity.
- From the Netskope Settings section, select Enable Netskope packet ingest.
- Click Save.
Next steps
- From the Assets page, you can search for this sensor to view traffic and detections observed from the Netskope data.
- Log into Administration settings on the connected Reveal(x) Enterprise or Reveal(x) 360 console to check the status of sensors integrated with Netskope.
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 Reveal(x) 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 Reveal(x) 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.
- Type a name to identify this flow network in the Flow Network ID field.
- 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 menu:
- 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.SSL Certificate
SSL 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 SSL certificate, the web server service is restarted. Tunneled connections from ExtraHop sensors to ExtraHop consoles are lost but then re-established automatically. |
Upload an SSL 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. |
- In the Network Settings section, click SSL 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.
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 SSL certificate. The CSR is generated on the ExtraHop system where the SSL 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 SSL certificate from the CA, return to the SSL 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 SSL/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): The ExtraHop system ships with a set of built-in certificates. Select Trust System Certificates if you want to trust these certificates, and then click Save.
- To add your own certificate, click Add Certificate and then paste the contents of the PEM-encoded certificate chain into the Certificate field
- Type a name into the Name field and 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.
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.
- 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, or packet slices only.
These privileges determine the level of functionality users have within the modules where they have been granted access.
For Reveal(x) Enterprise, users with system access and administration privileges can access all features, packets, and session keys for their licensed modules.
For Reveal(x) 360, system access and administration privileges, access to licensed modules, packets, and session keys must be assigned separately. Reveal(x) 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 (Reveal(x) 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 |
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 |
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 and threat briefings. NPM module license and access required to create and modify notifications for performance detections. |
||||||
Create and modify detection 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 (Reveal(x) only) | 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. | ||||||
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 SSL 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, SSL 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, SSL 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 SSL 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.
Enable SAML on the ExtraHop system
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Access Settings section, click Remote Authentication.
- From the Remote authentication method drop-down list, select SAML.
- Click Continue.
- Click View SP Metadata. You will need to copy the ACS URL and Entity ID to paste into the Okta configuration in the next procedure.
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.
Enable SAML on the ExtraHop system
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Access Settings section, click Remote Authentication.
- From the Remote authentication method drop-down list, select SAML.
- Click Continue.
- Click View SP Metadata.
- Copy the ACS URL and Entity ID to a text file. You will paste this information into the Google configuration in a later procedure.
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): Type a description in the Description field.
-
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 with the following information.
- 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.
- 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 dropdown, 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, enter 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
- SSL
On Reveal(x) 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 |
CIFS | CIFS | TCP | 0 | 139, 445 |
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 |
SMPP | SMPP | TCP | 0 | 2775 |
SMTP | SMTP | TCP | 0 | 25 |
SNMP | SNMP | UDP | 0 | 162 |
SSH | SSH | TCP | 0 | 0 |
SSL | SSL | TCP | 0 | 443 |
Sybase | Sybase | TCP | 0 | 10200 |
SybaseIQ | SybaseIQ | TCP | 0 | 2638 |
Syslog | Syslog | UDP | 0 | 514 |
Telnet | Telnet | TCP | 0 | 23 |
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.
SSL decryption
The ExtraHop system supports real-time decryption of SSL traffic for analysis. Before the system can decrypt your traffic, you must configure session key forwarding or upload an SSL 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 SSL 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 SSL traffic by uploading a certificate and private key.
Note: | SSL decryption requires a license. However, if you have a license for MS SQL, you can also upload an SSL 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 |
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 |
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.
- 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, clear the Require Private Keys checkbox.
- In the Global Protocol to Port Mapping section, click Add Global Protocol.
- From the Protocol drop-down list, select the protocol for the traffic that you want to decrypt.
- In the Port field, type the number of the port. Type 0 to add all ports.
- Click Add.
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 SSL/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 SSL/TLS traffic that you want to decrypt.
Before you begin- Read about SSL/TLS decryption and review the list of supported cipher suites.
- Make sure that the ExtraHop system is licensed for SSL Decryption and SSL Shared Secrets.
- Make sure that your server environment is supported by the ExtraHop session key
forwarder software:
- Microsoft Secure Channel (Schannel) security package
- Java SSL/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 SSL 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 SSL-based services with the native Windows SSL framework. OpenSSL on Windows is not currently supported.
Important: | After you install the session key forwarder software, applications that
include SSL-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 SSL 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.
Add a global port to protocol mapping
Add each protocol for the traffic that you want to decrypt with your session key forwarders.
- 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, clear the Require Private Keys checkbox.
- In the Global Protocol to Port Mapping section, click Add Global Protocol.
- From the Protocol drop-down list, select the protocol for the traffic that you want to decrypt.
- In the Port field, type the number of the port. Type 0 to add all ports.
- Click Add.
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 SSL 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 SSL 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 SSL 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 SSL Decryption and SSL 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 SSL 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 SSL 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 SSL 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 SSL 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 SSL certificate of the sensor, then the forwarder must be configured with the correct CN. This parameter is optional. We recommend that you regenerate the SSL self-signed certificate based on the hostname from the SSL 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 SSL/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 SSL/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 SSL/TLS traffic that you want to decrypt.
Before you begin- Read about SSL/TLS decryption and review the list of supported cipher suites.
- Make sure that the ExtraHop system is licensed for SSL Decryption and SSL Shared Secrets.
- Make sure that your server environment is supported by the ExtraHop session key
forwarder software:
- Microsoft Secure Channel (Schannel) security package
- Java SSL/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 SSL 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 SSL 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.
Add a global port to protocol mapping
Add each protocol for the traffic that you want to decrypt with your session key forwarders.
- 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, clear the Require Private Keys checkbox.
- In the Global Protocol to Port Mapping section, click Add Global Protocol.
- From the Protocol drop-down list, select the protocol for the traffic that you want to decrypt.
- In the Port field, type the number of the port. Type 0 to add all ports.
- Click Add.
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 SSL 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 SSL 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 SSL 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 SSL 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 SSL Decryption and SSL 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 SSL certificate presented by the sensor does not include an IP address as a Subject Alternate Name (SAN). | Select from the following three solutions.
|
|
||
|
Supported SSL/TLS cipher suites
The ExtraHop system can decrypt SSL/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 SSL/TLS cipher suites
The ExtraHop system can decrypt SSL/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 SSL 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 SSL 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 a domain controller. 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 Reveal(x) 360.
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.
- Only one domain controller can be configured on a sensor, which means you can decrypt the traffic from one domain per sensor.
- 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.Connect a domain controller to a Reveal(x) 360 sensor
Before you begin
Your user account must have privileges on Reveal(x) 360 for System and Access Administration.Validate the configuration settings
To validate that the ExtraHop system is able to decrypt traffic with the domain controller, create a dashboard that identifies successful decryption attempts.
- Create a new dashboard.
- Click the chart widget to add the metric source.
- Click Add Source.
- In the Sources field, type the name of the sensor communicating with a domain controller and then select the sensor from the list.
- In the Metrics field, type DC in the search field and then select DC-Assisted Decryption Health - Successful Kerberos Decryption Attempts by SPN.
- Click Save.
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
- 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 Network Overlay Decapsulation.
- In the Settings section, select the Enabled checkbox next to GENEVE. The default destination port is 6081.
- Click Save.
- Click OK.
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 CIFS (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 CIFS or NFS datastore.Configure an extended CIFS 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 CIFS 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 Extended Datastore Settings section, click Configure Extended Datastore.
-
Click Add Kerberos Config, then complete the
following information.
- 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 and Customizations.
- 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 and Customizations.
- 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 and then 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, click Datastore and Customizations.
- 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 and Customizations.
- 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. The following table provides guidance on each entry and identifies any applicable action.
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.
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.
- Type a value from 1 to 90 in the inactive days field.
- 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.
const summary = "ExtraHop Detection: " + Detection.id + ": " + Detection.title; const description = "ExtraHop has detected the following event on your network: " + Detection.description const payload = { "fields": { "summary": summary, "assignee": { "name": "escalations_team" }, "reporter": { "name": "ExtraHop" }, "priority": { "id": Detection.riskScore }, "labels": Detection.categories, "mitreCategories": Detection.mitreCategories, "description": description } }; const req = { 'path': '/rest/api/issue', 'headers': { 'Content-Type': 'application/json' }, 'payload': JSON.stringify(payload) }; Remote.HTTP('ticket-server').post(req);
Send ticket information to detections through the REST API
After you have configured a trigger to create tickets for detections in your ticket tracking system, you can update ticket information on your ExtraHop system through the REST API.
Ticket information appears in detections on the Detections page in the ExtraHop system. For more information, see the Detections topic.
The following example Python script takes ticket information from a Python array and updates the associated detections on the ExtraHop system.
#!/usr/bin/python3 import json import requests import csv API_KEY = '123456789abcdefghijklmnop' HOST = 'https://extrahop.example.com/' # Method that updates detections on an ExtraHop system def updateDetection(detection): url = HOST + 'api/v1/detections/' + detection['detection_id'] del detection['detection_id'] data = json.dumps(detection) headers = {'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': 'ExtraHop apikey=%s' % API_KEY} r = requests.patch(url, data=data, headers=headers) print(r.status_code) print(r.text) # Array of detection information detections = [ { "detection_id": "1", "ticket_id": "TK-16982", "status": "new", "assignee": "sally", "resolution": None, }, { "detection_id": "2", "ticket_id": "TK-2078", "status": None, "assignee": "jim", "resolution": None, }, { "detection_id": "3", "ticket_id": "TK-3452", "status": None, "assignee": "alex", "resolution": None, } ] for detection in detections: updateDetection(detection)
Note: | If the script returns an error message that the SSL
certificate verification failed, make sure that a trusted certificate has
been added to your sensor or console. Alternatively, you can add the
verify=False option to bypass certificate verification. However, this
method is not secure and not recommended. The following code sends an HTTP GET request
without certificate
verification:requests.get(url, headers=headers, verify=False) |
- Status
- The status of the ticket associated with the detection. Ticket tracking
supports the following statuses:
- New
- In Progress
- Closed
- Closed with Action Taken
- Closed with No Action Taken
- Ticket ID
- The ID of the ticket in your work-tracking system that is associated with the detection. If you have configured a template URL, you can click the ticket ID to open the ticket in your work-tracking system.
- Assignee
- The username assigned to the ticket associated with the detection. Usernames in gray indicate a non-ExtraHop account.
Configure endpoint lookup links
Endpoint lookup enables you to specify external IP address tools that are available for retrieving up information about endpoints within the ExtraHop system. For example, when you click or hover over an IP address, lookup tool links are displayed so that you can easily find information about that endpoint.
- ARIN Whois Lookup
- VirusTotal Lookup
Geomap Data Source
Geographic locations mapped in the product and triggers reference a GeoIP database to identify the approximate location of an IP address.
Change the GeoIP database
You can upload your own GeoIP database to the ExtraHop system to ensure that you have the latest version of the database or if your database contains internal IP addresses that only you or your company know the location of.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Geomap Data Source.
- Click GeoIP Database.
- In the City-level Database section, select Upload New Database.
- Click Choose File and navigate to the new city-level database file on your computer.
- Click Save.
Override an IP location
You can override missing or incorrect IP addresses that are in the GeoIP database. You can enter a comma-delimited list or tabbed list of overrides into the text box.
- IP address (a single IP address or CIDR notation)
- Latitude
- Longitude
- City
- State or region
- Country name
- ISO alpha-2 country code
You can edit and delete items as necessary, but you must ensure that there is data present for each of the seven columns. For more information about ISO country codes, refer to https://www.iso.org/obp/ui/#search and click Country Codes.
Open Data Streams
By configuring an open data stream, you can send the data collected by your ExtraHop system to an external third-party system, such as syslog systems, MongoDB databases, HTTP servers, Kafka servers. In addition, you can send raw data to any external server by configuring the target with port and protocol specifications.
You can configure up to 16 open data stream targets of each external system type.
Important: | After you configure an open data stream (ODS) for an external system, you
must create a trigger that specifies what data to manage through the stream. Similarly, if you delete an open data stream, you should also delete the associated trigger to avoid needlessly consuming system resources. For more information, see Open data stream classes in the ExtraHop Trigger API Reference. |
Configure an HTTP target for an open data stream
You can export data on an ExtraHop system to a remote HTTP server for long-term archiving and comparison with other sources.
Next steps
Create a trigger that specifies what HTTP message data to send and initiates the transmission of data to the target. For more information, see the Remote.HTTP class in the ExtraHop Trigger API Reference.Configure a Kafka target for an open data stream
You can export data on an ExtraHop system to any Kafka server for long-term archiving and comparison with other sources.
Next steps
Create a trigger that specifies what Kafka message data to send and initiates the transmission of data to the target. For more information, see the Remote.Kafka class in the ExtraHop Trigger API Reference.Configure a MongoDB target for an open data stream
You can export data on an ExtraHop system to a system that receives MongoDB input for long-term archiving and comparison with other sources.
Important: | The system must be running MongoDB 6.0 or earlier to receive exported data. |
Next steps
Create a trigger that specifies what MongoDB message data to send and initiates the transmission of data to the target. For more information, see the Remote.MongoDB class in the ExtraHop Trigger API Reference.Configure a raw data target for an open data stream
You can export raw data on an ExtraHop system to any server for long-term archiving and comparison with other sources. In addition, you can select an option to compress the data through GZIP.
Next steps
Create a trigger that specifies what raw message data to send and initiates the transmission of data to the target. For more information, see the Remote.Raw class in the ExtraHop Trigger API Reference.Configure a syslog target for an open data stream
You can export data on an ExtraHop system to any system that receives syslog input (such as Splunk, ArcSight, or Q1 Labs) for long-term archiving and comparison with other sources.
Next steps
Create a trigger that specifies what syslog message data to send and initiates the transmission of data to the target. For more information, see the Remote.Syslog class in the ExtraHop Trigger API Reference.ODS Details
The Open Data Stream (ODS) details page provides information about the amount of data that has been sent to the ODS target and how many errors have occurred.
Note: | The ODS Details page is currently available only for HTTP ODS targets. |
- Connection attempts
- The number of times the ExtraHop system attempted to connect to the ODS target.
- Connection errors
- The number of errors that occurred during attempts to connect to the ODS target.
- IPC errors
- The number of errors that occurred during data transfer between triggers and the exremote process. If IPC errors occur, contact ExtraHop Support for help.
- Bytes sent to target
- The number of bytes that were forwarded by the exremote process to the ODS target.
- Messages sent to target
- The number of messages that were forwarded by the exremote process to the ODS target.
- Bytes sent from triggers
- The number of bytes that triggers sent to the exremote process to be forwarded to the ODS target.
- Messages sent from triggers
- The number of messages that triggers sent to the exremote process to be forwarded to the ODS target.
- Messages dropped by exremote
- The number of messages that triggers sent to the exremote process but were never forwarded to the ODS target.
- Error Details
-
- Time
- The time that the error occurred.
- URL
- The URL of the ODS target.
- Status
- The HTTP status code returned by the ODS target.
- Request Headers
- The headers of the HTTP request sent to the ODS target.
- Request Body
- The body of the HTTP request sent to the ODS target.
- Response Headers
- The headers of the HTTP response sent by the ODS target.
- Response Body
- The body of the HTTP response sent by the ODS target.
Trends
Trend-based alerts are generated when a monitored metric deviates from the normal trends observed by the ExtraHop system. If needed, you can delete all configured trends and trend-based alerts.
- Click Reset Trends to erase all trend data from the ExtraHop system.
Back up and restore a sensor or console
After you have configured your ExtraHop console and sensor with customizations such as bundles, triggers, and dashboards or administrative changes such as adding new users, ExtraHop recommends that you periodically back up your settings to make it easier to recover from a system failure.
Back up a sensor or console
Create a system backup and store the backup file to a secure location.
Important: | System backups contain sensitive information, including SSL keys. When you create a system backup, make sure you store the backup file to a secure location. |
- User customizations such as bundles, triggers, and dashboards.
- Configurations made from Administration settings, such as locally-created users and remote imported user groups, running configuration file settings, SSL certificates, and connections to ExtraHop recordstores and packetstores.
- License information for the system. If you are restoring settings to a new target, you must manually license the new target.
- Precision packet captures. You can download saved packet captures manually by following the steps in View and download packet captures.
- When restoring a virtual console that has a tunneled connection from a sensor, the tunnel must be reestablished after the restore is complete and any customizations on the console for that sensor must be manually recreated.
- User-uploaded SSL keys for traffic decryption.
- Secure keystore data, which contains passwords. If you are restoring a
backup file to the same target that created the backup, and the keystore is intact, you
do not need to re-enter credentials. However, if you are restoring a backup file to a
new target or migrating to a new target, you must re-enter the following credentials:
- Any SNMP community strings provided for SNMP polling of flow networks.
- Any bind password provided to connect with LDAP for remote authentication purposes.
- Any password provided to connect to an SMTP server where SMTP authentication is required.
- Any password provided to connect to an external datastore.
- Any password provided to access external resources through the configured global proxy.
- Any password provided to access ExtraHop Cloud Services through the configured ExtraHop cloud proxy.
- Any authentication credentials or keys provided to configure Open Data Stream targets.
Restore a sensor or console from a system backup
You can restore the ExtraHop system from the user-saved or automatic backups stored on the system. You can perform two types of restore operations: only customizations (changes to alerts, dashboards, triggers, custom metrics, for example) or both customizations and system resources.
Before you begin
The target must be running the same firmware version, matching the first and second digits of the firmware that generated the backup file. If the versions are not the same, the restore operation will fail.Restore a sensor or console from a backup file
Transfer settings to a new sensor or console
This procedure describes the steps required to restore a backup file to a new console or sensor. Only system settings from your existing console or sensor are transferred. Metrics on the local datastore are not transferred.
Before you begin
- Create a system backup and save the backup file to a secure location.
- Power off the source sensor or console to remove
it from the network before transferring settings. The target and source cannot
be active on the network at the same time.
Important: Do not disconnect any sensors that are already connected to a console. -
Deploy and register the target
sensor or console.
- Ensure that the target is the same type of sensor or console (physical or virtual) as the source.
- Ensure that the target is the same size or larger (maximum throughput on the sensor; CPU, RAM, and disk capacity on the console) as the source.
- Ensure that the target has a firmware version that matches the firmware version that generated the backup file. If the first two digits of the firmware versions are not the same, the restore operation will fail.
- After transferring settings to a target console, you must manually reconnect all sensors.
- When transferring settings to a target console that is configured for a tunneled connection to the sensors, we recommend that you configure the target console with the same hostname and IP address as the source console.
Reconnect sensors to the console
Before you begin
Important: | If your console and sensors are configured for a tunneled connection, we recommend that you configure the source and target consoles with the same IP address and hostname. If you cannot set the same IP address and hostname, skip this procedure and create a new tunneled connection to the new IP address or hostname of the console. |
Appliance Settings
You can configure the following components of the ExtraHop appliance in the Appliance Settings section.
All appliances have the following components:
- Running Config
- Download and modify the running configuration file.
- Services
- Enable or disable the Web Shell, management GUI, SNMP service, SSH access, and SSL session key receiver. The SSL Session Key Receiver option appears only on packet sensors.
- Firmware
- Upgrade the ExtraHop system firmware.
- System Time
- Configure the system time.
- Shutdown or Restart
- Halt and restart system services.
- License
- Update the license to enable add-on modules.
- Disks
- Provides information about the disks in the appliance.
The following components only appear on the specified appliances:
- Command Nickname
- Assign a nickname to the console. This setting is available only on the console.
- Reset Packetstore
- Delete all packets stored on ExtraHop packetstores. The Reset Packetstore page appears only on packetstores.
Running Config
The running configuration file specifies the default system configuration. When you modify system settings, you must save the running configuration file to preserve those modifications after a system restart.
Note: | Making configuration changes to the code from the Edit page is not recommended. You can make most system modifications through other pages in the Administration settings. |
Save system settings to the running configuration file
When you modify any of the system configuration settings on an ExtraHop system, you must confirm the updates by saving the running configuration file. If you do not save the settings, the changes are lost when your ExtraHop system restarts.
- Click View and Save Changes.
-
Review the comparison between the old running configuration and the current
(unsaved) running configuration, and then select from the following
options:
- If the changes are correct, click Save.
- If the changes are not correct, click Cancel and then revert the changes by clicking Revert config.
Edit the running config
The ExtraHop Administration settings provide an interface to view and modify the code that specifies the default system configuration. In addition to making changes to the running configuration file through the Administration settings, changes can also be made on the Running Config page.
Note: | Making configuration changes to the code from the Edit page is not recommended. You can make most system modifications through other Administration settings. |
Download the running configuration as a text file
You can download the running configuration file to your workstation. You can open this text file and make changes to it locally, before copying those changes into the Running Config window.
- Click Running Config.
- Click Download config as a File.
Disable ICMPv6 Destination Unreachable messages
You can prevent the ExtraHop system from generating ICMPv6 Destination Unreachable messages. You might want to disable ICMPv6 Destination Unreachable messages for security reasons per RFC 4443.
To disable ICMPv6 Destination Unreachable messages, you must edit the Running Configuration. However, we recommend that you do not manually edit the Running Configuration file without direction from ExtraHop Support. Manually editing the running config file incorrectly might cause the system to become unavailable or stop collecting data. You can contact ExtraHop Support.
Disable specific ICMPv6 Echo Reply messages
You can prevent the ExtraHop system from generating Echo Reply messages in response to ICMPv6 Echo Request messages that are sent to an IPv6 multicast or anycast address. You might want to disable these messages to reduce unnecessary network traffic.
To disable specific ICMPv6 Echo Reply messages, you must edit the running configuration file. However, we recommend that you do not manually edit the running configuration file without direction from ExtraHop Support. Manually editing this file incorrectly might cause the system to become unavailable or stop collecting data. You can contact ExtraHop Support.
Services
These services run in the background and perform functions that do not require user input. These services can be started and stopped through the Administration settings.
- Enable or disable the Management GUI
- The Management GUI provides browser-based access to the ExtraHop system. By default, this
service is enabled so that ExtraHop users can access the ExtraHop system through a web
browser. If this service is disabled, the Apache Web Server session is terminated and all
browser-based access is disabled.
Warning: Do not disable this service unless you are an experienced ExtraHop administrator and you are familiar with the ExtraHop CLI. - Enable or disable the SNMP Service
- Enable the SNMP service on the ExtraHop system when you want your network device monitoring
software to collect information about the ExtraHop system. This service is disabled by
default.
- Enable the SNMP service from the Services page by selecting the Disabled checkbox and then clicking Save. After the page refreshes, the Enabled checkbox appears.
- Configure the SNMP service and download the ExtraHop MIB file
- Enable or disable SSH Access
- SSH access is enabled by default to enable users to securely log in to the ExtraHop
command-line interface (CLI).
Note: The SSH Service and the Management GUI Service cannot be disabled at the same time. At least one of these services must be enabled to provide access to the system. - Enable or disable the SSL Session Key Receiver (Sensor only)
- You must enable the session key receiver service through the Administration settings before
the ExtraHop system can receive and decrypt session keys from the session key forwarder. By
default, this service is disabled.
Note: If you do not see this checkbox and have purchased the SSL Decryption license, contact ExtraHop Support to update your license.
SNMP Service
Configure the SNMP service on your ExtraHop system so that you can configure your network device monitoring software to collect information about your ExtraHop system through the Simple Network Management Protocol (SNMP).
For example, you can configure your monitoring software to determine how much free space is available on an ExtraHop system and send an alert if the system is over 95% full. Import the ExtraHop SNMP MIB file into your monitoring software to monitor all ExtraHop-specific SNMP objects. You can configure settings for SNMPv1/SNMPv2 and SNMPv3
Configure the SNMPv1 and SNMPv2 service
The following configuration enables you to monitor the system with an SNMP manager that supports SNMPv1 and SNMPv2.
Next steps
Download the ExtraHop SNMP MIB file from the SNMP Service Configuration page.Configure the SNMPv3 service
The following configuration enables you to monitor the system with an SNMP manager that supports SNMPv3. The SNMPv3 security model provides additional support for authentication and privacy protocols.
Next steps
Download the ExtraHop SNMP MIB file from the SNMP Service Configuration page.Firmware
The Administration settings provide an interface to upload and delete the firmware on ExtraHop appliances. The firmware file must be accessible from the computer where you will perform the upgrade.
Before you begin
Be sure to read the release notes for the firmware version that you want to install. Release notes contain upgrade guidance as well as known issues that might affect critical workflows in your organization.Upgrade the firmware on your ExtraHop system
The following procedure shows you how to upgrade your ExtraHop system to the latest firmware release. While the firmware upgrade process is similar across all ExtraHop appliances, some appliances have additional considerations or steps that you must address before you install the firmware in your environment. If you need assistance with your upgrade, contact ExtraHop Support.
Video: | See the related training: Update Firmware |
Important: | When settings migration fails during firmware upgrade, the previously installed firmware version and ExtraHop system settings are restored. |
Pre-upgrade checklist
Here are some important considerations and requirements about upgrading ExtraHop appliances.
- A system notice appears on consoles and sensors connected to ExtraHop Cloud Services when a new firmware version is available.
- Verify that your Reveal(x) 360 system has been upgraded to version 9.6 before upgrading your self-managed sensors.
- If you are upgrading from firmware version 8.7 or earlier, contact ExtraHop Support for additional upgrade guidance.
- If you are upgrading a virtual ExtraHop sensor deployed on a VMware ESXi/ESX, Microsoft Hyper-V, or Linux KVM platform from firmware version 9.1 or earlier, the VM must support Streaming SIMD Extensions 4.2 (SSE4.2) and POPCNT instruction; otherwise, the system will become unstable.
- If you have multiple types of ExtraHop appliances, you must upgrade them in the
following order:
- Console
- Sensors (EDA and Ultra)
- Recordstores
- Packetstores
Note: | Your browser might time out after 5 minutes of inactivity. Refresh the browser page if
the update appears incomplete. If the browser session times out before the ExtraHop system is able to complete the update process, you can try the following connectivity tests to confirm the status up the upgrade process:
|
Console upgrades
- For large console deployments (managing 50,000 devices or more), reserve a minimum of one hour to perform the upgrade.
- The console firmware version must be greater than or equal to the firmware version of all connected appliances. To ensure feature compatibility, all connected appliances should be running firmware version 8.7 or later.
Recordstore upgrades
- Do not upgrade recordstores to a firmware version that is newer than the version installed on connected consoles and sensors.
- After upgrading the console and sensors, disable record ingest on the recordstore before upgrading the recordstore.
- You must upgrade all recordstore nodes in a recordstore cluster. The cluster will not
function correctly if nodes are on dissimilar firmware versions.
Important: The messages Could not determine ingest status on some nodes and Error appear on the Cluster Data Management page in the Administration settings of the upgraded nodes until all nodes in the cluster are upgraded. These errors are expected and can be ignored. - You must enable record ingest and shard reallocation from the Cluster Data Management page after all nodes in the recordstore cluster are upgraded.
Upgrade the firmware on a console and sensor
Upgrade the firmware on recordstores
Next steps
After all nodes in the recordstore cluster are upgraded, re-enable record ingest and shard reallocation on the cluster. You only need to perform these steps on one recordstore node.- In the Recordstore Cluster Settings section, click Cluster Data Management.
- Click Enable Record Ingest.
- Click Enable Shard Reallocation.
Upgrade connected sensors in Reveal(x) 360
Administrators can upgrade sensors that are connected to Reveal(x) 360.
Before you begin
- Your user account must have privileges on Reveal(x) 360 for System and Access Administration or System Administration.
- Sensors must be connected to ExtraHop Cloud Services
- Notifications appear when a new firmware version is available
- You can upgrade multiple sensors at the same time
System Time
The System Time page displays the current time settings configured for your ExtraHop system. View the current system time settings, the default display time for users, and details for configured NTP servers.
System time is the time and date tracked by services running on the ExtraHop system to ensure accurate time calculations. By default, the system time on the sensor or console is configured locally. For better accuracy, we recommend that you configure the system time through an NTP time server.
When capturing data, the system time must match the time on connected sensors to ensure that time stamps are correct and complete in scheduled reports, exported dashboards and chart metrics. If time sync issues occur, check that the configured system time, external time servers, or NTP servers are accurate. Reset the system time or sync NTP servers if needed
The table below contains details about the current system time configuration. Click Configure Time to configure system time settings.
Detail | Description |
---|---|
Time Zone | Displays the currently selected time zone. |
System Time | Displays the current system time. |
Time Servers | Displays a comma-separated list of configured time servers. |
Default display time for users
The Default Display Time for Users section shows the time displayed to all users in the ExtraHop system unless a user manually changes their displayed time zone.
To modify the default display time, select one of the following options and then click Save Changes:
- Browser time
- System time
- UTC
NTP Status
The NTP Status table displays the current configuration and status of all NTP servers that keep the system clock in sync. The table below contains details about each configured NTP server. Click Sync Now to sync the current system time to a remote server.
remote | The host name or IP address of the remote NTP server you have configured to synchronize with. |
st | The stratum level, 0 through 16. |
t | The type of connection. This value can be u for unicast or manycast, b for broadcast or multicast, l for local reference clock, s for symmetric peer, A for a manycast server, B for a broadcast server, or M for a multicast server. |
when | The last time when the server was queried for the time. The default value is seconds, or m is displayed for minutes, h for hours, and d for days. |
poll | How often the server is queried for the time, with a minimum of 16 seconds to a maximum of 36 hours. |
reach | Value that shows the success and failure rate of communicating with the remote server. Success means the bit is set, failure means the bit is not set. 377 is the highest value. |
delay | The round trip time (RTT) of the ExtraHop appliance communicating with the remote server, in milliseconds. |
offset | Indicates how far off the ExtraHop appliance clock is from the time reported by the server. The value can be positive or negative, displayed in milliseconds. |
jitter | Indicates the difference, in milliseconds, between two samples. |
Configure the system time
By default, the ExtraHop system synchronizes the system time through the *.extrahop.pool.ntp.org network time protocol (NTP) servers. If your network environment prevents the ExtraHop system from communicating with these time servers, you must configure an alternate time server source.
Before you begin
Important: | Always configure more than one NTP server to increase the accuracy and reliability of time kept on the system. |
The NTP Status table displays a list of NTP servers that keep the system clock in sync. To sync the current system time a remote server, click the Sync Now button.
Shutdown or Restart
The Administration settings provides an interface to halt, shutdown, and restart the ExtraHop system and its system components. For each ExtraHop system component, the table includes a time stamp to show the start time.
- Restart or shutdown System to pause or shut down and restart the ExtraHop system.
- Restart Bridge Status (Sensor only) to restart the ExtraHop bridge component.
- Restart Capture (Sensor only) to restart the ExtraHop capture component.
- Restart Portal Status to restart the ExtraHop web portal.
- Restart Scheduled Reports (Console only) to restart the ExtraHop scheduled reports component.
Sensor Migration
You can migrate your stored metrics, customizations and system resources on your existing physical ExtraHop sensor to a new sensor.
Migrate an ExtraHop sensor
When you are ready to upgrade your existing sensor, you can easily migrate to new hardware without losing business critical metrics and time-consuming system configurations.
- License information for the system. If you are restoring settings to a new target, you must manually license the new target.
- Precision packet captures. You can download saved packet captures manually by following the steps in View and download packet captures.
- When restoring a virtual console that has a tunneled connection from a sensor, the tunnel must be reestablished after the restore is complete and any customizations on the console for that sensor must be manually recreated.
- User-uploaded SSL keys for traffic decryption.
- Secure keystore data, which contains passwords. If you are restoring a
backup file to the same target that created the backup, and the keystore is intact, you
do not need to re-enter credentials. However, if you are restoring a backup file to a
new target or migrating to a new target, you must re-enter the following credentials:
- Any SNMP community strings provided for SNMP polling of flow networks.
- Any bind password provided to connect with LDAP for remote authentication purposes.
- Any password provided to connect to an SMTP server where SMTP authentication is required.
- Any password provided to connect to an external datastore.
- Any password provided to access external resources through the configured global proxy.
- Any password provided to access ExtraHop Cloud Services through the configured ExtraHop cloud proxy.
- Any authentication credentials or keys provided to configure Open Data Stream targets.
Before you begin
Important: | If the source sensor has an external datastore and the datastore is configured on a CIFS/SMB server requiring password authentication, contact ExtraHop Support to assist you with your migration. |
- Source and target sensors must be running the same firmware version.
- Migrate only to same-edition sensors, such as Reveal(x). If you need to migrate between editions, contact your ExtraHop sales team for assistance.
- Migration is only supported between physical sensors. Virtual sensor migrations are not supported.
- Supported migration paths are listed in the following tables.
Source | Target | ||||
---|---|---|---|---|---|
EDA 1200 | EDA 6200 | EDA 8200 | EDA 9200 | EDA 10200 | |
EDA 1200 | YES | YES | YES | YES | YES |
EDA 6200 | NO | YES* | YES | YES | YES |
EDA 8200 | NO | NO | YES* | YES* | YES |
EDA 9200 | NO | NO | NO | YES* | YES |
EDA 10200 | NO | NO | NO | NO | YES* |
*Migration is supported only if the source and target sensor were manufactured in May 2019 or later. Contact ExtraHop Support to verify compatibility.
Source | Target | |||
---|---|---|---|---|
EDA 6200 | EDA 8200 | EDA 9200 | EDA 10200 | |
EH3000 | YES | YES | YES | YES |
EH6000 | YES | YES | YES | YES |
EH8000 | NO | YES | YES | YES |
EDA 1100 | YES | YES | YES | YES |
EDA 3100 | YES | YES | YES | YES |
EDA 6100 | YES | YES | YES | YES |
EDA 8100 | NO | YES | YES | YES |
EDA 9100 | NO | NO | YES | YES |
EDA 6200 | YES* | YES | YES | YES |
EDA 8200 | NO | YES* | YES* | YES |
EDA 9200 | NO | NO | YES* | YES |
EDA 10200 | NO | NO | NO | YES* |
* Migration is supported only if the source and target sensor were manufactured in May 2019 or later. Contact ExtraHop Support to verify compatibility.
Prepare the source and target sensors
- Follow the instructions in the deployment guide for your sensor model to deploy the target sensor.
- Register the target sensor.
- Make sure that the target and the source sensor are running the exact same firmware version. You can download current and previous firmware from the ExtraHop Customer Portal.
-
Choose one of the following networking methods to migrate to the target
sensor.
- (Recommended) To complete the migration in the fastest time possible, directly connect the sensors with 10G management interfaces.
-
Create a bond interface (optional) of available 1G
management interfaces. With the appropriate network cables, directly connect
the available port or ports on the source sensor to similar ports on the
target sensor. The figure below shows an example configuration with bonded
1G interfaces.
Important: Make sure that your IP address and subnet configuration on both sensors route management traffic to your management workstation and migration traffic to the direct link. - Migrate the sensor over your existing network. The source and target sensors must be able to communicate with each other over your network. Note that migration might take significantly longer with this configuration.
Create a bond interface (optional)
Follow the instructions below to bond 1G interfaces. Creating a bond interface decreases the amount of time it takes to complete the migration over 1G interfaces.
- In the Network Settings section on the source sensor, click Connectivity.
- In the Bond Interface Settings section, click Create Bond Interface.
- In the Members section, Select the members of the bond interface depending on the sensor type. Do not include the current management interface, typically interface 1 or interface 3, in the bond interface.
- From the Take Settings From drop-down list, select one of the members of the new bond interface.
- For Bond Type, select Static.
- Click Create.
- On the Connectivity page, in the Bond Interfaces section, click Bond Interface 1.
- From the Interface Mode drop-down menu, select Management.
- Type the IPv4 Address, Netmask, and Gateway for your migration network.
- Click Save.
- Repeat this procedure on the target sensor.
Start the migration
Migration can take several hours to complete. During this time, neither the source nor the target sensor can collect data. The migration process cannot be paused or canceled.
Configure the target sensor
If sensor networking is not configured through DHCP, make sure connectivity settings are updated, including any assigned IP addresses, DNS servers, and static routes. Connections to ExtraHop consoles, recordstores, and packetstores on the source sensor are automatically established on the target sensor when network settings are configured.
- Log in to the Administration settings on the target sensor.
- In the Network Settings section, click Connectivity.
- In the Interfaces section, click the management interface (typically interface 1 or interface 3, depending on the sensor model).
- Type the IP address of the source sensor in the IPv4 Address field.
- If static routes were configured on the source sensor, click Edit Routes, add any required route information, and then click Save.
- Click Save to save the interface settings.
- If you had to change any interface settings to perform the migration with bonded interfaces, make sure that the interface modes are configured as you expect them to be.
- Restore any additional settings that are not automatically restored.
License
The License Administration page enables you to view and manage licenses for your ExtraHop system. You must have an active license to access the ExtraHop system, and your system must be able to connect to the ExtraHop licensing server for periodic updates and check-ins about your license status.
To learn more about ExtraHop licenses, see the License FAQ.
Register your ExtraHop system
This guide provides instructions on how to apply a new product key and activate all of your purchased modules. You must have privileges on the ExtraHop system to access the Administration settings.
Register the appliance
Before you begin
Note: | If you are registering a sensor or a console, you can optionally enter the product key after you accept the EULA and log in to the ExtraHop system (https://<extrahop_ip_address>/). |
Next steps
Have more questions about ExtraHop licensing works? See the License FAQ.Troubleshoot license server connectivity
For ExtraHop systems licensed and configured to connect to ExtraHop Cloud Services, registration and verification is performed through an HTTPS request to ExtraHop Cloud Services.
If your ExtraHop system is not licensed for ExtraHop Cloud Services or is not yet licensed, the system attempts to register the system through a DNS TXT request for regions.hopcloud.extrahop.com and an HTTPS request to all ExtraHop Cloud Services regions. If this request fails, the system tries to connect to the ExtraHop licensing server through DNS server port 53. The following procedure is useful to verify that the ExtraHop system can communicate with the licensing server through DNS.
nslookup -type=NS d.extrahop.com
Non-authoritative answer: d.extrahop.com nameserver = ns0.use.d.extrahop.com. d.extrahop.com nameserver = ns0.usw.d.extrahop.com.If the name resolution is not successful, make sure that your DNS server is properly configured to lookup the
Apply an updated license
When you purchase a new protocol module, service, or feature, the updated license is automatically available on the ExtraHop system. However you must apply the updated license to the system through the Administration settings for the new changes to take effect.
Update a license
If ExtraHop Support provides you with a license file, you can install this file on your appliance to update the license.
Note: | If you want to update the product key for your appliance, you must register your ExtraHop system. |
Disks
The Disks page displays a map of the drives on the ExtraHop system and lists their statuses. This information can help you determine whether drives need to be installed or replaced. Automatic system health checks and email notifications (if enabled) can provide timely notice about a disk that is in a degraded state. System health checks display disk errors at the top of the Settings page.
Self-encrypting disks (SEDs)
For sensors that include self-encrypting disks (SEDs), the Hardware Disk Encryption status can be set to Disabled or Enabled. This status set to Unsupported for sensors that do not include SEDs.
These sensors support SEDs:
- EDA 9300
- EDA 10300
- IDS 9380
For information about configuring SEDs, see Configure self-encrypting disks (SEDs).
RAID
For information about configuring and repairing RAID10 functionality on the EDA 6200 sensors, see Upgrade from RAID 0 to RAID 10.
For help replacing a RAID 0 disk or installing an SSD drive, refer to the instructions below. The RAID 0 instructions apply to the following types of disks:
- Datastore
- Packet Capture
- Firmware
Do not attempt to install or replace the drive in Slot 0 unless instructed by ExtraHop Support.
Note: | Ensure that your device has a RAID controller before attempting the following procedure. If unsure, contact ExtraHop Support. A persistently damaged disk might not be replaceable with this procedure. |
Console Nickname
By default, your ExtraHop console is identified by its hostname on connected sensors. However, you can optionally configure a custom name to identify your console.
Choose from the following options to configure the display name:
- Select Display custom nickname and type the name in the field you want to display for this console.
- Select Display hostname to display the hostname configured for this console.
Configure packet capture
Packet capture enables you to collect, store, and retrieve data packets from your network traffic. You can download a packet capture file for analysis in a third-party tool, such as Wireshark. Packets can be inspected to diagnose and resolve network problems and to verify that security policies are being followed.
By adding a packet capture disk to the ExtraHop sensor, you can store the raw payload data sent to your ExtraHop system. This disk can be added to your virtual sensor or an SSD that is installed in your physical sensor.
These instructions only apply to ExtraHop systems that have a precision packet capture disk. To store packets on an ExtraHop packetstore appliance, see the packetstore deployment guides.
Important: | Systems with self-encrypting disks (SEDs) cannot be configured for software encryption on packet captures. For information on enabling security on these systems, see Configure self-encrypting disks (SEDs). |
Packet slicing
By default, the packetstore saves whole packets. If packets are not already sliced, you can configure the sensor to store packets sliced to a fixed number of bytes for improved privacy and lookback.
For more information on configuring this feature in your running configuration file, contact ExtraHop Support.
Enable packet capture
Your ExtraHop system must be licensed for packet capture and configured with a dedicated storage disk. Physical sensors require an SSD storage disk and virtual sensors require a disk configured on your hypervisor.
Before you begin
- Verify that your ExtraHop system is licensed for Packet Capture by logging in to the Administration settings and clicking License. Packet Capture is listed under Features and Enabled should appear.
Important: | The capture process restarts when you enable the packet capture disk. |
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Appliance Settings section, click Disks.
-
Depending on your sensor type and menu options, configure the following
settings.
- For physical sensors click Enable next to SSD Assisted Packet Capture, and then click OK.
- For virtual sensors, verify that running appears in the Status column and that the disk size you configured for packet capture appears in the Size column. Click Enable next to Triggered Packet Capture, and then click OK.
Next steps
Your packet capture disk is now enabled and ready to store packets. Click Configure if you want to encrypt the disk, or configure global or precision packet captures.Encrypt the packet capture disk
Packet capture disks can be secured with 256-bit AES encryption.
- You cannot decrypt a packet capture disk after it is encrypted. You can clear the encryption, but the disk is formatted, and all data is deleted.
- You can lock an encrypted disk to prevent any read or write access to stored packet capture files. If the ExtraHop system is restarted, encrypted disks are automatically locked and remain locked until they are unlocked with the passphrase. Unencrypted disks cannot be locked.
- You can reformat an encrypted disk, but all data is permanently deleted. You can reformat a locked disk without unlocking the disk first.
- You can perform a secure delete (or system wipe) of all system data. For instructions, see the ExtraHop Rescue Media Guide.
Important: | Systems with self-encrypting disks (SEDs) cannot be configured for software encryption on packet captures. For information on enabling security on these systems, see Configure self-encrypting disks (SEDs). |
- In the Appliance Settings section, click Disks.
-
On the Disks page, select one of the following options based on your sensor
type.
- For virtual sensors, click Configure next to Triggered Packet Capture.
- For physical sensors, click Configure next to SSD Assisted Packet Capture.
- Click Encrypt Disk.
-
Specify a disk encryption key from one of the following options:
- Type a passphrase into the Passphrase and Confirm fields.
- Click Choose File and select an encryption key file.
- Click Encrypt.
Next steps
You can change the disk encryption key by returning to the Disks page and clicking Configure and then Change Disk Encryption Key.Format the packet capture disk
You can format an encrypted packet capture disk to permanently remove all packet captures. Formatting an encrypted disk removes the encryption. If you want to format an unencrypted packet capture disk, you must remove the disk, and then enable the disk again.
Warning: | This action cannot be reversed. |
- In the Appliance Settings section, click Disks.
-
On the Disks page, choose one of the following options based on your appliance
platform.
- For virtual sensors, click Configure next to Triggered Packet Capture.
- For physical sensors, click Configure next to SSD Assisted Packet Capture.
- Click Clear Disk Encryption.
- Click Format.
Remove the packet capture disk
If you want to replace a packet capture disk, you must first remove the disk from the system. When a packet capture disk is removed from the system, all of the data on the disk is permanently deleted.
- In the Appliance Settings section, click Disks.
-
On the Disks page, choose one of the following options based on your appliance
platform.
- For virtual appliances, click Configure next to Triggered Packet Capture.
- For physical devices, click Configure next to SSD Assisted Packet Capture.
- Click Remove Disk.
-
Select one of the following format options:
- Quick Format
- Secure Erase
- Click Remove.
Configure a global packet capture
A global packet capture collects every packet that is sent to the ExtraHop system for the duration that matches the criteria.
- On Reveal(x) Enterprise systems, click Packets from the
top menu and then click Download PCAP.
To help locate your packet capture, click and drag on the Packet Query timeline to select the time range when you started the packet capture.
- On ExtraHop Performance systems, click the System Settings icon , click All Administration, and then click View and Download Packet Captures in the Packet Capture section.
Configure a precision packet capture
Precision packet captures require ExtraHop Triggers, which enable you to capture only the packets that meet your specifications. Triggers are highly customizable user-defined code that run upon defined system events.
Before you begin
Packet capture must be licensed and enabled on your ExtraHop system.- Trigger concepts
- Build a trigger
- Trigger API Reference
- Walkthough: Initiate precision packet captures to analyze zero window conditions
In the following example, the trigger captures an HTTP flow with the name HTTP host <hostname> and stops the capture after a maximum of 10 packets are collected.
Next steps
Download the packet capture file.- On Reveal(x) Enterprise systems, click Records from the top menu. Select Packet Capture from the Record Type drop-down list. After the records associated with your packet capture appear, click the Packets icon , and then click Download PCAP.
- On ExtraHop Performance systems, click the System Settings icon , click All Administration, and then click View and Download Packet Captures in the Packet Capture section.
View and download packet captures
If you have packet captures stored on a virtual disk or on an SSD disk in your sensor, you can manage those files from the View Packet Captures page in the Administration settings. For Reveal(x) systems and on ExtraHop packetstores, view the Packets page.
The View and Download Packet Captures section only appears on ExtraHop Performance systems. On Reveal(x) systems, precision packet capture files are found by searching Records for the packet capture record type.
- Click Configure packet capture settings to automatically delete stored packet captures after the specified duration (in minutes).
- View statistics about your packet capture disk.
- Specify criteria to filter packet captures and limit the number of files displayed in the Packet Capture List.
- Select a file from the Packet Capture list and then download or delete the file.
Note: You cannot delete individual packet capture files from Reveal(x) systems.
Recordstore
You can send transaction-level records written by the ExtraHop system to a supported recordstore and then query those records from the Records page or REST API on your console and sensors.
Send records from ExtraHop to Google BigQuery
You can configure your ExtraHop system to send transaction-level records to a Google BigQuery server for long-term storage, and then query those records from the ExtraHop system and the ExtraHop REST API. Records on BigQuery recordstores expire after 90 days.
Before you begin
- Any console and all connected sensors must be running the same ExtraHop firmware version.
- You need the BigQuery project ID
- You need the credential file (JSON) from your BigQuery service account. The service account requires the BigQuery Data Editor, BigQuery Data Viewer, and BigQuery User roles.
- For access to the ExtraHop Cloud Recordstore, 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.
- If you want to configure the BigQuery recordstore settings with Google Cloud
workload identity federation authentication, you need the configuration file from
your workload identity pool.
Note: The workload identity provider must be set up to provide a fully valid OIDC ID Token in response to a Client Credentials request. For more information about workload identity federation, see https://cloud.google.com/iam/docs/workload-identity-federation.
Enable BigQuery as the recordstore
Note: | Any triggers configured to send records through commitRecord to an ExtraHop recordstore are automatically redirected to BigQuery. No further configuration is required. |
Important: | If your ExtraHop system includes a console, configure all appliances with the same recordstore settings or transfer management to manage settings from the console. |
Important: | Do not modify or delete the table in BigQuery where the records are stored. Deleting the table deletes all stored records. |
Transfer recordstore settings
If you have an ExtraHop console connected to your ExtraHop sensors, you can configure and manage the recordstore settings on the sensor, or transfer the management of the settings to the console. Transferring and managing the recordstore settings on the console enables you to keep the recordstore settings up to date across multiple sensors.
Send records from ExtraHop to Splunk
You can configure the ExtraHop system to send transaction-level records to a Splunk server for long-term storage, and then query those records from the ExtraHop system and the ExtraHop REST API.
- Any triggers configured to send records through commitRecord to a recordstore are automatically redirected to the Splunk server. No further configuration is required.
- If you are migrating to Splunk from a connected ExtraHop recordstore, you will no longer be able to access records stored on the recordstore.
- If you want to view and analyze ExtraHop data such as metrics and detections in a Splunk interface, configure a Splunk or Splunk SOAR integration.
Enable Splunk as the recordstore
Important: | If your ExtraHop system includes a console or Reveal(x) 360, configure all sensors with the same recordstore settings or transfer management to manage settings from the console or Reveal(x) 360. |
Before you begin
- Any console and all connected sensors must be running the same ExtraHop firmware version.
- You must have version 7.0.3 or later of Splunk Enterprise and a user account that has administrator privileges.
- You must configure the Splunk HTTP Event Collector before your Splunk server can receive ExtraHop records. See the Splunk HTTP Event Collector documentation for instructions.
Transfer recordstore settings
If you have an ExtraHop console connected to your ExtraHop sensors, you can configure and manage the recordstore settings on the sensor, or transfer the management of the settings to the console. Transferring and managing the recordstore settings on the console enables you to keep the recordstore settings up to date across multiple sensors.
ExtraHop Command Settings
The ExtraHop Command Settings section on the ExtraHop sensor enables you to connect a packet sensor to an ExtraHop console. Depending on your network configuration, you can establish a connection from the sensor (tunneled connection) or from the console (direct connection).
- We recommend that you log in to the Administration settings on your console and create a direct connection to the sensor. Direct connections are made from the console over HTTPS on port 443 and do not require special access. For instructions, see Connect an ExtraHop console to an ExtraHop sensor.
- If your sensor is behind a firewall, you can create an SSH tunnel connection from this sensor to your console. For instructions, see Connect to a console from a sensor.
Generate Token
You must generate a token on a sensor before you can connect to a console. The token ensures a secure connection, making the connection process less susceptible to machine-in-the-middle (MITM) attacks.
Click Generate Token and then complete the configuration on your console.
Connect to a console from a sensor
You can connect the ExtraHop sensor to the console through an SSH tunnel.
Before you begin
- You can only establish a connection to a sensor that is licensed for the same system edition as the console. For example, a console on Reveal(x) Enterprise can only connect to sensors on Reveal(x) Enterprise.
Connect an ExtraHop console to an ExtraHop sensor
You can manage multiple ExtraHop sensors from a console. After you connect the sensors, you can view and edit the sensor properties, assign a nickname, upgrade firmware, check the license status, and create a diagnostic support package.
Video: | See the related training: Connect an Appliance to a Reveal(x) Enterprise Console (ECA) |
Before you begin
You can only establish a connection to a sensor that is licensed for the same system edition as the console. For example, a console on Reveal(x) Enterprise can only connect to sensors on Reveal(x) Enterprise.Important: | We strongly recommend configuring a unique hostname. If the system IP address changes, the ExtraHop console can re-establish connection easily to the system by hostname. |
Generate a token on the sensor
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the ExtraHop Command Settings section, click Generate Token.
- Click Generate Token.
- Copy the token and continue to the next procedure.
Manage packet sensors
From the ExtraHop console, you can view connected sensors and manage some administrative tasks.
Select the checkbox for one or more connected sensors. Then, select from the following administrative tasks.
- Click Check License to connect to the ExtraHop licensing server and retrieve the latest status for the selected sensors. If your Command appliance is unable to access data from a connected sensor, the license might be invalid.
- Click Run Support Script and then select from the following
options:
- Click Run Default Support Script to collect information about the selected sensors. You can send this diagnostics file to ExtraHop Support for analysis.
- Click Run Custom Support Script to upload a file from ExtraHop Support that provides small system changes or enhancements.
- Click Upgrade Firmware to upgrade the selected sensor. You can enter a URL to the firmware on the Customer Portal website or upload the firmware file from your computer. With either option, we strongly recommend you read the firmware release notes and the firmware upgrade guide.
- Click Disable or Enable to temporarily alter the connection between sensors and consoles. When this connection is disabled, the Command appliance does not display the sensor and cannot access the sensor data.
- Click Remove Appliance to permanently disconnect selected sensors.
ExtraHop Recordstore Settings
This section contains the following configuration settings for the ExtraHop recordstore.
- Configure automatic flow records (Sensors only)
- Connect to an ExtraHop recordstore
- Manage an ExtraHop recordstore (Console only)
Connect the console and sensors to ExtraHop recordstores
After you deploy an ExtraHop recordstore, you must establish a connection from all ExtraHop sensors and the console to the recordstore nodes before you can query for stored records.
Important: | If your recordstore cluster is configured with manager-only nodes, you only need to connect the sensors and console to the data-only nodes in the recordstore cluster. Do not connect to the manager-only nodes since manager-only nodes do not receive records. |
Next steps
If the recordstore settings are managed by sensors and not by a connected console, repeat this procedure on the console.Manage recordstores
From the ExtraHop console, you can view connected recordstores and manage some administrative tasks.
View information about connected recordstores as individual appliances or as part of a cluster.
- Click Explore Cluster in the Name field to open the Cluster Properties. You can add a custom nickname for the recordstore and view the Cluster ID.
- Click any node name to open the node properties. By clicking Open Admin UI, you can access the Administration settings for the specific recordstore.
- View the date and time that the appliance was added to this console.
- View the license status for your appliances.
- View the list of actions that you can perform on this appliance.
- View the Job column to see the status of any running support scripts.
Select the recordstore cluster or a single node in the cluster by clicking an empty area in the table, and then select from the following administrative tasks.
- Click Run Support Script and then select from the following
options:
- Select Run Default Support Script to collect information about the selected recordstore. You can send this diagnostics file to ExtraHop Support for analysis.
- Select Run Custom Support Script to upload a file from ExtraHop Support that provides small system changes or enhancements.
- Click Remove Cluster to permanently disconnect the selected recordstore. This option only prevents you from performing the administrative tasks on this page from the console. The recordstore remains connected to your packet sensor and continues to collect records.
Collect flow records
You can automatically collect and store all flow records, which are network-layer communications between two devices over an IP protocol. If you enable this setting, but do not add any IP addresses or port ranges, all detected flow records are captured. Configuring flow records for automatic collection is fairly straight-forward and can be a good way to test connectivity to your recordstore.
Before you begin
You must have access to an ExtraHop system with System and Access Administration privileges.ExtraHop Recordstore Status
If you have connected an ExtraHop recordstore to your sensor or console, you can access information about the recordstore.
The table on this page provides the following information about any connected recordstores.
- Activity since
- Displays the timestamp when record collection began. This value is automatically reset every 24 hours.
- Record Sent
- Displays the number of records sent to the recordstore from a sensor.
- I/O Errors
- Displays the number of errors generated.
- Queue Full (Records Dropped)
- Displays the number of records dropped when records are created faster than they can be sent to the recordstore.
ExtraHop Packetstore Settings
ExtraHop packetstores continuously collect and store raw packet data from your sensors. Connect the sensor to the packetstore to begin storing packets.
Connect sensors and console to the packetstore
Before you can query for packets, you must connect the console and all sensors to the packetstore.
Connected to a sensor
Connected to sensor and console
Manage packetstores
From the ExtraHop console, you can view connected packetstores and manage some administrative tasks.
View information about connected packetstores.
- Click Trace Cluster in the Name field to open the Cluster Properties. You can add a custom nickname for the packetstore and view the Cluster ID.
- Click any appliance to view the properties. By clicking Open Admin UI, you can access the Administration settings for the specific packetstore.
- View the date and time that the appliance was added to this Command appliance.
- View the license status for your appliances.
- View the list of actions that you can perform on this appliance.
- View the Job column to see the status of any running support scripts.
Select a packetstore. Then, select from the following administrative tasks.
- Click Run Support Script and then select from the following
options:
- Click Run Default Support Script to collect information about the selected packetstore. You can send this diagnostics file to ExtraHop Support for analysis.
- Click Run Custom Support Script to upload a file from ExtraHop Support that provides small system changes or enhancements.
- Click Upgrade Firmware to upgrade the selected packetstore. You can enter a URL to the firmware on the Customer Portal website or upload the firmware file from your computer. With either option, we strongly recommend you read the firmware release notes and the firmware upgrade guide.
- Click Remove Appliance to permanently disconnect the selected packetstore. This option only prevents you from performing the administrative tasks on this page from the console. The packetstore remains connected to your packet sensor and continues to collect packets.
Appendix
Common acronyms
The following common computing and networking protocol acronyms are used in this guide.
Acronym | Full Name |
---|---|
AAA | Authentication, authorization, and accounting |
AMF | Action Message Format |
CIFS | Common Internet File System |
CLI | Command Line Interface |
CPU | Central Processing Unit |
DB | Database |
DHCP | Dynamic Host Configuration Protocol |
DNS | Domain Name System |
ERSPAN | Encapsulated Remote Switched Port Analyzer |
FIX | Financial Information Exchange |
FTP | File Transfer Protocol |
HTTP | Hyper Text Transfer Protocol |
IBMMQ | IBM Message Oriented Middleware |
ICA | Independent Computing Architecture |
IP | Internet Protocol |
iSCSI | Internet Small Computer System Interface |
L2 | Layer 2 |
L3 | Layer 3 |
L7 | Layer 7 |
LDAP | Lightweight Directory Access Protocol |
MAC | Media Access Control |
MIB | Management Information Base |
NFS | Network File System |
NVRAM | Non-Volatile Random Access Memory |
RADIUS | Remote Authentication Dial-In User Service |
RPC | Remote Procedure Call |
RPCAP | Remote Packet Capture |
RSS | Resident Set Size |
SMPP | Short Message Peer-to-Peer Protocol |
SMTP | Simple Message Transport Protocol |
SNMP | Simple Network Management Protocol |
SPAN | Switched Port Analyzer |
SSD | Solid-State Drive |
SSH | Secure Shell |
SSL | Secure Socket Layer |
TACACS+ | Terminal Access Controller Access-Control System Plus |
TCP | Transmission Control Protocol |
UI | User Interface |
VLAN | Virtual Local Area Network |
VM | Virtual Machine |
Configure Cisco NetFlow devices
The following are 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 will be exported to the ExtraHop sensor.
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 sensor. For more information on how to enable SNMP ifIndex persistence on your network devices, refer 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.
Thank you for your feedback. Can we contact you to ask follow up questions?