macOS Installation Preview

macOS agent support is currently Preview/Experimental. Use this guide for lab evaluation and compatibility testing only; Windows and Linux are the primary supported endpoint platforms for the current public release.

This guide covers evaluating the Tamandua EDR agent on macOS systems, including the necessary system extension approvals and security permissions.

Prerequisites

System Requirements

Preview Compatibility

Apple Silicon is the primary macOS target for preview validation. Intel builds are maintained for compatibility, but feature work and performance checks should be verified first on aarch64-apple-darwin.

For developer-side compilation after cloning the repository on a Mac, use bash scripts/macos_build_check.sh --target arm64 --release for Apple Silicon, or --target universal --release to validate both Apple Silicon and Intel artifacts before packaging.

Administrative Requirements

• Administrator privileges required for installation
• Network access to the Tamandua server
• Enrollment token from the Tamandua admin console
• MDM profile recommended for silent approval of system extensions

Security Permissions Required

The experimental macOS agent may require the following system permissions:

Download the Agent

From Admin Console

1. Log in to the Tamandua admin console
2. Navigate to Settings > Agents > Downloads
3. Download the macOS preview installer, when available for your release:

• Tamandua-Agent-arm64.pkg for Apple Silicon Macs
• Tamandua-Agent-x86_64.pkg for Intel Macs
• Tamandua-Agent.pkg only when a universal package is explicitly published

Command Line Download

# Download latest Apple Silicon preview agent
curl -L -o Tamandua-Agent.pkg \
    "https://tamandua.treantlab.org/downloads/agent/macos/arm64/Tamandua-Agent.pkg"

# Verify code signature
pkgutil --check-signature Tamandua-Agent.pkg

# Expected output:
# Package "Tamandua-Agent.pkg":
#    Status: signed by a certificate trusted by macOS
#    Certificate Chain:
#     1. Developer ID Installer: Treant Lab (XXXXXXXXXX)
#     2. Developer ID Certification Authority
#     3. Apple Root CA

PKG Installer (Interactive)

Step 1: Run the Installer

1. Double-click Tamandua-Agent.pkg
2. Click Continue on the Introduction screen
3. Read and accept the License Agreement

Step 2: Enter Enrollment Token

1. Enter your Enrollment Token when prompted
2. Optionally modify:

• Server URL: Only change for self-hosted deployments

1. Click Continue

Step 3: Select Destination

1. Select the installation disk (typically "Macintosh HD")
2. Click Continue

Step 4: Install

1. Click Install
2. Enter your administrator password when prompted
3. Wait for installation to complete (typically 30-60 seconds)

Step 5: Approve System Extension

After installation, macOS will prompt you to approve the system extension:

1. A notification appears: "System Extension Blocked"
2. Click Open System Settings (or navigate manually)
3. Go to Privacy & Security > Security
4. Click Allow next to "Treant Lab" or "Tamandua"
5. Enter your administrator password

Step 6: Grant Full Disk Access

1. Go to System Settings > Privacy & Security > Full Disk Access
2. Click the + button
3. Navigate to /Library/Application Support/Tamandua/Tamandua Agent.app
4. Select the application and click Open
5. Toggle the switch to enable Full Disk Access

Step 7: Restart (if required)

Some macOS versions require a restart after approving the system extension:

# Check if restart is required
systemextensionsctl list | grep tamandua

# If showing "waiting for user", restart:
sudo shutdown -r now

Silent Installation (MDM)

For enterprise lab deployments, use MDM to silently install and approve permissions. Do not treat this preview path as a production macOS fleet rollout until your organization has validated the build, extension behavior, telemetry, and rollback process.

Create MDM Configuration Profile

Create a configuration profile with the following payloads:

System Extension Payload

<?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>PayloadContent</key>
    <array>
        <dict>
            <key>AllowedSystemExtensions</key>
            <dict>
                <key>XXXXXXXXXX</key>
                <array>
                    <string>com.treantlab.tamandua.extension</string>
                </array>
            </dict>
            <key>AllowedSystemExtensionTypes</key>
            <dict>
                <key>XXXXXXXXXX</key>
                <array>
                    <string>EndpointSecurityExtension</string>
                    <string>NetworkExtension</string>
                </array>
            </dict>
            <key>PayloadType</key>
            <string>com.apple.system-extension-policy</string>
            <key>PayloadIdentifier</key>
            <string>com.treantlab.tamandua.sysext</string>
            <key>PayloadUUID</key>
            <string>YOUR-UUID-HERE</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
        </dict>
    </array>
    <key>PayloadIdentifier</key>
    <string>com.treantlab.tamandua.profile</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>YOUR-UUID-HERE</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>

Privacy Preferences (TCC) Payload

<dict>
    <key>PayloadType</key>
    <string>com.apple.TCC.configuration-profile-policy</string>
    <key>Services</key>
    <dict>
        <key>SystemPolicyAllFiles</key>
        <array>
            <dict>
                <key>Identifier</key>
                <string>com.treantlab.tamandua.agent</string>
                <key>IdentifierType</key>
                <string>bundleID</string>
                <key>CodeRequirement</key>
                <string>identifier "com.treantlab.tamandua.agent" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] and certificate leaf[field.1.2.840.113635.100.6.1.13] and certificate leaf[subject.OU] = XXXXXXXXXX</string>
                <key>Allowed</key>
                <true/>
            </dict>
        </array>
    </dict>
</dict>

Silent PKG Installation

# Install via MDM command or script
sudo installer -pkg /path/to/Tamandua-Agent.pkg -target / \
    -allowUntrusted \
    -dumplog

# Enroll agent; token is prompted without echo
sudo /Library/Application\ Support/Tamandua/tamandua-agent install

Jamf Pro Deployment

For Jamf Pro:

1. Upload Tamandua-Agent.pkg to Jamf Admin
2. Create a Policy with:

• Package: Tamandua-Agent.pkg
• Scripts: Pre-install and post-install scripts for enrollment

1. Deploy the System Extension and TCC profiles created above
2. Scope to target computers

Verify Installation

Check System Extension Status

# List installed system extensions
systemextensionsctl list

# Expected output:
# 1 extension(s)
# --- com.apple.system_extension.endpoint_security
# enabled    active    teamID    bundleID (version)    name            [state]
# *          *         XXXXXXXXXX com.treantlab.tamandua.extension (1.0.0) Tamandua Extension [activated enabled]

Check Agent Status

# Check if agent is running
launchctl list | grep tamandua

# Expected output:
# -    0    com.treantlab.tamandua.agent

# Check detailed status
sudo launchctl print system/com.treantlab.tamandua.agent

Check Agent Logs

# View agent logs
log show --predicate 'subsystem == "com.treantlab.tamandua"' --last 1h

# Or check log file
tail -f /Library/Application\ Support/Tamandua/logs/agent.log

Verify Permissions

# Check Full Disk Access
sudo sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db \
    "SELECT client, allowed FROM access WHERE service = 'kTCCServiceSystemPolicyAllFiles';" | grep tamandua

Verify in Admin Console

1. Log in to the Tamandua admin console
2. Navigate to Agents > All Agents
3. Confirm the new agent appears with status Online

Directory Structure

/Library/Application Support/Tamandua/
    Tamandua Agent.app/        # Agent application bundle
        Contents/
            MacOS/
                tamandua-agent # Agent binary
            Resources/
            Info.plist
    tamandua-agent             # CLI symlink
    config/
        agent.toml             # Agent configuration
        cert.pem               # Agent certificate
        key.pem                # Agent private key (protected)
        ca-bundle.pem          # CA certificate bundle
    logs/
        agent.log              # Agent logs (rotated)
    models/
        malware_smell.onnx     # ML model (if enabled)
    rules/
        yara/                  # YARA rules
        sigma/                 # Sigma rules
    quarantine/                # Quarantined files
    journal/                   # File modification journal

/Library/SystemExtensions/
    com.treantlab.tamandua.extension.systemextension/
                               # System extension bundle

/Library/LaunchDaemons/
    com.treantlab.tamandua.agent.plist
                               # LaunchDaemon configuration

Endpoint Security Framework

The experimental macOS agent path is designed around Apple's Endpoint Security Framework for kernel-level monitoring.

Monitored Events

TCC Monitoring

When enabled and validated in a preview build, the agent may monitor changes to TCC (Transparency, Consent, and Control) permissions:

• Camera and microphone access changes
• Screen recording permissions
• Accessibility access grants
• Full disk access modifications
• Automation and Apple Events permissions

Troubleshooting

System Extension Not Loading

Cause: Extension not approved or macOS security blocking. Solution:

# Check extension status
systemextensionsctl list

# If "waiting for user":
# Go to System Settings > Privacy & Security > Security
# Click "Allow" for Tamandua/Treant Lab

# If MDM-managed, verify profile is installed:
sudo profiles list | grep tamandua

Full Disk Access Denied

Cause: TCC permission not granted. Solution:

1. Open System Settings > Privacy & Security > Full Disk Access
2. If Tamandua Agent is listed but disabled, toggle it ON
3. If not listed, click + and add /Library/Application Support/Tamandua/Tamandua Agent.app

Agent Not Starting

Cause: LaunchDaemon configuration issue. Solution:

# Check LaunchDaemon status
sudo launchctl list | grep tamandua

# If not listed, load it:
sudo launchctl load /Library/LaunchDaemons/com.treantlab.tamandua.agent.plist

# Check for errors:
sudo launchctl print system/com.treantlab.tamandua.agent

# View boot-out reason if failed:
sudo launchctl dumpstate | grep -A 10 tamandua

Enrollment Fails

Cause: Network issues or invalid token. Solution:

# Test connectivity
curl -v https://tamandua.treantlab.org/api/v1/agent/health

# Verify DNS
dig agents.tamandua.treantlab.org

# Re-run enrollment; token is prompted without echo
sudo /Library/Application\ Support/Tamandua/tamandua-agent install

High CPU Usage

Cause: Aggressive monitoring or Endpoint Security event flood. Solution:

# Check current profile
grep performance_profile /Library/Application\ Support/Tamandua/config/agent.toml

# Switch to balanced profile
sudo sed -i '' 's/performance_profile = "aggressive"/performance_profile = "balanced"/' \
    "/Library/Application Support/Tamandua/config/agent.toml"

# Restart agent
sudo launchctl kickstart -k system/com.treantlab.tamandua.agent

Conflicts with Other Security Software

Cause: Multiple Endpoint Security clients competing for events. Solution:

1. Check for other ES clients:

   systemextensionsctl list | grep -i "endpoint"
   

1. If another EDR is installed, coordinate with your security team
2. Preview builds must be validated alongside other ES clients; event ordering and compatibility may vary

Agent Not Appearing in Console

Cause: Enrollment incomplete or network issues. Solution:

# Check agent logs for errors
log show --predicate 'subsystem == "com.treantlab.tamandua"' --last 15m | grep -i error

# Verify certificate was issued
ls -la /Library/Application\ Support/Tamandua/config/cert.pem

# Check WebSocket connectivity
sudo lsof -i :8443 | grep tamandua

Uninstall

Interactive Uninstall

1. Download the uninstaller from the admin console
2. Run Tamandua-Uninstaller.pkg
3. Enter your enrollment token when prompted

Command Line Uninstall

# Stop agent
sudo launchctl bootout system/com.treantlab.tamandua.agent

# Uninstall with token verification; token is prompted without echo
sudo /Library/Application\ Support/Tamandua/tamandua-agent uninstall

Manual Uninstall

# Stop agent
sudo launchctl bootout system/com.treantlab.tamandua.agent

# Remove system extension
sudo systemextensionsctl uninstall XXXXXXXXXX com.treantlab.tamandua.extension

# Remove files
sudo rm -rf "/Library/Application Support/Tamandua"
sudo rm -f /Library/LaunchDaemons/com.treantlab.tamandua.agent.plist

# Remove from Privacy settings (manual step in System Settings)

Remove MDM Profiles

If deployed via MDM:

1. Remove the device from the deployment scope
2. Remove the configuration profile via MDM command
3. The system extension approval will be revoked

Next Steps

• Configure the Agent - Customize agent settings
• Enrollment Guide - Manage agent enrollment
• Windows Installation - Install on Windows systems
• Linux Installation - Install on Linux systems