Skip to content

Quick Start

Getting Nullafi Shield up and running can be as simple as 1, 2, 3! Before we dive into every possible option, let’s just make it work quickly:

  1. Start the Docker conteiners 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

Note

The databases take a little while to initialize. If you start the services and immediately try to log in to Sheild's Admin UI, you might find several warnings about the missing database. Just be patient and give it a minute or two to finish.

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

  • The sample Environment file (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 five services
    • A Nullafi Shield to serve as the Admin interface (policy creation)
    • A Nullafi Shield to serve as the ICAP server (policy enforcement)
    • 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>

You will be asked to create a username and password on first launch.

The rest of this document will provide full descriptions of the Dashboard landing page and the rest of the Admin Console, but for now let’s just make a rule to get started. Click on Policy in the left navigation menu to expand the policy section, and then Applications to define our first app. From there:

  1. Define an Application
    • Click on the Add New Application in the upper right
      • We’ll be making a sample rule to hide email addresses, so make sure to choose an app that contains email data. HubSpot will be used here, but you can replace it with any app you have access to.
    • Give it a meaningful name; type “HubSpot” in the Name field.
    • Click on the Add button in the Definitions section
      • Choose Domain from the Type dropdown menu
      • Type “hubspot.com” in the text field, and click on the Save button.
    • Now click Save in the lower right corner – you’ve just defined your first App!
  2. Create an Obfuscation
    • Navigate to Obfuscations in the left navigation menu, and click on the Add New Obfuscation button in teh upper right
    • Since we'll be hiding email addresses, let's use "Hide Email" for the name.
    • In the Definitions section
      • choose Email Address from the Data Type dropdown menu
      • choose Fully Obfuscated from the Mask Format dropdown menu
      • Click the Add button to add the definition
    • Click the Save button in the lower right to save the new Obfuscation
  3. Next we will create a rule to apply to our sample App.
    • Navigate to Rules in the Policy section of the left navigation menu
    • Click on the Add New Rule button in the upper right
    • Give it a name; type “Test Rule” in the Name field.
    • Choose HubSpot from the Applications menu and Hide Email from the Obfuscations menu.
    • Click Save in the lower right, and Nullafi Shield will begin enforcing the 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). This will require that you accept the self-signed certificate from the Squid proxy, which is acceptable for the purposes of this quick start guide but of course will be changed before you go into production for real users. 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 …