CIFS ACLs

License: PRO+ (Professional Edition or higher)
Plugin Type: Post-Index Plugin
Author: Diskover Data, Inc.

Overview

The CIFS ACLs plugin retrieves NTFS security permissions from files and directories on Linux-mounted CIFS/SMB shares and enriches your Diskover indices with that permission data. It's the Linux counterpart to the Windows Attributes plugin — if your environment runs on Linux and your data lives on Windows file servers (accessed via CIFS/SMB mounts), this plugin lets you collect and search NTFS ACL information without needing a Windows machine.

Under the hood, the plugin uses the getcifsacl command (provided by the cifs-utils Linux package) to read NTFS Security Descriptors from each file and directory in your index. It then writes three new searchable fields back into Elasticsearch: cifsacls (the ACL entries), cifsowner (the NTFS file owner), and cifsgroup (the NTFS primary group).

⚠️ Platform: This plugin runs on Linux only. It requires the cifs-utils system package and a CIFS/SMB share mounted with the cifsacl mount option. It does not run on Windows or macOS.

Use Cases

• Post-Hoc Security Enrichment — You have existing Diskover indices created by a Linux crawler scanning CIFS/SMB shares. The indices contain file metadata (names, sizes, dates) but lack NTFS permission information. Run this plugin after indexing to backfill ACL, owner, and group data into those existing indices.

• Selective ACL Collection — You don't need ACL data for your entire index — just for sensitive directories like Finance, HR, or Legal. Use the plugin's query filtering to target only the files and directories that matter, reducing processing time and storage overhead.

• Security Auditing & Compliance — Find permission issues like overly broad access grants, explicit DENY entries, or files accessible by Everyone. Use the enriched data to support compliance requirements for frameworks like SOX, HIPAA, PCI-DSS, and GDPR.

Sample data from a CIFS ACLs execution:

Here we can see the entire list of metadata returned from the CIFS ACLs plugin!

Installation

DNF Installation (Linux RPM)

On Linux systems using DNF package management, this plugin can be installed via RPM:

sudo dnf install diskover-plugin-postindex-getcifsacls

Note: Ensure your system is configured with the Diskover RPM repository before running the install command.

Prerequisites

Step 1 — Install the cifs-utils Package

The cifs-utils package provides the getcifsacl binary that the plugin relies on:

# Debian / Ubuntu
sudo apt install cifs-utils

# RHEL / CentOS / Rocky Linux
sudo yum install cifs-utils

# SUSE
sudo zypper install cifs-utils

Step 2 — Install the Plugin

Copy the plugin files to your Diskover post-index plugins directory:

cp -r diskover_getcifsacls /opt/diskover/plugins_postindex/

Step 3 — Mount Your CIFS Share with the cifsacl Option

⚠️ Critical: The CIFS share must be mounted with the cifsacl mount option. Without this option, the Linux kernel does not expose NTFS Security Descriptors, and getcifsacl will fail with "Operation not supported" for every file.

Mount command:

sudo mount -t cifs //server/share /mnt/share -o cifsacl,username=user,password=pass

Or in /etc/fstab for persistent mounts:

//server/share  /mnt/share  cifs  cifsacl,username=user,password=pass  0  0

Step 4 — Verify the Installation

# Verify getcifsacl is installed
which getcifsacl

# Verify getcifsacl works on a file in your mounted share
getcifsacl /mnt/share/testfile.txt

# Verify the share is mounted with the cifsacl option
mount | grep cifs

# Verify Elasticsearch connectivity
python3 -c "from diskover_elasticsearch import es_connection_cached; print(es_connection_cached().info())"

If getcifsacl returns ACL output (lines like OWNER:, GROUP:, and ACL:) for a test file, you're ready to go.

Configuration

Configuration is managed through the Diskover Admin Panel. Navigate to Plugins → Post Index → CIFS ACLs to access the settings.

Here is the beginning of our sample configuration There are many other configuraitons for the CIFS ACLs plugin - covered in detail below!

Configuration Parameters

Configuration Examples

Basic Configuration

Collect CIFS ACLs for all files and directories with default settings:

Plugins:
  Post Index:
    CIFS ACLs:
      Default:
        maxthreads: 4
        other_query: ""
        replace_paths:
          from_path: ""
          to_path: ""
        getcifsacl_path: "/usr/bin/getcifsacl"
        include_owner_group: true
        raw_sids: false
        batch_size: 500
        subprocess_timeout: 30
        doc_types: "files_and_dirs"

Cross-Platform Path Translation

If your Diskover index was created by crawling an NFS mount but you need to read ACLs from a CIFS mount of the same data, configure path translation:

Plugins:
  Post Index:
    CIFS ACLs:
      Default:
        maxthreads: 8
        replace_paths:
          from_path: "/mnt/nfs/data"
          to_path: "/mnt/cifs/data"
        include_owner_group: true
        raw_sids: false

In this example, an indexed path like /mnt/nfs/data/Finance/report.xlsx would be translated to /mnt/cifs/data/Finance/report.xlsx before calling getcifsacl.

Selective ACL Collection

Target only specific directories and process files only (skip directories):

Plugins:
  Post Index:
    CIFS ACLs:
      Default:
        maxthreads: 4
        other_query: "parent_path:*Finance* OR parent_path:*HR*"
        doc_types: "files"

High-Performance Configuration

For large indices with many files, increase parallelism and batch size:

Plugins:
  Post Index:
    CIFS ACLs:
      Default:
        maxthreads: 16
        batch_size: 1000
        subprocess_timeout: 15
        include_owner_group: false

💡 Tip: Setting include_owner_group: false reduces the number of fields written per document. Increasing batch_size reduces the number of Elasticsearch bulk operations at the cost of higher memory usage.

Raw SID Output

For environments where SID-to-name resolution is not available (no Winbind, SSSD, or ID mapping configured), enable raw SID mode:

Plugins:
  Post Index:
    CIFS ACLs:
      Default:
        raw_sids: true

Execution / Usage Guide

The CIFS ACLs plugin can be run manually from the command line, scheduled as a Custom Task, or triggered automatically as a Post-Crawl Command after an Index Task completes.

Manual Execution

Run the plugin from the Diskover installation directory:

# Basic execution on a specific index
python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py diskover-2026.02.10.index

# With verbose output
python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py -v diskover-2026.02.10.index

# With debug-level output
python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py -V diskover-2026.02.10.index

# Auto-find the latest index for a top path
python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py -l /mnt/cifs/data

# Use a named configuration
python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py -c finance_audit diskover-2026.02.10.index

# Override the query filter from the command line
python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py -q "parent_path:*Finance*" -v diskover-2026.02.10.index

# Check the plugin version
python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py --version

Command-Line Options

Automated Execution — Custom Task

You can schedule the CIFS ACLs plugin to run on a recurring basis using Diskover's Custom Task feature.

Here we can see the Run Command & args needed for the Custom Task - Note that in this case you cannot use the {indexname} variable as this is not a task that creates an index, so we must use the -l (toppath) CLI option and pass in our top path!

Automated Execution — Post-Crawl Command

To run the plugin automatically after every index crawl completes, configure it as a Post-Crawl Command on your Index Task:

To use verbose logging:

To use a named configuration:

Available Index Task Tokens:

• {indexname} — The name of the index that was just created

Important: The Post-Crawl Command field should contain only the executable (python3). All script paths, flags, and arguments go in the Post-Crawl Command Args field.

In your system ensure to replace the ConfigurationName above with a named configuraiton that you've created at Diskover Admin → Plugins → Post-Index → CIFS ACLs – If you are not using a custom configuration and you're just using Default than the -c flag and the ConfigurationName is not required!

‌

Expected Behavior During Execution

When the plugin runs, you'll see output like this:

2026-02-10 10:30:15,123 - INFO - Starting diskover CIFS ACLs ...
2026-02-10 10:30:15,234 - INFO - Found getcifsacl binary at: /usr/bin/getcifsacl
2026-02-10 10:30:15,345 - INFO - Updating index mappings for CIFS ACL fields in diskover-2026.02.10.index...
2026-02-10 10:30:15,456 - INFO - Done.
2026-02-10 10:30:15,567 - INFO - Started 4 CIFS ACL processing threads
2026-02-10 10:30:15,678 - INFO - Searching and queuing docs from index diskover-2026.02.10.index...
2026-02-10 10:30:18,789 - INFO - STATS (docs processed 1500 (15.0%), docs in queue 500, elapsed 0:00:03, perf 500.000 docs/s, memory usage 125 MB)
...
2026-02-10 10:32:45,456 - INFO - *** Elapsed time 0:03:00 ***
2026-02-10 10:32:45,567 - INFO - *** Total files/folders (ES docs): 10000 ***
2026-02-10 10:32:45,678 - INFO - *** Files/folders processed CIFS ACLs OK: 9850 ***
2026-02-10 10:32:45,789 - INFO - *** Files/folders processed CIFS ACLs ERROR: 150 ***

The STATS line updates every 3 seconds during processing, showing progress percentage, queue depth, throughput, and memory usage.

Reviewing the Output

What Gets Added to Your Index

The plugin adds up to three new fields to each processed document:

Understanding the ACE Format

Each ACL entry follows the format: TRUSTEE:TYPE/FLAGS/MASK

• TRUSTEE — The user or group (e.g., DOMAIN\user1, BUILTIN\Administrators)

• TYPE — ALLOWED or DENIED

• FLAGS — Inheritance flags (e.g., OI|CI for Object Inherit + Container Inherit, or 0x0 for none)

• MASK — Permission level: FULL (Full Control), CHANGE (Modify), READ, D (Delete), or a hex value

Common ACE Examples

Verifying Successful Execution

Look at the summary lines at the end of the plugin output:

• Total files/folders (ES docs) — How many documents were found in the index matching your filters

• Files/folders processed CIFS ACLs OK — How many were successfully enriched with ACL data

• Files/folders processed CIFS ACLs ERROR — How many failed (check the log for details on individual failures)

A small number of errors is normal — files may have been deleted between indexing and ACL collection, or individual files may have permission restrictions. If the error count is very high relative to the total, check the Troubleshooting section below.

Searching in Diskover

Once the plugin has run, you can search for files and directories based on their NTFS permissions directly in the Diskover web UI. This is where the real value of the plugin comes through — turning permission data into actionable, searchable intelligence.

Basic ACL Searches

Security Audit Searches

Owner and Group Searches

Full-Text Searches

The plugin creates both keyword and text sub-fields for each field. Use the .text sub-field for tokenized, partial matching:

cifsacls.text:domain admin
cifsowner.text:administrator
cifsgroup.text:domain users

Combined Searches

These examples combine ACL data with other Diskover metadata for powerful targeted queries:

Compliance Use Cases

Troubleshooting

"getcifsacl binary not found"

The plugin exits at startup because it can't find the getcifsacl binary.

Fix: Install the cifs-utils package (see Installation above). If getcifsacl is installed at a non-default location, update the getcifsacl_path configuration parameter to the correct path. You can find it with which getcifsacl.

"Operation not supported" for Every File

The getcifsacl command fails on all files because the CIFS share is not mounted with the cifsacl option.

Fix: Remount the share with the cifsacl option:

sudo umount /mnt/share
sudo mount -t cifs //server/share /mnt/share -o cifsacl,username=user,password=pass

Verify with mount | grep cifs — you should see cifsacl in the mount options.

"No such file or directory" for Most Files

The plugin can't find files on disk because the paths stored in the index don't match the CIFS mount path on this host.

Fix: Configure the replace_paths setting to translate index paths to the correct CIFS mount paths. For example, if your index stores paths like /mnt/nfs/data/... but the CIFS mount is at /mnt/cifs/data/...:

replace_paths:
  from_path: "/mnt/nfs/data"
  to_path: "/mnt/cifs/data"

Use the -V (very verbose) flag to see the exact paths being used for each file.

Subprocess Timeout Errors

Many files fail with "Timeout getting CIFS ACLs" — usually indicating network latency or file server performance issues.

Fix: Increase the subprocess_timeout value (default is 30 seconds) and consider reducing the thread count to lower the load on the file server:

subprocess_timeout: 60
maxthreads: 2

Enabling Debug Logging

For detailed diagnostic output, use the -V flag:

python3 /opt/diskover/plugins_postindex/diskover_getcifsacls/diskover_getcifsacls.py -V diskover-2026.02.10.index

This shows the exact path being used for each getcifsacl call, the parsed output, and detailed error information.

Log File Location

Plugin output is written to the Diskover logs directory. Check your Diskover configuration for the log path, or look for output in the terminal when running manually.

Comparison with Windows Attributes Plugin

If you're deciding between this plugin and the Windows Attributes plugin, here's a quick comparison:

Use this plugin if you operate a Linux-only environment or your CIFS/SMB shares are already mounted on Linux hosts. Use the Windows Attributes plugin if you have a Windows host available and need ACE format compatibility with Windows tools like icacls.

Support

• Diskover Documentation

• Diskover Support Portal

Last Updated: April 2026