Connect a macOS host#

Step 1 - Open Integrations#

Go to app.jutsu.ai and select Integrations in the left navigation. Open the Data Sources category if it is not already selected.

Step 2 - Select macOS host#

Find macOS host in the Endpoint data sources and select the card or its plus button.

This single setup enables the macOS audit trail and command-line process telemetry; compliance posture is installed during the same run.

Step 3 - Name the collector#

Enter a human-readable name that identifies the endpoint in your fleet, such as macos-finance-01 or adnan-macbook-pro.

The source types are fixed to macos.unified and macos.esf. Jutsu enforces this allowlist at ingest, so the token cannot be used to submit unrelated source types.

Step 4 - Create the collector#

Select Create. Jutsu registers the asset and mints a bearer secret for this Mac.

Step 5 - Copy the command and open Terminal#

In the Collector registered dialog, select Copy command. Optionally expand Verify script before running to download the per-OS script, compare its SHA-256 value, and then execute it. The hash confirms integrity in transit; it is not a code signature.

Open Terminal on the Mac you are enrolling. Use a trusted local or remote administrative session, because the copied line contains the collector secret.

Command pattern - always paste the exact command copied from your own Jutsu dialog

Step 6 - Run the installer and authorize sudo#

Paste the copied command and press Return. The bootstrap detects macOS, confirms that the token was created for macOS, downloads the platform installer, and asks to elevate because it installs system services.

Wait for the checks to finish. A successful run validates the Vector configuration, starts both LaunchDaemons, verifies the API and ingest endpoints, waits up to 60 seconds for the first event, and confirms osquery enrollment.

Step 7 - Confirm the asset in Jutsu#

Return to Jutsu, close the registration dialog, and open Assets. The new macOS asset should appear within about 60 seconds after events and health begin reaching Jutsu.

The card shows its name, macos.unified and macos.esf source types, current status, and last-seen time. Select the asset to inspect activity and health details.

Step 8 - Resolve a Full Disk Access warning#

Skip this step when the installer reports EndpointSecurity (macos.esf) source active.

If the installer reports that eslogger was denied Full Disk Access:

1. Open Apple menu > System Settings > Privacy & Security > Full Disk Access.
2. Unlock the settings if prompted, select Add, and add the Vector binary path printed by the installer. On Apple silicon this is commonly /opt/jutsu/bin/vector.
3. Add /usr/bin/eslogger as well. TCC can attribute the request to the responsible Vector process, so both paths are required by the Jutsu collector flow.
4. Restart the collector with the command below, then check the log for EndpointSecurity source activity.

Restart the collector after changing Full Disk Access

Verify collection and posture#

1. In Assets, confirm that the collector shows Connected and that Last seen updates approximately every 30 seconds.
2. Open the asset details and confirm that recent activity is present. On an idle Mac, event delivery can take longer even while health is current.
3. In Terminal, confirm that the Jutsu LaunchDaemon is loaded and inspect the collector log if needed.
4. On macOS 13+, confirm that the terminal install summary or collector log reports macos.esf active after any Full Disk Access change.
5. Open Compliance and allow up to about 1 hour for the first osquery posture checks to appear.

What healthy looks like#

Use these signals together. A current heartbeat confirms the agent is reporting; event and posture data can arrive on different schedules.

Asset status	Connected; a healthy heartbeat is current. Three missed 30-second heartbeats can move health offline.
Last seen	Refreshes from collector health approximately every 30 seconds.
Buffer	Low utilization with no recent discarded events or sink errors.
macos.unified	Security-relevant unified-log events arrive from the host.
macos.esf	Active on supported hosts after Full Disk Access is available.
Compliance	The macOS host appears with osquery results after its first schedule cycle.

Troubleshooting#

The token is rejected#

• A 401 or 403 during the first token check normally means the secret was rotated, revoked, copied incompletely, or created for another organization.
• Create or rotate a macOS collector in Jutsu and rerun with the newly shown command. The installer performs this check before installing anything.

The asset does not appear within about 60 seconds#

• Confirm that the installer reached Jutsu Agent installed (macOS) and did not stop on a red error line.
• Run the launchctl and log commands in the verification section.
• Confirm outbound HTTPS reaches the Jutsu API and /ingest endpoint. If the service is temporarily unreachable, Vector buffers events on disk and drains when connectivity returns.
• An idle host may not generate an event during the installer's 60-second confirmation window. Current health in Assets is stronger evidence that the service is running.
• Review the asset Severity filter if health is current but expected informational activity is absent.

Vector is not running#

• Inspect /var/log/jutsu-collector.log for a configuration, TLS, permission, or disk error.
• Confirm that the startup service exists at /Library/LaunchDaemons/ai.jutsu.collector.plist.
• Make sure /var/lib/vector has enough free storage. Vector can stop when a disk-buffer write cannot be completed safely.
• Restart with sudo launchctl kickstart -k system/ai.jutsu.collector after correcting the cause.

Troubleshooting - macOS-specific cases#

macos.esf is missing or repeatedly exits#

• Confirm the Mac is running macOS 13 or later and that /usr/bin/eslogger exists.
• Grant Full Disk Access to both the Vector binary and /usr/bin/eslogger, then restart the collector.
• If ESF is intentionally unavailable, macos.unified continues collecting. Record the reduced coverage in your endpoint inventory.

Installation fails on an Intel Mac#

• Install Homebrew before rerunning. The installer uses Homebrew for Vector on x86_64 because the pinned archive is unavailable for that architecture.
• If Homebrew reports an Xcode or Command Line Tools problem, update those tools and rerun the exact Jutsu command.
• The installer warns if the Homebrew Vector version differs from the tested pin; capture that warning when opening a support case.

Logs work, but Compliance stays unknown#

• osquery requires HTTPS for enroll, configuration, and result logging. A plain HTTP deployment can still receive Vector logs while posture remains unavailable.
• For an internal CA or TLS-inspecting proxy, rerun the per-OS installer with --tls-ca pointing to a trusted PEM bundle.
• Run sudo launchctl print system/io.osquery.agent and check that the installer reported osqueryd is running and enrolled.
• Allow up to about 1 hour for the first scheduled posture results after a successful enrollment.

Security and ongoing operations#

Protect the collector secret#

• Jutsu returns the plaintext collector secret once and stores only its cryptographic hash server-side.
• The installed host stores the secret in the root-owned Jutsu LaunchDaemon plist and in the osquery enrollment-secret file with restrictive permissions.
• Do not paste the command into tickets, chat, documentation, screen recordings, or screenshots. Review your shell-history policy because the pasted line contains the secret.
• If exposure is possible, rotate the secret in Jutsu and redeploy during the selected grace window. Set the grace window to zero for immediate invalidation when containment is more important than continuity.
• The token is limited to macos.unified and macos.esf at ingest. New collectors also start with a 1,000 EPS limit and a Medium minimum-severity filter.

Key local paths#

Collector service	/Library/LaunchDaemons/ai.jutsu.collector.plist
Collector config	/etc/jutsu/vector.yaml
Collector log	/var/log/jutsu-collector.log
Disk buffer	/var/lib/vector
Pinned Vector path	/opt/jutsu/bin/vector on the archive-based Apple-silicon install
osquery flags	/var/osquery/osquery.flags
osquery secret	/var/osquery/enroll.secret
osquery service	/Library/LaunchDaemons/io.osquery.agent.plist

Archive and uninstall#

Archiving and uninstalling are two separate actions. Complete both when removing a Mac from Jutsu.

1. Archive in Jutsu	Stops ingest server-side, invalidates the asset for ongoing use, and frees the plan slot. Previously collected events and alerts remain searchable.
2. Uninstall on the Mac	Stops the local LaunchDaemons and removes the Jutsu collector, disk buffer, configuration, logs, osquery enrollment, and installed agent files.

Preview what would be removed - no sudo required

Remove the Jutsu collector and osquery

Optional - remove Jutsu enrollment but keep a shared or pre-existing osquery installation

The uninstaller is idempotent: it reports items that are already absent and can be rerun safely. Use the uninstall command shown by the archive dialog when your Jutsu deployment uses a different API base URL.

Related documentation#

• Apple - Change Privacy & Security settings on Mac
• Vector - Buffering model
• osquery - Remote settings and TLS enrollment