مدیریت رمزها

Triggerfish هرگز بیانات اعتبار را در فایل‌های پیکربندی ذخیره نمی‌کند. تمام رمزها — کلیدهای API، توکن‌های OAuth، بیانات اعتبار یکپارچه‌سازی — در ذخیره‌سازی امن بومی پلتفرم نگهداری می‌شوند: کلیدزنجیر سیستم‌عامل برای سطح شخصی، یا سرویس خزانه برای سطح سازمانی. Plugin‌ها و عامل‌ها از طریق SDK با بیانات اعتبار تعامل می‌کنند که کنترل‌های دسترسی سختگیرانه‌ای اجرا می‌کند.

بک‌اندهای ذخیره‌سازی

سطح	بک‌اند	جزئیات
شخصی	کلیدزنجیر سیستم‌عامل	macOS Keychain، Linux Secret Service (از طریق D-Bus)، Windows Credential Manager
سازمانی	یکپارچه‌سازی خزانه	HashiCorp Vault، AWS Secrets Manager، Azure Key Vault یا سایر سرویس‌های خزانه سازمانی

در هر دو حالت، رمزها در حالت استراحت توسط بک‌اند ذخیره‌سازی رمزنگاری می‌شوند. Triggerfish رمزنگاری خود را برای رمزها پیاده‌سازی نمی‌کند — به سیستم‌های ذخیره‌سازی رمز هدفمند و بازرسی‌شده واگذار می‌کند.

در پلتفرم‌هایی بدون کلیدزنجیر بومی (Windows بدون Credential Manager، کانتینرهای Docker)، Triggerfish به فایل JSON رمزنگاری‌شده در ~/.triggerfish/secrets.json بازمی‌گردد. ورودی‌ها با AES-256-GCM با استفاده از کلید ۲۵۶ بیتی وابسته به ماشین ذخیره‌شده در ~/.triggerfish/secrets.key (مجوز: 0600) رمزنگاری می‌شوند. هر ورودی از IV تصادفی ۱۲ بایتی جدید در هر نوشتن استفاده می‌کند. فایل‌های رمز متن ساده قدیمی به‌صورت خودکار هنگام اولین بارگذاری به قالب رمزنگاری‌شده مهاجرت می‌کنند.

سطح شخصی نیاز به هیچ پیکربندی برای رمزها ندارد. وقتی یکپارچه‌سازی را در طول راه‌اندازی (triggerfish dive) متصل می‌کنید، بیانات اعتبار به‌صورت خودکار در کلیدزنجیر سیستم‌عامل ذخیره می‌شوند. نیازی به نصب یا پیکربندی چیزی فراتر از آنچه سیستم‌عامل شما قبلاً ارائه می‌دهد ندارید. :::

مراجع رمز در پیکربندی

Triggerfish از مراجع secret: در triggerfish.yaml پشتیبانی می‌کند. به جای ذخیره بیانات اعتبار به‌صورت متن ساده، آن‌ها را با نام ارجاع می‌دهید و از کلیدزنجیر سیستم‌عامل در هنگام راه‌اندازی رفع می‌شوند.

models:
  providers:
    anthropic:
      apiKey: "secret:provider:anthropic:apiKey"
    openai:
      apiKey: "secret:provider:openai:apiKey"

channels:
  telegram:
    botToken: "secret:channel:telegram:botToken"

رفع‌کننده یک پیمایش عمقی از فایل پیکربندی انجام می‌دهد. هر مقدار رشته‌ای که با secret: شروع شود با ورودی کلیدزنجیر متناظر جایگزین می‌شود. اگر رمز ارجاع‌داده‌شده یافت نشود، راه‌اندازی فوراً با پیام خطای واضح شکست می‌خورد.

مهاجرت رمزهای موجود

اگر بیانات اعتبار متن ساده در فایل پیکربندی خود از نسخه قبلی دارید، دستور مهاجرت آن‌ها را به‌صورت خودکار به کلیدزنجیر منتقل می‌کند:

triggerfish config migrate-secrets

این دستور:

۱. triggerfish.yaml را برای مقادیر بیانات اعتبار متن ساده اسکن می‌کند ۲. هر یک را در کلیدزنجیر سیستم‌عامل ذخیره می‌کند ۳. مقدار متن ساده را با مرجع secret: جایگزین می‌کند ۴. یک پشتیبان از فایل اصلی ایجاد می‌کند

پس از مهاجرت، تأیید کنید که عامل شما به‌درستی شروع به کار می‌کند قبل از حذف فایل پشتیبان. مهاجرت بدون پشتیبان بازگشت‌ناپذیر است. :::

معماری بیانات اعتبار تفویض‌شده

یک اصل امنیتی اساسی در Triggerfish این است که جستجوهای داده با بیانات اعتبار کاربر اجرا می‌شوند، نه بیانات اعتبار سیستمی. این تضمین می‌کند که عامل مدل مجوز سیستم منبع را به ارث می‌برد — کاربر فقط می‌تواند به داده‌هایی دسترسی پیدا کند که مستقیماً هم می‌تواند.

این معماری به معنای:

• عدم اعطای مجوز بیش از حد — عامل نمی‌تواند به داده‌هایی دسترسی پیدا کند که کاربر مستقیماً نمی‌تواند
• بدون حساب‌های سرویس سیستمی — هیچ بیانات اعتبار قدرتمندی وجود ندارد که بتواند به خطر بیفتد
• اجرای سیستم منبع — سیستم منبع (Salesforce، Jira، GitHub و غیره) مجوزهای خود را بر هر جستجو اجرا می‌کند

امنیت پلتفرم‌های سنتی عامل هوش مصنوعی اغلب از یک حساب سرویس سیستمی واحد برای دسترسی به یکپارچه‌سازی‌ها از طرف تمام کاربران استفاده می‌کنند. این بدان معناست که عامل به تمام داده‌های یکپارچه‌سازی دسترسی دارد و به LLM اعتماد می‌شود تا تصمیم بگیرد چه چیزی به هر کاربر نشان داده شود. Triggerfish این خطر را کاملاً حذف می‌کند: جستجوها با توکن OAuth تفویض‌شده خود کاربر اجرا می‌شوند. :::

اجرای SDK Plugin

Plugin‌ها فقط از طریق SDK Triggerfish با بیانات اعتبار تعامل می‌کنند. SDK متدهای آگاه از مجوز ارائه می‌دهد و هر تلاش برای دسترسی به بیانات اعتبار سطح سیستم را مسدود می‌کند.

مجاز: دسترسی به بیانات اعتبار کاربر

def get_user_opportunities(sdk, params):
    # SDK توکن تفویض‌شده کاربر را از ذخیره‌سازی امن بازیابی می‌کند
    # اگر کاربر Salesforce را متصل نکرده باشد، خطای مفید برمی‌گرداند
    user_token = sdk.get_user_credential("salesforce")

    # جستجو با مجوزهای کاربر اجرا می‌شود
    # سیستم منبع کنترل دسترسی را اجرا می‌کند
    return sdk.query_as_user(
        integration="salesforce",
        query="SELECT Id, Name, Amount FROM Opportunity",
        user_id=sdk.current_user_id
    )

مسدود: دسترسی به بیانات اعتبار سیستمی

def get_all_opportunities(sdk, params):
    # این PermissionError ایجاد خواهد کرد -- توسط SDK مسدود شد
    token = sdk.get_system_credential("SALESFORCE_TOKEN")
    return query_salesforce(token, "SELECT * FROM Opportunity")

sdk.get_system_credential() همیشه مسدود است. هیچ پیکربندی برای فعال‌سازی آن، هیچ لغو مدیر و هیچ راه فراری وجود ندارد. این یک قانون امنیتی ثابت است، همانند قانون عدم نوشتن به پایین. :::

ابزارهای رمز قابل فراخوانی توسط LLM

عامل می‌تواند به شما در مدیریت رمزها از طریق سه ابزار کمک کند. نکته مهم اینکه LLM هرگز مقادیر واقعی رمز را نمی‌بیند — ورودی و ذخیره‌سازی خارج از باند رخ می‌دهد.

secret_save

از شما درخواست ورود امن مقدار رمز می‌کند:

• CLI: ترمینال به حالت ورودی مخفی تغییر می‌کند (کاراکترها نمایش داده نمی‌شوند)
• Tidepool: یک پنجره بازشوی ورود امن در رابط وب ظاهر می‌شود

LLM درخواست ذخیره رمز می‌کند، اما مقدار واقعی توسط شما از طریق prompt امن وارد می‌شود. مقدار مستقیماً در کلیدزنجیر ذخیره می‌شود — هرگز از زمینه LLM عبور نمی‌کند.

secret_list

نام‌های تمام رمزهای ذخیره‌شده را لیست می‌کند. هرگز مقادیر را فاش نمی‌کند.

secret_delete

یک رمز را با نام از کلیدزنجیر حذف می‌کند.

جایگزینی آرگومان ابزار

وقتی عامل از ابزاری استفاده می‌کند که به رمز نیاز دارد (مثلاً تنظیم کلید API در متغیر محیطی سرور MCP)، از نحو {{secret:name}} در آرگومان‌های ابزار استفاده می‌کند:

tool_call: set_env_var
arguments: { "key": "API_TOKEN", "value": "{{secret:my-api-token}}" }

زمان اجرا مراجع {{secret:name}} را زیر لایه LLM قبل از اجرای ابزار رفع می‌کند. مقدار رفع‌شده هرگز در تاریخچه مکالمه یا گزارش‌ها ظاهر نمی‌شود.

امنیت جایگزینی {{secret:name}} توسط کد اجرا می‌شود، نه توسط LLM. حتی اگر LLM تلاش کند مقدار رفع‌شده را ثبت یا بازگرداند، لایه سیاست تلاش را در Hook PRE_OUTPUT شناسایی خواهد کرد. :::

متدهای مجوز SDK

متد	رفتار
sdk.get_user_credential(integration)	توکن OAuth تفویض‌شده کاربر را برای یکپارچه‌سازی مشخص‌شده برمی‌گرداند. اگر کاربر یکپارچه‌سازی را متصل نکرده باشد، خطایی با راهنما برمی‌گرداند.
sdk.query_as_user(integration, query)	جستجویی را با بیانات اعتبار تفویض‌شده کاربر روی یکپارچه‌سازی اجرا می‌کند. سیستم منبع مجوزهای خود را اجرا می‌کند.
sdk.get_system_credential(name)	همیشه مسدود. PermissionError ایجاد می‌کند. به‌عنوان رویداد امنیتی ثبت می‌شود.
sdk.has_user_connection(integration)	اگر کاربر یکپارچه‌سازی مشخص‌شده را متصل کرده باشد true و در غیر این صورت false برمی‌گرداند. هیچ داده بیانات اعتبار را فاش نمی‌کند.

دسترسی داده آگاه از مجوز

معماری بیانات اعتبار تفویض‌شده دست در دست سیستم طبقه‌بندی کار می‌کند. حتی اگر کاربر اجازه دسترسی به داده در سیستم منبع داشته باشد، قوانین طبقه‌بندی Triggerfish حاکم بر جایی هستند که آن داده پس از بازیابی می‌تواند جریان یابد.

مثال:

کاربر: «معامله Acme را خلاصه کن و به همسرم بفرست»

مرحله ۱: بررسی مجوز
  --> توکن Salesforce کاربر استفاده شد
  --> Salesforce فرصت Acme را برمی‌گرداند (کاربر دسترسی دارد)

مرحله ۲: طبقه‌بندی
  --> داده‌های Salesforce با طبقه‌بندی CONFIDENTIAL
  --> Taint نشست به CONFIDENTIAL بالا می‌رود

مرحله ۳: بررسی خروجی
  --> همسر = گیرنده EXTERNAL
  --> CONFIDENTIAL --> EXTERNAL: مسدود شد

نتیجه: داده بازیابی شد (کاربر مجوز دارد)، اما قابل ارسال نیست
        (قوانین طبقه‌بندی از نشت جلوگیری می‌کنند)

کاربر دسترسی مشروع به معامله Acme در Salesforce دارد. Triggerfish این را محترم شمرده و داده را بازیابی می‌کند. اما سیستم طبقه‌بندی از جریان آن داده به گیرنده خارجی جلوگیری می‌کند. مجوز دسترسی به داده از مجوز اشتراک‌گذاری آن جداست.

ثبت دسترسی رمز

هر دسترسی به بیانات اعتبار از طریق Hook اجرایی SECRET_ACCESS ثبت می‌شود:

{
  "timestamp": "2025-01-29T10:23:45Z",
  "hook_type": "SECRET_ACCESS",
  "session_id": "sess_456",
  "decision": "ALLOW",
  "details": {
    "method": "get_user_credential",
    "integration": "salesforce",
    "user_id": "user_456",
    "credential_type": "oauth_delegated"
  }
}

تلاش‌های مسدودشده نیز ثبت می‌شوند:

{
  "timestamp": "2025-01-29T10:23:46Z",
  "hook_type": "SECRET_ACCESS",
  "session_id": "sess_456",
  "decision": "BLOCK",
  "details": {
    "method": "get_system_credential",
    "requested_name": "SALESFORCE_TOKEN",
    "reason": "System credential access is prohibited",
    "plugin_id": "plugin_789"
  }
}

تلاش‌های مسدودشده دسترسی به بیانات اعتبار با سطح هشدار بالا ثبت می‌شوند. در استقرارهای سازمانی، این رویدادها می‌توانند اعلان‌هایی به تیم امنیت ارسال کنند. :::

یکپارچه‌سازی خزانه سازمانی

استقرارهای سازمانی می‌توانند Triggerfish را به سرویس خزانه متمرکز برای مدیریت بیانات اعتبار متصل کنند:

سرویس خزانه	یکپارچه‌سازی
HashiCorp Vault	یکپارچه‌سازی API بومی
AWS Secrets Manager	یکپارچه‌سازی AWS SDK
Azure Key Vault	یکپارچه‌سازی Azure SDK
خزانه سفارشی	رابط SecretProvider قابل اتصال

یکپارچه‌سازی خزانه سازمانی ارائه می‌دهد:

• چرخش متمرکز — بیانات اعتبار در خزانه چرخش می‌شوند و به‌صورت خودکار توسط Triggerfish دریافت می‌شوند
• سیاست‌های دسترسی — سیاست‌های سطح خزانه کنترل می‌کنند کدام عامل‌ها و کاربران به کدام بیانات اعتبار دسترسی دارند
• تجمیع بازرسی — گزارش‌های دسترسی بیانات اعتبار از Triggerfish و خزانه قابل همبستگی هستند

آنچه هرگز در فایل‌های پیکربندی ذخیره نمی‌شود

موارد زیر هرگز به‌عنوان مقادیر متن ساده در triggerfish.yaml یا هیچ فایل پیکربندی دیگری ظاهر نمی‌شوند. آن‌ها یا در کلیدزنجیر سیستم‌عامل ذخیره شده و از طریق نحو secret: ارجاع داده می‌شوند، یا از طریق ابزار secret_save مدیریت می‌شوند:

• کلیدهای API ارائه‌دهندگان LLM
• توکن‌های OAuth برای یکپارچه‌سازی‌ها
• بیانات اعتبار پایگاه‌داده
• رمزهای Webhook
• کلیدهای رمزنگاری
• کدهای جفت‌سازی (موقت، فقط در حافظه)

اگر بیانات اعتبار متن ساده در فایل پیکربندی Triggerfish پیدا کردید (مقادیری که مرجع secret: نیستند)، مشکلی پیش آمده. دستور triggerfish config migrate-secrets را اجرا کنید تا آن‌ها را به کلیدزنجیر منتقل کنید. بیانات اعتبار یافت‌شده به‌صورت متن ساده باید فوراً چرخش شوند. :::

صفحات مرتبط

• طراحی امنیت‌محور — مروری بر معماری امنیتی
• قانون عدم نوشتن به پایین — نحوه تکمیل کنترل‌های طبقه‌بندی با جداسازی بیانات اعتبار
• هویت و احراز هویت — نحوه ارتباط هویت کاربر با دسترسی بیانات اعتبار تفویض‌شده
• بازرسی و انطباق — نحوه ثبت رویدادهای دسترسی بیانات اعتبار