System Extensions

RSS for tag

Install and manage user space code that extends the capabilities of macOS using System Extensions.

Posts under System Extensions tag

72 Posts

Post

Replies

Boosts

Views

Activity

NE System Extension stuck on Validation By Category
Hello, I'm having some problems when install my Packet Tunnel network extension as system extension on my mac(macos 15.0). It stuck on Validation By Category. (it works well as NE app extension on ios) systemextensionsctl list --- com.apple.system_extension.network_extension enabled active teamID bundleID (version) name [state] <...> com.myteam.balabalabla.ne (1.0/1) - [validating by category] This is my install System Extension Code sample public class SystemExtension: NSObject, OSSystemExtensionRequestDelegate { private let forceUpdate: Bool private let inBackground: Bool private let semaphore = DispatchSemaphore(value: 0) private var result: OSSystemExtensionRequest.Result? private var properties: [OSSystemExtensionProperties]? private var error: Error? private init(_ forceUpdate: Bool = false, _ inBackground: Bool = false) { } // some request function i overwrite public func activation() throws -> OSSystemExtensionRequest.Result? { let request = OSSystemExtensionRequest.activationRequest(forExtensionWithIdentifier: FilePath.packageName + ".myNeName", queue: .main) request.delegate = self OSSystemExtensionManager.shared.submitRequest(request) semaphore.wait() if let error { throw error } return result } public func getProperties() throws -> [OSSystemExtensionProperties] { let request = OSSystemExtensionRequest.propertiesRequest(forExtensionWithIdentifier: FilePath.packageName + ".myNeName", queue: .main) request.delegate = self OSSystemExtensionManager.shared.submitRequest(request) semaphore.wait() if let error { throw error } return properties! } public nonisolated static func install(forceUpdate: Bool = false, inBackground: Bool = false) async throws -> OSSystemExtensionRequest.Result? { try await Task.detached { try SystemExtension(forceUpdate, inBackground).activation() }.result.get() } public nonisolated static func uninstall() async throws -> OSSystemExtensionRequest.Result? { try await Task.detached { try SystemExtension().deactivation() }.result.get() } } // And other methods I follow this post Your Friend the System Log and use this command line to collect log. After I initiated the system extension request sudo log collect --last 5m Here is my log (),I only pasted some code snippets that caught me, full version see attachments.(only include com.apple.sysextd), if need more, plz ask me. 1. Some policy missing ```log 22:00:13.818257 `sysextd` extension mockTeamID app.balabala.com.mockbalabala (1.0/1) advancing state from staging to validating 22:00:13.818263 sysextd returning cdhash for local arch arm64 of extension app.balabala.com.mockbalabala info 2025-05-01 22:00:13.818336 sysextd Extension with identifier <private> reached state <private> 22:00:13.819185 sysextd [0x9a2034b00] activating connection: mach=false listener=false peer=false name=com.apple.CodeSigningHelper 22:00:13.819911 sysextd [0x9a2034b00] invalidated after the last release of the connection object 22:00:13.821024 sysextd making activation decision for extension with teamID teamID("mockTeamID ), identifier app.balabala.com.mockbalabala 22:00:13.821026 sysextd no related kext found for sysex `app.balabala.com.mockbalabala` 22:00:13.821027 sysextd no extension policy -- activation decision is UserOption nesessionmanager.system-extensions interrupted 22:00:14.313576 sysextd [0x9a2178280] invalidated because the client process (pid 1886) either cancelled the connection or exited 22:00:14.542154 sysextd connection to com.apple.nesessionmanager.system-extensions interrupted 22:00:14.542319 sysextd [0x9a2178000] Re-initialization successful; calling out to event handler with XPC_ERROR_CONNECTION_INTERRUPTED 22:00:14.542351 sysextd connection to com.apple.nesessionmanager.system-extensions interrupted 22:00:14.589375 nesessionmanager [0x6c80e4500] activating connection: mach=true listener=false peer=false name=com.apple.sysextd And when i debug the System Extension code i notice the request Error catch by didFailWithError public func request(_: OSSystemExtensionRequest, didFailWithError error: Error) { self.error = error semaphore.signal() } error is OSSystemExtensionErrorDomain code 1 This problem has been bothering me for a long time, I would appreciate any help, if need more info, comment, thank you.
3
0
269
May ’25
How to avoid my local server flows in Transparent App Proxy
I have written the Transparent App Proxy and can capture the network flow and send it to my local server. I want to avoid any processing on the traffic outgoing from my server and establish a connection with a remote server, but instead of connecting to the remote server, it again gets captured and sent back to my local server. I am not getting any clue on how to ignore these flows originating from my server. Any pointers, API, or mechanisms that will help me?
9
2
297
Apr ’25
How to develop system extension if System Integrity Protection is enabled?
Hi I am developing the packet tunnel extension on a SIP enabled device. If I build the app and notarize and install it on the device, it works fine. If I modify, build and execute the App (which contains the system extension), it fails with below error. 102.3.1.4 is production build. And 201.202.0.101 is for XCode build. SystemExtension "&lt;&lt;complete name&gt;&gt;.pkttunnel" request for replacement from 102.3.1.4 to 201.202.0.101 Packet Tunnel SystemExtension "&lt;&lt;complete name&gt;&gt;.pkttunnel" activation request did fail: Error Domain=OSSystemExtensionErrorDomain Code=8 "(null)" If SIP is disabled, it works fine. Is there a way the system extension can be developed even if SIP remains enabled?
1
0
140
Apr ’25
Title: DNS Proxy Not Capturing Traffic When Public DNS Is Set in WiFi Settings
I'm working on a Network Extension using NEDNSProxyProvider to inspect DNS traffic. However, I've run into a couple of issues: DNS Proxy is not capturing traffic when a public DNS (like 8.8.8.8 or 1.1.1.1) is manually configured in the WiFi settings. It seems like the system bypasses the proxy in this case. Is this expected behavior? Is there a way to force DNS traffic through the proxy even if a public DNS is set? Using DNS Proxy and DNS Settings simultaneously doesn't work. Is there a known limitation or a correct way to combine these? How to set DNS or DNSSettings using DNSProxy? import NetworkExtension import SystemExtensions import SwiftUI protocol DNSProxyManagerDelegate { func managerStateDidChange(_ manager: DNSProxyManager) } class DNSProxyManager: NSObject { private let manager = NEDNSProxyManager.shared() var delegate: DNSProxyManagerDelegate? private(set) var isEnabled: Bool = false { didSet { delegate?.managerStateDidChange(self) } } var completion: (() -> Void)? override init() { super.init() self.load() } func toggle() { isEnabled ? disable() : start() } private func start() { let request = OSSystemExtensionRequest .activationRequest(forExtensionWithIdentifier: Constants.extensionBundleID, queue: DispatchQueue.main) request.delegate = self OSSystemExtensionManager.shared.submitRequest(request) log.info("Submitted extension activation request") } private func enable() { update { self.manager.localizedDescription = "DNS Proxy" let proto = NEDNSProxyProviderProtocol() proto.providerBundleIdentifier = Constants.extensionBundleID self.manager.providerProtocol = proto self.manager.isEnabled = true } } private func disable() { update { self.manager.isEnabled = false } } private func remove() { update { self.manager.removeFromPreferences { _ in self.isEnabled = self.manager.isEnabled } } } private func update(_ body: @escaping () -> Void) { self.manager.loadFromPreferences { (error) in if let error = error { log.error("Failed to load DNS manager: \(error)") return } self.manager.saveToPreferences { (error) in if let error = error { return } log.info("Saved DNS manager") self.isEnabled = self.manager.isEnabled } } } private func load() { manager.loadFromPreferences { error in guard error == nil else { return } self.isEnabled = self.manager.isEnabled } } } extension DNSProxyManager: OSSystemExtensionRequestDelegate { func requestNeedsUserApproval(_ request: OSSystemExtensionRequest) { log.info("Extension activation request needs user approval") } func request(_ request: OSSystemExtensionRequest, didFailWithError error: Error) { log.error("Extension activation request failed: \(error)") } func request(_ request: OSSystemExtensionRequest, foundProperties properties: [OSSystemExtensionProperties]) { log.info("Extension activation request found properties: \(properties)") } func request(_ request: OSSystemExtensionRequest, didFinishWithResult result: OSSystemExtensionRequest.Result) { guard result == .completed else { log.error("Unexpected result \(result.description) for system extension request") return } log.info("Extension activation request did finish with result: \(result.description)") enable() } func request(_ request: OSSystemExtensionRequest, actionForReplacingExtension existing: OSSystemExtensionProperties, withExtension ext: OSSystemExtensionProperties) -> OSSystemExtensionRequest.ReplacementAction { log.info("Existing extension willt be replaced: \(existing.bundleIdentifier) -> \(ext.bundleIdentifier)") return .replace } } import NetworkExtension class DNSProxyProvider: NEDNSProxyProvider { var handlers: [String: FlowHandler] = [:] var isReady = false let queue = DispatchQueue(label: "DNSProxyProvider") override func startProxy(options:[String: Any]? = nil, completionHandler: @escaping (Error?) -> Void) { completionHandler(nil) } override func stopProxy(with reason: NEProviderStopReason, completionHandler: @escaping () -> Void) { completionHandler() } override func handleNewUDPFlow(_ flow: NEAppProxyUDPFlow, initialRemoteEndpoint remoteEndpoint: NWEndpoint) -> Bool { let id = shortUUID() handlers[id] = FlowHandler(flow: flow, remoteEndpoint: remoteEndpoint, id: id, delegate: self) return true } override func handleNewFlow(_ flow: NEAppProxyFlow) -> Bool { return false } } class FlowHandler { let id: String let flow: NEAppProxyUDPFlow let remoteEndpoint: NWHostEndpoint let delegate: FlowHandlerDelegate private var connections: [String: RemoteConnection] = [:] private var pendingPacketsByDomain: [String: [(packet: Data, endpoint: NWEndpoint, uniqueID: String, timestamp: Date)]] = [:] private let packetQueue = DispatchQueue(label: "com.flowhandler.packetQueue") init(flow: NEAppProxyUDPFlow, remoteEndpoint: NWEndpoint, id: String, delegate: FlowHandlerDelegate) { log.info("Flow received for \(id) flow: \(String(describing: flow))") self.flow = flow self.remoteEndpoint = remoteEndpoint as! NWHostEndpoint self.id = id self.delegate = delegate defer { start() } } deinit { closeAll(nil) } func start() { flow.open(withLocalEndpoint: flow.localEndpoint as? NWHostEndpoint) { error in if let error = error { self.delegate.flowClosed(self) return } self.readFromFlow() } } func readFromFlow() { self.flow.readDatagrams { packets, endpoint, error in if let error = error { self.closeAll(error) return } guard let packets = packets, let endpoints = endpoint, !packets.isEmpty, !endpoints.isEmpty else { self.closeAll(nil) return } self.processFlowPackets(packets, endpoints) self.readFromFlow() } } } Any insights or suggestions would be greatly appreciated. Thanks!
2
3
282
Apr ’25
packet-tunnel-provider-systemextension doesn't work
I am currently creating a MacOS app that uses NetworkExtension and SystemExtension without going through the Store. Using entitlements, I manually codesign and create a pkg Installer, but when I run it I get an error message saying "No matching profile found." Below is the log /Applications/Runetale.app/Contents/MacOS/Runetale not valid: Error Domain=AppleMobileFileIntegrityError Code=-413 "No matching profile found" UserInfo={NSURL=file:///Applications/Runetale.app/, unsatisfiedEntitlements=&lt;CFArray 0x71c040fa0 [0x1f7bec120]&gt;{type = immutable, count = 3, values ​​= ( 0 : &lt;CFString 0x71c04f340 [0x1f7bec120]&gt;{contents = "com.apple.developer.system-extension.install"} 1 : &lt;CFString 0x71c1ccaf0 [0x1f7bec120]&gt;{contents = "com.apple.developer.networking.networkextension"} 2 : &lt;CFString 0x71c04fc00 [0x1f7bec120]&gt;{contents = "com.apple.developer.team-identifier"} )}, NSLocalizedDescription=No matching profile found} I looked into it myself and found that if you want to install the app without going through the Store, you need to use packet-tunnel-provider-systemextension instead of packet-tunnel-provider. here However, simply changing to packet-tunnel-provider-systemextension does not allow the build to pass. I use a build method that changes the value of entitlements only during codesign in order to pass the build. SYSEXT="$APP_BUNDLE/Contents/Library/SystemExtensions/com.runetale.desktop.PacketTunnel.systemextension" if [ -d "$SYSEXT" ]; then echo "Signing PacketTunnel system extension with entitlements..." cp macos/PacketTunnel/PacketTunnelRelease.entitlements macos/PacketTunnel/PacketTunnelRelease-sign.entitlements sed -i '' 's/packet-tunnel-provider/packet-tunnel-provider-systemextension/' macos/PacketTunnel/PacketTunnelRelease-sign.entitlements codesign --force --options runtime --timestamp --entitlements "$ENTITLEMENTS_FILE" --sign "$DEV_ID_APP_CERT" "$SYSEXT" fi # 3. Sign the entire .app bundle (deep sign by signing the outer app after inner ones) echo "Signing Runetale App with entitlements..." cp macos/Runner/Release.entitlements macos/PacketTunnel/Release-sign.entitlements sed -i '' 's/packet-tunnel-provider/packet-tunnel-provider-systemextension/' macos/PacketTunnel/Release-sign.entitlementsmacos/PacketTunnel/Release-sign.entitlements codesign --force --options runtime --timestamp --entitlements "$APP_ENTITLEMENTS_FILE" --sign "$DEV_ID_APP_CERT" "$APP_BUNDLE" Is this build method wrong? The next solution I'm thinking of is as follows. Is there a way to write packet-tunnel-provider-systemextension directly to entitlments and pass the build? (provisioning profile?) Apply to forum and get permission to use packet-tunnel-provider-systemextension Thank you.
6
0
205
Apr ’25
How can user allow a content filter after previously choosing "Don't Allow"?
Our enterprise product uses a content filter, normally customers deploy MDM profiles to authorise and allow the content filter to work. Some customers however do not use these profiles, requiring them to enable the system extension in System Settings and allow the content filter via the popup below. If the user selects "Don't Allow", intentionally or by mistake, there does not appear to be an mechanism for them to change their mind and allow it instead. If the user fails to enable the system extension on the first prompt, there is an option to enable if via System Settings. There doesn't seem to be a similar option if they "Don't Allow" the content filter. How can the user allow a previously denied content filter?
2
0
144
Apr ’25
On-demand rules
I've implemented a custom system extension VPN for macOS using Packet Tunnel Provider. The VPN is configured with on-demand, and a rule to always connect whenever there's traffic: onDemandRules = [NEOnDemandRuleConnect()] As expected, if the VPN isn't active, all traffic gets blocked until it is ready. Not expected: In the following scenario, there is some 'traffic leak': Use only WiFi (not wired cable) Connect the VPN Disable the WiFi and wait for the VPN to disconnect Enable the WiFi Some packets are routed outside the VPN, and aren't being blocked Some moments after, all traffic will be blocked, and the VPN will start the 'connecting' process. Is the above scenario a 'known' issue? Can it be a race condition in the OS, where some packets can be sent after the network is brought back before the VPN process starts? Is there any way to fix this problem? P.S: I'm not using flags such as 'capture all network'
3
1
177
Apr ’25
XPC listener initialized in System Extesnion invalidates incoming connection under certain conditions
I found a problem where a process tries to connect to System Extension and connection is invalidated. XPC listener has to be disposed and initialized again. This happens when System Extension executes tasks in following order: NSXPCListener initialized NSXPCListener.resume() NSProvider.startSystemExtensionMode() Result: Connection is invalidated and not only that the client has to retry connection, nut also System Extension must reinitialize listener (execute step 1 and 2). However if I call NSProvider.startSystemExtensionMode() NSXPCListener initialized NSXPCListener.resume() It works as expected and even if the connection is invalidated/interrupted, client process can always reconnect and no other action is necessary in System Extension (no need to reinitialize XPC listener), In Apple docs about NSProvider.startSystemExtensionMode() it says that this method starts handling request, but in another online article written by Scott Knight I found that startSystemExtensionMode() also starts listener server. Is that right? PLease could you add this info into the docs if it is so? https://knight.sc/reverse%20engineering/2019/08/24/system-extension-internals.html I would like to use following logic: Call NSProvider.startSystemExtensionMode() only under certain circumstances - I have received some configuration that I need to process and do some setup. If I don't receive it, there is no reason to call startSystemExtensionMode() yet, I don't need to handle handleNewFlow() yet. Connect XPC client to System Extension under certain conditions. Ideally communicate with client even though System Extension is not handling network requests yet, that is without receiving handleNewFlow(). Basically I consider XPC and System Extension handling network requests as separate things. Is that correct, are they separate and independent? Does XPC communication really depend on calling startSystemExtensionMode()? Another potential issue: Is it possible that XPC listener fails to validate connection when client tries to connect before System Extension manages to complete init and park the main thread in CFRunLoop? Note: These querstions arose mostly from handling upgrades of System Extension (extension is already running, network filter is created and is connected and new version of the app upgrades System Exension). Thanks.
5
0
1.4k
Apr ’25
DNS Proxy network extension doesn't start even after saving preferences successfully
Hello, I'm having some problems starting my DNS proxy network extension. Even after I call NEDNSProxyManager.saveToPreference() successfully I don't see any logs from my dns proxy. This is the code from the user space app: import SwiftUI import NetworkExtension func configureDNSProxy() { let dnsProxyManager = NEDNSProxyManager.shared() dnsProxyManager.loadFromPreferences { error in if let error = error { print("Error loading DNS proxy preferences: \(error)") return } dnsProxyManager.localizedDescription = "my DNS proxy" let proto = NEDNSProxyProviderProtocol() proto.providerBundleIdentifier = "com.myteam.dns-proxy-tests.ne" dnsProxyManager.providerProtocol = proto // Enable the DNS proxy. dnsProxyManager.isEnabled = true dnsProxyManager.saveToPreferences { error in if let error = error { print("Error saving DNS proxy preferences: \(error)") } else { NSLog("DNS Proxy enabled successfully") } } } } @main struct dns_proxy_testsApp: App { var body: some Scene { WindowGroup { ContentView() } } init() { configureDNSProxy() } } This is the code for my network extension(DNSProxyProvider.swift): import NetworkExtension class DNSProxyProvider: NEDNSProxyProvider { override func startProxy(options:[String: Any]? = nil, completionHandler: @escaping (Error?) -> Void) { NSLog("dns proxy ne started") completionHandler(nil) } override func stopProxy(with reason: NEProviderStopReason, completionHandler: @escaping () -> Void) { NSLog("dns proxy ne stopped") completionHandler() } override func sleep(completionHandler: @escaping () -> Void) { NSLog("dns proxy ne sleep") completionHandler() } override func wake() { NSLog("dns proxy ne wake") } override func handleNewFlow(_ flow: NEAppProxyFlow) -> Bool { NSLog("dns proxy ne flow") return true } } The bundle identifier for my network extension is: com.myteam.dns-proxy-tests.ne and both the user space app and the network extension have the DNS Proxy capability. Both have the same app group capability with the same group name group.com.myteam.dns-proxy-test. The info.plist from the network extension look like this(I didn't really modify it from the default template created by xcode) <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>NetworkExtension</key> <dict> <key>NEMachServiceName</key> <string>$(TeamIdentifierPrefix)com.example.app-group.MySystemExtension</string> <key>NEProviderClasses</key> <dict> <key>com.apple.networkextension.dns-proxy</key> <string>$(PRODUCT_MODULE_NAME).DNSProxyProvider</string> </dict> </dict> </dict> </plist> In the logs I do see DNS Proxy enabled successfully and also I see: NESMDNSProxySession[Primary Tunnel:my DNS proxy:<...>:(null)] starting with configuration: { name = my DNS proxy identifier = <..> applicationName = dns-proxy-tests application = com.myteam.dns-proxy-tests grade = 1 dnsProxy = { enabled = YES protocol = { type = dnsProxy identifier = <...> identityDataImported = NO disconnectOnSleep = NO disconnectOnIdle = NO disconnectOnIdleTimeout = 0 disconnectOnWake = NO disconnectOnWakeTimeout = 0 disconnectOnUserSwitch = NO disconnectOnLogout = NO includeAllNetworks = NO excludeLocalNetworks = NO excludeCellularServices = YES excludeAPNs = YES excludeDeviceCommunication = YES enforceRoutes = NO pluginType = com.myteam.dns-proxy-tests providerBundleIdentifier = com.myteam.dns-proxy-tests.ne designatedRequirement = identifier "com.myteam.dns-proxy-tests.ne" <...> /* exists */ } } } But then I see: Checking for com.myteam.dns-proxy-tests.ne - com.apple.networkextension.dns-proxy But then finally Found 0 registrations for com.myteam.dns-proxy-tests.ne (com.apple.networkextension.dns-proxy) So I think that last log probably indicates the problem. I'm a bit lost at what I'm doing wrong so I'd be super thankful for any pointer!
17
0
746
Mar ’25
DriverKit IOUSBHostInterface iterator always empty
I'm trying to iterate through a USB device but the iterator is always empty or contains only the matched interface: Single interface in Iterator This happens when my driver matches against the interface. Because I need to use 2 interfaces (control and cdc), I try to open the IOUSBHostDevice (copied from the interface) and iterate through the rest, but I only get the interface my dext matched with. Empty Iterator I decided to match against USB communication devices, thinking things would be different. However, this time the interface iterator is completely empty (provider is IOUSBHostDevice). Here's a snippet of my code before iterating with IOUSBHostDevice->CopyInterface(): // teardown the configured interfaces. result = device->SetConfiguration(ivars->Config, true); __Require_noErr_Action(result, _failure_Out, ELOG("IOUSBHostDevice::SetConfiguration failed 0x%x", result)); // open usb device result = device->Open(this, 0, 0); __Require_noErr_Action(result, _failure_Out, ELOG("Failed to open IOUSBHostDevice")); // Get interface iterator result = device->CreateInterfaceIterator(&iterRef); __Require_noErr_Action(result, _failure_Out, ELOG("IOUSBHostDevice::CreateInterfaceIterator failed failed: 0x%x", result));
1
0
296
Mar ’25
After the device wake ups, NEFilterDataProvider causes internet access issue intermittently
We have a NEFilterDataProvider extension that intercepts all TCP and UDP IPv4/6 traffic. At times just after wakeup from sleep, it causes internet access issues, such as showing "This site can't be reached" when opening websites. The traffic is not being dropped by the extension. According to the logs, the connection is being closed after approximately 4 minutes. During the issue, the flow logs are as follows: Flow 515129771 is connecting New flow: NEFlow type = stream, app = com.google.Chrome.helper... Detaching, ref count = 2 (logged after ~4 minutes) Sending close, how = 2 Removing from group 2, ref count = 2 Destroying, app tx 0, tunnel tx 0, tunnel rx 0 Closing reads, not closed by plugin Closing writes, not sending close Any suggestions on the possible cause and how to further debug it?
2
0
235
Mar ’25