fix(deploy): ipass-agent 加「受管容器」锁,破坏性操作只碰 ipass 容器

问题:update / restart / rollback 的 name 参数**没有任何校验** —— 传
{"name":"invoicehelper-nginx"} 就会去重启/删除同机别的容器(.11 上还跑着
invoicehelper-nginx、d15-nginx-1 等)。

修复:
- 新增 managed_container() / ensure_managed():--name 指定者优先 → 自动探测到的
  ipass 容器 → 两者都没有时退化为 ipass* 前缀白名单
- _post 同步前置校验(非法 name 直接 403、**不建任务**);op_update 内再校验一次
  (op_rollback 内部也走 op_update,纵深防御)
- _dispatch 把 PermissionError 映射为 403;/containers 保留全量但标注 managed;
  / 与 /logs 统一走受管容器
- VERSION 1.0.0 → 1.0.1

本地实测(自造 victim-app + ipass-dt2 两个容器,未触碰任何真实业务容器):
- `--name ipass-dt2`:对 victim-app 发 restart/update/rollback 全部 403,且
  victim-app 的 State.StartedAt 前后完全一致;对 ipass-dt2 正常重启
- 无 `--name` 且机器上没有 ipass 容器:victim-app → 403(前缀白名单);
  ipass-x 通过校验后由 docker 报「No such container」
This commit is contained in:
admin committed 2026-09-12 11:02:28 +08:00
1 parent 327838b427
commit 13c0c7a427
3 files changed
+94 -21

No files matched your search

+7
View File
@@ -447,10 +447,17 @@ curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback
- **HTTP/1.1 必须先把请求体读掉再应答**(哪怕是 401):不读的话残包会被当成下一个请求的
请求行 → 响应串包。改 Handler 时别把 `_read_body()` 从 `_dispatch` 开头挪走。
- 端口/挂载/env/网络/重启策略从旧容器 `docker inspect` 复刻;动手前自动备份 + 打 rollback 标签。
- **受管容器锁(别退回「信任调用方传的 name」)**:`update` / `restart` / `rollback` 只允许作用于
「受管容器」——`--name` 指定者优先,否则自动探测到的 ipass 容器;两者都没有时退化为主机名
前缀白名单 `ipass*`(`ensure_managed()`)。传别的容器名 → **403 且不建任务**。同机通常还跑着
别的 nginx(.11 上有 `invoicehelper-nginx`、`d15-nginx-1`),没这道锁 = 把删/起容器的能力
开到整台机器。
- `/data` 对 `api_key` 脱敏,但 `domains.json` 原样返回 —— 服务等价 docker 权限,**必须设 token
且只在内网监听**,绝不上公网。
- 本机自测夹具做法:造 `ipass-dt` 容器(高位端口 + `/tmp` 数据目录),`--port` 用 18449,
`IPASS_AGENT_TOKEN=xxx` 固定 token,`POST /update` 带 `skip_pull:true` + 本地镜像。
再顺手造一个**非 ipass 名**的容器(如 `victim-app`)验证守卫:对它发 restart / update / rollback
应**全部 403**,且它的 `docker inspect -f '{{.State.StartedAt}}'` **前后一字不变**。
注意 `echo "$JSON" | python3` 在 **zsh 下会把 `\r` 还原成真回车**导致 JSON 解析报错 ——
那是测试命令的问题,不是服务的 bug(用文件或 `printf '%s'` 传)。
+77 -17
View File
@@ -27,6 +27,16 @@ ipass-agent — iPass 容器远程更新控制面
token 取值顺序:--token > 环境变量 IPASS_AGENT_TOKEN > ~/.ipass-agent-token
(文件不存在时随机生成并写入,权限 600)
--------------------------------------------------------------------------------
受管容器(限定爆炸半径)—— 重要
--------------------------------------------------------------------------------
本服务等价 docker 权限,但**只操作一个容器**(下称「受管容器」):
① `--name` 显式指定者优先;② 否则自动探测到的 ipass 容器(结果缓存一次)。
两者都没有时退化为主机名前缀白名单(`ipass*`,见 MANAGED_PREFIX)。
update / restart / rollback 若带 `name` 且**不等于**受管容器 → 直接 403,
不建任务、更不会碰那个容器;`GET /containers` 会标明哪个是 managed。
(同一台机器上往往还跑着别的 nginx / 业务容器,绝不能误伤。)
--------------------------------------------------------------------------------
端点一览
--------------------------------------------------------------------------------
@@ -34,8 +44,8 @@ token 取值顺序:--token > 环境变量 IPASS_AGENT_TOKEN > ~/.ipass-agent-t
GET / 服务信息 + 端点清单
GET /check 探测(dry-run):容器 / 端口 / 挂载 / 数据摘要
GET /status 当前容器状态 + 镜像 digest + 数据摘要 + 宿主探活
GET /containers 所有候选容器(名字或镜像含 ipass)
GET /logs?tail=200 容器日志
GET /containers 所有容器(标注哪个是受管容器)
GET /logs?tail=200 受管容器的日志
GET /data?file=users 数据文件摘要(api_key 已脱敏)
GET /jobs?limit=5 最近任务列表
GET /jobs/<id>?offset=N 任务详情 + 增量日志
@@ -44,6 +54,8 @@ token 取值顺序:--token > 环境变量 IPASS_AGENT_TOKEN > ~/.ipass-agent-t
POST /rollback {"tag":...} 回滚到 rollback 标签(异步任务)
POST /restart 只重启容器(同步)
`name` 只接受受管容器(见上);传其它容器名 → 403。
任务(job)在同一时刻**只允许一个**在跑,避免并发删容器互相踩。
"""
@@ -69,7 +81,7 @@ from urllib.parse import urlparse, parse_qs
# ------------------------------------------------------------------ 常量
SERVICE = "ipass-agent"
VERSION = "1.0.0"
VERSION = "1.0.1"
DEFAULT_PORT = 18099
DEFAULT_IMAGE = ("crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/"
@@ -217,6 +229,47 @@ def detect_container(prefer=None):
return None
# ------------------------------------------------- 受管容器(限定爆炸半径)
#
# 本服务等价 docker 权限,而同一台机器上通常还跑着**别的** nginx / 业务容器
# (实测 .11 上就有 invoicehelper-nginx、d15-nginx-1 …)。所有破坏性操作
# (update / restart / rollback)**只允许作用于「受管容器」**:
# ① 显式 `--name` 指定的那个;② 否则自动探测到的 ipass 容器(结果缓存一次)。
# 两者都没有时退化为主机名前缀白名单(`ipass*`)。
# ⚠️ 不要改成「信任调用方传进来的 name」—— 那等于把删/起容器的能力开到全机器。
MANAGED_PREFIX = "ipass"
def managed_container():
"""受管容器名(缓存)。显式 --name 优先,否则自动探测一次。"""
if BACK.get("name"):
return BACK["name"]
if BACK.get("_managed") is None:
BACK["_managed"] = detect_container(None)
return BACK["_managed"]
def ensure_managed(name):
"""把目标容器收敛到受管容器;不合法抛 PermissionError(HTTP 层 → 403)。"""
managed = managed_container()
if not name:
if managed:
return managed
raise PermissionError("未发现受管容器(容器名应以 %r 开头),拒绝操作"
% MANAGED_PREFIX)
if managed:
if name != managed:
raise PermissionError(
"拒绝操作容器 %s:本控制面只管 %s(避免误伤同机其它容器)"
% (name, managed))
return name
if not name.lower().startswith(MANAGED_PREFIX):
raise PermissionError("拒绝操作容器 %s:只允许 %s* 开头的受管容器"
% (name, MANAGED_PREFIX))
return name
def inspect_one(name):
rc, out = docker(["inspect", name])
if rc != 0:
@@ -495,9 +548,9 @@ def op_pull(job, p):
def op_update(job, p):
name = p.get("name") or detect_container(BACK["name"])
if not name:
raise RuntimeError("未发现 ipass 容器,请用 --name 指定或检查 docker ps -a")
# 受管容器约束。HTTP 层已同步校验过一次(非法 name 直接 403、不建任务),
# 这里是纵深防御 —— op_rollback 内部也走 op_update,不能只靠入口把关。
name = ensure_managed(p.get("name"))
image = p.get("image") or DEFAULT_IMAGE
skip_pull = bool(p.get("skip_pull"))
data_override = p.get("data_dir")
@@ -733,7 +786,8 @@ def build_status(name=None):
# ------------------------------------------------------------------ HTTP 层
BACK = {"quiet": False, "name": None, "data_dir": None, "token": ""}
BACK = {"quiet": False, "name": None, "data_dir": None, "token": "",
"_managed": None}
class Handler(BaseHTTPRequestHandler):
@@ -799,6 +853,8 @@ class Handler(BaseHTTPRequestHandler):
if method == "GET":
return self._get(path)
return self._post(path)
except PermissionError as e:
return self._send(403, {"error": str(e)})
except Exception as e: # noqa: BLE001
return self._send(500, {"error": str(e)})
@@ -810,7 +866,8 @@ class Handler(BaseHTTPRequestHandler):
if path == "/":
return self._send(200, {
"service": SERVICE, "version": VERSION, "docker": DOCKER,
"container": detect_container(BACK["name"]),
"container": managed_container(),
"note": "破坏性操作(update/restart/rollback)只作用于 container 这个受管容器",
"default_image": DEFAULT_IMAGE,
"endpoints": [
"GET /health", "GET /check", "GET /status",
@@ -828,9 +885,13 @@ class Handler(BaseHTTPRequestHandler):
if path == "/status":
return self._send(200, build_status(BACK["name"]))
if path == "/containers":
return self._send(200, {"containers": [
{"name": n, "image": i, "status": s}
for n, i, s in list_containers()]})
managed = managed_container()
return self._send(200, {
"managed": managed,
"note": "只有 managed 这个容器会被本服务更新/重启/回滚",
"containers": [
{"name": n, "image": i, "status": s, "managed": n == managed}
for n, i, s in list_containers()]})
if path == "/logs":
name = BACK["name"] or detect_container(None)
if not name:
@@ -888,21 +949,19 @@ class Handler(BaseHTTPRequestHandler):
return self._send(202 if job else 409,
{"job": job["id"]} if job else {"error": err})
if path == "/update":
p.setdefault("name", BACK["name"])
p.setdefault("data_dir", BACK["data_dir"])
p["name"] = ensure_managed(p.get("name")) # 非法 → 403,不建任务
job, err = start_job("update", op_update, p)
return self._send(202 if job else 409,
{"job": job["id"]} if job else {"error": err})
if path == "/rollback":
p.setdefault("name", BACK["name"])
p.setdefault("data_dir", BACK["data_dir"])
p["name"] = ensure_managed(p.get("name"))
job, err = start_job("rollback", op_rollback, p)
return self._send(202 if job else 409,
{"job": job["id"]} if job else {"error": err})
if path == "/restart":
name = p.get("name") or BACK["name"] or detect_container(None)
if not name:
return self._send(404, {"error": "未发现容器"})
name = ensure_managed(p.get("name")) # 非法 → 403
rc, out = docker(["restart", name], timeout=120)
code = http_probe(build_check(name).get("main_port"))
return self._send(200 if rc == 0 else 500,
@@ -985,7 +1044,8 @@ def main():
ap = argparse.ArgumentParser(description="iPass 容器远程更新控制面")
ap.add_argument("--port", type=int, default=DEFAULT_PORT)
ap.add_argument("--bind", default="0.0.0.0")
ap.add_argument("--name", help="容器名(缺省自动探测)")
ap.add_argument("--name", help="受管容器名(缺省自动探测 ipass* 容器;"
"破坏性操作只作用于它)")
ap.add_argument("--data-dir", help="数据目录(缺省从容器挂载读)")
ap.add_argument("--image", help="默认更新目标镜像")
ap.add_argument("--token", help="访问令牌(缺省用环境变量/~/.ipass-agent-token)")
+10 -4
View File
@@ -577,14 +577,14 @@ tail -f ~/ipass-agent.log # 日志(pid 在 ~/ipass-agent
| GET | `/` | 服务信息 + 端点清单 |
| GET | `/check` | 探测(dry-run),等价 `--check` |
| GET | `/status` | 容器状态 + 镜像 digest + 数据摘要 + 宿主探活 |
| GET | `/containers` | 容器列表(只留与 ipass/nginx 相关的) |
| GET | `/logs?tail=200` | 容器日志 |
| GET | `/containers` | 所有容器(`managed` 字段标出哪个是**受管容器**) |
| GET | `/logs?tail=200` | **受管容器**的日志 |
| GET | `/data?file=users\|domains\|upstreams` | 数据文件摘要(**`api_key` 已脱敏**) |
| GET | `/jobs?limit=5`、`/jobs/<id>?offset=N` | 任务列表 / 任务详情 + 增量日志 |
| POST | `/pull` | `{image, registry_user?, registry_pass?}` → 只拉镜像 |
| POST | `/update` | `{image?, skip_pull?, name?, data_dir?, host_port?}` → 完整更新 |
| POST | `/update` | `{image?, skip_pull?, name?, data_dir?, host_port?}` → 完整更新(`name` 只接受受管容器) |
| POST | `/rollback` | `{tag?}` → 回滚到最近(或指定)的 `rollback-*` 镜像 |
| POST | `/restart` | 只重启容器(同步返回) |
| POST | `/restart` | 只重启容器(同步返回;`{name?}` 只接受受管容器) |
典型远程调用:
@@ -601,6 +601,12 @@ curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback # 出
> `image` 填**当前要上的 tag**(§12.6 的约定:只增不改,发新版就换新号,别覆盖旧号)。
> 不传 `image` 时用服务启动时的默认值(`--image` 指定,缺省 `ipass-1.0.0`)。
**爆炸半径:只碰一个容器**。虽然它等价 docker 权限,但**破坏性操作只作用于「受管容器」**——
`--name` 指定者优先,否则自动探测到的 ipass 容器;两者都没有时退化为 `ipass*` 前缀白名单。
`/update`、`/rollback`、`/restart` 请求里带 `name` 且**不等于**受管容器 → **直接 403**,
不建任务、更不会碰那个容器;`GET /containers` 的 `managed` 字段标明受管的是谁。
(实测:对同机另一个容器发这三种请求全部 403,该容器 `StartedAt` 前后完全不变。)
**安全**:这个服务能删/起容器,**等价服务器上的 docker 权限**,务必做到
① **必须设 token**(别用空/弱口令);② 只在内网监听(默认 `0.0.0.0`,可 `--bind 127.0.0.1`
或加防火墙);③ **绝不暴露到公网**。`/data` 对 `api_key` 已脱敏,但 `domains.json` 会原样返回。