贡多林

具有完全可编程网络堆栈和文件系统的本地Linux微VM.

Gondolin在您的 Mac 或 Linux 机上运行轻量级微VMs( QEMU by 默认, 可选 krun 后端). 网络堆栈和虚拟文件系统是 在 TypeScript 中执行,使您能够完全控制什么 沙盒可以访问 和它可以使用的秘密.

所需资源

您需要安装 QEMU 来运行微VM( 默认后端) :

可选的实验后端 :

• libkrun + 键 host/krun-runner (单位:千美元)sandbox.vmm = "krun"(中文(简体) )
• make krun-runner 从地上恢复根相依赖并构建跑道
  • 在MacOS上,它也给跑者签上 com.apple.security.hypervisor
  • Gondolin自动探测这个本地跑者 --vmm krun
• @earendil-works/gondolin 为所支持的目标出版针对特定平台的可选跑道套件(darwin-arm64, (中文(简体) ), linux-x64(中文(简体) )
• krun 启动资产通过图像清单提供(assets.krunKernel 编号 : assets.krunInitrd(单位:千美元) gondolin build 并发布图像
• gondolin bash --vmm krun 选择每个命令的后端
• GONDOLIN_VMM=krun 仍然是全球默认值
• 后端等同矩阵 : 文件/后端

Linux 的先决条件 make krun-runner (乌班图/德比安):

sudo apt install \
  build-essential curl git make pkg-config clang lld xz-utils \
  libclang-dev llvm-dev libcap-ng-dev

# libkrun needs current stable Rust (edition2024 crates)
curl https://sh.rustup.rs -sSf | sh -s -- -y --profile minimal
. "$HOME/.cargo/env"

# install Zig 0.17.0 for your Linux architecture

• 节点.js 22.19

说明: 运行时验证目前在ARM64(Apple Silicon,Linux arch64)上最强. Linux x86 64 目前正在测试烟雾 make krun-runner 在中央情报局.

安装

npm install @earendil-works/gondolin

快速启动( CLI)

npx @earendil-works/gondolin bash

您也可以从另一个终端中发现并重新附加运行 VMS :

# List running sessions
npx @earendil-works/gondolin list

# Attach a second shell to a running VM by UUID/prefix
npx @earendil-works/gondolin attach <session-id>

# Snapshot a running VM session (stops that session)
npx @earendil-works/gondolin snapshot <session-id>

# Resume from snapshot id/path
npx @earendil-works/gondolin bash --resume <snapshot-id-or-path>

来宾图像(~200MB)在首通运行时自动解析 builtin-image-registry.json 缓存于 ~/.cache/gondolin/images/。 。 。 . 如果没有提供明确的图像,贡多林将使用 GONDOLIN_DEFAULT_IMAGE (默认 : alpine-base:latest) (中文(简体) ).

哈罗世界

import { VM, createHttpHooks, MemoryProvider } from "@earendil-works/gondolin";

const { httpHooks, env } = createHttpHooks({
  allowedHosts: ["api.github.com"],
  secrets: {
    GITHUB_TOKEN: {
      hosts: ["api.github.com"],
      value: process.env.GITHUB_TOKEN!,
    },
  },
});

const vm = await VM.create({
  httpHooks,
  env,
  vfs: {
    mounts: { "/workspace": new MemoryProvider() },
  },
});

// NOTE:
// - `vm.exec("...")` runs via `/bin/sh -lc "..."` (shell features work)
// - `vm.exec([cmd, ...argv])` executes `cmd` directly and does not search `$PATH`
//   so `cmd` must be an absolute path
const cmd = `
  curl -sS -f \
    -H "Accept: application/vnd.github+json" \
    -H "Authorization: Bearer $GITHUB_TOKEN" \
    https://api.github.com/user
`;

// You can pass a string to `vm.exec(...)` as shorthand for `/bin/sh -lc "..."`.
const result = await vm.exec(cmd);

console.log("exitCode:", result.exitCode);
console.log("stdout:\n", result.stdout);
console.log("stderr:\n", result.stderr);

await vm.close();

客人从不看真正的秘密价值 它只得到占位符. 默认( E)secretPlaceholderMode: "shared"那些占位符看起来像 <random-marker>.<normalized_secret_name>,所有产生的秘密共享 一个随机标记. secretPlaceholderMode: "unique" 而不是每个秘密 完全随机的占位符 GONDOLIN_SECRET_<random>。 。 。 . 位置符由主机在输出的 HTTP 信头中替换, 包括 Authorization: Basic … (基数64的符号在 username:password 现予替换).

默认情况下, URL 查询参数中的占位符不会被替换 。 你们可以 选择使用 replaceSecretsInQuery: true,但这会增加反射 风险,只应在必要时使用.

说明: 避免挂起一个 MemoryProvider 时间 / 除非您还提供了 系统 CA 捆绑。 贡多林在 /etc/gondolin/mitm/ca.crt, (中文(简体) ), 但是,如果你的根挂载隐藏 Distro CA 文件,那么公开的 TLS 校验可以 仍然失败(例如:. curl: (60)) (中文(简体) ).

外出 SSH 主机授权列表

SSH egress 可以使用一个明确的主机授权列表:

const vm = await VM.create({
  dns: {
    mode: "synthetic",
    syntheticHostMapping: "per-host",
  },
  ssh: {
    allowedHosts: ["github.com"],

    // Upstream host key verification
    //
    // If `hostVerifier` is not provided, gondolin verifies upstream host keys using
    // OpenSSH known_hosts (by default: ~/.ssh/known_hosts and /etc/ssh/ssh_known_hosts).
    // You can override this with `knownHostsFile`.
    // knownHostsFile: "/path/to/known_hosts",

    // Option A: use an ssh-agent (recommended for encrypted keys)
    agent: process.env.SSH_AUTH_SOCK,

    // Option B: provide a raw private key
    credentials: {
      "github.com": {
        username: "git",
        privateKey: process.env.GITHUB_DEPLOY_KEY!,
      },
    },
  },
});

syntheticHostMapping: "per-host" 需要这样,主机就可以向外映射 端口上的 TCP 连接 22 返回预定主机名.

当证书或 SSH 代理配置时, 主机终止 SSH 的来宾 届会和代理 exec 请求(包括 Git smart- protocol 命令) 到 真实的上游主机使用主机侧认证 。 私钥从不 可见于来宾.

如果未为主机配置匹配证书, 则无 ssh.agent 设定了 SSH流量被屏蔽(直接通过不支持).

由于这是SSH终止,客人看到主机提供的SSH主机密钥; 配置来宾 known_hosts (或按需要禁止严格检查).

上游 SSH 主机密钥对照 OpenSSH 进行校验 known_hosts 默认. 如果缺少上游主机(或密钥更改),则代理的 SSH 请求 将失败.

许可证和链接

• 文档
• 问题跟踪器
• 许可证 : 阿帕奇 - 2.0