# macOS Agent Deployment

## Scope

This document covers the API-connected macOS endpoint agent under `deploy/mac/`.

Current scope:

- collect macOS machine profile
- collect installed applications
- sync inventory into the ISA API
- poll lightweight central commands

Current non-goals:

- no macOS uninstall workflow yet
- no hostname rename workflow yet
- no signed `.pkg` installer yet

## Bundle Files

- `deploy/mac/run_agent.py`
- `deploy/mac/agent-config.example.json`
- `deploy/mac/software_audit_agent/`
- `deploy/mac/install_macos_agent.sh`
- `deploy/mac/uninstall_macos_agent.sh`

## Runtime Paths

- install dir: `/usr/local/software-audit-agent`
- config: `/usr/local/software-audit-agent/agent-config.json`
- queue: `/Library/Application Support/SoftwareAudit/queue`
- logs: `/Library/Application Support/SoftwareAudit/logs`

## Launchd Jobs

- `th.sru.softwareaudit.agent.cycle`
- `th.sru.softwareaudit.agent.poll`

Recommended intervals:

- `cycle`: every 4 hours
- `poll`: every 15 minutes

## Install

Self-service browser download:

- `/isa/downloads/mac/`
- `/isa/downloads/mac/Install-ISA-Agent-Appist.command.zip`

The `.zip` keeps the executable bit of the enclosed `.command` file. After extraction, the `.command` bootstrap downloads the current `deploy/mac` bundle into `~/Downloads/SoftwareAuditDeploy-mac` and then runs `install_macos_agent.sh` with `sudo`.

Run on the target Mac:

```bash
cd /path/to/deploy/mac
chmod +x install_macos_agent.sh uninstall_macos_agent.sh
sudo ./install_macos_agent.sh --prompt-api-key
```

Optional flags:

```bash
sudo ./install_macos_agent.sh \
  --server-base-url "https://appist.sru.ac.th/isa" \
  --site-name "Main Campus" \
  --department-name "International College" \
  --prompt-api-key
```

Authentication notes:

- current installer flow prompts for `api_key`
- runtime support also exists for `enrollment_token` when config is preseeded or managed manually
- when enrollment flow is used, the agent stores a per-client `api_key` in `/usr/local/software-audit-agent/agent-config.json`
- the runtime also stores a persistent `client_uuid` in `/usr/local/software-audit-agent/agent-config.json` after the first successful run

## Validate

Check launchd:

```bash
sudo launchctl print system/th.sru.softwareaudit.agent.cycle
sudo launchctl print system/th.sru.softwareaudit.agent.poll
```

Run the agent manually:

```bash
sudo "$(command -v python3)" /usr/local/software-audit-agent/run_agent.py \
  --config /usr/local/software-audit-agent/agent-config.json \
  cycle
```

Check logs:

```bash
tail -n 50 "/Library/Application Support/SoftwareAudit/logs/agent.log"
```

## Inventory Signals Collected

- hostname
- current username
- macOS version
- serial number
- hardware UUID when available
- primary IP address
- default gateway
- DNS servers
- DHCP or static signal when detectable
- application inventory from `system_profiler SPApplicationsDataType`

## Supported Central Commands

- `collect_inventory`
- `agent_ping`

Unsupported for now on macOS:

- `rename_hostname`
- `uninstall_software`

## Uninstall

```bash
cd /path/to/deploy/mac
sudo ./uninstall_macos_agent.sh
```

Keep local queue/log data:

```bash
sudo ./uninstall_macos_agent.sh --keep-data
```