# Sentinel Endpoint — Intune upload (macOS)

Built: 2026-05-28T15:25:05Z
Version: 1.0.15
QA source: `/Users/runner/work/sentinel-endpoint-agent/sentinel-endpoint-agent/test_results/qa_release_v1.0.15_mac_20260528_152430`
PKG: `quilrai-endpoint-v1.0.15_unsigned.pkg`
Offline mode: true

## 1. Deploy configuration profiles FIRST (same Entra group as the app)

Upload these **macOS configuration profiles** in Intune **before** the PKG:

1. `quilr-endpoint-agent-nw-extension.mobileconfig` — pre-approves the network/system extension **ai.quilr.agent.sentinel.extension** and silences the content-filter prompt
2. `quilr-endpoint-agent_FullDiskAccess.mobileconfig` — Full Disk Access (PPPC) for **ai.quilr.agent.sentinel**

Both profiles are the canonical hand-maintained copies from `scripts/distribution/mdm/profiles/` (bundle IDs, Team ID `W8FHSH4RM5`, and code requirements baked in).

## 1b. CA certificates (`certs/`)

Raw PEM files are shipped at `certs/` for admin-side trust deployment:

- `certs/quilr-ea-intermediate-ca.crt` — Quilr EA Intermediate CA
- `certs/quilr-ea-root-ca.crt` — Quilr EA Root CA

Deploy via your usual cert tooling (Intune trusted-cert profile, JAMF certificate payload, manual Keychain import, etc.). They are **not required** for the agent to install — the installer trusts the MITM cert at install time — but pre-deploying via MDM gives system-wide trust before the agent runs.

## 2. Wait for MDM

Allow time for profile installation (macOS Intune check-in can be **up to ~8 hours** unless manually synced).

## 3. Deploy the PKG

- App type: **macOS** line-of-business / pkg.
- Upload: `quilrai-endpoint-v1.0.15_unsigned.pkg`
- Install command: *(leave default for PKG)*

## 4. Uninstall command (custom)

```bash
"/Library/Application Support/QuilrAI/quilrai-endpoint-uninstaller" --force
```

## 5. Detection rule

Use **custom detection script** and paste the contents of `detection_script.sh`.

## Metadata extracted at build time

| Field | Value |
|-------|-------|
| Team ID | W8FHSH4RM5 |
| App bundle ID | ai.quilr.agent.sentinel |
| Extension bundle ID | ai.quilr.agent.sentinel.extension |

## 6. Troubleshooting — coexistence with other security agents

The postinstall is **verbose and graceful**: every install produces a log even when blocked.

### Where to look first

| File | What it contains |
|------|------------------|
| `/Library/Application Support/QuilrAI/logs/postinstall-bootstrap.log` | Full postinstall trace — **start here** |
| `/var/log/quilr/quilrai-postinstall.log` | Mirror of the above (system-wide path) |
| `/Library/Application Support/QuilrAI/logs/quilrai-endpoint.log` | Installer's own log — **absent if the binary was blocked from running** |
| `/var/log/install.log` | macOS-level PKG install events |

### Log section guide

The bootstrap log is divided into labelled sections — `grep '\[<section>\]'` to filter:

| Section | Tells you |
|---------|-----------|
| `[boot]` | Identity, OS version, installer env vars, SIP state |
| `[vendors]` | Which other security agents are present (CrowdStrike, Netskope, Zscaler 1.x/2.x, SentinelOne, Defender, Jamf) |
| `[environment]` | Disk space, VPN tunnels, system proxy, loaded sysexts |
| `[pre-flight]` | Binary stat, codesign, xattr, gatekeeper assessment |
| `[quarantine-fix]` | Whether com.apple.quarantine was stripped from our binaries |
| `[smoke-test]` | Bounded `quilrai-endpoint --version` probe — **rc=124 = blocked by EDR** |
| `[install]` | Full installer output, bounded at 600s in offline mode |
| `[unified-log]` | macOS unified-log entries since install start (kernel/security denials) |
| `[post-run]` | Final state inventory: app, daemon, version, sysext registration |
| `[final-report]` | **Single-line PASS / PARTIAL / FAIL verdict + remediation hint** |

### Common failure modes

| Symptom in `[final-report]` | Likely cause | Fix |
|---|---|---|
| `FAIL — binary blocked from executing` | Gatekeeper / EDR / quarantine xattr | Allowlist Team ID `W8FHSH4RM5` and bundle id `ai.quilr.agent.sentinel` in the EDR named in `[vendors]` |
| `FAIL — install timed out at 600s` | AV doing on-access scanning, or hung CDN fetch | Allowlist `/usr/local/bin/quilrai-endpoint` and `/Applications/QuilrAIProxy.app` from FS scanning; allowlist Sentinel cloud endpoints in Zscaler/Netskope |
| `PARTIAL — version file missing` | Daemon staged but didn't finalize first run | Usually self-recovers on next launchd tick; otherwise rerun installer |
| `FAIL — installer exited N` | quilrai-endpoint hit an error | Review `[install]` section for installer output and `[unified-log]` for kernel denials |

### Vendor-specific allowlists

- **CrowdStrike Falcon**: in Falcon console → Endpoint Security → IOA Exceptions → add `/usr/local/bin/quilrai-endpoint` and `/Applications/QuilrAIProxy.app`
- **Netskope**: in Netskope tenant → Steering → Bypass → add Sentinel cloud endpoints (FQDN allowlist) and process-based bypass for `quilrai-endpoint`
- **Zscaler 1.x/2.x**: in ZIA/ZSA admin → SSL Inspection bypass → add Sentinel cloud FQDNs; in App Profile → add `SentinelProxy` to traffic-bypass
- **SentinelOne**: Endpoint → Exclusions → Path `/Applications/QuilrAIProxy.app` and `/usr/local/bin/quilrai-endpoint`

