Ajanların Araç Erişimini Güvenceye Alma
Ajan araç izinlerine en az ayrıcalık ilkelerini uygulayın, yıkıcı eylemlerden önce onay adımları ekleyin ve anormal davranışları tespit etmek için ajan eylem günlüklerini denetleyin.
Ajanların Araç Erişimini Güvenceye Alma, CoddyKit'te ücretsiz bir AI Engineering Academy dersidir. Bu, 4 dersinin 3. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, AI Engineering Academy öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. AI Engineering Academy kursu toplamda 4 dersten oluşur.
Araç Erişimi Güvenliği Sorunu
Bir yapay zekâ aracısına bir araç verdiğinizde, ona gerçek dünyada eylemler gerçekleştirme yeteneği kazandırırsınız. E-posta gönderen, SQL sorguları çalıştıran, ödeme API'lerini çağıran veya dosyaları değiştiren bir araç; aracı bir istem enjeksiyonuyla ele geçirilirse ya da yalnızca bir hata yaparsa ciddi zarara yol açabilir. Aracı sistemlerin araç erişimini güvence altına almak, araç katmanınızı herhangi bir tekil araç kullanımından doğabilecek zararın sınırlandırılacağı, denetlenebileceği ve mümkün olduğunda geri alınabileceği şekilde tasarlamak anlamına gelir.
En Az Ayrıcalık İlkesi
En az ayrıcalık ilkesini her araca uygulayın: aracıya, kendisine verilen görevi tamamlamak için gereken en az erişimi verin ve bundan fazlasını vermeyin. Aracının müşteri kayıtlarını okuması gerekiyorsa, bakım için kullandığınız tam yönetici bağlantısı yerine salt okunur bir veritabanı bağlantısı verin. Bildirim gönderiyorsa API anahtarının kapsamını yalnızca bildirim uç noktasıyla sınırlandırın. En az ayrıcalık, herhangi bir güvenlik olayının etki alanını sınırlar.
from enum import Enum
from dataclasses import dataclass
class Permission(Enum):
READ_CUSTOMER_PROFILE = 'read_customer_profile'
SEND_NOTIFICATION = 'send_notification'
READ_ORDER_HISTORY = 'read_order_history'
WRITE_CUSTOMER_PROFILE = 'write_customer_profile' # higher privilege
PROCESS_REFUND = 'process_refund' # highest risk
@dataclass
class AgentIdentity:
agent_id: str
allowed_permissions: set[Permission]
# Support chat agent: read-only + send notification only
SUPPORT_AGENT = AgentIdentity(
agent_id='support-agent-v1',
allowed_permissions={
Permission.READ_CUSTOMER_PROFILE,
Permission.READ_ORDER_HISTORY,
Permission.SEND_NOTIFICATION # can notify, but NOT write or refund
}
)
# NOT: give every agent all permissions for convenienceİzin Denetimli Araç Çalıştırma
En az ayrıcalığı yalnızca tasarım katmanında değil, çalıştırma katmanında da zorunlu kılın. Her araç çağrısı, çağrıyı yapan aracının söz konusu eylem için gerekli izne sahip olduğunu doğrulayan bir izin denetiminden geçmelidir. Bu denetim istemde değil kodda uygulandığı için aracı veya bir istem enjeksiyonu tarafından atlanamaz.
class ToolGateway:
def __init__(self, agent: AgentIdentity):
self.agent = agent
self.audit_log = []
def execute_tool(self, tool_name: str, required_permission: Permission, tool_fn, **kwargs) -> dict:
# Permission check - enforced in code, not in the LLM prompt
if required_permission not in self.agent.allowed_permissions:
self.log_denied(tool_name, required_permission, kwargs)
raise PermissionError(
f'Agent {self.agent.agent_id} does not have permission: {required_permission.value}'
)
# Execute tool
result = tool_fn(**kwargs)
self.log_allowed(tool_name, kwargs, result)
return result
def log_denied(self, tool: str, permission: Permission, args: dict):
entry = {'type': 'DENIED', 'agent': self.agent.agent_id, 'tool': tool, 'permission': permission.value, 'args': args}
self.audit_log.append(entry)
print(f'SECURITY: Permission denied - {entry}')
def log_allowed(self, tool: str, args: dict, result):
entry = {'type': 'ALLOWED', 'agent': self.agent.agent_id, 'tool': tool, 'args': args}
self.audit_log.append(entry)
gateway = ToolGateway(SUPPORT_AGENT)
# This will succeed (agent has READ permission)
gateway.execute_tool('read_profile', Permission.READ_CUSTOMER_PROFILE, read_customer_profile, user_id='123')
# This will raise PermissionError (agent lacks PROCESS_REFUND permission)
gateway.execute_tool('process_refund', Permission.PROCESS_REFUND, process_refund, order_id='456', amount=50.00)Yıkıcı Eylemler İçin Onay Adımları
Bazı eylemler geri alınamaz veya yüksek etkilidir: kayıtları silmek, toplu e-posta göndermek ve finansal işlemleri gerçekleştirmek. Aracının bu tür eylemlerden herhangi birini gerçekleştirmesinden önce açık insan onayı alınmasını zorunlu kılın. Aracı, gerçekleştirmek istediği eylemi ve nedenini önerir; bir insan bunu onaylar veya reddeder ve ancak bundan sonra çalıştırma devam eder. Bu onay kapısı, aracı hatalarına ve enjeksiyon kaynaklı kötüye kullanıma karşı en etkili tek savunmadır.
HIGH_RISK_ACTIONS = {
'delete_customer_record',
'send_bulk_email',
'process_refund_over_100',
'deploy_code',
'revoke_user_access'
}
def execute_with_confirmation(tool_name: str, tool_args: dict, agent_reasoning: str) -> dict:
if tool_name in HIGH_RISK_ACTIONS:
# Pause and request human approval
approval_request = {
'action': tool_name,
'arguments': tool_args,
'agent_reasoning': agent_reasoning,
'risk_level': 'HIGH'
}
approval = request_human_approval(approval_request) # blocks until human responds
if not approval.approved:
return {'status': 'rejected', 'reason': approval.rejection_reason}
# Log the approval for audit trail
log_approval(tool_name, tool_args, approved_by=approval.approver_id)
# Execute only after confirmation
return execute_tool(tool_name, **tool_args)Araç Kapsamlandırma: Zaman, Kullanıcı ve Veri Sınırları
İzin türlerinin ötesinde, araç erişimini üç boyutta kapsamlandırın. Zaman sınırları: aracının oturumu sona erdikten sonra süresi dolan API anahtarları veya belirteçler. Kullanıcı sınırları: kullanıcı A'ya yardımcı olan bir aracı, kendisine böyle bir talimat verilse bile kullanıcı B'nin verilerine asla erişmemelidir. Veri sınırları: müşteri destek aracısı, tüm müşterilerin verileri yerine yalnızca o anda yardım ettiği müşterinin verilerine erişmelidir. Bu sınırları aracı istemlerinde değil, araç uygulamalarınızda uygulayın.
class ScopedCustomerTool:
def __init__(self, current_user_id: str, session_token: str):
self.user_id = current_user_id # agent can only access THIS user's data
self.token = session_token # expires at end of session
def get_customer_profile(self) -> dict:
# Hardcoded to current user - agent cannot change this via prompt
return db.query(
'SELECT * FROM customers WHERE id = %s',
(self.user_id,) # parameterized, always this user's ID only
)
def get_order_history(self, limit: int = 10) -> list:
# Even if the agent says 'get orders for user 999', it gets self.user_id
return db.query(
'SELECT * FROM orders WHERE customer_id = %s ORDER BY date DESC LIMIT %s',
(self.user_id, min(limit, 50)) # cap limit too
)
# Inject scoped tool into agent - cannot be overridden by prompt
def create_support_agent(user_id: str, session_token: str):
scoped_tools = ScopedCustomerTool(user_id, session_token)
return AgentExecutor(llm=llm, tools=[scoped_tools.get_customer_profile, scoped_tools.get_order_history])Araç Bağımsız Değişkenlerinde Girdi Doğrulama
Aracılar, araç bağımsız değişkenlerini metin olarak üretir. Herhangi bir aracı çalıştırmadan önce tüm bağımsız değişkenleri katı bir şemaya göre doğrulayın. Bu, şunları önler: araç parametreleri üzerinden SQL enjeksiyonu, yol geçişi saldırıları (aracının dosya yolu olarak '../../../etc/passwd' göndermesi), SSRF saldırıları (aracının 'uzak URL' parametresi olarak dahili bir hizmet URL'si göndermesi) ve beklenmedik davranışa yol açabilecek tam sayı taşmaları veya aralık dışı değerler.
from pydantic import BaseModel, validator, constr, confloat
import re
class SendEmailArgs(BaseModel):
to: str
subject: constr(max_length=200)
body: constr(max_length=10000)
@validator('to')
def must_be_company_email(cls, v):
if not re.match(r'^[^@]+@(?:yourcorp\.com|partner\.com)$', v):
raise ValueError('Email must be sent to yourcorp.com or partner.com domains only')
return v
class ReadFileArgs(BaseModel):
filename: constr(pattern=r'^[a-zA-Z0-9_\-\.]+$') # alphanumeric only, no path traversal
@validator('filename')
def no_parent_directory(cls, v):
if '..' in v or '/' in v or '\\' in v:
raise ValueError('Path traversal detected')
return v
# Validate before execution
def validated_send_email(args_dict: dict) -> dict:
args = SendEmailArgs(**args_dict) # raises ValueError on invalid input
return send_email(args.to, args.subject, args.body)Değiştirilemez Denetim Günlüğü Kaydı
Bir aracı tarafından yapılan her araç çağrısı değiştirilemez bir denetim günlüğüne kaydedilmelidir. Günlük girdisi şunları içermelidir: aracının kimliği ve oturum kimliği, araç adı ve tüm bağımsız değişkenler, dönüş değeri, zaman damgası ve aracının çağrıyı yapma gerekçesi. Değiştirilemez olması, aracının veya bir saldırganın günlük girdilerini silemeyeceği ya da değiştiremeyeceği anlamına gelir. Yalnızca eklemeli depolama kullanın (bulut günlük hizmetleri, bir kez yazılabilen veritabanları veya WORM depolaması).
import hashlib
import json
import time
class ImmutableAuditLog:
def __init__(self, log_backend):
self.backend = log_backend # e.g., CloudWatch, BigQuery, or append-only file
self.previous_hash = '0' * 64 # genesis hash
def record(self, agent_id: str, tool_name: str, args: dict, result, reasoning: str):
entry = {
'agent_id': agent_id,
'tool': tool_name,
'args': args,
'result_summary': str(result)[:500], # truncate large results
'reasoning': reasoning[:1000],
'timestamp': time.time(),
'previous_hash': self.previous_hash # chain entries like a blockchain
}
entry_json = json.dumps(entry, sort_keys=True)
entry['hash'] = hashlib.sha256(entry_json.encode()).hexdigest()
self.backend.append(entry) # append-only, never update
self.previous_hash = entry['hash']
return entry['hash']Anormal Aracı Davranışını Algılama
İzin kapıları ve denetim günlükleri olsa bile, bir aracının ele geçirildiğini veya beklenmedik davrandığını gösteren anormal davranış örüntülerini izleyin. Anomali sinyalleri şunları içerir: bir destek aracısının daha önce hiç çağırmadığı araçları aniden çağırması, tek bir aracıdan gelen araç çağrılarının sıklığında olağandışı artış, şüpheli biçimde normdan sapan bağımsız değişkenler (olağandışı uzun dizeler, garip karakter dizileri) veya olağandışı saatlerde gerçekleşen çağrılar.
from collections import Counter
class AgentBehaviorMonitor:
def __init__(self):
self.tool_call_counts = Counter() # tracks historical tool usage
self.arg_length_history = {} # tracks typical argument lengths
def record_and_check(self, agent_id: str, tool_name: str, args: dict) -> list[str]:
key = f'{agent_id}:{tool_name}'
anomalies = []
self.tool_call_counts[key] += 1
# Flag tools never called before by this agent
if self.tool_call_counts[key] == 1 and tool_name not in COMMON_TOOLS:
anomalies.append(f'First time agent {agent_id} called unusual tool: {tool_name}')
# Flag unusually long arguments (potential injection payload)
total_arg_length = sum(len(str(v)) for v in args.values())
if tool_name not in self.arg_length_history:
self.arg_length_history[tool_name] = []
self.arg_length_history[tool_name].append(total_arg_length)
if len(self.arg_length_history[tool_name]) > 10:
avg = sum(self.arg_length_history[tool_name]) / len(self.arg_length_history[tool_name])
if total_arg_length > avg * 5:
anomalies.append(f'Unusually long arguments for {tool_name}: {total_arg_length} chars (avg: {avg:.0f})')
return anomaliesBelirteç Süresinin Dolması ve Oturum Kapsamlandırması
Aracı oturumlarının tanımlı bir ömrü olmalıdır. Bir oturum başladığında aracıya kısa ömürlü belirteçler veya kimlik bilgileri verin ve oturum sona erdiğinde bunları iptal edin. Bir aracının oturumu yürütme sırasında ele geçirilirse, saldırganın ele geçirilen oturumdan yararlanma yeteneği belirtecin süresinin dolmasıyla sınırlanır. Oturum kapsamlandırması ayrıca tek bir ele geçirilmiş aracının günler sonra gerçekleştirilecek takip saldırılarında kullanılmasını önler.
import secrets
import time
class SessionTokenManager:
def __init__(self, ttl_seconds=3600):
self.tokens = {} # token -> (agent_id, user_id, expires_at)
self.ttl = ttl_seconds
def issue_token(self, agent_id: str, user_id: str) -> str:
token = secrets.token_urlsafe(32)
expires_at = time.time() + self.ttl
self.tokens[token] = (agent_id, user_id, expires_at)
return token
def validate_token(self, token: str) -> dict | None:
if token not in self.tokens:
return None
agent_id, user_id, expires_at = self.tokens[token]
if time.time() > expires_at:
del self.tokens[token] # clean up expired token
return None
return {'agent_id': agent_id, 'user_id': user_id}
def revoke_token(self, token: str):
self.tokens.pop(token, None)
token_manager = SessionTokenManager(ttl_seconds=1800) # 30-minute sessionsAraç Güvenliğini Sınama
Saldırıları benzeterek araç güvenliği katmanınızı sınayın: yetkisiz bir aracıyla kısıtlı bir aracı çağırmayı deneyin, yol geçişi bağımsız değişkenleri sağlayın, araç parametrelerine talimat dizeleri enjekte edin ve süresi dolmuş belirteçlerle araç çağırmayı deneyin. Kapsamlı bir araç güvenliği test paketi tüm izin sınırlarını, tüm doğrulama kurallarını ve tüm anomali algılama tetikleyicilerini kapsamalıdır.
Geri Alınabilirlik İçin Tasarlama
Mümkün olduğunda araçları geri alınabilir veya aşamalı olacak şekilde tasarlayın. Bir kaydı hemen silmek yerine, geri yüklenebilmesi için silinmiş olarak bir silme işaretiyle işaretleyin. Bir e-postayı hemen göndermek yerine, 5 dakikalık bir inceleme penceresinden sonra çalıştırılan bir 'gönderilmeyi bekleyen' kuyruğuna koyun. Finansal işlemleri sonuçlandırmadan önce bekletme aşamasıyla hazırlayın. Geri alınabilirlik güvenlik riskini ortadan kaldırmaz, ancak başarılı saldırıların etkisini büyük ölçüde azaltır.
Hızlı Kontrol
Bu derste aracı sistemlerin araç erişimini güvence altına alma konusundaki anlayışınızı sınayın.
Ders Özeti
Bu derste şunları öğrendiniz: en az ayrıcalık ilkesi, araç izinlerini her bir aracı rolünün gerçekten ihtiyaç duyduğu şeylerle sınırlar; kod düzeyindeki izin kapıları, bu izinleri istem enjeksiyonuyla aşılamayacak şekilde uygular; yüksek riskli eylemler için insan onayı adımları ise geri alınamaz işlemler gerçekleştirilmeden önce son bir güvenlik katmanı sağlar. Sırada LLM uygulamalarında yapılandırılmış bir kırmızı takım çalışması yürütmek var.
Sıkça Sorulan Sorular
“Ajanların Araç Erişimini Güvenceye Alma” dersi ücretsiz mi?
Evet — “Ajanların Araç Erişimini Güvenceye Alma” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve AI Engineering Academy kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. AI Engineering Academy kursu toplamda 4 dersten oluşur.
“Ajanların Araç Erişimini Güvenceye Alma” dersinde ne öğreneceğim?
Ajan araç izinlerine en az ayrıcalık ilkelerini uygulayın, yıkıcı eylemlerden önce onay adımları ekleyin ve anormal davranışları tespit etmek için ajan eylem günlüklerini denetleyin. AI Engineering Academy ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.
AI Engineering Academy öğrenmeye başlamak için deneyim gerekli mi?
Önceden deneyim gerekmez. CoddyKit'te AI Engineering Academy, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 3. dersidir.
“Ajanların Araç Erişimini Güvenceye Alma” dersi ne kadar sürer?
Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.
Bu AI Engineering Academy dersinde kod yazıp çalıştırabilir miyim?
Evet. Her AI Engineering Academy dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.
Bu kursun tüm dersleri
- İstem Enjeksiyonu Saldırıları Sınıflandırması
- RAG Sistemlerinde Enjeksiyonlara Karşı Savunma
- Ajanların Araç Erişimini Güvenceye Alma
- LLM Uygulamanızda Kırmızı Ekip Çalışması