Cấu trúc đối tượng Actions

Actions có thể được sử dụng để tạo các công cụ một cách linh hoạt từ các thông số kỹ thuật OpenAPI. Cấu trúc đối tượng actions cho phép bạn chỉ định các tên miền được phép cho các hành động của tác nhân/trợ lý (agent/assistant).

Thông tin thêm: Agents - Actions

Ví dụ

# Example Actions Object Structure
actions:
  # Strict whitelist mode:
  # allowedDomains:
  #   - "swapi.dev"
  #   - "librechat.ai"
  #   - "google.com"
  #   - "https://api.example.com:8443"  # With protocol and port

  # Default SSRF mode with private service exemptions:
  allowedAddresses:
    - "host.docker.internal:11434"    # Permit one private host on one port
    - "10.0.0.5:8080"                 # Permit one private IP on one port

allowedDomains

Khóa:

Tùy chọn

Bối cảnh bảo mật (Bảo vệ SSRF)

LibreChat bao gồm tính năng bảo vệ SSRF (Server-Side Request Forgery) với hành vi như sau:

Khi allowedDomains KHÔNG được cấu hình:

• Các mục tiêu dễ bị SSRF sẽ bị chặn theo mặc định
• Tất cả các tên miền bên ngoài khác đều được cho phép

Khi allowedDomains ĐƯỢC cấu hình:

• Chỉ các tên miền trong danh sách mới được cho phép
• Các mục tiêu Internal/SSRF có thể được cho phép bằng cách thêm chúng một cách rõ ràng vào danh sách

Các mục tiêu SSRF bị chặn bao gồm:

• Các địa chỉ Localhost (localhost, 127.0.0.1, ::1)
• Dải IP riêng (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Các địa chỉ link-local (169.254.0.0/16, bao gồm các IP metadata của cloud)
• Các TLD nội bộ (.internal, .local, .localhost)
• Các tên dịch vụ nội bộ phổ biến (redis, mongodb, postgres, api, v.v.)

Nếu các hành động của bạn cần truy cập vào các dịch vụ nội bộ, hãy thêm chúng vào danh sách trắng allowedDomains nghiêm ngặt, hoặc để trống allowedDomains và thêm chính xác dịch vụ riêng tư đó vào allowedAddresses.

Định dạng mẫu

Mảng allowedDomains hỗ trợ một số định dạng sau:

1. Chỉ tên miền - Cho phép tất cả các giao thức và cổng:

   allowedDomains:
     - "api.example.com"

2. Với giao thức - Giới hạn ở giao thức cụ thể:

   allowedDomains:
     - "https://api.example.com"

3. Với giao thức và cổng - Giới hạn ở giao thức và cổng cụ thể:

   allowedDomains:
     - "https://api.example.com:8443"

4. Các địa chỉ nội bộ (phải được cho phép một cách rõ ràng):

   allowedDomains:
     - "192.168.1.100"
     - "internal-api.local"

Ví dụ:

allowedDomains:
  - "swapi.dev"
  - "librechat.ai"
  - "google.com"
  - "https://secure-api.example.com:443"
  - "192.168.1.50"  # Internal service (explicitly allowed)

allowedAddresses

allowedAddresses là một danh sách miễn trừ cho khối IP riêng SSRF — không phải là danh sách trắng tên miền. Đây là công cụ phù hợp khi bạn muốn cho phép một hoặc hai dịch vụ nội bộ/riêng tư cụ thể mà không hạn chế những gì Actions của bạn có thể truy cập trên internet công cộng.

Khi nào nên sử dụng thay vì allowedDomains

allowedDomains là một danh sách trắng nghiêm ngặt: khi được thiết lập, chỉ những mục được liệt kê mới có thể truy cập được. Việc thêm một IP riêng vào đó để cho phép, ví dụ, một API nội bộ tự lưu trữ cũng sẽ chặn mọi endpoint hành động công khai mà bạn chưa liệt kê.

allowedAddresses chỉ được sử dụng khi allowedDomains không được cấu hình. Nó cho phép các mục tiêu host:port riêng tư cụ thể trong khi vẫn giữ cho phần còn lại của internet công cộng có thể truy cập được thông qua chính sách SSRF mặc định.

actions:
  allowedAddresses:
    - "host.docker.internal:11434"
    - "10.0.0.5:8080"
  # allowedDomains is intentionally not set — public destinations
  # remain reachable, only listed private host:port services are exempted.

Nếu allowedDomains được cấu hình, nó sẽ là nguồn xác thực chính: các dịch vụ riêng tư phải được liệt kê tại đó thay vì dựa vào allowedAddresses.

Các mục nhập hợp lệ

• Tên máy chủ kèm cổng: host.docker.internal:11434, ollama.internal:8080, localhost:11434
• Các giá trị IPv4 riêng tư kèm cổng: 10.0.0.5:8080, 127.0.0.1:11434, 192.168.1.10:443, 169.254.169.254:80
• Các ký tự IPv6 riêng tư trong ngoặc vuông kèm cổng: [::1]:11434, [fc00::1]:8080, [fe80::1]:8080

Các mục bị từ chối (được xác thực khi tải cấu hình)

• URLs / đường dẫn / dải CIDR: http://10.0.0.5, 10.0.0.0/24, /path
• Tên máy chủ hoặc địa chỉ IP thuần: localhost, 10.0.0.5, ::1, [::1] — mọi mục nhập phải bao gồm cổng
• Các cổng không hợp lệ: localhost:0, localhost:65536, localhost:http
• Các IP công khai (Public IP literals): 8.8.8.8:53, 1.1.1.1:53, [2001:4860::8888]:443 — trường này được giới hạn trong không gian IP riêng tư; các IP công khai không phải là mục tiêu SSRF và việc miễn trừ IP công khai không có mục đích phòng thủ nào.

Tin cậy hostname

Một mục hostname tin tưởng bất kỳ IP nào mà hostname đó phân giải tới tại thời điểm chạy trên cổng được liệt kê. Nếu DNS cho một hostname được liệt kê bị xoay vòng hoặc bị chiếm quyền điều khiển để trỏ đến một IP riêng khác, thì ngoại lệ đó sẽ đi theo. Chỉ liệt kê các hostname mà bạn kiểm soát DNS. Hãy ưu tiên sử dụng IP cụ thể khi có thể.