Den poison0-Agenten auf macOS installieren
Den poison0-Agenten auf dem Mac installieren, ausrollen, prüfen und entfernen.
Voraussetzungen
| Voraussetzung | Details |
|---|---|
| Prozessor | Apple M2 oder neuer, oder ein Intel-Mac mit AVX2 (Intel Haswell, 2013, oder neuer). Apple M1 wird nicht unterstützt. |
| Rechte | Administratorrechte. Der Installer läuft über sudo als root. |
| Installationsschlüssel | Ein Installationsschlüssel aus der Konsole, unter Geräte → Mehrere Geräte per Schlüssel. |
| KI-Agenten | Mindestens ein KI-Agent aus Unterstützte Agenten. |
Einen Mac installieren
Führen Sie diesen Befehl im Terminal aus.
curl -fsSL https://poisonzero.com/install.sh | sudo PZ_ENROLL_CODE="<install-key>" sh
Der Installer prüft das Programm gegen SHA256SUMS und bricht bei einer Abweichung ab. Dann installiert er den Dienst und registriert den Mac. In einem Terminal fragt er zusätzlich, ob er den Gerätenamen an die Konsole senden soll. Sie antworten mit Ja oder Nein, eine Vorgabe gibt es nicht. Ja sendet den Computernamen des Macs, Nein sendet keinen Namen. Bei Jamf, Intune und in Skripten ohne Terminal fragt er nicht und sendet keinen Namen.
Die Standardwerte ändern Sie mit den Umgebungsvariablen unter Referenz.
Mac prüfen
- Führen Sie
launchctl print system/com.poisonzero.daemonaus. Der Dienst sollte laufen. - Führen Sie
poison0 doctorin Ihrer Desktop-Sitzung aus. Der Befehl nennt, was nicht stimmt. - Öffnen Sie die Konsole. Der Mac steht unter Geräte.
poison0 ist auch als p0 und pz aufrufbar. Nutzt bereits ein anderes Programm einen dieser Namen, wird dieser Alias nicht angelegt.
Nach der ersten Installation lädt das Modell im Hintergrund. Die festen Regeln schützen sofort.
Auf viele Macs ausrollen
Nutzen Sie das Paket mit dem Profil Ihres Mandanten oder alternativ ein Jamf-Richtlinienskript oder ein Intune-Shellskript. Alle laufen als root.
Paket und Profil (Intune, Jamf)
Das ist der empfohlene Weg, er braucht kein Skript. Sie weisen denselben Macs zwei Dateien zu: das Paket poisonzero-<version>.pkg und das Profil Ihres Mandanten <slug>-poisonzero-macos.mobileconfig. Das Paket ist signiert (Developer ID Jon Knoll (RYR9QUYGWV)), von Apple notarisiert und für alle Kunden gleich. Das Profil enthält den Installationsschlüssel Ihres Mandanten und die Einstellung, ob der Computername als Gerätename gesendet wird.
- Öffnen Sie in der Konsole Geräte, klappen Sie Mehrere Geräte per Schlüssel auf und wählen Sie Intune-Paket herunterladen. Wählen Sie den Tab macOS.
- Optional: Setzen Sie den Haken bei Computername als Gerätenamen verwenden, bevor Sie das Profil herunterladen.
- Laden Sie bei 1. Paket herunterladen das Paket über den Link herunter.
- Laden Sie bei 2. Profil herunterladen das Profil mit Herunterladen herunter.
Schritte in Intune:
- Öffnen Sie Apps → macOS → Hinzufügen, wählen Sie Branchen-App und laden Sie das Paket hoch.
- Weisen Sie die App unter Erforderlich einer Gerätegruppe zu.
- Öffnen Sie Geräte → macOS → Konfiguration → Erstellen → Neue Richtlinie. Wählen Sie als Profiltyp Vorlagen → Benutzerdefiniert und als Bereitstellungskanal Gerätekanal. Laden Sie die Datei
.mobileconfighoch. - Weisen Sie das Profil derselben Gerätegruppe zu.
Schritte in Jamf Pro:
- Laden Sie unter Settings → Computer Management → Packages das Paket hoch.
- Legen Sie unter Computers → Policies eine Richtlinie an, die das Paket installiert (Packages → Install). Wählen Sie einen Trigger, zum Beispiel Recurring Check-in, und setzen Sie den Scope auf Ihre Macs.
- Laden Sie unter Computers → Configuration Profiles → Upload die Datei
.mobileconfighoch. - Setzen Sie den Scope des Profils auf dieselben Macs.
Paket und Profil gehören denselben Macs, die Reihenfolge ist egal. Sobald beides auf einem Mac liegt, meldet er sich bei Ihrem Mandanten an. Kommt das Profil später, erkennt ein Hintergrunddienst es und meldet den Mac dann an. Ohne das Profil verbindet sich der Mac nicht mit Ihrem Mandanten. Ob PoisonZero läuft, sehen Sie in der Konsole unter Geräte.
Das Profil enthält einen Installationsschlüssel, den alle Admins sehen, die Profile in Ihrem MDM lesen dürfen. Die Konsole listet ihn als Intune macOS profile mit dem Datum. Er gilt ein Jahr, widerrufen Sie ihn nach dem Rollout.
Zum Entfernen führen Sie die Deinstallation unter Deinstallieren aus. Bei einer Paketinstallation entfernt sie auch den Paketbeleg. Nehmen Sie Paket und Profil danach aus der Zuweisung in Ihrem MDM. Das Profil gibt es auch über die Admin-API: POST /v1/intune/macos-profile, siehe Admin-API.
Den Agenten installieren
Jamf und Intune starten das Skript ohne Terminal. Übergeben Sie den Schlüssel deshalb als Umgebungsvariable. In Intune legen Sie das Skript unter Geräte → macOS → Shellskripts an und setzen Skript als angemeldeter Benutzer ausführen auf Nein. Intune speichert den Skripttext samt Schlüssel, widerrufen Sie den Schlüssel deshalb nach dem Rollout in der Konsole. Gerätename: Ohne Ihre Wahl sendet PoisonZero keinen Namen, und die Konsole zeigt einen Platzhalter. PZ_DEVICE_NAME_FROM_HOSTNAME=1 im Skript unten sendet den Computernamen jedes Macs (Systemeinstellungen → Allgemein → Info → Name, der Name, den Intune anzeigt). Entfernen Sie die Variable, wenn kein Name gesendet werden soll. Die Alternativen PZ_DEVICE_NAME und PZ_DEVICE_NAMES_CSV stehen unter Referenz. Der Name wird nur bei der ersten Anmeldung gesetzt. Spätere Läufe des Skripts ändern ihn nicht, benennen Sie einen Mac dann in der Konsole um.
#!/bin/sh PZ_ENROLL_CODE="<install-key>" PZ_DEVICE_NAME_FROM_HOSTNAME=1 sh -c "$(curl -fsSL https://poisonzero.com/install.sh)"
Den Schutz für die KI-Agenten richtet PoisonZero nach der Installation selbst ein, in jedem Benutzerkonto und für alle unterstützten Agenten. Sie müssen dafür nichts tun.
Intune (macOS)
Alternativ liefert die Konsole das fertige Skript mit dem Installationsschlüssel Ihres Mandanten. Sie tippen in Intune nichts ein.
- Öffnen Sie in der Konsole Geräte, wählen Sie Intune-Paket herunterladen und den Tab macOS. Klappen Sie Andere Wege auf und laden Sie das Skript herunter.
- Legen Sie in Intune unter Geräte → macOS → Skripts → Hinzufügen ein Skript an und laden Sie die Datei hoch.
- Setzen Sie Skript als angemeldeter Benutzer ausführen auf Nein, damit es als root läuft. Die Häufigkeit lassen Sie auf Nicht konfiguriert, bei Wiederholungen bei Fehler tragen Sie zum Beispiel 3 ein.
- Weisen Sie das Skript einer Gerätegruppe zu.
Voraussetzungen: macOS 12 oder neuer, der Mac ist in Intune angemeldet und erreicht das Internet ohne Proxy. Den Intune-Agenten installiert Intune selbst, sobald dem Mac ein Skript zugewiesen ist. Er holt neue Skripts etwa alle 8 Stunden. Im Unternehmensportal beschleunigt Einstellungen prüfen den Abruf.
Das Skript meldet einen Mac, der schon registriert ist, kein zweites Mal an. Intune zeigt je Mac nur Erfolg oder Fehler. Ob PoisonZero läuft, sehen Sie in der Konsole unter Geräte.
Das Skript enthält einen Installationsschlüssel, den alle Intune-Admins mit Leserecht auf Skripts sehen. Die Konsole listet ihn als Intune macOS mit dem Datum. Er gilt ein Jahr, widerrufen Sie ihn nach dem Rollout.
Private Macs: signierte Konfiguration
Ein privater Mac holt keine Einstellungen aus der Cloud. Er liest eine signierte client-config.json.
- Öffnen Sie in der Konsole das Profil und wählen Sie Für Private exportieren.
- Übergeben Sie die Datei mit
PZ_CONFIGan den Installer, wie unten gezeigt. - Oder legen Sie sie mit dem Jamf-Skript ab, das die Konsole nach dem Export zeigt.
curl -fsSL https://poisonzero.com/install.sh | sudo \ PZ_ENROLL_CODE="<install-key>" PZ_CONFIG="./client-config.json" sh
Der Installer prüft die Datei mit poison0 config verify und legt sie unter /Library/Application Support/PoisonZero/client-config.json ab, lesbar nur für root.
Update
Cloud-Geräte aktualisieren sich selbst. Ausschalten können Sie das je Gerät in der Konsole unter Settings → Schutz & Geräte → Updates. Private Geräte aktualisieren sich nicht selbst.
Für ein Update von Hand führen Sie den Installationsbefehl erneut aus. Die Zugangsdaten bleiben erhalten. Mehr unter Updates und Lebenszyklus.
Ab dieser Version ist die Programmdatei /usr/local/bin/poison0. poisonzero verweist darauf und funktioniert weiter, Ordnerausschlüsse bleiben gültig. Für Datei- oder Prozessausschlüsse fügen Sie poison0 hinzu und behalten poisonzero, weil Agenten-Hooks es weiter aufrufen.
Deinstallieren
curl -fsSL https://poisonzero.com/install.sh | sudo sh -s -- --uninstall
Die Deinstallation entfernt zuerst die Agent-Hooks aller Nutzer und bricht ab, wenn das fehlschlägt. Danach entfernt sie den Dienst, das Programm für Bestätigungsdialoge, die Befehle, das Programm und das Datenverzeichnis.
Bei einer Homebrew-Installation entfernen Sie zuerst die Hooks:
poison0 remove-agent-integration && brew uninstall poisonzero
Offene Quarantänefälle
Die Deinstallation listet jeden offenen Quarantänefall mit Originalpfad, Quarantänekopie (*.infection.pz) und Weg zur Wiederherstellung. Eine Kopie bleibt in /Library/Application Support/PoisonZero-quarantine, lesbar nur für root.
Mit PZ_UNINSTALL_SKIP_QUARANTINE_COPY=1 entfällt diese Kopie. Nichts wird automatisch wiederhergestellt. Prüfen Sie jede Datei, bevor Sie sie wiederherstellen.
Zurückgehaltene Änderungen, die noch auf Prüfung warten, verwirft die Deinstallation. Um eine zu behalten, geben Sie sie vorher frei: Listen Sie sie mit poison0 quarantine pending auf und führen Sie poison0 quarantine pending approve <id> aus.
Fehlerbehebung
| Symptom | Ursache | Lösung |
|---|---|---|
poison0 doctor zeigt, dass der Download des Modells fehlgeschlagen ist. | Der Download im Hintergrund nach der ersten Installation wurde nicht abgeschlossen. | Führen Sie sudo poison0 model aus, um es sofort erneut zu versuchen. poison0 doctor zeigt den Grund. |
poison0 exec0 status zeigt, dass Claude Code den exec0-Hook nicht aufruft. | Die Claude-Code-Einstellungen kommen aus einem MDM-Profil (Domain com.anthropic.claudecode) oder der Admin-Konsole von claude.ai. Claude Code ignoriert dann 50-poisonzero-exec0.json. | Setzen Sie in dieser Quelle "managedSourcesBehavior": "merge" (Claude Code 2.1.242 oder neuer), oder kopieren Sie den Inhalt der Datei hinein. |
poison0 doctor meldet, dass die verwalteten Hooks aus sind. | Die verwalteten Einstellungen von Claude Code setzen "disableAllHooks": true. Das schaltet auch die verwalteten Hooks des Agenten aus. | Entfernen Sie die Einstellung dort, wo sie gesetzt ist: in managed-settings.json, einer anderen Datei in managed-settings.d/, dem MDM-Profil oder der Admin-Konsole von claude.ai. Der Agent ändert diese Quellen nie. |
| Die Installation bricht nach der Registrierung ab, und die signierte Konfiguration wird nicht abgelegt. | poison0 config verify hat client-config.json abgelehnt. Eine vorhandene Datei bleibt. | Schlagen Sie den Exit-Code unter Referenz nach. |
| Die Deinstallation bricht ab und entfernt nichts. | Sie konnte die Agent-Hooks nicht bei allen Nutzern entfernen. | Setzen Sie PZ_UNINSTALL_FORCE=1 und entfernen Sie die restlichen Einträge von Hand. |
Referenz
Umgebungsvariablen
Setzen Sie die Variablen, bevor der Installer startet. Ein Flag, übergeben nach sh -s --, hat Vorrang vor seiner Variablen.
| Variable | Wirkung |
|---|---|
PZ_ENROLL_CODE | Der Installationsschlüssel aus der Konsole. Auf einem registrierten Mac registriert ein neuer Schlüssel ihn erneut. |
PZ_APP_ID | Nur für einen Einmal-Code, der mit einer App-ID kam. |
PZ_HEADLESS | Wie Bestätigungsdialoge behandelt werden, wenn kein Desktop-Nutzer antworten kann. none (Standard) richtet sich nach dem angemeldeten Nutzer, standard behandelt den Mac immer als Gerät ohne Desktop, strict ist am strengsten. Flag: --headless. |
PZ_DEVICE_NAME | Der Gerätename in der Konsole, bis 63 Zeichen, nur a-z, 0-9 und -. Ohne Namen zeigt die Konsole einen Platzhalter. Stattdessen sendet PZ_DEVICE_NAME_FROM_HOSTNAME=1 den Computernamen des Macs (Systemeinstellungen → Allgemein → Info → Name), oder PZ_DEVICE_NAMES_CSV (Datei oder https-URL, Kopfzeile hostname,name) sucht den Mac über Computernamen, lokalen Hostnamen oder Hostnamen und sendet nur den Namen aus der CSV. Sind mehrere gesetzt, gilt PZ_DEVICE_NAME, danach die CSV. Sie wirken nur bei der ersten Anmeldung. Mehr im Onboarding. |
PZ_SETUP_AGENTS | Trägt den lokalen Statistikbefehl /poison0 in die genannten Agenten ein, zum Beispiel claude,codex. |
PZ_SETUP_STATUSLINE | Auf 1 setzen, um die Statusline in Claude Code einzutragen. Eine vorhandene Statusline bleibt. |
PZ_SETUP_EXEC0 | Auf off setzen, damit exec0 aus bleibt, auch nach Updates. Andere Werte werden ignoriert. Eingeschaltet wird es im Konsolenprofil oder mit sudo poison0 exec0 observe bzw. enforce. |
PZ_SETUP_LEAK0 | Nur für private Geräte. Setzt den leak0-Modus: enforce, observe oder off. Ohne die Variable und ohne Terminal bleibt leak0 aus. |
PZ_BACKEND | cpu (Standard) oder gpu. Ob der Mac die GPU nutzt, legt das Konsolenprofil fest. |
PZ_TIER | enterprise (Standard) oder ultra. Mit ultra bricht der Installer mit einem Fehler ab. Legen Sie Ultra deshalb im Konsolenprofil fest. |
PZ_NO_SHORT_ALIAS | Auf 1 setzen, um den Kurzbefehl p0 auszulassen. |
PZ_FETCH_ONLY | Auf 1 setzen, um das Programm nur herunterzuladen und zu prüfen, ohne Dienst und ohne Administratorrechte. Es landet in ./poison0 oder in PZ_FETCH_DEST. |
PZ_DRY_RUN | Auf 1 setzen, um den Installationsmodus auszugeben und vor jeder Änderung zu beenden. |
POISONZERO_DATA_DIR | Ändert das Datenverzeichnis von Installer und Agent. |
PZ_CONFIG | Pfad zu einer signierten client-config.json für einen privaten Mac. Flag: --config. |
PZ_QUARANTINE_RETENTION_DAYS | Nur für private Geräte. Tage, die ein Quarantänefall aufbewahrt wird, 1 bis 3650. Flag: --quarantine-retention-days. |
PZ_AUDIT_MAX_MB | Nur für private Geräte. Größe in MB, ab der das Audit-Log rotiert, 1 bis 1024. Flag: --audit-max-mb. |
Pfade und Dienst
| Element | Ort |
|---|---|
| Das Programm und seine Befehle. | /usr/local/bin/poison0. Die Befehle poisonzero, p0 und pz verweisen darauf. |
| Das Datenverzeichnis. | /Library/Application Support/PoisonZero, Eigentümer root:wheel. Es enthält die Zugangsdaten, die Registrierungsdatei, die Logs und die Quarantäne. |
| Der Dienst. | Der LaunchDaemon com.poisonzero.daemon. Er startet beim Booten und läuft als root. |
| Das Programm für Bestätigungsdialoge. | Der LaunchAgent com.poisonzero.notifier in jeder Benutzersitzung. Ohne angemeldeten Nutzer startet er bei der nächsten Anmeldung. |
| Das Dienst-Log. | daemon.log im Datenverzeichnis. Es rotiert bei 5 MB. |
| Die exec0-Hooks für Claude Code. | /Library/Application Support/ClaudeCode/managed-settings.d/50-poisonzero-exec0.json. Eine Homebrew-Installation unter einem Präfix des Nutzers nutzt ~/.claude/settings.json. |
exec0-Hooks in Claude Code
Der Agent ändert nie Ihre managed-settings.json und keine anderen Dateien in managed-settings.d/. So schalten Sie exec0 für Claude Code aus oder ein:
# turn off sudo poison0 setup-claude --toolgate-off # turn on sudo poison0 setup-claude --toolgate
Exit-Codes der signierten Konfiguration
poison0 config verify gibt diese Codes zurück. Der Installer legt die Datei nur bei 0 oder 6 ab.
| Exit-Code | Bedeutung |
|---|---|
| 0 | Die Datei ist gültig. |
| 6 | Die Lizenz fehlt noch. Der Dienst prüft die Datei beim Start. |
| 1 | Die Datei ist nicht lesbar. |
| 3 | Die Datei ist nicht für dieses Gerät signiert. |
| 4 | Die Datei ist veraltet oder abgelaufen. |
| 5 | Die Datei ist ungültig oder zu neu für diese Agent-Version. |
| 7 | Der Mac ist ein Cloud-Gerät, das die Datei ignoriert. |
Weiterlesen
Andere Betriebssysteme: Installationsüberblick. Hardware: Systemvoraussetzungen. Schutz je Agent: Unterstützte Agenten.