diff --git a/CLAUDE.md b/CLAUDE.md index 3cc36c6..8c8f42d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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'` 传)。 diff --git a/deploy/ipass-agent.py b/deploy/ipass-agent.py index fba42ad..869e74b 100644 --- a/deploy/ipass-agent.py +++ b/deploy/ipass-agent.py @@ -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/?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)") diff --git a/readme.md b/readme.md index 5989734..1d30509 100755 --- a/readme.md +++ b/readme.md @@ -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/?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` 会原样返回。