Logo

A powerful, easily deployable network traffic analysis tool suite

Quick Start

Documentation

Components

Supported Protocols

Configuring

Arkime

Dashboards

Hedgehog Linux

Contribution Guide

Configure authentication

Malcolm requires authentication to access the user interface. Nginx can authenticate users with either local TLS-encrypted HTTP basic authentication or 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. 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 or OpenLDAP.

Malcolm’s authentication method is defined in the auth-common.env configuration file file with the NGINX_BASIC_AUTH environment variable: true for local TLS-encrypted HTTP basic authentication, false for LDAP authentication and no_authentication to disable authentication completely.

In either case, you must run ./scripts/auth_setup before starting Malcolm for the first time in order to:

Local account management

auth_setup is used to define the username and password for the administrator account. Once Malcolm is running, the administrator account can be used to manage other user accounts via a Malcolm User Management page at https://localhost/auth if connecting locally)

Malcolm user accounts can be used to access the interfaces of all of its components, including Arkime. Arkime uses its own internal database of user accounts, so when a Malcolm user account logs in to Arkime for the first time, Malcolm creates a corresponding Arkime user account automatically. This being the case, it is not recommended to use the Arkime Users settings page or change the password via the Password form under the Arkime Settings page, as those settings would not be consistently used across Malcolm.

Users may change their passwords via the Malcolm User Management page by clicking User Self Service.

Lightweight Directory Access Protocol (LDAP) authentication

The nginx-auth-ldap module serves as the interface between Malcolm’s Nginx web server and a remote LDAP server. When you run auth_setup for the first time, a sample LDAP configuration file is created at nginx/nginx_ldap.conf.

# This is a sample configuration for the ldap_server section of nginx.conf.
# Yours will vary depending on how your Active Directory/LDAP server is configured.
# See https://github.com/kvspb/nginx-auth-ldap#available-config-parameters for options.

ldap_server ad_server {
  url "ldap://ds.example.com:3268/DC=ds,DC=example,DC=com?sAMAccountName?sub?(objectClass=person)";

  binddn "bind_dn";
  binddn_passwd "bind_dn_password";

  group_attribute member;
  group_attribute_is_dn on;
  require group "CN=Malcolm,CN=Users,DC=ds,DC=example,DC=com";
  require valid_user;
  satisfy all;
}

auth_ldap_cache_enabled on;
auth_ldap_cache_expiration_time 10000;
auth_ldap_cache_size 1000;

This file is mounted into the nginx container when Malcolm is started to provide connection information for the LDAP server.

The contents of nginx_ldap.conf will vary depending on how the LDAP server is configured. Some of the avaiable parameters in that file include:

Before starting Malcolm, edit nginx/nginx_ldap.conf according to the specifics of your LDAP server and directory tree structure. Using a LDAP search tool such as ldapsearch in Linux or dsquery in Windows may be of help as you formulate the configuration. Your changes should be made within the curly braces of the ldap_server ad_server { … } section. You can troubleshoot configuration file syntax errors and LDAP connection or credentials issues by running ./scripts/logs (or docker-compose logs nginx) and examining the output of the nginx container.

The Malcolm User Management page described above is not available when using LDAP authentication.

LDAP connection security

Authentication over LDAP can be done using one of three methods, two of which offer data confidentiality protection:

In addition to the NGINX_BASIC_AUTH environment variable being set to false in the auth-common.env configuration file file, the NGINX_LDAP_TLS_STUNNEL and NGINX_LDAP_TLS_STUNNEL environment variables are used in conjunction with the values in nginx/nginx_ldap.conf to define the LDAP connection security level. Use the following combinations of values to achieve the connection security methods above, respectively:

For encrypted connections (whether using StartTLS or LDAPS), Malcolm will require and verify certificates when one or more trusted CA certificate files are placed in the nginx/ca-trust/ directory. Otherwise, any certificate presented by the domain server will be accepted.

TLS certificates

When users set up authentication for Malcolm a set of unique self-signed TLS certificates are created which are used to secure the connection between clients (e.g., your web browser) and Malcolm’s browser-based interface. This is adequate for most Malcolm instances as they are often run locally or on internal networks, although your browser will most likely require users to add a security exception for the certificate when first connecting to Malcolm.

Another option is for users to generate their own certificates (or have them issued directly) and have them placed in the nginx/certs/ directory. The certificate and key file should be named cert.pem and key.pem, respectively.

A third possibility is to use a third-party reverse proxy (e.g., Traefik or Caddy) to handle the issuance of the certificates and to broker the connections between clients and Malcolm. Reverse proxies such as these often implement the ACME protocol for domain name authentication and can be used to request certificates from certificate authorities such as Let’s Encrypt. In this configuration, the reverse proxy will be encrypting the connections instead of Malcolm, so users will need to set the NGINX_SSL environment variable to false in nginx.env (or answer no to the “Require encrypted HTTPS connections?” question posed by ./scripts/configure). If you are setting NGINX_SSL to false, make sure user must understand precisely what they are doing, ensuring that external connections cannot reach ports over which Malcolm will be communicating without encryption, including verifying local firewall configuration.

Command-line arguments

The ./scripts/auth_setup script can also be run noninteractively which can be useful for scripting Malcolm setup. This behavior can be selected by supplying the --auth-noninteractive option on the command line. Running with the --help option will list the arguments accepted by the script:

$ ./scripts/auth_setup --help
usage: auth_setup <arguments>

Malcolm control script

options:
  -v [DEBUG], --verbose [DEBUG]
                        Verbose output
  -f <string>, --file <string>
                        docker-compose or kubeconfig YML file
  -e <string>, --environment-dir <string>
                        Directory containing Malcolm's .env files

…

Authentication Setup:
  --auth [CMDAUTHSETUP]
                        Configure Malcolm authentication
  --auth-noninteractive [CMDAUTHSETUPNONINTERACTIVE]
                        Configure Malcolm authentication (noninteractive using arguments provided)
  --auth-admin-username <string>
                        Administrator username (for --auth-noninteractive)
  --auth-admin-password-openssl <string>
                        Administrator password hash from "openssl -passwd -1" (for --auth-noninteractive)
  --auth-admin-password-htpasswd <string>
                        Administrator password hash from "htpasswd -n -B username | cut -d: -f2" (for --auth-noninteractive)
  --auth-generate-webcerts [AUTHGENWEBCERTS]
                        (Re)generate self-signed certificates for HTTPS access (for --auth-noninteractive)
  --auth-generate-fwcerts [AUTHGENFWCERTS]
                        (Re)generate self-signed certificates for a remote log forwarder
  --auth-generate-netbox-passwords [AUTHGENNETBOXPASSWORDS]
                        (Re)generate internal passwords for NetBox
…

In order to avoid specifying passwords as command line arguments, when setting the administrator password noninteractively the user must instead provide hashes generated by openssl -passwd -1 and htpasswd -n -B username.