A powerful, easily deployable network traffic analysis tool suite
Malcolm requires authentication to access the user interface. Nginx 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. 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 x-auth-variables
section near the top of the docker-compose.yml
file with the NGINX_BASIC_AUTH
environment variable: true
for local TLS-encrypted HTTP basic authentication, false
for LDAP authentication.
In either case, you must run ./scripts/auth_setup
before starting Malcolm for the first time in order to:
nginx/certs/
directoryBEATS_SSL
environment variable above)
logstash/certs/
directoryfilebeat/certs/
directory; if using Hedgehog Linux, these certificates should be copied to the /opt/sensor/sensor_ctl/logstash-client-certificates
directory on the sensoropensearch/opensearch.keystore
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 served over HTTPS on port 488 (e.g., https://localhost:488 if you are 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. A forgotten password can also be reset via an emailed link, though this requires SMTP server settings to be specified in htadmin/config.ini
in the Malcolm installation directory.
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:
url
- the ldap://
or ldaps://
connection URL for the remote LDAP server, which has the following syntax: ldap[s]://<hostname>:<port>/<base_dn>?<attributes>?<scope>?<filter>
binddn
and binddn_password
- the account credentials used to query the LDAP directorygroup_attribute
- the group attribute name which contains the member object (e.g., member
or memberUid
)group_attribute_is_dn
- whether or not to search for the user’s full distinguished name as the value in the group’s member attributerequire
and satisfy
- require user
, require group
and require valid_user
can be used in conjunction with satisfy any
or satisfy all
to limit the users that are allowed to access the Malcolm instanceBefore 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.
Authentication over LDAP can be done using one of three ways, two of which offer data confidentiality protection:
In addition to the NGINX_BASIC_AUTH
environment variable being set to false
in the x-auth-variables
section near the top of the docker-compose.yml
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:
NGINX_LDAP_TLS_STUNNEL
set to true
in docker-compose.yml
url
should begin with ldap://
and its port should be either the default LDAP port (389) or the default Global Catalog port (3268) in nginx/nginx_ldap.conf
NGINX_LDAP_TLS_STUNNEL
set to false
in docker-compose.yml
url
should begin with ldaps://
and its port should be either the default LDAPS port (636) or the default LDAPS Global Catalog port (3269) in nginx/nginx_ldap.conf
NGINX_LDAP_TLS_STUNNEL
set to false
in docker-compose.yml
url
should begin with ldap://
and its port should be either the default LDAP port (389) or the default Global Catalog port (3268) in nginx/nginx_ldap.conf
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.
When you 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 you to add a security exception for the certificate the first time you connect to Malcolm.
Another option is to generate your own certificates (or have them issued to you) 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 for you 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 like Let’s Encrypt. In this configuration, the reverse proxy will be encrypting the connections instead of Malcolm, so you’ll need to set the NGINX_SSL
environment variable to false
in docker-compose.yml
(or answer no
to the “Require encrypted HTTPS connections?” question posed by install.py
). If you are setting NGINX_SSL
to false
, make sure you understand what you are doing and ensure that external connections cannot reach ports over which Malcolm will be communicating without encryption, including verifying your local firewall configuration.