Guardrails qua MDM
Guardrails chạy trên máy từng người dùng, nên muốn phủ cả đơn vị thì IT đẩy nó xuống bằng công cụ quản lý thiết bị (MDM). Trang này nói những gói có sẵn, cách dựng, nơi Guardrails ghi file trên từng hệ điều hành, cách kiểm và cách gỡ. Còn luật của Guardrails là chuyện khác, nằm trong gói policy trên Tara. Luật áp theo ba tầng (nền tảng, tổ chức, project), tầng dưới chỉ siết thêm được so với tầng trên.
Cá nhân cài cho máy mình vẫn dùng sudo ph guardrails install. Các gói MDM chạy đúng lệnh đó thay bạn, nên file ghi ra giống hệt.
Có những gói nào
| Hệ điều hành | Gói | Đẩy bằng |
|---|---|---|
| macOS | PhillipCLI-Guardrails-<version>.pkg | Jamf, Kandji, Intune (gói cần ký), installer -pkg |
| Linux | .deb và .rpm | apt, dnf, Ansible, Satellite |
| Windows | PhillipCLI-Guardrails-<version>-windows.zip (script PowerShell, đóng thành Win32 app) và Detect-Guardrails.ps1 | Intune, SCCM, cửa sổ PowerShell có quyền Administrator |
Mỗi tổ chức dựng một bộ gói riêng, vì địa chỉ Tara, Ryoma và khóa công khai được ghi vào cấu hình trong gói:
deploy/guardrails-mdm/build.sh all \
--tara https://tara.phillipcli.cloud --ryoma https://ryoma.phillipcli.cloud --keys ed25519:...Các tham số dựng như sau.
| Tham số | Ý nghĩa |
|---|---|
--tara | Địa chỉ Tara, nơi hook server tải policy |
--keys | Khóa công khai ed25519:... để kiểm chữ ký policy. Lấy từ GET /v1/signing-keys của Tara |
--ryoma | Địa chỉ Ryoma nhận số lần chặn. Tùy chọn |
--policy | Tên gói policy nền tảng, mặc định kit-policy-corporate |
--org | UUID tổ chức trên Claude. Ghi forceLoginOrgUUID để chỉ đăng nhập bằng tài khoản tổ chức, dùng với gói Team |
--managed-hooks-only | Chặn hook do plugin khai báo, chỉ cho hook của managed settings. Mặc định tắt |
--audit-upload | Gửi audit đã che về kho tập trung. Chỉ bật khi tổ chức đã quyết định |
--device-token-file | File chứa token thiết bị của tổ chức, để máy nhận policy mà chưa ai đăng nhập. Xem mục sau |
--selftest | warn (mặc định), strict hoặc skip: việc làm khi selftest lúc cài rớt |
--node-mac, --node-linux, --node-win | Đóng kèm Node.js. Không có thì máy phải có sẵn Node 22 trở lên |
Gói do chính Phillip cài: bước cài trên máy gọi ph guardrails install, nên đường dẫn, quyền và token riêng từng máy đều lấy từ cùng một mã. Nếu máy đã có managed settings của bên khác, bản cũ được sao lưu trước khi ghi.
Gói dựng không kèm token thiết bị thì mỗi người dùng phải đăng nhập Tara một lần bằng ph tara login, vì hook server tải policy bằng token của chính họ. Cho tới lúc đó Claude Code chặn mọi prompt. Token thiết bị bỏ bước này.
Máy mới chưa ai đăng nhập: token thiết bị
Máy vừa được MDM cài thì chưa ai chạy ph tara login, nên hook server chưa có token để tải policy nền tảng và Guardrails chặn tất cả (fail-closed). Token thiết bị cho máy nhận policy của tổ chức ngay khi cài.
Owner hoặc admin tạo token, từ phiên đăng nhập (Portal hoặc ph tara login). Token chỉ thuộc về một tổ chức và chỉ làm được ba việc: đọc danh sách policy nền tảng và tổ chức đang áp, tải các gói policy trong danh sách đó cùng chữ ký, và đọc danh sách thu hồi. Mọi route khác trả 403, kể cả policy tầng project. Tara chỉ lưu bản băm, và việc tạo, thu hồi đều vào nhật ký.
ph org device-token create "Laptop (Jamf)" --out device-token.env
deploy/guardrails-mdm/build.sh all --tara https://tara.phillipcli.cloud --keys ed25519:... \
--device-token-file device-token.envLệnh đầu ghi token vào file quyền 600 và không in ra màn hình. Portal có cùng chức năng ở Settings, Guardrails, mục "Device enrollment tokens". Dùng file thay vì tham số dòng lệnh để token không vào lịch sử shell hay danh sách tiến trình. Gói dựng với token mang token bên trong, nên chỉ đẩy qua MDM hoặc kho riêng.
Trên máy, ph guardrails install ghi token vào file guardrails-device.json cạnh bản Phillip, rồi script cài xóa token khỏi cấu hình trong gói. Token không nằm trong managed settings, file dịch vụ hay nhật ký. Chỉ quản trị viên ghi được file, nhưng mọi người dùng trên máy đọc được, vì hook server chạy bằng quyền người dùng. Rủi ro được giới hạn ở phía Tara: token chỉ đọc policy.
Người dùng đã đăng nhập Tara thì hook server dùng token của chính họ, nên policy tầng project vẫn áp. Token thiết bị là phương án dự phòng, dùng khi chưa ai đăng nhập hoặc token đăng nhập hết hạn. Hai giới hạn: chưa đăng nhập thì không có policy tầng project, và số liệu gửi về Ryoma cùng --audit-upload vẫn cần đăng nhập (audit trên máy vẫn ghi).
Xoay vòng: tạo token mới, dựng và đẩy gói mới, rồi thu hồi token cũ bằng ph org device-token revoke <id>. ph org device-token liệt kê token với hạn và lần dùng cuối. Token hết hạn hoặc bị thu hồi thì hook server đang chạy giữ policy đã nạp, nhưng sau khi khởi động lại mà không nạp được thì Claude Code chặn prompt cho tới khi máy có token hợp lệ.
Nơi Guardrails ghi file
| Hệ điều hành | Managed settings | Bản Phillip | Dịch vụ |
|---|---|---|---|
| macOS | /Library/Application Support/ClaudeCode/ | /Library/Application Support/AI-Forge/phillip | LaunchAgent chạy hook server |
| Linux | /etc/claude-code/ | /opt/ai-forge/phillip | systemd user unit, bật cho mọi người dùng |
| Windows | C:\Program Files\ClaudeCode\ | C:\Program Files\AI-Forge\phillip | Scheduled Task chạy lúc đăng nhập |
Hook server tự khởi động lại nếu bị dừng. Sau khi cài, phiên Claude Code mở trước đó phải mở lại để nạp hook. Đổi policy không cần đẩy lại gói, vì hook server tự tải policy mới từ Tara. Chỉ khi đổi địa chỉ Tara, địa chỉ Ryoma hay khóa thì bạn dựng và đẩy lại.
Managed settings cũng đẩy được từ admin console của Claude. Khi đó bạn giữ đúng khối hooks mà lệnh cài sinh ra trên từng máy, vì token trong đó khác nhau theo máy. Chúng tôi không có file .mobileconfig cho Claude Code, vì tài liệu không nói Claude Code đọc các thiết lập này từ profile.
Đẩy bằng công cụ của bạn
Jamf Pro. Tải .pkg lên, tạo policy với trigger Enrollment Complete hoặc Recurring Check-in, tần suất Once per computer.
Kandji. Thêm Custom App loại Package. Để Kandji tự cài lại khi mất Guardrails, dùng audit script kiểm grep -q "127.0.0.1:7802/hook" "/Library/Application Support/ClaudeCode/managed-settings.json".
Intune, Windows. Đóng thư mục script bằng IntuneWinAppUtil.exe (chạy trên Windows), rồi tạo Win32 app với các thiết lập sau.
| Mục | Giá trị |
|---|---|
| Install command | powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Install-Guardrails.ps1 |
| Uninstall command | powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Uninstall-Guardrails.ps1 |
| Install behavior | System |
| Detection rule | Custom script Detect-Guardrails.ps1 |
Linux. apt install ./phillip-guardrails_<version>_all.deb hoặc dnf install ./phillip-guardrails-<version>-1.noarch.rpm, hoặc đưa vào kho nội bộ.
Kiểm tra sau khi đẩy
Ngay lúc cài, gói chạy selftest trên một hook server tạm và ghi từng dòng vào nhật ký (/var/log/phillip-guardrails.log trên macOS và Linux, C:\ProgramData\AI-Forge\logs\guardrails-install.log trên Windows). Gói có token thiết bị thì selftest dùng token đó và đạt mà không cần đăng nhập. Gói không có token, hoặc Tara chưa với tới được, thì selftest lúc cài có thể rớt dù cài đúng. Ở chế độ warn bản cài vẫn giữ, bạn chạy lại selftest sau khi người dùng đăng nhập.
Trên một máy mẫu, bạn chạy ba lệnh sau khi MDM đã cài.
ph guardrails status
ph forge doctor
ph guardrails selfteststatus cho biết hook server có chạy không, policy nền tảng nào đang áp, hook server đang dùng đăng nhập của người dùng hay token thiết bị, và managed settings ở đâu. forge doctor có một dòng Guardrails. selftest gửi 16 kịch bản chấp nhận tới hook server đang chạy mà không gọi model, và phải đạt hết. Bạn nên chạy lại selftest sau mỗi lần đổi policy.
Nếu muốn thử bằng Claude Code thật, mở /status trong một phiên mới. Dòng Setting sources phải có Managed settings.
Hook server chạy bằng quyền của người dùng, nên một tiến trình độc hại cùng quyền có thể dừng nó. Guardrails có luật tự bảo vệ, dịch vụ tự khởi động lại, và forge doctor cùng status báo khi hook server không chạy. Nhưng nó là lớp đầu chứ không thay firewall hay proxy, và không chống người có quyền admin cố tình vượt rào. Phần đó là việc của MDM và quy định nội bộ.
Gỡ và khôi phục
Mỗi hệ điều hành có một cách gỡ, đều gọi ph guardrails uninstall bên dưới.
| Hệ điều hành | Lệnh gỡ |
|---|---|
| macOS | sudo "/Library/Application Support/AI-Forge/installer/uninstall.sh" |
| Linux | apt remove phillip-guardrails hoặc dnf remove phillip-guardrails |
| Windows | Uninstall-Guardrails.ps1 trong cửa sổ Administrator, hoặc Uninstall command của Intune |
Lệnh gỡ managed settings trước (khôi phục bản cũ đã sao lưu lúc cài), rồi mới tới dịch vụ và bản Phillip. Claude Code chạy lại bình thường như trước khi cài.