Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

Secrets et trafic sortant : des clés qu’une sandbox ne détient jamais

Mis à jour le · 8 min de lecture

Une sandbox exécute du code auquel vous ne faites pas forcément confiance : celui d’un agent, d’un utilisateur, d’un paquet. Deux paramètres la tiennent dans ses limites. Un secret est une clé que la sandbox ne détient jamais : elle voit un marqueur, et le proxy de sortie met la vraie clé sur le réseau, seulement vers les hôtes que vous nommez. Le trafic sortant, c’est la liste des destinations où elle peut se connecter tout court.

En bref
  • SetSecret garde une valeur dans l’espace de travail avec ses hôtes ; une variable qui y est liée (EnvVar.secret) contient un marqueur, phs_….
  • La substitution : dans les en-têtes des requêtes HTTPS vers les seuls hôtes du secret, Authorization comme x-api-key. Une nouvelle valeur marche aussitôt.
  • egress.allow et deny : domaines, sous-domaines, IP et CIDR, avec un port quand ce n’est ni 80 ni 443 ; deny l’emporte ; par défaut, partout.
  • Seuls TCP et DNS sortent, et le DNS de la sandbox ne répond qu’aux noms que la liste autorise.

Step 1: Enregistrez un secret avec ses hôtes

Un secret a un nom (a-z, 0-9 et « - »), une valeur et les hôtes vers lesquels la valeur peut être envoyée. Définissez-le depuis votre propre environnement, jamais depuis un prompt ou un fichier de la sandbox. Le redéfinir remplace sa valeur et ses hôtes ensemble.

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: Créez une sandbox qui le lie, derrière une liste d’autorisation

Liez une variable au secret dans l’environment de la sandbox, et listez dans egress.allow où elle peut se connecter : ici l’index des paquets Python et l’hôte du secret. Le trafic sortant doit autoriser les hôtes du secret.

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: Voyez ce que voit la sandbox

À l’intérieur, la variable contient le marqueur, une requête vers l’hôte du secret porte la clé, et un nom que la liste n’autorise pas ne se résout même pas.

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);

L’exécution ci-dessus avait enregistré une clé inventée, à laquelle OpenAI a répondu 401 ; votre vraie clé reçoit 200. Dans les deux cas, la requête a quitté la sandbox avec la valeur enregistrée à la place du marqueur.

Step 4: Changez la liste pendant qu’elle tourne

UpdateSandbox avec un groupe egress remplace toute la liste d’un coup, et ferme les connexions qu’elle n’autorise plus. Une nouvelle valeur de secret n’a besoin de rien : rappelez SetSecret, et chaque sandbox qui le lie envoie la nouvelle dès sa prochaine requête.

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"]}}}

Comment marche un secret

La valeur d’un secret vit dans la console, scellée, et dans la mémoire des serveurs qui font tourner des sandboxes qui le lient : jamais sur le disque d’une sandbox, jamais dans sa mémoire, jamais dans une réponse de l’API. Une variable qui y est liée contient un marqueur qui commence par phs_, le même pour chaque processus de la sandbox.

Le proxy de sortie de la sandbox termine le TLS pour les seuls hôtes du secret, avec un certificat de l’autorité propre au serveur, à laquelle la sandbox fait confiance : Node, Python, curl et git sont configurés pour elle. Dans chaque requête vers ces hôtes, il remplace le marqueur par la valeur partout où il apparaît dans la valeur d’un en-tête : Authorization: Bearer, x-api-key, dans les identifiants de Authorization: Basic. Une requête vers tout autre hôte porte le marqueur, qui n’y vaut rien. La substitution se fait dans les en-têtes seulement, pas dans le corps d’une requête.

  • Les hôtes s’écrivent comme les domaines du trafic sortant : api.openai.com, ou *.example.com pour ses sous-domaines, avec un port quand ce n’est pas 443.
  • Une nouvelle valeur marche aussitôt, dans chaque sandbox active et chaque copie qui lie le secret.
  • Un secret lié ne peut pas être supprimé : DeleteSecret est refusé tant qu’une sandbox non supprimée le lie.
  • Un espace de travail contient 100 secrets. GetWorkspace liste leurs noms et leurs hôtes, jamais leurs valeurs.

Les événements de trafic sortant disent, pour chaque hôte et chaque minute, quels secrets ont été substitués dans ses requêtes : observabilité.

Comment marche le trafic sortant

L’egress d’une sandbox a deux listes. allow dit où elle peut se connecter, deny où elle ne le peut pas, et deny l’emporte. Par défaut, allow vaut ["*"], partout. Un groupe envoyé remplace tout le groupe : deny envoyé seul laisse allow vide ; pour bloquer quelques hôtes, envoyez donc allow ["*"] avec eux. À elles deux, elles contiennent 100 entrées de 255 octets au plus.

EntréeOuvre
*Partout.
pypi.orgCe domaine, sur les ports 80 et 443.
*.github.comSes sous-domaines à toute profondeur, mais pas github.com lui-même.
github.com:22Ce domaine sur ce port : git sur SSH.
203.0.113.7, 203.0.113.0/24Ces adresses, jointes par adresse, avec :port quand ce n’est ni 80 ni 443.
  • Seuls TCP et DNS sortent d’une sandbox : pas d’UDP, donc ni QUIC ni HTTP/3, et pas de ping, quoi que dise la liste.
  • Le DNS ne répond qu’aux noms autorisés. Le résolveur de la sandbox répond REFUSED pour un nom qu’aucune entrée de domaine n’autorise, sans rien demander à personne : aucune donnée ne sort donc par les questions DNS.
  • Le TLS est jugé sur le nom qu’envoie le client, et le proxy se connecte à l’adresse qu’il a résolue lui-même, jamais à celle qu’a choisie la sandbox. Une entrée de domaine fait confiance à tout ce que servent les adresses de ce nom, y compris les autres sites d’un CDN : une barrière qui doit tenir là nomme des IP, ou lie un secret à l’hôte, dont le proxy lit alors les requêtes une à une.
  • Le HTTP en clair est jugé requête par requête : une requête vers un autre hôte que celui de sa connexion reçoit 421, et la nouvelle connexion du client est jugée sur cet hôte.
  • SSH et les autres protocoles ne nomment pas d’hôte, et ne passent que vers une entrée de domaine qui nomme le port, comme github.com:22.
  • Toujours refusés : les adresses privées, link-local et CGNAT, le serveur lui-même, le port 25, et HTTP/2 sans TLS.
  • Un refus auquel le proxy peut répondre est un 403 qui dit ce qui l’a refusé.

Chaque sandbox a aussi ses propres limites : 200 nouvelles connexions par seconde après une rafale de 1 000, 1 024 ouvertes en même temps, et 200 questions DNS par seconde.

Des listes qui marchent

Pourallow
pip et uvpypi.org, files.pythonhosted.org
npmregistry.npmjs.org
git sur HTTPS et SSHgithub.com, *.githubusercontent.com, github.com:22
Claude Codeapi.anthropic.com
Codexapi.openai.com

Regardez les événements de trafic sortant d’une sandbox pendant une minute de vrai travail pour trouver ce dont elle a encore besoin : chacun dit l’hôte, s’il a été autorisé et combien d’octets sont passés dans chaque sens.

Quand ça ne marche pas

  • « Could not resolve host » : aucune entrée n’autorise ce nom. Ajoutez-le à allow.
  • Un 403 qui nomme la politique de trafic sortant : l’hôte, ou son port, n’est pas autorisé, ou une entrée deny correspond. SSH a besoin du port dans son entrée.
  • Le service répond 401 avec un secret lié : la requête est allée vers un hôte que le secret ne nomme pas, ou le client a mis la clé dans le corps, où aucune substitution n’a lieu, ou il épingle ses propres certificats. Nommez l’hôte dans les hosts du secret, et envoyez la clé dans un en-tête.
  • INVALID_ARGUMENT à une création ou une mise à jour : les hôtes d’un secret lié ne sont pas autorisés par le trafic sortant de la sandbox, ou le secret n’existe pas. Autorisez-les, ou définissez d’abord le secret.
  • FAILED_PRECONDITION sur DeleteSecret : une sandbox le lie. Déliez-le avec UpdateSandbox, ou supprimez cette sandbox.
  • RESOURCE_EXHAUSTED avec LimitReached, secrets : l’espace de travail en a 100. Supprimez-en un que vous ne liez plus.

Questions

Un processus de la sandbox peut-il lire ma clé d’API ?

Non. Une variable liée contient un marqueur ; le proxy de sortie, hors de la VM, met la clé dans les requêtes vers les hôtes du secret.

Quelles requêtes reçoivent la vraie clé ?

Les requêtes HTTPS vers les hôtes que nomme le secret, dans leurs en-têtes. Tout autre hôte reçoit le marqueur.

Comment couper l’accès à Internet dans une sandbox ?

Envoyez egress avec un allow vide : rien ne sort, et le DNS ne résout rien. N’ajoutez que ce dont le travail a besoin.

Une sandbox a-t-elle de l’UDP ?

Non. Seuls TCP et DNS sortent d’une sandbox : QUIC, HTTP/3 et ping ne marchent donc pas, quoi que dise la liste.

Les changements de trafic sortant s’appliquent-ils à une sandbox active ?

Oui, aussitôt : les connexions que la nouvelle liste n’autorise plus sont fermées.

Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

Démarrer l’essai gratuit