AlfaMacDriver

AlfaMacDriver is an experimental, open-source macOS DriverKit project for a MediaTek MT7921AU / MT7961 USB wireless adapter.

The project provides a user-space USBDriverKit driver, a versioned IOUserClient interface, a command-line control path, and integrations for monitor-mode capture workflows.

Warning

This is development software, not a production Wi-Fi driver. The current locally signed ad-hoc test build requires a dedicated test Mac, Reduced Security, and System Integrity Protection (SIP) to be disabled temporarily. Do not use this procedure on a primary or production computer.

Project status

Item	Status
Current release candidate	`0.2.31` (`33`)
Driver model	DriverKit / USBDriverKit user-space system extension
Target chipset	MediaTek MT7921AU / MT7961
USB identity	VID `0x0E8D`, PID `0x7961`, interface `3`
Logical interface name	`wlan1`
Capture link type	`DLT_IEEE802_11_RADIO` (`127`)
Native macOS Wi-Fi interface	Not implemented
Distribution signing and notarization	Not available
Intended audience	Driver developers, researchers, and authorized lab users

The current scope includes passive scanning, monitor mode, Radiotap capture, and explicitly authorized raw 802.11 frame injection. It does not provide station mode, authentication, association, internet connectivity, a BSD network interface, or CoreWLAN integration.

The name wlan1 is a project-level logical interface used by the supplied CLI and integrations. It does not appear in System Settings, the macOS Wi-Fi menu, ifconfig, or CoreWLAN.

Detailed implementation and hardware-validation notes are maintained in Documentation/CURRENT_STATUS.md.

Implemented capabilities

USBDriverKit matching and lifecycle management for the target USB interface.
Chip identity, revision, and endpoint-contract validation.
Bounded ROM Patch and WM RAM firmware loading.
Running-firmware adoption after a DriverKit extension upgrade.
DMA, UDMA, WFSYS, and radio initialization.
MCU responses through USB endpoint 0x84.
Monitor frames and TX-status events through USB endpoint 0x85.
Raw transmit queues through USB endpoints 0x04 through 0x07.
Monitor-mode enable and disable operations.
Country and channel allowlists.
Channel switching and fresh-result passive scanning.
Radiotap output in PCAPNG and classic PCAP containers.
USB-completion timestamps in capture output.
Explicitly authorized raw-frame injection through TXWI.
Fresh TX-status matching by packet ID and sequence, including ACK results.
Bounded RX-transfer resubmission and disconnect handling.
Wireshark Extcap, Kismet datasource, and Scapy integration paths.
Versioned and size-checked IOUserClient messages.
Defensive selector, scalar, descriptor, and output-length validation.

Not implemented

Native macOS station mode or normal Wi-Fi connectivity.
Authentication, association, DHCP, or IP networking.
A BSD network interface or CoreWLAN registration.
Access-point mode.
DFS-channel injection.
6 GHz injection.
Production distribution through Apple signing and notarization.
Production-grade long-duration or multi-client qualification.
Complete calibration and regulatory validation for every region and device.

Architecture

MT7921AU / MT7961 USB adapter
        |
        v
USBDriverKit system extension
        |
        +---- 0x84 MCU command responses
        +---- 0x85 monitor frames and TX status
        +---- 0x04..0x07 raw transmit queues
        |
        v
Versioned IOUserClient ABI
        |
        v
AlfaMacDriver application / CLI
        |
        +---- logical wlan1 interface
        +---- Wireshark Extcap
        +---- Kismet datasource
        +---- Scapy SuperSocket
        +---- PCAPNG / PCAP output

See Documentation/ARCHITECTURE.md for the component and data-flow design.

Requirements

A dedicated Apple-silicon test Mac is strongly recommended.
A recent version of macOS and Xcode with DriverKit and USBDriverKit SDKs.
Administrator access to the test Mac.
The target MT7921AU / MT7961 USB adapter.
Firmware files obtained independently from an authorized source.
An Apple Developer signing configuration for normal system-extension use, or an explicitly isolated local ad-hoc test setup.

Firmware binaries are not included in this repository. See Documentation/FIRMWARE.md for the pinned source, expected names, integrity hashes, and provenance notes.

Security preparation for the current local test build

Caution

The current ad-hoc development build requires SIP to be disabled temporarily. Disabling SIP removes important macOS protections and allows unauthorized code to run more easily. Use a dedicated test Mac, disconnect sensitive storage and accounts, and restore all security settings immediately after testing.

This requirement applies to the repository's current local ad-hoc testing workflow. It is not presented as a requirement for a future correctly signed and notarized release.

1. Back up and isolate the test Mac

Before changing security settings:

Back up any important data.
Do not use a work-managed or production Mac.
Sign out of unnecessary accounts and remove sensitive data.
Disconnect unrelated external storage and USB devices.

2. Enter macOS Recovery on Apple silicon

Shut down the Mac completely.
Press and hold the power button.
Release it when Loading startup options appears.
Select Options, then select Continue.
Authenticate with an administrator account when requested.

3. Select Reduced Security

In Recovery, open Utilities > Startup Security Utility.
Select the startup system and unlock it if required.
Select Security Policy.
Select Reduced Security.
Confirm the change with an administrator account.

Only change the options required by the isolated test environment. DriverKit is not a legacy kernel extension, so do not enable unrelated kernel-extension options unless another component in your test environment specifically needs them.

4. Disable System Integrity Protection

While still in Recovery:

Open Utilities > Terminal.
Run:

csrutil disable

Restart the Mac.
After macOS starts, verify the state:

csrutil status

The output must report that System Integrity Protection is disabled before the current local ad-hoc activation workflow is attempted.

5. Enable system-extension developer mode

In a normal Terminal session after restarting:

sudo systemextensionsctl developer on
systemextensionsctl developer

For the verified 0.2.31/33 local test environment, the status command reported:

Developer mode is on

Developer mode relaxes the normal application-location check for development. It does not replace the required entitlements, signatures, user approval, or other DriverKit checks.

6. Restore macOS security after testing

Do not leave the test Mac in this state.

First disable system-extension developer mode:

sudo systemextensionsctl developer off

Then restart into Recovery again, open Utilities > Terminal, and run:

csrutil enable

In Startup Security Utility, restore Full Security, then restart macOS. Verify the final SIP state:

csrutil status

The output should report that System Integrity Protection is enabled.

Apple references:

Building

Requirements

The current Xcode project requires:

macOS deployment target 26.0;
DriverKit deployment target 25.5;
Xcode with matching macOS and DriverKit SDKs;
Xcode command-line tools.

The local ad-hoc installation workflow is intended only for a dedicated development Mac and is not a public binary distribution workflow.

List schemes and destinations

xcodebuild \
  -list \
  -project AlfaMacDriver.xcodeproj

xcodebuild \
  -showdestinations \
  -project AlfaMacDriver.xcodeproj \
  -scheme AlfaUsbDriver

Unsigned Release build of the DriverKit extension

Use the DriverKit destination shown by xcodebuild -showdestinations. On an Apple-silicon development Mac, a typical command is:

xcodebuild \
  -project AlfaMacDriver.xcodeproj \
  -scheme AlfaUsbDriver \
  -configuration Release \
  -destination 'platform=macOS,arch=arm64,variant=DriverKit,name=My Mac' \
  -derivedDataPath build/DerivedData \
  CODE_SIGNING_ALLOWED=NO \
  CODE_SIGNING_REQUIRED=NO \
  clean build

This command verifies compilation and linking only. An unsigned system extension cannot be activated as a normal distributable DriverKit product.

Unsigned Release build of the host application

xcodebuild \
  -project AlfaMacDriver.xcodeproj \
  -scheme AlfaMacDriver \
  -configuration Release \
  -destination 'platform=macOS,arch=arm64,name=My Mac' \
  -derivedDataPath build/DerivedData \
  CODE_SIGNING_ALLOWED=NO \
  CODE_SIGNING_REQUIRED=NO \
  build

Portable CLI and test build

make alfa-wlan
make test

The portable tests exercise parsing, control contracts, capture formats, injection authorization, TX-status handling, and integrations without opening a real DriverKit connection or transmitting through hardware.

Quick local workflow

Run the portable tests and build both macOS targets:

make test
make sanitize
make local-release

For an acknowledged local ad-hoc installation on a dedicated test Mac:

make install-local-adhoc ACK_LOCAL_ADHOC=YES
make local-install-status

For safe removal:

make request-local-uninstall
make local-install-status
make remove-local-app

See Local Ad-Hoc Build and Installation for the complete security, signing, activation, verification, and removal workflow.

Signing verification

A signed build must pass the repository verification gate before installation or activation:

make verify-signed-app \
  SIGNED_APP=/path/to/AlfaMacDriver.app

For an isolated local ad-hoc build:

make verify-local-adhoc-app \
  SIGNED_APP=/path/to/AlfaMacDriver.app

The verification commands inspect application and extension signatures, identities, entitlements, provisioning expectations, bundle identifiers, and USB matching declarations. They do not install or activate the extension.

Installation and activation

The bundled application is currently an installer and uninstaller for the DriverKit system extension. It also exposes the development CLI through its main executable.

A typical local development workflow is:

Complete the isolated security preparation above.
Build an appropriately signed or local ad-hoc application and extension.
Run the repository's signing verifier.
Copy AlfaMacDriver.app to /Applications when required by the selected activation mode.
Launch the application and request installation of the system extension.
Approve the extension in macOS System Settings if macOS requests approval.
Restart when macOS requests it.
Confirm that the extension is activated before connecting to the real IOUserClient interface.

The installed executable is expected at:

/Applications/AlfaMacDriver.app/Contents/MacOS/AlfaMacDriver

For convenience:

export ALFA_WLAN_BIN="/Applications/AlfaMacDriver.app/Contents/MacOS/AlfaMacDriver"
"$ALFA_WLAN_BIN" --help

Do not distribute the current ad-hoc build to other users. A public binary release requires appropriate Apple entitlements, Developer ID signing, provisioning where applicable, notarization, and independent release testing.

Safe operational workflow

1. Read diagnostics first

"$ALFA_WLAN_BIN" diagnostics --json

Do not begin firmware or DMA initialization unless the diagnostic output reports:

safe_for_dma_configuration: true

The driver repeats the safety check internally before the first hardware write. The CLI output is not a substitute for that internal guard.

2. Load firmware

"$ALFA_WLAN_BIN" firmware-load \
  --patch /path/to/WIFI_MT7961_patch_mcu_1_2_hdr.bin \
  --ram /path/to/WIFI_RAM_CODE_MT7961_1.bin

When upgrading only the extension while compatible firmware remains active:

"$ALFA_WLAN_BIN" firmware-adopt

3. Initialize the radio policy

Use a valid locally administered MAC address and a country/channel policy that matches the physical location and applicable regulations:

"$ALFA_WLAN_BIN" radio-init \
  --mac 02:11:22:33:44:55 \
  --country DE \
  --channels 2:1,2:6,2:11,5:36 \
  --inject-channels 2:1,2:6,2:11,5:36 \
  --initial 2:6

Injection is permitted only on channels explicitly listed by --inject-channels.

4. Enable monitor mode and scan passively

"$ALFA_WLAN_BIN" monitor-on

"$ALFA_WLAN_BIN" scan \
  --channels 2:1,2:6,2:11,5:36 \
  --dwell-ms 250

5. Capture

PCAPNG:

"$ALFA_WLAN_BIN" capture --output capture.pcapng

Classic PCAP:

"$ALFA_WLAN_BIN" capture \
  --output capture.pcap \
  --format pcap

The output uses Radiotap with DLT_IEEE802_11_RADIO (127).

6. Authorized injection only

"$ALFA_WLAN_BIN" inject \
  --file authorized-frame.bin \
  --channel 2:6 \
  --mode cck \
  --rate 0 \
  --pid 1 \
  --wait-status-ms 500 \
  --authorized

USB submission alone is not treated as wireless success. The command waits for a fresh hardware TX status when requested.

Tool integrations

Tool	Integration
Wireshark	Extcap adapter and Radiotap capture
Kismet	External datasource for logical `wlan1`
Scapy	SuperSocket receive and authorized injection path
tcpdump	Reads generated Radiotap PCAPNG/PCAP captures
Aircrack-ng-compatible readers	Classic PCAP output with link type `127`

See Documentation/TOOL_INTEGRATION.md for setup and command examples.

Testing and verification

The repository contains portable tests for:

Firmware parsing and bounded staging.
USB endpoint semantics.
Driver-service and selector-dispatch contracts.
IOUserClient version, selector, scalar, and descriptor validation.
Radio policy and channel authorization.
Monitor and passive-scan behavior.
Radiotap, PCAPNG, and PCAP output.
Capture timestamps.
Injection requests and fresh TX-status matching.
Wireshark, Kismet, and Scapy adapters.
Signed-application verification rules.
AddressSanitizer and UndefinedBehaviorSanitizer paths.

Run the portable suite with:

make test

Passing portable tests does not by itself prove safe behavior on real hardware. Review the hardware test plan before using a physical adapter:

Repository layout

App/                 Host application and CLI entry point
Driver/              Portable driver core and protocol logic
Extension/           DriverKit / USBDriverKit integration
Integrations/        Wireshark, Kismet, and Scapy adapters
Tests/               Unit, contract, integration, and sanitizer tests
Documentation/       Architecture, safety, firmware, status, and release notes
AlfaMacDriver.xcodeproj/
Makefile

Security policy

Do not publish sensitive diagnostics, device identifiers, signing material, provisioning profiles, firmware obtained under restricted terms, packet captures, or credentials in an issue.

Report suspected vulnerabilities according to SECURITY.md.

Responsible and lawful use

This project includes monitor-mode capture and raw-frame injection capabilities. Those capabilities are intended only for:

Hardware and driver development.
Controlled laboratory testing.
Defensive research.
Networks, devices, and radio environments that you own or for which you have explicit written authorization.

Do not use this software to intercept private communications, gain unauthorized access, disrupt services, evade access controls, interfere with other users, violate spectrum regulations, or perform any activity prohibited by applicable law or policy.

You are solely responsible for determining whether your intended use is legal, authorized, safe, and compliant with local radio regulations. Authorization to use a network does not automatically authorize packet injection, interference, or collection of third-party traffic.

Disclaimer

This software is experimental and is provided as is, without warranties or guarantees of correctness, safety, fitness, availability, regulatory compliance, or compatibility with any device, network, or version of macOS.

Low-level driver development can cause system instability, kernel or system extension failures, USB device malfunction, data loss, network disruption, unexpected radio transmission, or security exposure. Disabling SIP or reducing startup security materially weakens macOS protections.

To the maximum extent permitted by applicable law, the author and contributors are not responsible for damage to hardware or software, data loss, service interruption, privacy violations, regulatory violations, unauthorized access, interference, or other consequences arising from installation, testing, modification, distribution, or misuse of this project.

Use of this repository does not grant permission to access, monitor, test, or transmit on any system, device, network, or radio channel.

Firmware and third-party material

Firmware is not distributed by this repository. Users must obtain firmware from an authorized source and comply with its separate license terms.

Third-party notices, license boundaries, and pinned provenance information are recorded in:

License

The project core is licensed under the MIT License unless a file or integration states otherwise. Some integration or compatibility files have separate license requirements. Review LICENSE, file-level SPDX identifiers, and THIRD_PARTY_NOTICES.md before redistribution.

Contributing

Contributions should:

Preserve the versioned IOUserClient ABI and input-validation boundaries.
Include tests for new protocol, parser, and lifecycle behavior.
Avoid adding firmware, captures, signing assets, personal data, or generated build products.
Document upstream provenance and license obligations.
Keep raw injection explicitly authorized and policy-restricted.
Avoid claims of hardware support that are not backed by reproducible tests.

Open an issue before submitting a large architectural change.

Name		Name	Last commit message	Last commit date
.github		.github
AlfaMacDriver.xcodeproj		AlfaMacDriver.xcodeproj
App		App
Documentation		Documentation
Driver		Driver
Extension		Extension
Tests		Tests
Tools		Tools
.gitignore		.gitignore
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md

Latest commit

History

Folders and files

Repository files navigation

AlfaMacDriver

Project status

Implemented capabilities

Not implemented

Architecture

Requirements

Security preparation for the current local test build

1. Back up and isolate the test Mac

2. Enter macOS Recovery on Apple silicon

3. Select Reduced Security

4. Disable System Integrity Protection

5. Enable system-extension developer mode

6. Restore macOS security after testing

Building

Requirements

List schemes and destinations

Unsigned Release build of the DriverKit extension

Unsigned Release build of the host application

Portable CLI and test build

Quick local workflow

Signing verification

Installation and activation

Safe operational workflow

1. Read diagnostics first

2. Load firmware

3. Initialize the radio policy

4. Enable monitor mode and scan passively

5. Capture

6. Authorized injection only

Tool integrations

Testing and verification

Repository layout

Security policy

Responsible and lawful use

Disclaimer

Firmware and third-party material

License

Contributing

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages