Skip to content

Commit cf57c46

Browse files
mlwmlw
authored
Add network extension docs (#895)
This adds information about required profiles changes as well as installation/upgrade/verification instructions for the network extension. **New Page: Profiles: Network Extension:** <img width="3114" height="5902" alt="localhost_3000_deployment_profile-network-extension_" src="https://github.com/user-attachments/assets/04011018-e4ec-4338-9a23-d9d39abc117a" /> **New Page: Network Extension:** <img width="3114" height="3570" alt="localhost_3000_deployment_network-extension_" src="https://github.com/user-attachments/assets/ce07ab7e-e612-4295-8c3d-eecd12d60900" /> **Updated Page: Profiles: System Extension** <img width="3114" height="5994" alt="localhost_3000_deployment_profile-system-extension_" src="https://github.com/user-attachments/assets/27fdb7dc-9ab3-430b-824f-017eee13fc89" />
1 parent e843268 commit cf57c46

11 files changed

Lines changed: 243 additions & 7 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ compile_commands.json
1717
.cache/
1818
.vscode/*
1919
.zed**
20+
docs/superpowers/

‎docs/docs/deployment/install-package.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 7
2+
sidebar_position: 8
33
---
44

55
# Install Santa Package

‎docs/docs/deployment/migration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 8
2+
sidebar_position: 10
33
---
44

55
# Migration

‎docs/docs/deployment/network-extension.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
sidebar_position: 9
3+
---
4+
5+
# Network Extension
6+
7+
Santa includes an optional network [system
8+
extension](https://developer.apple.com/documentation/systemextensions) that can
9+
monitor and control network traffic. It provides two capabilities: a content
10+
filter for monitoring network flows and a DNS proxy for intercepting DNS queries.
11+
12+
:::info
13+
14+
The network extension requires a [Workshop](https://northpole.dev/) subscription
15+
and will not activate without one.
16+
17+
:::
18+
19+
## Installation
20+
21+
### Enabling the feature
22+
23+
Workshop customers must enable the network extension on a
24+
[tag](https://docs.workshop.cloud/tags). Navigate to the tag's sync
25+
settings and enable the **Network Extension** setting. The network extension
26+
will only be installed on hosts that are members of a tag with this setting
27+
enabled.
28+
29+
### Automatic installation
30+
31+
The network extension is lazily installed by default. Activating a network
32+
extension tears down all existing network connections, which can disrupt users.
33+
To minimize impact, Santa will automatically install or upgrade the network
34+
extension when:
35+
36+
- The system reboots
37+
- The system wakes from sleep (e.g. when the laptop lid opens)
38+
39+
The network extension [profiles](profile-network-extension.md) must be installed
40+
for automatic installation to succeed silently. If the profiles are not installed
41+
and a user is logged in, macOS will display its standard prompt asking the user
42+
to approve the extension.
43+
44+
### Manual installation
45+
46+
If you need to install the network extension immediately, you can trigger it
47+
manually:
48+
49+
```text
50+
sudo santactl install --network-extension
51+
```
52+
53+
:::caution
54+
55+
This will tear down existing network connections and can interrupt active
56+
network operations. Use with care.
57+
58+
:::
59+
60+
## Verification
61+
62+
You can check the status of the network extension using `santactl status`. The
63+
output includes a Network Extension section:
64+
65+
```text title="santactl status"
66+
>>> Network Extension
67+
Enabled | Yes
68+
Loaded | Yes
69+
```
70+
71+
- **Enabled** means the appropriate Workshop settings have been configured to
72+
allow the network extension to run on the system.
73+
- **Loaded** means the network extension has been installed and activated via the
74+
network extension provider configuration.
75+
76+
You can also run `santactl version` to view version information:
77+
78+
```text title="santactl version"
79+
santad | 2026.3 (build 187, commit 47a21b0d)
80+
santactl | 2026.3 (build 187, commit 47a21b0d)
81+
SantaGUI | 2026.3 (build 187, commit 47a21b0d)
82+
santanetd (BETA) | 2026.3 (build 187, commit 2149a1ce)
83+
```
84+
85+
If a newer version of the network extension is available, it will be noted in the
86+
output and installed on the next reboot or sleep/wake cycle.

‎docs/docs/deployment/profile-background.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 5
33
---
44

55
# Profiles: Background Apps

‎docs/docs/deployment/profile-configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 7
33
---
44

55
# Profiles: Santa Configuration

‎docs/docs/deployment/profile-network-extension.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Profiles: Network Extension
6+
7+
Santa includes an optional network [system
8+
extension](https://developer.apple.com/documentation/systemextensions) that can
9+
monitor and control network traffic. It provides two capabilities: a content
10+
filter for monitoring network flows and a DNS proxy for intercepting DNS queries.
11+
:::info
12+
13+
The network extension requires a [Workshop](https://northpole.dev/) subscription
14+
and will not activate without one.
15+
16+
:::
17+
18+
Like the endpoint security system extension, loading the network extension
19+
requires approval. For organizations deploying Santa, this step can be automated
20+
by sending an appropriate profile via an MDM.
21+
22+
Enabling the network extension requires two separate payloads: a
23+
[Web Content Filter](https://developer.apple.com/documentation/devicemanagement/webcontentfilter)
24+
payload for the content filter provider and a
25+
[DNS Proxy](https://developer.apple.com/documentation/devicemanagement/dnsproxy)
26+
payload for the DNS proxy provider.
27+
28+
:::warning
29+
30+
You must also update your [system extension profile](profile-system-extension.md)
31+
to allow the network extension. Without this, macOS will not permit the extension
32+
to load without manual user intervention.
33+
34+
:::
35+
36+
For installation and verification steps, see the
37+
[Network Extension](network-extension.md) page.
38+
39+
## Generating the profile
40+
41+
The process for adding these payloads to your machines will differ depending on
42+
which MDM you are using. Many MDMs have specific support for these kinds of
43+
profiles. In that case, you will need the following information:
44+
45+
### Content Filter
46+
47+
- Filter Type: `Plugin`
48+
- Plugin Bundle ID: `com.northpolesec.santa`
49+
- Filter Data Provider Bundle Identifier: `com.northpolesec.santa.netd`
50+
- Filter Data Provider Designated Requirement: `identifier "com.northpolesec.santa.netd" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] and certificate leaf[field.1.2.840.113635.100.6.1.13] and certificate leaf[subject.OU] = "ZMCG7MLDV9"`
51+
- Filter Sockets: `true`
52+
- Filter Packets: `false`
53+
54+
### DNS Proxy
55+
56+
- App Bundle Identifier: `com.northpolesec.santa`
57+
- Provider Bundle Identifier: `com.northpolesec.santa.netd`
58+
59+
## Example Profile
60+
61+
If your MDM doesn't have an option to add Content Filter or DNS Proxy profiles
62+
but does have the option for deploying custom profiles, you can use the following
63+
example as a template.
64+
65+
```xml showLineNumbers
66+
<?xml version="1.0" encoding="UTF-8"?>
67+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
68+
<plist version="1.0">
69+
<dict>
70+
<key>PayloadContent</key>
71+
<array>
72+
<dict>
73+
<key>PayloadType</key>
74+
<string>com.apple.webcontent-filter</string>
75+
<key>PayloadIdentifier</key>
76+
<string>com.northpolesec.santa.content-filter</string>
77+
<key>PayloadUUID</key>
78+
<string>A1B2C3D4-5555-6666-7777-888899990000</string>
79+
<key>PayloadVersion</key>
80+
<integer>1</integer>
81+
<key>PayloadDisplayName</key>
82+
<string>Santa Content Filter</string>
83+
<key>UserDefinedName</key>
84+
<string>Santa Content Filter</string>
85+
<key>FilterType</key>
86+
<string>Plugin</string>
87+
<key>PluginBundleID</key>
88+
<string>com.northpolesec.santa</string>
89+
<key>FilterDataProviderBundleIdentifier</key>
90+
<string>com.northpolesec.santa.netd</string>
91+
<key>FilterDataProviderDesignatedRequirement</key>
92+
<string>identifier "com.northpolesec.santa.netd" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] and certificate leaf[field.1.2.840.113635.100.6.1.13] and certificate leaf[subject.OU] = "ZMCG7MLDV9"</string>
93+
<key>FilterSockets</key>
94+
<true/>
95+
<key>FilterPackets</key>
96+
<false/>
97+
</dict>
98+
<dict>
99+
<key>PayloadType</key>
100+
<string>com.apple.dnsProxy.managed</string>
101+
<key>PayloadIdentifier</key>
102+
<string>com.northpolesec.santa.dns-proxy</string>
103+
<key>PayloadUUID</key>
104+
<string>A1B2C3D4-1111-2222-3333-444455556666</string>
105+
<key>PayloadVersion</key>
106+
<integer>1</integer>
107+
<key>PayloadDisplayName</key>
108+
<string>Santa DNS Proxy</string>
109+
<key>AppBundleIdentifier</key>
110+
<string>com.northpolesec.santa</string>
111+
<key>ProviderBundleIdentifier</key>
112+
<string>com.northpolesec.santa.netd</string>
113+
</dict>
114+
</array>
115+
<key>PayloadDisplayName</key>
116+
<string>Santa Network Extension</string>
117+
<key>PayloadIdentifier</key>
118+
<string>com.northpolesec.santa.netd.profile</string>
119+
<key>PayloadUUID</key>
120+
<string>A1B2C3D4-AAAA-BBBB-CCCC-DDDDEEEEFFFF</string>
121+
<key>PayloadType</key>
122+
<string>Configuration</string>
123+
<key>PayloadVersion</key>
124+
<integer>1</integer>
125+
<key>PayloadScope</key>
126+
<string>System</string>
127+
<key>PayloadDescription</key>
128+
<string>Enables the Santa network content filter and DNS proxy extensions.</string>
129+
</dict>
130+
</plist>
131+
```

‎docs/docs/deployment/profile-notifications.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 6
33
---
44

55
# Profiles: Notifications

‎docs/docs/deployment/profile-system-extension.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,18 @@ and malicious scripts from bypassing Santa. If you decide at some later point to
4141
uninstall Santa, you will need to remove the system extension profile before
4242
attempting to uninstall.
4343

44+
:::info Network Extension
45+
Enterprise deployments that include Santa's [network
46+
extension](profile-network-extension.md) should also allow the following in this
47+
profile:
48+
49+
- Allowed extension types: `NetworkExtension`
50+
- Allowed extensions: `com.northpolesec.santa.netd`
51+
52+
The highlighted lines in the example below include the network extension. These
53+
lines can be safely removed if you are not deploying the network extension.
54+
:::
55+
4456
## Example Profile
4557

4658
If your MDM doesn't have an option to add a System Extension profile but does
@@ -97,20 +109,26 @@ example as a template.
97109
<key>ZMCG7MLDV9</key>
98110
<array>
99111
<string>com.northpolesec.santa.daemon</string>
112+
<!-- highlight-next-line -->
113+
<string>com.northpolesec.santa.netd</string>
100114
</array>
101115
</dict>
102116
<key>AllowedSystemExtensionTypes</key>
103117
<dict>
104118
<key>ZMCG7MLDV9</key>
105119
<array>
106120
<string>EndpointSecurityExtension</string>
121+
<!-- highlight-next-line -->
122+
<string>NetworkExtension</string>
107123
</array>
108124
</dict>
109125
<key>NonRemovableSystemExtensions</key>
110126
<dict>
111127
<key>ZMCG7MLDV9</key>
112128
<array>
113129
<string>com.northpolesec.santa.daemon</string>
130+
<!-- highlight-next-line -->
131+
<string>com.northpolesec.santa.netd</string>
114132
</array>
115133
</dict>
116134
</dict>

‎docs/docs/deployment/profile-tcc.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 4
33
---
44

55
# Profiles: TCC

0 commit comments

Comments
 (0)