hush-toolbox

English · 中文

---

English

Multi-arch Docker toolbox image for the Hush platform. Includes Python 3.12, Node.js 20, ffmpeg (static), common dev tools, and Hush-only CA trust.

What's Inside

Layer	Contents
Runtime	Python 3.12, Node.js 20
System libs	git, libgl1, libglib2.0, libsndfile1, poppler-utils, libcairo2, libpango, libgdk-pixbuf, tesseract-ocr (+ Chinese)
Media	ffmpeg / ffprobe (static binaries, GPLv2+)
Python	requests, httpx, numpy, pandas, Pillow, openai, anthropic, psycopg2-binary, cryptography, pdfplumber, pymupdf, yt-dlp, and more (see requirements.txt)
Node	typescript (see package.json)
CA trust	Hush CA only — all HTTPS must go through the Hush proxy

Build

# 1. Fetch ffmpeg static binaries (one-time)
./scripts/fetch-ffmpeg.sh

# 2. Build for current platform
docker build -t hush-toolbox .

# Or: multi-arch build + push to registry
./scripts/build.sh --push

Prerequisites: Docker with buildx. For multi-arch builds, install QEMU:

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Usage

# Basic (no CA trust — HTTP only)
docker run --rm -it hush-toolbox

# Mount Hush CA cert at runtime (HTTPS through Hush proxy)
docker run --rm -it \
  -v /path/to/hush-ca.crt:/etc/hush/ca.crt:ro \
  -e HTTP_PROXY=http://hush:8080 \
  -e HTTPS_PROXY=http://hush:8080 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -v hush-pip-cache-$USER:/cache/pip \
  -v hush-npm-cache-$USER:/cache/npm \
  hush-toolbox

The entrypoint script detects the mounted CA cert, installs it into the system trust store, certifi, and sets all SSL_CERT_FILE / REQUESTS_CA_BUNDLE / NODE_EXTRA_CA_CERTS env vars automatically.

Runtime Security Options

docker run --rm -it \
  --cap-drop=ALL \
  --security-opt no-new-privileges \
  --read-only --tmpfs /tmp \
  --memory 4g --cpus 2 --pids-limit 256 \
  --network locked-net \
  --dns 10.0.0.53 \
  -v /path/to/hush-ca.crt:/etc/hush/ca.crt:ro \
  -e HTTP_PROXY=http://hush:8080 \
  -e HTTPS_PROXY=http://hush:8080 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -e OPENAI_API_KEY=__SENTINEL__ \
  hush-toolbox

CA Trust Model

The Hush CA cert is not baked into the image — it is mounted at docker run time.

On startup, the entrypoint script:

1. Copies the cert into the system trust store (update-ca-certificates)
2. Appends it to the Python certifi bundle
3. Exports SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS

All HTTPS traffic from the container then must go through the Hush proxy:

toolbox → [TLS: Hush CA cert] → Hush Proxy → [decrypt / audit] → upstream

Without the mounted cert, direct HTTPS to external services fails with CERTIFICATE_VERIFY_FAILED — by design.

Image Layers

L0  python:3.12-slim + Node.js 20
 └ L1  system libs + git (apt)
   └ L2  ffmpeg/ffprobe static binaries (per TARGETARCH)
     └ L3  Python & Node packages (most volatile, topmost cache layer)
       └ L4  entrypoint (CA trust setup at runtime)

ffmpeg License

ffmpeg / ffprobe are licensed under GPLv2+ (source: BtbN/FFmpeg-Builds). Full text at licenses/ffmpeg-GPLv3.txt inside the image.

This image invokes ffmpeg via CLI (subprocess); the wrapper code is Apache-2.0 and does not form a derivative work.

See THIRD_PARTY_LICENSES.md for all bundled licenses.

License

Repository code: Apache-2.0

---

中文

Hush 平台的多架构 Docker 工具箱镜像。包含 Python 3.12、Node.js 20、ffmpeg（静态编译）、常用开发工具，以及仅信任 Hush CA 的证书链。

包含什么

层	内容
运行时	Python 3.12、Node.js 20
系统库	git、libgl1、libglib2.0、libsndfile1、poppler-utils、libcairo2、libpango、tesseract-ocr（含中文语言包）
媒体	ffmpeg / ffprobe（静态二进制，GPLv2+）
Python	requests、httpx、numpy、pandas、Pillow、openai、anthropic、psycopg2-binary、cryptography、pdfplumber、pymupdf、yt-dlp 等（详见 requirements.txt）
Node	typescript（详见 package.json）
CA 信任	仅信任 Hush CA — 所有 HTTPS 流量必须经 Hush 代理

构建

# 1. 下载 ffmpeg 静态二进制（仅需一次）
./scripts/fetch-ffmpeg.sh

# 2. 构建当前平台镜像
docker build -t hush-toolbox .

# 或：多架构构建 + 推送到 registry
./scripts/build.sh --push

前置条件： Docker 需开启 buildx。多架构构建需安装 QEMU：

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

使用

# 基本用法（无 CA 信任，仅 HTTP）
docker run --rm -it hush-toolbox

# 运行时挂载 Hush CA 证书（走 Hush 代理的 HTTPS）
docker run --rm -it \
  -v /你的/hush-ca.crt:/etc/hush/ca.crt:ro \
  -e HTTP_PROXY=http://hush:8080 \
  -e HTTPS_PROXY=http://hush:8080 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -v hush-pip-cache-$USER:/cache/pip \
  -v hush-npm-cache-$USER:/cache/npm \
  hush-toolbox

entrypoint 脚本会自动检测挂载的 CA 证书，将其安装到系统信任链、certifi bundle，并自动设置 SSL_CERT_FILE / REQUESTS_CA_BUNDLE / NODE_EXTRA_CA_CERTS 等环境变量。

运行时安全选项

docker run --rm -it \
  --cap-drop=ALL \
  --security-opt no-new-privileges \
  --read-only --tmpfs /tmp \
  --memory 4g --cpus 2 --pids-limit 256 \
  --network locked-net \
  --dns 10.0.0.53 \
  -v /你的/hush-ca.crt:/etc/hush/ca.crt:ro \
  -e HTTP_PROXY=http://hush:8080 \
  -e HTTPS_PROXY=http://hush:8080 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -e OPENAI_API_KEY=__SENTINEL__ \
  hush-toolbox

CA 信任模型

Hush CA 证书不打包进镜像 — 在 docker run 时挂载。

容器启动时，entrypoint 脚本会：

1. 将证书复制到系统信任链（update-ca-certificates）
2. 追加到 Python certifi bundle
3. 导出 SSL_CERT_FILE、REQUESTS_CA_BUNDLE、CURL_CA_BUNDLE、NODE_EXTRA_CA_CERTS

之后容器内所有 HTTPS 流量必须经 Hush 代理转发：

toolbox → [TLS: Hush CA 证书] → Hush 代理 → [解密 / 审计] → 外部服务

未挂载证书时，直连外部 HTTPS 会报 CERTIFICATE_VERIFY_FAILED — 这是设计如此，不是 bug。

镜像分层

L0  python:3.12-slim + Node.js 20
 └ L1  系统库 + git（apt）
   └ L2  ffmpeg/ffprobe 静态二进制（按 TARGETARCH）
     └ L3  Python & Node 包（最常变，最顶层缓存）
       └ L4  entrypoint（运行时 CA 信任设置）

ffmpeg 许可

ffmpeg / ffprobe 使用 GPLv2+ 许可（来源：BtbN/FFmpeg-Builds）。 完整许可文本见镜像内 licenses/ffmpeg-GPLv3.txt。

本镜像通过 CLI（子进程）调用 ffmpeg，wrapper 代码为 Apache-2.0 许可，不构成衍生作品。

所有打包组件许可详见 THIRD_PARTY_LICENSES.md。

许可

仓库自有代码：Apache-2.0