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
synauditis 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 thatsynauditdid to my system, due to an incorrect policy, is change permissions on my home directory and~/.sshso that incoming SSH connections required a password. That was an easy fix.
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/synauditEach release includes SHA256 checksums for verification:
wget https://github.com/dmitrii/synaudit/releases/latest/download/checksums.txt
shasum -a 256 -c checksums.txtNo configuration file is needed. Point synaudit at a shared folder and go:
synaudit scan /volume1/docsThis will:
- Walk the directory tree, skipping system directories (
@eaDir,#recycle,#snapshot,.DS_Store) - Check that the
is_inheritflag 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/musicAudit 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 |
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 |
For each scan root, synaudit resolves policy in this order (first match wins):
- Explicit
--policyflag synaudit-policy.jsonin the directory being scanned/usr/local/etc/synaudit/policy.json(system-wide)- 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
The policies/ directory in this repository contains example policy files:
policy_default.json— the built-in defaults as a file, ready to copy and tweakpolicy_single.json— single-path policy with owner, ACL entries, and exclusionspolicy_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.
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.jsonAll other defaults still apply. No --policy flag needed.
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"]
}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.
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).
| 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) |
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.
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).
synaudit uses a two-phase approach:
-
Pre-scan (BFS): A fast breadth-first count of directories only. No files are read, no
synoacltoolcalls are made. BFS is used here so that a timeout produces a useful lower bound — breadth explored rather than one deep subtree. -
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
- Path validation: All scan roots must match
/volumeN/sharename/.... Paths like/,/volume1,/etc, or/usrare 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:
fixprompts for each change unless--yesor--dry-runis given.
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# 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 --yesBSD 2-Clause. See LICENSE.