Merge pull request #700 from NA-Wen/codex/secure-local-tool-upload

fix: secure local tool installation
This commit is contained in:
Yufan Dang 2026-10-30 13:36:20 +01:00 committed by GitHub
commit ad8461b88c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 243 additions and 32 deletions

View File

@ -74,7 +74,21 @@ nodes:
3. 若函数依赖额外第三方库,可在仓库 `requirements.txt`/`pyproject.toml` 中声明,或在函数内调用 `install_python_packages`(同目录提供)动态安装。
4. 运行 `python -m tools.export_design_template ...` 以刷新前端枚举。
## 6. 调试与排错
## 6. 本地 API 安装
后端和前端开发服务器默认仅监听 `127.0.0.1`。通过 API 上传工具时,先向
`GET /api/tools/local/session` 发送请求头 `X-ChatDev-Local: 1`,再将返回的
`token` 放入 `POST /api/tools/local` 的 `X-ChatDev-Tool-Token` 请求头。
前端可直接调用 `frontend/src/utils/apiFunctions.js` 中的 `uploadLocalTool()`,
它会自动完成这两个步骤,无需登录。令牌在后端进程重启后失效,不要记录或分享它。
两个接口均检查本地连接和 Host;浏览器 Origin 默认仅允许
`http://localhost:5173` 和 `http://127.0.0.1:5173`。更换前端端口时,
在后端通过 `CORS_ALLOW_ORIGINS` 配置完整来源地址(逗号分隔,不支持 `*`)。
上传的 Python 代码仍在服务器进程内执行,请仅安装自己信任的代码。
## 7. 调试与排错
- 若前端/CLI 报告 “function 'xxx' not found”,检查函数名称与文件是否位于 `MAC_FUNCTIONS_DIR`(默认 `functions/function_calling/`)。
- `function_catalog` 加载失败时,`FunctionToolEntryConfig.field_specs()` 会在描述中提示错误,请先修复函数语法或依赖。
- 工具运行超时会向 Agent 返回异常文本;可通过 `timeout` 扩大限额,或在函数内部自行捕获并返回友好错误。

View File

@ -1,6 +1,32 @@
const apiUrl = (path) => path
// Install trusted Python code using a process-local session token. Fetch a fresh
// token for each upload so backend restarts do not require a page refresh.
export async function uploadLocalTool(filename, content, overwrite = false) {
const session = await fetch(apiUrl('/api/tools/local/session'), {
headers: { 'X-ChatDev-Local': '1' },
cache: 'no-store',
})
if (!session.ok) {
throw new Error(`Local tool session failed: ${session.status}`)
}
const { token } = await session.json()
const response = await fetch(apiUrl('/api/tools/local'), {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-ChatDev-Tool-Token': token,
},
body: JSON.stringify({ filename, content, overwrite }),
})
const data = await response.json()
if (!response.ok) {
throw new Error(data.detail || `Tool upload failed: ${response.status}`)
}
return data
}
const addYamlSuffix = (filename) => {
const trimmed = (filename || '').trim()
if (!trimmed) {

View File

@ -9,7 +9,7 @@ export default defineConfig(({ mode }) => {
return {
plugins: [vue()],
server: {
host: true,
host: '127.0.0.1',
proxy: {
'/api': {
target: target,

View File

@ -1,7 +1,6 @@
"""Application bootstrap helpers for the FastAPI server."""
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from server import state
from server.config_schema_router import router as config_schema_router
@ -13,14 +12,6 @@ from utils.middleware import add_middleware
def init_app(app: FastAPI) -> None:
"""Apply shared middleware, routers, and global state to ``app``."""
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
add_exception_handlers(app)
add_middleware(app)

48
server/local_security.py Normal file
View File

@ -0,0 +1,48 @@
"""Access checks for installing trusted Python tools in the local app."""
import ipaddress
import os
import secrets
from fastapi import HTTPException, Request
_LOCAL_TOOL_TOKEN = secrets.token_urlsafe(32)
_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
def allowed_browser_origins() -> list[str]:
configured = os.getenv("CORS_ALLOW_ORIGINS")
if configured is not None:
# Wildcards must never authorize reading the local session token.
return [origin.strip() for origin in configured.split(",") if origin.strip() and origin.strip() != "*"]
return ["http://localhost:5173", "http://127.0.0.1:5173"]
def require_local_tool_access(request: Request) -> None:
try:
local_client = request.client is not None and ipaddress.ip_address(request.client.host).is_loopback
except ValueError:
local_client = False
# Check Host as well as the peer address to reject DNS rebinding.
if not local_client or request.url.hostname not in _LOCAL_HOSTS:
raise HTTPException(status_code=403, detail="Tool installation is only available locally")
origin = request.headers.get("origin")
if origin is not None and origin not in allowed_browser_origins():
raise HTTPException(status_code=403, detail="Browser origin is not allowed")
def local_tool_session(request: Request) -> dict[str, str]:
require_local_tool_access(request)
# A custom header prevents cross-origin simple requests from reading a token.
if request.headers.get("x-chatdev-local") != "1":
raise HTTPException(status_code=403, detail="Local session header is required")
return {"token": _LOCAL_TOOL_TOKEN}
def require_local_tool_token(request: Request) -> None:
require_local_tool_access(request)
token = request.headers.get("x-chatdev-tool-token", "")
if not secrets.compare_digest(token.encode("utf-8"), _LOCAL_TOOL_TOKEN.encode("utf-8")):
raise HTTPException(status_code=403, detail="Valid local tool token is required")

View File

@ -1,9 +1,10 @@
import re
from pathlib import Path
from fastapi import APIRouter, HTTPException
from fastapi import APIRouter, Depends, HTTPException, Request, Response
from pydantic import BaseModel, constr
from server.local_security import local_tool_session, require_local_tool_token
from utils.function_catalog import get_function_catalog
from utils.function_manager import FUNCTION_CALLING_DIR
@ -40,7 +41,13 @@ def list_local_tools():
}
@router.post("/api/tools/local")
@router.get("/api/tools/local/session")
def get_local_tool_session(request: Request, response: Response):
response.headers["Cache-Control"] = "no-store"
return local_tool_session(request)
@router.post("/api/tools/local", dependencies=[Depends(require_local_tool_token)])
def create_local_tool(payload: LocalToolCreateRequest):
raw_name = payload.filename.strip()
if not raw_name:

View File

@ -74,8 +74,8 @@ def build_parser() -> argparse.ArgumentParser:
parser.add_argument(
"--host",
type=str,
default="0.0.0.0",
help="Server host (default: 0.0.0.0)"
default="127.0.0.1",
help="Server host (default: 127.0.0.1)"
)
parser.add_argument(
"--port",

View File

@ -0,0 +1,137 @@
"""Exercise the actual upload route without importing the workflow runtime."""
import importlib.util
import sys
from pathlib import Path
import pytest
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.testclient import TestClient
from server.local_security import allowed_browser_origins
from utils.function_catalog import FunctionCatalog
@pytest.fixture
def local_tools(tmp_path, monkeypatch):
monkeypatch.delenv("CORS_ALLOW_ORIGINS", raising=False)
spec = importlib.util.spec_from_file_location(
"local_tools_under_test",
Path(__file__).resolve().parents[1] / "server/routes/tools.py",
)
routes = importlib.util.module_from_spec(spec)
monkeypatch.setitem(sys.modules, spec.name, routes)
spec.loader.exec_module(routes)
catalog = FunctionCatalog(tmp_path)
monkeypatch.setattr(routes, "FUNCTION_CALLING_DIR", tmp_path)
monkeypatch.setattr(routes, "get_function_catalog", lambda: catalog)
app = FastAPI()
app.include_router(routes.router)
app.add_middleware(
CORSMiddleware,
allow_origins=allowed_browser_origins(),
allow_methods=["*"],
allow_headers=["*"],
)
return app, tmp_path
def client_for(app, host="127.0.0.1"):
return TestClient(app, base_url="http://127.0.0.1:8000", client=(host, 12345))
def session_token(client):
response = client.get(
"/api/tools/local/session",
headers={"X-ChatDev-Local": "1", "Origin": "http://localhost:5173"},
)
assert response.status_code == 200
assert response.headers["cache-control"] == "no-store"
return response.json()["token"]
@pytest.mark.parametrize("token", [None, "incorrect", "非有效令牌"])
def test_unauthorized_upload_does_not_write_or_execute(local_tools, token):
app, directory = local_tools
headers = {} if token is None else {"X-ChatDev-Tool-Token": token.encode("utf-8")}
with client_for(app) as client:
response = client.post(
"/api/tools/local", headers=headers,
json={"filename": "probe.py", "content": "raise RuntimeError('must not execute')"},
)
assert response.status_code == 403
assert list(directory.iterdir()) == []
def test_authorized_upload_preserves_install_and_load(local_tools):
app, directory = local_tools
marker = directory / "executed.txt"
source = f"from pathlib import Path\nPath({str(marker)!r}).write_text('ok')\n"
with client_for(app) as client:
token = session_token(client)
response = client.post(
"/api/tools/local",
headers={"X-ChatDev-Tool-Token": token, "Origin": "http://localhost:5173"},
json={"filename": "probe.py", "content": source},
)
assert response.status_code == 200
assert (directory / "probe.py").read_text() == source
assert marker.read_text() == "ok"
@pytest.mark.parametrize("origin", ["https://evil.example", "null", "http://localhost:5174"])
def test_disallowed_origin_cannot_get_token_or_upload(local_tools, origin):
app, directory = local_tools
with client_for(app) as client:
token = session_token(client)
headers = {"Origin": origin, "X-ChatDev-Local": "1", "X-ChatDev-Tool-Token": token}
assert client.get("/api/tools/local/session", headers=headers).status_code == 403
response = client.post(
"/api/tools/local", headers=headers,
json={"filename": "probe", "content": "pass"},
)
assert response.status_code == 403
assert list(directory.iterdir()) == []
def test_session_requires_custom_header(local_tools):
app, _ = local_tools
with client_for(app) as client:
assert client.get("/api/tools/local/session").status_code == 403
@pytest.mark.parametrize("peer,host", [
("192.0.2.10", "127.0.0.1:8000"),
("127.0.0.1", "evil.example:8000"),
])
def test_remote_peer_and_rebinding_host_rejected_even_with_token(local_tools, peer, host):
app, directory = local_tools
with client_for(app) as local:
token = session_token(local)
with client_for(app, peer) as client:
headers = {"Host": host, "X-ChatDev-Local": "1", "X-ChatDev-Tool-Token": token}
assert client.get("/api/tools/local/session", headers=headers).status_code == 403
response = client.post(
"/api/tools/local", headers=headers,
json={"filename": "probe", "content": "pass"},
)
assert response.status_code == 403
assert list(directory.iterdir()) == []
def test_untrusted_browser_preflight_is_rejected(local_tools):
app, _ = local_tools
with client_for(app) as client:
response = client.options("/api/tools/local/session", headers={
"Origin": "https://evil.example",
"Access-Control-Request-Method": "GET",
"Access-Control-Request-Headers": "X-ChatDev-Local",
})
assert response.status_code == 400
assert "access-control-allow-origin" not in response.headers
def test_cors_wildcard_does_not_authorize_token_access(monkeypatch):
monkeypatch.setenv("CORS_ALLOW_ORIGINS", "*,http://localhost:5173")
assert allowed_browser_origins() == ["http://localhost:5173"]

View File

@ -115,6 +115,9 @@ class TestBuildReloadKwargs:
class TestParserFlags:
def test_default_host_is_loopback(self, server_main):
assert server_main.build_parser().parse_args([]).host == "127.0.0.1"
def test_reload_dir_is_repeatable(self, server_main):
parser = server_main.build_parser()
args = parser.parse_args(["--reload", "--reload-dir", "a", "--reload-dir", "b"])

View File

@ -7,10 +7,10 @@ from fastapi.responses import JSONResponse
from fastapi.middleware.cors import CORSMiddleware
import time
import re
import os
from utils.structured_logger import get_server_logger, LogType
from utils.exceptions import SecurityError
from server.local_security import allowed_browser_origins
async def correlation_id_middleware(request: Request, call_next: Callable):
@ -89,24 +89,9 @@ async def rate_limit_middleware(request: Request, call_next: Callable):
def add_cors_middleware(app: FastAPI) -> None:
"""Configure and attach CORS middleware."""
# Dev defaults; override via CORS_ALLOW_ORIGINS (comma-separated)
default_origins = [
"http://localhost:5173",
"http://127.0.0.1:5173",
]
env_origins = os.getenv("CORS_ALLOW_ORIGINS")
if env_origins:
origins = [o.strip() for o in env_origins.split(",") if o.strip()]
origin_regex = None
else:
origins = default_origins
# Helpful in dev: allow localhost/127.0.0.1 on any port
origin_regex = r"^https?://(localhost|127\.0\.0\.1)(:\d+)?$"
app.add_middleware(
CORSMiddleware,
allow_origins=origins,
allow_origin_regex=origin_regex,
allow_origins=allowed_browser_origins(),
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],