Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/cli/configuration/settings.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ Local overrides merge on top of the corresponding `settings.json` at the same le
| `soundFocusMode` | `always`, `focused`, `unfocused` | `always` | When to play sound notifications. |
| `commandAllowlist` | Array of commands | Safe defaults provided | Commands that run without extra confirmation. |
| `commandDenylist` | Array of commands | Restrictive defaults provided | Commands that always require confirmation. |
| `commandBlocklist` | Array of commands | `[]` (none) | Commands that can never run, even when approvals are skipped. |
| `includeCoAuthoredByDroid` | `true`, `false` | `true` | Automatically append the Droid co-author trailer to commits. |
| `enableDroidShield` | `true`, `false` | `true` | Enable secret scanning and git guardrails. |
| `hooksDisabled` | `true`, `false` | `false` | Globally disable all hooks execution. |
Expand Down Expand Up @@ -135,25 +136,27 @@ The `ideAutoConnect` setting controls whether droid automatically connects to yo
- **`true`** – Auto-connect to IDE from any terminal


## Command allowlist & denylist
## Command allowlist, denylist & blocklist

Use these settings to control which commands droid can execute automatically and which it must never run:

- **`commandAllowlist`** – Commands in this array are treated as safe and run without additional confirmation, regardless of autonomy prompts. Include only low-risk utilities you rely on frequently (for example `ls`, `pwd`, `dir`).
- **`commandDenylist`** – Commands in this array always require confirmation and are typically blocked because they are destructive or unsafe (for example recursive `rm`, `mkfs`, or privileged system operations).
- **`commandDenylist`** – Commands in this array always require confirmation and are typically blocked because they are destructive or unsafe (for example recursive `rm`, `mkfs`, or privileged system operations). A denied command can still be run if you explicitly approve it.
- **`commandBlocklist`** – Commands in this array can **never** run. Unlike the denylist, there is no prompt and no way to approve them: the block applies even under full autonomy, auto-run, or `--skip-permissions-unsafe`. droid also resolves the actual program being invoked, so a blocked command cannot be slipped through with a wrapper shell, an absolute path, quoting tricks, or command substitution.

Commands that appear in both lists default to the denylist behavior. Any command that is in neither list falls back to the autonomy level you selected for the session.
Commands that appear in both the allowlist and denylist default to the denylist behavior. The blocklist always takes precedence over both. Any command that is in none of the lists falls back to the autonomy level you selected for the session.

### Example allow/deny configuration
### Example allow/deny/block configuration

```json
{
"commandAllowlist": ["ls", "pwd", "dir"],
"commandDenylist": ["rm -rf /", "mkfs", "shutdown"]
"commandDenylist": ["rm -rf /", "mkfs", "shutdown"],
"commandBlocklist": ["shutdown", "mkfs", "curl"]
}
```

Review and update these arrays periodically to match your workflow and security posture, especially when sharing configurations across teams.
Use `commandBlocklist` for commands that should be hard-stopped regardless of approvals; use `commandDenylist` for commands that are allowed only after explicit confirmation. Review and update these arrays periodically to match your workflow and security posture, especially when sharing configurations across teams.

## Session defaults

Expand Down
19 changes: 12 additions & 7 deletions docs/cli/user-guides/auto-run.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Autonomy Level sets the highest-risk work Droid can run without pausing for appr

## Choose a level

Execute commands and MCP tools have a risk level (`low`, `medium`, or `high`). Droid runs them automatically when the risk is at or below your Autonomy Level, unless a denylist or sandbox check requires approval.
Execute commands and MCP tools have a risk level (`low`, `medium`, or `high`). Droid runs them automatically when the risk is at or below your Autonomy Level, unless a denylist or sandbox check requires approval, or the command matches the blocklist. Blocklisted commands never run at any level and have no approval prompt.

| Autonomy Level | What can run without approval | Examples |
| -------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
Expand All @@ -26,22 +26,27 @@ Autonomy Level controls automatic approval, not which tools are available. Tool
- **Auto vs. Spec Mode** – In Auto, Autonomy Level controls approvals. Spec Mode is read-only planning; after approval, Droid exits Spec Mode and uses the selected Autonomy Level for implementation.
- **File changes** – Low or higher lets Droid create, edit, and patch files without asking first.
- **Commands and MCP tools** – Droid compares the tool risk level to your Autonomy Level. If the risk is higher, it asks before continuing.
- **Allowlisted commands** – Commands in the allowlist can run without approval unless they also match the denylist.
- **Safety checks** – Denylisted dangerous commands still ask at High, including dangerous commands nested inside `$(...)` or backticks. [Sandbox](/cli/configuration/sandbox) read, write, and network checks can also prompt separately.
- **Allowlisted commands** – Commands in the allowlist can run without approval unless they also match the denylist or blocklist.
- **Safety checks** – Denylisted dangerous commands still ask at High, including dangerous commands nested inside `$(...)` or backticks. Blocklisted commands are rejected outright at every level, with no approval prompt. [Sandbox](/cli/configuration/sandbox) read, write, and network checks can also prompt separately.
- **Allow always** – Choosing an “always allow” option raises the current Autonomy Level to the level required by that prompt. Sandbox “allow always” options instead persist the allowed path or domain.
- **Spec approval** – When approving a Spec Mode plan, choose **Proceed with implementation** to keep the current Autonomy Level, or choose an available Low, Medium, or High option for implementation. Organization Maximum Autonomy Level can hide higher options.

## Command allowlists and denylists
## Command allowlists, denylists, and blocklists
Comment thread
shashank-factory marked this conversation as resolved.

Use `commandAllowlist` and `commandDenylist` in [Settings](/cli/configuration/settings) to encode command policy for your user profile, a project, a local project override, or a nested folder.
Use `commandAllowlist`, `commandDenylist`, and `commandBlocklist` in [Settings](/cli/configuration/settings) to encode command policy for your user profile, a project, a local project override, or a nested folder.

- Allowlist entries are treated as low-risk for the matching scope.
- Denylist entries always take precedence over allowlist entries.
- Commands not covered by either list fall back to the active Autonomy Level and command restrictions.
- Denylist entries always take precedence over allowlist entries. A denied command still runs if you explicitly approve it.
- Blocklist entries can never run: there is no approval prompt, and the block holds even under full autonomy, auto-run, or `--skip-permissions-unsafe`. Use it for commands that must be hard-stopped regardless of approvals.
- Commands not covered by any list fall back to the active Autonomy Level and command restrictions.
- Organization-managed settings have the highest priority. Local and project settings can add defaults for a repo or machine, but they cannot weaken organization command policy or raise autonomy above the organization maximum. See [Hierarchical Settings & Org Control](/enterprise/hierarchical-settings-and-org-control).

The built-in denylist covers common destructive patterns such as filesystem wipes, disk formatting, shutdown commands, fork bombs, and broad permission or ownership changes. Add project-specific commands when your repo has additional dangerous scripts or deployment paths.

<Warning>
Because the blocklist cannot be bypassed by approval, it is the strongest control available. droid resolves the actual program being invoked before matching, so a blocked command cannot be slipped through with a wrapper shell (for example `bash -c "…"`), an absolute path, quoting tricks, or command substitution.
</Warning>

## Change the level

- Press `Ctrl+L` to cycle `Off → Low → Medium → High → Off`. Organization policy can cap the highest available level.
Expand Down
11 changes: 10 additions & 1 deletion docs/enterprise/hierarchical-settings-and-org-control.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,10 @@ Below is the full schema for org-managed settings. These are configured by org a
Whether sessions are synced to the cloud.
</ResponseField>

<ResponseField name="wikiCloudSync" type="boolean">
Whether AutoWiki content can be stored in the Factory App and synced to GitHub wikis.
</ResponseField>

<ResponseField name="includeCoAuthoredByDroid" type="boolean">
Include a `Co-authored-by: Droid` trailer in git commits.
</ResponseField>
Expand All @@ -106,7 +110,11 @@ Below is the full schema for org-managed settings. These are configured by org a
</ResponseField>

<ResponseField name="commandDenylist" type="string[]">
Shell command patterns that are always denied (accumulated across levels).
Shell command patterns that always require confirmation (accumulated across levels). A denylisted command can still run if the user explicitly approves it; use `commandBlocklist` for a hard block.
</ResponseField>

<ResponseField name="commandBlocklist" type="string[]">
Comment thread
shashank-factory marked this conversation as resolved.
Shell command patterns that can never run (accumulated across levels). Unlike the denylist, blocked commands have no approval path: the block holds even under full autonomy, auto-run, or `--skip-permissions-unsafe`. droid resolves the actual program being invoked before matching, so a blocked command cannot be bypassed with a wrapper shell, an absolute path, quoting tricks, or command substitution. Use this for organization-mandated hard stops.
</ResponseField>

<ResponseField name="customModels" type="object[]">
Expand Down Expand Up @@ -418,6 +426,7 @@ Again, users cannot override these rules; they can only choose safer personal de
"ideAutoConnect": true,
"commandAllowlist": ["npm *", "yarn *", "pnpm *", "make *"],
"commandDenylist": ["rm -rf /", "sudo *"],
"commandBlocklist": ["shutdown", "mkfs", "curl"],
"customModels": [
{
"model": "my-internal-model",
Expand Down
17 changes: 12 additions & 5 deletions docs/jp/cli/configuration/settings.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ droidの設定を行うには:
| `soundFocusMode` | `always`, `focused`, `unfocused` | `always` | 音声通知を再生するタイミング。 |
| `commandAllowlist` | コマンドの配列 | 安全なデフォルトが提供 | 追加確認なしで実行されるコマンド。 |
| `commandDenylist` | コマンドの配列 | 制限的なデフォルトが提供 | 常に確認が必要なコマンド。 |
| `commandBlocklist` | コマンドの配列 | `[]`(なし) | 承認をスキップしても絶対に実行されないコマンド。 |
| `includeCoAuthoredByDroid` | `true`, `false` | `true` | コミットにDroidの共同作成者トレーラーを自動追加します。 |
| `enableDroidShield` | `true`, `false` | `true` | シークレットスキャンとgitガードレールを有効にします。 |
| `hooksDisabled` | `true`, `false` | `false` | 全てのフックの実行をグローバルに無効にします。 |
Expand Down Expand Up @@ -134,16 +135,17 @@ droidイベントの音声フィードバックを設定します:
- **`false`** – IDEターミナル内での実行時のみ自動接続(デフォルト)
- **`true`** – 任意のターミナルからIDEに自動接続

## コマンド許可リストと拒否リスト
## コマンド許可リスト、拒否リスト、ブロックリスト

これらの設定を使用して、droidが自動実行できるコマンドと絶対に実行してはいけないコマンドを制御します:

- **`commandAllowlist`** – この配列内のコマンドは安全として扱われ、自律プロンプトに関係なく追加確認なしで実行されます。頻繁に使用する低リスクユーティリティのみを含めてください(例:`ls`、`pwd`、`dir`)。
- **`commandDenylist`** – この配列内のコマンドは常に確認が必要で、破壊的または危険なため通常ブロックされます(例:再帰的`rm`、`mkfs`、特権システム操作)。
- **`commandDenylist`** – この配列内のコマンドは常に確認が必要で、破壊的または危険なため通常ブロックされます(例:再帰的`rm`、`mkfs`、特権システム操作)。拒否されたコマンドでも、明示的に承認すれば実行できます。
- **`commandBlocklist`** – この配列内のコマンドは**絶対に**実行されません。拒否リストとは異なり、承認のプロンプトも承認する手段もありません。完全自律、自動実行、`--skip-permissions-unsafe`のいずれの場合でもブロックが適用されます。droidは実際に呼び出されるプログラムを解決してから照合するため、ラッパーシェル、絶対パス、クォートのトリック、コマンド置換でブロックを回避することはできません。

両方のリストに登場するコマンドは、拒否リストの動作がデフォルトとなります。どちらのリストにもないコマンドは、セッションで選択した自律レベルにフォールバックします。
許可リストと拒否リストの両方に登場するコマンドは、拒否リストの動作がデフォルトとなります。ブロックリストは常に両者より優先されます。いずれのリストにもないコマンドは、セッションで選択した自律レベルにフォールバックします。

### 許可/拒否設定例
### 許可/拒否/ブロック設定例
```json
{
"commandAllowlist": [
Expand All @@ -155,10 +157,15 @@ droidイベントの音声フィードバックを設定します:
"rm -rf /",
"mkfs",
"shutdown"
],
"commandBlocklist": [
"shutdown",
"mkfs",
"curl"
]
}
```
これらの配列を定期的に見直し更新して、ワークフローとセキュリティ体制に合わせてください。特にチーム間で設定を共有する場合は重要です。
承認に関係なくハードストップすべきコマンドには`commandBlocklist`を、明示的な確認後にのみ許可するコマンドには`commandDenylist`を使用してください。これらの配列を定期的に見直し更新して、ワークフローとセキュリティ体制に合わせてください。特にチーム間で設定を共有する場合は重要です。

## セッションデフォルト

Expand Down
Loading
Loading