# Agent Safety & Controls

Control Droid with permission rules, hooks, sandboxing, IP restrictions, and Droid Shield secret scanning in high-security environments.

Factory treats LLMs as powerful but untrusted components. Droid's safety model combines **deterministic controls** that do not depend on model behavior with **Droid Shield** secret scanning for git commit and push operations. Even a frontier model operating with high autonomy stays inside the boundaries you set.

---

## Two layers of safety

<CardGroup cols={2}>
  <Card title="Deterministic controls" icon="shield-check" href="#command-controls">
    - Command permission rules: allow, ask, or block
    - Programmable hooks (9 lifecycle events)
    - Built-in sandboxing (filesystem + network)
    - Network egress allowlists
  </Card>
  <Card title="Droid Shield" icon="sparkles" href="/autonomy-and-safety/droid-shield">
    - Secret and credential scanning
    - `git commit` and `git push` protection
    - Learned classification models <Badge variant='accent'>Private Preview</Badge>
    - Fail-closed behavior when a diff is too large to scan
    - Hook-based DLP integration for custom checks
  </Card>
</CardGroup>

Build enterprise security primarily on deterministic controls. They are configured through [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control), so policies such as model access, command permission rules, sandbox rules, and managed hooks can be applied across laptops, CI, VMs, and airgapped environments.

<LabeledDivider label='Deterministic controls' />

## Command controls

Droid evaluates shell commands against [permission rules](/autonomy-and-safety/permission-rules).
Each rule matches an exact, ordered command prefix and includes examples that verify
its matching behavior.

| Decision | Effect |
| :------- | :----- |
| `allow` | Skip command approval for matching commands, subject to other controls. |
| `ask` | Require approval in normal permission-checked execution, even at High autonomy. |
| `block` | Reject matching commands without an approval path, including under `--skip-permissions-unsafe`. |

Organization rules claim repeated IDs before lower-priority definitions. Rules with
different IDs accumulate, and matching blocks take precedence over requests for
approval, which take precedence over allows. Commands with no policy match fall back
to normal approval handling.

Configure rules through [Enterprise Controls](/enterprise/hierarchical-settings-and-org-control#manage-permission-rules)
or the `permissionRules` setting. Use `droid rules check --command 'git push origin main'`
to preview command policy without executing the command.

<Note>
  `commandAllowlist`, `commandDenylist`, and `commandBlocklist` are **deprecated,
  not removed**. Existing lists remain respected for backward compatibility.
  Use permission rules for new policy. A native rule can replace a custom legacy
  restriction from the same source; see [migration guidance](/autonomy-and-safety/permission-rules#migrate-legacy-command-lists)
  before replacing entries.
</Note>

<Warning>
  Command rules are not a sandbox or a complete analysis of program behavior. Exact
  prefixes do not cover every equivalent executable path, argument order, or action
  inside a script. An allow is a permission grant, not proof of safety. Pair rules
  with sandboxing, managed hooks, and least-privilege credentials.
</Warning>

Command risk is also emitted via OTEL, so security teams can monitor how often high-risk commands are proposed or attempted.

---

## Hooks

Hooks are Droid's programmable enforcement and observability interface: they run your own code at defined points in the agent loop. There are **nine hook events**:

| Event | Fires when |
| --- | --- |
| `PreToolUse` | Before a tool runs (including shell commands, file edits, and git operations). |
| `PostToolUse` | After a tool completes. |
| `UserPromptSubmit` | When the user submits a prompt, before it reaches the model. |
| `Notification` | When Droid emits a notification. |
| `Stop` | When the main agent finishes responding. |
| `SubagentStop` | When a subagent finishes. |
| `PreCompact` | Before the context is compacted. |
| `SessionStart` | When a session starts. |
| `SessionEnd` | When a session ends. |

There are no separate "pre-git", "pre-command", or "post-edit" hooks. Those are `PreToolUse` and `PostToolUse` hooks scoped with a **matcher** that selects which tools (or command patterns) the hook applies to.

A hook controls the agent through its output. `PreToolUse` hooks can return a `permissionDecision` of `allow`, `deny`, or `ask`. More broadly, hook output can set `decision` (`block` or `approve`), `continue`, `suppressOutput`, a `systemMessage`, and structured `hookSpecificOutput`. This lets you, for example, block direct `git push` operations and redirect developers to internal PR tooling, or forward prompts and file snippets to a DLP or CASB API and deny operations that violate policy.

<Note>
  Set `allowManagedHooksOnly` in org settings to ensure only org-managed hooks run; project- and user-defined hooks are then ignored.
</Note>

See the [Hooks Guide](/harness/hooks) for the full event payloads, matcher syntax, and output schema.

---

## Sandboxing

Droid includes a built-in **sandbox** that isolates command execution and file access, so you can grant more autonomy without exposing the host. Configure it under the `sandbox` setting:

<ResponseField name="enabled" type="boolean">
  Turn sandboxing on.
</ResponseField>

<ResponseField name="mode" type="string">
  Sandbox scope: `per-command` (isolate each command) or `whole-process` (run the whole session sandboxed).
</ResponseField>

<ResponseField name="filesystem" type="object">
  Path access lists: `allowRead`, `allowWrite`, `denyRead`, `denyWrite`. Use deny lists to keep secrets such as `~/.ssh` and `~/.aws` out of reach.
</ResponseField>

<ResponseField name="network" type="object">
  Network access: `allowedDomains` plus `allowUnixSockets`, `allowAllUnixSockets`, `allowLocalBinding`, and `httpProxyPort` / `socksProxyPort` for routing egress through a proxy.
</ResponseField>

```json
{
  "sandbox": {
    "enabled": true,
    "mode": "per-command",
    "filesystem": {
      "denyRead": ["~/.ssh", "~/.aws"],
      "denyWrite": ["/etc"]
    },
    "network": {
      "allowedDomains": ["api.github.com", "registry.npmjs.org"]
    }
  }
}
```

Sandboxing is a first-class product feature, not just a recommendation to run Droid inside Docker. You can still combine it with external devcontainers or VMs for defense in depth, and tag OTEL sessions by environment (for example, `environment.type=local|ci|sandbox`) for environment-specific dashboards and alerts.

---

## Network controls

The built-in sandbox controls command-level network egress, while Enterprise Controls can also restrict which client IPs may access Factory APIs and applications.

<ResponseField name="sandbox.network.allowedDomains" type="string[]">
  Domains sandboxed commands may reach during a session.
</ResponseField>

<ResponseField name="networkPolicy.allowedIps" type="string[]">
  IPv4 addresses or CIDR ranges allowed to access Factory web, CLI, and API key surfaces. Must contain at least one entry when set.
</ResponseField>

Use sandbox network rules and corporate proxies for outbound restrictions. Use `networkPolicy.allowedIps` to reduce where authenticated Factory requests can originate.

<LabeledDivider label='Model-led safeguards' />

## Droid Shield: git secret scanning

**Droid Shield** (`enableDroidShield`) scans staged diffs before `git commit` and `git push`. It blocks the command when it detects likely secrets, and it fails closed when a diff is too large to scan safely.

For detection behavior, false positives, and recovery steps, see [Droid Shield](/autonomy-and-safety/droid-shield).

Use hooks when you need custom DLP, approval workflows, prompt inspection, or calls to internal security systems. Org admins can enforce Droid Shield and managed hooks at the org or project level; users cannot disable controls that are locked by those settings.

---

## Steering as a complement

Deterministic controls are the foundation; **LLM steering** reduces how often dangerous actions are even proposed. Org and project settings can define rules and instructions (security guidelines and coding standards applied to every request), standardized commands and workflows (for example, `/security-review`), and context enrichment through allowlisted MCP servers so models work from accurate information. Because these are instructions, not enforcement, they complement rather than replace the hard boundaries above.

For the full schema behind every control on this page, see [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control).

<RelatedLinks>
  <RelatedLink href="/enterprise/hierarchical-settings-and-org-control" title="Enterprise Controls & Managed Settings">
    Configure the managed settings schema for command lists, sandbox, and hooks.
  </RelatedLink>
  <RelatedLink href="/autonomy-and-safety/droid-shield" title="Droid Shield">
    Deep dive into secret scanning for git commit and push operations.
  </RelatedLink>
</RelatedLinks>