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 Shield Docker container
  2. Configure the proxy as an ICAP client
  3. Set a sample policy to enforce

Start Nullafi Shield

The following docker run command will start an instance of Nullafi Shield with some very basic parameters. The settings are designed for a temporary testing environment and are not recommended for production use. Check out that password! It also assumes that you have placed a license key file on your docker host at ~/nullafi/user-data/license.key. Please modify the command as necessary so that Shield can access the license key when it starts.

Neither of these docker images are hosted at Docker Hub yet. We’ll have to post them before we give this doc to anyone, or just manually supply the images.

docker run \
   --name nullafi -h nullafi \
   -v ~/nullafi/user-data:/apps/nullafi/user-data \
   --network="bridge" \
   -p 1344:1344 -p 8080:8080 \
   -e NULLAFI_USERNAME=admin \
   -e NULLAFI_PASSWORD=123456 \
   -e NULLAFI_LICENSE_KEY_FILE=/apps/nullafi/user-data/license.key \
   nullafi/shield:latest

While this isn’t really a Docker tutorial, here’s a brief explanation for each parameter: - Naming the container (both container name and hostname) makes it easier to reference later or when viewing logs, etc. - -v tells Docker to attach the host’s ~/nullafi/user-data directory to the Shield container’s /apps/nullafi/user-data. This is where we will put the license key. - The network bridge is a simple way to grant the container access to the outside world - The Shield container will expose two ports - 1344 is the default ICAP listening port - 8080 is where the Admin Console will listen - Username and Password are self explanatory - The license key file is required for Shield to run - The container image will be pulled from Docker Hub

Configure Proxy

Since this is a test environment, it’s likely that you are deploying a sample proxy alongside the Nullafi Shield container. The only requirement is that the proxy be ICAP compliant (IETF RFC 3507) and configured to use Shield for response modification (respmod). Further discussion of both Proxy configuration and the ICAP protocol itself can be found later in this document.

To enable this quick start tutorial, Nullafi has created a sample container which provides an instance of the free and open source Squid proxy, configured as an ICAP server. It will use self-signed certificates for SSL connections.

docker run  \
   --name squid5 -h squid5 \
   --network="bridge" \
   -p 44509:44509  \
   -e MITM_CERT=/etc/squid5/nullafi.crt  \
   -e MITM_KEY=/etc/squid5/nullafi.pem  \
   -e MITM_PROXY=yes  \
   -e ICAP_URL=icap://nullafi:1344/respmod  \
   -e ENABLE_AUTH=no  \
   -e ENABLE_ICAP=yes  \
   nullafi/squid5:latest 

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 port 8080 at your Docker host’s IP address.

http://<ip address>:8080

The username is “admin” and the password is “123456” if you used the sample docker run command above.

This section relies on product changes to be implemented. We don’t yet have predefined sample Obfuscation objects.

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:

  • 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.
  • Choose Domain from the Type dropdown menu
  • Type “hubspot.com” in the text field, and click on the Add button.
  • Now click Save in the lower right corner – you’ve just defined your first App!

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 Email - Leave Domain from the Obfuscations menu ==(This is the one that’s not there yet!)== - Click Save in the lower right, and Nullafi Shield will begin enforcing the rule.

In order to test the rule, run traffic through the proxy to your sample application. If you used the sample Squid proxy container above, it is listening for explicit proxy connections on port 44509 (from the -p 44509:44509 part of the docker run command)

Configure your browser to use a proxy at your Docker host’s IP address or port 44509, and navigate to your sample 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 “Email leave domain” uses asterisks to mask the username portion of an email address, and maybe dive into the many powerful policy options …