Skip to content
dmitriiPublic

About

Synology ACL audit and remediation tool

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

synaudit

Audit and fix file permissions on Synology NAS.

synaudit walks a shared folder tree, compares each item's ACL against a policy, and reports violations. It can also apply fixes — enforcing inheritance, setting ownership, and adding missing ACL entries — all through the Synology synoacltool binary.

It never opens, writes, truncates, or deletes file contents. All ACL modifications go through synoacltool. Ownership changes use os.Chown.

Should you trust this tool? If you are reluctant to run some random person's code on your NAS, I totally understand. My blog post gives more context to the problem that synaudit is trying to solve and shows solutions based solely on tools from Synology. For what it's worth, the tool is designed to only touch metadata — never the files themselves — which you can verify with a code analysis tool of your choice (e.g., I gave it to Gemini and got a reassuring assessment). The worst thing that synaudit did to my system, due to an incorrect policy, is change permissions on my home directory and ~/.ssh so that incoming SSH connections required a password. That was an easy fix.

Installation

Download a single binary and copy it to your NAS:

# x86_64 (most desktop Synology models)
wget https://github.com/dmitrii/synaudit/releases/latest/download/synaudit-linux-amd64 \
  -O /usr/local/bin/synaudit
chmod +x /usr/local/bin/synaudit

# ARM (some compact Synology models)
wget https://github.com/dmitrii/synaudit/releases/latest/download/synaudit-linux-arm64 \
  -O /usr/local/bin/synaudit
chmod +x /usr/local/bin/synaudit

Each release includes SHA256 checksums for verification:

wget https://github.com/dmitrii/synaudit/releases/latest/download/checksums.txt
shasum -a 256 -c checksums.txt

Quick Start

No configuration file is needed. Point synaudit at a shared folder and go:

synaudit scan /volume1/docs

This will:

  • Walk the directory tree, skipping system directories (@eaDir, #recycle, #snapshot, .DS_Store)
  • Check that the is_inherit flag is set on every item
  • Warn if ownership changes below the scan root
  • Print a summary and write a detailed log file

Scan multiple shares at once:

synaudit scan /volume1/docs /volume1/photos /volume1/music

Commands

scan

Audit one or more directory trees and report violations.

synaudit scan PATH [PATH...] [flags]
Flag Default Description
--policy PATH (lookup chain) Path to policy file
--log PATH synaudit-TIMESTAMP.log Override log file path
--prescan-timeout DURATION 5s Timeout for directory pre-scan
--ignore-inheritance false Skip inheritance checks
--ignore-owner false Skip ownership checks

fix

Apply remediations with logging.

synaudit fix PATH [PATH...] [flags]
Flag Default Description
--policy PATH (lookup chain) Path to policy file
--log PATH synaudit-TIMESTAMP.log Override log file path
--prescan-timeout DURATION 5s Timeout for directory pre-scan
--ignore-inheritance false Skip inheritance checks/fixes
--ignore-owner false Skip ownership checks/fixes
--yes false Apply all fixes without prompting
--dry-run false Show what would change, modify nothing

Three modes of operation:

Invocation Behavior
synaudit fix PATH Interactive: prompt Y/N for each change
synaudit fix PATH --yes Batch: apply all changes
synaudit fix PATH --dry-run Preview: show what would change

Policy

Lookup Chain

For each scan root, synaudit resolves policy in this order (first match wins):

  1. Explicit --policy flag
  2. synaudit-policy.json in the directory being scanned
  3. /usr/local/etc/synaudit/policy.json (system-wide)
  4. Built-in defaults

The tool prints which policy source it is using:

/volume1/docs    policy: /usr/local/etc/synaudit/policy.json
/volume1/photos  policy: /volume1/photos/synaudit-policy.json
/volume1/music   policy: built-in defaults

Example Policies

The policies/ directory in this repository contains example policy files:

  • policy_default.json — the built-in defaults as a file, ready to copy and tweak
  • policy_single.json — single-path policy with owner, ACL entries, and exclusions
  • policy_multi.json — multi-root policy for managing several shares from one file

To use one as a starting point, copy it to your share root as synaudit-policy.json (picked up automatically) or pass it with --policy.

Built-in Defaults

When no policy file is found:

Setting Default Rationale
require_inherit true Broken inheritance is the #1 Synology ACL issue
warn_ownership_drift true Catch accidental ownership changes deep in a share
owner (none) Too share-specific to guess; set to "*" to accept any owner
acl_entries (none) Too share-specific to guess
exclude @eaDir, #recycle, #snapshot, .DS_Store Standard Synology system dirs
allow_linux_mode false Linux-mode items are violations by default
suppress_linux_mode_log false Log allowed Linux-mode items as OK

To disable a noisy check, drop a minimal policy file in the share root. For example, to turn off missing_inherit violations for a single share:

echo '{"require_inherit": false}' > /volume1/docs/synaudit-policy.json

All other defaults still apply. No --policy flag needed.

Single-Path Policy

A flat JSON object applied to whatever path is being scanned:

{
  "owner": "owen",
  "require_inherit": true,
  "warn_ownership_drift": true,
  "acl_entries": [
    "group:administrators:allow:rwxpdDaARWc--:fd--",
    "user:owen:allow:rwxpdDaARWc--:fd--"
  ],
  "exclude": ["@eaDir", "#recycle", "#snapshot", ".DS_Store"]
}

Multi-Root Policy

A single file mapping different scan roots to different policies. Per-path settings override defaults. Useful as a system-wide config:

{
  "defaults": {
    "require_inherit": true,
    "warn_ownership_drift": true,
    "exclude": ["@eaDir", "#recycle", "#snapshot", ".DS_Store"]
  },
  "paths": {
    "/volume1/docs": {
      "owner": "owen",
      "acl_entries": [
        "group:administrators:allow:rwxpdDaARWc--:fd--",
        "user:owen:allow:rwxpdDaARWc--:fd--"
      ]
    },
    "/volume1/photos": {
      "owner": "photo_user"
    }
  }
}

The format is auto-detected: if the top-level JSON has a paths key, it is treated as multi-root. Scan roots not listed in paths get the defaults.

Ownership Drift Detection

When warn_ownership_drift is enabled (default) and no explicit owner is configured, synaudit records the owner of the scan root directory. Any item below with a different owner is flagged as a warning. This catches accidental chown deep in a share without requiring you to specify expected ownership.

If owner is set explicitly, it takes precedence (exact match enforcement). Drift detection only activates when owner is not configured.

Setting "owner": "*" disables both ownership enforcement and drift detection for a path. This is useful for subtrees with intentionally varied ownership (e.g., home directories where each user owns their own files).

Checks Performed

Violation Description Fixable
missing_inherit Item lacks the is_inherit archive flag Yes (synoacltool -enforce-inherit)
wrong_owner Owner does not match policy Yes (synoacltool -set-owner)
missing_acl_entry Required ACL entry not present Yes (synoacltool -add)
ownership_drift Owner differs from scan root (warning) No (informational only)
linux_mode Item is in POSIX/Linux mode, has no Synology ACL Yes (synoacltool -set-archive + enforce-inherit)

Output

Terminal

On a TTY, synaudit shows a live progress line while scanning:

Scanning /volume1/docs/projects/2024/reports  [342/1,234 dirs · 5 violations]

The directory count comes from a fast BFS pre-scan (directories only, no synoacltool calls, bounded by --prescan-timeout). If the pre-scan times out, the count is a lower bound shown with a + suffix.

When the scan completes, a summary is printed:

/volume1/docs
  Scanned: 12,456 items (3,201 directories, 9,255 files)
  Violations: 23
    - missing_inherit: 18
    - ownership_drift: 5

When stdout is not a TTY (piped or redirected), the progress line is suppressed.

Log File

A detailed TAB-separated log is always written (default: synaudit-TIMESTAMP.log):

2026-02-12T10:30:00	VIOLATION	/volume1/docs/dir1	missing_inherit
2026-02-12T10:30:01	OK	/volume1/docs/dir2
2026-02-12T10:30:02	ERROR	/volume1/docs/dir3	permission denied
2026-02-12T10:30:03	FIX	/volume1/docs/dir4	enforce_inherit	SUCCESS
2026-02-12T10:30:04	SKIP_FIX	/volume1/docs/dir5	chown	owen

The log is machine-parseable (TAB-delimited fields, one entry per line).

Design Decisions

Directory Traversal

synaudit uses a two-phase approach:

  1. Pre-scan (BFS): A fast breadth-first count of directories only. No files are read, no synoacltool calls are made. BFS is used here so that a timeout produces a useful lower bound — breadth explored rather than one deep subtree.

  2. Audit scan (DFS): The full scan uses depth-first traversal. DFS is preferred because:

    • IO locality: on spinning disks (common on NAS), descending into a directory right after reading it keeps the disk head near the same area
    • Memory efficiency: stack depth bounded by tree depth (typically <100), versus BFS queue bounded by the widest level (could be thousands)
    • Convention: matches find, rsync, du, and every standard Unix tree tool

Safety

  • Path validation: All scan roots must match /volumeN/sharename/.... Paths like /, /volume1, /etc, or /usr are rejected.
  • No file content access: synaudit never opens, reads, writes, or deletes file data. It only reads and modifies ACL metadata.
  • No ACL removal: The tool only adds missing ACL entries and enforces inheritance. It never removes existing entries.
  • Interactive by default: fix prompts for each change unless --yes or --dry-run is given.

Building from Source

Requires Go 1.21 or later.

make              # Show all targets
make build        # Build for current platform
make test         # Run tests with race detector
make lint         # Run golangci-lint
make release      # Cross-compile linux/amd64 and linux/arm64
make install      # Copy to /usr/local/bin

Examples

# Zero-config audit
synaudit scan /volume1/docs

# Audit multiple shares
synaudit scan /volume1/docs /volume1/photos /volume1/music

# Audit with a policy file
synaudit scan /volume1/docs --policy policy.json

# Skip ownership checks
synaudit scan /volume1/docs --ignore-owner

# Preview fixes
synaudit fix /volume1/docs --dry-run

# Apply fixes interactively
synaudit fix /volume1/docs --policy policy.json

# Apply all fixes without prompting
synaudit fix /volume1/docs --policy policy.json --yes

# Fix only inheritance issues
synaudit fix /volume1/docs --ignore-owner --yes

License

BSD 2-Clause. See LICENSE.

About

Synology ACL audit and remediation tool

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages