--- title: "Poświadczenia — Architektura techniczna, model zagrożeń, szczegóły protokołu" description: "Jak proxy poświadczeń Clavitor działa na poziomie protokołu. MITM TLS, cykl życia poświadczeń, kody błędów, ochrona SSRF i czego nie chroni." lang: pl url: https://clavitor.ai/pl/proxy-technical markdown: https://clavitor.ai/pl/proxy-technical.md translation_of: https://clavitor.ai/en/proxy-technical.md authoritative: false publisher: Clavitor LLC --- > This is the Polish translation of [Credential Proxy Technical — Architecture, threat model, protocol details](https://clavitor.ai/en/proxy-technical.md). The original English text is authoritative; where the two differ, the English version prevails. # 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. ## Credential lifecycle 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ń. ## Agent identity 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. ## Field-to-header mapping 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 ` | | `x-api-key`, `api-key` | `X-API-Key: ` | | `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. ## Error codes 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. ### Skompromitowany host 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. ### Wyciek poświadczeń przez odpowiedź API 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](https://wazero.io), 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. ## Configuration 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ć. [Zgłoś znalezisko](mailto:security@clavitor.ai) [← Przegląd biznesowy](https://clavitor.ai/pl/proxy)