From a05efbf27a784a96052157318c9b47ef0032f6a9 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Fri, 16 Oct 2026 10:17:37 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=89=E5=85=A8=E5=93=8D=E5=BA=94=E5=A4=B4?= =?UTF-8?q?=EF=BC=9A=E6=89=80=E6=9C=89=20HTTP=20=E5=93=8D=E5=BA=94?= =?UTF-8?q?=E8=A1=A5=20nosniff=E3=80=81Referrer-Policy=20=E5=92=8C=20CSP?= =?UTF-8?q?=20frame-ancestors=EF=BC=8C=E9=A1=B5=E9=9D=A2=E5=8F=AA=E4=B8=8A?= =?UTF-8?q?=E6=8A=A5=E4=B8=A5=E6=A0=BC=E7=9A=84=20script-src?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 以前服务端一个安全头都不发,任何站点都能把 AgentLab 嵌进 iframe:同站门户(Lax 会话 cookie 会随请求带上)和关登录的部署 都有被点击劫持的可能,也没有「允许谁嵌」的白名单可配。 - 新增 app/web_security.py,纯 ASGI 中间件,main.py 里加在最外层:CORS 预检、登录检查自己回的 401 / 403 也带上; WebSocket 不经过它;接口自己设过的同名头(文件下载的 nosniff)不覆盖、不重复 - frame-ancestors 缺省只有 'self',这时另加 X-Frame-Options: SAMEORIGIN;AGENTLAB_FRAME_ANCESTORS 配了同站门户的白名单时 只发 CSP(XFO 写不了白名单,两个都发会让只认 XFO 的老浏览器把门户也拦掉) - 分享页 /s 只认 AGENTLAB_EMBED_ORIGINS、Referrer-Policy 用 no-referrer。分享链接第 3 波才加,这一波先把配置读进来、 头的规则写好 - 严格的 script-src 先只发 Content-Security-Policy-Report-Only:mount_web 启动时给构建产物 index.html 里的内联主题 脚本算 sha256,只在页面响应上发;接口返回的 HTML(导出的报告自带 meta CSP)不发、不动。观察一个版本没有误报再强制执行 - HSTS 交给终结 https 的反向代理 - 两个白名单只收「协议://主机[:端口]」(可以 *. 开头),带路径、裸 *、没写协议的启动时就报错;deploy/agentlab.env 写明 两个变量和缺省行为 测试 tests/test_web_security.py:页面、/api、中间件自己的 401、CORS 预检都带头;白名单生效时不发 XFO;/s 的规则; 上报策略只在页面上、哈希对得上;已有的头不重复;WebSocket 不受影响;白名单写错启动报错;子进程起真实的 app.main 核对 环境变量接线。 --- backend/app/core/config.py | 34 ++++- backend/app/main.py | 3 + backend/app/web.py | 11 +- backend/app/web_security.py | 90 +++++++++++ backend/tests/test_web_security.py | 235 +++++++++++++++++++++++++++++ deploy/agentlab.env | 11 ++ 6 files changed, 381 insertions(+), 3 deletions(-) create mode 100644 backend/app/web_security.py create mode 100644 backend/tests/test_web_security.py diff --git a/backend/app/core/config.py b/backend/app/core/config.py index 9dcf013a..27533ecd 100644 --- a/backend/app/core/config.py +++ b/backend/app/core/config.py @@ -1,9 +1,10 @@ from __future__ import annotations import ipaddress +import re from functools import lru_cache from pathlib import Path -from typing import Annotated +from typing import Annotated, Any from pydantic import field_validator from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict @@ -11,6 +12,9 @@ from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict BACKEND_DIR = Path(__file__).resolve().parents[2] PROJECT_DIR = BACKEND_DIR.parent +#: 嵌入白名单里一项的主机部分:域名(可以 *. 开头)或方括号里的 IPv6,可以带端口;不许路径、查询、用户名 +_ORIGIN_HOST = re.compile(r"(?:\*\.)?(?:[A-Za-z0-9-]+\.)*[A-Za-z0-9-]+(?::\d{1,5})?|\[[0-9A-Fa-f:.]+\](?::\d{1,5})?") + # session_id 拼进路径前必须过这一关。允许的字符刻意收得很窄:字母数字加 # 连字符下划线——点号也不放行,免得出现 ".." 这种能往上走的名字。 _SESSION_MAX = 64 @@ -64,6 +68,13 @@ class Settings(BaseSettings): # 不设时按请求的 Host 拼 public_url: str = "" + # --- 安全响应头(app/web_security.py)--- + # 允许哪些站点用 iframe 嵌整站(同站的门户,如 https://portal.example.com),逗号分隔。本站自己总是允许的。 + # 不设时只有本站能嵌(frame-ancestors 'self',另加 X-Frame-Options: SAMEORIGIN) + frame_ancestors: Annotated[list[str], NoDecode] = [] + # 分享页(/s)允许被哪些站点嵌,逗号分隔,写法同上。分享页只认这一项,不认上面那一项 + embed_origins: Annotated[list[str], NoDecode] = [] + # --- 沙箱 --- sandbox_backend: str = "auto" # auto | microvm | seatbelt | bubblewrap | local | off sandbox_timeout: int = 30 @@ -121,7 +132,8 @@ class Settings(BaseSettings): "https://223.5.5.5/resolve", ] - @field_validator("http_tool_allowlist", "http_tool_fake_ip_ranges", "http_tool_doh_urls", mode="before") + @field_validator("http_tool_allowlist", "http_tool_fake_ip_ranges", "http_tool_doh_urls", "frame_ancestors", + "embed_origins", mode="before") @classmethod def _comma_list(cls, value: object) -> object: # 环境变量里写逗号分隔;也兼容 JSON 数组的写法 @@ -134,6 +146,24 @@ class Settings(BaseSettings): return [part.strip() for part in text.split(",") if part.strip()] return value + @field_validator("frame_ancestors", "embed_origins") + @classmethod + def _valid_origins(cls, value: list[str], info: Any) -> list[str]: + # 只收「协议://主机[:端口]」,主机可以写 *.example.com。路径、裸 *、没写协议的写错了启动时就报出来,别到嵌入 + # 失败(或者整站被谁都能嵌)才发现。'self' 本来就有,写了也不重复 + name = f"AGENTLAB_{(info.field_name or '').upper()}" + out: list[str] = [] + for raw in value: + item = raw.strip().rstrip("/") + if item == "'self'": + continue + scheme, _, host = item.partition("://") + if scheme.lower() not in ("http", "https") or not _ORIGIN_HOST.fullmatch(host): + raise ValueError(f"{name} 里的「{raw}」需要写成「协议://主机」(可以带端口),例如 https://portal.example.com") + if (origin := f"{scheme.lower()}://{host.lower()}") not in out: + out.append(origin) + return out + @field_validator("auth_cookie_secure", mode="before") @classmethod def _blank_is_auto(cls, value: object) -> object: diff --git a/backend/app/main.py b/backend/app/main.py index 657c917a..62cfea6f 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -30,6 +30,7 @@ from app.core.config import settings from app.db.base import init_db from app.engine.runner import run_manager from app.seed import seed_defaults +from app.web_security import SecurityHeaders logging.basicConfig( level=logging.INFO, @@ -192,6 +193,8 @@ app.add_middleware( allow_methods=["*"], allow_headers=["*"], ) +# 安全响应头(app/web_security.py):最后加、在最外层,CORS 预检和登录检查自己回的 401 / 403 也带上 +app.add_middleware(SecurityHeaders) # 路由级权限(§3.12)。关登录时这些依赖全部放行;开了登录,中间件先挡掉没登录的,这里再按角色和运行挡 _BUILDER = [require_role("builder")] diff --git a/backend/app/web.py b/backend/app/web.py index d2c36605..30602b95 100644 --- a/backend/app/web.py +++ b/backend/app/web.py @@ -9,7 +9,9 @@ - /api 下不存在的路径照旧是 JSON 404。排除 /api 写在路由的路径规则里,不在处理函数里判断—— 否则 POST /api/不存在 会因为「路径对上了、方法不对」变成 405; - 只注册 GET / HEAD 的 HTTP 路由,WebSocket 不经过这里; -- index.html 不缓存,发版后刷新即生效;assets/ 下的文件名带内容哈希,长缓存。 +- index.html 不缓存,发版后刷新即生效;assets/ 下的文件名带内容哈希,长缓存; +- index.html 另带严格 script-src 的上报策略(Content-Security-Policy-Report-Only):启动时按构建产物里的内联脚本算 + sha256(web_security.script_policy),只上报、不拦。其余安全头由 web_security 的中间件统一补。 """ from __future__ import annotations @@ -20,6 +22,8 @@ from fastapi import FastAPI, HTTPException from fastapi.responses import FileResponse from starlette.convertors import Convertor, register_url_convertor +from app.web_security import REPORT_ONLY_HEADER, script_policy + _NO_CACHE = "no-cache" _IMMUTABLE = "public, max-age=31536000, immutable" @@ -72,7 +76,12 @@ def mount_web(app: FastAPI, dist: Path) -> None: "先构建前端(cd frontend && pnpm build),或者去掉这个设置" ) + # 哈希按启动这一刻的 index.html 算:换了构建产物要重启服务,哈希才跟着换(只上报不拦,对不上也只多几条上报) + page_headers = {"Cache-Control": _NO_CACHE, REPORT_ONLY_HEADER: script_policy(index.read_text(encoding="utf-8"))} + def respond(target: Path, *, immutable: bool = False) -> FileResponse: + if target in (index, index.resolve()): + return FileResponse(target, media_type=_media_type(target), headers=page_headers) return FileResponse( target, media_type=_media_type(target), diff --git a/backend/app/web_security.py b/backend/app/web_security.py new file mode 100644 index 00000000..a7ae8646 --- /dev/null +++ b/backend/app/web_security.py @@ -0,0 +1,90 @@ +"""安全响应头(04 细案 C1):页面不能被别的站点套进 iframe 诱导点击,浏览器不按内容猜类型,链接不把完整地址带给别的站点。 + +以前服务端一个安全头都不发:任何站点都能把 AgentLab 嵌进 iframe。同站的门户页面(SameSite=Lax 的会话 cookie 会随请求 +带上)和关登录的部署,都有被点击劫持的可能;也没有一条「允许谁嵌」的白名单可配。 + +纯 ASGI 中间件(同 auth/middleware.py,main.py 里加在最外层):在 http.response.start 上补头,WebSocket 不经过它。 +所有 HTTP 响应(页面、/api、登录检查自己回的 401 / 403、CORS 预检)都补: +- X-Content-Type-Options: nosniff; +- Referrer-Policy: strict-origin-when-cross-origin(分享页 /s 用 no-referrer:分享的 key 在地址的 # 后面,本来不随 + Referer 走,这里再收一道); +- Content-Security-Policy: frame-ancestors。缺省只有 'self';AGENTLAB_FRAME_ANCESTORS 列出允许嵌整站的同站门户;分享页 + /s 只认 AGENTLAB_EMBED_ORIGINS(分享链接第 3 波才加,路由在那时挂,头的规则先在这里定好); +- 只有 frame-ancestors 是 'self' 时另加 X-Frame-Options: SAMEORIGIN,给不认 CSP 的老浏览器。XFO 写不了白名单,有白名单 + 时只发 CSP:两个都发的话,只认 XFO 的老浏览器会把白名单里的门户也拦掉(认 CSP 的浏览器以 frame-ancestors 为准)。 +接口自己设过的同名头(文件下载的 nosniff)不覆盖、不重复。 + +严格的 script-src 先只上报、不拦(Content-Security-Policy-Report-Only):页面里有一段首帧前定主题的内联脚本,强制执行 +的话写错一个哈希页面就会先闪一帧深色,构建会不会产出别的内联内容也没核实。所以 mount_web(app/web.py)启动时给构建产物 +index.html 里的内联脚本算 sha256(script_policy),只在页面这一个响应上发;观察一个版本没有误报,再改成强制执行。没配 +上报地址:违规只在浏览器的控制台里看得到。接口返回的 HTML(导出的报告、可验证报告)文件里自带 meta CSP,不发它,也不动。 + +HSTS 交给终结 https 的反向代理:这里不知道对外是不是 https、要不要连子域名一起管,发错了浏览器会按 max-age 记很久, +撤不回来。 +""" +from __future__ import annotations + +import base64 +import hashlib +import re +from typing import Any + +#: 分享页的路径(/s#<分享 key>):只认 /s 这一段,/settings、/studio 不算 +SHARE_PATH = "/s" +_SELF = "'self'" +_DEFAULT_REFERRER = b"strict-origin-when-cross-origin" +_SHARE_REFERRER = b"no-referrer" +#: 页面里不带 src 的 " + "" + "
") +HASH = base64.b64encode(hashlib.sha256(THEME.encode()).digest()).decode() +REPORT = ("" + "") + + +@pytest.fixture +def dist(tmp_path: Path) -> Path: + root = tmp_path / "dist" + (root / "assets").mkdir(parents=True) + (root / "index.html").write_text(INDEX) + (root / "assets" / "index-AbC123.js").write_text("console.log('bundle')") + return root + + +def _app(dist: Path | None = None, **config) -> FastAPI: + app = FastAPI() + api = APIRouter(prefix="/api") + + @api.get("/ping") + async def ping() -> dict[str, str]: + return {"pong": "1"} + + @api.get("/report.html") + async def report() -> HTMLResponse: + return HTMLResponse(REPORT) + + @api.get("/download") + async def download() -> Response: + # 文件下载自己设了 nosniff(api/files.py):不能再加一份 + return Response(b"x", headers={"X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer"}) + + @api.websocket("/echo") + async def echo(ws: WebSocket) -> None: + await ws.accept() + await ws.send_text(await ws.receive_text()) + await ws.close() + + app.include_router(api) + if dist is not None: + from app.web import mount_web + + mount_web(app, dist) + app.add_middleware(SecurityHeaders, **config) + return app + + +async def _get(app: FastAPI, path: str) -> httpx.Response: + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://t") as client: + return await client.get(path) + + +def _single(r: httpx.Response, name: str) -> str | None: + values = r.headers.get_list(name) + assert len(values) <= 1, f"{name} 发了 {len(values)} 份:{values}" + return values[0] if values else None + + +async def test_api_and_page_carry_the_defaults(dist: Path) -> None: + app = _app(dist, frame_ancestors=[], embed_origins=[]) + for path in ("/api/ping", "/api/nope", "/", "/studio", "/assets/index-AbC123.js"): + r = await _get(app, path) + assert _single(r, "x-content-type-options") == "nosniff", path + assert _single(r, "referrer-policy") == "strict-origin-when-cross-origin", path + assert _single(r, "content-security-policy") == "frame-ancestors 'self'", path + assert _single(r, "x-frame-options") == "SAMEORIGIN", path + + +async def test_report_only_script_policy_is_only_on_the_page(dist: Path) -> None: + app = _app(dist, frame_ancestors=[], embed_origins=[]) + for path in ("/", "/studio", "/runs/abc/evidence"): + r = await _get(app, path) + assert r.text == INDEX + assert _single(r, "content-security-policy-report-only") == f"script-src 'self' 'sha256-{HASH}'", path + # 脚本文件、接口不带;接口返回的 HTML(导出的报告)自带 meta CSP,不加一份对不上哈希的上报策略,正文原样 + for path in ("/assets/index-AbC123.js", "/api/ping", "/api/report.html"): + r = await _get(app, path) + assert "content-security-policy-report-only" not in r.headers, path + r = await _get(app, "/api/report.html") + assert r.text == REPORT + + +async def test_whitelist_wins_and_drops_x_frame_options() -> None: + app = _app(frame_ancestors=["https://portal.example.com", "https://*.corp.example"], embed_origins=[]) + r = await _get(app, "/api/ping") + assert _single(r, "content-security-policy") == \ + "frame-ancestors 'self' https://portal.example.com https://*.corp.example" + assert "x-frame-options" not in r.headers, "有白名单时以 CSP 为准:XFO 写不了白名单" + + +async def test_share_page_uses_the_embed_origins(dist: Path) -> None: + app = _app(dist, frame_ancestors=["https://portal.example.com"], embed_origins=["https://bi.example.org"]) + for path in ("/s", "/s/", "/s/anything"): + r = await _get(app, path) + assert _single(r, "content-security-policy") == "frame-ancestors 'self' https://bi.example.org", path + assert _single(r, "referrer-policy") == "no-referrer", path + assert "x-frame-options" not in r.headers, path + # 只认 /s 这一段:/settings、/studio 照整站的规则 + for path in ("/settings", "/studio", "/share"): + r = await _get(app, path) + assert _single(r, "content-security-policy") == "frame-ancestors 'self' https://portal.example.com", path + assert _single(r, "referrer-policy") == "strict-origin-when-cross-origin", path + # 没配嵌入白名单:分享页只能被本站嵌,同样另加 XFO + r = await _get(_app(dist, frame_ancestors=[], embed_origins=[]), "/s") + assert _single(r, "content-security-policy") == "frame-ancestors 'self'" + assert _single(r, "x-frame-options") == "SAMEORIGIN" + + +async def test_headers_already_set_are_kept() -> None: + r = await _get(_app(frame_ancestors=[], embed_origins=[]), "/api/download") + assert _single(r, "x-content-type-options") == "nosniff" + assert _single(r, "referrer-policy") == "no-referrer" + assert _single(r, "content-security-policy") == "frame-ancestors 'self'" + + +def test_websocket_is_not_touched() -> None: + with TestClient(_app(frame_ancestors=[], embed_origins=[])) as client: + with client.websocket_connect("/api/echo") as ws: + ws.send_text("hi") + assert ws.receive_text() == "hi" + + +async def test_main_app_and_its_own_refusals_carry_the_headers() -> None: + """真实的 app.main:加在最外层,登录检查自己回的 401、CORS 预检也带。""" + app = main_app + r = await _get(app, "/api/health") + assert _single(r, "content-security-policy") == "frame-ancestors 'self'" + assert _single(r, "x-frame-options") == "SAMEORIGIN" and _single(r, "x-content-type-options") == "nosniff" + await auth_env.reset() + try: + await auth_env.turn_on_local() + r = await _get(app, "/api/workflows") + assert r.status_code == 401 and r.json()["code"] == "auth_required" + assert _single(r, "x-content-type-options") == "nosniff" + assert _single(r, "content-security-policy") == "frame-ancestors 'self'" + finally: + await auth_env.reset() + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://t") as client: + r = await client.options("/api/health", headers={"Origin": "http://localhost:5273", + "Access-Control-Request-Method": "GET"}) + assert r.status_code == 200 and _single(r, "x-content-type-options") == "nosniff" + + +def test_origin_lists_parse_and_bad_entries_fail_at_startup(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("AGENTLAB_FRAME_ANCESTORS", raising=False) + monkeypatch.delenv("AGENTLAB_EMBED_ORIGINS", raising=False) + assert Settings().frame_ancestors == [] and Settings().embed_origins == [] + monkeypatch.setenv("AGENTLAB_FRAME_ANCESTORS", " https://portal.example.com/ , https://*.corp.example,'self'") + monkeypatch.setenv("AGENTLAB_EMBED_ORIGINS", '["http://bi.example.org:8080"]') + got = Settings() + assert got.frame_ancestors == ["https://portal.example.com", "https://*.corp.example"], "末尾的 / 去掉,'self' 本来就有" + assert got.embed_origins == ["http://bi.example.org:8080"] + monkeypatch.delenv("AGENTLAB_EMBED_ORIGINS") + # 只收「协议://主机[:端口]」:路径、通配一切、没写协议、'none' 这类写法启动时就报出来,别到嵌入失败才发现 + for bad in ("*", "portal.example.com", "https://portal.example.com/app", "ftp://portal.example.com", "'none'", + "https://", "https://portal.example.com?x=1"): + monkeypatch.setenv("AGENTLAB_FRAME_ANCESTORS", bad) + with pytest.raises(ValidationError, match="AGENTLAB_FRAME_ANCESTORS"): + Settings() + + +def test_deploy_env_documents_both_lists() -> None: + text = (PROJECT_DIR / "deploy" / "agentlab.env").read_text() + assert "# AGENTLAB_FRAME_ANCESTORS=" in text and "# AGENTLAB_EMBED_ORIGINS=" in text + + +_PROBE = r""" +import asyncio, json, httpx +from app.main import app + +async def main(): + t = httpx.ASGITransport(app=app) + async with httpx.AsyncClient(transport=t, base_url="http://t") as c: + out = {} + for p in ("/", "/api/health"): + r = await c.get(p) + out[p] = {k: r.headers.get(k) for k in ("content-security-policy", "x-frame-options", + "content-security-policy-report-only")} + print(json.dumps(out)) + +asyncio.run(main()) +""" + + +def test_main_app_reads_the_whitelist_and_hashes_the_page(dist: Path, tmp_path: Path) -> None: + """真实的 app.main:环境变量里的白名单生效、不发 XFO;托管页面时 index.html 带上报策略。settings、app 都是模块级 + 单例,起一个子进程导入。""" + env = {**os.environ, "AGENTLAB_DATA_DIR": str(tmp_path / "data"), "AGENTLAB_WEB_DIST": str(dist), + "AGENTLAB_SECRET_KEY": "test-only-not-a-real-key", "AGENTLAB_FRAME_ANCESTORS": "https://portal.example.com"} + proc = subprocess.run([sys.executable, "-c", _PROBE], cwd=BACKEND_DIR, env=env, capture_output=True, text=True, + timeout=120) + assert proc.returncode == 0, proc.stderr[-2000:] + out = json.loads(proc.stdout.strip().splitlines()[-1]) + for path in ("/", "/api/health"): + assert out[path]["content-security-policy"] == "frame-ancestors 'self' https://portal.example.com", path + assert out[path]["x-frame-options"] is None, path + assert out["/"]["content-security-policy-report-only"] == f"script-src 'self' 'sha256-{HASH}'" + assert out["/api/health"]["content-security-policy-report-only"] is None diff --git a/deploy/agentlab.env b/deploy/agentlab.env index 15b615d8..3a411c0b 100644 --- a/deploy/agentlab.env +++ b/deploy/agentlab.env @@ -31,6 +31,17 @@ BIND_ADDR=0.0.0.0 # 会话 cookie 是否带 Secure:留空按请求是不是 https 决定;反向代理终结了 https 时填 true # AGENTLAB_AUTH_COOKIE_SECURE= +# ---- 嵌入(可选)---- +# 默认只有 AgentLab 自己能把页面放进 iframe(响应头 Content-Security-Policy: frame-ancestors 'self',另加 +# X-Frame-Options: SAMEORIGIN),别的站点嵌进去会被浏览器拦下,防点击劫持。HSTS 不在这里加,交给终结 https 的反向代理。 +# 同站的门户(和 AgentLab 在同一个可注册域名下,比如 portal.example.internal 和 agentlab.example.internal)要嵌整站时, +# 把门户的地址写在下面,逗号分隔,只写 协议://主机[:端口],主机可以写 *.example.internal。填了之后只发 +# frame-ancestors、不再发 X-Frame-Options。登录用的 cookie 只随同站的请求带上,跨站的门户嵌整站登录不了。 +# 写错了(带路径、没写协议、只写 *)服务启动时报错。 +# AGENTLAB_FRAME_ANCESTORS=https://portal.example.internal +# 分享页(/s)允许被哪些站点嵌,写法同上。分享页只认这一项、不认上面那一项。分享链接还没有上线,现在填了不起作用 +# AGENTLAB_EMBED_ORIGINS=https://bi.example.internal + # ---- 数据 ---- # 数据目录:数据库、执行断点、上传的文件、沙箱工作区,还有加密密钥 .secret_key 都在这里。 # 要备份的就是这个目录(丢了 .secret_key,存进去的 API Key 就解不开了)。