Русский
Меню документации

Документация Agent Sandboxes · Задачи

Секреты и исходящий трафик: ключи, которых нет в песочнице

Обновлено · 7 мин чтения

Песочница выполняет код, которому вы можете не доверять: код агента, пользователя, пакета. Две настройки держат ее в рамках. Секрет — это ключ, которого в песочнице нет: она видит заглушку, а настоящий ключ в запрос подставляет прокси исходящего трафика, и только для хостов, которые вы назовете. Исходящий трафик — это список того, куда она вообще может подключаться.

Коротко
  • SetSecret хранит значение в рабочем пространстве вместе с его хостами; привязанная к нему переменная (EnvVar.secret) содержит заглушку, phs_….
  • Подстановка: только в заголовках HTTPS-запросов к хостам секрета, и в Authorization, и в x-api-key. Новое значение работает сразу.
  • egress.allow и deny: домены, поддомены, IP и CIDR, порт, если это не 80 и 443; deny побеждает; по умолчанию — куда угодно.
  • Наружу выходят только TCP и DNS, а DNS песочницы отвечает только для имен, которые разрешает список.

Step 1: Сохраните секрет с его хостами

У секрета есть имя (a-z, 0-9 и «-»), значение и хосты, куда это значение можно отправлять. Задавайте его из своего окружения, а не из промпта или файла в песочнице. Повторная установка заменяет значение и хосты вместе.

Python
import os

sandboxes.set_secret("openai", value=os.environ["OPENAI_API_KEY"], hosts=["api.openai.com"])
TypeScript
await sandboxes.setSecret({ name: "openai", value: process.env.OPENAI_API_KEY!, hosts: ["api.openai.com"] });
Go
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
	Name:  "openai",
	Value: os.Getenv("OPENAI_API_KEY"),
	Hosts: []string{"api.openai.com"},
})
Rust
sandboxes
    .set_secret(SetSecretRequest {
        name: "openai".into(),
        value: std::env::var("OPENAI_API_KEY")?,
        hosts: vec!["api.openai.com".into()],
        ..Default::default()
    })
    .await?;
CLI
$ printf %s "$OPENAI_API_KEY" | pethost sandbox secret set openai --host api.openai.com
✓ Set the secret openai for api.openai.com. Bind it:  --env <VARIABLE>=secret:openai
openai

Step 2: Создайте песочницу, которая его привязывает, за списком адресов

Привяжите переменную к секрету в environment песочницы и перечислите в egress.allow, куда ей можно подключаться: здесь это индекс пакетов Python и хост секрета. Исходящий трафик должен разрешать хосты секрета.

Python
from pethost.sandboxes import Egress, Environment, EnvVar, SandboxSettings

sandbox = sandboxes.create_sandbox("base", settings=SandboxSettings(
    environment=Environment(variables=[EnvVar(name="OPENAI_API_KEY", secret="openai")]),
    egress=Egress(allow=["pypi.org", "files.pythonhosted.org", "api.openai.com"]),
))
sandbox_id = sandbox.sandbox_id
TypeScript
const sandbox = await sandboxes.createSandbox({
  template: "base",
  settings: {
    environment: { variables: [{ name: "OPENAI_API_KEY", secret: "openai" }] },
    egress: { allow: ["pypi.org", "files.pythonhosted.org", "api.openai.com"] },
  },
});
const sandboxId = sandbox.sandboxId;
Go
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base", Settings: &sandboxes.SandboxSettings{
	Environment: &sandboxes.Environment{Variables: []sandboxes.EnvVar{
		{Name: "OPENAI_API_KEY", Source: sandboxes.EnvVarSecret("openai")},
	}},
	Egress: &sandboxes.Egress{Allow: []string{"pypi.org", "files.pythonhosted.org", "api.openai.com"}},
}})
if err != nil {
	log.Fatal(err)
}
id := sandbox.SandboxID
Rust
let key = EnvVar { name: "OPENAI_API_KEY".into(), source: Some(EnvVarSource::Secret("openai".into())) };
let allow = ["pypi.org", "files.pythonhosted.org", "api.openai.com"].map(String::from).to_vec();
let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "base".into(),
        settings: Some(SandboxSettings {
            environment: Some(Environment { variables: vec![key] }),
            egress: Some(Egress { allow, ..Default::default() }),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
let id = sandbox.sandbox_id.clone();
CLI
$ pethost sandbox new --name fenced --env OPENAI_API_KEY=secret:openai \
    --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com
✓ Made sandbox fenced (xhww8xdrh7jj2d8c): default, running, from base@17, in <1 s
xhww8xdrh7jj2d8c
Next:   pethost sandbox run xhww8xdrh7jj2d8c -- <command>   ·   pethost sandbox shell xhww8xdrh7jj2d8c
MCP
CreateSandbox {"name": "fenced", "settings": {"environment": {"variables": [{"name": "OPENAI_API_KEY", "secret": "openai"}]}, "egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com"]}}}

Step 3: Посмотрите, что видит песочница

Внутри переменная содержит заглушку, запрос к хосту секрета несет ключ, а имя, которого нет в списке, даже не резолвится.

Python
check = sandboxes.run_command(sandbox_id, command=(
    'echo "$OPENAI_API_KEY" | cut -c1-8; '
    'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; '
    'curl -sS https://example.com'
))
print(check.stdout, check.stderr)
# phs_szjl
# 401
#  curl: (6) Could not resolve host: example.com
TypeScript
const check = await sandboxes.runCommand({
  sandboxId,
  command:
    'echo "$OPENAI_API_KEY" | cut -c1-8; ' +
    'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ' +
    "curl -sS https://example.com",
});
console.log(check.stdout, check.stderr);
Go
check, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: `echo "$OPENAI_API_KEY" | cut -c1-8; ` +
	`curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ` +
	`curl -sS https://example.com`})
if err != nil {
	log.Fatal(err)
}
fmt.Println(check.Stdout, check.Stderr)
Rust
let check = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: id.clone(),
        command: concat!(
            r#"echo "$OPENAI_API_KEY" | cut -c1-8; "#,
            r#"curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; "#,
            "curl -sS https://example.com",
        )
        .into(),
        ..Default::default()
    })
    .await?;
println!("{} {}", check.stdout, check.stderr);

В прогоне выше был сохранен выдуманный ключ, на который OpenAI ответил 401; ваш настоящий ключ получит 200. В любом случае запрос ушел из песочницы с сохраненным значением на месте заглушки.

Step 4: Меняйте список на ходу

UpdateSandbox с группой egress сразу заменяет весь список и закрывает подключения, которые он больше не разрешает. Новому значению секрета ничего не нужно: снова вызовите SetSecret, и каждая песочница, которая его привязывает, отправит новое со следующего запроса.

CLI
$ pethost sandbox set fenced --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com --allow github.com:22
MCP
UpdateSandbox {"sandbox_id": "…", "settings": {"egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com", "github.com:22"]}}}

Как работает секрет

Значение секрета хранится в панели в зашифрованном виде и в памяти серверов, на которых работают песочницы, которые его привязывают: никогда на диске песочницы, никогда в ее памяти, никогда в ответе API. Привязанная к нему переменная содержит заглушку, которая начинается с phs_, одну и ту же для всех процессов песочницы.

Прокси исходящего трафика песочницы завершает TLS только для хостов секрета, сертификатом удостоверяющего центра самого сервера, которому песочница доверяет: на него настроены Node, Python, curl и git. В каждом запросе к этим хостам он заменяет заглушку значением везде, где она встречается в значении заголовка: Authorization: Bearer, x-api-key, внутри учетных данных Authorization: Basic. Запрос к любому другому хосту несет заглушку, которая там ничего не стоит. Подстановка — только в заголовках, а не в теле запроса.

  • Хосты записываются так же, как домены в настройках исходящего трафика: api.openai.com или *.example.com для его поддоменов, с портом, если это не 443.
  • Новое значение работает сразу, в каждой работающей песочнице и форке, которые привязывают секрет.
  • Привязанный секрет нельзя удалить: DeleteSecret получает отказ, пока его привязывает неудаленная песочница.
  • В рабочем пространстве до 100 секретов. GetWorkspace перечисляет их имена и хосты, но никогда значения.

События исходящего трафика говорят по каждому хосту и минуте, какие секреты подставлялись в его запросы: наблюдаемость.

Как работает исходящий трафик

У egress песочницы два списка. allow говорит, куда ей можно подключаться, deny — куда нельзя, и deny побеждает. По умолчанию allow — ["*"], куда угодно. Отправленная группа заменяет всю группу: deny, отправленный один, оставляет allow пустым, поэтому, чтобы заблокировать несколько хостов, отправляйте вместе с ними allow ["*"]. Вместе в них до 100 записей длиной до 255 байт.

ЗаписьОткрывает
*Куда угодно.
pypi.orgЭтот домен, на портах 80 и 443.
*.github.comЕго поддомены любой глубины, но не сам github.com.
github.com:22Этот домен на этом порту: git по SSH.
203.0.113.7, 203.0.113.0/24Эти адреса при подключении по адресу, с :port, если это не 80 и 443.
  • Из песочницы выходят только TCP и DNS: UDP нет, а значит, нет QUIC и HTTP/3, и нет ping, что бы ни говорил список.
  • DNS отвечает только для разрешенных имен. Резолвер песочницы отвечает REFUSED для имени, которого не разрешает ни одна запись домена, никого не спрашивая, так что через DNS-запросы данные не утекают.
  • TLS проверяется по имени, которое отправляет клиент, а прокси подключается к адресу, который зарезолвил сам, и никогда к тому, что выбрала песочница. Запись домена доверяет всему, что отдают адреса этого имени, включая другие сайты того же CDN: ограждение, которое должно держать и там, называет IP или привязывает к хосту секрет — тогда прокси читает его запросы по одному.
  • Обычный HTTP проверяется по каждому запросу: на запрос к другому хосту, а не к тому, для которого открыто подключение, приходит 421, а новое подключение клиента проверяется уже по этому хосту.
  • SSH и другие протоколы не называют хост и проходят только к записи домена, где указан порт, например github.com:22.
  • Всегда запрещены: частные, link-local и CGNAT-адреса, сам сервер, порт 25 и HTTP/2 без TLS.
  • Отказ, на который прокси может ответить, — это 403, где сказано, что именно отказало.

У каждой песочницы есть и свои границы: 200 новых подключений в секунду после всплеска в 1 000, 1 024 открытых одновременно и 200 DNS-запросов в секунду.

Списки, которые работают

Для чегоallow
pip и uvpypi.org, files.pythonhosted.org
npmregistry.npmjs.org
git по HTTPS и SSHgithub.com, *.githubusercontent.com, github.com:22
Claude Codeapi.anthropic.com
Codexapi.openai.com

Посмотрите на события исходящего трафика песочницы за минуту настоящей работы, чтобы найти, что еще ей нужно: каждое называет хост, было ли подключение разрешено и сколько байт ушло в каждую сторону.

Если не работает

  • «Could not resolve host»: ни одна запись не разрешает это имя. Добавьте его в allow.
  • 403, где названа политика исходящего трафика: хост или его порт не разрешены, или сработала запись deny. Для SSH в записи нужен порт.
  • Сервис отвечает 401 с привязанным секретом: запрос ушел к хосту, которого нет в секрете, или клиент положил ключ в тело, где подстановки нет, или пинит свои сертификаты. Назовите хост в hosts секрета и отправляйте ключ в заголовке.
  • INVALID_ARGUMENT при создании или изменении: исходящий трафик песочницы не разрешает хосты привязанного секрета, или такого секрета нет. Разрешите их или сначала задайте секрет.
  • FAILED_PRECONDITION на DeleteSecret: секрет привязывает песочница. Отвяжите его через UpdateSandbox или удалите эту песочницу.
  • RESOURCE_EXHAUSTED с LimitReached, secrets: в рабочем пространстве уже 100 секретов. Удалите тот, который больше не привязан.

Вопросы

Может ли процесс в песочнице прочитать мой API-ключ?

Нет. Привязанная переменная содержит заглушку; ключ в запросы к хостам секрета подставляет прокси исходящего трафика вне ВМ.

Какие запросы получают настоящий ключ?

HTTPS-запросы к хостам, названным в секрете, — в заголовках. Все остальные хосты получают заглушку.

Как закрыть песочнице доступ в интернет?

Отправьте egress с пустым allow: наружу ничего не выходит, и DNS ничего не резолвит. Добавьте только то, что нужно для работы.

Есть ли у песочницы UDP?

Нет. Из песочницы выходят только TCP и DNS, так что QUIC, HTTP/3 и ping не работают, что бы ни говорил список.

Действуют ли изменения исходящего трафика на работающую песочницу?

Да, сразу: подключения, которые новый список больше не разрешает, закрываются.

Попробуйте Pethost Agent Sandboxes

Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.

Начать пробный период