Jupyter Notebook 安全加固实战:口令认证配置

Jupyter Notebook 安全加固的本质,是把它当成一台「带 HTTP 接口的代码执行器」来对待,而不是一个文档工具。默认启动的 jupyter lab --ip=0.0.0.0 --no-browser 会把 8888 端口连同 token 一起交给整个网段,任何人打开浏览器就能新建 kernel、执行 os.system,等价于拿到服务器 shell。本文给出从基线排查、身份认证、反向代理、容器隔离到验证的完整配置链路,命令可直接复制执行。

适用场景

以下部署形态在数据团队里非常普遍,也是实际被入侵的高频入口:

  • 开发机上用 --ip=0.0.0.0 --NotebookApp.token='' 启动,图方便让同事直接访问,之后一直没改;
  • Notebook 跑在云服务器上,安全组放通 8888 便于远程办公,token 通过微信或文档传给多人,从未轮换;
  • 容器里挂载了宿主机的 /var/run/docker.sock,方便在 Notebook 里构建镜像,等于把 root 权限交出去;
  • 训练脚本需要在 GPU 机器上跑,多人共用一个实例,彼此能看到对方的进程、环境变量与数据目录;
  • 安全扫描报告里出现「Jupyter 未授权访问」,但团队认为「内网的东西不用管」。

前置条件

  • JupyterLab 或 Notebook 7 以上(基于 jupyter_server),配置文件名统一为 jupyter_server_config.py;
  • 具备服务运行用户的权限,能修改 ~/.jupyter/ 下的配置并重启进程;
  • 已安装 nginx 与 apache2-utils(提供 htpasswd),用于反代与额外一层口令;
  • 有 HTTPS 证书,否则反代层口令仍是明文传输;
  • 维护窗口内操作。切换认证方式会导致已打开的页面掉线,kernel 中的变量需要重新执行。

原理说明

Jupyter Server 的 API 设计决定了它的风险等级:POST /api/kernels 创建 kernel、POST /api/kernels/{id}/channels 建立 WebSocket 通道、然后通过该通道下发代码并回收输出。这条链路上没有任何「沙箱」概念,代码以启动 Jupyter 的进程身份执行,能读环境变量、能访问挂载目录、能发起内网请求。所以认证不是可选项,而是这个服务的唯一门锁。

门锁有两把:token 与 password。token 是启动时随机生成的长串,默认打印在控制台并写入访问 URL;password 是用户自定义口令,服务端以 argon2 哈希存储在配置里。两者只要留一个为空,且另一个也没配,服务就会进入「无认证」状态——这是最危险的组合,很多事故都源于 token='' 而忘记设 password。正确做法是设置 password 后再清空 token,让 URL 里不再带凭据(URL 会进浏览器历史、进反代 access log、进截图)。

第二层是来源校验。allow_origin 控制哪些站点可以跨域调用 API,配置为空时服务端只接受同源请求;一旦写成 *,任意网页都能通过浏览器向本机 8888 发起请求,形成典型的跨站请求伪造式代码执行。allow_remote_access 则决定是否接受 Host 头不指向本机的请求,放在反向代理后面时必须为 true,此时真正的防护由 allow_origin 和 HTTPS 承担。

第三层是运行时隔离。认证只能挡住「谁能进来」,挡不住「进来之后能做什么」。容器化运行、去掉多余 capability、限制内存与进程数、不挂 docker socket,才是把一次 Notebook 沦陷控制在单个工作目录内的关键。

操作步骤

第一步:基线排查,确认当前暴露面

# 1) 找出所有 jupyter 进程及其启动参数(重点看 --ip / --NotebookApp.token)
ps -eo pid,user,args | grep -E '[j]upyter-(lab|notebook|server)'

# 2) 监听地址:0.0.0.0 或 :: 表示对全网开放
ss -lntp | grep -E ':(8888|8889|9999)\b'

# 3) 未带凭据访问 API:返回 200 说明认证已经关闭
curl -s -o /dev/null -w 'api/status -> %{http_code}\n' http://127.0.0.1:8888/api/status

# 4) 尝试创建 kernel:能创建就是可直接 RCE
curl -s -X POST http://127.0.0.1:8888/api/kernels \
  -H 'Content-Type: application/json' -d '{"name":"python3"}' | head -c 300; echo

# 5) 检查容器是否挂载了 docker socket(等于交出宿主机 root)
docker ps --format '{{.Names}}' | while read n; do
  docker inspect -f '{{.Name}} {{range .Mounts}}{{.Source}} {{end}}' "$n" | grep -q docker.sock && echo "RISK: $n"
done

# 6) 检查是否以 root 运行
ps -eo user,args | grep '[j]upyter' | awk '$1=="root"{print "RISK: running as root"}'

第 3、4 步返回 200 或成功创建 kernel,必须立刻停止服务或在下游防火墙封端口,再按下面步骤改配置。不要指望「先加个 nginx 认证」就算了,本机 8888 仍是可达的。

第二步:设置口令并关闭 URL 中的 token

先生成配置文件,再用官方命令写入口令哈希。顺序很重要:必须先设 password,再清空 token,否则中间状态是无认证:

# 1) 生成配置文件(已存在会跳过,不会覆盖)
jupyter server --generate-config

# 2) 交互式设置口令,输出写入 c.ServerApp.password 的 argon2 哈希
jupyter server password
# 输入两次口令后,配置文件里会出现类似:
# c.ServerApp.password = 'argon2:$argon2id$v=19$m=10240,t=10,p=8$...'

# 3) 确认哈希已落盘(不要保存明文口令到任何脚本里)
grep -n '^c.ServerApp.password' ~/.jupyter/jupyter_server_config.py
# ~/.jupyter/jupyter_server_config.py

# 只监听回环地址,外部访问一律走 nginx 反代
c.ServerApp.ip = '127.0.0.1'
c.ServerApp.port = 8888

# 挂在子路径下,便于与其它服务共用 443
c.ServerApp.base_url = '/lab/'

# 关闭 URL token,改由口令认证(必须已设置 password,见上一步)
c.ServerApp.token = ''

# 反代场景下 Host 头为外部域名,必须放行;真正的跨站防护由 allow_origin 负责
c.ServerApp.allow_remote_access = True
c.ServerApp.allow_origin = 'https://nb.example.com'

# 保持 XSRF 校验开启(默认即 true,写出来防止被误改)
c.ServerApp.disable_check_xsrf = False

# 关闭内置终端(终端等于一个不记录命令的 shell,通常不需要)
c.ServerApp.terminals_enabled = False

# 禁止 root 身份启动
c.ServerApp.allow_root = False

# 工作目录固定,避免用户在主目录下乱放文件
c.ServerApp.root_dir = '/srv/notebooks'

# 空闲 kernel 自动回收,防止僵尸 kernel 占满内存
c.MappingKernelManager.cull_idle_timeout = 1800
c.MappingKernelManager.cull_interval = 300
c.MappingKernelManager.cull_connected = False

# 单次上传与请求体上限(防止大文件打满内存)
c.ServerApp.max_body_size = 200 * 1024 * 1024

启动方式改为使用配置文件:jupyter lab --config ~/.jupyter/jupyter_server_config.py。若走 systemd 托管,ExecStart 里必须带上同一份配置,否则重启后配置丢失,服务又回到默认状态。

第三步:用 nginx 做反向代理与前置认证

反代要解决两件事:把 443 的合法流量转给 127.0.0.1:8888,以及为 kernel 的 WebSocket 通道保留长连接。注意 Upgrade 与 Connection 头必须透传,否则页面能打开但执行代码一直显示「connecting」:

# 生成前置口令(与 Jupyter 口令相互独立,形成双因素)
htpasswd -c /etc/nginx/.htpasswd_nb alice

# /etc/nginx/conf.d/notebook.conf
server {
    listen 443 ssl http2;
    server_name nb.example.com;

    ssl_certificate     /etc/nginx/ssl/nb.example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/nb.example.com.key;

    # 只允许办公网与 VPN 段访问,公网直接 403
    allow 10.0.0.0/8;
    allow 192.168.10.0/24;
    deny  all;

    location /lab/ {
        auth_basic           "notebook";
        auth_basic_user_file /etc/nginx/.htpasswd_nb;

        proxy_pass         http://127.0.0.1:8888/lab/;
        proxy_http_version 1.1;

        # WebSocket 升级,缺这两行 kernel 无法连接
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # kernel 长连接,超时太短会在空闲后断开
        proxy_read_timeout  3600s;
        proxy_send_timeout  3600s;
        proxy_buffering     off;
    }
}

反代配置里 deny all; 与 allow 的顺序不能反,nginx 按书写顺序匹配,先 deny 会导致白名单也一起被拒。若通过 CDN 回源,注意 X-Forwarded-For 可被伪造,应改用 CDN 提供的真实 IP 头并只信任回源段。

第四步:容器化运行,限制沦陷后的破坏半径

认证被绕过时,隔离就是最后一道防线。以下参数组合的核心是「不给特权、不给外设、不给宿主控制面」:

docker run -d --name nb-alice \
  --user 1000:1000 \
  --cap-drop=ALL \
  --security-opt no-new-privileges:true \
  --pids-limit=512 \
  --memory=8g --memory-swap=8g \
  --cpus=4 \
  -v /srv/notebooks/alice:/home/jovyan/work:rw \
  -p 127.0.0.1:8888:8888 \
  jupyter/minimal-notebook:latest \
  start-notebook.sh \
    --ServerApp.password='argon2:$argon2id$v=19$m=10240,t=10,p=8$REPLACE_WITH_HASH' \
    --ServerApp.base_url=/lab/ \
    --ServerApp.allow_origin=https://nb.example.com \
    --ServerApp.terminals_enabled=False

三个参数必须强调:--cap-drop=ALL 去掉全部 capability,容器内无法 mount、无法改网络栈;--pids-limit 防止 fork 炸弹拖垮宿主机;-p 127.0.0.1:8888:8888 保证端口只在本机回环可达。绝对不要挂载 /var/run/docker.sock,也不要加 --privileged,这两个做法会让上面的隔离全部失效。

配置验证

# 1) 监听地址应为 127.0.0.1,不应出现 0.0.0.0
ss -lntp | grep 8888

# 2) 未认证访问 API:期望 403(Authentication required)
curl -s -o /dev/null -w 'api/status -> %{http_code}\n' http://127.0.0.1:8888/lab/api/status

# 3) 未认证创建 kernel:期望 403,绝不能返回 kernel id
curl -s -o /dev/null -w 'create kernel -> %{http_code}\n' \
  -X POST http://127.0.0.1:8888/lab/api/kernels \
  -H 'Content-Type: application/json' -d '{"name":"python3"}'

# 4) 错误口令走登录接口:期望 401
curl -s -o /dev/null -w 'login -> %{http_code}\n' \
  -X POST http://127.0.0.1:8888/lab/login \
  -d 'password=wrongpass' -H 'Content-Type: application/x-www-form-urlencoded'

# 5) 外部视角:公网 8888 应 closed/filtered
nmap -Pn -p 8888 <公网IP>

# 6) 反代层:不带 Basic Auth 访问应返回 401 而非 200
curl -s -o /dev/null -w 'proxy -> %{http_code}\n' https://nb.example.com/lab/

# 7) 容器权限复核:CapEff 应为 0000000000000000
docker exec nb-alice grep CapEff /proc/self/status
  • 认证:第 2、3、4 步全部为非 200(403 或 401),说明门锁生效。
  • 暴露面:第 1 步只有回环地址,第 5 步公网端口不可达。
  • 代理:第 6 步返回 401,说明 Basic Auth 生效;登录后再打开页面能正常执行代码,说明 WebSocket 通道通畅。
  • 隔离:第 7 步 CapEff 全 0,说明 capability 已清空。

常见问题

Q1:token 和 password 到底该留哪个?把 token 清空后为什么反而更危险?

两者是并列的认证凭据,任意一个通过即可登录。token 的优点是随机性强、无需用户设置,缺点是它出现在 URL 里,会留在浏览器历史、反代 access log、聊天记录与截图中,泄露面远比口令大;password 的优点是可通过 allow_origin + HTTPS + 前置认证叠加,缺点是弱口令就是灾难。把 token 清空本身不会让服务变安全——如果此时 c.ServerApp.password 仍为空,服务会进入无认证模式,任何人都能直接进。所以正确顺序永远是:先 jupyter server password 写入 argon2 哈希,确认生效,再把 token 置空。

Q2:反代配置写好、页面能登录,但一执行代码就卡在 connecting,控制台报 WebSocket 握手失败,怎么修?

这是典型的 WebSocket 未透传。三个检查点:第一,location 里必须有 proxy_http_version 1.1; 与 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";,缺 http_version 1.1 时 nginx 默认用 1.0,Upgrade 头会被丢弃。第二,proxy_read_timeout 要放大到小时级,否则 kernel 空闲一会儿就被切断,表现为「过几分钟再执行就没反应」。第三,base_url 必须与反代路径一致(本例都是 /lab/),不一致时前端请求会指向错误路径,WebSocket 连到 /api/kernels/.../channels 而不是 /lab/api/...。若前面还有 CDN,需确认 CDN 支持并转发 WebSocket。

Q3:团队 5 个人共用一个 Jupyter 实例行不行?

技术上能跑,安全上不建议。共用实例意味着所有 kernel 以同一系统用户身份运行,彼此的进程可见、/proc 可读、工作目录可写,任何一个人上传的脚本都能读到其他人的 .env、SSH 私钥与数据集。cull_idle_timeout 只能回收空闲 kernel,解决不了隔离问题。人数超过 2 人或者存在不同权限等级时,应改用 JupyterHub:每个用户一个独立容器、独立存储卷,认证接 LDAP/OIDC,资源配额按用户下发。若短期无法上 Hub,至少做到「一人一实例一端口一系统用户」,并在反代层按用户维度绑定 Basic Auth 账号。

Q4:忘记口令或者配置写错导致无法登录,如何在不丢 kernel 数据的前提下恢复?

口令只存在配置文件里,重置不影响工作目录。jupyter server password 会覆盖 c.ServerApp.password,执行后重启服务即可。若连配置文件都改坏了,可用最小参数临时启动一个新实例验证:jupyter lab --no-browser --ip=127.0.0.1 --port=8899 --ServerApp.token='' --ServerApp.password='',仅限本机回环、验证完立刻停止。注意工作目录与 kernel 状态不共享,临时实例看不到原 kernel 里的内存变量,因此关键结果应随时保存到文件而不是只留在内存中。

总结

Jupyter Notebook 的安全问题可以用一句话概括:它默认把代码执行能力暴露在 HTTP 上,而认证只是一个可能被关掉的开关。jupyter 安全 的落地路径应当固定为四步:绑定 127.0.0.1 收掉公网暴露、设置 argon2 口令并清空 URL token、用 nginx 做 HTTPS 反代加 allow_origin 白名单、容器化运行并清空 capability。四步做完之后,即使口令泄露,攻击面也被限制在单个容器与单个工作目录内。所有配置改完都要用本文的验证命令实测一遍,尤其是「未认证创建 kernel」这一项——它是判断这个服务是否真的可被远程执行代码的唯一硬指标。