chore: professionalize project for community contributions

- Add CONTRIBUTING.md with guidelines for PRs and issues
- Add CODE_OF_CONDUCT.md (Contributor Covenant v2.1)
- Add SECURITY.md with vulnerability reporting policy
- Add CHANGELOG.md for version tracking
- Add GitHub issue templates (bug, feature, compatibility)
- Add GitHub Actions CI (ShellCheck, syntax check, markdown lint)
- Add .gitignore for backup dirs and OS artifacts
- Update README with badges and new commands
- Bump version to 1.1.0
- Update comparison table with new features
This commit is contained in:
2026-06-20 11:59:22 -03:00
parent e0dee7cfcc
commit b96d86cc38
11 changed files with 382 additions and 3 deletions
+30
View File
@@ -0,0 +1,30 @@
---
name: Bug report
about: Something is not working as expected
title: ''
labels: bug
assignees: ''
---
**Describe the bug**
A clear description of what is not working.
**To reproduce**
1. Run `./unleash <command>` from Recovery / booted system
2. See error: ...
**Expected behavior**
What should have happened instead.
**Environment**
- macOS version: (e.g. Sequoia 15.5, Tahoe 26.3)
- Hardware: (Intel / Apple Silicon M1/M2/M3/M4)
- Recovery mode: (Yes / No)
- FileVault: (Enabled / Disabled)
**Screenshots or logs**
If applicable, add output from `unleash status` or terminal logs.
**Additional context**
Anything else relevant.
@@ -0,0 +1,32 @@
---
name: Compatibility report
about: Report success or failure on a specific macOS version or hardware
title: ''
labels: compatibility
assignees: ''
---
**macOS version tested**
e.g. macOS Tahoe 26.5.1
**Hardware**
e.g. MacBook Pro M4 Pro (2025)
**Command tested**
[ ] bypass
[ ] suppress
[ ] heal
[ ] persist
[ ] firewall
[ ] harden
[ ] audit
[ ] whitelist
**Result**
[ ] Works perfectly
[ ] Works with issues (describe below)
[ ] Does not work
**Details**
Any errors, unexpected behavior, or observations.
+20
View File
@@ -0,0 +1,20 @@
---
name: Feature request
about: Suggest an idea for unleash
title: ''
labels: enhancement
assignees: ''
---
**Is your feature request related to a problem?**
Describe what doesn't work or could be improved.
**Describe the solution you'd like**
What should the new command or behavior look like?
**Describe alternatives you've considered**
Other approaches or workarounds.
**Additional context**
Add any references (other tools, links, screenshots).
+54
View File
@@ -0,0 +1,54 @@
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
shellcheck:
name: ShellCheck
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run ShellCheck
uses: ludeeus/action-shellcheck@master
with:
severity: warning
additional_files: >
unleash
lib/colors.sh
lib/detect.sh
lib/validate.sh
lib/dscl.sh
lib/suppress.sh
lib/backup.sh
lib/status.sh
lib/heal.sh
lib/firewall.sh
lib/harden.sh
lib/whitelist.sh
syntax:
name: Bash Syntax Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check syntax
run: |
for f in unleash lib/*.sh examples/*.sh; do
[ -f "$f" ] || continue
echo "Checking: $f"
bash -n "$f" || exit 1
done
echo "All files pass syntax check"
markdown:
name: Markdown Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DavidAnson/markdownlint-cli2-action@v16
with:
globs: '*.md'
+4
View File
@@ -0,0 +1,4 @@
.unleash-backup/
*.swp
*.swo
.DS_Store
+25
View File
@@ -0,0 +1,25 @@
# Changelog
## [1.0.0] — 2026-06-20
### Added
- Initial release of unleashes — Unified MDM Bypass for macOS
- **bypass**: Full MDM bypass with admin user creation (Recovery mode)
- **suppress**: Suppress MDM enrollment without creating a user
- **heal**: Auto-heal — check and re-apply suppression after macOS updates
- **persist**: Install LaunchDaemon for boot-time auto-heal
- **unpersist**: Remove the persistence LaunchDaemon
- **firewall**: Block Apple MDM IP ranges via pf (DoH-proof)
- **firewall-off**: Remove pf firewall MDM block
- **harden**: Live-OS hardening (kill MDM, remove profiles, flush DNS)
- **audit**: Deep MDM audit (profiles, certs, agents, risk scoring)
- **whitelist**: Selective block (block MDM only, keep iCloud/App Store)
- **backup/restore**: Save and revert all changes
- **dualboot**: Target external or dual-boot volumes
- **status**: MDM status check with deep audit mode
- User-level MDM artifact cleanup (Preferences, Caches, LaunchAgents)
- Expanded domain blocking (13 Apple MDM domains + org MDM host)
- 4 enrollment daemon overrides (launchd disabled.plist)
- Intel T2 and Apple Silicon support
- DFU/IPSW restore guide in documentation
- macOS Tahoe 26.x compatibility
+43
View File
@@ -0,0 +1,43 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes
- Focusing on what is best for the overall community
Examples of unacceptable behavior:
- The use of sexualized language or imagery, and sexual attention or advances
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
## Enforcement Responsibilities
Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated promptly and fairly.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
[homepage]: https://www.contributor-covenant.org
+52
View File
@@ -0,0 +1,52 @@
# Contributing to unleash
Thank you for considering contributing to unleash! This document outlines the guidelines for contributions.
## Code of Conduct
This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold it.
## How to Contribute
### Reporting Issues
- **Bug reports**: Open an issue with the `bug` label. Include macOS version, hardware (Intel/Apple Silicon), and steps to reproduce.
- **Feature requests**: Open an issue with the `enhancement` label. Describe the problem and the proposed solution.
- **Compatibility reports**: Open an issue with the `compatibility` label if you've tested on a new macOS version or hardware.
### Pull Requests
1. Fork the repository
2. Create a feature branch from `main`
3. Follow the existing code style (ShellCheck compliant)
4. Test your changes:
- Syntax check: `bash -n lib/*.sh unleash`
- ShellCheck: `shellcheck lib/*.sh unleash` (install via `brew install shellcheck`)
5. Update documentation (README.md) if adding features
6. Open a PR against `main`
### Code Style
- **Shell**: Bash 3.2+ compatible (macOS default)
- **Naming**: Functions → `snake_case`, Constants → `UPPER_CASE`
- **Error handling**: Use `set -euo pipefail` in the main script
- **Library functions**: Return 0 on success, call `error_exit` on failure
- **Portability**: Avoid GNU-specific flags; prefer macOS-compatible options
### Testing
- Manual testing is required for now
- Preferred environments: macOS Recovery mode (Intel and Apple Silicon)
- Test both `bypass` (from Recovery) and `suppress`/`heal` (from booted system)
## Areas Needing Help
- **New macOS version compatibility**: Test on latest macOS releases
- **Additional MDM domains**: Research and add new Apple MDM endpoints
- **Firewall improvements**: Better pf rules for selective blocking
- **Documentation**: Translations, better troubleshooting guides
- **CI/CD**: GitHub Actions for automated ShellCheck and syntax validation
## Questions?
Open a discussion or issue. We aim to respond within 48 hours.
+91 -2
View File
@@ -1,6 +1,13 @@
# unleash — Unified MDM Bypass for macOS
**unleash** is a single-tool solution to bypass, suppress, backup, restore, and audit MDM (Mobile Device Management) enrollment on macOS. It unifies the functionality of the original `bypass-mdm` project into one script with CLI flags and an interactive menu.
[![CI](https://github.com/mateussiqueira/unleash/actions/workflows/ci.yml/badge.svg)](https://github.com/mateussiqueira/unleash/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![macOS](https://img.shields.io/badge/macOS-12.x–26.x-green.svg)](README.md)
[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-M1%20|%20M2%20|%20M3%20|%20M4-orange.svg)](#intel-vs-apple-silicon)
[![Intel](https://img.shields.io/badge/Intel-T2%20supported-lightgrey.svg)](#intel-vs-apple-silicon)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
**unleash** is a single-tool solution to bypass, suppress, backup, restore, audit, and harden MDM (Mobile Device Management) enrollment on macOS. It unifies the functionality of the original `bypass-mdm` project into a single script with CLI flags and an interactive menu.
> **Legal**: This tool suppresses MDM locally on devices you own. It does not touch Apple Business Manager (ABM) records. The permanent fix is the organization releasing the device. Use at your own risk.
@@ -18,6 +25,7 @@
- [Architecture](#architecture)
- [Safety & Limitations](#safety--limitations)
- [FAQ](#faq)
- [Contributing](#contributing)
---
@@ -37,8 +45,14 @@ The original `bypass-mdm` project grew into 5 separate scripts (v2, v3, express,
| Org MDM host blocking | v3 | always |
| Launchd daemon disable | v3 | always |
| User-level cleanup | — | yes |
| pf firewall (DoH-proof) | — | yes |
| Live-OS hardening | — | yes |
| Deep MDM audit | — | yes |
| Selective iCloud-safe block | — | yes |
| Boot-time persistence (LaunchDaemon) | — | yes |
| Auto-heal after macOS updates | — | yes |
| Interactive menu | brew-based | native |
| CLI flags | none | yes |
| CLI flags | none | 13 commands |
---
@@ -131,6 +145,72 @@ sudo ./unleash unpersist # from booted system
./unleash unpersist # from Recovery mode
```
### `unleash firewall` — pf Kernel-Level MDM Block
Blocks Apple MDM infrastructure IP ranges using pf (packet filter), which operates below DNS resolution and is immune to DNS-over-HTTPS bypass:
```bash
sudo ./unleash firewall # from booted system or Recovery
```
Creates a pf anchor at `/etc/pf.anchors/com.unleash/mdm` that drops traffic to Apple's `17.0.0.0/8` and `17.128.0.0/10` IP ranges.
> ⚠️ This blocks ALL Apple services (iCloud, App Store, system updates). Use `unleash whitelist` for selective blocking instead.
### `unleash firewall-off` — Remove pf Block
Flushes the Unleash pf anchor and restores the original `pf.conf`:
```bash
sudo ./unleash firewall-off
```
### `unleash harden` — Live-OS Hardening
Runs from the booted system (after bypass) to remove residual MDM artifacts:
```bash
sudo ./unleash harden
```
**What it does:**
1. Kills running MDM processes (ManagedClient, mdmclient, activationd)
2. Forces removal of installed MDM profiles (`profiles -D -F`)
3. Scans and removes MDM-related user LaunchAgents
4. Flushes DNS cache and restarts mDNSResponder
5. Checks keychain for MDM identity certificates
6. Scans for JAMF/Intune/Workspace ONE agent binaries
7. Disables iCloud Private Relay (a DoH source)
### `unleash audit` — Deep MDM Audit
Comprehensive system scan for MDM artifacts, with risk scoring:
```bash
sudo ./unleash audit # from booted system
```
**Checks:**
1. Installed configuration profiles (name and count)
2. MDM enrollment state
3. MDM identity certificates in keychain
4. User LaunchAgents for MDM references
5. System LaunchDaemons for MDM references
6. Running MDM processes
7. MDM agent binaries (JAMF, Intune, Workspace ONE)
8. pf firewall status
9. Overall risk assessment (LOW / MEDIUM / HIGH / CRITICAL)
### `unleash whitelist` — Selective iCloud-Safe Block
Blocks only MDM enrollment endpoints while preserving iCloud, App Store, and system updates:
```bash
sudo ./unleash whitelist # from booted system or Recovery
```
Uses pf rules targeting only the essential MDM domains (`mdmenrollment.apple.com`, `deviceenrollment.apple.com`, `iprofiles.apple.com`) while leaving Apple services unblocked.
### `unleash suppress` — Suppress Only
Suppresses MDM enrollment without creating a user. Ideal after a clean bypass breaks (e.g., after macOS update).
@@ -531,6 +611,15 @@ Contributions welcome, especially for:
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
- [Open issues](https://github.com/mateussiqueira/unleash/issues) for bugs and features
- Submit PRs with ShellCheck-validated code
- Test on your hardware and report compatibility
- Read the [Code of Conduct](CODE_OF_CONDUCT.md)
## License
MIT. See [LICENSE](LICENSE).
+30
View File
@@ -0,0 +1,30 @@
# Security Policy
## Supported Versions
| Version | Supported |
|---------|--------------------|
| 1.x | ✅ Currently supported |
## Reporting a Vulnerability
This tool modifies system configuration to suppress MDM enrollment. While designed to be safe (SSV-safe, reversible via backup/restore), please report any security concerns.
To report a vulnerability:
1. **Do NOT** open a public issue
2. Open a [security advisory](https://github.com/mateussiqueira/unleash/security/advisories) privately
3. Or email the maintainer directly
## Safety Guarantees
- **No system volume writes**: All operations target the Data volume only
- **Reversible**: `unleash backup`/`restore` saves and reverts all changes
- **No data loss**: Never runs `profiles renew` or erase commands
- **No ABM modification**: Does not touch Apple Business Manager records
## Known Limitations
- Serial numbers remain in ABM after bypass
- macOS updates may reset suppression (use `unleash heal`)
- Profile enrollment status may still show as active (cosmetic, from SSV)
+1 -1
View File
@@ -25,7 +25,7 @@ set -euo pipefail
# Put this on an external SSD and run from Recovery.
# No curl, no downloads, no typing URLs.
VERSION="1.0.0"
VERSION="1.1.0"
# Determine script location (works with symlinks and source)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"