The NTFS connector for Elimity Insights fetches trustees, access rights and files for an NTFS file system so you can keep in control of your environment.

Follow the instructions below to set up the connector for your environment.

How it works

Elimity Insights periodically fetches trustees, access rights and files for an NTFS file system.
Write Elimity Insights queries to review and monitor updates to the data, or leverage existing queries.
Configure these stored queries to take action when the Elimity Insights data changes.

Integration requirements

Setting up an NTFS source in Elimity Insights requires:

read access to permissions in your NTFS file system (e.g. directly from a local file system, via SMB mounts, ...)
a user in Elimity Insights with the role Connector Admin or higher.

Integration instructions

The following sections will explain the different steps you'll need to take to set up the NTFS connector for Elimity Insights.

1. Deploying a gateway

Firstly we suggest reading our knowledge base article about installing gateways for some general information. Visit https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/ntfs-gateway to get a list of available image tags for this specific gateway.

Since this image is a simple HTTP server, typically we'd recommend to use your cloud provider’s dedicated container hosting platform (e.g. Google Cloud Run, Azure Container Apps, …) for deployment. However, this gateway is only available as a Windows Container and most container hosting platforms don't support those very well. Therefore we suggest getting a plain Windows Server VM from your cloud provider (e.g. Google Cloud Compute Engine, Azure Virtual Machines, ...) and combining it with their product for HTTP(S) proxying (e.g. Google Cloud Load Balancing, Azure Load Balancer). Refer to our knowledge base article about installing gateways for instructions about deploying the gateway on a Windows Server VM.

To configure your gateway, mount a JSON configuration file at `/app/config/config.json` with the properties listed below. You can find an example in the attachments at the bottom of this page.

`secretTokenHash`: hex-encoded SHA256 hash of a secret token you generate securely to ensure only your Elimity Insights tenant can use this gateway
- for example, you can use `openssl rand -base64 32` to generate a 256-bit token
- securely note down the token itself to configure the built-in connector
- hash the token, for example by running `echo -n '<my-token>' | sha256sum` on Linux, or `[Text.Encoding]::UTF8.GetBytes('token') | openssl dgst -sha256` in PowerShell.

Now is also a good time to mount the directories you want to start scanning from. Refer to the examples below for additional details.

Example 1: local directories

In this example we assume you want to scan the files in local directories `C:\dir1\subdir` and `D:\dir2`. The following Docker Compose specification would be a good starting point:

services:
  ntfs-gateway:
    image: europe-west1-docker.pkg.dev/elimity-general/docker/ntfs-gateway:<tag>
    restart: always
    ports:
      - 8080:80
    volumes:
      - .\config:C:\app\config
      - C:\dir1\subdir:C:\target1
      - D:\dir2:C:\target2

Now you can configure the source in Elimity Insights to target the `C:\target1` and `C:\target2` directories. Note that you can freely choose the destination paths for these mounts.

Example 2: SMB shares

Scanning permissions for SMB shares is very similar to scanning permissions for local directories, we just need one extra preliminary step to mount the shares into the local filesystem. Microsoft provides explicit support for making SMB share mounts available to containers, the official documentation contains detailed instructions about setting this up. In short: to mount a directory `dir` in share `\\host\share` to local drive `D:`, run the following PowerShell command:

New-SmbGlobalMapping D: \\host\share\dir -Persistent $true

You can now mount the `D:` drive into the NTFS gateway container using a Docker Compose specification based on the following snippet:

services:
  ntfs-gateway:
    image: europe-west1-docker.pkg.dev/elimity-general/docker/ntfs-gateway:<tag>
    restart: always
    ports:
      - 8080:80
    volumes:
      - .\config:C:\app\config
      - D:\:C:\target

2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Sharepoint source providing the following configuration:

Gateway URL: HTTP(S) URL of your Elimity Insights NTFS gateway
Gateway secret token: secret token you generated in step 1
Targets: HJSON object mapping file labels to paths from which you want to start scanning
- Example 1: you want to scan `C:\target` and display it as `\\server\share\dir`:
```
{ \\server\share\dir: C:\target }
```
- Example 2: you want to scan `C:\target1` and `C:\target2` and display them as `C:\foo\bar` and `C:\foo\baz` respectively:
```
{
  "C:\\foo\\bar": C:\target1
  "C:\\foo\\baz": C:\target2
}
```
Max depth: maximum level of directory nesting; use 0 to set no limit
Only directories: enable if you only want to import directories
Omit advanced access rights: enable if you only want to import basic access rights
Maximum concurrency: maximum number of concurrent workers to use for scanning
Overrides: HJSON object mapping file labels to configuration objects
- `maxDepth`: overrides the global 'Max depth' setting for scans starting from the matched directory
- `onlyDirs`: overrides the global 'Only directories' setting for scans starting from the matched directory