security-bun

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Security audit patterns for Bun runtime applications covering shell injection, SQL injection, server security, and Bun-specific vulnerabilities.

</overview> <rules>

针对Bun运行时应用的安全审计模式，涵盖Shell注入、SQL注入、服务器安全以及Bun特有的漏洞。

</overview> <rules>

The #1 Bun Footgun: Shell Escaping vs Raw Shell

Bun头号陷阱：Shell转义 vs 原生Shell

Bun's shell

is a tagged template that escapes by default. If you bypass escaping (via raw mode), user input can become command injection.

typescript

import { $ } from "bun";

const userInput = "hello; rm -rf /";

// ✓ SAFE: Tagged template - automatically escapes
await $`echo ${userInput}`;
// Executes: echo 'hello; rm -rf /'

// ❌ CRITICAL: Spawning a new shell (bypasses Bun escaping)
await $`bash -c "echo ${userInput}"`;
// The nested shell interprets user input as code

Bun的Shell

是默认会转义的标签模板。如果绕过转义（通过原生模式），用户输入可能会导致命令注入。

typescript

import { $ } from "bun";

const userInput = "hello; rm -rf /";

// ✓ 安全：Tagged template - 自动转义
await $`echo ${userInput}`;
// 执行：echo 'hello; rm -rf /'

// ❌ 严重：生成新Shell（绕过Bun转义）
await $`bash -c "echo ${userInput}"`;
// 嵌套Shell会将用户输入解析为代码

Argument Injection (Even with Escaping)

参数注入（即使使用转义）

Even the safe tagged template is vulnerable to argument injection:

typescript

import { $ } from "bun";

// ❌ HIGH: Argument injection via -- prefix
const userRepo = "--upload-pack=id>/tmp/pwned";
await $`git ls-remote ${userRepo} main`;
// The -- prefix makes it a command-line argument, not a value

// ✓ Validate input format before use
const userRepo = getUserInput();
if (!userRepo.match(/^https?:\/\//)) {
  throw new Error("Invalid repository URL");
}
await $`git ls-remote ${userRepo} main`;

// ✓ Or use -- to end argument parsing
await $`git ls-remote -- ${userRepo} main`;

即使是安全的标签模板也可能存在参数注入漏洞：

typescript

import { $ } from "bun";

// ❌ 高危：通过--前缀进行参数注入
const userRepo = "--upload-pack=id>/tmp/pwned";
await $`git ls-remote ${userRepo} main`;
// --前缀会将其视为命令行参数，而非值

// ✓ 使用前验证输入格式
const userRepo = getUserInput();
if (!userRepo.match(/^https?:\/\//)) {
  throw new Error("无效的仓库URL");
}
await $`git ls-remote ${userRepo} main`;

// ✓ 或者使用--结束参数解析
await $`git ls-remote -- ${userRepo} main`;

bun:sqlite SQL Injection

bun:sqlite SQL注入

sql

is a tagged template that parameterizes values. If you build SQL strings manually, you can still be vulnerable.

typescript

import { sql } from "bun";

const userId = "1 OR 1=1";

// ❌ CRITICAL: Function call - SQL injection!
await sql(`SELECT * FROM users WHERE id = ${userId}`);
// Executes: SELECT * FROM users WHERE id = 1 OR 1=1

// ✓ SAFE: Tagged template - parameterized query
await sql`SELECT * FROM users WHERE id = ${userId}`;
// Executes: SELECT * FROM users WHERE id = $1 with params ['1 OR 1=1']

sql

是会参数化值的标签模板。如果手动构建SQL字符串，仍然可能存在漏洞。

typescript

import { sql } from "bun";

const userId = "1 OR 1=1";

// ❌ 严重：函数调用 - SQL注入！
await sql(`SELECT * FROM users WHERE id = ${userId}`);
// 执行：SELECT * FROM users WHERE id = 1 OR 1=1

// ✓ 安全：Tagged template - 参数化查询
await sql`SELECT * FROM users WHERE id = ${userId}`;
// 执行：SELECT * FROM users WHERE id = $1，参数为 ['1 OR 1=1']

bun:sqlite Database Class

bun:sqlite Database类

typescript

import { Database } from "bun:sqlite";

const db = new Database("mydb.sqlite");
const userInput = "'; DROP TABLE users; --";

// ❌ CRITICAL: String interpolation
db.run(`INSERT INTO logs VALUES ('${userInput}')`);

// ✓ SAFE: Parameterized with .run()
db.run("INSERT INTO logs VALUES (?)", [userInput]);

// ✓ SAFE: Prepared statements
const stmt = db.prepare("SELECT * FROM users WHERE id = ?");
stmt.get(userInput);

// ✓ SAFE: Query with parameters
db.query("SELECT * FROM users WHERE email = ?").get(userInput);

</rules> <vulnerabilities>

typescript

import { Database } from "bun:sqlite";

const db = new Database("mydb.sqlite");
const userInput = "'; DROP TABLE users; --";

// ❌ 严重：字符串插值
db.run(`INSERT INTO logs VALUES ('${userInput}')`);

// ✓ 安全：使用.run()进行参数化
db.run("INSERT INTO logs VALUES (?)", [userInput]);

// ✓ 安全：预编译语句
const stmt = db.prepare("SELECT * FROM users WHERE id = ?");
stmt.get(userInput);

// ✓ 安全：带参数的查询
db.query("SELECT * FROM users WHERE email = ?").get(userInput);

</rules> <vulnerabilities>

Bun.serve() Security

Bun.serve()安全

Missing Request Validation

缺少请求验证

typescript

// ❌ No input validation
Bun.serve({
  fetch(req) {
    const url = new URL(req.url);
    const file = url.searchParams.get("file");
    return new Response(Bun.file(`./uploads/${file}`)); // Path traversal!
  },
});

// ✓ Validate and sanitize
import { join, basename, resolve } from "path";

Bun.serve({
  fetch(req) {
    const url = new URL(req.url);
    const file = url.searchParams.get("file");
    
    // Sanitize filename
    const safeName = basename(file ?? "");
    const uploadsDir = resolve("./uploads");
    const filePath = resolve(join(uploadsDir, safeName));
    
    // Verify path is within uploads directory
    if (!filePath.startsWith(uploadsDir)) {
      return new Response("Forbidden", { status: 403 });
    }
    
    return new Response(Bun.file(filePath));
  },
});

typescript

// ❌ 无输入验证
Bun.serve({
  fetch(req) {
    const url = new URL(req.url);
    const file = url.searchParams.get("file");
    return new Response(Bun.file(`./uploads/${file}`)); // 路径遍历！
  },
});

// ✓ 验证并清理
import { join, basename, resolve } from "path";

Bun.serve({
  fetch(req) {
    const url = new URL(req.url);
    const file = url.searchParams.get("file");
    
    // 清理文件名
    const safeName = basename(file ?? "");
    const uploadsDir = resolve("./uploads");
    const filePath = resolve(join(uploadsDir, safeName));
    
    // 验证路径是否在uploads目录内
    if (!filePath.startsWith(uploadsDir)) {
      return new Response("禁止访问", { status: 403 });
    }
    
    return new Response(Bun.file(filePath));
  },
});

Request Size Limits (DoS Protection)

请求大小限制（DoS防护）

typescript

// ❌ No body size limit (large uploads can exhaust memory)
Bun.serve({
  fetch(req) {
    return new Response("ok");
  },
});

// ✓ Set a max request body size
Bun.serve({
  maxRequestBodySize: 1_000_000, // 1 MB
  fetch(req) {
    return new Response("ok");
  },
});

typescript

// ❌ 无请求体大小限制（大上传会耗尽内存）
Bun.serve({
  fetch(req) {
    return new Response("ok");
  },
});

// ✓ 设置最大请求体大小
Bun.serve({
  maxRequestBodySize: 1_000_000, // 1 MB
  fetch(req) {
    return new Response("ok");
  },
});

CORS Configuration

CORS配置

typescript

// ❌ Wide open CORS
Bun.serve({
  fetch(req) {
    return new Response("data", {
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Credentials": "true", // Dangerous combo!
      },
    });
  },
});

// ✓ Explicit origin allowlist
const ALLOWED_ORIGINS = ["https://app.example.com"];

Bun.serve({
  fetch(req) {
    const origin = req.headers.get("Origin");
    const corsHeaders: Record<string, string> = {};
    
    if (origin && ALLOWED_ORIGINS.includes(origin)) {
      corsHeaders["Access-Control-Allow-Origin"] = origin;
      corsHeaders["Access-Control-Allow-Credentials"] = "true";
    }
    
    return new Response("data", { headers: corsHeaders });
  },
});

typescript

// ❌ 完全开放的CORS
Bun.serve({
  fetch(req) {
    return new Response("data", {
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Credentials": "true", // 危险组合！
      },
    });
  },
});

// ✓ 明确的源白名单
const ALLOWED_ORIGINS = ["https://app.example.com"];

Bun.serve({
  fetch(req) {
    const origin = req.headers.get("Origin");
    const corsHeaders: Record<string, string> = {};
    
    if (origin && ALLOWED_ORIGINS.includes(origin)) {
      corsHeaders["Access-Control-Allow-Origin"] = origin;
      corsHeaders["Access-Control-Allow-Credentials"] = "true";
    }
    
    return new Response("data", { headers: corsHeaders });
  },
});

Host Binding

主机绑定

typescript

// ❌ Exposed to network (sometimes unintentional)
Bun.serve({
  hostname: "0.0.0.0", // Accessible from any network interface
  port: 3000,
  fetch(req) { /* ... */ },
});

// ✓ Localhost only for development
Bun.serve({
  hostname: "127.0.0.1", // Only local access
  port: 3000,
  fetch(req) { /* ... */ },
});

typescript

// ❌ 暴露到网络（有时是无意的）
Bun.serve({
  hostname: "0.0.0.0", // 可从任何网络接口访问
  port: 3000,
  fetch(req) { /* ... */ },
});

// ✓ 开发环境仅本地访问
Bun.serve({
  hostname: "127.0.0.1", // 仅本地可访问
  port: 3000,
  fetch(req) { /* ... */ },
});

Bun.spawn() Command Injection

Bun.spawn()命令注入

typescript

// ❌ CRITICAL: User input in command array (can still be dangerous)
const filename = userInput; // Could be "--version" or other flags
Bun.spawn(["convert", filename, "output.png"]);

// ❌ CRITICAL: Shell execution with user input
Bun.spawn(["sh", "-c", `convert ${userInput} output.png`]);

// ✓ Validate input first
const filename = userInput;
if (!filename.match(/^[a-zA-Z0-9_-]+\.(jpg|png|gif)$/)) {
  throw new Error("Invalid filename");
}
Bun.spawn(["convert", filename, "output.png"]);

// ✓ Use -- to prevent flag injection
Bun.spawn(["convert", "--", filename, "output.png"]);

typescript

// ❌ 严重：命令数组中包含用户输入（仍可能危险）
const filename = userInput; // 可能是"--version"或其他标志
Bun.spawn(["convert", filename, "output.png"]);

// ❌ 严重：带用户输入的Shell执行
Bun.spawn(["sh", "-c", `convert ${userInput} output.png`]);

// ✓ 先验证输入
const filename = userInput;
if (!filename.match(/^[a-zA-Z0-9_-]+\.(jpg|png|gif)$/)) {
  throw new Error("无效文件名");
}
Bun.spawn(["convert", filename, "output.png"]);

// ✓ 使用--防止标志注入
Bun.spawn(["convert", "--", filename, "output.png"]);

Bun.file() and Bun.write() Path Traversal

Bun.file()和Bun.write()路径遍历

typescript

// ❌ HIGH: Path traversal
const userFile = req.query.file; // "../../etc/passwd"
const content = await Bun.file(`./uploads/${userFile}`).text();

// ❌ HIGH: Writing to arbitrary paths
await Bun.write(`./data/${userFile}`, content);

// ✓ Sanitize paths
import { join, basename, resolve } from "path";

const UPLOADS_DIR = resolve("./uploads");

function getSafePath(userInput: string): string {
  const safeName = basename(userInput);
  const fullPath = resolve(join(UPLOADS_DIR, safeName));
  
  if (!fullPath.startsWith(UPLOADS_DIR)) {
    throw new Error("Invalid path");
  }
  
  return fullPath;
}

const content = await Bun.file(getSafePath(userFile)).text();

typescript

// ❌ 高危：路径遍历
const userFile = req.query.file; // "../../etc/passwd"
const content = await Bun.file(`./uploads/${userFile}`).text();

// ❌ 高危：写入任意路径
await Bun.write(`./data/${userFile}`, content);

// ✓ 清理路径
import { join, basename, resolve } from "path";

const UPLOADS_DIR = resolve("./uploads");

function getSafePath(userInput: string): string {
  const safeName = basename(userInput);
  const fullPath = resolve(join(UPLOADS_DIR, safeName));
  
  if (!fullPath.startsWith(UPLOADS_DIR)) {
    throw new Error("无效路径");
  }
  
  return fullPath;
}

const content = await Bun.file(getSafePath(userFile)).text();

Bun.password (Secure, but check usage)

Bun.password（安全，但需检查使用方式）

typescript

// ✓ Bun.password.hash is secure by default (uses argon2)
const hash = await Bun.password.hash(password);

// ✓ Verify passwords
const isValid = await Bun.password.verify(password, hash);

// ⚠️ But check: is it actually being used?
// Common vibecoding mistake: storing plaintext anyway

// ❌ Storing plaintext
db.run("INSERT INTO users (password) VALUES (?)", [password]);

// ✓ Storing hash
const hash = await Bun.password.hash(password);
db.run("INSERT INTO users (password_hash) VALUES (?)", [hash]);

typescript

// ✓ Bun.password.hash默认是安全的（使用argon2）
const hash = await Bun.password.hash(password);

// ✓ 验证密码
const isValid = await Bun.password.verify(password, hash);

// ⚠️ 但需检查：是否真的正确使用？
// 常见的编码错误：仍然存储明文

// ❌ 存储明文
db.run("INSERT INTO users (password) VALUES (?)", [password]);

// ✓ 存储哈希值
const hash = await Bun.password.hash(password);
db.run("INSERT INTO users (password_hash) VALUES (?)", [hash]);

Environment Variables

环境变量

typescript

// Bun.env is the same as process.env

// ❌ Secrets in client-facing code
// If using Bun with a bundler, check what gets bundled

// ✓ Server-only access
const apiKey = Bun.env.API_KEY;
if (!apiKey) {
  throw new Error("API_KEY not configured");
}

// Check bunfig.toml for any exposed variables

typescript

// Bun.env与process.env相同

// ❌ 客户端代码中包含密钥
// 如果使用Bun进行打包，检查哪些内容会被打包

// ✓ 仅服务器端访问
const apiKey = Bun.env.API_KEY;
if (!apiKey) {
  throw new Error("未配置API_KEY");
}

// 检查bunfig.toml中的暴露变量

bunfig.toml Security

bunfig.toml安全

toml

undefined

toml

undefined

Check for suspicious configurations

检查可疑配置

[install]

❌ Disabling lockfile = supply chain risk

❌ 禁用锁文件 = 供应链风险

save-lockfile = false

❌ Allowing arbitrary registries

❌ 允许任意注册表

registry = "http://malicious-registry.com"

[run]

registry = "http://malicious-registry.com"

[run]

❌ Disabling sandbox (if applicable)

❌ 禁用沙箱（如果适用）

undefined

undefined

WebSocket Security

WebSocket安全

typescript

Bun.serve({
  fetch(req, server) {
    if (req.headers.get("upgrade") === "websocket") {
      // ❌ No auth check before upgrade
      server.upgrade(req);
      return;
    }
  },
  websocket: {
    message(ws, message) {
      // ❌ Broadcasting without auth
      ws.publish("chat", message);
    },
  },
});

// ✓ Authenticate before upgrade
Bun.serve({
  fetch(req, server) {
    if (req.headers.get("upgrade") === "websocket") {
      const token = req.headers.get("Authorization");
      const user = await verifyToken(token);
      
      if (!user) {
        return new Response("Unauthorized", { status: 401 });
      }
      
      server.upgrade(req, { data: { user } });
      return;
    }
  },
  websocket: {
    message(ws, message) {
      // Access authenticated user
      const user = ws.data.user;
      // Now safe to process message
    },
  },
});

</vulnerabilities>

<severity_table>

typescript

Bun.serve({
  fetch(req, server) {
    if (req.headers.get("upgrade") === "websocket") {
      // ❌ 升级前无身份验证检查
      server.upgrade(req);
      return;
    }
  },
  websocket: {
    message(ws, message) {
      // ❌ 无身份验证的广播
      ws.publish("chat", message);
    },
  },
});

// ✓ 升级前进行身份验证
Bun.serve({
  fetch(req, server) {
    if (req.headers.get("upgrade") === "websocket") {
      const token = req.headers.get("Authorization");
      const user = await verifyToken(token);
      
      if (!user) {
        return new Response("未授权", { status: 401 });
      }
      
      server.upgrade(req, { data: { user } });
      return;
    }
  },
  websocket: {
    message(ws, message) {
      // 访问已认证用户
      const user = ws.data.user;
      // 现在可以安全处理消息
    },
  },
});

</vulnerabilities>

<severity_table>

Common Vulnerabilities Summary

常见漏洞汇总

Issue	Pattern to Find	Severity
Shell injection (function call)	`$(` ... `)` or `$("...")`	CRITICAL
SQL injection (function call)	`sql(` ... `)`	CRITICAL
SQL string interpolation	`...${var}...` in SQL	CRITICAL
Argument injection	User input starting with `-`	HIGH
Path traversal	`Bun.file(userInput)`	HIGH
Command injection	`Bun.spawn` with user input	HIGH
Open CORS	`Access-Control-Allow-Origin: *`	MEDIUM
Network exposure	`hostname: "0.0.0.0"`	MEDIUM
Missing WebSocket auth	`server.upgrade` without auth check	HIGH

</severity_table>

问题	查找模式	严重程度
Shell注入（函数调用）	`$(` ... `)` 或 `$("...")`	严重
SQL注入（函数调用）	`sql(` ... `)`	严重
SQL字符串插值	SQL中的 `...${var}...`	严重
参数注入	以 `-` 开头的用户输入	高危
路径遍历	`Bun.file(userInput)`	高危
命令注入	带用户输入的 `Bun.spawn`	高危
开放CORS	`Access-Control-Allow-Origin: *`	中危
网络暴露	`hostname: "0.0.0.0"`	中危
缺少WebSocket认证	无认证检查的 `server.upgrade`	高危

</severity_table>

Quick Audit Commands

快速审计命令

bash

undefined

bash

undefined

Find dangerous shell usage (function call instead of tagged template)

查找危险的Shell使用（函数调用而非标签模板）

rg '$\s*(' . -g ".ts" -g ".js"

Find SQL function calls (should be tagged template)

查找SQL函数调用（应为标签模板）

rg 'sql\s*(' . -g ".ts" -g ".js"

Find string interpolation in queries

查找查询中的字符串插值

rg '(query|run|exec)\s*(\s*`' . -g ".ts" -g ".js"

Find Bun.spawn usage

查找Bun.spawn的使用

rg 'Bun.spawn' . -g ".ts" -g ".js" -A 2

Find Bun.file with variables (potential path traversal)

查找带变量的Bun.file（潜在路径遍历）

rg 'Bun.file\s*([^"'''`]' . -g ".ts" -g ".js"

Find hostname binding

查找主机名绑定

rg 'hostname.0.0.0.0' . -g ".ts" -g "*.js"

Find CORS headers

查找CORS头

rg 'Access-Control-Allow-Origin' . -g ".ts" -g ".js"

Find WebSocket upgrades

查找WebSocket升级

rg 'server.upgrade' . -g ".ts" -g ".js" -B 5


</commands>

<checklist>

rg 'server.upgrade' . -g ".ts" -g ".js" -B 5


</commands>

<checklist>

Hardening Checklist

加固检查清单

All
```
$
```
shell usage is tagged template (no parentheses)
All
```
sql
```
usage is tagged template (no parentheses)
All bun:sqlite queries use parameterization
User input validated before shell/spawn commands
```
--
```
used to prevent argument injection where applicable
File paths sanitized with basename() and path validation
CORS restricted to specific origins
hostname is 127.0.0.1 for dev, explicit for prod
WebSocket connections authenticated before upgrade
Bun.password.hash used for passwords (not plaintext)
bunfig.toml reviewed for suspicious settings

</checklist>

所有
```
$
```
Shell使用均为标签模板（无括号）
所有
```
sql
```
使用均为标签模板（无括号）
所有bun:sqlite查询均使用参数化
Shell/spawn命令使用前验证用户输入
适用时使用--防止参数注入
使用basename()和路径验证清理文件路径
CORS限制为特定源
开发环境hostname为127.0.0.1，生产环境明确配置
WebSocket连接升级前进行身份验证
使用Bun.password.hash存储密码（而非明文）
审核bunfig.toml中的可疑设置

</checklist>