Proxy kredensial — teknis
Cara kerja proxy.
Apa yang dilindunginya. Apa yang tidak.
Halaman ini ditujukan untuk peninjau keamanan, penguji penetrasi, dan insinyur yang mengevaluasi model ancaman proxy. Halaman ini menjelaskan apa yang dilakukan proxy pada tingkat protokol, di mana kredensial ada di memori, dan permukaan serangan apa yang tersisa.
Arsitektur
Proxy adalah proxy HTTPS MITM berbasis CONNECT. Agen AI mengatur HTTPS_PROXY untuk mengarah padanya. Ketika agen membuat permintaan HTTPS, proxy mencegat koneksi TLS, memeriksa header permintaan untuk referensi kredensial, menyelesaikannya terhadap brankas Clavitor, dan meneruskan permintaan dengan kredensial yang disuntikkan ke API hulu.
Proxy mendengarkan pada 127.0.0.1:1983 secara default — pola sidecar di mana proxy dan agen berbagi host. Untuk penyebaran bersama (satu proxy melayani banyak agen di jaringan pribadi, sidecar kontainer ke banyak beban kerja, host proxy khusus), antarmuka pendengar dapat dikonfigurasi melalui CLAVITOR_PROXY_LISTEN.
Proxy adalah biner Go mandiri. Tanpa CGO. Seluruh kriptografi protokol Clavitor diproses melalui implementasi Rust kanonik yang dikompilasi ke WebAssembly dan dimuat melalui wazero saat startup.
Penanganan TLS
Proxy menghasilkan CA root ECDSA P-256 yang ditandatangani sendiri saat pertama kali dijalankan, disimpan di direktori biner dengan mode 0600. Untuk setiap host hulu, sertifikat leaf diterbitkan sesuai permintaan, ditandatangani oleh CA ini, dan di-cache dalam memori dengan eviksi terbatas (1.000 host). Sertifikat leaf berlaku selama 24 jam dan dibuat ulang secara transparan pada jam ke-23 untuk mencegah kedaluwarsa di tengah sesi.
Agen harus mempercayai sertifikat CA proxy. Ekspor dengan clavitor-proxy ca.
Koneksi hulu menggunakan TLS 1.3 minimum dengan negosiasi ALPN untuk HTTP/2 dan HTTP/1.1. Kumpulan sertifikat sistem digunakan untuk verifikasi hulu. Tidak ada penyematan sertifikat — proxy mempercayai apa pun yang dipercayai OS.
Kredensial tidak pernah di-cache, tidak pernah ditulis ke disk, dan tidak pernah disimpan lebih lama dari satu permintaan HTTP.
| Fase | Di mana kredensial berada | Durasi |
|---|---|---|
| Saat diam di brankas | Ciphertext AES-GCM di database brankas | Hingga dihapus |
| Dalam transit ke proxy | Respons JSON terenkripsi TLS dari API brankas | Satu putaran HTTP |
| Didekripsi di proxy | Memori proses (string Go di heap) | Satu permintaan HTTP |
| Disuntikkan ke dalam permintaan hulu | Byte terenkripsi TLS di jalur ke hulu | Satu permintaan HTTP |
Proxy menyimpan kunci dekripsi kredensial agen (16 byte) dalam memori selama seluruh waktu berjalan. Kunci dimuat dari konfigurasi sidecar terenkripsi (format CLV1) saat startup dan dihapus saat shutdown yang terkendali. Kunci tidak pernah meninggalkan proses.
Konfigurasi sidecar dienkripsi dengan AES-128-GCM dan HMAC-SHA256 menggunakan kunci deterministik yang diturunkan dari seed statis. Ini adalah obfuskasi, bukan kerahasiaan — batas keamanan adalah izin file (0600) dan kepemilikan file. Format CLV1 dibagikan antara proxy, CLI, dan ekstensi peramban.
Mode resolusi
Mode 1 — placeholder eksplisit
Agen menyertakan referensi clavitor://Entry/field dalam header permintaan. Proxy mencari entri di brankas berdasarkan nama, mengambilnya, mendekripsi bidang yang disebutkan, dan mengganti placeholder dengan nilai sebenarnya.
Jika pencarian mengembalikan nol atau lebih dari satu hasil, proxy mengembalikan 502 dengan kode kesalahan yang stabil. Placeholder tidak pernah dihapus dan diteruskan apa adanya.
Mode 2 — pencocokan URL
Ketika tidak ada placeholder, proxy meminta brankas untuk entri yang bidang URL-nya cocok dengan host hulu. Jika tepat satu kecocokan ada dengan bentuk bidang yang dikenali, proxy menyuntikkan kredensial secara otomatis.
Nol kecocokan → passthrough (tidak ada ekspektasi kredensial). Banyak kecocokan → 502 dengan panduan klarifikasi. Bentuk bidang tidak diketahui → 502.
Pohon keputusan bersifat deterministik: placeholder ada → selesaikan atau gagal. Tidak ada placeholder → pencocokan URL atau passthrough. Tidak ada jalur fallback tersembunyi di mana resolusi yang gagal menghasilkan permintaan yang diteruskan ke hulu tanpa kredensial.
Secara default, brankas melihat ID agen proxy sendiri pada setiap permintaan. Batas laju, pemeriksaan cakupan, dan entri audit dikaitkan dengan proxy.
Ketika banyak agen berbagi satu instance proxy, placeholder dapat menyertakan ID agen: clavitor://agentid@Entry/field. Proxy mengirimkan ID agen ini ke brankas, yang menerapkan cakupan agen tersebut dan batas laju serta mencatat akses terhadapnya. ID agen adalah nilai heksadesimal 32 karakter yang ditampilkan di halaman detail agen di UI brankas.
# 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
| Penyebaran | Model identitas | Isolasi |
|---|---|---|
| Satu proxy per agen | ID Proxy = ID agen (default) | Penuh — biner, konfigurasi, cakupan, batas laju terpisah |
| Proxy bersama, tanpa ID agen di URL | Semua agen berbagi ID proxy | Cakupan dan batas laju bersama |
Proxy bersama + agentid@ di URL | Identitas per agen | Cakupan, batas laju, dan audit per agen |
ID agen di URL bukanlah mekanisme otentikasi — token CVT proxy mengotentikasi koneksi. ID agen menentukan atribusi: cakupan siapa yang berlaku, batas laju siapa yang dihitung, jejak audit siapa yang mencatat akses. Brankas menolak ID agen yang tidak dikenal dengan kegagalan yang eksplisit.
Keamanan jaringan
Perlindungan SSRF
Secara default, proxy memblokir koneksi hulu ke jaringan pribadi (RFC 1918), metadata instance cloud (169.254.169.254), loopback, link-local, dan rentang NAT kelas operator. DNS diselesaikan terlebih dahulu; semua IP yang dikembalikan divalidasi sebelum koneksi TCP dibuat, menutup jendela TOCTOU rebinding DNS.
Timpa dengan CLAVITOR_PROXY_ALLOW_PRIVATE=true untuk agen yang sah mengakses API pribadi.
Penyematan target
Target CONNECT ditangkap saat pembentukan terowongan dan digunakan untuk seluruh masa pakai terowongan. Permintaan selanjutnya dalam terowongan tidak dapat mengalihkan ke host yang berbeda dengan memanipulasi header Host. Ketidakcocokan menghasilkan 502.
Ini mencegah agen membuat terowongan ke api.openai.com dan kemudian mengirim permintaan ke internal-service.corp.
Penanganan header
Header hop-by-hop dihapus dari permintaan dan respons sesuai RFC 7230 §6.1: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.
Set-Cookie dihapus dari respons hulu untuk mencegah hulu menanam cookie di klien HTTP agen.
Badan permintaan dan respons dialirkan tanpa buffering. Badan permintaan dibatasi hingga 64 MB secara default (CLAVITOR_PROXY_MAX_BODY_MB). Badan respons dialirkan tanpa batas keras; peringatan log dikeluarkan ketika Content-Length melebihi 100 MB.
Dalam mode pencocokan URL, proxy memetakan label bidang brankas ke header HTTP:
| Label bidang | Header yang disuntikkan |
|---|---|
key, apikey, api_key, token, secret, bearer, access_token | Authorization: Bearer <value> |
x-api-key, api-key | X-API-Key: <value> |
username + password (berpasangan) | Authorization: Basic base64(user:pass) |
| Apa pun yang lain | Ditolak — ERR-PROXY-052 |
Dalam mode placeholder, agen mengontrol bidang mana yang diselesaikan dan ke mana tujuannya. Pemetaan di atas hanya berlaku untuk mode pencocokan URL.
Setiap kegagalan menghasilkan kode ERR-PROXY-NNN yang stabil. Kode-kode ini adalah bagian dari antarmuka publik proxy — agen dan operator dapat mencocokkannya untuk peringatan dan debugging.
| Rentang | Kategori |
|---|---|
001–019 | Pengaturan (konfigurasi, inisialisasi, pembuatan CA, WASM) |
020–029 | Siklus hidup daemon |
030–049 | Resolusi placeholder (URI clavitor://) |
050–069 | Injeksi pencocokan URL |
070–089 | Hulu / TLS |
Bidang identitas tidak dapat dijangkau
Entri brankas mendukung tiga tingkatan enkripsi. Bidang Enkripsi brankas adalah metadata plaintext. Bidang Enkripsi kredensial didekripsi dengan kunci agen. Bidang Enkripsi identitas dienkripsi dengan kunci yang belum pernah dilihat oleh server dan proxy. Hanya pemilik brankas, melalui kunci perangkat kerasnya, yang dapat mendekripsinya.
Jika placeholder merujuk ke bidang Enkripsi identitas, proxy mengembalikan ERR-PROXY-035. Tidak ada fallback, tidak ada hasil parsial. Bidang tersebut secara arsitektural tidak dapat dijangkau dari proxy.
Apa yang tidak dilindungi oleh proxy
Model ancaman proxy adalah keterampilan yang disusupi atau injeksi prompt yang membuat agen yang terautentikasi memanen kredensial. Batas laju per agen brankas, kuota entri unik, dan penguncian dua kali percobaan adalah pertahanan utama. Proxy menambahkan titik penegakan lapisan jaringan di mana kredensial diselesaikan per permintaan dan tidak pernah disimpan oleh agen.
Proxy berjalan di mesin yang sama dengan agen. Penyerang dengan akses root dapat membaca memori proses, melampirkan debugger, atau mencegat lalu lintas loopback. Proxy adalah lapisan injeksi kredensial, bukan batas keamanan perangkat keras.
Jika API hulu menggemakan kredensial kembali dalam responsnya (misalnya, titik akhir "whoami"), agen akan melihatnya. Proxy menyuntikkan kredensial ke dalam permintaan, bukan respons. Proxy tidak memfilter apa yang kembali.
Pencatatan
Proxy mencatat satu baris per CONNECT yang diterima dan mengeluarkan baris kesalahan untuk kegagalan. Proxy tidak pernah mencatat:
- Nilai kredensial yang didekripsi
- URL permintaan lengkap (string kueri dapat membawa rahasia — hanya skema + host + jalur yang dicatat)
- Badan permintaan atau respons
- Kunci dekripsi kredensial atau isi konfigurasi sidecar
Ketika proxy mendeteksi bahwa respons 400 dari hulu berisi kata kunci terkait otentikasi (unauthorized, invalid token, dll.), ia mencatat petunjuk diagnostik yang menunjukkan kredensial yang disuntikkan mungkin sudah usang. Respons diteruskan tanpa perubahan.
Kriptografi
Semua kriptografi protokol Clavitor — dekripsi bidang AES-GCM, derivasi kunci HKDF, pengkodean base62, penerbitan token CVT, pengemasan/pembongkaran paket konfigurasi CLV1 — dieksekusi di dalam satu modul WebAssembly (clavis_crypto.wasm) yang dimuat melalui wazero, runtime WASM murni Go. Tanpa CGO. Tanpa implementasi ulang primitif Clavitor oleh Go.
Modul WASM dikompilasi dari crate Rust yang sama (clavis-crypto) yang digunakan oleh peramban, CLI, dan ekstensi peramban. Satu sumber kebenaran, satu biner, satu permukaan audit.
Proxy menggunakan crypto/tls Go untuk TLS di jalur dan crypto/ecdsa untuk pembuatan sertifikat MITM. Ini adalah masalah transportasi, bukan operasi protokol Clavitor.
Rahasia (kunci dekripsi kredensial, ID agen, ID perangkat, URL brankas) berada di konfigurasi sidecar CLV1 terenkripsi, ditulis sekali selama clavitor-proxy init. Parameter operasional berada di variabel lingkungan:
| Variabel | Default | Tujuan |
|---|---|---|
CLAVITOR_PROXY_LISTEN | 127.0.0.1 | Antarmuka pendengar. Atur ke 0.0.0.0 untuk penyebaran bersama, atau ke IP antarmuka tertentu. |
CLAVITOR_PROXY_PORT | 1983 | Port pendengar |
CLAVITOR_PROXY_ALLOW_PRIVATE | false | Izinkan koneksi ke jaringan RFC-1918 / pribadi |
CLAVITOR_PROXY_MAX_BODY_MB | 64 | Batas ukuran badan permintaan |
CLAVITOR_PROXY_WRITE_TIMEOUT | 300 | Waktu tunggu penulisan respons dalam detik |
CLAVITOR_CONFIG | (direktori exe) | Timpa jalur konfigurasi sidecar |
Parameter operasional bukanlah rahasia. Mereka tidak termasuk dalam konfigurasi terenkripsi. Mereka berada di tempat alat penyebaran sudah mengelolanya — lingkungan.
Tinjau sendiri.
Kriptografi adalah satu artefak WASM yang dapat diaudit. Model ancaman didokumentasikan. Jika Anda menemukan sesuatu yang kami lewatkan, kami ingin mendengarnya.