fix(seatbelt): allow AF_UNIX sockets and resolve symlinked root paths

[Carlos Alexandro Becker (caarlos0)]

📖 Description

Fixes two bugs in the macOS Seatbelt backend that made UNIX-domain sockets unusable and silently dropped most filesystem policy rules.

1. AF_UNIX sockets were never permitted

Seatbelt matches AF_UNIX sockets by path — bind() under network-bind, connect() under network-outbound — while allowLocalNetwork only emits network-inbound (local ip), which covers IP sockets. Any Node toolchain that uses an IPC pipe (tsx, vite, esbuild, jest workers) failed with:

Error: listen EPERM: operation not permitted /var/folders/…/T/tsx-501/51325.pipe

Both operations are now granted on readwritePaths. A UNIX socket is a filesystem object reachable only by processes that can traverse to its path, so using one where writes are already permitted grants no new capability. This is why the filesystem policy governs it rather than the network policy — gating it behind allowLocalNetwork would force real network ingress on just to run a build.

Because the rules are path-scoped they never widen IP binding or IP egress, which stay governed by defaultPolicy and allowLocalNetwork. Verified empirically: with only a (subpath …) filter present, TCP bind() and TCP connect() both still return EPERM.

readonlyPaths deliberately gets neither operation — a socket is a bidirectional channel, not a read.

2. Policy paths were emitted verbatim

/etc, /tmp, /var and /home are symlinks on macOS, and the kernel fully canonicalizes a path before matching it against a profile filter. A rule written against the unresolved path therefore never matches and is silently dead — no error, no diagnostic.

This also killed the automatic $TMPDIR grant, which resolves to /var/folders/…. Policy paths are now rewritten to their real targets before emission (/etc, /tmp, /var → /private/…; /home → /System/Volumes/Data/home). /Users needs no rewriting — it is a firmlink, not a symlink.

Escape closed as a side effect

Fixing (2) turns dead deny rules live as well as dead allow rules. While auditing that, an actual bypass was found and closed: deniedPaths now also denies network-outbound. defaultPolicy: "allow" and the remote-proxy fallback emit an unfiltered (allow network-outbound), which previously let the sandbox connect() to a pre-existing socket inside a denied subtree. A Docker, ssh-agent or gpg-agent socket is a control plane, so that was an escape.

Reproduced end to end — a listener planted in a deniedPaths subtree, with the sandbox connecting to it:

	Result
before	ESCAPE: PWNED
after	BLOCKED EPERM

Path normalization

Policy paths are also folded to a single canonical spelling before emission: redundant separators (//tmp), . segments (/./tmp) and a trailing / are collapsed. Seatbelt canonicalizes only the accessed path, not the filter, so a rule written with a redundant spelling is dead — and for deniedPaths that fails open. Confirmed with sandbox-exec: a deny on (subpath "//private/tmp/x/secret/") lets a write through, while the normalized spelling denies it.

A .. segment is rejected as a config error rather than resolved. macOS resolves .. physically, after following symlinks, so /tmp/.. is /private, not / — resolving it lexically could silently widen an allow rule to /, which is worse than the dead rule it replaces.

All of this is pure string work, so profile_builder stays platform-agnostic and unit-testable on Linux CI.

Path precedence

Most-restrictive-wins (deny > readonly > readwrite) is re-applied to the resolved paths. The shared config parser already applies it, but only to the raw strings — so readonlyPaths: ["/private/tmp/x"] and readwritePaths: ["/tmp/x"] survive it as distinct entries and collide only at emission. Seatbelt is last-match-wins and the read-write rule is emitted second, so without this the read-only intent would be silently lost.

Rule ordering

readonlyPaths and readwritePaths are emitted shallow-to-deep, one rule per path, reusing wxc_common::filesystem_resolve::resolve_path_plan — the same plan the Bubblewrap and LXC backends use. Last-match-wins then gives deepest-intent-wins, so a read-only entry nested inside a broader read-write subtree stays read-only. Since an allow can never take authority back, each read-only path also emits an explicit (deny file-write* network-bind network-outbound …).

deniedPaths stays outside that plan and is emitted after the network rules, so it still overrides the unfiltered (allow network-outbound).

Security tradeoff

AF_UNIX connect() is a capability that file-write* alone did not grant. A sandbox with a broad readwritePaths root can now reach any pre-existing listener underneath it, and a control socket (Docker, ssh-agent, gpg-agent) is a meaningful target. Documented in the backend guide: prefer a narrow read-write root, and put sensitive sockets in deniedPaths, which overrides the grant.

Known limitation

.. is rejected on this backend only, while the shared parser accepts it — a cross-backend policy using .. will fail on macOS and run elsewhere. That is intentional: the alternative is the silently-dead rule this PR exists to remove. Resolving it correctly needs std::fs::canonicalize against the live filesystem.

For the same reason, only root symlinks are resolved. A policy path that traverses a non-root symlink still produces a rule that never matches; for deniedPaths that fails open. Fixing it needs std::fs::canonicalize, which would break profile_builder's platform-agnostic purity (it is pure string generation, unit-tested on every host including Linux CI). Left as a separate change — Bubblewrap already solves the equivalent problem with resolve_through_symlinks in bwrap_runner.rs.

🔗 References

• docs/macos-support/seatbelt-backend.md — updated with the new rule tables, a #### Path resolution section, and a #### UNIX-domain sockets section explaining the rationale and the two intentional asymmetries.

🔍 Validation

Automated

• cargo test -p seatbelt_common → 62 passed, 0 failed (was 45 before; 17 new tests cover socket ops, readonly exclusion, deny ordering vs. the unfiltered outbound allow, root-symlink resolution incl. whole-segment matching and idempotence, lexical spelling normalization / .. rejection, resolved-path precedence for aliased spellings, and depth ordering in both nesting directions)
• cargo clippy -p seatbelt_common --all-targets -- -D warnings → clean
• cargo test -p seatbelt_common -p wxc_common -p mxc_engine -p mxc-sdk -p mxc_darwin → all green, 0 failed

Manual, with a real mxc-exec-mac build

Scenario	Result
defaultPolicy: "block", raw $TMPDIR in readwritePaths, bind + connect on a .pipe (the reported failure)	LISTEN_OK / CONNECT_OK / SERVER_GOT ping
same scenario on main	LISTEN_FAIL EPERM
bind inside a deniedPaths subtree	EPERM
connect to a pre-existing socket inside a deniedPaths subtree	EPERM (ESCAPE: PWNED before)
deny written as //private/tmp/x/secret/	denied (write went through before normalization)
readonlyPaths: ["/private/tmp/x"] + readwritePaths: ["/tmp/x"]	EPERM on write (was writable before resolved-path precedence)
readonlyPaths: ["/private/tmp/x/secret"] nested in readwritePaths: ["/tmp/x"]	EPERM on write (was writable before depth ordering)
readwritePaths: ["/private/tmp/x/build"] nested in readonlyPaths: ["/tmp/x"]	write succeeds — deeper intent still wins
TCP listen() under block, no allowLocalNetwork	EPERM — no IP-bind leak
TCP listen() under block with allowLocalNetwork: true	TCP_LISTEN_OK — existing behavior preserved
TCP connect() with only path-scoped outbound rules	EPERM — no IP-egress leak

Bypass probes — .., //, trailing slash, and the /tmp → /private/tmp alias were each attempted against a denied subtree; all correctly denied (the kernel canonicalizes before rule evaluation).

Pre-existing, unrelated build breakage on macOS (nanvix_common E0425, windows-future) was confirmed present on main, hence the targeted -p crate selection above rather than --workspace.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)
• If this PR changes Cargo.lock, the dependency-feed-check check passes (see docs/pull-requests.md)

📋 Issue Type

• Bug fix
• Feature
• Task

Microsoft Reviewers: Open in CodeFlow

[Carlos Alexandro Becker (caarlos0)]

Let me know if y'all think that the socket listen should be behind a new option.

[Copilot]

🟡 Changes recommended

Lexically equivalent root paths can still leave denied-path rules ineffective.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Fixes Seatbelt filesystem policy handling and AF_UNIX socket access on macOS.

Changes:

• Allows AF_UNIX sockets within read-write paths.
• Resolves known macOS root symlinks.
• Extends denied paths to block socket access.

File summaries

File	Description
src/backends/seatbelt/common/src/profile_builder.rs	Updates profile generation and tests.
docs/macos-support/seatbelt-backend.md	Documents path and socket behavior.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 3
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Changes recommended

Resolved path aliases can bypass read-only precedence and become writable.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Changes recommended

Nested read-only paths can retain write/socket authority, and valid paths containing .. are rejected only by Seatbelt.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (3)

src/backends/seatbelt/common/src/profile_builder.rs:181

• Resolved precedence still handles only identical paths. For example, readwritePaths: ["/tmp"] and readonlyPaths: ["/private/tmp/secret"] now produce a live broad read-write rule after the read-only rule; because the read-only rule does not deny file-write*, writes and the new socket operations remain allowed in secret. This conflicts with the repository's deepest-path-wins policy (wxc_common/src/filesystem_resolve.rs:12-16) and is a regression made reachable by resolving /tmp. Emit resolved intents shallow-to-deep and explicitly remove write/socket authority for read-only subtrees, with a regression test for this parent/child alias case.

        let mut readonly: Vec<String> = readonly;
        readonly.retain(|p| !denied.contains(p));
        readwrite.retain(|p| !denied.contains(p) && !readonly.contains(p));

src/backends/seatbelt/common/src/profile_builder.rs:558

• This adds a Seatbelt-only rejection for filesystem paths that the shared parser accepts and preserves (config_parser.rs:280-298). Concrete host paths can legitimately contain ..—especially across symlinked roots—so existing cross-backend policies now fail only on macOS. Resolve components with macOS filesystem semantics instead (for non-existent targets, canonicalize the longest existing prefix and append the remaining components safely) rather than requiring callers to know the host's symlink layout.

    if path.split('/').any(|seg| seg == "..") {
        return Err(format!(
            "Filesystem path '{path}' contains a '..' segment. macOS resolves '..' after \
             following symlinks, so the generated sandbox rule could not be matched \
             reliably; specify the fully resolved path instead."
        ));

docs/macos-support/seatbelt-backend.md:228

• The claim that this grants no new capability is incorrect: filesystem write permission alone did not authorize connect(), while the new network-outbound rule permits communication with any pre-existing listener under the read-write subtree. This matters for control sockets and should be documented as a security tradeoff so callers know to avoid broad read-write roots or exclude sensitive sockets.

This is deliberate. The socket is a filesystem object reachable only by
processes that can traverse to its path, so using one where writes are already
permitted grants no new capability — and Node toolchains (tsx, vite, esbuild,
jest workers) need it for their IPC pipes. Gating it behind `allowLocalNetwork`
would force real network ingress on just to run a build. Because the rules are
path-scoped they never widen IP binding or IP egress, which stay governed by
`defaultPolicy` and `allowLocalNetwork`.

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Changes recommended

A later unfiltered network allow can override the new read-only socket deny.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Changes recommended

Several comments and documentation statements contradict the implemented and tested Seatbelt rule-precedence behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (4)

docs/macos-support/seatbelt-backend.md:198

• This contradicts lines 184–186: the path-scoped deny beats an unfiltered outbound allow regardless of order. Last emission matters for overriding filtered read-write grants; documenting the actual distinction avoids making network-rule ordering look security-sensitive when it is not.

`deniedPaths` is not part of that plan — it is emitted after the network rules
so it also overrides the unfiltered `(allow network-outbound)`, which makes it
win outright regardless of depth.

docs/macos-support/seatbelt-backend.md:285

• The “required in addition to network-bind” claim conflicts with the generated default-block profile, which emits only network-inbound, and with this PR's validation that default-block plus allowLocalNetwork can listen successfully. Describe the observed behavior without requiring a rule that is absent in that configuration.

| `allowLocalNetwork: true` | `(allow network-inbound (local ip))` — required in addition to `network-bind` before the kernel will accept `listen()` on an IP socket. Independent of `defaultPolicy`, and unrelated to AF_UNIX sockets (see above). |

src/backends/seatbelt/common/src/profile_builder.rs:208

• This ordering rationale contradicts the filtered/unfiltered behavior pinned by readonly_socket_strip_survives_a_default_allow_outbound: a path-filtered deny overrides an unfiltered outbound allow regardless of order. Emitting deniedPaths last is required to override filtered path grants, not the unfiltered rule; please correct the comment so future changes do not preserve a nonexistent ordering constraint.

    // parent's write grant. `deniedPaths` is deliberately not part of this
    // plan: it is emitted after the network rules so it also overrides the
    // unfiltered `(allow network-outbound)`, which makes it win outright.

docs/macos-support/seatbelt-backend.md:194

• This overstates Seatbelt semantics: a later filtered allow can override an earlier filtered deny, as the shallow-to-deep design itself relies on. The reason for the explicit deny is specifically that allow file-read* does not revoke write/socket operations granted by a broader rule.

This issue also appears in the following locations of the same file:

• line 196
• line 285

read-write subtree stays read-only. Because an `allow` can never take authority
back from an earlier rule, each read-only path also emits an explicit
`(deny file-write* network-bind network-outbound …)`.

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Soham Das (SohamDas2021)]

Follow up:
This read-only network-outbound deny is defeated under defaultPolicy: "allow". It's emitted here in the allow phase, so the later unfiltered (allow network-outbound) wins under last-match-wins and re-enables AF_UNIX connect() on the read-only path - the explicit strip becomes a dead rule.
Fix: move the write_network_rules block before  write_filesystem_allow?

[Carlos Alexandro Becker (caarlos0)]

Checked this end-to-end and the strip holds — it isn't defeated under defaultPolicy: "allow".

Real mxc-exec-mac, real config (defaultPolicy: "allow", so the unfiltered (allow network-outbound) is emitted after the filesystem section), against a listener created outside the sandbox at /private/tmp/sbt7/ro/s.sock. The two runs differ in one character of config:

readonlyPaths:  ["/private/tmp/sbt7/ro"]   ->  CONNECT_DENIED [Errno 1] Operation not permitted
readwritePaths: ["/private/tmp/sbt7/ro"]   ->  CONNECT_OK

The control matters: it shows connect() genuinely is reachable there, so the first row is the strip winning rather than a capability that was never granted.

The reason is that Seatbelt's last-match-wins holds between rules that carry a filter. An unfiltered rule doesn't override a path-filtered one, in either direction:

fs deny, then unfiltered net allow  ->  EPERM      (current emission order)
unfiltered net allow, then fs deny  ->  EPERM      (the proposed order)
unfiltered net allow, no fs deny    ->  CONNECT_OK (control)

Filtered-vs-filtered does honour order (allow then deny on a path denies; reversed allows; shallow deny + deeper allow allows), which is what the shallow-to-deep emission relies on — so moving write_network_rules earlier would be a no-op here.

This is squarely my fault for how it was written up: the guide claimed plain last-match-wins without the filtered/unfiltered distinction, which makes the ordering look load-bearing when it isn't. Both Copilot and you read it the same way, which is a good sign the text was the problem.

Two things already landed / are up:

• readonly_socket_strip_survives_a_default_allow_outbound (in 6f70f7b, merged here) pins exactly this case — defaultPolicy: "allow" + readonlyPaths, asserting the strip is emitted and that the unfiltered allow still follows it, so the test stays meaningful if someone reorders.
• docs(seatbelt): correct rule-precedence and listen() rationale #754 corrects the docs and comments, including a related one I got backwards: network-inbound governs listen() on its own; network-bind alone is what's insufficient.

Happy to reorder anyway if you'd prefer the profile to read defensively, but it would be for legibility rather than a behavior fix.