WeKnora/internal/sandbox
Captain 171097f06e
feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393)
* feat(security): add a whitelist-only outbound mode that refuses before DNS

A penetration test of a private deployment found that a host outside
SSRF_WHITELIST still produces a DNS query: every outbound guard resolves
the name first and judges the addresses afterwards, which is what makes
it immune to DNS rebinding, but it also means an attacker-chosen name
reaches the resolver and can carry data out of an otherwise offline
network (#3378).

SSRF_DNS_WHITELIST_ONLY makes the whitelist the whole egress policy, and
the check is placed wherever a name is still in hand.

Where a URL is available, CheckSSRFWhitelistOnly refuses a host the
whitelist does not name, IP literals included: URL validation, the
sandbox outbound policy, and the web-fetch target resolver.

Where only a dial address is available, CheckDialWhitelistOnly judges
hostnames and leaves addresses to the checks that already exist, because
an IP arriving at a dialer is either a name something else resolved or a
literal the URL layer already refused. That covers the shared SSRF-safe
dialer, the web-fetch dialer, the Yunzhijia webhook dialer, and every
sandbox transport: the HTTP and websocket data planes, the guarded
transport and the Docker engine now share one GuardedDialContext instead
of each building its own dialer.

Where the client resolves its own target, the name is judged before the
client exists. gRPC's resolver runs before any dialer it was given, so
the env-configured qdrant and milvus clients are built through small
constructors that refuse a non-whitelisted host outright; a whitelisted
one is resolved by gRPC as before.

docreader enforces the same switch in its own validator, and compose
passes the variable to both services.

Matching is by name only in this mode: the whitelist's CIDR entries
still match an IP literal, but a hostname is no longer resolved to see
whether its addresses fall inside one, because that lookup is the query
the mode exists to prevent.

The value is parsed with ParseBool, and a non-empty value that parses as
neither enables the mode: silently leaving an egress lockdown off
because an operator wrote "yes" is the one failure mode a security
control must not have.

Still not covered, and documented as such: the Langfuse OTLP exporter
builds its own client and never reaches these guards; and with
HTTP(S)_PROXY set the proxy host is dialled unguarded when the dial
address equals the proxy URL's host exactly, while a mismatch makes the
proxy host itself subject to the whitelist.

The switch defaults to off, so nothing changes for deployments that do
not set it.

* docs(security): document SSRF_DNS_WHITELIST_ONLY in website-docs

docs/ has been retired in favour of website-docs/ (#3580), so the notes that
lived in docs/QA.md move to the configuration table: the new switch, what to
whitelist before turning it on, and the three outbound paths it still does
not cover.

The existing SSRF_WHITELIST row was also stale: compose gives only the app its
SSRF_WHITELIST_EXTRA default (which now includes minio), and docreader's is
empty, so "shared by app and docreader" held for SSRF_WHITELIST alone.
2026-09-23 12:02:06 +08:00
..
desktopscripts feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
capabilities.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
check_client_guard_test.go feat(sandbox): 沙箱后端改为按空间配置,并补齐 E2B 模板与检测诊断 2026-08-11 15:42:02 +08:00
command_output.go feat(sandbox): stream live shell and install command output 2026-09-12 10:16:39 +08:00
config_identity.go feat(sandbox): Docker 后端支持会话级长驻容器与远程守护进程 2026-08-24 12:22:58 +08:00
config_identity_test.go feat(sandbox): remove the Local host-process backend 2026-08-26 17:48:21 +08:00
config_required.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
config_sandboxes.go feat(sandbox) (#2301) 2026-08-10 21:28:20 +08:00
config_sandboxes_test.go feat(sandbox) (#2301) 2026-08-10 21:28:20 +08:00
cube_dns.go feat(sandbox): pin Cube DNS on templates and freeze skill snapshot configs 2026-08-26 16:56:26 +08:00
cube_dns_test.go feat(sandbox): pin Cube DNS on templates and freeze skill snapshot configs 2026-08-26 16:56:26 +08:00
cube_egress_integration_test.go feat(sandbox): pin Cube DNS on templates and freeze skill snapshot configs 2026-08-26 16:56:26 +08:00
cube_integration_test.go feat(sandbox): add tenant-configurable network policy (#2995) 2026-09-03 10:49:46 +08:00
cube_mock_test.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
cube_remote_client.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
cube_remote_client_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
cube_template_catalog_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
cube_terminal.go feat(sandbox): add an interactive terminal and files tab beside chat (#3110) 2026-09-08 17:43:15 +08:00
cube_terminal_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
desktop.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
desktop_scripts.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
desktop_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
docker_enabled.go feat: require opt-in for the Docker sandbox backend (#2936) 2026-09-01 15:42:28 +08:00
docker_enabled_test.go feat: require opt-in for the Docker sandbox backend (#2936) 2026-09-01 15:42:28 +08:00
docker_engine.go feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393) 2026-09-23 12:02:06 +08:00
docker_host.go feat(sandbox): Docker 后端支持会话级长驻容器与远程守护进程 2026-08-24 12:22:58 +08:00
docker_host_test.go feat(sandbox): Docker 后端支持会话级长驻容器与远程守护进程 2026-08-24 12:22:58 +08:00
docker_idle_sweeper.go feat(sandbox): run sandboxed execs as root by default (#3067) 2026-09-07 13:03:35 +08:00
docker_idle_sweeper_test.go feat(sandbox): run sandboxed execs as root by default (#3067) 2026-09-07 13:03:35 +08:00
docker_integration_test.go fix(sandbox): use E2B BuildID as template version 2026-09-12 10:31:14 +08:00
docker_remote_client.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
docker_remote_client_test.go feat(sandbox): stream live shell and install command output 2026-09-12 10:16:39 +08:00
docker_rpc_timeout.go fix(sandbox): rebuild templates without dropping the live ID 2026-08-26 16:56:26 +08:00
docker_snapshot.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
docker_snapshot_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
docker_template_catalog.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
e2b_compatible_integration_test.go feat(sandbox): remove the Local host-process backend 2026-08-26 17:48:21 +08:00
e2b_exec_timeout_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
e2b_integration_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
e2b_remote_client.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
e2b_remote_client_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
e2b_rpc_timeout.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
e2b_terminal.go feat(sandbox): add an interactive terminal and files tab beside chat (#3110) 2026-09-08 17:43:15 +08:00
envd_compat_transport.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
envd_compat_transport_test.go feat(sandbox): run sandboxed execs as root by default (#3067) 2026-09-07 13:03:35 +08:00
filesystem_identity.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
filesystem_identity_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
gateway_transport.go feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393) 2026-09-23 12:02:06 +08:00
gateway_transport_test.go feat(sandbox): add tenant-configurable network policy (#2995) 2026-09-03 10:49:46 +08:00
inbound_token_registry.go fix(sandbox): always require inbound credentials 2026-09-03 13:34:40 +08:00
inbound_token_registry_test.go feat(sandbox): add tenant-configurable network policy (#2995) 2026-09-03 10:49:46 +08:00
langfuse.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
langfuse_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
manager.go feat(sandbox): remove the Local host-process backend 2026-08-26 17:48:21 +08:00
mkdir.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
mkdir_test.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
orphan_reaper.go feat(sandbox) (#2301) 2026-08-10 21:28:20 +08:00
orphan_reaper_test.go feat(sandbox) (#2301) 2026-08-10 21:28:20 +08:00
pty_input_coalesce.go feat(sandbox): add an interactive terminal and files tab beside chat (#3110) 2026-09-08 17:43:15 +08:00
pty_input_coalesce_test.go feat(sandbox): add an interactive terminal and files tab beside chat (#3110) 2026-09-08 17:43:15 +08:00
remote_client.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
remote_client_test.go feat(sandbox): add tenant-configurable network policy (#2995) 2026-09-03 10:49:46 +08:00
remote_errors.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
remote_errors_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
remote_fake_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
remote_sandbox.go feat(agent): write workspace scripts and run them with installed skills 2026-08-29 22:45:18 +08:00
remote_sandbox_test.go feat(agent): write workspace scripts and run them with installed skills 2026-08-29 22:45:18 +08:00
remote_snapshot_test.go fix(sandbox): keep skill image pointer out of sandbox config PUT 2026-08-24 16:00:23 +08:00
runtime_defaults.go feat(sandbox): Docker 后端支持会话级长驻容器与远程守护进程 2026-08-24 12:22:58 +08:00
sandbox.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
sandbox_test.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
session_binding.go feat(session): in-place rewind with workspace checkpoint reset (#3469) 2026-09-20 21:01:00 +08:00
session_binding_redis.go feat(session): in-place rewind with workspace checkpoint reset (#3469) 2026-09-20 21:01:00 +08:00
session_binding_redis_test.go feat(session): in-place rewind with workspace checkpoint reset (#3469) 2026-09-20 21:01:00 +08:00
session_binding_tenant_test.go feat(sandbox) (#2301) 2026-08-10 21:28:20 +08:00
session_binding_test.go feat(session): in-place rewind with workspace checkpoint reset (#3469) 2026-09-20 21:01:00 +08:00
session_bootstrapper.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
session_bootstrapper_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
session_connect.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
session_connect_test.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
session_file_operation.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
session_file_operation_test.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
session_lifecycle.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
session_lifecycle_test.go feat(session): fork conversations from a historical user message (#3304) 2026-09-17 14:20:18 +08:00
session_manager.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
session_manager_desktop_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
session_manager_terminal_test.go feat(sandbox): unify the interactive PTY prompt and reconnect running sandboxes (#3128) 2026-09-09 18:17:10 +08:00
session_manager_test.go feat(session): in-place rewind with workspace checkpoint reset (#3469) 2026-09-20 21:01:00 +08:00
session_shell_snapshot_test.go perf(sandbox): reduce redundant remote calls 2026-09-17 17:47:24 +08:00
shell_quote.go feat(sandbox): add tenant skill install and remove service layer 2026-08-24 17:51:13 +08:00
shell_quote_test.go feat(sandbox): add tenant skill install and remove service layer 2026-08-24 17:51:13 +08:00
skill_image.go feat(sandbox): remove the Local host-process backend 2026-08-26 17:48:21 +08:00
skill_paths.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
skill_paths_test.go feat(sandbox): run sandboxed execs as root by default (#3067) 2026-09-07 13:03:35 +08:00
template_catalog.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
template_catalog_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
tenant_config.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
tenant_config_test.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
tenant_resolver.go feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393) 2026-09-23 12:02:06 +08:00
tenant_resolver_test.go feat: require opt-in for the Docker sandbox backend (#2936) 2026-09-01 15:42:28 +08:00
terminal.go feat(sandbox): unify the interactive PTY prompt and reconnect running sandboxes (#3128) 2026-09-09 18:17:10 +08:00
terminal_test.go feat(sandbox): add an interactive terminal and files tab beside chat (#3110) 2026-09-08 17:43:15 +08:00
terminal_ttl_test.go feat(sandbox): add an interactive terminal and files tab beside chat (#3110) 2026-09-08 17:43:15 +08:00
url_guard.go feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393) 2026-09-23 12:02:06 +08:00
url_guard_test.go fix: share IP classification between SSRF and sandbox URL guards 2026-09-01 15:35:14 +08:00
url_guard_whitelist_only_test.go feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393) 2026-09-23 12:02:06 +08:00
validator.go perf(sandbox): compile command-substitution regexps once 2026-06-16 19:51:32 +08:00
validator_test.go feat(sandbox) (#2301) 2026-08-10 21:28:20 +08:00
websocket_dialer.go feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393) 2026-09-23 12:02:06 +08:00
websocket_dialer_test.go feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
workspace_failure_test.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
workspace_layout.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
workspace_layout_test.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
workspace_path.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00