mirror of
https://github.com/openai/codex.git
synced 2026-04-29 19:03:02 +03:00
4816b89204
## Why
`PermissionProfile` is becoming the canonical permissions abstraction,
but the old shape only carried optional filesystem and network fields.
It could describe allowed access, but not who is responsible for
enforcing it. That made `DangerFullAccess` and `ExternalSandbox` lossy
when profiles were exported, cached, or round-tripped through app-server
APIs.
The important model change is that active permissions are now a disjoint
union over the enforcement mode. Conceptually:
```rust
pub enum PermissionProfile {
Managed {
file_system: FileSystemSandboxPolicy,
network: NetworkSandboxPolicy,
},
Disabled,
External {
network: NetworkSandboxPolicy,
},
}
```
This distinction matters because `Disabled` means Codex should apply no
outer sandbox at all, while `External` means filesystem isolation is
owned by an outside caller. Those are not equivalent to a broad managed
sandbox. For example, macOS cannot nest Seatbelt inside Seatbelt, so an
inner sandbox may require the outer Codex layer to use no sandbox rather
than a permissive one.
## How Existing Modeling Maps
Legacy `SandboxPolicy` remains a boundary projection, but it now maps
into the higher-fidelity profile model:
- `ReadOnly` and `WorkspaceWrite` map to `PermissionProfile::Managed`
with restricted filesystem entries plus the corresponding network
policy.
- `DangerFullAccess` maps to `PermissionProfile::Disabled`, preserving
the “no outer sandbox” intent instead of treating it as a lax managed
sandbox.
- `ExternalSandbox { network_access }` maps to
`PermissionProfile::External { network }`, preserving external
filesystem enforcement while still carrying the active network policy.
- Split runtime policies that legacy `SandboxPolicy` cannot faithfully
express, such as managed unrestricted filesystem plus restricted
network, stay `Managed` instead of being collapsed into
`ExternalSandbox`.
- Per-command/session/turn grants remain partial overlays via
`AdditionalPermissionProfile`; full `PermissionProfile` is reserved for
complete active runtime permissions.
## What Changed
- Change active `PermissionProfile` into a tagged union: `managed`,
`disabled`, and `external`.
- Keep partial permission grants separate with
`AdditionalPermissionProfile` for command/session/turn overlays.
- Represent managed filesystem permissions as either `restricted`
entries or `unrestricted`; `glob_scan_max_depth` is non-zero when
present.
- Preserve old rollout compatibility by accepting the pre-tagged `{
network, file_system }` profile shape during deserialization.
- Preserve fidelity for important edge cases: `DangerFullAccess`
round-trips as `disabled`, `ExternalSandbox` round-trips as `external`,
and managed unrestricted filesystem + restricted network stays managed
instead of being mistaken for external enforcement.
- Preserve configured deny-read entries and bounded glob scan depth when
full profiles are projected back into runtime policies, including
unrestricted replacements that now become `:root = write` plus deny
entries.
- Regenerate the experimental app-server v2 JSON/TypeScript schema and
update the `command/exec` README example for the tagged
`permissionProfile` shape.
## Compatibility
Legacy `SandboxPolicy` remains available at config/API boundaries as the
compatibility projection. Existing rollout lines with the old
`PermissionProfile` shape continue to load. The app-server
`permissionProfile` field is experimental, so its v2 wire shape is
intentionally updated to match the higher-fidelity model.
## Verification
- `just write-app-server-schema`
- `cargo check --tests`
- `cargo test -p codex-protocol permission_profile`
- `cargo test -p codex-protocol
preserving_deny_entries_keeps_unrestricted_policy_enforceable`
- `cargo test -p codex-app-server-protocol
permission_profile_file_system_permissions`
- `cargo test -p codex-app-server-protocol serialize_client_response`
- `cargo test -p codex-core
session_configured_reports_permission_profile_for_external_sandbox`
- `just fix`
- `just fix -p codex-protocol`
- `just fix -p codex-app-server-protocol`
- `just fix -p codex-core`
- `just fix -p codex-app-server`
656 lines
17 KiB
JSON
Generated
656 lines
17 KiB
JSON
Generated
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"definitions": {
|
|
"AbsolutePathBuf": {
|
|
"description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
|
|
"type": "string"
|
|
},
|
|
"CommandExecTerminalSize": {
|
|
"description": "PTY size in character cells for `command/exec` PTY sessions.",
|
|
"properties": {
|
|
"cols": {
|
|
"description": "Terminal width in character cells.",
|
|
"format": "uint16",
|
|
"minimum": 0.0,
|
|
"type": "integer"
|
|
},
|
|
"rows": {
|
|
"description": "Terminal height in character cells.",
|
|
"format": "uint16",
|
|
"minimum": 0.0,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"cols",
|
|
"rows"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"FileSystemAccessMode": {
|
|
"enum": [
|
|
"read",
|
|
"write",
|
|
"none"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"FileSystemPath": {
|
|
"oneOf": [
|
|
{
|
|
"properties": {
|
|
"path": {
|
|
"$ref": "#/definitions/AbsolutePathBuf"
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"path"
|
|
],
|
|
"title": "PathFileSystemPathType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"path",
|
|
"type"
|
|
],
|
|
"title": "PathFileSystemPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"pattern": {
|
|
"type": "string"
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"glob_pattern"
|
|
],
|
|
"title": "GlobPatternFileSystemPathType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"pattern",
|
|
"type"
|
|
],
|
|
"title": "GlobPatternFileSystemPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"type": {
|
|
"enum": [
|
|
"special"
|
|
],
|
|
"title": "SpecialFileSystemPathType",
|
|
"type": "string"
|
|
},
|
|
"value": {
|
|
"$ref": "#/definitions/FileSystemSpecialPath"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"value"
|
|
],
|
|
"title": "SpecialFileSystemPath",
|
|
"type": "object"
|
|
}
|
|
]
|
|
},
|
|
"FileSystemSandboxEntry": {
|
|
"properties": {
|
|
"access": {
|
|
"$ref": "#/definitions/FileSystemAccessMode"
|
|
},
|
|
"path": {
|
|
"$ref": "#/definitions/FileSystemPath"
|
|
}
|
|
},
|
|
"required": [
|
|
"access",
|
|
"path"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"FileSystemSpecialPath": {
|
|
"oneOf": [
|
|
{
|
|
"properties": {
|
|
"kind": {
|
|
"enum": [
|
|
"root"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"kind"
|
|
],
|
|
"title": "RootFileSystemSpecialPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"kind": {
|
|
"enum": [
|
|
"minimal"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"kind"
|
|
],
|
|
"title": "MinimalFileSystemSpecialPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"kind": {
|
|
"enum": [
|
|
"current_working_directory"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"kind"
|
|
],
|
|
"title": "CurrentWorkingDirectoryFileSystemSpecialPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"kind": {
|
|
"enum": [
|
|
"project_roots"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"subpath": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"kind"
|
|
],
|
|
"title": "KindFileSystemSpecialPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"kind": {
|
|
"enum": [
|
|
"tmpdir"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"kind"
|
|
],
|
|
"title": "TmpdirFileSystemSpecialPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"kind": {
|
|
"enum": [
|
|
"slash_tmp"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"kind"
|
|
],
|
|
"title": "SlashTmpFileSystemSpecialPath",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"kind": {
|
|
"enum": [
|
|
"unknown"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"path": {
|
|
"type": "string"
|
|
},
|
|
"subpath": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"kind",
|
|
"path"
|
|
],
|
|
"type": "object"
|
|
}
|
|
]
|
|
},
|
|
"NetworkAccess": {
|
|
"enum": [
|
|
"restricted",
|
|
"enabled"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"PermissionProfile": {
|
|
"oneOf": [
|
|
{
|
|
"description": "Codex owns sandbox construction for this profile.",
|
|
"properties": {
|
|
"fileSystem": {
|
|
"$ref": "#/definitions/PermissionProfileFileSystemPermissions"
|
|
},
|
|
"network": {
|
|
"$ref": "#/definitions/PermissionProfileNetworkPermissions"
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"managed"
|
|
],
|
|
"title": "ManagedPermissionProfileType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"fileSystem",
|
|
"network",
|
|
"type"
|
|
],
|
|
"title": "ManagedPermissionProfile",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"description": "Do not apply an outer sandbox.",
|
|
"properties": {
|
|
"type": {
|
|
"enum": [
|
|
"disabled"
|
|
],
|
|
"title": "DisabledPermissionProfileType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "DisabledPermissionProfile",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"description": "Filesystem isolation is enforced by an external caller.",
|
|
"properties": {
|
|
"network": {
|
|
"$ref": "#/definitions/PermissionProfileNetworkPermissions"
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"external"
|
|
],
|
|
"title": "ExternalPermissionProfileType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"network",
|
|
"type"
|
|
],
|
|
"title": "ExternalPermissionProfile",
|
|
"type": "object"
|
|
}
|
|
]
|
|
},
|
|
"PermissionProfileFileSystemPermissions": {
|
|
"oneOf": [
|
|
{
|
|
"properties": {
|
|
"entries": {
|
|
"items": {
|
|
"$ref": "#/definitions/FileSystemSandboxEntry"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"globScanMaxDepth": {
|
|
"format": "uint",
|
|
"minimum": 1.0,
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
]
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"restricted"
|
|
],
|
|
"title": "RestrictedPermissionProfileFileSystemPermissionsType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"entries",
|
|
"type"
|
|
],
|
|
"title": "RestrictedPermissionProfileFileSystemPermissions",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"type": {
|
|
"enum": [
|
|
"unrestricted"
|
|
],
|
|
"title": "UnrestrictedPermissionProfileFileSystemPermissionsType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "UnrestrictedPermissionProfileFileSystemPermissions",
|
|
"type": "object"
|
|
}
|
|
]
|
|
},
|
|
"PermissionProfileNetworkPermissions": {
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"required": [
|
|
"enabled"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ReadOnlyAccess": {
|
|
"oneOf": [
|
|
{
|
|
"properties": {
|
|
"includePlatformDefaults": {
|
|
"default": true,
|
|
"type": "boolean"
|
|
},
|
|
"readableRoots": {
|
|
"default": [],
|
|
"items": {
|
|
"$ref": "#/definitions/AbsolutePathBuf"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"restricted"
|
|
],
|
|
"title": "RestrictedReadOnlyAccessType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "RestrictedReadOnlyAccess",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"type": {
|
|
"enum": [
|
|
"fullAccess"
|
|
],
|
|
"title": "FullAccessReadOnlyAccessType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "FullAccessReadOnlyAccess",
|
|
"type": "object"
|
|
}
|
|
]
|
|
},
|
|
"SandboxPolicy": {
|
|
"oneOf": [
|
|
{
|
|
"properties": {
|
|
"type": {
|
|
"enum": [
|
|
"dangerFullAccess"
|
|
],
|
|
"title": "DangerFullAccessSandboxPolicyType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "DangerFullAccessSandboxPolicy",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"access": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/definitions/ReadOnlyAccess"
|
|
}
|
|
],
|
|
"default": {
|
|
"type": "fullAccess"
|
|
}
|
|
},
|
|
"networkAccess": {
|
|
"default": false,
|
|
"type": "boolean"
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"readOnly"
|
|
],
|
|
"title": "ReadOnlySandboxPolicyType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "ReadOnlySandboxPolicy",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"networkAccess": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/definitions/NetworkAccess"
|
|
}
|
|
],
|
|
"default": "restricted"
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"externalSandbox"
|
|
],
|
|
"title": "ExternalSandboxSandboxPolicyType",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "ExternalSandboxSandboxPolicy",
|
|
"type": "object"
|
|
},
|
|
{
|
|
"properties": {
|
|
"excludeSlashTmp": {
|
|
"default": false,
|
|
"type": "boolean"
|
|
},
|
|
"excludeTmpdirEnvVar": {
|
|
"default": false,
|
|
"type": "boolean"
|
|
},
|
|
"networkAccess": {
|
|
"default": false,
|
|
"type": "boolean"
|
|
},
|
|
"readOnlyAccess": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/definitions/ReadOnlyAccess"
|
|
}
|
|
],
|
|
"default": {
|
|
"type": "fullAccess"
|
|
}
|
|
},
|
|
"type": {
|
|
"enum": [
|
|
"workspaceWrite"
|
|
],
|
|
"title": "WorkspaceWriteSandboxPolicyType",
|
|
"type": "string"
|
|
},
|
|
"writableRoots": {
|
|
"default": [],
|
|
"items": {
|
|
"$ref": "#/definitions/AbsolutePathBuf"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
],
|
|
"title": "WorkspaceWriteSandboxPolicy",
|
|
"type": "object"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"description": "Run a standalone command (argv vector) in the server sandbox without creating a thread or turn.\n\nThe final `command/exec` response is deferred until the process exits and is sent only after all `command/exec/outputDelta` notifications for that connection have been emitted.",
|
|
"properties": {
|
|
"command": {
|
|
"description": "Command argv vector. Empty arrays are rejected.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"cwd": {
|
|
"description": "Optional working directory. Defaults to the server cwd.",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"disableOutputCap": {
|
|
"description": "Disable stdout/stderr capture truncation for this request.\n\nCannot be combined with `outputBytesCap`.",
|
|
"type": "boolean"
|
|
},
|
|
"disableTimeout": {
|
|
"description": "Disable the timeout entirely for this request.\n\nCannot be combined with `timeoutMs`.",
|
|
"type": "boolean"
|
|
},
|
|
"env": {
|
|
"additionalProperties": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"description": "Optional environment overrides merged into the server-computed environment.\n\nMatching names override inherited values. Set a key to `null` to unset an inherited variable.",
|
|
"type": [
|
|
"object",
|
|
"null"
|
|
]
|
|
},
|
|
"outputBytesCap": {
|
|
"description": "Optional per-stream stdout/stderr capture cap in bytes.\n\nWhen omitted, the server default applies. Cannot be combined with `disableOutputCap`.",
|
|
"format": "uint",
|
|
"minimum": 0.0,
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
]
|
|
},
|
|
"permissionProfile": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/PermissionProfile"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Optional full permissions profile for this command.\n\nDefaults to the user's configured permissions when omitted. Cannot be combined with `sandboxPolicy`."
|
|
},
|
|
"processId": {
|
|
"description": "Optional client-supplied, connection-scoped process id.\n\nRequired for `tty`, `streamStdin`, `streamStdoutStderr`, and follow-up `command/exec/write`, `command/exec/resize`, and `command/exec/terminate` calls. When omitted, buffered execution gets an internal id that is not exposed to the client.",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"sandboxPolicy": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/SandboxPolicy"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Optional sandbox policy for this command.\n\nUses the same shape as thread/turn execution sandbox configuration and defaults to the user's configured policy when omitted. Cannot be combined with `permissionProfile`."
|
|
},
|
|
"size": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/CommandExecTerminalSize"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Optional initial PTY size in character cells. Only valid when `tty` is true."
|
|
},
|
|
"streamStdin": {
|
|
"description": "Allow follow-up `command/exec/write` requests to write stdin bytes.\n\nRequires a client-supplied `processId`.",
|
|
"type": "boolean"
|
|
},
|
|
"streamStdoutStderr": {
|
|
"description": "Stream stdout/stderr via `command/exec/outputDelta` notifications.\n\nStreamed bytes are not duplicated into the final response and require a client-supplied `processId`.",
|
|
"type": "boolean"
|
|
},
|
|
"timeoutMs": {
|
|
"description": "Optional timeout in milliseconds.\n\nWhen omitted, the server default applies. Cannot be combined with `disableTimeout`.",
|
|
"format": "int64",
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
]
|
|
},
|
|
"tty": {
|
|
"description": "Enable PTY mode.\n\nThis implies `streamStdin` and `streamStdoutStderr`.",
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"required": [
|
|
"command"
|
|
],
|
|
"title": "CommandExecParams",
|
|
"type": "object"
|
|
} |