जोखिम सीमित करने वाले Autonomous Coding Agents के लिए API Scopes

Autonomous coding agent को किसी तय काम के लिए credential मिलना चाहिए, ऐसा credential नहीं जो हर गलती को गायब कर दे। मुश्किल यह नहीं कि write नाम वाला scope मिल जाए। असली चुनौती यह साबित करना है कि token एक task पूरा कर सकता है और उससे जुड़े उन actions पर fail होता है जो उसके काम का हिस्सा नहीं हैं।

मैंने teams को personal token से शुरुआत करते देखा है, क्योंकि agent को "बस शुरू करना" था। कुछ हफ्तों बाद वही token developer द्वारा कभी छुई गई हर repository पढ़ सकता है, deployment settings बदल सकता है और ऐसे destructive requests भेज सकता है जिनकी मूल task को कोई ज़रूरत नहीं थी। यह जोखिम agent ने नहीं बनाया। इसे ढीली permission boundary ने बनाया।

Task, role से अधिक सीमित होता है

Agent task किसी outcome और state में होने वाले सीमित बदलावों का वर्णन करता है। Role किसी व्यक्ति या service का व्यापक परिचय देता है। अगर access role के आधार पर दिया जाए, तो लगभग हमेशा task से अधिक access मिल जाता है।

मान लीजिए request है: "payments service में dependency update करो, test suite चलाओ और pull request खोलो।" Agent को एक repository पढ़ने, branch बनाने, उस branch पर commits push करने और pull request बनाने की ज़रूरत हो सकती है। Test service उन्हें API के ज़रिए उपलब्ध कराती हो तो build logs पढ़ने की permission भी चाहिए हो सकती है। उसे organization administer करने, protected branch rules बदलने, deployment credentials rotate करने या अपना काम merge करने की ज़रूरत नहीं है।

Task contracts को named resources पर verbs के रूप में लिखें। "repository write" न लिखें। यह लिखें कि agent वास्तव में क्या कर सकता है:

• payments-service में source, issues और मौजूदा pull requests पढ़ना।
• ऐसे branches बनाना और update करना जिनके नाम agent/ से शुरू हों।
• उस branch से designated base branch के लिए एक pull request बनाना।
• उस pull request से शुरू हुए workflow का status और logs पढ़ना।
• Test result वाला comment पोस्ट करना।

यह bureaucracy नहीं है। यह सूची छिपे हुए फैसले सामने लाती है। क्या agent issue बंद कर सकता है? क्या वह किसी और की pull request edit कर सकता है? क्या उसे महँगा workflow दोबारा चलाने की अनुमति है? क्या उसे private registry से package लाना है? हर verb या तो permission का हकदार बनता है या हटा दिया जाता है।

Task contract ज़रूरी side effect और सुविधाजनक side effect को भी अलग करता है। Pull request खोलने के बाद agent issue label update करना चाह सकता है। यह उपयोगी हो सकता है, लेकिन dependency update के लिए ज़रूरी नहीं है। इसे पहले permission set से बाहर रखें। बाद में तभी जोड़ें जब कोई व्यक्ति इस effect को स्वीकार करे और boundary का परीक्षण हो जाए।

Recurring jobs को अलग tasks मानें, भले ही एक ही agent process उन्हें चलाता हो। Nightly dependency check, release promotion और production rollback के परिणाम अलग होते हैं। संचित permissions वाला एक identity इन तीनों की समीक्षा कठिन और साफ़ तरीके से revoke करना असंभव बना देता है।

Scope names permission boundaries नहीं होते

Scope string authorization के लिए input है, यह इस बात का प्रमाण नहीं कि API call सुरक्षित है। Providers "scope" शब्द का उपयोग कई अलग mechanisms के लिए करते हैं: OAuth strings, repository permissions, project roles, installation grants और resource list तक सीमित tokens। ये एक-दूसरे के बदले इस्तेमाल नहीं किए जा सकते।

OAuth 2.0 RFC 6749 में scope को space-separated strings के set के रूप में परिभाषित किया गया है, जो access token की access सीमित करता है। हर string का अर्थ authorization server पर छोड़ दिया गया है। Providers के लिए यह flexibility उपयोगी है, लेकिन इसका मतलब है कि repo:write, projects.write और api तब तक लगभग कुछ नहीं बताते जब तक provider का endpoint documentation न पढ़ें और token का परीक्षण न करें।

RFC 8707 resource indicators जोड़ता है। Client पूरे authorization server के पीछे मौजूद हर endpoint को एक ही target मानने के बजाय किसी specific protected resource के लिए token मांग सकता है। Issuer इसे support करता हो तो यह मददगार है। लेकिन इससे वह provider ठीक नहीं होता जो एक broad scope को उसी resource के हर project या हर destructive endpoint से जोड़ देता है।

अपने design notes में इन तीन layers को अलग रखें:

आम खराब सलाह है, "read only plus write इस्तेमाल करें।" यह लोकप्रिय है क्योंकि setup guide में आसानी से आ जाती है और पहली कोशिश में अक्सर काम करती है। यह गलत है क्योंकि write कई असंबंधित verbs को cover कर सकता है। Pull request बनाना, repository delete करना, webhook बदलना और access control में बदलाव करना एक ही broad grant के पीछे हो सकते हैं।

जब provider केवल broad scope देता हो, तो उसे सावधानी से नाम देकर least privilege हासिल करने का दिखावा न करें। Resource layer को सीमित करें। ऐसा dedicated repository, project, environment या service account बनाएँ जिसकी access केवल target तक हो। अगर agent को production में एक action चाहिए, तो उस action के लिए अलग identity दें और explicit approval ज़रूरी करें। Provider का coarse model coarse ही रहेगा, लेकिन credential कम जगहों तक पहुँच सकेगा।

Token जारी करने से पहले endpoint ledger बनाएँ

Endpoint ledger अस्पष्ट request को ऐसी permission design में बदलता है जिसकी समीक्षा की जा सके। इसमें agent की हर allowed call, उसकी ज़रूरत का कारण, छू सकने वाला resource और उसे सक्षम करने वाली exact permission दर्ज होती है।

Provider के permissions page से नहीं, action sequence से शुरुआत करें। Pull request खोलने वाले agent को अपेक्षा से अधिक calls की ज़रूरत हो सकती है: base revision पढ़ना, ref बनाना, files बनाना या update करना, workflow status पाना और pull request submit करना। Permissions page शायद यह न बताए कि आपके workflow के लिए इनमें से कौन-सी call अनिवार्य है।

इस तरह का ledger इस्तेमाल करें। Illustrative paths को अपने provider द्वारा documented paths से बदलें।

task: update dependency and open pull request
resource: org/payments-service
calls:
  - method: GET
    path: /repos/org/payments-service/contents/package-lock.json
    purpose: read current dependency lockfile
    permission: contents:read

  - method: POST
    path: /repos/org/payments-service/git/refs
    constraint: "ref starts with refs/heads/agent/"
    purpose: create working branch
    permission: contents:write

  - method: PUT
    path: /repos/org/payments-service/contents/package-lock.json
    constraint: "branch starts with agent/"
    purpose: commit updated lockfile
    permission: contents:write

  - method: POST
    path: /repos/org/payments-service/pulls
    constraint: "base is main; head starts with agent/"
    purpose: request review
    permission: pull_requests:write

forbidden_calls:
  - DELETE /repos/org/payments-service
  - PATCH /repos/org/payments-service/branches/main/protection
  - POST /repos/org/organization-hooks
  - GET /repos/org/another-service/contents/secrets.yml

constraint field महत्वपूर्ण है, क्योंकि endpoint permissions अक्सर task permissions तक नहीं पहुँचतीं। API branch बनाने की अनुमति दे सकता है, लेकिन agent/ prefix तक native restriction न दे। इस gap को दर्ज करें। आपको intermediary action service, अलग repository या review gate की ज़रूरत हो सकती है, क्योंकि scope आपके चाही गई branch rule को लागू नहीं कर सकता।

Constraints को intact रखने के लिए agent prompt पर निर्भर न रहें। Prompt intended branch prefix बता सकता है, लेकिन main को भेजी गई request को reject नहीं कर सकता। Enforcement point API provider, target resource की settings या ऐसा action gateway होना चाहिए जो request भेजने से पहले उसकी जाँच करे।

Ledger में read calls को भी write calls जितनी गंभीरता से दर्ज करें। Deployment secret, customer export, security advisory या दूसरी repository पढ़ना किसी खराब commit से भी अधिक उजागर कर सकता है। अधिकांश permission reviews writes पर पूरा ध्यान देते हैं क्योंकि writes दिखाई देते हैं। Agent का context window broad reads को भी खतरनाक बनाता है।

Discovery access और mutation access अलग रखें

Discovery access और mutation access के लिए आम तौर पर अलग credentials इस्तेमाल करें, क्योंकि agent को broad context की ज़रूरत broad authority से अधिक बार पड़ती है।

Planning agent को कई repositories में code search करने, issues देखने, build output जाँचने और versions की तुलना करने की ज़रूरत हो सकती है। Patching agent को शायद केवल एक repository की एक branch में लिखना हो। अगर दोनों jobs एक token साझा करते हैं, तो patching agent planner की व्यापक read surface पा लेता है और planner को ऐसी write capability मिल जाती है जिसकी उसे ज़रूरत नहीं।

जहाँ provider अनुमति दे, काम को stages में बाँटें। Discovery stage एक सीमित plan या patch proposal बनाए। दूसरा process उस artifact और अधिक संकीर्ण credential से requested mutation करे। Protected area पर असर हो तो handoff की human review कराएँ।

यह separation उस practical failure को पकड़ती है जिसे prompts ठीक नहीं कर सकते। मान लें planner किसी package के references के लिए organization search करता है और deployment notes वाली पुरानी internal repository खोज लेता है। अगर वही token पढ़ी गई हर जगह push भी कर सकता है, तो बाद की गलत tool call गलत repository बदल सकती है। Model task को पूरी तरह समझता हो, फिर भी गलत identifier चुन सकता है। Writer को intended repository तक सीमित करने से वह गलती denied request में बदल जाती है।

सिर्फ अधिक tokens बनाने के लिए tokens न बाँटें। उन्हें तब बाँटें जब permissible resources या verbs अलग हों। एक read token coherent investigation के लिए पर्याप्त हो सकता है। एक write token किसी एक target के भीतर closely related edits के लिए पर्याप्त हो सकता है। उद्देश्य यह है कि हर token के लिए "यह process क्या कर सकता है?" का उत्तर इतना छोटा हो कि engineer बिना अनुमान लगाए उसे verify कर सके।

Source control में, जहाँ provider अनुमति दे, branch write authority को merge authority से अलग रखें। Branch proposed change है। Merge shared baseline बदलता है और deployments, releases या downstream automation शुरू कर सकता है। Agent उपयोगी pull request खोल सकता है, बिना merge permission पाए।

Scope को बेहतर बनाने से पहले resource सीमित करें

Organization-wide credential से जुड़ा narrow scope अक्सर disposable, isolated target से जुड़े broad scope से भी बदतर होता है। Scope verbs नियंत्रित करता है। Resource boundaries तय करती हैं कि वे verbs कहाँ लागू होंगे। दोनों चाहिए, लेकिन resource boundaries अक्सर गलतियों को संभालने योग्य बनाती हैं।

Autonomous agents को personal tokens के बजाय service identities दें। Personal access tokens अक्सर इंसान की पुरानी memberships, temporary administrator grants और उन projects की access भी ले आते हैं जिन्हें setup के समय कोई याद नहीं करता। बाद में एक token revoke करने से unrelated work रुक सकता है, इसलिए teams revocation टालती रहती हैं। इसी तरह temporary exceptions permanent access बन जाती हैं।

Dedicated identity बिना access से शुरू होनी चाहिए और endpoint ledger में दर्ज resource grants ही पाने चाहिए। Agent किसी repository पर काम करता है तो उसे पूरी organization के बजाय वही repository दें। Staging deployment update करता है तो उसे सभी environments के बजाय staging environment दें। किसी एक customer account के records लिखता है तो global API credential के बजाय उसी account तक access दें।

Permissions test करने के लिए अलग nonproduction targets रखें। Production में actual writes करके token test करने से पता चल सकता है कि token काम करता है, लेकिन यह साबित नहीं होता कि वह उचित रूप से सीमित है। Test repository या project में creation, update, failure, revocation और audit behavior को live system में cleanup किए बिना आज़माया जा सकता है।

Resource isolation उन APIs की भी भरपाई करती है जिनका scope model खराब है। कुछ services केवल एक api scope वाला token देती हैं और endpoint granularity नहीं देतीं। फिर भी आप ऐसा dedicated project बना सकते हैं जिसमें केवल agent के लिए ज़रूरी resources हों, organization administration रोक सकते हैं और हर environment के लिए अलग identity इस्तेमाल कर सकते हैं। Fine-grained API से यह कम सुंदर है, लेकिन dynamically requests बनाने वाले process को all-purpose token देने से कहीं बेहतर है।

Agent को production access केवल इसलिए न दें कि उसका बदला code आखिरकार production तक पहुँचता है। Release system को approved, separately authorized path से यह transition संभालना चाहिए। अगर task में सचमुच production operation शामिल है, तो उसके लिए अलग contract लिखें। उसमें target environment, allowed method, allowable parameters, rollback behavior और approval देने वाले व्यक्ति का नाम होना चाहिए।

Success और denial को एक ही contract में test करें

Permission set तब तक अधूरा है जब तक आप दो बातें साबित न कर दें: agent अपना assigned work पूरा कर सकता है और उसके पास न दिए गए पास के actions fail होते हैं। केवल happy path test करने से सुविधा साबित होती है, containment नहीं।

हर permission change के लिए clean test identity इस्तेमाल करें। Existing credentials में cached grants, inherited roles या दूसरा authentication path हो सकता है, जिससे test गलत कारण से सफल दिखे। Run से पहले token का subject, intended resources, issued scopes और expiry रिकॉर्ड करें।

एक practical test sequence इस तरह हो सकती है:

1. Disposable target resource और proposed grants वाला credential बनाएँ।
2. Agent या deterministic request fixture को ledger की हर allowed call से चलाएँ।
3. Expected state, जैसे branch, pull request, comment या updated record, verify करें।
4. उसी credential से हर forbidden call भेजें और denial की अपेक्षा रखें।
5. Credential हटाएँ या session revoke करें, फिर पहले allowed call को दोबारा चलाकर denial की अपेक्षा रखें।

Agent run के साथ direct requests भी चलाएँ। Direct requests tool selection की अनिश्चितता हटाती हैं और दिखाती हैं कि provider खुद boundary लागू करता है या नहीं। यह shell fixture test का आकार दिखाता है। इसमें माना गया है कि API JSON लौटाती है और authorized identity के पास permission न होने पर 403 देती है।

base="https://api.example.internal"
auth="Authorization: Bearer $AGENT_TOKEN"

curl -sS -o allowed.json -w "%{http_code}\n" \
  -H "$auth" \
  -X POST "$base/repos/acme/payments-service/pulls" \
  -H "Content-Type: application/json" \
  -d '{"head":"agent/dependency-bump","base":"main","title":"Update parser"}'
# Expected output: 201

curl -sS -o denied.json -w "%{http_code}\n" \
  -H "$auth" \
  -X DELETE "$base/repos/acme/payments-service"
# Expected output: 403

cat denied.json
# Expected shape: {"message":"Resource not accessible by integration"}

केवल status code assert न करें। Allowed operations के लिए resulting state भी देखें। कुछ APIs request स्वीकार करके उसे asynchronous तरीके से process करती हैं, या success लौटाकर उस field को अनदेखा कर देती हैं जिस पर agent निर्भर था। Denials के लिए 401 और 403 अलग करें। 401 का मतलब malformed या expired test credential हो सकता है। Successful authentication के बाद मिला 403 बेहतर ढंग से दिखाता है कि authorization ने call रोकी। Providers अलग-अलग व्यवहार करते हैं, इसलिए अपने fixture में उनके semantics दर्ज करें।

हर dangerous permission boundary के लिए negative test रखें। Agent deployment बना सकता है तो test करें कि वह उसे promote न कर सके। Issue पर comment कर सकता है तो test करें कि labels या assignees न बदल सके। Staging secret value लिख सकता है तो, अगर API read के बिना write support करती है, test करें कि वह उसे पढ़कर वापस न ला सके। ये tests बाद में scope edit होने पर access के चुपचाप बढ़ने से रोकते हैं।

Failed 403 से task या grant बदलना चाहिए

403 Forbidden response contract के बारे में evidence है। इसे provider की सबसे broad permission मांगने का reflex न बनाएँ।

मैंने यह failure pattern बार-बार देखा है। Agent branch बनाता है और fix commit करता है, फिर pull request खोलते समय denied हो जाता है। पता चलता है कि provider की pull request permission review dismissal या व्यापक discussion edits की अनुमति भी देती है। Agent को काम पूरा कराना है, इसलिए permission दे दी जाती है। कुछ दिनों बाद वही agent stale pull requests को "clean up" करने लगता है और assignment से बाहर का काम edit करता है।

पहले denial में design question छिपा था: क्या pull request खोलने के लिए वह broader capability ज़रूरी है, और क्या team उसके side effects स्वीकार कर सकती है? इसके कई ईमानदार जवाब हो सकते हैं:

• Full endpoint surface test करने और accepted risk दर्ज करने के बाद permission दें।
• Task बदल दें ताकि agent branch तैयार करे और human pull request खोले।
• अलग provider identity या resource इस्तेमाल करें, जहाँ broad grant केवल intended repository तक पहुँचे।
• Provider API के सामने narrow action service रखें, जो fixed resource और branch constraints वाली केवल pull request creation request स्वीकार करे।

गलत जवाब यह है कि हर उस scope को जोड़ दें जो red responses को green बना दे। इससे authorization errors delayed incidents में बदल जाते हैं।

Request bodies की भी जाँच करें। कई API permission models endpoint को authorize करते हैं, लेकिन safe और harmful values में फर्क नहीं करते। POST /deployments में एक ही permission के तहत staging और production दोनों स्वीकार हो सकते हैं। PATCH /projects/{id} harmless description update और harmful visibility change दोनों की अनुमति दे सकता है। Provider इन operations को अलग नहीं कर सकता तो boundary endpoint से ऊपर रखें। Human approval ज़रूरी करें, dedicated target इस्तेमाल करें या raw API access के बजाय purpose-built operation दें।

Denied call को उस कारण सहित ledger में दर्ज करें जिसके आधार पर आपने उसे जोड़ा या अस्वीकार किया। छह महीने बाद यही record समझाएगा कि agent branch बना सकता है लेकिन repository rename नहीं कर सकता। इसके बिना कोई boundary को मनमाना कहकर जल्दबाज़ी में उसे चौड़ा कर देगा।

Approval gates बाकी high-consequence calls को रोकते हैं

संकीर्ण provider permissions agent की संभावित actions घटाती हैं। Approval gates उन अनुमति प्राप्त actions में human decision जोड़ते हैं जिनके परिणाम अब भी महत्वपूर्ण हैं, जैसे external payment operation, महत्वपूर्ण host पर SSH command या production service पर write।

Approval को broad credentials देने का बहाना न बनाएँ। एक click वाला confirmation स्पष्ट bad request रोक सकता है, लेकिन लोग repetitive cards जल्दी approve कर देते हैं, खासकर जब agent को job पूरा करने के लिए कई routine calls करनी हों। Permission boundary को approval card दिखने से पहले ही पूरी categories of actions को रोकना चाहिए।

Approval वहाँ इस्तेमाल करें जहाँ human context decision बदलता है। Deployment technically authorized हो सकता है, लेकिन incident के दौरान अनुचित हो सकता है। Branch delete करना allowed हो सकता है, लेकिन गलत, अगर दूसरा engineer उसका उपयोग कर रहा हो। Approval prompt उस moment पर actual target और requested action दिखा सकता है जब व्यक्ति उनका मूल्यांकन कर सके।

Sallyport API और SSH credentials को अपने encrypted macOS vault में रखता है और secret agent को दिखाए बिना requested action चलाता है। इसका session authorization और per-credential approval controls ऐसे calls में व्यक्ति को बीच में ला सकते हैं जहाँ इसकी ज़रूरत हो। फिर भी approved credential कहाँ तक पहुँच सकता है, यह provider-side scope design ही तय करता है।

ऐसे audit records रखें जो दो अलग सवालों का जवाब दें: किस agent process को act करने की permission मिली और उसने कौन-सी individual API calls कीं। ये अलग records हैं। Process approval यह साबित करती है कि किसी human ने उस run को credential इस्तेमाल करने दिया, लेकिन यह नहीं बताती कि run ने pull request बनाई, environment variable बदला या failed deletion attempt की। Permission change और incident, दोनों के बाद records की समीक्षा करें।

Scope reviews को calendar promise नहीं, trigger चाहिए

Permission reviews तब काम करते हैं जब कोई engineering event उन्हें trigger करता है। अस्पष्ट quarterly reminder अक्सर पुराने tokens तब खोजता है जब किसी को उनका उद्देश्य याद नहीं रहता। Review को task changes, नए endpoints, resource expansion, provider permission changes और agent workflow edits से जोड़ें।

Endpoint ledger को उस code के साथ रखें जो agent को invoke करता है। जब pull request agent के tool instructions बदलती है या API call जोड़ती है, तो ledger और उसके positive तथा negative tests का update अनिवार्य करें। इससे permission decision उसी behavior के पास रहती है जिसे इसकी ज़रूरत है।

Revocation की समीक्षा उसकी ज़रूरत पड़ने से पहले करें। Test credential हटाएँ और verify करें कि पहले allowed request fail होती है। Service identity disable करें और confirm करें कि running agent cached session से जारी नहीं रह सकता। जाँचें कि provider ने refresh tokens या duplicate credentials तो जारी नहीं किए जो वही access बनाए रखें। Teams अक्सर इन paths को incident के दौरान खोजती हैं, जब जवाब सबसे कम उपयोगी होता है।

छोटे changes में permission creep पर नज़र रखें। Workflow logs पढ़ने की request jobs दोबारा चलाने की permission में बदल सकती है। एक issue update करने की request organization-wide issue administration में बदल सकती है। एक environment access की request "just in case" production fallback बन सकती है। हर added call को उसी सवाल से गुज़रना चाहिए: क्या agent इसके बिना अपना stated task पूरा कर सकता है?

अगर जवाब नहीं है, तो call को सक्षम करने वाला सबसे छोटा grant जोड़ें और उसके निकटतम harmful neighbor के आसपास denial test जोड़ें। अगर जवाब हाँ है, तो उसे बाहर रखें। यह अनुशासन short term में agent failures को अधिक visible बनाता है। साथ ही malformed instruction, confused model या compromised process को वह authority लेने से रोकता है जिसे देने का किसी का इरादा नहीं था।