You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**Scope:**User-facing overview for `franklesniak/macOSLab`, including the fastest safe starting path, project boundaries, current phase status, validation commands, deferred work, and license information.
`macOSLab` is a PowerShell 7.4+ starter kit for building reproducible Apple-silicon macOS VM labs for Intune policy testing. The repository is initialized from [`franklesniak/copilot-repo-template`](https://github.com/franklesniak/copilot-repo-template) and is being tailored for the `MacLab` PowerShell module.
The project goal is to help Microsoft endpoint administrators test risky macOS policies before they reach production users. The supported local virtualization paths are Parallels Desktop Pro and UTM. Tart remains an advanced stub path until later owner approval.
17
+
`macOSLab` is a PowerShell 7.4+ starter kit for building reproducible Apple-silicon macOS VM labs for Microsoft Intune policy testing. It helps endpoint administrators pin macOS media, build lab VMs, create rollback checkpoints, validate FileVault/Defender/PPPC outcomes, and export redacted evidence before risky policy changes reach production users.
15
18
16
-
## Current Bootstrap State
19
+
This repository is not a production Mac management platform, not legal advice, not a replacement for physical Mac sign-off, and not a place to store tenant data or recovery keys. VM evidence accelerates iteration; it does not prove Red-bucket outcomes such as ADE/ABM zero-touch enrollment, Platform SSO sign-in/unlock, Touch ID, Secure Enclave-dependent behavior, or executive pilot readiness.
17
20
18
-
Phase 0 establishes repository identity, trims irrelevant template sample content, keeps governance and validation tooling intact, and records deferred verification work. The full module implementation, user docs, and evidence schema are not part of Phase 0.
21
+
## Fastest Safe Start
19
22
20
-
The repository languages are PowerShell and Markdown. Python may still appear as a tool runtime for pre-commit hooks such as `check-jsonschema`, but Python sample/source code is not part of this project.
23
+
Start at [docs/Start-Here.md](docs/Start-Here.md), then read [docs/Prereqs.md](docs/Prereqs.md) before running any provider or cloud workflow. The implementation is delivered in phase gates; Phase 1 provides the foundation documentation, while module implementation begins in Phase 2.
Until later phases add the module and scripts, treat that snippet as the stable target interface rather than a promise that the commands are already implemented.
36
+
37
+
## What Ships First
38
+
39
+
The first working path is deliberately narrow:
40
+
41
+
- Apple-silicon macOS host.
42
+
- PowerShell 7.4 or newer.
43
+
- Parallels Desktop as the primary provider.
44
+
- UTM as a documented/manual provider-swap path with partial lifecycle automation.
45
+
- Tart as a stubbed advanced path unless later owner approval expands it.
46
+
-`mist-cli` for macOS restore image or provider-appropriate install artifact discovery.
47
+
- Redacted JSON evidence as the durable output.
48
+
49
+
The owner/demo path reuses the already-downloaded macOS Tahoe 26.4.1 IPSW at `~/Demo/Installers/UniversalMac_26.4.1_25E253_Restore.ipsw` when it exists and matches SHA-256 `8aa7f7aea6b20d1839d85a0017c9a1472f26c63ad496919f85db988eb01a5c32`. Demo scripts and runbooks must not start another download when that verified file is present.
50
+
51
+
## Documentation Map
52
+
53
+
-[docs/Start-Here.md](docs/Start-Here.md) - first read for new users.
54
+
-[docs/Prereqs.md](docs/Prereqs.md) - host, provider, tooling, and tenant prerequisites.
55
+
-[docs/Hypervisor-Decision-Guide.md](docs/Hypervisor-Decision-Guide.md) - Parallels vs. UTM vs. Tart.
56
+
-[docs/Apple-Silicon-Constraints.md](docs/Apple-Silicon-Constraints.md) - Apple Virtualization, licensing posture, and physical hardware boundaries.
57
+
-[docs/Provider-Version-Matrix.md](docs/Provider-Version-Matrix.md) - how evidence records host/provider/guest facts.
Phase completion summaries must state whether the matching TODO file is closed, empty, or still carrying deferred work.
103
+
104
+
## Security
105
+
106
+
Do not commit real tenant IDs, device IDs, recovery keys, UPNs, policy exports, tokens, private keys, screenshots, recordings, `.ipsw`, `.dmg`, `.iso`, `.app`, or binary `.utm` bundles. If content appears to contain a real secret, report it privately through the GitHub security advisory process described in [SECURITY.md](SECURITY.md).
107
+
108
+
## Acknowledgements
109
+
110
+
This repository is initialized from [`franklesniak/copilot-repo-template`](https://github.com/franklesniak/copilot-repo-template). The lab posture is shaped by the MMSMOA macOS policy-testing session, owner-supplied provider validation evidence, and public vendor documentation linked from the foundation docs.
111
+
51
112
## License
52
113
53
114
This project is licensed under the MIT License. See [LICENSE](LICENSE).
-**Scope:** Apple-silicon virtualization constraints, licensing posture, host/guest compatibility, APNs/network caveats, and physical hardware boundaries for `macOSLab`.
10
+
-**Related:**[Hypervisor Decision Guide](Hypervisor-Decision-Guide.md), [Fidelity Boundaries](Fidelity-Boundaries.md), [Provider Version Matrix](Provider-Version-Matrix.md), [macOS Tahoe SLA](https://www.apple.com/legal/sla/docs/macOSTahoe.pdf), [Parallels macOS VM limitations](https://kb.parallels.com/en/128867), [UTM Apple settings documentation](https://docs.getutm.app/settings-apple/settings-apple/)
11
+
12
+
`macOSLab` targets Apple-branded Apple-silicon Macs. The lab is built around Apple's Virtualization framework because Parallels, UTM macOS guests on Apple silicon, and Tart all depend on that platform boundary for macOS guests.
13
+
14
+
## Licensing Posture
15
+
16
+
The repository links to the [macOS Tahoe software license agreement](https://www.apple.com/legal/sla/docs/macOSTahoe.pdf) as the primary Apple license source for the initial documentation set.
17
+
18
+
The practical default posture is:
19
+
20
+
- Use Apple-branded hardware.
21
+
- Assume no more than two concurrent macOS guest instances per Apple-branded host unless the owner or user verifies a different license posture.
22
+
- Use the lab for testing, development, and validation scenarios that fit the user's own license review.
23
+
- Do not treat this repository as legal advice.
24
+
25
+
Users are responsible for confirming their own Apple, hypervisor, and organizational licensing requirements.
26
+
27
+
## Host And Guest Compatibility
28
+
29
+
For macOS guests on Apple-silicon hosts, compatibility is a preflight gate, not a static version table.
30
+
31
+
The default supported path is same-major host and guest macOS. For example, a macOS 26 host running a macOS 26 guest is the preferred demo path. Cross-major targets may remain useful, but automation must not assume they work everywhere. A guest macOS major version higher than the host macOS major version must be rejected by default or require explicit owner-approved override.
32
+
33
+
Provider documentation reinforces this conservative posture:
34
+
35
+
- Parallels documents `prlctl create <name> -o macos --restore-image <path>` for macOS VM creation from IPSW and states that the only guaranteed Apple-silicon macOS VM compatibility scenario is the same macOS major version on host and guest.
36
+
- Parallels also documents that macOS Arm VMs are built using Apple's Virtualization framework and that running a guest higher than the host may not be possible.
37
+
- UTM documents the Apple Virtualization backend as the way to run virtualized macOS on Apple silicon.
38
+
- Tart describes itself as using Apple's native Virtualization framework.
39
+
40
+
## Version Matrix Requirement
41
+
42
+
Every meaningful run must record:
43
+
44
+
- Host macOS version and build.
45
+
- Host architecture.
46
+
- Guest macOS version and build, when known.
47
+
- Provider and provider version.
48
+
- Restore image path, size, and SHA-256 where practical.
49
+
- Host/guest compatibility classification.
50
+
- Manual-step gaps.
51
+
52
+
The Provider Version Matrix turns "works on my Mac" into reviewable evidence.
53
+
54
+
## APNs And Network Caveats
55
+
56
+
The default lab network posture is Shared networking, not bridged networking. Shared networking is suitable for most Intune, APNs, Graph, and Defender validation paths, but it is still a VM network. If a test depends on network identity, source IP, captive portals, proxy behavior, multicast discovery, or hardware-adjacent network controls, mark the result Yellow or Red as appropriate.
57
+
58
+
APNs, Intune, Graph, Defender, and Apple software update reachability are required for live policy validation. When those services are not reachable, readiness checks should fail or warn with specific detail instead of treating cloud timing as a policy failure.
59
+
60
+
## Physical Hardware Boundaries
61
+
62
+
The VM lab is not enough for Red-bucket outcomes:
63
+
64
+
- ADE/ABM zero-touch enrollment.
65
+
- Platform SSO sign-in/unlock.
66
+
- Touch ID.
67
+
- Secure Enclave-dependent behavior.
68
+
- Serial-number-dependent production workflows.
69
+
- Final executive pilot sign-off.
70
+
71
+
Yellow outcomes can be iterated in the VM but still need physical Mac sign-off. FileVault rollout behavior, user prompts, compliance timing, and performance-sensitive Defender behavior often fall into this category.
72
+
73
+
## Operational Rule
74
+
75
+
Do not create a macOS VM until the host/guest compatibility check, provider version capture, and media checksum verification are complete. A fast failed preflight is better than a VM that looks valid but cannot be trusted as evidence.
The lab is useful because it is honest. A macOS VM can prove many automation and policy behaviors quickly, but it cannot replace every physical Mac validation path.
13
+
14
+
## Traffic Light
15
+
16
+
| Color | Meaning | Examples |
17
+
| --- | --- | --- |
18
+
| Green | VM evidence is sufficient on its own. | Script syntax, package install behavior, Intune assignment logic, profile receipt, basic PPPC payload behavior, Defender health checks, rollback routines, evidence export. |
19
+
| Yellow | VM evidence is useful for iteration, but physical hardware sign-off remains required. | FileVault rollout behavior, recovery-key process end to end, compliance experience under realistic timing, user prompts, UI flows, performance-sensitive Defender behavior. |
20
+
| Red | The VM cannot validate the outcome. | ADE/ABM zero-touch enrollment, serial-number-dependent workflows, Platform SSO sign-in/unlock, Touch ID, Secure Enclave-dependent behavior, final executive pilot sign-off. |
21
+
22
+
## Cmdlet Honesty Rules
23
+
24
+
Evidence-producing cmdlets must:
25
+
26
+
- Stamp evidence with the fidelity color.
27
+
- Set `hardwareSignoffRequired: true` for Yellow evidence.
28
+
- Reject Red-bucket assertions at parse time.
29
+
- Preserve the cloud-state warning in restore and evidence records.
30
+
- Refuse to write evidence when redaction cannot be applied.
31
+
32
+
Documentation must not claim the lab proves Red-bucket outcomes.
33
+
34
+
## Cloud-State Warning
35
+
36
+
Every restore warning and evidence record must include this statement:
37
+
38
+
> VM rollback does not rewind Intune, Entra, Defender portal state, audit logs, or reporting history.
39
+
40
+
The warning is not decorative. It explains why a local VM restore can leave stale device records, compliance history, audit entries, Defender machine records, or assignment timing in cloud services.
41
+
42
+
## Yellow Change-Ticket Wording
43
+
44
+
Use wording like this when VM evidence supports but does not replace physical sign-off:
45
+
46
+
```text
47
+
macOSLab VM evidence shows the policy payload was received and produced the expected lab behavior on the recorded host/provider/guest matrix. This is Yellow evidence: physical Mac sign-off remains required before production rollout because VM rollback does not rewind Intune, Entra, Defender portal state, audit logs, or reporting history, and VM hardware fidelity does not cover Secure Enclave, Touch ID, ADE/ABM, or final user-pilot behavior.
48
+
```
49
+
50
+
## Red Assertion Example
51
+
52
+
This is not a valid VM test assertion:
53
+
54
+
```yaml
55
+
fidelity: Red
56
+
expectation: ADE zero-touch enrollment succeeds in production
57
+
```
58
+
59
+
The validation loop must reject this plan before execution. The correct action is to document a physical hardware validation step outside the VM evidence path.
60
+
61
+
## Evidence Review Checklist
62
+
63
+
Before using VM evidence in a review, confirm:
64
+
65
+
- The Provider Version Matrix is present.
66
+
- The fidelity color is present.
67
+
- Yellow evidence says hardware sign-off is required.
0 commit comments