diff --git a/docs/hedgehog-boot.md b/docs/hedgehog-boot.md index 67c8c8478..6e6984b0c 100644 --- a/docs/hedgehog-boot.md +++ b/docs/hedgehog-boot.md @@ -4,14 +4,14 @@ Each time the sensor boots, a grub boot menu will be shown briefly, after which ## Kiosk mode -![Kiosk mode sensor menu: resource statistics](./docs/images/kiosk_mode_sensor_menu.png) +![Kiosk mode sensor menu: resource statistics](./docs/images/hedgehog/images/kiosk_mode_sensor_menu.png) The sensor automatically logs in as the sensor user account and runs in **kiosk mode**, which is intended to show an at-a-glance view of the its resource utilization. Clicking the **☰** icon in allows you to switch between the resource statistics view and the services view. -![Kiosk mode sensor menu: services](./docs/images/kiosk_mode_services_menu.png) +![Kiosk mode sensor menu: services](./docs/images/hedgehog/images/kiosk_mode_services_menu.png) The kiosk's services screen (designed with large clickable labels for small portable touch screens) can be used to start and stop essential services, get a status report of the currently running services, and clean all captured data from the sensor. -!["Clean Sensor" confirmation prompt before deleting sensor data](./docs/images/kiosk_mode_wipe_prompt.png) +!["Clean Sensor" confirmation prompt before deleting sensor data](./docs/images/hedgehog/images/kiosk_mode_wipe_prompt.png) -!["Sensor Status" report from the kiosk services menu](./docs/images/kiosk_mode_status.png) \ No newline at end of file +!["Sensor Status" report from the kiosk services menu](./docs/images/hedgehog/images/kiosk_mode_status.png) \ No newline at end of file diff --git a/docs/hedgehog-config-root.md b/docs/hedgehog-config-root.md index 357672e23..df549188b 100644 --- a/docs/hedgehog-config-root.md +++ b/docs/hedgehog-config-root.md @@ -6,11 +6,11 @@ The first step of sensor configuration is to configure the network interfaces an You may next select whether to configure the network interfaces, hostname, or time synchronization. -![Selection to configure network interfaces, hostname, or time synchronization](./docs/images/root_config_mode.png) +![Selection to configure network interfaces, hostname, or time synchronization](./docs/images/hedgehog/images/root_config_mode.png) Selecting **Hostname**, you will be presented with a summary of the current sensor identification information, after which you may specify a new sensor hostname. This name will be used to tag all events forwarded from this sensor in the events' **host.name** field. -![Specifying a new sensor hostname](./docs/images/hostname_setting.png) +![Specifying a new sensor hostname](./docs/images/hedgehog/images/hostname_setting.png) ## Interfaces @@ -18,15 +18,15 @@ Returning to the configuration mode selection, choose **Interface**. You will be You will be presented with a list of interfaces to configure as the sensor management interface. This is the interface the sensor itself will use to communicate with the network in order to, for example, forward captured logs to an aggregate server. In order to do so, the management interface must be assigned an IP address. This is generally **not** the interface used for capturing data. Select the interface to which you wish to assign an IP address. The interfaces are listed by name and MAC address and the associated link speed is also displayed if it can be determined. For interfaces without a connected network cable, generally a `-1` will be displayed instead of the interface speed. -![Management interface selection](./docs/images/select_iface.png) +![Management interface selection](./docs/images/hedgehog/images/select_iface.png) Depending on the configuration of your network, you may now specify how the management interface will be assigned an IP address. In order to communicate with an event aggregator over the management interface, either **static** or **dhcp** must be selected. -![Interface address source](./docs/images/iface_mode.png) +![Interface address source](./docs/images/hedgehog/images/iface_mode.png) If you select static, you will be prompted to enter the IP address, netmask, and gateway to assign to the management interface. -![Static IP configuration](./docs/images/iface_static.png) +![Static IP configuration](./docs/images/hedgehog/images/iface_static.png) In either case, upon selecting **OK** the network interface will be brought down, configured, and brought back up, and the result of the operation will be displayed. You may choose **Quit** upon returning to the configuration tool's welcome screen. @@ -34,14 +34,14 @@ In either case, upon selecting **OK** the network interface will be brought down Returning to the configuration mode selection, choose **Time Sync**. Here you can configure the sensor to keep its time synchronized with either an NTP server (using the NTP protocol) or a local [Malcolm](https://github.com/idaholab/Malcolm) aggregator or another HTTP/HTTPS server. On the next dialog, choose the time synchronization method you wish to configure. -![Time synchronization method](./docs/images/time_sync_mode.png) +![Time synchronization method](./docs/images/hedgehog/images/time_sync_mode.png) If **htpdate** is selected, you will be prompted to enter the IP address or hostname and port of an HTTP/HTTPS server (for a Malcolm instance, port `9200` may be used) and the time synchronization check frequency in minutes. A test connection will be made to determine if the time can be retrieved from the server. -![*htpdate* configuration](./docs/images/htpdate_setup.png) +![*htpdate* configuration](./docs/images/hedgehog/images/htpdate_setup.png) If *ntpdate* is selected, you will be prompted to enter the IP address or hostname of the NTP server. -![NTP configuration](./docs/images/ntp_host.png) +![NTP configuration](./docs/images/hedgehog/images/ntp_host.png) Upon configuring time synchronization, a "Time synchronization configured successfully!" message will be displayed, after which you will be returned to the welcome screen. \ No newline at end of file diff --git a/docs/hedgehog-config-user.md b/docs/hedgehog-config-user.md index af1bae0af..a5027a990 100644 --- a/docs/hedgehog-config-user.md +++ b/docs/hedgehog-config-user.md @@ -2,7 +2,7 @@ Clicking the **Configure Capture and Forwarding** toolbar icon (or, if you are at a command prompt, running `configure-capture`) will launch the configuration tool for capture and forwarding. The root password is not required as it was for the interface and hostname configuration, as sensor services are run under the non-privileged sensor account. Select **Continue** to proceed. You may select from a list of configuration options. -![Select configuration mode](./docs/images/capture_config_main.png) +![Select configuration mode](./docs/images/hedgehog/images/capture_config_main.png) ## Capture @@ -10,15 +10,15 @@ Choose **Configure Capture** to configure parameters related to traffic capture You will be presented with a list of network interfaces and prompted to select one or more capture interfaces. An interface used to capture traffic is generally a different interface than the one selected previously as the management interface, and each capture interface should be connected to a network tap or span port for traffic monitoring. Capture interfaces are usually not assigned an IP address as they are only used to passively “listen” to the traffic on the wire. The interfaces are listed by name and MAC address and the associated link speed is also displayed if it can be determined. For interfaces without a connected network cable, generally a `-1` will be displayed instead of the interface speed. -![Select capture interfaces](./docs/images/capture_iface_select.png) +![Select capture interfaces](./docs/images/hedgehog/images/capture_iface_select.png) Upon choosing the capture interfaces and selecting OK, you may optionally provide a capture filter. This filter will be used to limit what traffic the PCAP service ([`tcpdump`](https://www.tcpdump.org/)) and the traffic analysis services ([`zeek`](https://www.zeek.org/) and [`suricata`](https://suricata.io/)) will see. Capture filters are specified using [Berkeley Packet Filter (BPF)](http://biot.com/capstats/bpf.html) syntax. Clicking **OK** will attempt to validate the capture filter, if specified, and will present a warning if the filter is invalid. -![Specify capture filters](./docs/images/capture_filter.png) +![Specify capture filters](./docs/images/hedgehog/images/capture_filter.png) Next you must specify the paths where captured PCAP files and logs will be stored locally on the sensor. If the installation worked as expected, these paths should be prepopulated to reflect paths on the volumes formatted at install time for the purpose storing these artifacts. Usually these paths will exist on separate storage volumes. Enabling the PCAP and log pruning autostart services (see the section on autostart services below) will enable monitoring of these paths to ensure that their contents do not consume more than 90% of their respective volumes' space. Choose **OK** to continue. -![Specify capture paths](./docs/images/capture_paths.png) +![Specify capture paths](./docs/images/hedgehog/images/capture_paths.png) ### Automatic file extraction and scanning @@ -26,7 +26,7 @@ Hedgehog Linux can leverage Zeek's knowledge of network protocols to automatical To specify which files should be extracted, specify the Zeek file carving mode: -![Zeek file carving mode](./docs/images/zeek_file_carve_mode.png) +![Zeek file carving mode](./docs/images/hedgehog/images/zeek_file_carve_mode.png) If you're not sure what to choose, either of **mapped (except common plain text files)** (if you want to carve and scan almost all files) or **interesting** (if you only want to carve and scan files with [mime types of common attack vectors](./interface/sensor_ctl/zeek/extractor_override.interesting.zeek)) is probably a good choice. @@ -34,7 +34,7 @@ Next, specify which carved files to preserve (saved on the sensor under `/captur You'll be prompted to specify which engine(s) to use to analyze extracted files. Extracted files can be examined through any of three methods: -![File scanners](./docs/images/zeek_file_carve_scanners.png) +![File scanners](./docs/images/hedgehog/images/zeek_file_carve_scanners.png) * scanning files with [**ClamAV**](https://www.clamav.net/); to enable this method, select **ZEEK_FILE_SCAN_CLAMAV** when specifying scanners for Zeek-carved files * submitting file hashes to [**VirusTotal**](https://www.virustotal.com/en/#search); to enable this method, select **ZEEK_FILE_SCAN_VTOT** when specifying scanners for Zeek-carved files, then manually edit `/opt/sensor/sensor_ctl/control_vars.conf` and specify your [VirusTotal API key](https://developers.virustotal.com/reference) in `VTOT_API2_KEY` @@ -43,7 +43,7 @@ You'll be prompted to specify which engine(s) to use to analyze extracted files. Files which are flagged as potentially malicious will be logged as Zeek `signatures.log` entries, and can be viewed in the **Signatures** dashboard in [OpenSearch Dashboards](https://github.com/idaholab/Malcolm#DashboardsVisualizations) when forwarded to Malcolm. -![File quarantine](./docs/images/file_quarantine.png) +![File quarantine](./docs/images/hedgehog/images/file_quarantine.png) Finally, you will be presented with the list of configuration variables that will be used for capture, including the values which you have configured up to this point in this section. Upon choosing **OK** these values will be written back out to the sensor configuration file located at `/opt/sensor/sensor_ctl/control_vars.conf`. It is not recommended that you edit this file manually. After confirming these values, you will be presented with a confirmation that these settings have been written to the configuration file, and you will be returned to the welcome screen. @@ -51,7 +51,7 @@ Finally, you will be presented with the list of configuration variables that wil Select **Configure Forwarding** to set up forwarding logs and statistics from the sensor to an aggregator server, such as [Malcolm](https://github.com/idaholab/Malcolm). -![Configure forwarders](./docs/images/forwarder_config.png) +![Configure forwarders](./docs/images/hedgehog/images/forwarder_config.png) There are five forwarder services used on the sensor, each for forwarding a different type of log or sensor metric. @@ -61,23 +61,23 @@ There are five forwarder services used on the sensor, each for forwarding a diff First, select the OpenSearch connection transport protocol, either **HTTPS** or **HTTP**. If the metrics are being forwarded to Malcolm, select **HTTPS** to encrypt messages from the sensor to the aggregator using TLS v1.2 using ECDHE-RSA-AES128-GCM-SHA256. If **HTTPS** is chosen, you must choose whether to enable SSL certificate verification. If you are using a self-signed certificate (such as the one automatically created during [Malcolm's configuration](https://github.com/idaholab/Malcolm#configure-authentication)), choose **None**. -![OpenSearch connection protocol](./docs/images/opensearch_connection_protocol.png) ![OpenSearch SSL verification](./docs/images/opensearch_ssl_verification.png) +![OpenSearch connection protocol](./docs/images/hedgehog/images/opensearch_connection_protocol.png) ![OpenSearch SSL verification](./docs/images/hedgehog/images/opensearch_ssl_verification.png) Next, enter the **OpenSearch host** IP address (ie., the IP address of the aggregator) and port. These metrics are written to an OpenSearch database using a RESTful API, usually using port 9200. Depending on your network configuration, you may need to open this port in your firewall to allow this connection from the sensor to the aggregator. -![OpenSearch host and port](./docs/images/arkime-capture-ip-port.png) +![OpenSearch host and port](./docs/images/hedgehog/images/arkime-capture-ip-port.png) You will be asked to enter authentication credentials for the sensor's connections to the aggregator's OpenSearch API. After you've entered the username and the password, the sensor will attempt a test connection to OpenSearch using the connection information provided. -![OpenSearch username](./docs/images/opensearch_username.png) ![OpenSearch password](./docs/images/opensearch_password.png) ![Successful OpenSearch connection](./docs/images/opensearch_connection_success.png) +![OpenSearch username](./docs/images/hedgehog/images/opensearch_username.png) ![OpenSearch password](./docs/images/hedgehog/images/opensearch_password.png) ![Successful OpenSearch connection](./docs/images/hedgehog/images/opensearch_connection_success.png) Finally, you will be shown a dialog for a list of IP addresses used to populate an access control list (ACL) for hosts allowed to connect back to the sensor for retrieving session payloads from its PCAP files for display in Arkime viewer. The list will be prepopulated with the IP address entered a few screens prior to this one. -![PCAP retrieval ACL](./docs/images/malcolm_arkime_reachback_acl.png) +![PCAP retrieval ACL](./docs/images/hedgehog/images/malcolm_arkime_reachback_acl.png) Finally, you'll be given the opportunity to review the all of the Arkime `capture` options you've specified. Selecting **OK** will cause the parameters to be saved and you will be returned to the configuration tool's welcome screen. -![capture settings confirmation](./docs/images/arkime_confirm.png) +![capture settings confirmation](./docs/images/hedgehog/images/arkime_confirm.png) ## filebeat: Zeek and Suricata log forwarding @@ -85,29 +85,29 @@ Finally, you'll be given the opportunity to review the all of the Arkime `captur To configure filebeat, first provide the log path (the same path previously configured for log file generation). -![Configure filebeat for log forwarding](./docs/images/filebeat_log_path.png) +![Configure filebeat for log forwarding](./docs/images/hedgehog/images/filebeat_log_path.png) You must also provide the IP address of the Logstash instance to which the logs are to be forwarded, and the port on which Logstash is listening. These logs are forwarded using the Beats protocol, generally over port 5044. Depending on your network configuration, you may need to open this port in your firewall to allow this connection from the sensor to the aggregator. -![Configure filebeat for log forwrading](./docs/images/filebeat_ip_port.png) +![Configure filebeat for log forwrading](./docs/images/hedgehog/images/filebeat_ip_port.png) Next you are asked whether the connection used for log forwarding should be done **unencrypted** or over **SSL**. Unencrypted communication requires less processing overhead and is simpler to configure, but the contents of the logs may be visible to anyone who is able to intercept that traffic. -![Filebeat SSL certificate verification](./docs/images/filebeat_ssl.png) +![Filebeat SSL certificate verification](./docs/images/hedgehog/images/filebeat_ssl.png) If **SSL** is chosen, you must choose whether to enable [SSL certificate verification](https://www.elastic.co/guide/en/beats/filebeat/current/configuring-ssl-logstash.html). If you are using a self-signed certificate (such as the one automatically created during [Malcolm's configuration](https://github.com/idaholab/Malcolm#configure-authentication), choose **None**. -![Unencrypted vs. SSL encryption for log forwarding](./docs/images/filebeat_ssl_verify.png) +![Unencrypted vs. SSL encryption for log forwarding](./docs/images/hedgehog/images/filebeat_ssl_verify.png) The last step for SSL-encrypted log forwarding is to specify the SSL certificate authority, certificate, and key files. These files must match those used by the Logstash instance receiving the logs on the aggregator. If Malcolm's `auth_setup` script was used to generate these files they would be found in the `filebeat/certs/` subdirectory of the Malcolm installation and must be manually copied to the sensor (stored under `/opt/sensor/sensor_ctl/logstash-client-certificates` or in any other path accessible to the sensor account). Specify the location of the certificate authorities file (eg., `ca.crt`), the certificate file (eg., `client.crt`), and the key file (eg., `client.key`). -![SSL certificate files](./docs/images/filebeat_certs.png) +![SSL certificate files](./docs/images/hedgehog/images/filebeat_certs.png) The Logstash instance receiving the events must be similarly configured with matching SSL certificate and key files. Under Malcolm, the `BEATS_SSL` variable must be set to `true` in Malcolm's `docker-compose.yml` file and the SSL files must exist in the `logstash/certs/` subdirectory of the Malcolm installation. Once you have specified all of the filebeat parameters, you will be presented with a summary of the settings related to the forwarding of these logs. Selecting **OK** will cause the parameters to be written to filebeat's configuration keystore under `/opt/sensor/sensor_ctl/logstash-client-certificates` and you will be returned to the configuration tool's welcome screen. -![Confirm filebeat settings](./docs/images/filebeat_confirm.png) +![Confirm filebeat settings](./docs/images/hedgehog/images/filebeat_confirm.png) ## miscbeat: System metrics forwarding @@ -141,11 +141,11 @@ Despite configuring capture and/or forwarder services as described in previous s Note that only one packet capture engine ([capture](https://arkime.com/), [netsniff-ng](http://netsniff-ng.org/), or [tcpdump](https://www.tcpdump.org/)) can be used. -![Autostart services](./docs/images/autostarts.png) +![Autostart services](./docs/images/hedgehog/images/autostarts.png) Once you have selected the autostart services, you will be prompted to confirm your selections. Doing so will cause these values to be written back out to the `/opt/sensor/sensor_ctl/control_vars.conf` configuration file. -![Autostart services confirmation](./docs/images/autostarts_confirm.png) +![Autostart services confirmation](./docs/images/hedgehog/images/autostarts_confirm.png) After you have completed configuring the sensor it is recommended that you reboot the sensor to ensure all new settings take effect. If rebooting is not an option, you may click the **Restart Sensor Services** menu icon in the top menu bar, or open a terminal and run: diff --git a/docs/hedgehog-config.md b/docs/hedgehog-config.md index d3881958d..97c1c3342 100644 --- a/docs/hedgehog-config.md +++ b/docs/hedgehog-config.md @@ -2,7 +2,7 @@ Kiosk mode can be exited by connecting an external USB keyboard and pressing **Alt+F4**, upon which the *sensor* user's desktop is shown. -![Sensor login session desktop](./docs/images/desktop.png) +![Sensor login session desktop](./docs/images/hedgehog/images/desktop.png) Several icons are available in the top menu bar: diff --git a/docs/hedgehog-installation.md b/docs/hedgehog-installation.md index 5ceb82633..fd3b48339 100644 --- a/docs/hedgehog-installation.md +++ b/docs/hedgehog-installation.md @@ -4,7 +4,7 @@ The Hedgehog Linux installation image, when provided on an optical disc, USB thumb drive, or other removable medium, can be used to install or reinstall the sensor software. -![Sensor installation image boot menu](./docs/images/boot_options.png) +![Sensor installation image boot menu](./docs/images/hedgehog/images/boot_options.png) The boot menu of the sensor installer image provides several options: @@ -25,11 +25,11 @@ The installer will ask for a few pieces of information prior to installing the s Each of these passwords must be entered twice to ensure they were entered correctly. -![Example of the installer's password prompt](./docs/images/users_and_passwords.png) +![Example of the installer's password prompt](./docs/images/hedgehog/images/users_and_passwords.png) After the passwords have been entered, the installer will proceed to format the system drive and install Hedgehog Linux. -![Installer progress](./docs/images/installer_progress.png) +![Installer progress](./docs/images/hedgehog/images/installer_progress.png) At the end of the installation process, you will be prompted with a few self-explanatory yes/no questions: diff --git a/docs/hedgehog.md b/docs/hedgehog.md index e735cd785..f0743e2d3 100644 --- a/docs/hedgehog.md +++ b/docs/hedgehog.md @@ -2,7 +2,7 @@ **Network Traffic Capture Appliance** -![](./docs/logo/hedgehog-color-w-text.png) +![](./docs/images/hedgehog/logo/hedgehog-color-w-text.png) Hedgehog Linux is a Debian-based operating system built to