MongoSecurityPlaypen

MongoSecurityPlaypen is intended to be used for learning, exploring or demo'ing specific MongoDB security features, to be deployed only in a safe sandbox environment. The project uses VirtualBox, Vagrant & Ansible to create, configure and run a set of virtual machines on a host Laptop/PC.

WARNING This project is intentionally NOT "production secure" to make it easier for people to explore. For example, no firewalls are configured and passwords are passed around on the command line which can be view-able in OS user history and OS process lists. Other potential security holes are likely to exist. It is strongly suggested that you consult the MongoDB Security Checklist.

The project demonstrates the following MongoDB 3.6 security capabilities.

• Client Authentication - SCRAM-SHA-1, Certificate, LDAP (Proxy & Direct) & Kerberos
• Internal Authentication - Keyfile & Certificate
• Role Based Access Control - Internal-DB & External-LDAP authorization
• User Access IP Address Whitelists
• Auditing
• Log Redaction
• Encryption-over-the-Wire - TLS/SSL
• Encryption-at-Rest - Keyfile & KMIP
• Secured Views - Using custom roles
• FIPS 140-2 usage

When the project is run on a Laptop/PC, the following local environment is generated, in a set of 5 Virtual Machines:

WARNING This project is licensed using the open source MIT License (refer to the 'LICENSE' file in the root directory of this project). However, when run, the project will download and install the Enterprise version of MongoDB, supplied by MongoDB Inc., which has a commercial licence. By running the 'vagrant up' command of this MongoSecurityPlaypen project, you will be implicitly accepting the terms and conditions of the MongoDB Enterprise licence enforced by MongoDB Inc.. Please consult MongoDB Inc.'s licence documents directly, for more information.

1 How To Run

1.1 Prerequisites

Ensure the following dependencies are already fulfilled on the host Laptop/PC:

• Host operating system is Mac OS X or Linux
• VirtualBox is already installed on the host machine
• Vagrant is already installed on the host machine
• Ansible is already installed on the host machine (see OS specific installation guides for Mac OSX and the many Linux variants). Max OS X Hint: Run "brew install ansible" but if that fails try the "pip" method described in the link
• Host machine is connected to the internet (for the installation/configuration only - once configured, you can re-start the environment offline)

1.2 Main Steps to Run

1. Download or Clone this repository (see green "Clone or Download" button at top right of project home page). Example command to clone:

   $ git clone https://github.com/pkdone/MongoSecurityPlaypen.git
   $ cd MongoSecurityPlaypen
   

2. If required, change any values in the text file vars/external_vars.yml to define which security features should be turned on and off (e.g. to enable Kerberos, to enable KMIP)

3. From the terminal/shell, ensure the current directory is the base directory of this MongoSecurityPlaypen project (i.e. the directory containing the file Vagrantfile)

4. Run the following commands to configure the 5-virtual-machine environment outlined in the diagram above - includes final step of automatically running the Test Client Python Application and listing the results in the console:

   $ vagrant destroy -f
   $ vagrant up
   

Notes:

• May not be necessary to run 'destroy' first, but some users have reported that one of the VMs is not generated when they run 'up', if they don't run 'destroy' first (root cause not yet diagnosed). Also some Mac users have reported that the first time they run this it fails, and thereafter it runs fine.
• It may take around 15 minutes to complete execution, mainly depending on the speed of the host's internet connection.
• If the internet connection is very slow, the build process may fail with an error due to the CentOS/RedHat package manager (yum) timing out when trying to download binaries.
• Once completed, the results from the Test Client Python Application will have been displayed towards the end of the Vagrant output text in the console, showing some data queried from the MongoDB replica set.
• If the configuration process results in an error, run 'vagrant destroy -f' and then try again, as sometimes old environments can get in the way.

2 Tips for Exploring & Playing With the Configured Environment

2.1 SSH'ing to each of the 5 VMs

# Connect to the VM hosting OpenLDAP, MIT Kerberos KDC and PyKMIP Server
$ vagrant ssh centralit

# Connect to the VM hosting the 1st MongoDB Database Replica in the Replica Set
$ vagrant ssh dbnode1

# Connect to the VM hosting the 2nd MongoDB Database Replica in the Replica Set
$ vagrant ssh dbnode2

# Connect to the VM hosting the 3rd MongoDB Database Replica in the Replica Set
$ vagrant ssh dbnode3

# Connect to the VM hosting the Test Client Python Application
$ vagrant ssh client

2.2 Stopping, Re-starting and Clearing Out The Environment

To shutdown/halt the VMs, allowing them to be re-started at a future time, as is, for use offline, run:

$ vagrant halt

To restart the VMs (inc. the MongoDB, OpenLDAP, Kerberos & PyKMIP processes) after previously halting it, just run (this won’t attempt to recreate the VMs - the VMs will just be started up again):

$ vagrant up 

Note: Halt/Up doesn't currently work when the 'encryptdb_enabled' variable is true, because the PyKMIP Server is intended for testing purposes only and does not have the capability to persist saved keys to disk (see section 4. Project TODOs, below).

To completely remove the VMs, ready to start all over again with 'vagrant up', run:

$ vagrant destroy -f

Note: If a different security configuration is required, by changing the values in the text file vars/external_vars.yml, the steps of running 'vagrant destroy -f' and then 'vagrant up' need to be executed, to tear down and then re-create the whole environment again. This project does not have a way of allowing just a few existing environment settings to be re-configured on the fly.

2.3 Using Mongo Shell to Connect to the Replica Set

Each sub-section below outlines a specific way to connect to the MongoDB cluster, depending on the type of MongoDB authentication that has been configured for the cluster.

Notes:

• Users must connect to the Replica Set from one of the following IP addresses, due to an IP Address Whitelist that has been defined to apply to all database users: 127.0.0.1, 192.168.14.100, 192.168.14.101, 192.168.14.102, 192.168.14.103, 192.168.14.109.
• For some types of authentication, when connecting via the Mongo Shell, Fully Qualified Domain Names - FQDNs (eg. dbnode1.vagrant.dev), need to be used rather than just hostnames (eg. dbnode1, localhost) or IP addresses (eg. 192.168.14.101, or 127.0.0.1). This is necessary when using Kerberos, Certificates and/or TLS.
• For some types of authentication, when invoking the Mongo Shell, the 'mongo' command has to be run as the 'mongod' OS user because a referenced file (such as a keyfile/certificate or a Kerberos keytab), has been "locked down" to only be visible to the 'mongod' OS user that runs the 'mongod' OS process. Hence the use of 'sudo' in those cases.

2.3.1 Connect with no authentication enabled

$ vagrant ssh dbnode1
$ mongo    # If SSL disabled
$ mongo dbnode1.vagrant.dev:27017 --ssl --sslCAFile /etc/ssl/mongodbca.pem  # If SSL enabled
> show dbs

2.3.2 Connect with Username/Password Challenge (SCRAM-SHA-1) authentication

$ vagrant ssh dbnode1
$ mongo    # If SSL disabled
$ mongo dbnode1.vagrant.dev:27017 --ssl --sslCAFile /etc/ssl/mongodbca.pem  # If SSL enabled
> db.getSiblingDB("admin").auth(
    {
         mechanism: "SCRAM-SHA-1",
         user: "dbmaster",
         pwd:  "adminPa55wd123",
         digestPassword: true
    }
  );
> show dbs

2.3.3 Connect with Certificate authentication

$ vagrant ssh dbnode1
$ sudo -u mongod mongo dbnode1.vagrant.dev:27017 --ssl --sslCAFile /etc/ssl/mongodbca.pem --sslPEMKeyFile /etc/ssl/adminuser_client.pem --sslPEMKeyPassword tlsClientPa55word678
> db.getSiblingDB("$external").auth(
    {
         mechanism: "MONGODB-X509",
         user: "CN=dbmaster,OU=Human Resources,O=WizzyIndustries,L=London,ST=London,C=GB"
    }
 );
> show dbs

2.3.4 Connect with LDAP authentication (for both Proxy and Direct mechanisms)

$ vagrant ssh dbnode1
$ mongo    # If SSL disabled
$ mongo dbnode1.vagrant.dev:27017 --ssl --sslCAFile /etc/ssl/mongodbca.pem  # If SSL enabled
> db.getSiblingDB("$external").auth(
    {
         mechanism: "PLAIN",
         user: "dbmaster",
         pwd:  "adminPa55wd123",
         digestPassword: false
    }
 );
> show dbs

2.3.5 Connect with Kerberos (GSSAPI) authentication

$ vagrant ssh dbnode1
$ sudo -u mongod kinit dbmaster  # Required after running Vagrant 'halt' and then 'up, to obtain a Kerberos ticket again
$ sudo -u mongod mongo dbnode1.vagrant.dev:27017   # If SSL disabled
$ sudo -u mongod mongo dbnode1.vagrant.dev:27017 --ssl --sslCAFile /etc/ssl/mongodbca.pem  # If SSL enabled
> db.getSiblingDB("$external").auth(
    {
         mechanism: "GSSAPI",