Deploy a Sensor on macOS

This guide walks you through installing and enrolling an AttackLens sensor on a macOS machine.

Prerequisites

• Role: Posture Manager or higher.
• Enrollment token: You need a valid enrollment token. See Create an Enrollment Token if you have not created one yet.
• Network access: The target machine must be able to reach your AttackLens instance over HTTPS.
• Permissions: Administrator (sudo) access on the target machine.

Step 1: Download the Sensor Binary

1. In AttackLens, navigate to Settings > Sensor Downloads.
2. Download the binary that matches your Mac's processor:
   • sensor-darwin-amd64 for Intel-based Macs
   • sensor-darwin-arm64 for Apple Silicon Macs (M1, M2, M3, M4)

TIP

Not sure which architecture you need? Open Terminal and run:

uname -m

If the result is arm64, download the arm64 binary. If it is x86_64, download the amd64 binary.

Step 2: Make the Binary Executable

Open Terminal and set the executable permission:

chmod +x ~/Downloads/sensor-darwin-arm64

Adjust the filename if you downloaded the amd64 variant.

Step 3: Remove the Quarantine Attribute

macOS Gatekeeper may block the binary because it was downloaded from the internet. Remove the quarantine attribute:

xattr -d com.apple.quarantine ~/Downloads/sensor-darwin-arm64

WARNING

If you skip this step, macOS will display a dialog saying the binary "cannot be opened because the developer cannot be verified." You can also approve it through System Settings > Privacy & Security after the first blocked attempt, but removing the attribute beforehand is more straightforward.

Step 4: Move the Binary to a System Location

Move the sensor to a standard location:

sudo mv ~/Downloads/sensor-darwin-arm64 /usr/local/bin/attacklens-sensor

Step 5: Enroll the Sensor

Run the enrollment command with your AttackLens instance URL and the enrollment token:

sudo /usr/local/bin/attacklens-sensor enroll \
  --server https://your-attacklens-instance:8080 \
  --token YOUR_ENROLLMENT_TOKEN

Replace:

• your-attacklens-instance:8080 with the actual hostname and port of your AttackLens backend.
• YOUR_ENROLLMENT_TOKEN with the token you copied from AttackLens.

On successful enrollment, you will see output similar to:

[INFO] Enrolling sensor with AttackLens backend...
[INFO] Enrollment successful. Sensor ID: s-a1b2c3d4
[INFO] Starting sensor service...
[INFO] Sensor is now running.

Step 6: Install as a Launch Daemon

Create a launch daemon so the sensor starts automatically on boot:

sudo tee /Library/LaunchDaemons/com.attacklens.sensor.plist > /dev/null <<EOF
<?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>Label</key>
    <string>com.attacklens.sensor</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/attacklens-sensor</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/var/log/attacklens-sensor.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/attacklens-sensor.log</string>
</dict>
</plist>
EOF

Load and start the daemon:

sudo launchctl load /Library/LaunchDaemons/com.attacklens.sensor.plist

Step 7: Verify the Sensor

Check that the daemon is running:

sudo launchctl list | grep attacklens

You should see an entry for com.attacklens.sensor with a PID (the first column is not -).

In AttackLens, navigate to Sensors to confirm the new sensor appears in the list with an Online status.

WARNING

If the sensor shows as Pending for more than a few minutes, check the sensor logs:

tail -f /var/log/attacklens-sensor.log

Common issues include incorrect server URLs, expired enrollment tokens, or network connectivity problems.

macOS-Specific Considerations

Full Disk Access

Depending on your macOS version and security settings, the sensor may need Full Disk Access to read certain system configuration files. If you see permission errors in the logs:

1. Open System Settings > Privacy & Security > Full Disk Access.
2. Click the + button and add /usr/local/bin/attacklens-sensor.
3. Restart the sensor daemon.

Network Filtering

If your organization uses a content filter or firewall on macOS endpoints, ensure the sensor can reach your AttackLens instance on the configured HTTPS port.

Verify Data Collection

Once the sensor is online, it will begin its first data collection cycle. You can verify data is flowing by:

1. Navigating to Sensors and clicking on the new sensor.
2. Checking the Last Seen timestamp -- it should update within the collection interval.
3. Navigating to Inventory to see the Homebrew packages, running services, and security configurations discovered on the endpoint.

Uninstalling the Sensor

To remove a sensor from a macOS machine:

sudo launchctl unload /Library/LaunchDaemons/com.attacklens.sensor.plist
sudo rm /Library/LaunchDaemons/com.attacklens.sensor.plist
sudo rm /usr/local/bin/attacklens-sensor
sudo rm /var/log/attacklens-sensor.log

INFO

Uninstalling the sensor from the machine does not remove it from AttackLens. The sensor will appear as Offline in the sensor list. You can delete the sensor record from the AttackLens UI if it is no longer needed.

Next Steps

• Manage Sensors -- View sensor details, link to assets, monitor status.
• Sensor Auto-Update -- Learn how sensors keep themselves up to date.