Gerbang MCP
Pengagregat MCP Yabanin ialah proxy di sisi gerbang yang membolehkan organisasi
mendedahkan mana-mana pelayan Model Context Protocol (MCP) luaran kepada ejennya — dengan
kawalan akses ejen sahaja, senarai benarkan alat bagi setiap ejen, jejak audit, pemajuan
identiti, kelayakan huluan (peringkat pelayan + kebenaran malas setiap pengguna),
kebolehcerapan, dan pengawal parameter. Ia mati secara lalai: keseluruhan
kumpulan laluan dipasang hanya apabila YABANIN_MCP_GATEWAY=1.
Nama itu bukan protokol. Walaupun nama "gerbang MCP", apa yang
dihantar hari ini ialah API seruan: endpoint HTTP biasa
POST /api/mcp/invoke (permintaan JSON, kunci ejen yag_*) yang sendiri memanggil
pelayan MCP luaran melalui JSON-RPC. Klien MCP tidak boleh menyambung kepadanya:
tiada tools/list dan tiada pengangkutan MCP yang berhadapan klien di sini.
Endpoint MCP natif pada gerbang (katalog tools/list dan pelayan
Streamable HTTP) ialah kerja masa hadapan yang dirancang (kad RM-100 dan
RM-101); sehingga itu mendarat, satu-satunya antara muka berprogram
pengagregat ialah API seruan yang diterangkan dalam §5.
Jambatan rakan keluar yang diterangkan dalam §1 ialah ciri berasingan yang sudah dihantar dan berada di luar skop di sini. Jambatan menjawab "ejen memanggil alat Yabanin"; pengagregat menjawab songsangan — "ejen Yabanin memanggil pelayan MCP luaran sewenang-wenang", dengan selamat.
1. Apa yang wujud hari ini (di luar skop pengagregat)
Yabanin sudah menghantar jambatan rakan MCP keluar
(pkg/mcppartner, services/run/mcp.go, subarahan binari mcp):
- Pengangkutan: stdio (Claude Code) dan HTTP-SSE pada
:8787(YABANIN_MCP_HTTP=1). - Alat yang didedahkan:
tr_route,tr_spend_report,tr_set_policy,tr_lineage_verify, sertatr_delegate/tr_delegation_statuspilihan. - Pengesahan: kunci API rakan (
YABANIN_PARTNER_API_KEY), dihantar sebagai Bearer ke gerbang:8082dan pentadbir:8086. - Klien huluan:
http.Clientyang dihadkan (tamat masa 30 s); klien ini hanya bercakap dengan endpoint milik Yabanin sendiri — ia tidak sekali-kali mendail URL sewenang-wenang yang dibekalkan pengguna.
Pengagregat ialah kerja baharu: registri pelayan + kawalan akses, pemajuan identiti, metrik, dan pengawal parameter — semuanya pada satah data gerbang.
2. Tingkah laku
- Akses ejen sahaja. Seruan alat diterima hanya untuk kunci prinsipal
ejen (
yag_*, kunci prinsipal ejen). Kunci APIyab_biasa tidak mempunyai identiti ejen dan ditolak dengan403 agent_onlysebelum apa-apa dicari. PengepalaX-Agent-Idmasuk dilucutkan pada kemasukan dan ditetapkan semula hanya daripada prinsipalyag_*yang dileraikan, supaya klien tidak boleh memalsukan ejen. - Geran setiap ejen + senarai benarkan alat. Ejen boleh menyeru pelayan hanya jika
ia memegang geran yang didayakan bagi
(org, agent, server); geran yang tiada atau dilumpuhkan tidak dapat dibezakan daripada "pelayan tidak tersedia" (404 not_found) — ejen tidak boleh menyenaraikan seruan mana yang disekat oleh geran. Set alat berkesan ialah persilangan senarai benarkan pelayan (mcp_servers.allowed_tools, siling) dan senarai benarkan geran (mcp_server_grants.allowed_tools).[]pada mana-mana sisi bermaksud "semua bagi sisi itu". - Keluar yang dikawal SSRF. URL huluan melepasi pengawal
pkg/ssrf(senarai benarkan DNS + penolakan IP terpelihara) semasa pendaftaran dan sekali lagi pada setiap seruan (tetingkap pengikatan semula). Proxy tidak mengikut sebarang ubah hala dan menggunakan tamat masa sambung/baca yang dihadkan. - Jejak audit. Setiap seruan alat direkodkan ke strim peristiwa yang sama yang
digunakan gerbang untuk permintaan sembang, jadi
loggerdmengekalkan barisrequest_logsyang ditag dengantask_id,agent_id, danupstream_url. Baris itu dilabelModelUsed = "mcp:<server>:<tool>"(boleh dibezakan daripada inferens model). Gerbang tidak menulisrequest_logssecara langsung. - Pemajuan identiti. Prinsipal yang disahkan dibawa ke huluan sebagai
pengepala
X-Yabanin-Agent-Id,X-Yabanin-Agent-Name, danX-Yabanin-Team-Id. Ini ialah atribusi, bukan kebenaran: pelayan luaran boleh menggunakannya untuk mengatribusikan seruan, tetapi ia tidak sekali-kali menjadi kelayakan, dan gerbang menetapkannya hanya daripada prinsipal yang disahkan (tidak sekali-kali daripada klien). - Kebolehcerapan.
gateway_mcp_calls_total{server,tool,outcome}mengira setiap seruan (kejayaan atau kegagalan); satu span OTel bagi setiap seruan (mcp.tools/call) membawamcp.server/mcp.tool/mcp.org/mcp.agent_iddanmcp.outcomeakhir. Kedua-duanya direkodkan walaupun tiada pencatat audit yang diwayar.gateway_toolpolicy_decisions_total{org,server,tool,outcome}mengira setiap keputusan pagar OP-6 (allow / deny / mask / flag / error —errorialah gangguan stor dasar gagal-terbuka, seruan berjalan TANPA PAGAR). - Pagar seruan alat (OP-6). Parameter input alat melepasi cangkuk pengawal pra-keluar
(
guardhooks.Scan) dengan mod yang diwarisi daripadaguard_mode(YABANIN_GUARD_MODE: off / log / redact / deny).redactmenggantikan rahsia/PII yang dikesan sebelum keluar dan sebelum jejak audit (parameter klien asal tidak sekali-kali sampai ke audit);denymenggugurkan seruan (409 denied). Di atas itu, peraturan pagar setiap pelayan (tool_policies.rules) menambah semakan skema/saiz/regex pada argumen dan semakan pasca pada hasil — lihat §7.
Bukan-matlamat (buat masa ini)
- pelayan stdio huluan (tiada pelancaran proses pada gerbang — permukaan keselamatan hos yang baharu; kaji semula selepas HTTP-SSE terbukti).
- Perkongsian pelayan merentas organisasi — pelayan adalah bagi setiap organisasi.
- Kependaman bagi setiap model pada skrin perbandingan — skrin perbandingan Model papan pemuka menunjukkan kos penilaian bayang bagi setiap model, persentil kependaman seluruh organisasi (berkapsyen sebagai bukan bagi setiap model) dan bahagian kualiti tersampel evalgate (ADL-04: bagi setiap pasangan murah/premium pada pertindihan yang dihakimi + bagi setiap kelas tugasan, dengan pengesyoran penghalaan yang diterapkan manusia). Kependaman bagi setiap model tidak diukur.
3. Seni bina
agent (yag_* key, X-Yabanin-Task)
│ POST /api/mcp/invoke {"server":"knowledge","tool":"search","params":{...}}
▼
┌─────────────────────────── gateway proxy (:8082) ───────────────────────────┐
│ 0. agent-only: resolved yag_* principal, else 403 agent_only │
│ 1. server row: enabled? (404 not_found) │
│ 1b. grant: enabled grant for (org, agent, server)? (404 not_found) │
│ 2. tool allowed? server allow-list ∩ grant allow-list (404 not_found) │
│ 2c. toolpolicy guardrails: server-aware deny + args rules │
│ (schema/max_bytes/deny_regex) → 400 mcp_tool_blocked (OP-6) │
│ 3. ssrf: AllowList re-check (400 ssrf_blocked) │
│ 4. guard: guardhooks.Scan(params) → off/log/redact/deny (409 denied) │
│ 5. creds: resolve outbound auth — per-user active → server-level enabled │
│ → none; 401/403 upstream → one force-refresh retry, else lazy │
│ mcp_auth_required with the human flow URL (§6) │
│ 5b. proxy: JSON-RPC tools/call POST → upstream (bounded timeout) │
│ headers: X-Yabanin-Agent-Id / X-Yabanin-Agent-Name / X-Yabanin-Team-Id │
│ 6. record: gateway_mcp_calls_total{server,tool,outcome} + OTel span │
│ + audit event → loggerd → request_logs (task_id, agent_id, upstream_url) │
│ 6b. toolpolicy result post-check (secrets/deny_regex: flag|mask|deny) │
│ → 400 mcp_tool_blocked / redacted result (OP-6) │
└──────────────────────────────────────────────────────────────────────────────┘
▼
external MCP server (HTTP-SSE, e.g. an org's internal knowledge server)
Proxy berada dalam satah data gerbang (:8082, kumpulan laluan /api/mcp/...),
bukan pentadbir — trafik ejen ialah satah data. Pentadbir memiliki
CRUD mcp_servers dan CRUD geran setiap ejen; gerbang membaca kedua-duanya melalui
stor yang sama yang digunakan tetapan organisasi/penghalaan.
Postur lalai: mati. Kumpulan laluan dikompil masuk tetapi dipasang hanya apabila
YABANIN_MCP_GATEWAY=1 dan kolam pangkalan data wujud. Pelaksanaan yang tidak menetapkan
pemboleh ubah persekitaran baharu berkelakuan tepat seperti sebelumnya.
4. Model data
Dua jadual, kedua-duanya bagi setiap organisasi:
-- Baseline 0001_init: the server registry.
CREATE TABLE mcp_servers (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
org_id uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
name text NOT NULL, -- [a-z0-9][a-z0-9_-]*
display_name text,
url text NOT NULL, -- https://… (the SSRF-guarded host)
transport text NOT NULL DEFAULT 'http', -- only 'http' is proxied
allowed_tools jsonb NOT NULL DEFAULT '[]', -- [] = all tools the server offers
enabled boolean NOT NULL DEFAULT false,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (org_id, name)
);
CREATE INDEX idx_mcp_servers_org ON mcp_servers (org_id) WHERE enabled;
-- Baseline 0001_init: per-agent grants (one row per agent per server).
CREATE TABLE mcp_server_grants (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
org_id uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
agent_id uuid NOT NULL REFERENCES agent_keys(id) ON DELETE CASCADE,
server_name text NOT NULL, -- same name rules as mcp_servers
allowed_tools jsonb NOT NULL DEFAULT '[]', -- [] = every tool the SERVER allows
enabled boolean NOT NULL DEFAULT true,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (org_id, agent_id, server_name)
);
CREATE INDEX idx_mcp_server_grants_org_agent ON mcp_server_grants (org_id, agent_id) WHERE enabled;
CREATE INDEX idx_mcp_server_grants_org_server ON mcp_server_grants (org_id, server_name) WHERE enabled;
Geran merujuk agent_keys.id (prinsipal ejen). Geran ialah
fakta kebenaran (siapa boleh memanggil apa), bukan kelayakan — tiada bahan
rahsia. Geran yang dilumpuhkan lengai sehingga pengendali mendayakannya (postur
kejujuran ketersediaan yang sama seperti mcp_servers.enabled).
Migrasi 0007 menambah jadual kelayakan — mcp_server_credentials
(peringkat pelayan) dan mcp_user_credentials (bagi setiap (server, agent)) — diterangkan
dalam §6.
5. Endpoint
Pentadbir (satah kawalan, pengesahan root sahaja, berskop organisasi):
POST /api/organizations/{id}/mcp/servers create server
GET /api/organizations/{id}/mcp/servers list servers
GET /api/organizations/{id}/mcp/servers/{name} get one server
PATCH /api/organizations/{id}/mcp/servers/{name} update (incl. enabled)
DELETE /api/organizations/{id}/mcp/servers/{name} delete server
GET /api/organizations/{id}/mcp/servers/{name}/grants list grants
POST /api/organizations/{id}/mcp/servers/{name}/grants create grant
PATCH /api/organizations/{id}/mcp/servers/{name}/grants/{agent_id} update grant
DELETE /api/organizations/{id}/mcp/servers/{name}/grants/{agent_id} revoke grant
PUT /api/organizations/{id}/mcp/servers/{name}/credential upsert server-level credential
GET /api/organizations/{id}/mcp/servers/{name}/credential read the masked row
DELETE /api/organizations/{id}/mcp/servers/{name}/credential delete
Senarai benarkan domain SSRF bagi URL pelayan ialah milik pelaksanaan
YABANIN_MCP_ALLOWED_UPSTREAMS (domain tepat dipisahkan koma atau *.suffix;
kosong = gagal-tertutup, setiap hos ditolak). Penciptaan geran memerlukan
pelayan yang dirujuk wujud bagi organisasi (404 jika tidak) dan memulangkan 409 pada
pendua pelanggaran unik.
Gerbang (satah data, pengesahan ejen yag_*):
POST /api/mcp/invoke {"server":"knowledge","tool":"search","params":{...}}
→ 200 {tool result} | 401 mcp_auth_required | 403 agent_only | 404 not_found
| 400 ssrf_blocked | 400 mcp_tool_blocked | 409 denied
| 504 timeout | 502 upstream
POST /api/mcp/credentials/{server} headers submit/rotate (per-user, grant ceiling)
POST /api/mcp/auth/{server}/begin oauth: consent URL + pending row
GET /api/mcp/auth/{server}/callback oauth: code exchange (public — the IdP
redirects the human's browser here)
Satu endpoint seruan (bukan laluan bagi setiap pelayan) mengekalkan jadual laluan stabil
apabila pelayan ditambah atau dibuang; pelayan ialah nilai, bukan segmen laluan.
params ialah objek input alat; proxy mensirinya ke dalam permintaan
JSON-RPC tools/call huluan. Respons ialah sama ada application/json
(hasil tunggal) atau text/event-stream (hasil sebagai bingkai data terakhir);
kedua-duanya dikendalikan dan diruntuhkan kepada result akhir. Seruan alat ialah
permintaan/respons dari perspektif ejen (tiada penstriman separa).
| Kod | HTTP | Maksud |
|---|---|---|
agent_only | 403 | pemanggil bukan kunci prinsipal ejen (yag_*) |
mcp_auth_required | 401 | tiada kelayakan boleh guna bagi huluan (atau yang disimpan sudah mati); badan membawa {"error":{"code":"mcp_auth_required","kind":"headers|oauth","url":"/api/mcp/…"}} — aliran manusia yang menyelesaikannya (§6) |
not_found | 404 | pelayan tiada/dilumpuhkan, atau tiada geran ejen, atau alat tiada pada senarai benarkan berkesan |
ssrf_blocked | 400 | URL gagal pengawal SSRF bagi setiap seruan |
mcp_tool_blocked | 400 | pagar toolpolicy OP-6 menyekat seruan atau hasilnya (dasar nafi, peraturan skema/saiz maksimum/regex argumen, atau semakan pasca hasil mod nafi); mesej menamakan semakan yang gagal, tidak sekali-kali nilai yang sepadan |
denied | 409 | pengawal parameter (mod deny) menolak parameter |
timeout | 504 | huluan melebihi tamat masa baca/sambung |
upstream | 502 | huluan memulangkan bukan-2xx atau badan cacat bentuk |
6. Kelayakan huluan (MC-1..3)
Pelayan MCP huluan mungkin memerlukan pengesahan. Pengagregat meleraikan kelayakan keluar pada setiap seruan melalui rantai tetap — setiap pengguna (aktif) → peringkat pelayan (didayakan) → tiada — dan tidak sekali-kali membenarkan kelayakan meluaskan permukaan keluar: semakan senarai benarkan SSRF pada URL pelayan berjalan sebelum sebarang peleraian kelayakan, jadi hos yang didaftarkan tetapi tidak dibenarkan kekal disekat dengan atau tanpa kelayakan.
Jenis pengesahan
| Jenis pengesahan | Siapa yang menetapkannya | Peleraian pada seruan |
|---|---|---|
none (-) | — | seruan diteruskan tanpa pengesahan (postur legasi); keputusan huluan yang menentukan |
headers (peringkat pelayan) | pentadbir melalui API pentadbir (PUT …/credential) | digunakan pada seruan setiap ejen apabila didayakan |
headers (setiap pengguna) | manusia ejen melalui aliran malas (POST /api/mcp/credentials/{server}) | digunakan hanya bagi pasangan (server, agent) itu, apabila active |
oauth (peringkat pelayan atau setiap pengguna) | pentadbir, atau aliran malas begin/callback | token akses digunakan; 401/403 huluan mencetuskan tepat satu cubaan semula muat semula paksa; token yang mati menjadi needs_reauth (kekal) |
Kebenaran malas (mcp_auth_required)
Apabila tiada kelayakan boleh guna wujud (atau yang disimpan sudah mati), seruan
menjawab 401 dengan badan berstruktur:
{"error": {"code": "mcp_auth_required", "kind": "headers",
"url": "/api/mcp/credentials/knowledge"}}
kind menamakan jenis kelayakan yang akan memenuhi pelayan (headers →
endpoint hantar, oauth → endpoint mula) dan url ialah
laluan relatif manusia untuk memulakan aliran itu. Aliran hantar/mula memerlukan
kunci prinsipal ejen (yag_) dan menghormati X-Audit-Reason.
Status kitar hayat (kelayakan setiap pengguna)
| Status | Maksud |
|---|---|
pending | aliran malas bermula (persetujuan oauth belum selesai) |
active | dileraikan dan digunakan pada seruan |
orphaned | geran pada pelayan dibatalkan — kelayakan itu lengai; pemberian semula geran memulihkannya (RestoreMCPUserCredentials) |
needs_reauth | huluan menolak token secara muktamad (kekal sehingga pengesahan semula) |
needs_update | rahsia yang disimpan gagal pengesahan selepas perubahan huluan |
version bertambah pada setiap putaran atau peralihan status supaya cache
penyelesai gerbang dinyahsah serta-merta.
Invarian keselamatan
- Bahan rahsia teks biasa wujud hanya sebagai argumen panggilan ke dalam
kaedah store/resolve; setiap bacaan memulangkan baris bertopeng sahaja
(
secret_last4,has_secret) — tiada respons API boleh membawa teks biasa atau teks sifer, dan tiada medan struct boleh menyimpannya. - Rahsia disulitkan semasa rehat dengan sampul berawalan
enc:(pkg/encryption, pariti BYOK, jadual migrasi0007). Penulisan ialah gagal-tertutup: tanpa penyulit yang dikonfigurasi penulisan ditolak — konfigurasi penyulitan yang tiada tidak sekali-kali boleh merosot secara senyap kepada teks biasa. - Setiap operasi berjalan dalam satu transaksi yang GUC
app.current_org-nya disemat — kontrak RLSorg_isolation(ENABLE + FORCE, peranan keistimewaan paling rendah). Baris organisasi asing tidak kelihatan dan tidak boleh ditulis. - Setiap langkah CRUD/status mendarat dalam jurnal audit berantai cincang.
- Teks biasa dihadkan (8 KiB bagi setiap muatan rahsia) dan tidak sekali-kali dilog atau disiri oleh proxy.
- Upsert setiap pengguna memerlukan geran yang didayakan pada pelayan — geran kekal sebagai siling bagi setiap langkah aliran (lihat Tadbir urus ejen).
7. Pagar seruan alat (OP-6)
Di atas registri benarkan/nafi yang biasa (Dasar alat),
baris tool_policies boleh membawa dokumen rules yang dinilai pada
granulariti (organisasi, pelayan, alat, subjek):
- Pengawal argumen berjalan pra-keluar: JSON-Schema (draf 2020-12) pada
argumen yang disiri, had saiz
max_bytesdan corak RE2deny_regex. Sesuatu pelanggaran menyekat seruan dengan400 mcp_tool_blockedsebelum sebarang trafik huluan. - Semakan pasca hasil berjalan pada hasil huluan yang disiri: pengesan
rahsia/PII/suntikan
guardhooksdandeny_regextersuai dengan mod setiap peraturanflag | mask | deny— topeng memulangkan hasil yang dihitamkan, nafi menggugurkannya dengan400 mcp_tool_blocked.
Peraturan yang sepadan digabung kesatuan + paling ketat (peraturan hanya boleh menambah
sekatan); setiap dapatan membawa hanya sumber semakan dan penunjuk span/JSON
— nilai yang sepadan tidak sekali-kali muncul dalam ralat, dapatan atau metrik. Mod
gagal adalah bagi setiap peraturan (fail: closed|open, lalai tertutup): sebaik sahaja organisasi
mengisytiharkan peraturan gagal-tertutup, gangguan stor dasar menyekat seruan yang dikawal
sehingga stor pulih. Tiada rules pada mana-mana baris = tingkah laku
pra-pagar, bit demi bit.
Keputusan dikira dalam gateway_toolpolicy_decisions_total{org,server,tool,outcome}
(error ialah gangguan stor dasar gagal-terbuka — seruan berjalan TANPA PAGAR).
8. Matriks risiko
| # | Risiko | Keterukan | Mitigasi |
|---|---|---|---|
| R1 | SSRF: organisasi mendaftarkan http://169.254.169.254/… atau hos pengikatan semula DNS yang menunjuk kepada metadata awan / perkhidmatan dalaman | Tinggi | pkg/ssrf AllowList.ValidateUpstream (senarai benarkan DNS + penolakan IP terpelihara) semasa pendaftaran dan sekali lagi pada setiap seruan (tetingkap pengikatan semula); tiada ubah hala diikuti; senarai benarkan domain statik pelaksanaan (YABANIN_MCP_ALLOWED_UPSTREAMS) |
| R2 | Suntikan prompt / persenjataan alat: seruan alat yang didorong model mengeksfiltrasi data organisasi melalui skema alat atau parameter pelayan luaran yang berniat jahat | Tinggi | akses ejen sahaja, geran setiap ejen, senarai benarkan alat setiap pelayan (persilangan), cangkuk pengawal pada parameter, dasar nafi toolpolicy organisasi + peraturan argumen (skema/saiz maksimum/regex) pra-keluar, lalai MATI, jejak audit dengan parameter yang dihitamkan; bajet setiap ejen mengikat jejari letupan seruan berulang |
| R3 | Keluar rahsia: parameter membawa kunci API organisasi / PII ke pelayan luaran | Sederhana | guardhooks.Scan (termasuk pengesan PII kebangsaan) dalam mod redact/deny mengikut guard_mode sebelum keluar; deny menggugurkan seruan dengan 409 + peristiwa audit; semakan pasca hasil OP-6 (pengesan rahsia, flag/mask/deny setiap peraturan) menghentikan HASIL alat yang sarat rahsia daripada sampai kepada ejen |
| R4 | Kebocoran kelayakan: menyimpan token huluan setiap pelayan dalam Postgres | Sederhana | rahsia hanya sebagai sampul disulitkan enc: semasa rehat (penulisan gagal-tertutup tanpa penyulit); RLS pengasingan organisasi (GUC app.current_org); bacaan memulangkan baris bertopeng sahaja (secret_last4/has_secret — teks biasa tidak sekali-kali merentas API); setiap langkah CRUD/status dalam jurnal audit berantai cincang; kelayakan tidak sekali-kali meluaskan keluar (semakan SSRF mendahului peleraian) (§6) |
| R5 | Penafian perkhidmatan / kos: ejen menggelung seruan alat; huluan mengecaj setiap seruan | Sederhana | bajet token/perbelanjaan setiap ejen yang diwarisi; tamat masa sambung + baca proxy yang dihadkan; gateway_mcp_calls_total menjadikan kadar gelung kelihatan |
| R6 | Pemalsuan identiti: huluan mempercayai pengepala X-Yabanin-Agent-* yang dipalsukan oleh ejen milik organisasi sendiri | Rendah | pengepala ialah atribusi, bukan kebenaran; gerbang tidak sekali-kali memajukan nilai pengepala ini yang dibekalkan pemanggil (dilucutkan pada kemasukan, ditetapkan daripada prinsipal ejen yang disahkan) |
| R7 | Jurang audit: seruan alat berlaku tetapi tidak dilog | Sederhana | seruan dijawab tanpa mengira audit (ketersediaan mengatasi audit); metrik gateway_mcp_calls_total dan span OTel direkodkan walaupun penerbitan audit digugurkan, jadi jurang kelihatan |
| R8 | Rampasan strim SSE / huluan slow-loris | Rendah | tamat masa baca yang dihadkan pada badan SSE, saiz respons maksimum, tiada guna semula keep-alive terbiar kepada hos yang dibekalkan pengguna di luar kolam standard |
| R9 | Kebergantungan: permukaan klien MCP untuk HTTP-SSE | Rendah | pembungkus klien nipis (JSON-RPC atas HTTP/SSE) supaya lapisan pengangkutan boleh ditukar; pintu keselamatan pada setiap perubahan |
| R10 | Rayapan skop ke huluan stdio (pelancaran proses pada gerbang) | Sederhana | bukan-matlamat yang eksplisit (§2); stdio kekal hanya untuk jambatan keluar |
9. Invarian keselamatan (disemak oleh pintu keselamatan repositori pada setiap perubahan pengagregat)
- Tiada URL yang dikawal pengguna sampai ke
http.Clienttanpa melepasi pengawal SSRF dua kali (pendaftaran + seruan) — dan sentiasa sebelum peleraian kelayakan, supaya kelayakan tidak boleh memanjangkan keluar. - Rahsia kelayakan disimpan hanya sebagai sampul
enc:, dibaca semula hanya sebagai baris bertopeng (secret_last4/has_secret) di bawah RLS pengasingan organisasi, dan setiap mutasi diaudit; tiada bahan rahsia disimpan dalammcp_servers/mcp_server_grantsatau dilog tanpa penghitaman; peristiwa audit membawaparams-redacted. - Identiti ejen datang hanya daripada prinsipal
yag_*yang disahkan; pengepalaX-Yabanin-Agent-*ditetapkan oleh proxy dan dilucutkan daripada permintaan masuk. - Ciri ini MATI secara lalai (
YABANIN_MCP_GATEWAYtidak ditetapkan ⇒ kumpulan laluan tidak dipasang ⇒ sifar perubahan tingkah laku).
10. Rujukan konfigurasi
| Pemboleh ubah persekitaran | Lalai | Maksud |
|---|---|---|
YABANIN_MCP_GATEWAY | tidak ditetapkan (mati) | 1 memasang kumpulan laluan /api/mcp/invoke (memerlukan kolam pangkalan data). |
YABANIN_MCP_ALLOWED_UPSTREAMS | kosong | Domain tepat dipisahkan koma atau *.suffix yang mesti dipadankan hos URL huluan. Kosong = gagal-tertutup (setiap hos ditolak). |
YABANIN_GUARD_MODE | off | off / log / redact / deny — mod pengawal parameter yang digunakan pada input alat (diwarisi daripada cangkuk pengawal laluan sembang). |
Pendawaian pelaksanaan (OP-25 F-5): perkhidmatan pentadbir menghurai
YABANIN_MCP_ALLOWED_UPSTREAMS daripada persekitaran (config.Load("") ialah
env sahaja — config.yaml yang dilekapkan tidak dibaca) dan menghantar senarai itu kepada
CRUD registri; gerbang menghurai pemboleh ubah yang sama untuk semakan semula
semasa seruan, pengawal URL token kelayakan dan pelaksana alat sisi pelayan —
SATU senarai mentadbir pendaftaran dan setiap dail keluar. Dalam pelaksanaan compose,
pemboleh ubah itu oleh itu mesti dihantar kepada KEDUA-DUA perkhidmatan admin dan gateway
(deploy/docker-compose.prod.yml + deploy/.env.example melakukan ini);
kosong/tidak ditetapkan bermaksud pendaftaran menjawab 400 (host not in the allowed domains list) — gagal-tertutup mengikut reka bentuk, bukan kerosakan.
11. Ringkasan penerimaan
| Komponen | Penerimaan |
|---|---|
| Registri + proxy | CRUD mcp_servers dalam pentadbir; proxy seruan untuk HTTP-SSE; lalai MATI; pengawal SSRF pada pendaftaran + seruan; tamat masa yang dihadkan; ujian meliputi nafi ubah hala, IP terpelihara, tamat masa |
| Akses + audit | seruan menolak kunci bukan-yag_ (403 agent_only) dan ejen/pelayan/alat tanpa geran (404); setiap seruan → baris request_logs dengan task_id/agent_id/upstream_url + peristiwa audit (parameter dihitamkan), dilabel mcp:<server>:<tool>; CRUD geran dalam pentadbir |
| Identiti | huluan menerima X-Yabanin-Agent-Id / -Name / X-Yabanin-Team-Id; salinan masuk dilucutkan; nilai datang daripada prinsipal yang disahkan |
| Kebolehcerapan | gateway_mcp_calls_total{server,tool,outcome} hadir di bawah /metrics; satu span OTel (mcp.tools/call) bagi setiap seruan dengan atribut pelayan/alat/hasil |
| Pengawal parameter | parameter melepasi guardhooks.Scan; mod redact menggantikan rahsia; mod deny menggugurkan seruan (409) + audit; mod diwarisi daripada guard_mode |
| Pagar seruan alat (OP-6) | tool_policies.rules (skema argumen/max_bytes/deny_regex pra-keluar; rahsia hasil/regex flag/mask/deny pasca-keluar); pelanggaran skema → 400 mcp_tool_blocked sebelum sebarang trafik huluan; rahsia dalam hasil → bertopeng atau dinafikan mengikut peraturan; dapatan membawa span/kategori sahaja (bebas nilai, disemat oleh ujian); -race hijau pada keserentakan Decide/Guard; peraturan organisasi terasing bagi setiap organisasi |
| Kelayakan huluan (MC-1..3) | kelayakan peringkat pelayan + setiap pengguna sebagai sampul enc: di bawah RLS pengasingan organisasi; bacaan bertopeng sahaja; seruan meleraikan setiap pengguna → peringkat pelayan → none dengan satu cubaan semula muat semula; mcp_auth_required malas dengan URL aliran manusia; siling geran + penyatiman/pemulihan; jurnal audit pada setiap langkah CRUD/status |
| Skrin perbandingan model | skrin perbandingan papan pemuka (#compare): kos penilaian bayang bagi setiap model + kependaman seluruh organisasi (berkapsyen bukan bagi setiap model) + kualiti tersampel evalgate bagi setiap pasangan/kelas tugasan (ADL-04) dengan pengesyoran penghalaan yang diterapkan manusia; kapsyen skop yang digunakan; terpapar pada semua ruang pandang |