Skip to content

Quick Start

Getting Nullafi Shield up and running can be as simple as 1, 2, 3! This guide focuses on getting a basic setup working quickly, before diving into every possible option:

  1. Start the Docker containers for Shield and supporting services.
  2. Set a sample policy to enforce.
  3. Configure a web browser to use the testing proxy.

Start Nullafi Shield

Using the following Docker Compose command, along with supplied sample Compose and Environment files, will bring up an environment for testing. The settings are designed for a temporary testing environment and are not recommended for production use. You will need to either change the Environment file to match your test server's hostname or IP address, or modify your client's hosts file to resolve test.host.name to the test server's IP address. It also assumes that you have placed a license key file on your docker host in the same directory as the docker-compose.yml file named license.file. Please modify the .env file as necessary so that Shield can access the license key when it starts.

docker compose up -d

Database Initialization

On first run, the databases take a little while to initialize. If you start the services and immediately try to log in to Shield's Admin UI, you might encounter warnings about a missing database. Please be patient and allow a minute or two for the initialization to complete. Subsequent restarts will be faster.

While this isn’t really a Docker tutorial, here’s a brief explanation of what is happening:

  • The sample Environment file (which must be named .env and be in the same directory as the docker-compose.yml file) sets up values for some commonly changed items, like the port exposed by the proxy server.
  • The sample Compose file creates a network and starts four services
    • A Nullafi Shield instance
    • A Squid proxy server, configured as an ICAP client to the Shield service
    • An Elasticsearch database to store Activity data
    • A Redis database to store Shield's configuration

Sample Policy

Now that Nullafi Shield is running, we can set up a rule to demonstrate data protection. First, open a web browser and navigate to the Admin Console. It’s listening on HTTPS at your Docker host’s name or IP address.

https://<ip address or hostname>

First-Time Login

When you access the Admin Console for the first time, you'll be prompted to create an administrator username and password.



The rest of this document provides full descriptions of the Dashboard and Admin Console, but for now, let’s create a simple rule.

Define an Application

This tells Shield where to look for data.

  1. In the Admin Console, click on Policy in the left navigation menu to expand it, then select Applications.
  2. Click the Add New Application button in the upper right.
    • Example: We'll create a rule to hide email addresses. For this, we'll use HubSpot as our sample app. You can adapt this to any application you have access to that displays email data.
  3. For the Name, type HubSpot.
  4. In the Definitions section:
    • Click the Add button.
    • Choose Domain from the Type dropdown.
    • In the text field, enter hubspot.com.
    • Click the Save button for this definition.
  5. Click Save in the lower right corner of the application editing window. You’ve just defined your first App!

Create an Obfuscation

This defines what data to protect and how to protect it.

  1. Navigate to Obfuscations (under Policy in the left navigation menu).
  2. Click the Add New Obfuscation button (in the upper right).
  3. For the Name, enter Hide Email.
  4. In the Definitions section:
    • Choose Email Address from the Data Type dropdown.
    • Choose Fully Obfuscated from the Mask Format dropdown.
    • Click the Add button to add this definition.
  5. Click Save in the lower right to save the new Obfuscation.

Create a Rule

This brings the Application and Obfuscation together.

  1. Navigate to Rules (under Policy in the left navigation menu).
  2. Click the Add New Rule button.
  3. Give it a Name, such as Test Rule.
  4. From the Applications list, select your HubSpot application.
  5. From the Obfuscations list, select Hide Email.
  6. Click Save in the lower right. Nullafi Shield will now begin enforcing this rule.

Configure Proxy

In order to test the rule, run traffic through the proxy to your testing application. The sample Squid proxy container from above is listening for explicit proxy connections on port 44509.

Since this is a test environment, it’s likely that you only need one or two clients to use the proxy. This is easily accomplished with manual proxy settings. Using Firefox as the test browser, enter the hostname or IP address of your test server into the Manual proxy configuration, set the port to 44509, and check the box for "Also use this proxy for HTTPS."

Navigate to your testing App (HubSpot if you’re using our example).

Self-Signed Certificate

You will likely need to accept a self-signed certificate from the Squid proxy. This is expected for this quick start guide. For production environments, properly signed certificates should be used.

Now log in and head to a page that would otherwise display email addresses – it should show redacted addresses instead.

Back in the Nullafi Shield Admin Console, you’ll see stats growing on the Dashboard, connection activity generated on the Activity page, and can explore the settings that created the policy you are enforcing. Check out the Mask Formats section to see why “Fully Obfuscated” uses asterisks to mask the email address, and maybe dive into the many powerful policy options …