[2/3] Add permissions command

[fdcastel]

Based on #478

Adds a new opkssh permissions command for checking and fixing file permissions/ACLs, and refactors the audit command infrastructure to support cross-platform permission validation.

This is the second of three PRs splitting the work from #389 (Windows SSH server support).

Changes

New permissions command

Adds opkssh permissions with three subcommands:

• permissions check — Verifies that all opkssh files have correct permissions/ACLs. Reports problems without modifying anything.
• permissions fix — Repairs permissions/ACLs on opkssh files (requires admin/root).
• permissions install — Non-interactive permission setup for use by installers. Sets up correct ownership, groups, and permissions for a fresh installation.

Permission infrastructure (policy/files/)

• PermInfo struct — Centralized definition of required file permissions (mode, owner, group, ACL entries) for each opkssh file type (system policy, home policy, providers, config, binary, log, plugin dir). Platform-specific implementations in perminfo_unix.go and perminfo_windows.go.
• ACL verification abstraction (acl.go, acl_unix.go, acl_windows.go) — Cross-platform interface for verifying file access control lists. Unix implementation checks POSIX modes; Windows implementation checks NTFS DACLs.
• File permission operations (fileperms_ops.go, fileperms_ops_windows.go) — Cross-platform file ownership and permission manipulation (chown, chmod, ACL modification).
• permschecker_common.go — Shared permission checker code extracted from the original permschecker.go.
• permschecker_windows.go — Windows-specific permission checker using ACL APIs.
• Windows SID utilities (sid_windows.go) — Helper for resolving Windows Security Identifiers.

Audit command refactors

• Platform-independent paths: Replaced hardcoded /etc/opk/ paths with policy.GetSystemConfigBasePath() and policy.SystemDefaultProvidersPath/SystemDefaultPolicyPath.
• Shared permission checking: Extracted CheckFilePermissions() function used by both audit and permissions commands.
• Platform-specific user enumeration: Moved /etc/passwd parsing to audit_enum_unix.go; added audit_enum_windows.go for Windows user profile enumeration via registry.
• Windows audit support: Added audit_windows_profiles.go for enumerating Windows user profiles, and audit_windows_test.go for Windows-specific audit tests.
• Updated audit flags: Default paths now use platform-aware constants; --skip-user-policy defaults to true on Windows.

Policy refactors

• Platform-specific paths (paths_unix.go, paths_windows.go): GetSystemConfigBasePath() returns /etc/opk on Unix, %ProgramData%\opk on Windows.
• policyloader.go: Uses filepath.Join + GetSystemConfigBasePath() instead of hardcoded paths.
• multipolicyloader.go: Moved ReadWithSudoScript to platform-specific files (multipolicyloader_unix.go for sudo, multipolicyloader_windows.go returning unsupported error).
• plugins.go: Export RequiredPolicyDirPerms() for use by the permissions command.

Other changes

• commands/elevate_unix.go / elevate_windows.go: Platform-specific elevation detection (root check on Unix, admin check on Windows).
• commands/verify_test_unix.go: Moved Linux-specific verify tests to build-tagged file.
• commands/add_test.go: Removed test case that relied on platform-specific permission behavior.
• policy/plugins/plugins_test.go: Removed permission-specific test cases that don't work cross-platform (file mode checks on Windows behave differently).
• docs/audit.md: Documents the relationship between audit and permissions commands.

Testing

• All existing tests pass on both Linux and Windows.
• New tests: audit_permissions_test.go, audit_windows_test.go, permissions_test.go, permissions_fix_nonwindows_test.go, permissions_fix_windows_test.go, permissions_install_test.go, permissions_mocks_test.go.

Related

• Part 2 of 3 from Adds support to OpenSSH Servers on Windows. #389
• Addresses feedback from Adds support to OpenSSH Servers on Windows. #389 reviews (PermInfo struct, centralized permissions)
• Related to Create command to look FOR misconfigurations #388 (audit command improvements)

[fdcastel]

Rebased onto the latest main.

[fdcastel]

Rebased onto the latest main.

@EthanHeilman: this one’s up next in the queue 😉
@Basti-Fantasti: if you could, we’d really appreciate your thoughts as well.

I’m happy to take care of any changes or fixes you’d like.

[EthanHeilman]

@fdcastel Looking forward to reviewing this. I won't have time until next week, 55 files is a lot of files to review =)

[fdcastel]

I completely understand. Yes, there are quite a few changes related to infrastructure updates and other refactors that I picked up along the way. I tried to split them between this PR and the next one.

If you have any suggestions, I could look into breaking this down into smaller PRs.

I’ll try to explore an approach along those lines, if time permits.

[EthanHeilman]

Not a complete review, but all the time I had today

[fdcastel]

Rebased onto the latest main. Made the following changes based on feedback:

1. Copyright year — Updated Copyright 2025 → Copyright 2026 in all 16 new files.

2. License headers — Added full Apache 2.0 license headers to elevate_unix.go and elevate_windows.go.

3. Octal notation — Changed all raw octal literals (0640, 0750, 0600) to use the explicit 0o prefix (0o640, 0o750, 0o600) in code and comments across perminfo_unix.go, perminfo_windows.go, permschecker_common.go, perminfo.go, and test files.

4. Struct-based PermissionsCmd — Refactored permissions.go from package-level variables (DefaultFs, ConfirmPrompt, IsElevatedFunc, RunPermissionsFixWithDepsFn) to a PermissionsCmd struct with Fs, Out, ErrOut, In, Ops, ACLVerifier, IsElevatedFn, and ConfirmPrompt fields — matching the AuditCmd pattern. Updated main.go and all 5 test files accordingly.

5. --json flag — Added --json/-j flag to both permissions check and permissions fix subcommands, outputting structured JSON via json.Encoder.

6. Renamed etcPasswdRow → userHomeEntry — Made the struct name platform-generic across audit.go, audit_enum_unix.go, audit_enum_windows.go, audit_windows_profiles.go, and audit_test.go.

7. Error handling comments — Added inline comments in audit_windows_profiles.go explaining why each continue (stale registry entries, incomplete profiles, orphaned SIDs) is intentionally silent.

8. New tests — Added audit_enum_unix_test.go and audit_enum_windows_test.go with unit tests for enumerateUserHomeDirs on both platforms.

[EthanHeilman]

Probably too big of an ask, but the permissions issue adds a lot of complex and files, is there anyway to create a mockable files struct that hides and abstracts away all the permission and filesystem details.

[fdcastel]

Probably too big of an ask, but the permissions issue adds a lot of complex and files, is there anyway to create a mockable files struct that hides and abstracts away all the permission and filesystem details.

I understand. No problem!

I’m a bit tight on schedule right now, but give me a few days and I’ll come back with something.

Also, if you wish/have any suggestions on how to split this PR into smaller sub-PRs, I’m all ears. 😄

[fdcastel]

@EthanHeilman I've implemented an unified mockable FileSystem interface you suggested.

This is just a first attempt. If you're not happy with it, we can always roll it back and try a different approach.

Do not hesitate to suggest alternative paths -- I’m totally open to them!

---

Summary of changes

New: policy/files/filesystem.go — A single FileSystem interface that combines:

• File I/O (Stat, Exists, Open, ReadFile, MkdirAll, CreateFile, WriteFile)
• Permission mutations (Chmod, Chown, ApplyACE)
• Permission checking (CheckPerm, VerifyACL)

The NewFileSystem(afero.Fs) constructor wires up the platform-specific FilePermsOps, PermsChecker, and ACLVerifier behind this single interface. A WithCmdRunner functional option allows tests to inject a mock command runner.

Refactored PermissionsCmd — Now has a single FileSystem files.FileSystem field instead of three separate fields (Fs, Ops, ACLVerifier). All methods use p.FileSystem.* uniformly.

Refactored AuditCmd — Added FileSystem files.FileSystem field. Permission checking via CheckFilePermissions now takes a FileSystem instead of separate checker + verifier arguments.

Refactored CheckFilePermissions — Signature simplified from (afero.Fs, files.PermsChecker, files.ACLVerifier, path, permInfo) → (files.FileSystem, path, permInfo).

Simplified test mocks — A single mockFileSystem struct implements the interface, replacing the previous mockFilePermsOps + mockACLVerifier pattern. Tests now create mocks with one struct instead of three separate components.

Files changed (12 files)

File	Change
policy/files/filesystem.go	New — unified interface + default implementation
commands/permissions.go	Uses FileSystem instead of Fs/Ops/ACLVerifier
commands/permcheck.go	Simplified CheckFilePermissions signature
commands/audit.go	Uses FileSystem for permission checks
commands/permissions_mocks_test.go	Single mockFileSystem replaces two separate mock types
commands/permissions_fix_nonwindows_test.go	Updated to use mockFileSystem
commands/permissions_fix_windows_test.go	Updated to use mockFileSystem
commands/permissions_install_test.go	Updated to use mockFileSystem
commands/permissions_test.go	Uses newTestPermissionsCmd with WithCmdRunner
commands/audit_test.go	Uses files.NewFileSystem with WithCmdRunner
commands/audit_permissions_test.go	Uses files.NewFileSystem with WithCmdRunner
commands/audit_enum_*_test.go	Uses files.NewFileSystem with WithCmdRunner

All existing tests pass on both platforms. CI is green.

[fdcastel]

Awesome feedback, @EthanHeilman!! And great catches, too.

I’ll start working on these shortly.

[fdcastel]

All review feedback from the latest round has been addressed in commit d49f93a. Summary of changes:

Naming & structure:

• Merged AuditCmd.Fs (afero.Fs) and AuditCmd.FileSystem (files.FileSystem) into a single Fs files.FileSystem field — now audit_enum_unix.go uses a.Fs.Exists()/a.Fs.ReadFile() instead of raw afero calls
• Renamed RequiredPerms.ProvidersDir → RequiredPerms.Providers (it's a file, not a directory)
• Renamed verify_test_unix.go → verify_unix_test.go so Go recognizes it as a test file
• Removed expectedSystemOwner() and platform.go/platform_*_test.go — trivial helper with no real value
• Removed acl_unit_test_nonwindows.go — skip-only test file, no value

Permissions checks:

• Providers is now treated as a file throughout (chmod+chown, not mkdir)
• Added RequiredPerms.Config for config.yml permission checks
• permissions check and permissions fix now handle config.yml (chmod/chown when it exists)
• Fixed plugins dir group check: now passes RequiredPerms.PluginsDir.Group instead of ""

Mock fixes:

• mockFileSystem.MkdirAll, .Chmod, .WriteFile now use the actual perm parameter instead of hardcoded values
• The Created/ChmodCalled/ChownCalled booleans are asserted in permissions_fix_nonwindows_test.go and permissions_install_test.go

Other:

• Added Apache 2.0 license header to audit_windows_test.go

All 17 CI checks pass (including Windows tests and all integration tests).

[EthanHeilman]

This is looks good enough to merge. There are some architectural changes I want to make in this code, but it will go quicker if I make them after windows support is merged.