0016. Bỏ Proxy xác thực - một bề mặt bí mật, một cơ chế tiêm token

Trạng thái: Đã chấp nhận Ngày: 2026-07-13

Thay thế ADR-0011 §6 (Thông tin xác thực docker headless Proxy) và ADR-0012 §10 (cơ chế tiêm hai cho một SANDBOX_GIT_TOKEN). Nó giữ lại mọi thứ khác trong cả hai: CommandExecutor đường may chạy và SANDBOX_MODE bảo vệ khởi động (0011 §1), an toàn phát lại (0011 §5), thang cách ly (0011 §7) và toàn bộ thiết kế Không gian làm việc biệt lập (0012 §§1–9). Nó được xây dựng trực tiếp trên ADR-0015, điều này đã được thực hiện Settings đĩa đơn bề mặt cấu hình

Bối cảnh

decode đã đưa ra hai câu trả lời cho "làm thế nào để một bí mật đến được nơi cần thiết" và đến ADR-0015 họ đã có đã không còn là hai vấn đề:

1. Cấu hình hydrat hóa — .env tại DECODE_ENV=local, Nhóm Môi trường (decode-<env>) ở trên nó. Một bề mặt, Settings, hai cơ chế tiêm (ADR-0015).
2. Proxy thông tin xác thực (ADR-0011 §6) — vùng chứa mitmproxy trên mạng docker mỗi lần chạy. các hộp cát Worker đã được chỉ vào nó thông qua http_proxy/https_proxy; bản đồ thông tin xác thực đã giải quyết chỉ sống trong env của proxy; tiện ích bổ sung đã đính kèm tiêu đề xác thực sau khi yêu cầu rời khỏi công nhân không có token. Điểm này là một thuộc tính thực: quá trình chạy các lệnh do mô hình chọn giữ không có bí mật.

Proxy đã phân phối thuộc tính đó và đó là một thiết kế thực sự thú vị. Nhưng nó đã mua nó với giá giá tiếp tục tăng và giá hiện tại rõ ràng không tương xứng với những gì nó bảo vệ:

• Nó chỉ hoạt động ở một trong ba chế độ hộp cát. headless + docker chỉ. modal — cái từ xa phụ trợ, nơi mà sự cô lập thực sự quan trọng nhất - chưa bao giờ có: ADR-0012 §10 tiêm trực tiếp SANDBOX_GIT_TOKEN vào env hộp cát Modal thông qua modal.Secret, bởi vì có không có mạng docker để treo container mitmproxy. Vì vậy, bất biến "công nhân không có token" là đã false theo phương thức và cơ sở mã có một ngoại lệ được ghi lại nói như vậy.
• Hai cơ chế cho một núm. Tóm tắt riêng của ADR-0012 §10 — "một SANDBOX_GIT_TOKEN, hai mũi tiêm cơ chế" — là mùi. Nút xoay tương tự hướng tới người dùng hoạt động khác nhau tùy thuộc vào phần phụ trợ người dùng đã không chọn vì lý do bảo mật.
• Máy móc lớn và chịu tải không đúng chỗ. Mạng docker mỗi lần chạy; một CA được tạo, gắn kết và xếp vào kho tin cậy của công nhân đồng bộ trước lần đầu tiên bash (một cuộc đua cần bài kiểm tra hồi quy riêng); một lệnh xé bỏ phải gặt người công nhân trước proxy hoặc docker network rm thất bại; một apt cài đặt phải thoát thông qua proxy; và một token mồi (decode-proxy-injects-the-real-token) được trồng trong môi trường của công nhân hoàn toàn vì gh từ chối đưa ra bất kỳ yêu cầu nào mà không có token nào cả. Mỗi một trong số đó là một thứ bị phá vỡ.
• Nó chưa bao giờ là rào cản thoát nước. Lối ra là hợp tác: công nhân chỉ vào proxy theo quy ước (http_proxy env vars mà các thư viện khách hoạt động tốt tôn vinh). Một mô hình mà muốn bỏ qua nó curl --noproxy '*'. Proxy được bảo vệ chống lại một mô hình đọc mô hình của chính nó môi trường, không chống lại mô hình có nghĩa là gây hại - và mô hình có nghĩa là gây hại là mối đe dọa duy nhất mô hình trong đó "công nhân không thể đọc token" có giá trị lớn như vậy.
• Thứ mà nó bảo vệ là một PAT có phạm vi, có thể thu hồi mà người dùng đã chọn giao cho agent để nó có thể đẩy một chi nhánh và mở một PR. Nó không phải là thông tin xác thực cơ sở dữ liệu sản xuất.

Trong khi đó, thuộc tính thực sự quan trọng — bí mật không bao giờ chạm đến ngữ cảnh của mô hình — thì không đều được cung cấp bởi proxy. Nó được cung cấp bởi Settings không bao giờ được tuần tự hóa thành một dấu nhắc, bởi SecretStrvà bởi bản đồ thông tin xác thực không bao giờ được ghi lại. Tất cả đều tồn tại ADR này mà không bị ảnh hưởng.

Quyết định

1. Xóa Proxy thông tin xác thực. sandbox/proxy.py (SandboxProxyRule, DEFAULT_PROXY_RULES, github_token_rules, build_credential_map, DockerCredentialProxy) và sandbox/proxy_addon.py được loại bỏ, cùng với runtime/flow.py's _sandbox_proxy trình quản lý bối cảnh và mọi phần của nối dây proxy vào DockerBackend (mạng, proxy_env, ngàm CA, _trust_proxy_ca, và token mồi nhử). Cài đặt sandbox_credential_proxy_enabled và sandbox_proxy_image bị xóa - nghỉ sạch, không có vấn đề, không có cảnh báo không dùng nữa: một khóa đã ngừng hoạt động trong một .env đơn giản là bị bỏ qua (extra="ignore"), chính xác như ADR-0015 §9 xử lý các núm đã ngừng hoạt động của chính nó.

2. SANDBOX_GIT_TOKEN được đưa trực tiếp vào Worker env — trong cả hai chương trình phụ trợ. Docker áp dụng những gì Modal đã làm (ADR-0012 §10): khi trường được đặt, token sẽ nhập vào vùng chứa env dưới dạng GITHUB_TOKEN, cộng với cùng một trình trợ giúp thông tin git (x-access-token:$GITHUB_TOKEN) vậy git push qua HTTPS hoạt động và gh xác thực tắt nó. Một cơ chế, hai phụ trợ, hành vi đối xứng. Trống/không đặt → không có token trong env, không có trình trợ giúp thông tin xác thực và quá trình chạy vùng chứa giống hệt byte với trường hợp không có token. none chế độ không bị ảnh hưởng (nó là máy chủ).

3. Bất biến được viết lại, không bị loại bỏ một cách lặng lẽ. Dòng AGENTS.md cũ — "Bí mật không bao giờ đến được mô hình hoặc tải trọng hộp cát" — vốn chỉ đúng trong docker. Đó là được thay thế bằng cặp thống nhất, trung thực:

   • Bí mật không bao giờ chạm tới bối cảnh của model. Settings không bao giờ được tuần tự hóa thành một dấu nhắc; bí mật là SecretStr; các dòng nhật ký mang tên, không bao giờ có giá trị. Điều này đúng ở mọi chế độ.
   • Hộp cát nhận chính xác thông tin xác thực mà người dùng cấp cho nó — không còn nữa. Ngày nay, đó là SANDBOX_GIT_TOKEN và không có gì khác. Thùng Môi trường cung cấp nước cho harness Settings; nó không bao giờ được đổ vào môi trường công nhân. Một quy trình hộp cát có thể đọc $GITHUB_TOKEN, và người dùng là đã nói rất rõ ràng: hãy trao cho nó một PAT có phạm vi, có thể thu hồi.

4. Việc trao tay vẫn ở phía máy chủ và giữ nguyên mặc định. sandbox/handback.py không bị ảnh hưởng: nó đẩy Không gian làm việc cuối cùng cho decode/<session-id> Nhánh phiên có tín dụng git máy chủ xung quanh, đang chạy mọi lệnh git phía máy chủ chống lại .decode/sandbox. Không có thông tin xác thực nào được đưa vào hộp cát cho hand-back - điều đó đúng trước ADR này và đúng sau ADR. SANDBOX_GIT_TOKEN còn lại chọn tham gia và chỉ cần thiết cho yêu cầu lớn hơn: để chính mô hình chạy git push / gh pr create từ bên trong hộp cát. Để nó không được đặt và hộp cát không có thông tin xác thực cả.

   Sửa đổi (2026-07, lần chạy từ xa đầu tiên). Một thùng chứa luồng headless không có git xung quanh hoàn toàn không có thông tin xác thực, do đó, "chỉ tín dụng xung quanh" đã khiến việc trao lại được đảm bảo là không hoạt động ở đó. sự đẩy bây giờ sử dụng SANDBOX_GIT_TOKEN khi được đặt, thông qua trình trợ giúp thông tin giống mà Công nhân nhận được — chạy trong quy trình khai thác (bộ chứa luồng), với token được truyền qua môi trường và không bao giờ vào một dòng lệnh. Đặc tính chịu tải không thay đổi và vẫn giữ nguyên ở mọi chế độ: không có thông tin xác thực nào được đặt bên trong hộp cát để gửi lại. token được chọn tham gia như trước; bỏ đặt nó và cú thuận tay của một cuộc chạy headless đơn giản là không thể đẩy được (nó nói như vậy và đặt tên cho nhánh mà nó để lại phía sau). Xem bản sửa đổi của ADR-0012 §8 để biết nơi thực hiện chuyển giao.

5. Không mục tiêu: thay thế. Không có danh sách cho phép đi ra, không có proxy được xây dựng lại phía sau cờ, không có "thông tin xác thực dịch vụ môi giới”. Nếu một bước trong tương lai cần một nhân viên trong hộp cát gọi API bên thứ ba mà không cần đang giữ chìa khóa của nó, đó là một ADR mới với trường hợp sử dụng thực sự đằng sau nó - không còn một cái móc treo lơ lửng ở đây. Xây dựng lại cái này git revert đi xa; thiết kế được ghi lại ở trên và trong ADR-0011 §6.

Sơ đồ

graph LR
    subgraph BEFORE["BEFORE — two mechanisms, one property, one backend"]
        direction TB
        B_S["Settings<br/>(sandbox_git_token)"]
        B_P["mitmproxy container<br/>holds the credential map"]
        B_W["docker Worker<br/>TOKEN-FREE<br/>(+ decoy for gh)"]
        B_M["modal Worker<br/>HOLDS THE TOKEN<br/>(the documented exception)"]
        B_G["api.github.com"]
        B_S -->|"resolve rules host-side"| B_P
        B_W -->|"http_proxy — cooperative"| B_P
        B_P -->|"inject header after egress"| B_G
        B_S -->|"modal.Secret — direct"| B_M
        B_M --> B_G
    end

    subgraph AFTER["AFTER — one mechanism, both backends"]
        direction TB
        A_E[".env  |  Environment Bucket"]
        A_S["Settings<br/>(sandbox_git_token)"]
        A_W["Worker — docker OR modal<br/>GITHUB_TOKEN in env<br/>+ credential helper"]
        A_G["api.github.com"]
        A_H["Hand-back — HOST side<br/>ambient git creds<br/>NO credential in the sandbox"]
        A_E -->|"DECODE_ENV"| A_S
        A_S -->|"direct-inject, opt-in"| A_W
        A_W --> A_G
        A_S -.->|"never poured into the worker"| A_H
        A_H --> A_G
    end

    style BEFORE fill:#3a2a2a,stroke:#c76a6a,color:#f0e0e0
    style AFTER fill:#22332a,stroke:#5fbf7f,color:#e0f0e4
    style B_P fill:#5a3030,stroke:#c76a6a,color:#fff
    style B_W fill:#4a3a2a,stroke:#c79a5a,color:#fff
    style B_M fill:#5a3030,stroke:#c76a6a,color:#fff
    style A_S fill:#2a4a5a,stroke:#5a9fc7,color:#fff
    style A_W fill:#2f5a3f,stroke:#5fbf7f,color:#fff
    style A_H fill:#2f5a3f,stroke:#5fbf7f,color:#fff

hậu quả

Tốt.

• Một cơ chế, hai phụ trợ. SANDBOX_GIT_TOKEN bây giờ có nghĩa giống nhau ở mọi nơi, và Mục nhập Công nhân của bảng thuật ngữ mất cảnh báo "chọn tham gia ngoại lệ" vì ngoại lệ là quy tắc.
• Một lượng lớn máy móc mỏng manh đã biến mất: mạng mỗi lần chạy, cuộc đua tin cậy CA và các kiểm tra hồi quy, ràng buộc thứ tự phân tách, apt-through-the-proxy và token mồi nhử. DockerBackend's docker run argv bây giờ là một hình chứ không phải hai.
• Câu chuyện bảo mật giờ đây đúng như đã viết, đáng giá hơn một câu chuyện mạnh mẽ hơn đã có tài liệu lỗ trong đó.
• Bộ tích hợp docker mất tệp chậm nhất, dễ vỡ nhất (một vùng chứa mitmproxy thực sự cho mỗi lần kiểm tra).

Xấu / được chấp nhận.

• Một quy trình trong hộp cát hiện có thể đọc $GITHUB_TOKEN. Đây là toàn bộ chi phí, được nêu rõ ràng. Giảm nhẹ là chính sách, không phải mã: token được chọn tham gia, có phạm vi và có thể thu hồi và các tài liệu đều nói như vậy ở mỗi lần đề cập. Bất cứ ai muốn tài sản mạnh hơn đều chạy mà không cần SANDBOX_GIT_TOKEN và nhận lại sự hỗ trợ từ phía máy chủ.
• Bước giảng dạy đã ngừng hoạt động. Proxy thông tin xác thực là minh chứng rõ ràng cho tiêu đề sau khi xuất ra tiêm và khóa học sẽ mất nó dưới dạng mã đang chạy. Thiết kế tồn tại ở đây và trong ADR-0011 §6, và cặp ADR hiện dạy một điều được cho là hữu ích hơn: cách nhận biết một cơ chế có chi phí phát triển nhanh hơn tài sản mà nó mua và cách loại bỏ nó mà không giả vờ không bao giờ là một ý tưởng hay.
• Không có đường dẫn cho thông tin xác thực API của bên thứ ba trong hộp cát. DEFAULT_PROXY_RULES là tướng quân điểm mở rộng ("bất kỳ máy chủ nào khác") và nó đã biến mất. Nó được vận chuyển trống rỗng và không có người gọi thứ hai - mỗi AGENTS.md, đó chính xác là sự trừu tượng chưa tồn tại. Khi trường hợp sử dụng thứ hai thực sự đến nơi nó kiếm được ADR của riêng mình.