diff --git a/docs/arkime.md b/docs/arkime.md index f1e9743c0..48961c05e 100644 --- a/docs/arkime.md +++ b/docs/arkime.md @@ -73,8 +73,6 @@ Clicking the down arrow **▼** icon to the far right of the search bar presents ![Export PCAP](./images/screenshots/arkime_export_pcap.png) -See the [issues](#Issues) section of this document for an error that can occur using this feature when Zeek log sessions are displayed.View - ### SPIView Arkime's **SPI** (**S**ession **P**rofile **I**nformation) **View** provides a quick and easy-to-use interface for exploring session/log metrics. The SPIView page lists categories for general session metrics (e.g., protocol, source and destination IP addresses, sort and destination ports, etc.) as well as for all of various types of network traffic understood by Malcolm. These categories can be expanded and the top *n* values displayed, along with each value's cardinality, for the fields of interest they contain. diff --git a/docs/authsetup.md b/docs/authsetup.md index 889394353..868f98456 100644 --- a/docs/authsetup.md +++ b/docs/authsetup.md @@ -2,7 +2,7 @@ Malcolm requires authentication to access the [user interface](quickstart.md#UserInterfaceURLs). [Nginx](https://nginx.org/) can authenticate users with either local TLS-encrypted HTTP basic authentication or using a remote Lightweight Directory Access Protocol (LDAP) authentication server. -With the local basic authentication method, user accounts are managed by Malcolm and can be created, modified, and deleted using a [user management web interface](#AccountManagement). This method is suitable in instances where accounts and credentials do not need to be synced across many Malcolm installations. +With the local basic authentication method, user accounts are managed by Malcolm and can be created, modified, and deleted using a [user management web interface](authsetup.md#AuthBasicAccountManagement). This method is suitable in instances where accounts and credentials do not need to be synced across many Malcolm installations. LDAP authentication are managed on a remote directory service, such as a [Microsoft Active Directory Domain Services](https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview) or [OpenLDAP](https://www.openldap.org/). diff --git a/docs/contributing.md b/docs/contributing.md index 6c89497ee..74fd5665f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -8,20 +8,20 @@ The purpose of this document is to provide some direction for those willing to m + [Docker bind mounts](contributing-local-modifications.md#Bind) + [Building Malcolm's Docker images](development.md#Build) * [Adding a new service (Docker image)](contributing-new-image.md#NewImage) - + [Networking and firewall](#NewImageFirewall) + + [Networking and firewall](contributing-new-image.md#NewImageFirewall) * [Adding new log fields](contributing-new-log-fields.md#NewFields) - [Zeek](contributing-zeek.md#Zeek) - + [`local.zeek`](#LocalZeek) + + [`local.zeek`](contributing-zeek.md#LocalZeek) + [Adding a new Zeek package](contributing-zeek.md#ZeekPackage) - + [Zeek Intelligence Framework](#ContributingZeekIntel) + + [Zeek Intelligence Framework](contributing-zeek.md#ContributingZeekIntel) * [PCAP processors](contributing-pcap.md#PCAP) * [Logstash](contributing-logstash.md#Logstash) + [Parsing a new log data source](contributing-logstash.md#LogstashNewSource) + [Parsing new Zeek logs](contributing-logstash.md#LogstashZeek) + [Enrichments](contributing-logstash.md#LogstashEnrichments) - + [Logstash plugins](#LogstashPlugins) -* [OpenSearch Dashboards](#dashboards) - + [Adding new visualizations and dashboards](#DashboardsNewViz) - + [OpenSearch Dashboards plugins](#DashboardsPlugins) -* [Carved file scanners](#Scanners) -* [Style](#Style) + + [Logstash plugins](contributing-logstash.md#LogstashPlugins) +* [OpenSearch Dashboards](contributing-dashboards.md#dashboards) + + [Adding new visualizations and dashboards](contributing-dashboards.md#DashboardsNewViz) + + [OpenSearch Dashboards plugins](contributing-dashboards.md#DashboardsPlugins) +* [Carved file scanners](contributing-file-scanners.md#Scanners) +* [Style](contributing-style.md#Style) diff --git a/docs/hedgehog.md b/docs/hedgehog.md index 309229398..14bebcf28 100644 --- a/docs/hedgehog.md +++ b/docs/hedgehog.md @@ -15,38 +15,27 @@ Hedgehog Linux is a Debian-based operating system built to ### Table of Contents * [Sensor installation](hedgehog-installation.md#HedgehogInstallation) - - [Image boot options](#HedgehogBootOptions) + - [Image boot options](hedgehog-installation.md#HedgehogBootOptions) - [Installer](hedgehog-installation.md#HedgehogInstaller) -* [Boot](#HedgehogBoot) - - [Kiosk mode](#HedgehogKioskMode) -* [Configuration](#HedgehogConfiguration) - - [Interfaces, hostname, and time synchronization](#HedgehogConfigRoot) - + [Hostname](#HedgehogConfigHostname) - + [Interfaces](#HedgehogConfigIface) - + [Time synchronization](#HedgehogConfigTime) +* [Boot](hedgehog-boot.md#HedgehogBoot) + - [Kiosk mode](hedgehog-boot.md#HedgehogKioskMode) +* [Configuration](hedgehog-config.md#HedgehogConfiguration) + - [Interfaces, hostname, and time synchronization](hedgehog-config-root.md#HedgehogConfigRoot) + + [Hostname](hedgehog-config-root.md#HedgehogConfigHostname) + + [Interfaces](hedgehog-config-root.md#HedgehogConfigIface) + + [Time synchronization](hedgehog-config-root.md#HedgehogConfigTime) - [Capture, forwarding, and autostart services](hedgehog-config-user.md#HedgehogConfigUser) - + [Capture](#HedgehogConfigCapture) - * [Automatic file extraction and scanning](#HedgehogZeekFileExtraction) - + [Forwarding](#HedgehogConfigForwarding) + + [Capture](hedgehog-config-user.md#HedgehogConfigCapture) + * [Automatic file extraction and scanning](hedgehog-config-user.md#HedgehogZeekFileExtraction) + + [Forwarding](hedgehog-config-user.md#HedgehogConfigForwarding) * [arkime-capture](hedgehog-config-user.md#Hedgehogarkime-capture): Arkime session forwarding * [filebeat](hedgehog-config-user.md#Hedgehogfilebeat): Zeek and Suricata log forwarding - * [miscbeat](#Hedgehogmiscbeat): System metrics forwarding + * [miscbeat](hedgehog-config-user.md#Hedgehogmiscbeat): System metrics forwarding + [Autostart services](hedgehog-config-user.md#HedgehogConfigAutostart) -+ [Zeek Intelligence Framework](#HedgehogZeekIntel) ++ [Zeek Intelligence Framework](hedgehog-config-zeek-intel.md#HedgehogZeekIntel) * [Appendix A - Generating the ISO](hedgehog-iso-build.md#HedgehogISOBuild) -* [Appendix B - Configuring SSH access](#HedgehogConfigSSH) -* [Appendix C - Troubleshooting](#HedgehogTroubleshooting) -* [Appendix D - Hardening](#HedgehogHardening) - - [Compliance exceptions](#HedgehogComplianceExceptions) -* [Appendix E - Upgrades](#HedgehogUpgradePlan) -* [Copyright](#HedgehogFooter) - -# Copyright - -Hedgehog Linux - part of [Malcolm](https://github.com/idaholab/Malcolm) - is Copyright 2022 Battelle Energy Alliance, LLC, and is developed and released through the cooperation of the Cybersecurity and Infrastructure Security Agency of the U.S. Department of Homeland Security. - -See [`License.txt`](https://raw.githubusercontent.com/idaholab/Malcolm/main/License.txt) for the terms of its release. - -### Contact information of author(s): - -[malcolm@inl.gov](mailto:malcolm@inl.gov?subject=Network%20sensor%20development) +* [Appendix B - Configuring SSH access](hedgehog-ssh.md#HedgehogConfigSSH) +* [Appendix C - Troubleshooting](hedgehog-troubleshooting.md#HedgehogTroubleshooting) +* [Appendix D - Hardening](hedgehog-hardening.md#HedgehogHardening) + - [Compliance exceptions](hedgehog-hardening.md#HedgehogComplianceExceptions) +* [Appendix E - Upgrades](hedgehog-upgrade.md#HedgehogUpgradePlan) diff --git a/docs/main.md b/docs/main.md index 975aaf48c..222f55535 100644 --- a/docs/main.md +++ b/docs/main.md @@ -4,7 +4,7 @@ Malcolm processes network traffic data in the form of packet capture (docs/PCAP) files or Zeek logs. A [sensor](live-analysis.md#Hedgehog) (packet capture appliance) monitors network traffic mirrored to it over a SPAN port on a network switch or router, or using a network TAP device. [Zeek](https://www.zeek.org/index.html) logs and [Arkime](https://molo.ch/) sessions are generated containing important session metadata from the traffic observed, which are then securely forwarded to a Malcolm instance. Full PCAP files are optionally stored locally on the sensor device for examination later. -Malcolm parses the network session data and enriches it with additional lookups and mappings including GeoIP mapping, hardware manufacturer lookups from [organizationally unique identifiers (docs/OUI)](http://standards-oui.ieee.org/oui/oui.txt) in MAC addresses, assigning names to [network segments](host-and-subnet-mapping.md#SegmentNaming) and [hosts](host-and-subnet-mapping.md#HostNaming) based on user-defined IP address and MAC mappings, performing [TLS fingerprinting](#https://engineering.salesforce.com/tls-fingerprinting-with-ja3-and-ja3s-247362855967), and many others. +Malcolm parses the network session data and enriches it with additional lookups and mappings including GeoIP mapping, hardware manufacturer lookups from [organizationally unique identifiers (docs/OUI)](http://standards-oui.ieee.org/oui/oui.txt) in MAC addresses, assigning names to [network segments](host-and-subnet-mapping.md#SegmentNaming) and [hosts](host-and-subnet-mapping.md#HostNaming) based on user-defined IP address and MAC mappings, performing [TLS fingerprinting](https://engineering.salesforce.com/tls-fingerprinting-with-ja3-and-ja3s-247362855967), and many others. The enriched data is stored in an [OpenSearch](https://opensearch.org/) document store in a format suitable for analysis through two intuitive interfaces: OpenSearch Dashboards, a flexible data visualization plugin with dozens of prebuilt dashboards providing an at-a-glance overview of network protocols; and Arkime, a powerful tool for finding and identifying the network sessions comprising suspected security incidents. These tools can be accessed through a web browser from analyst workstations or for display in a security operations center (SOC). Logs can also optionally be forwarded on to another instance of Malcolm. @@ -17,88 +17,87 @@ For smaller networks, use at home by network security enthusiasts, or in the fie * [Quick start](quickstart.md#QuickStart) * [Getting Malcolm](quickstart.md#GetMalcolm) * [User interface](quickstart.md#UserInterfaceURLs) -* [Overview](#Overview) * [Components](components.md#Components) * [Supported Protocols](protocols.md#Protocols) * [Development](development.md#Development) * [Building from source](development.md#Build) * [Pre-Packaged installation files](development.md#Packager) -* [Preparing your system](#Preparing) - * [Recommended system requirements](#SystemRequirements) +* [Preparing your system](preparation.md#Preparing) + * [Recommended system requirements](system-requirements.md#SystemRequirements) * [System configuration and tuning](malcolm-config.md#ConfigAndTuning) * [`docker-compose.yml` parameters](malcolm-config.md#DockerComposeYml) - * [Linux host system configuration](#HostSystemConfigLinux) - * [macOS host system configuration](#HostSystemConfigMac) - * [Windows host system configuration](#HostSystemConfigWindows) -* [Running Malcolm](#Running) + * [Linux host system configuration](host-config-linux.md#HostSystemConfigLinux) + * [macOS host system configuration](host-config-macos.md#HostSystemConfigMac) + * [Windows host system configuration](host-config-windows.md#HostSystemConfigWindows) +* [Running Malcolm](running.md#Running) * [OpenSearch instances](opensearch-instances.md#OpenSearchInstance) - * [Authentication and authorization for remote OpenSearch clusters](#OpenSearchAuth) + * [Authentication and authorization for remote OpenSearch clusters](opensearch-instances.md#OpenSearchAuth) * [Configure authentication](authsetup.md#AuthSetup) * [Local account management](authsetup.md#AuthBasicAccountManagement) * [Lightweight Directory Access Protocol (LDAP) authentication](authsetup.md#AuthLDAP) - - [LDAP connection security](#AuthLDAPSecurity) + - [LDAP connection security](authsetup.md#AuthLDAPSecurity) * [TLS certificates](authsetup.md#TLSCerts) * [Starting Malcolm](running.md#Starting) * [Stopping and restarting Malcolm](running.md#StopAndRestart) * [Clearing Malcolm's data](running.md#Wipe) - * [Temporary read-only interface](#ReadOnlyUI) + * [Temporary read-only interface](running.md#ReadOnlyUI) * [Capture file and log archive upload](upload.md#Upload) - [Tagging](upload.md#Tagging) - [Processing uploaded PCAPs with Zeek and Suricata](upload.md#UploadPCAPProcessors) -* [Live analysis](#LiveAnalysis) +* [Live analysis](live-analysis.md#LiveAnalysis) * [Using a network sensor appliance](live-analysis.md#Hedgehog) - * [Monitoring local network interfaces](#LocalPCAP) - * [Manually forwarding logs from an external source](#ExternalForward) -* [Arkime](#Arkime) + * [Monitoring local network interfaces](live-analysis.md#LocalPCAP) + * [Manually forwarding logs from an external source](live-analysis.md#ExternalForward) +* [Arkime](arkime.md#Arkime) * [Zeek log integration](arkime.md#ArkimeZeek) - [Correlating Zeek logs and Arkime sessions](arkime.md#ZeekArkimeFlowCorrelation) - * [Help](#ArkimeHelp) + * [Help](arkime.md#ArkimeHelp) * [Sessions](arkime.md#ArkimeSessions) - * [PCAP Export](#ArkimePCAPExport) - * [SPIView](#ArkimeSPIView) + * [PCAP Export](arkime.md#ArkimePCAPExport) + * [SPIView](arkime.md#ArkimeSPIView) * [SPIGraph](arkime.md#ArkimeSPIGraph) - * [Connections](#ArkimeConnections) + * [Connections](arkime.md#ArkimeConnections) * [Hunt](arkime.md#ArkimeHunt) - * [Statistics](#ArkimeStats) - * [Settings](#ArkimeSettings) + * [Statistics](arkime.md#ArkimeStats) + * [Settings](arkime.md#ArkimeSettings) * [OpenSearch Dashboards](dashboards.md#Dashboards) - * [Discover](#Discover) - - [Screenshots](#DiscoverGallery) + * [Discover](dashboards.md#Discover) + - [Screenshots](dashboards.md#DiscoverGallery) * [Visualizations and dashboards](dashboards.md#DashboardsVisualizations) - - [Prebuilt visualizations and dashboards](#PrebuiltVisualizations) - - [Screenshots](#PrebuiltVisualizationsGallery) + - [Prebuilt visualizations and dashboards](dashboards.md#PrebuiltVisualizations) + - [Screenshots](dashboards.md#PrebuiltVisualizationsGallery) - [Building your own visualizations and dashboards](dashboards.md#BuildDashboard) - + [Screenshots](#NewVisualizationsGallery) + + [Screenshots](dashboards.md#NewVisualizationsGallery) * [Search Queries in Arkime and OpenSearch](queries-cheat-sheet.md#SearchCheatSheet) -* [Other Malcolm features](#MalcolmFeatures) +* Other Malcolm features - [Automatic file extraction and scanning](file-scanning.md#ZeekFileExtraction) - [Automatic host and subnet name assignment](host-and-subnet-mapping.md#HostAndSubnetNaming) + [IP/MAC address to hostname mapping via `host-map.txt`](host-and-subnet-mapping.md#HostNaming) + [CIDR subnet to network segment name mapping via `cidr-map.txt`](host-and-subnet-mapping.md#SegmentNaming) + [Defining hostname and CIDR subnet names interface](host-and-subnet-mapping.md#NameMapUI) - + [Applying mapping changes](#ApplyMapping) + + [Applying mapping changes](host-and-subnet-mapping.md#ApplyMapping) - [OpenSearch index management](index-management.md#IndexManagement) - [Event severity scoring](severity.md#Severity) - + [Customizing event severity scoring](#SeverityConfig) + + [Customizing event severity scoring](severity.md#SeverityConfig) - [Zeek Intelligence Framework](zeek-intel.md#ZeekIntel) + [STIX™ and TAXII™](zeek-intel.md#ZeekIntelSTIX) + [MISP](zeek-intel.md#ZeekIntelMISP) - - [Anomaly Detection](#AnomalyDetection) + - [Anomaly Detection](anomaly-detection.md#AnomalyDetection) - [Alerting](alerting.md#Alerting) - + [Email Sender Accounts](#AlertingEmail) + + [Email Sender Accounts](alerting.md#AlertingEmail) - ["Best Guess" Fingerprinting for ICS Protocols](ics-best-guess.md#ICSBestGuess) - [Asset Management with NetBox](netbox.md#NetBox) - - [CyberChef](#CyberChef) + - [CyberChef](cyberchef.md#CyberChef) - [API](api.md#API) + [Examples](api-examples.md#APIExamples) -* [Ingesting Third-party Logs](#ThirdPartyLogs) +* [Ingesting Third-party Logs](third-party-logs.md#ThirdPartyLogs) * [Malcolm installer ISO](malcolm-iso.md#ISO) * [Installation](malcolm-iso.md#ISOInstallation) - * [Generating the ISO](#ISOBuild) - * [Setup](#ISOSetup) - * [Time synchronization](#ConfigTime) + * [Generating the ISO](malcolm-iso.md#ISOBuild) + * [Setup](malcolm-iso.md#ISOSetup) + * [Time synchronization](time-sync.md#ConfigTime) * [Hardening](hardening.md#Hardening) - * [Compliance Exceptions](#ComplianceExceptions) + * [Compliance Exceptions](hardening.md#ComplianceExceptions) * [Installation example using Ubuntu 22.04 LTS](ubuntu-install-example.md#InstallationExample) * [Upgrading Malcolm](malcolm-upgrade.md#UpgradePlan) -* [Modifying or Contributing to Malcolm](#Contributing) \ No newline at end of file +* [Modifying or Contributing to Malcolm](contributing.md#Contributing) \ No newline at end of file diff --git a/docs/malcolm-config.md b/docs/malcolm-config.md index f3a0d2590..e5e0e94af 100644 --- a/docs/malcolm-config.md +++ b/docs/malcolm-config.md @@ -41,7 +41,7 @@ Various other environment variables inside of `docker-compose.yml` can be tweake * `OPENSEARCH_SECONDARY` - if set to `true`, Malcolm will forward logs to a secondary remote OpenSearch instance in addition to the primary (local or remote) OpenSearch instance (default `false`) * `OPENSEARCH_SECONDARY_URL` - when forwarding to a secondary remote OpenSearch instance (i.e., `OPENSEARCH_SECONDARY` is `true`) this value specifies the secondary remote instance URL in the format `protocol://host:port` * `OPENSEARCH_SECONDARY_SSL_CERTIFICATE_VERIFICATION` - if set to `true`, connections to the secondary remote OpenSearch instance will require full TLS certificate validation (this may fail if using self-signed certificates) (default `false`) -* `NETBOX_DISABLED` - if set to `true`, Malcolm will **not** start [NetBox](netbox.md#NetBox) and manage a [NetBox](#NetBox) instance (default `true`) +* `NETBOX_DISABLED` - if set to `true`, Malcolm will **not** start and manage a [NetBox](netbox.md#NetBox) instance (default `true`) * `NETBOX_CRON` - if set to `true`, network traffic metadata will periodically be queried and used to populate Malcolm's [NetBox](netbox.md#NetBox) instance * `NGINX_BASIC_AUTH` - if set to `true`, use [TLS-encrypted HTTP basic](authsetup.md#AuthBasicAccountManagement) authentication (default); if set to `false`, use [Lightweight Directory Access Protocol (LDAP)](authsetup.md#AuthLDAP) authentication * `NGINX_LOG_ACCESS_AND_ERRORS` - if set to `true`, all access to Malcolm via its [web interfaces](quickstart.md#UserInterfaceURLs) will be logged to OpenSearch (default `false`)