Security model
An APF file describes the policy. The engine evaluates the proposed action, and a hook or wrapper enforces the outcome before invoking the tool. To know what protection you have, identify the tool paths that use that checkpoint, how the runtime behaves if it fails and who can change its configuration.
For two harnesses to enforce the same rule, both must recognize the relevant action, resource and conditions. For gates and budgets, they also need the applicable run history. Compare the supported integration paths.
What stays with your team
Your team runs the agents and holds the credentials used to access external providers. Nodrail Cloud integrations use a separate Nodrail credential to identify a connection. Keep it outside browser bundles, public repositories and agent-readable files where possible.
The local policy engine evaluates files without a Cloud account. The client and Cloud plugins send action requests to Nodrail for policy decisions and human review.
What reaches Cloud
For the documented plugins, file changes send paths and fingerprints rather than file contents. Commands, URLs, searches and MCP inputs may be sent for evaluation and review. Secret filtering is best effort; keep sensitive values out of those inputs. The Claude Code plugin also sends the run each call belongs to (NODRAIL_RUN, else the git branch name, else the session), the subagent taking it, and the receipt block a subagent ends its last message with, not the rest of that message.
The SDK's guard() sends tool arguments through its documented redaction and size limits. Direct run() and check() calls send the parameters you supply without that redaction. Do not assume every integration removes sensitive data. Result reporting describes completion status and duration; it is not a full recording of everything an agent did.
Decisions and approvals
The local engine can return allow, deny, require_approval or none. An unmatched or invalid decision must never be treated as implicit permission. In Cloud, a human review applies to the requested action, not arbitrary future actions. A reusable allow rule is a separate policy decision with its own scope.
Run history is what each installation reported, and it stays with that installation. A run belongs to the installation that declared its key: another installation, even in the same environment and with the same key, has a run of its own and can't finish its steps or meet its gates. Receipts and step names are still the integration's word, not verified facts.
An authorization is not proof of execution. A recorded outcome is a report from the integration. Protect installation credentials and configuration so that an agent cannot silently change its identity or remove the check.
Failure behavior depends on the integration
- TypeScript guard: requires a fresh exact authorization before invoking the wrapped tool; failed checks block that path.
- Claude Code plugin: uses the supported
onFailureconfiguration to block when the hook fails, including startup failure. - Codex plugin: blocks failed checks once the hook is running, but Codex can execute a tool if the hook cannot start at all. Installed hooks must also be activated.
- Your own local integration: must explicitly enforce engine results. Evaluating policy alone does not stop execution.
Check requirements and coverage
Mediated operations and isolated deployments
A covered operation passes through a checkpoint that can stop the underlying call. An operation outside that checkpoint is not governed by it. Examples include an unwrapped tool, changed hook settings, direct provider credentials, another MCP server or a different network route.
Full isolation requires controls outside the policy file: runtime permissions, protected configuration, credential boundaries and network restrictions. An allow rule for a shell program also does not inspect every operation that program may perform internally.
Choose those controls for your deployment and threat model. Do not describe an SDK or hook alone as a sandbox or a guarantee against a hostile agent that controls its own environment.
What held the merge in the GitHub pilot?
The runner read the candidate by commit SHA, checked the quota boundary independently of the QA agent, and attached matching review evidence to the APF evaluation. The operator posted the resulting status to the evaluated head. GitHub branch protection required that status and held the merge while it was missing or failing.
The pilot used one PR on a temporary branch. A production integration would also need a trusted status issuer and evidence that the PR author cannot rewrite. Read the GitHub merge check pilot.
Verify the boundary you use
Test explicit deny, unmatched calls, unavailable service, rejected credentials, expired approval waits and hook startup failure. Observe whether the underlying tool ran. Separately test that the agent cannot edit the configuration or use an unintended route around the checkpoint.
APF test cases check policy decisions. They complement integration and deployment tests; they do not replace them.
Read APF · Engine security reference
Report a vulnerability
Use the relevant repository's private security reporting instructions. Avoid posting credentials or exploitable details in a public issue.