Deploy on macOS ​

The InfraScout agent runs as a launchd service and connects back to the InfraScout server over an encrypted channel. Once enrolled, the agent accepts shell commands from AI-driven assessments and optionally queries Active Directory over LDAP.

Prerequisites ​

You need macOS 12 (Monterey) or later, outbound network access to the InfraScout server on port 443, an enrollment token from the InfraScout dashboard (Settings → Enrollment Tokens), and administrator privileges on the host.

Download the Agent ​

Download the agent binary from the InfraScout dashboard under Settings → Downloads. Choose infrascout-agent-darwin-arm64 for Apple Silicon Macs or infrascout-agent-darwin-amd64 for Intel Macs.

Once downloaded, install the binary to /usr/local/bin/:

bash
sudo install -m 755 infrascout-agent-darwin-arm64 /usr/local/bin/infrascout-agent

Adjust the filename to match your architecture.

Enroll the Agent ​

Enrollment registers the host with the InfraScout server and provisions a mutual TLS certificate for the agent. Run the enrollment command as root:

bash
sudo infrascout-agent enroll \
    --token YOUR_ENROLLMENT_TOKEN \
    --server YOUR_SERVER_ADDRESS

Replace YOUR_ENROLLMENT_TOKEN with the token from the dashboard and YOUR_SERVER_ADDRESS with the gRPC server address shown in Settings → Enrollment Tokens. The agent performs a certificate exchange with the server and writes agent-config.yaml to /etc/infrascout/. When enrollment succeeds, the command prints a confirmation message that includes the agent's assigned ID.

INFO

The enrollment token is consumed on first use. Generate a new token from the dashboard if you need to re-enroll this host or enroll an additional host.

Install as a launchd Service ​

After enrollment, install the agent as a managed launchd service so it starts automatically on boot:

bash
sudo infrascout-agent service install

Load and start the service:

bash
sudo launchctl load /Library/LaunchDaemons/cloud.infrascout.agent.plist

Verify it is running:

bash
sudo launchctl list | grep infrascout

The service runs as root. To follow live log output, use the unified log stream:

bash
log stream --predicate 'subsystem == "cloud.infrascout.agent"'

Alternatively, check the log file at /var/log/infrascout/agent.log. To stop the service, unload the plist:

bash
sudo launchctl unload /Library/LaunchDaemons/cloud.infrascout.agent.plist

Configure LDAP (Optional) ​

If this host can reach an Active Directory domain controller, you can enable LDAP queries so assessments can read directory data from this agent. Add an ldap block to /etc/infrascout/agent-config.yaml:

yaml
ldap:
  server: ldap://dc01.example.com
  base_dn: DC=example,DC=com
  bind_dn: CN=svc-infrascout,OU=Service Accounts,DC=example,DC=com
  bind_password: YourServiceAccountPassword

After saving the file, restart the service by unloading and reloading the plist:

bash
sudo launchctl unload /Library/LaunchDaemons/cloud.infrascout.agent.plist && \
sudo launchctl load /Library/LaunchDaemons/cloud.infrascout.agent.plist

The agent encrypts bind_password in place on first startup, so the file will no longer contain the plaintext value after the service has run.

TIP

Use a read-only service account for the bind credentials. The agent only reads from Active Directory — it never writes to the directory.

Capabilities on macOS ​

After enrollment, this agent reports the shell capability to InfraScout, allowing assessments to run commands via /bin/sh. If LDAP is configured and the service restarts successfully, the agent also reports the ldap capability.

Windows-only capabilities — powershell, wmi, and eventlog — are not available on macOS hosts.

Troubleshooting ​

Gatekeeper blocks the binary — If macOS prevents the binary from running, remove the quarantine attribute applied to downloaded files:

bash
sudo xattr -rd com.apple.quarantine /usr/local/bin/infrascout-agent

Service not starting — Inspect the system log for the last ten minutes of agent output:

bash
log show --predicate 'subsystem == "cloud.infrascout.agent"' --last 10m

A missing config file or a certificate path mismatch under /etc/infrascout/ is the most common cause. Re-running enrollment usually resolves this.

Agent appears offline in the dashboard — Confirm the launchd job is loaded with sudo launchctl list | grep infrascout. Also verify the host clock is synchronized, since clock skew beyond a small tolerance causes the mTLS handshake to fail:

bash
sntp -sS time.apple.com