Skip to content

MACOS-STATUS.md

Latest commit

 

History

History
181 lines (136 loc) · 4.55 KB

MACOS-STATUS.md

File metadata and controls

181 lines (136 loc) · 4.55 KB

macOS Implementation Status

Implementation Checklist

Core Files

  • ✅ src/macos-sandbox.ts - macOS sandbox implementation using sandbox-exec
  • ✅ src/platform-sandbox.ts - Cross-platform abstraction layer
  • ✅ src/sandbox-manager.ts - Updated to use PlatformSandbox
  • ✅ src/index.ts - Exports macOS classes

Seatbelt Profile Features

  • ✅ Deny access to sensitive paths (.ssh, .aws, .gnupg, etc.)
  • ✅ Allow access to working directory
  • ✅ Allow read access to system directories (/usr, /System, etc.)
  • ✅ Allow network access (controlled via proxy)
  • ✅ Allow process execution
  • ✅ Temporary profile file creation and cleanup

Platform Detection

  • ✅ Automatic platform detection (darwin vs linux)
  • ✅ Platform-specific error messages
  • ✅ PlatformSandbox.isAvailable() checks for sandbox-exec
  • ✅ PlatformSandbox.getSandboxType() returns implementation name

Testing Status

Linux (bubblewrap)

✅ TESTED AND VERIFIED

  • All 22 tests passing
  • Security validation confirmed
  • Bubblewrap 0.9.0 working

macOS (sandbox-exec)

⚠️ NOT YET TESTED

  • Code implemented but not tested on actual macOS
  • Need to run on macOS to verify

How to Test on macOS

# 1. Clone the repo
git clone <repo-url>
cd bubblewrap

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Verify sandbox-exec is available
which sandbox-exec
sandbox-exec -h

# 5. Run tests
npm test

# 6. Specifically run security validation
npm test -- src/__tests__/security-validation.test.ts

# 7. Or use the quick test script
./scripts/test-locally.sh

Expected Behavior on macOS

When running on macOS:

  1. PlatformSandbox detects platform() === 'darwin'
  2. Creates MacOSSandbox instance
  3. Generates Seatbelt profile on each command
  4. Runs sandbox-exec -f <profile> <command>
  5. Should block same paths as Linux version

Seatbelt Profile Example

Generated profile looks like this:

(version 1)
(debug deny)

(allow default)

; Deny sensitive paths
(deny file-read* file-write*
    (subpath "/Users/username/.ssh")
    (subpath "/Users/username/.aws")
    (subpath "/Users/username/.config/gcloud")
)

; Allow working directory
(allow file-read* file-write*
  (subpath "/Users/username/project")
)

; Allow system directories
(allow file-read*
  (subpath "/usr")
  (subpath "/System")
)

Known Limitations on macOS

  1. sandbox-exec limitations:

    • Less restrictive than bubblewrap
    • Network filtering is limited (relies on proxy)
    • Process isolation is weaker

  2. Seatbelt is deprecated:

    • macOS has moved to App Sandbox for apps
    • sandbox-exec still works but is legacy
    • Future macOS versions might remove it

  3. Root/sudo:

    • May need additional permissions
    • Some operations might bypass sandbox

Alternatives for macOS

If sandbox-exec doesn't work well:

Option A: Docker/Lima

# Run in Docker container on macOS
docker run --rm -v $(pwd):/workspace sandbox-image

Option B: macOS App Sandbox

  • More modern but requires app bundle
  • Better isolation but more complex

Option C: VM

  • Run Linux VM via UTM/Parallels
  • Use bubblewrap inside VM

GitHub Actions Testing

The workflow is set up to test on both platforms:

  • test-linux: Ubuntu with bubblewrap
  • test-macos: macOS with sandbox-exec

Once you push, GitHub Actions will test on actual macOS.

Next Steps

To complete macOS support:

  1. ✅ Code is written
  2. ⚠️ Need to test on actual macOS machine
  3. ⏳ Need to verify sandbox-exec blocks paths correctly
  4. ⏳ May need to adjust Seatbelt profile based on testing
  5. ⏳ Document any macOS-specific quirks

Manual Testing Checklist for macOS

When you test on macOS, verify these:

  • Platform detection works (Platform: darwin)
  • sandbox-exec is found
  • Seatbelt profile is created in /tmp
  • SSH key access is blocked (~/.ssh/id_rsa)
  • AWS credentials are blocked (~/.aws/credentials)
  • Working directory access is allowed
  • System files are blocked (/etc/sudoers)
  • Subprocess isolation works
  • Profile cleanup works (no /tmp pollution)
  • Performance is acceptable (<100ms overhead)

Status Summary

Component Linux macOS Status
Core implementation ✅ ✅ Complete
Platform detection ✅ ✅ Complete
Tests written ✅ ✅ Complete
Tests passing ✅ ⚠️ Need macOS machine
Documentation ✅ ✅ Complete
GitHub Actions ✅ ✅ Ready to test

Overall: 95% complete, waiting for macOS testing