A powerful, easily deployable network traffic analysis tool suite for network security monitoring
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:
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 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.
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 that 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 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:
NGINX_LDAP_TLS_STUNNEL
set to true
in auth-common.env
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 auth-common.env
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 auth-common.env
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 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.
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
.
Since Malcolm’s nginx reverse proxy uses HTTP Basic Authentication, there is no “Logout” button. Users should exit their browser window to log out of Malcom. On the next browser restart, Malcolm will prompt the user for credentials.
Another way to log out of Malcolm is for a user to manually clear their browser’s active sessions.