Proxy poświadczeń — techniczne
Jak działa proxy.
Przed czym chroni. Czego nie chroni.
Ta strona jest przeznaczona dla recenzentów bezpieczeństwa, testerów penetracyjnych i inżynierów oceniających model zagrożeń proxy. Opisuje, co proxy robi na poziomie protokołu, gdzie poświadczenia znajdują się w pamięci i jakie powierzchnie ataku pozostają.
Architektura
Proxy jest proxy HTTPS MITM opartym na CONNECT. Agent AI ustawia HTTPS_PROXY, aby wskazywał na nie. Kiedy agent wykonuje żądanie HTTPS, proxy przechwytuje połączenie TLS, sprawdza nagłówki żądania pod kątem odniesień do poświadczeń, rozwiązuje je w sejfie Clavitor i przekazuje żądanie z wstrzykniętymi poświadczeniami do interfejsu API wyższego poziomu.
Proxy nasłuchuje domyślnie na 127.0.0.1:1983 — wzorzec sidecar, gdzie proxy i agent współdzielą hosta. W przypadku wdrożeń współdzielonych (jedno proxy obsługujące wielu agentów w sieci prywatnej, sidecar kontenera dla wielu obciążeń, dedykowany host proxy), interfejs nasłuchu jest konfigurowalny za pomocą CLAVITOR_PROXY_LISTEN.
Proxy to samodzielny plik binarny Go. Bez CGO. Cała kryptografia protokołu Clavitor przechodzi przez kanoniczną implementację Rust skompilowaną do WebAssembly i ładowaną za pomocą wazero przy starcie.
Obsługa TLS
Proxy generuje samopodpisany główny urząd certyfikacji ECDSA P-256 przy pierwszym uruchomieniu, utrwalony w katalogu pliku binarnego z uprawnieniem 0600. Dla każdego hosta wyższego poziomu, certyfikat liścia jest wydawany na żądanie, podpisany przez ten urząd certyfikacji i buforowany w pamięci z ograniczonym usuwaniem (1000 hostów). Certyfikaty liści są ważne przez 24 godziny i są odnawiane w sposób przezroczysty w 23. godzinie, aby zapobiec wygaśnięciu w trakcie sesji.
Agent musi ufać certyfikatowi urzędu certyfikacji proxy. Wyeksportuj go za pomocą clavitor-proxy ca.
Połączenia wyższego poziomu używają minimum TLS 1.3 z negocjacją ALPN dla HTTP/2 i HTTP/1.1. Pula certyfikatów systemowych jest używana do weryfikacji wyższego poziomu. Brak przypinania certyfikatów — proxy ufa temu, czemu ufa system operacyjny.
Poświadczenia nigdy nie są buforowane, nigdy nie są zapisywane na dysku i nigdy nie są przechowywane dłużej niż jedno żądanie HTTP.
| Faza | Gdzie znajdują się poświadczenia | Czas trwania |
|---|---|---|
| W spoczynku w sejfie | Szyfrogram AES-GCM w bazie danych sejfu | Do momentu usunięcia |
| W tranzycie do proxy | Szyfrowany TLS JSON z interfejsu API sejfu | Jedna runda HTTP |
| Odszyfrowane w proxy | Pamięć procesu (ciąg Go na stercie) | Jedno żądanie HTTP |
| Wstrzyknięte do żądania wyższego poziomu | Szyfrowane TLS bajty w transmisji do wyższego poziomu | Jedno żądanie HTTP |
Proxy przechowuje klucz deszyfrujący poświadczenia agenta (16 bajtów) w pamięci przez cały czas działania. Jest on ładowany z zaszyfrowanej konfiguracji sidecar (format CLV1) przy starcie i usuwany przy płynnym zamknięciu. Klucz nigdy nie opuszcza procesu.
Konfiguracja sidecar jest szyfrowana za pomocą AES-128-GCM i HMAC-SHA256 przy użyciu deterministycznych kluczy pochodzących ze statycznego ziarna. Jest to zaciemnianie, a nie poufność — granica bezpieczeństwa to uprawnienia do plików (0600) i posiadanie pliku. Format CLV1 jest współdzielony między proxy, CLI i rozszerzeniem przeglądarki.
Tryby rozwiązywania
Tryb 1 — jawny symbol zastępczy
Agent zawiera odniesienie clavitor://Entry/field w nagłówku żądania. Proxy wyszukuje wpis w sejfie według nazwy, pobiera go, deszyfruje nazwane pole i zastępuje symbol zastępczy rzeczywistą wartością.
Jeśli wyszukiwanie zwróci zero lub więcej niż jeden wynik, proxy zwraca 502 ze stabilnym kodem błędu. Symbol zastępczy nigdy nie jest usuwany i przekazywany w niezmienionej postaci.
Tryb 2 — dopasowanie adresu URL
Gdy symbol zastępczy nie jest obecny, proxy pyta sejf o wpisy, których pole URL pasuje do hosta wyższego poziomu. Jeśli istnieje dokładnie jedno dopasowanie z rozpoznawalnym kształtem pola, proxy automatycznie wstrzykuje poświadczenia.
Zero dopasowań → przekazanie (brak oczekiwania na poświadczenia). Wiele dopasowań → 502 z wskazówkami dotyczącymi rozstrzygania niejednoznaczności. Nieznany kształt pola → 502.
Drzewo decyzyjne jest deterministyczne: obecny symbol zastępczy → rozwiąż lub zakończ błędem. Brak symbolu zastępczego → dopasowanie adresu URL lub przekazanie. Nie ma cichej ścieżki awaryjnej, w której nieudane rozwiązanie powoduje wysłanie żądania do wyższego poziomu bez poświadczeń.
Domyślnie sejf widzi własny identyfikator agenta proxy przy każdym żądaniu. Limity szybkości, kontrole zakresu i wpisy audytu są przypisywane do proxy.
Gdy wielu agentów współdzieli jedną instancję proxy, symbol zastępczy może zawierać identyfikator agenta: clavitor://agentid@Entry/field. Proxy wysyła ten identyfikator agenta do sejfu, który stosuje zakresy i limity szybkości tego agenta oraz rejestruje dostęp przeciwko niemu. Identyfikator agenta to 32-znakowa wartość szesnastkowa widoczna na stronie szczegółów agenta w interfejsie użytkownika sejfu.
# Without agent ID — attributed to the proxy Authorization: Bearer clavitor://OpenAI/key # With agent ID — attributed to agent 0102030405060708090a0b0c0d0e0f10 Authorization: Bearer clavitor://0102030405060708090a0b0c0d0e0f10@OpenAI/key
| Wdrożenie | Model tożsamości | Izolacja |
|---|---|---|
| Jedno proxy na agenta | ID proxy = ID agenta (domyślnie) | Pełne — oddzielny plik binarny, konfiguracja, zakres, limity szybkości |
| Współdzielone proxy, brak identyfikatora agenta w adresie URL | Wszyscy agenci współdzielą ID proxy | Współdzielony zakres i limity szybkości |
Współdzielone proxy + agentid@ w adresie URL | Tożsamość na agenta | Zakres, limity szybkości i audyt na agenta |
Identyfikator agenta w adresie URL nie jest mechanizmem uwierzytelniania — token CVT proxy uwierzytelnia połączenie. Identyfikator agenta określa przypisanie: czyje zakresy mają zastosowanie, czyje limity szybkości są liczone, czyj ślad audytu rejestruje dostęp. Sejf odrzuca nieznane identyfikatory agentów z głośnym błędem.
Bezpieczeństwo sieci
Ochrona SSRF
Domyślnie proxy blokuje połączenia wyższego poziomu do sieci prywatnych (RFC 1918), metadanych instancji chmury (169.254.169.254), pętli zwrotnej, sieci lokalnych i zakresów NAT klasy operatora. DNS jest rozwiązywany jako pierwszy; wszystkie zwrócone adresy IP są walidowane przed nawiązaniem połączenia TCP, zamykając okno TOCTOU ponownego wiązania DNS.
Nadpisz za pomocą CLAVITOR_PROXY_ALLOW_PRIVATE=true dla agentów, którzy legalnie uzyskują dostęp do prywatnych interfejsów API.
Przypinanie celu
Cel CONNECT jest przechwytywany podczas nawiązywania tunelu i używany przez cały czas trwania tunelu. Kolejne żądania w tunelu nie mogą przekierowywać do innego hosta poprzez manipulowanie nagłówkiem Host. Niezgodność skutkuje 502.
Zapobiega to sytuacji, w której agent nawiązuje tunel do api.openai.com, a następnie wysyła żądania do internal-service.corp.
Obsługa nagłówków
Nagłówki hop-by-hop są usuwane z żądań i odpowiedzi zgodnie z RFC 7230 §6.1: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.
Set-Cookie jest usuwany z odpowiedzi wyższego poziomu, aby zapobiec umieszczaniu plików cookie przez serwisy wyższego poziomu w kliencie HTTP agenta.
Treści żądań i odpowiedzi są przesyłane strumieniowo bez buforowania. Treści żądań są domyślnie ograniczone do 64 MB (CLAVITOR_PROXY_MAX_BODY_MB). Treści odpowiedzi są przesyłane strumieniowo bez twardego limitu; ostrzeżenie w dzienniku jest emitowane, gdy Content-Length przekroczy 100 MB.
W trybie dopasowania adresu URL proxy mapuje etykiety pól sejfu na nagłówki HTTP:
| Etykieta pola | Wstrzyknięty nagłówek |
|---|---|
key, apikey, api_key, token, secret, bearer, access_token | Authorization: Bearer <value> |
x-api-key, api-key | X-API-Key: <value> |
username + password (sparowane) | Authorization: Basic base64(user:pass) |
| Cokolwiek innego | Odrzucone — ERR-PROXY-052 |
W trybie symbolu zastępczego agent kontroluje, które pole jest rozwiązywane i dokąd trafia. Powyższe mapowanie dotyczy tylko trybu dopasowania adresu URL.
Każda awaria generuje stabilny kod ERR-PROXY-NNN. Kody te są częścią publicznego interfejsu proxy — agenci i operatorzy mogą je dopasowywać do alertów i debugowania.
| Zakres | Kategoria |
|---|---|
001–019 | Konfiguracja (konfiguracja, inicjalizacja, generowanie urzędu certyfikacji, WASM) |
020–029 | Cykl życia demona |
030–049 | Rozwiązywanie symboli zastępczych (adresy URI clavitor://) |
050–069 | Wstrzykiwanie dopasowania adresu URL |
070–089 | Poziom wyższy / TLS |
Pola tożsamości są niedostępne
Wpisy sejfu obsługują trzy poziomy szyfrowania. Pola objęte Szyfrowaniem sejfu to metadane w postaci zwykłego tekstu. Pola objęte Szyfrowaniem poświadczeń są deszyfrowane kluczem agenta. Pola tożsamości objęte Szyfrowaniem tożsamości są szyfrowane kluczem, którego serwer i proxy nigdy nie widziały. Tylko właściciel sejfu, za pomocą swojego klucza sprzętowego, może je odszyfrować.
Jeśli symbol zastępczy odnosi się do pola tożsamości objętego Szyfrowaniem tożsamości, proxy zwraca ERR-PROXY-035. Brak awaryjnego powrotu, brak częściowego wyniku. Pole jest architektonicznie niedostępne z poziomu proxy.
Czego proxy nie chroni
Model zagrożeń proxy to skompromitowana umiejętność lub wstrzyknięcie promptu, które skłania uwierzytelnionego agenta do pozyskiwania danych uwierzytelniających. Głównymi zabezpieczeniami są limity szybkości per agent w vaulcie, limity unikalnych wpisów oraz blokada po dwóch naruszeniach. Proxy dodaje punkt egzekwowania na poziomie sieci, w którym dane uwierzytelniające są rozwiązywane per żądanie i nigdy nie są przechowywane przez agenta.
Proxy działa na tej samej maszynie co agent. Atakujący z dostępem root może odczytać pamięć procesu, podłączyć debuger lub przechwycić ruch pętli zwrotnej. Proxy jest warstwą wstrzykiwania poświadczeń, a nie granicą bezpieczeństwa sprzętowego.
Jeśli interfejs API wyższego poziomu odbija poświadczenia w swojej odpowiedzi (np. punkt końcowy "whoami"), agent je widzi. Proxy wstrzykuje poświadczenia do żądań, a nie odpowiedzi. Nie filtruje tego, co wraca.
Logowanie
Proxy loguje jedną linię na zaakceptowane połączenie CONNECT i emituje linie błędów dla awarii. Nigdy nie loguje:
- Odszyfrowane wartości poświadczeń
- Pełne adresy URL żądań (ciągi zapytania mogą zawierać sekrety — logowany jest tylko schemat + host + ścieżka)
- Treści żądań lub odpowiedzi
- Klucz deszyfrujący poświadczenia lub zawartość konfiguracji sidecar
Kiedy proxy wykryje, że odpowiedź 400 od serwisu wyższego poziomu zawiera słowa kluczowe związane z uwierzytelnianiem (unauthorized, invalid token itp.), loguje podpowiedź diagnostyczną sugerującą, że wstrzyknięte poświadczenie może być nieaktualne. Odpowiedź jest przekazywana niezmieniona.
Kryptografia
Cała kryptografia protokołu Clavitor — deszyfrowanie pól AES-GCM, wyprowadzanie kluczy HKDF, kodowanie base62, generowanie tokenów CVT, pakowanie/rozpakowywanie konfiguracji CLV1 — wykonuje się w pojedynczym module WebAssembly (clavis_crypto.wasm) ładowanym przez wazero, czysty runtime WASM w Go. Bez CGO. Bez reimplementacji prymitywów Clavitor w Go.
Moduł WASM jest kompilowany z tej samej skrzynki Rust (clavis-crypto), której używa przeglądarka, CLI i rozszerzenia przeglądarki. Jedno źródło prawdy, jeden plik binarny, jedna powierzchnia audytu.
Proxy używa crypto/tls Go do obsługi TLS w transmisji i crypto/ecdsa do generowania certyfikatów MITM. Są to kwestie transportowe, a nie operacje protokołu Clavitor.
Sekrety (klucz deszyfrujący poświadczenia, identyfikator agenta, identyfikator urządzenia, adres URL sejfu) znajdują się w zaszyfrowanej konfiguracji sidecar CLV1, zapisanej raz podczas clavitor-proxy init. Pokrętła operacyjne znajdują się w zmiennych środowiskowych:
| Zmienna | Domyślnie | Cel |
|---|---|---|
CLAVITOR_PROXY_LISTEN | 127.0.0.1 | Interfejs nasłuchu. Ustaw na 0.0.0.0 dla wdrożeń współdzielonych lub na konkretny adres IP interfejsu. |
CLAVITOR_PROXY_PORT | 1983 | Port nasłuchu |
CLAVITOR_PROXY_ALLOW_PRIVATE | false | Zezwalaj na połączenia do sieci RFC-1918 / prywatnych |
CLAVITOR_PROXY_MAX_BODY_MB | 64 | Limit rozmiaru treści żądania |
CLAVITOR_PROXY_WRITE_TIMEOUT | 300 | Czas oczekiwania na zapis odpowiedzi w sekundach |
CLAVITOR_CONFIG | (katalog wykonywalny) | Nadpisz ścieżkę konfiguracji sidecar |
Pokrętła operacyjne nie są sekretami. Nie należą do zaszyfrowanej konfiguracji. Należą tam, gdzie narzędzia wdrożeniowe już nimi zarządzają — do środowiska.
Przejrzyj to samodzielnie.
Kryptografia to pojedynczy artefakt WASM nadający się do audytu. Model zagrożeń jest udokumentowany. Jeśli znajdziesz coś, co przeoczyliśmy, chcemy o tym usłyszeć.