Українська
Меню документації

Документація 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 $ на місяць, який включає стільки ж використання.

Почати пробний період