Control integrity
Control integrity covers attempts to disable, remove, weaken, or route around AgentKeeper on a workstation. It is the enterprise answer for situations where an AI agent suggests disabling a hook,...
Control integrity covers attempts to disable, remove, weaken, or route around AgentKeeper on a workstation. It is the enterprise answer for situations where an AI agent suggests disabling a hook, editing local settings, running through a helper script, or otherwise bypassing the control that just blocked an action.
What AgentKeeper protects
AgentKeeper treats these as managed control surfaces:
| Surface | Examples |
|---|---|
| AgentKeeper local state | ~/.agentkeeper/, ~/.agentkeeper-plugin/, API key and machine-id files |
| Agent settings | ~/.claude/settings.json, ~/.codex/config.toml, /etc/codex/requirements.toml |
| Hook scripts | pre-tool-hook.sh, post-tool-hook.sh, prompt hooks, session-start hooks |
| Service and launch state | AgentKeeper launch agents, managed gateway services, MDM-installed binaries |
| Runtime environment | Bypass toggles such as AGENTKEEPER_DISABLE, AGENTKEEPER_BYPASS, and skip flags |
Normal fleet configuration is not tampering. Jamf and support commands can still set AGENTKEEPER_API_URL=https://www.agentkeeper.dev, write credentials during enrollment, and run status helpers. The detector focuses on destructive changes, bypass toggles, and edits that would weaken enforcement.
What is blocked today
For supported pre-execution hook surfaces, Runtime Shield can block:
- Removing or moving AgentKeeper local state.
- Editing managed hook configuration files.
- Unsetting runtime credentials that the hook needs to enforce policy.
- Setting explicit bypass or disable environment variables.
- Prompting the agent to disable, remove, skip, or work around AgentKeeper.
- Hiding risky commands in a local helper script that the agent executes.
When a request is blocked, AgentKeeper includes guidance in the response:
Do not disable, remove, or bypass AgentKeeper. If this is authorized security testing, request a scoped Security Testing Exception from your AgentKeeper admin.
This wording is intentionally shown to the agent as well as the user. The goal is to steer the session away from creative bypass suggestions and toward an approved exception workflow.
Helper scripts
Agents sometimes suggest putting a blocked command into a local shell script and running that script. AgentKeeper inspects small local helper scripts invoked by common interpreters, including bash, sh, zsh, python, python3, and node.
AgentKeeper only inspects regular local files in the current working directory or a resolved absolute path. It does not chase remote code, huge files, directories, or arbitrary generated content.
Helper-script inspection requires a local command hook for PreToolUse. HTTP-only hooks can evaluate the visible command, such as bash /tmp/retest.sh, but cannot read /tmp/retest.sh before execution. Enterprise Jamf, Iru/Kandji, and Intune installs should use the command preflight hook under ~/.agentkeeper/scripts/pre-tool-hook.sh; that hook inspects the local script, forwards an enriched event to AgentKeeper for logging and policy evaluation, and falls back to a local block for critical preflight findings if the API is temporarily unavailable.
Governed exceptions
Authorized red-team, pentest, and SSRF validation work should use a scoped Security Testing Exception instead of disabling controls. A good exception records:
- The requester and approver.
- The workstation, user or group, source tool, and policy surface.
- The exact detector or blocked action.
- The allowed destination, path, command pattern, or MCP tool.
- The business reason and expiration time.
- The original blocked event as evidence.
Until the in-product exception flow is enabled for your org, document the exception in the security change ticket and keep AgentKeeper installed. Do not ask users to edit hook files, remove local state, or run with bypass flags.
Deployment health states
Use these states during a fleet rollout:
| State | Meaning | Action |
|---|---|---|
| Protected | Self-test, live events, and BLOCK validation all work | Continue rollout |
| Self-test only | Jamf/status path works, but the real agent has not loaded the hook | Restart the agent and run a live tool action |
| Degraded | Config exists, but policy fetch or event delivery is failing | Check API key, origin, network, and logs |
| Tamper suspected | A control integrity detector fired or hook files drifted | Repair with MDM and review the session |
| Exception active | An approved scoped exception is in effect | Monitor expiry and evidence |
| Unmanaged | No hook, gateway, or plugin evidence exists | Install or re-scope the device |
Jamf and MDM rollout checks
For Jamf, verify both installation and protection:
plutil -convert json -o /dev/null "$HOME/.claude/settings.json"
grep -n "agentkeeper" "$HOME/.claude/settings.json"
AGENTKEEPER_API_URL=https://www.agentkeeper.dev \
bash <(curl -fsSL https://www.agentkeeper.dev/cowork-status.sh) --self-test
Then run one real agent tool action and one known blocked action. The Workstations page should show the same machine row updating over time. Activity should show the expected source, policy verdict, detector, and workstation.
If an agent suggests bypassing AgentKeeper
- Do not choose an option that disables, removes, or edits AgentKeeper controls.
- Keep the blocked event as evidence.
- Decide whether the request is normal work, an authorized security test, or suspicious activity.
- For normal work, tune the policy or add an approved destination/path/tool.
- For authorized testing, create a scoped exception with an expiry.
- For suspicious activity, repair the endpoint through MDM and investigate neighboring events.
See Setup health, Enterprise install validation, and Security model for the larger validation flow.