Chuyển tới nội dung chính

Bảo mật

Hermes Agent được thiết kế với mô hình bảo mật có chiều sâu phòng thủ. Trang này bao gồm mọi ranh giới bảo mật — từ phê duyệt lệnh đến cách ly vùng chứa cho đến ủy quyền người dùng trên nền tảng nhắn tin.

Tổng quan​

Mô hình bảo mật có bảy lớp:

  1. Ủy quyền người dùng — ai có thể nói chuyện với nhân viên hỗ trợ (danh sách cho phép, ghép nối DM)
  2. Phê duyệt lệnh nguy hiểm — con người tham gia vào các hoạt động phá hoại
  3. Cách ly vùng chứa — Hộp cát Docker/Singularity/Modal với cài đặt cứng
  4. Lọc thông tin xác thực MCP — cách ly biến môi trường cho các quy trình con MCP
  5. Quét tệp ngữ cảnh — phát hiện nội dung nhắc nhở trong tệp dự án
  6. Cách ly nhiều phiên — các phiên không thể truy cập dữ liệu hoặc trạng thái của nhau; đường dẫn lưu trữ công việc định kỳ được tăng cường chống lại các cuộc tấn công truyền tải đường dẫn
  7. Khử trùng đầu vào — các tham số thư mục làm việc trong phần phụ trợ của công cụ đầu cuối được xác thực dựa trên danh sách cho phép để ngăn chặn việc chèn shell

Phê duyệt lệnh nguy hiểm​

Trước khi thực hiện bất kỳ lệnh nào, Hermes sẽ kiểm tra lệnh đó dựa trên danh sách các mẫu nguy hiểm đã được tuyển chọn. Nếu tìm thấy sự trùng khớp, người dùng phải phê duyệt nó một cách rõ ràng.

Chế độ phê duyệt​

Hệ thống phê duyệt hỗ trợ ba chế độ, được định cấu hình qua approvals.mode trong

~/.Hermes/config.yaml

:

approvals:
  mode: manual    # manual | smart | off
  timeout: 60     # seconds to wait for user response (default: 60)

`

| Chế độ | Hành vi |
|------|----------|
| **thủ công** (mặc định) | Luôn nhắc người dùng phê duyệt các lệnh nguy hiểm |
| **thông minh** | Sử dụng LLM phụ trợ để đánh giá rủi ro. Các lệnh có rủi ro thấp (ví dụ: 
`Python -c "print('hello')"

) được tự động phê duyệt. Các lệnh thực sự nguy hiểm sẽ bị tự động từ chối. Các trường hợp không chắc chắn sẽ chuyển sang lời nhắc thủ công. |
| **tắt** | Tắt tất cả các bước kiểm tra phê duyệt - tương đương với việc chạy với 

`
--yolo

. Tất cả các lệnh thực thi mà không có lời nhắc. |

:::warning
Cài đặt 
`approvals.mode: off
` sẽ tắt tất cả các lời nhắc an toàn. Chỉ sử dụng trong các môi trường đáng tin cậy (CI/CD, vùng chứa, v.v.).
:::

###Chế độ YOLO

Chế độ YOLO bỏ qua **tất cả** lời nhắc phê duyệt lệnh nguy hiểm cho phiên hiện tại. Nó có thể được kích hoạt theo ba cách:
1. **Cờ CLI**: Bắt đầu phiên với 
`Hermes --yolo
` hoặc 
`Hermes chat --yolo

2. **Lệnh gạch chéo**: Nhập 

/yolo
` trong phiên để bật/tắt nó
3. **Biến môi trường**: Đặt 
`Hermes_YOLO_MODE=1
``Lệnh 

/yolo
` là **chuyển đổi** — mỗi lần sử dụng sẽ bật hoặc tắt chế độ:

`
> /yolo
  ⚡ YOLO mode ON — all commands auto-approved. Use with caution.`> /yolo
  ⚠ YOLO mode OFF — dangerous commands will require approval.

`
``Chế độ YOLO có sẵn trong cả phiên CLI và cổng. Trong nội bộ, nó đặt biến môi trường 
`Hermes_YOLO_MODE
` được kiểm tra trước mỗi lần thực thi lệnh.

Khi YOLO hoạt động, Hermes hiển thị hai lời nhắc trực quan liên tục nên khó có thể quên rằng lời nhắc phê duyệt bị bỏ qua:
- Dòng biểu ngữ màu đỏ khi bắt đầu phiên khi YOLO đã hoạt động: 

⚠ YOLO mode — all approval prompts bypassed

. Ẩn khi YOLO tắt để biểu ngữ mặc định không bị lộn xộn.
- Một đoạn 

⚠ YOLO
` trên thanh trạng thái trên tất cả các bậc chiều rộng, được cập nhật trực tiếp khi bạn bật hoặc tắt YOLO (trình kết xuất văn bản đa dạng thức và dự phòng văn bản thuần túy).

:::danger
Chế độ YOLO vô hiệu hóa **tất cả** các kiểm tra an toàn lệnh nguy hiểm cho phiên — **ngoại trừ** danh sách chặn đường dây cứng rắn (xem bên dưới). Chỉ sử dụng khi bạn hoàn toàn tin tưởng vào các lệnh được tạo (ví dụ: các tập lệnh tự động hóa đã được kiểm tra kỹ lưỡng trong môi trường dùng một lần).
:::

Đối với các lệnh gạch chéo phiên phá hoại (

/clear

, 

/new
` / 

/reset

, 

/undo

, 

/exit --delete

), CLI cũng nhắc xác nhận trước khi chạy chúng. Xem [Slash Commands — Confirmation prompts for destructive commands](../reference/slash-commands.md#confirmation-prompts-for-destructive-commands).

### Danh sách chặn đường dây cứng (Luôn ở trên sàn)

Một số lệnh rất thảm khốc — xóa sạch hệ thống tập tin không thể đảo ngược, bom phân nhánh, ghi trực tiếp vào thiết bị chặn — đến nỗi Hermes từ chối chạy chúng **bất kể**:
- Đã bật 

--yolo
` / 

/yolo

- 
`approvals.mode: off

- Công việc định kỳ chạy ở chế độ 
`approve
` không đầu
- Người dùng nhấp vào rõ ràng "luôn cho phép"

Danh sách chặn là tầng bên dưới 

--yolo

. Nó ngắt **trước khi** lớp phê duyệt thậm chí còn nhìn thấy lệnh và không có cờ ghi đè. Các mẫu hiện được đề cập (không đầy đủ; được đồng bộ hóa với 
`tools/approval.py::UNRECOVERABLE_BLOCKLIST

):| Mẫu | Tại sao nó cứng rắn |
|---|---|
| 
`rm -rf /
` và các biến thể rõ ràng | Xóa gốc hệ thống tập tin |
| 
`rm -rf --no-preserve-root /
` | Biến thể rõ ràng "vâng, ý tôi là root" |
| 

:(){ :\|:& };:
` (bom bash fork) | Chốt máy chủ cho đến khi khởi động lại |
| 
`mkfs.*
` trên thiết bị gốc được gắn | Định dạng hệ thống trực tiếp |
| 
`dd if=/dev/zero of=/dev/sd*
` | Zero một đĩa vật lý |
| Chuyển các URL không đáng tin cậy tới 
``` sh
` ở cấp cao nhất của rootfs | Vectơ tấn công thực thi mã từ xa quá rộng để được phê duyệt |

Nếu bạn nhấn vào danh sách chặn, lệnh gọi công cụ sẽ trả về lỗi giải thích cho tổng đài viên và không có gì chạy. Nếu một quy trình công việc hợp pháp cần một trong các lệnh này (chẳng hạn như bạn là người vận hành quy trình xóa và cài đặt lại), hãy chạy nó bên ngoài tác nhân.

### Hết thời gian phê duyệt

Khi một dấu nhắc lệnh nguy hiểm xuất hiện, người dùng có một khoảng thời gian có thể định cấu hình để phản hồi. Nếu không có phản hồi nào được đưa ra trong thời gian chờ, lệnh sẽ bị **từ chối** theo mặc định (đóng không thành công).

Định cấu hình thời gian chờ trong 

~/.Hermes/config.yaml

:

`YAML
approvals:
  timeout: 60  # seconds (default: 60)

`

### Điều gì kích hoạt sự phê duyệt

Các mẫu sau kích hoạt lời nhắc phê duyệt (được xác định trong 
`tools/approval.py

):

| Mẫu | Mô tả |
|----------|-------------|
| 
`rm -r
` / 
`rm --recursive
` | Xóa đệ quy |
| 
`rm ... /
` | Xóa trong đường dẫn gốc |
| 
`chmod 777/666
` / 
`o+w
` / 
`a+w
` | Quyền trên thế giới/có thể ghi khác |
| 
`chmod --recursive
` với các phép uốn không an toàn | Thế giới đệ quy/có thể ghi khác (cờ dài) |
| 
`chown -R root
` / 
`chown --recursive root
` | Chown đệ quy về gốc |
| 
`mkfs
` | Định dạng hệ thống tập tin |
| 
`dd if=
` | Sao chép đĩa |
| 

> /dev/sd
` | Viết để chặn thiết bị |
| 
`DROP TABLE/DATABASE
` | THẢ SQL |
| 
`DELETE FROM
` (không có WHERE) | XÓA SQL mà không cần WHERE |
| 
`TRUNCATE TABLE
` | TRUNCATE SQL |
| 

> /etc/
` | Ghi đè cấu hình hệ thống |
| 
`systemctl stop/restart/disable/mask
` | Dừng/khởi động lại/vô hiệu hóa các dịch vụ hệ thống |
| 
`kill -9 -1
` | Giết tất cả các quá trình |
| 
`pkill -9
` | Buộc tiêu diệt quá trình |
| Mẫu bom ngã ba | Bom ngã ba |
| 
`bash -c
` / 
`sh -c
` / 
`zsh -c
` / 
`ksh -c
` | Thực thi lệnh Shell thông qua cờ 

`
-c
` (bao gồm các cờ kết hợp như 

-lc

) |
| 
`Python -e
` / 
`perl -e
` / 
`ruby -e
` / 
`node -c
` | Thực thi tập lệnh thông qua cờ 

-e

/

-c
` |
| 
`curl ... \| sh
` / 
`wget ... \| sh
` | Đưa nội dung từ xa vào shell |
| 
`bash <(curl ...)
` / 
`sh <(wget ...)
` | Thực thi tập lệnh từ xa thông qua thay thế quy trình |
| 
`tee
` đến 

/etc/

, 

~/.SSH/

, 

~/.Hermes/.env
` | Ghi đè tập tin nhạy cảm qua tee |
| 

>
` / 

>>
` đến 

/etc/

, 

~/.SSH/

, 

~/.Hermes/.env
` | Ghi đè tệp nhạy cảm thông qua chuyển hướng |
| 
`xargs rm
` | xargs với rm |
| 
`find -exec rm
` / 
`find -delete
` | Tìm với hành động phá hoại |
| 
`cp

/
`mv

/
`install
` đến 

/etc/
` | Sao chép/di chuyển tập tin vào cấu hình hệ thống |
| 
`sed -i
` / 
`sed --in-place
` trên 

/etc/
` | Chỉnh sửa tại chỗ cấu hình hệ thống |
| 
`pkill

/
`killall
` cổng/cổng | Phòng chống tự chấm dứt |
| 
`gateway run
` với 

&

/
`disown

/
`nohup

/
`setsid
` | Ngăn chặn việc khởi động cổng quản lý dịch vụ bên ngoài |

:::info
**Bỏ qua vùng chứa**: Khi chạy trong các chương trình phụ trợ 
`Docker

, 
`singularity

, 
`modal

, 
`daytona
` hoặc 
`vercel_sandbox

, việc kiểm tra lệnh nguy hiểm sẽ bị **bỏ qua** vì bản thân vùng chứa đó là ranh giới bảo mật. Các lệnh hủy bên trong vùng chứa không thể gây hại cho máy chủ.
:::

### Luồng phê duyệt (CLI)

Trong CLI tương tác, các lệnh nguy hiểm hiển thị lời nhắc phê duyệt nội tuyến:

`
  ⚠️  DANGEROUS COMMAND: recursive delete
      rm -rf /tmp/old-project`[o]nce  |  [s]ession  |  [a]lways  |  [d]eny

Choice [o/s/a/D]:

`
``Bốn lựa chọn:
- **một lần** — cho phép thực hiện một lần
- **session** — cho phép mẫu này trong phần còn lại của phiên
- **luôn luôn** — thêm vào danh sách cho phép vĩnh viễn (được lưu vào 
`config.yaml

)
- **deny** (mặc định) — chặn lệnh

### Luồng phê duyệt (Cổng/Nhắn tin)

Trên nền tảng nhắn tin, tác nhân gửi chi tiết lệnh nguy hiểm đến cuộc trò chuyện và chờ người dùng trả lời:- Trả lời **yes**, **y**, **approve**, **ok**, hoặc **go** để phê duyệt
- Trả lời **no**, **n**, **deny**, hoặc **cancel** để từ chối

Biến môi trường 
`Hermes_EXEC_ASK=1
` được đặt tự động khi chạy cổng.

### Danh sách cho phép vĩnh viễn

Các lệnh được phê duyệt với "luôn luôn" được lưu vào 

~/.Hermes/config.yaml

:

``` yaml

# Permanently allowed dangerous command patterns
command_allowlist:
  - rm
  - systemctl

`
``Các mẫu này được tải khi khởi động và được phê duyệt âm thầm trong tất cả các phiên trong tương lai.

:::tip
Sử dụng 
`Hermes config edit
` để xem xét hoặc xóa các mẫu khỏi danh sách cho phép vĩnh viễn của bạn.
:::

## Ủy quyền người dùng (Cổng)

Khi chạy cổng nhắn tin, Hermes kiểm soát ai có thể tương tác với bot thông qua hệ thống ủy quyền phân lớp.

### Lệnh kiểm tra ủy quyền

Phương pháp 
`_is_user_authoriZed()
` kiểm tra theo thứ tự sau:
1. **Cờ cho phép tất cả trên mỗi nền tảng** (ví dụ: 
`Discord_ALLOW_ALL_USERS=true

)
2. **Danh sách được phê duyệt ghép nối DM** (người dùng được phê duyệt thông qua mã ghép nối)
3. **Danh sách cho phép dành riêng cho từng nền tảng** (ví dụ: 
`Telegram_ALLOWED_USERS=12345,67890

)
4. **Danh sách cho phép toàn cầu** (
`GATEWAY_ALLOWED_USERS=12345,67890

)
5. **Cho phép tất cả toàn cầu** (
`GATEWAY_ALLOW_ALL_USERS=true

)
6. **Mặc định: từ chối**

### Danh sách cho phép của nền tảng

Đặt ID người dùng được phép làm giá trị được phân tách bằng dấu phẩy trong 

~/.Hermes/.env

:

``` bash

# Platform-specific allowlists
Telegram_ALLOWED_USERS=123456789,987654321
Discord_ALLOWED_USERS=111222333444555666
WhatsApp_ALLOWED_USERS=15551234567
Slack_ALLOWED_USERS=U01ABC123

# Cross-platform allowlist (checked for all platforms)
GATEWAY_ALLOWED_USERS=123456789

# Per-platform allow-all (use with caution)
Discord_ALLOW_ALL_USERS=true

# Global allow-all (use with extreme caution)
GATEWAY_ALLOW_ALL_USERS=true

`

:::warning
Nếu **không có danh sách cho phép nào được định cấu hình** và 
`GATEWAY_ALLOW_ALL_USERS
` chưa được đặt, **tất cả người dùng đều bị từ chối**. Cổng ghi lại cảnh báo khi khởi động:

`
No user allowlists configured. All unauthoriZed users will be denied.
Set GATEWAY_ALLOW_ALL_USERS=true in ~/.Hermes/.env to allow open access,
or configure platform allowlists (e.g., Telegram_ALLOWED_USERS=your_id).

`

:::

### Hệ thống ghép nối DM

Để ủy quyền linh hoạt hơn, Hermes bao gồm hệ thống ghép nối dựa trên mã. Thay vì yêu cầu trả trước ID người dùng, những người dùng không xác định sẽ nhận được mã ghép nối một lần mà chủ sở hữu bot phê duyệt thông qua CLI.

**Cách thức hoạt động:**
1. Một người dùng không xác định gửi tin nhắn trực tiếp tới bot
2. Bot trả lời bằng mã ghép nối gồm 8 ký tự
3. Chủ bot chạy 
`Hermes pairing approve <platform <code
` trên CLI
4. Người dùng được chấp thuận vĩnh viễn cho nền tảng đó

Kiểm soát cách xử lý tin nhắn trực tiếp trái phép trong 

~/.Hermes/config.yaml

:

``` yaml
unauthoriZed_dm_behavior: pair

WhatsApp:
  unauthoriZed_dm_behavior: ignore

`

- 
`pair
` là mặc định. DM trái phép sẽ nhận được phản hồi bằng mã ghép nối.

- 
`ignore
` âm thầm loại bỏ các DM trái phép.
- Các phần nền tảng ghi đè mặc định chung, do đó bạn có thể tiếp tục ghép nối trên Telegram trong khi giữ im lặng cho WhatsApp.

**Các tính năng bảo mật** (dựa trên hướng dẫn của OWASP + NIST SP 800-63-4):

| Tính năng | Chi tiết |
|----------|----------|
| Định dạng mã | 8-char từ bảng chữ cái rõ ràng 32-char (không có 0/O/1/I) |
| Sự ngẫu nhiên | Mật mã (
`secrets.choice()

) |
| Mã TTL | Hết hạn 1 giờ |
| Giới hạn tỷ lệ | 1 yêu cầu cho mỗi người dùng trong 10 phút |
| Giới hạn chờ xử lý | Tối đa 3 mã đang chờ xử lý trên mỗi nền tảng |
| Khóa | 5 lần phê duyệt không thành công → khóa 1 giờ |
| Bảo mật tập tin |

chmod 0600
` trên tất cả các tệp dữ liệu ghép nối |
| Ghi nhật ký | Mã không bao giờ được ghi vào thiết bị xuất chuẩn |

**Ghép nối các lệnh CLI:**

``` bash

# List pending and approved users
Hermes pairing list

# Approve a pairing code
Hermes pairing approve Telegram ABC12DEF

# Revoke a user's access
Hermes pairing revoke Telegram 123456789

# Clear all pending codes
Hermes pairing clear-pending

`
``**Lưu trữ:** Dữ liệu ghép nối được lưu trữ trong 

~/.Hermes/pairing/
` với các tệp JSON trên mỗi nền tảng:
- 

\{platform}-pending.JSON

 - yêu cầu ghép nối đang chờ xử lý
- 

\{platform}-approved.JSON

 - người dùng đã được phê duyệt
- 
`_rate_limits.JSON
` — giới hạn tốc độ và theo dõi khóa

## Cách ly container

Khi sử dụng phụ trợ terminal 
`Docker

, Hermes áp dụng biện pháp tăng cường bảo mật nghiêm ngặt cho mọi container.

### Cờ bảo mật Docker

Mọi container đều chạy với các cờ này (được xác định trong 
`tools/environments/Docker.py

):

``` python
_SECURITY_ARGS = [
    "--cap-drop", "ALL",                          # Drop ALL Linux capabilities
    "--cap-add", "DAC_OVERRIDE",                  # Root can write to bind-mounted dirs
    "--cap-add", "CHOWN",                         # Package managers need file ownership
    "--cap-add", "FOWNER",                        # Package managers need file ownership
    "--security-opt", "no-new-privileges",         # Block privilege escalation
    "--pids-limit", "256",                         # Limit process count
    "--tmpfs", "/tmp:rw,nosuid,size=512m",         # Size-limited /tmp
    "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=256m",  # No-exec /var/tmp
    "--tmpfs", "/run:rw,noexec,nosuid,size=64m",   # No-exec /run
]

`

### Giới hạn tài nguyên

Tài nguyên vùng chứa có thể định cấu hình trong 

~/.Hermes/config.yaml

:

`YAML
terminal:
  backend: Docker
  Docker_image: "nikolaik/Python-nodejs:Python3.11-nodejs20"
  Docker_forward_env: []  # Explicit allowlist only; empty keeps secrets out of the container
  container_cpu: 1        # CPU cores
  container_memory: 5120  # MB (default 5GB)
  container_disk: 51200   # MB (default 50GB, requires overlay2 on XFS)
  container_persistent: true  # Persist filesystem across sessions

`

### Tính bền bỉ của hệ thống tập tin
- **Chế độ liên tục** (
`container_persistent: true

): Gắn liên kết 

/workspace
` và 

/root
` từ 

~/.Hermes/sandboxes/Docker/<task_id/

`
- **Chế độ phù du** (
`container_persistent: false

): Sử dụng tmpfs cho không gian làm việc — mọi thứ sẽ bị mất khi dọn dẹp

:::tip
Để triển khai cổng sản xuất, hãy sử dụng chương trình phụ trợ 
`Docker

, 
`modal

, 
`daytona
` hoặc 
`vercel_sandbox
` để tách biệt các lệnh tác nhân khỏi hệ thống máy chủ của bạn. Điều này loại bỏ hoàn toàn sự cần thiết phải phê duyệt lệnh nguy hiểm.
:::

:::warning
Nếu bạn thêm tên vào 
`terminal.Docker_forward_env

, các biến đó sẽ được cố ý đưa vào vùng chứa cho các lệnh đầu cuối. Điều này hữu ích cho các thông tin xác thực dành riêng cho nhiệm vụ như 
`GitHub_TOKEN

, nhưng cũng có nghĩa là mã chạy trong vùng chứa có thể đọc và lọc chúng.
:::

## So sánh bảo mật phần cuối của terminal| Phần cuối | Cô lập | Kiểm tra Cmd nguy hiểm | Tốt nhất cho |
|----------|-------------|-------------------|----------|
| **địa phương** | Không có — chạy trên máy chủ | ✅ Có | Phát triển, người dùng tin cậy |
| **suỵt** | Máy từ xa | ✅ Có | Chạy trên một máy chủ riêng biệt |
| **Docker** | Thùng chứa | ❌ Bỏ qua (container là ranh giới) | Cổng sản xuất |
| **điểm kỳ dị** | Thùng chứa | ❌ Bỏ qua | Môi trường HPC |
| **phương thức** | Hộp cát đám mây | ❌ Bỏ qua | Cách ly đám mây có thể mở rộng |
| **daytona** | Hộp cát đám mây | ❌ Bỏ qua | Không gian làm việc trên đám mây liên tục |
| **vercel_sandbox** | Đám mây microVM | ❌ Bỏ qua | Thực thi trên đám mây với khả năng lưu giữ ảnh chụp nhanh |

## Truyền qua biến môi trường {#environment-variable-passthrough}

Cả 
`execute_code
` và 
`terminal
` đều loại bỏ các biến môi trường nhạy cảm khỏi các tiến trình con để ngăn chặn việc đánh cắp thông tin xác thực bằng mã do LLM tạo. Tuy nhiên, các kỹ năng khai báo 
`required_environment_variables
` một cách hợp pháp cần có quyền truy cập vào các lọ đó.

### Cách thức hoạt động

Hai cơ chế cho phép các biến cụ thể thông qua bộ lọc hộp cát:

**1. Chuyển qua phạm vi kỹ năng (tự động)**

Khi một kỹ năng được tải (thông qua 
`skill_view
` hoặc lệnh 

/skill

) và khai báo 
`required_environment_variables

, bất kỳ vars nào thực sự được đặt trong môi trường sẽ tự động được đăng ký dưới dạng truyền qua. Các vars bị thiếu (vẫn ở trạng thái cần thiết lập) **chưa** được đăng ký.

``` yaml

# In a skill's SKILL.md frontmatter
required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.Google.com/tenor

`
``Sau khi tải kỹ năng này, 
`TENOR_API_KEY
` chuyển sang 
`execute_code

, 
`terminal
` (cục bộ), **và các chương trình phụ trợ từ xa (Docker, Modal)** — không cần cấu hình thủ công.

:::info[Docker & Modal]
Trước v0.5.1, 
`forward_env
` của Docker là một hệ thống riêng biệt với quá trình chuyển đổi kỹ năng. Hiện chúng đã được hợp nhất - các env được khai báo theo kỹ năng sẽ tự động được chuyển tiếp vào vùng chứa Docker và hộp cát Modal mà không cần thêm chúng vào 
`Docker_forward_env
` theo cách thủ công.
:::

**2. Chuyển qua dựa trên cấu hình (thủ công)**

Đối với các vars env không được khai báo bởi bất kỳ kỹ năng nào, hãy thêm chúng vào 
`terminal.env_passthrough
` trong 
`config.yaml

:

``` yaml
terminal:
  env_passthrough:

    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

`

### Truyền qua tệp thông tin xác thực (Mã thông báo OAuth, v.v.) {#credential-file-passthrough}

Một số kỹ năng cần **tệp** (không chỉ env vars) trong hộp cát — ví dụ: Google Workspace lưu trữ mã thông báo OAuth dưới dạng 
`Google_token.JSON
` trong 
`Hermes_HOME
` của hồ sơ đang hoạt động. Các kỹ năng khai báo những điều này trong frontmatter:

``` yaml
required_credential_files:

  - path: Google_token.JSON
    description: Google OAuth2 token (created by setup script)
  - path: Google_CLIent_secret.JSON
    description: Google OAuth2 CLIent credentials

`
``Khi được tải, Hermes kiểm tra xem các tệp này có tồn tại trong 
`Hermes_HOME
` của cấu hình đang hoạt động hay không và đăng ký chúng để gắn kết:
- **Docker**: Gắn kết liên kết chỉ đọc (

-v host:container:ro

)
- **Phương thức**: Được gắn khi tạo hộp cát + được đồng bộ hóa trước mỗi lệnh (xử lý việc thiết lập OAuth giữa phiên)
- **Cục bộ**: Không cần thực hiện hành động nào (tệp đã có thể truy cập được)

Bạn cũng có thể liệt kê các tệp thông tin xác thực theo cách thủ công trong 
`config.yaml

:

``` yaml
terminal:
  credential_files:

    - Google_token.JSON
    - my_custom_OAuth_token.JSON

`
``Các đường dẫn có liên quan đến 

~/.Hermes/

. Các tệp được gắn vào 

/root/.Hermes/
` bên trong vùng chứa.

### Mỗi bộ lọc hộp cát sẽ lọc những gì

| Hộp cát | Bộ lọc mặc định | Ghi đè thông qua |
|----------|---------------|----------------------|
| **execute_code** | Chặn các vars chứa 
`KEY

, 
`TOKEN

, 
`SECRET

, 
`PASSWORD

, 
`CREDENTIAL

, 
`PASSWD

, 
`AUTH
` trong tên; chỉ cho phép các vars tiền tố an toàn thông qua | ✅ Passthrough vars bỏ qua cả hai lần kiểm tra |
| **terminal** (cục bộ) | Chặn các loại cơ sở hạ tầng Hermes rõ ràng (khóa nhà cung cấp, mã thông báo cổng, khóa API công cụ) | ✅ Vượt qua vars bỏ qua danh sách chặn |
| **terminal** (Docker) | Không có máy chủ env vars theo mặc định | ✅ Chuyển tiếp vars + 
`Docker_forward_env
` được chuyển tiếp qua 

-e
` |
| **terminal** (Phương thức) | Không có tập tin/env máy chủ theo mặc định | ✅ Đã gắn tệp thông tin xác thực; truyền env qua đồng bộ hóa |
| **MCP** | Chặn mọi thứ ngoại trừ các vars hệ thống an toàn + 
`env
` được cấu hình rõ ràng | ❌ Không bị ảnh hưởng bởi sự chuyển tiếp (thay vào đó hãy sử dụng cấu hình MCP 
`env

) |

### Cân nhắc về bảo mật- Việc chuyển tiếp chỉ ảnh hưởng đến các lọ mà bạn hoặc các kỹ năng của bạn đã khai báo rõ ràng — chế độ bảo mật mặc định không thay đổi đối với mã do LLM tạo tùy ý
- Các tệp thông tin xác thực được gắn **chỉ đọc** vào vùng chứa Docker
- Skills Guard quét nội dung kỹ năng để tìm các kiểu truy cập env đáng ngờ trước khi cài đặt
- Các lọ bị thiếu/không được đặt sẽ không bao giờ được đăng ký (bạn không thể rò rỉ những gì không tồn tại)
- Không bao giờ được thêm bí mật cơ sở hạ tầng Hermes (khóa API của nhà cung cấp, mã thông báo cổng) vào 
`env_passthrough

 - chúng có cơ chế chuyên dụng

## Xử lý thông tin xác thực MCP

Các quy trình con của máy chủ MCP (Model Context Protocol) nhận được **môi trường được lọc** để ngăn chặn rò rỉ thông tin xác thực do vô tình.

### Biến môi trường an toàn

Chỉ các biến này được truyền từ máy chủ đến các quy trình con MCP stdio:

`
PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR

`
``Cộng với bất kỳ biến 
`XDG_*
` nào. Tất cả các biến môi trường khác (khóa API, mã thông báo, bí mật) đều **bị loại bỏ**.

Các biến được xác định rõ ràng trong cấu hình 
`env
` của máy chủ MCP được chuyển qua:

``` yaml
MCP_servers:
  GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:
      GitHub_PERSONAL_ACCESS_TOKEN: "ghp_..."  # Only this is passed

`

### Chỉnh sửa thông tin xác thực

Thông báo lỗi từ các công cụ MCP sẽ được loại bỏ trước khi được trả lại cho LLM. Các mẫu sau được thay thế bằng 

[REDACTED]

:
- GitHub PAT (
`ghp_...

)

- Phím kiểu OpenAI (
`sk-...

)
- Mã thông báo mang
- Các thông số 
`token=

, 
`key=

, 
`API_KEY=

, 
`password=

, 
`secret=

### Chính sách truy cập trang web

Bạn có thể hạn chế những trang web mà đại lý có thể truy cập thông qua các công cụ trình duyệt và web của nó. Điều này hữu ích để ngăn tác nhân truy cập vào các dịch vụ nội bộ, bảng quản trị hoặc các URL nhạy cảm khác.

``` yaml

# In ~/.Hermes/config.yaml
security:
  website_blocklist:
    enabled: true
    domains:
      - "*.internal.company.com"
      - "admin.example.com"
    shared_files:
      - "/etc/Hermes/blocked-sites.txt"

`
``Khi yêu cầu một URL bị chặn, công cụ sẽ trả về lỗi giải thích miền bị chặn theo chính sách. Danh sách chặn được thực thi trên 
`web_search

, 
`web_extract

, 
`browser_navigate
` và tất cả các công cụ có khả năng hỗ trợ URL.

Xem [Website Blocklist](/docs/user-guide/configuration#website-blocklist) trong hướng dẫn cấu hình để biết chi tiết đầy đủ.

### Bảo vệ SSRF

Tất cả các công cụ hỗ trợ URL (tìm kiếm trên web, trích xuất web, tầm nhìn, trình duyệt) đều xác thực URL trước khi tìm nạp chúng để ngăn chặn các cuộc tấn công Giả mạo yêu cầu phía máy chủ (SSRF). Các địa chỉ bị chặn bao gồm:
- **Mạng riêng** (RFC 1918): 
`10.0.0.0/8

, 
`172.16.0.0/12

, 
`192.168.0.0/16

- **Lặp lại**: 
`127.0.0.0/8

, 

::1

- **Link-local**: 
`169.254.0.0/16
` (bao gồm siêu dữ liệu đám mây tại 
`169.254.169.254

)
- **CGNAT / không gian địa chỉ dùng chung** (RFC 6598): 
`100.64.0.0/10
` (Tailscale, WireGuard VPN)
- **Tên máy chủ siêu dữ liệu đám mây**: 
`metadata.Google.internal

, 
`metadata.goog

- **Địa chỉ dành riêng, multicast và không xác định**

Tính năng bảo vệ SSRF luôn hoạt động khi sử dụng trên Internet và các lỗi DNS được coi là bị chặn (đóng không thành công). Chuỗi chuyển hướng được xác nhận lại ở mỗi bước nhảy để ngăn chặn việc bỏ qua dựa trên chuyển hướng.

#### Cố tình cho phép URL riêng tư

Một số thiết lập cần quyền truy cập URL riêng tư/nội bộ một cách hợp pháp — mạng gia đình phân giải 
`home.arpa
` thành không gian RFC 1918, điểm cuối OLlama/Llama.cpp chỉ có mạng LAN, wiki nội bộ, gỡ lỗi siêu dữ liệu đám mây và những thứ tương tự. Đối với những trường hợp đó, có lựa chọn không tham gia toàn cầu:

``` yaml
security:
  allow_private_urls: true   # default: false

`
``Khi bật, các công cụ web, trình duyệt, tìm nạp URL tầm nhìn và tải xuống phương tiện cổng không còn từ chối các đích RFC 1918 / loopback / link-local / CGNAT / cloud-metadata. **Đây là ranh giới tin cậy có chủ ý** — chỉ kích hoạt nó trên các máy mà tác nhân chạy các URL được chèn lời nhắc tùy ý vào mạng cục bộ là một rủi ro có thể chấp nhận được. Các cổng đối mặt với công chúng nên bỏ nó đi.

Trình bảo vệ chuỗi con máy chủ (chặn các thủ thuật miền Unicode trông giống nhau ngay cả khi IP cơ bản ở chế độ công khai) vẫn bật bất kể cài đặt này.

### Quét bảo mật trước khi thực thi Tirith

Hermes tích hợp [tirith](https://GitHub.com/sheeki03/tirith) để quét lệnh ở cấp độ nội dung trước khi thực thi. Tirith phát hiện các mối đe dọa mà việc so khớp mẫu đơn thuần sẽ bỏ sót:
- Giả mạo URL đồng âm (tấn công tên miền quốc tế hóa)

- Các mẫu chuyển từ đường ống sang trình thông dịch (
`curl | bash

, 
`wget | sh

)
- Tấn công tiêm terminal

Tirith tự động cài đặt từ các bản phát hành GitHub trong lần sử dụng đầu tiên với xác minh tổng kiểm tra SHA-256 (và xác minh xuất xứ cosign nếu có sẵn cosign).

``` yaml

# In ~/.Hermes/config.yaml
security:
  tirith_enabled: true       # Enable/disable tirith scanning (default: true)
  tirith_path: "tirith"      # Path to tirith binary (default: PATH lookup)
  tirith_timeout: 5          # Subprocess timeout in seconds
  tirith_fail_open: true     # Allow execution when tirith is unavailable (default: true)

`
`Khi 
`tirith_fail_open
` là 
`true
` (mặc định), các lệnh sẽ tiếp tục nếu tirith chưa được cài đặt hoặc hết thời gian chờ. Đặt thành 
`false
` trong môi trường bảo mật cao để chặn lệnh khi không có tirith.

Tirith cung cấp các tệp nhị phân dựng sẵn cho Linux (x86_64 / aarch64) và macOS (x86_64 / arm64). Trên các nền tảng không có tệp nhị phân dựng sẵn (Windows, v.v.), tirith bị bỏ qua một cách âm thầm - các trình bảo vệ khớp mẫu vẫn chạy và CLI không hiển thị biểu ngữ "không khả dụng". Để sử dụng tirith trên Windows, hãy chạy Hermes trong WSL.

Phán quyết của Tirith tích hợp với luồng phê duyệt: các lệnh an toàn được chuyển qua, trong khi cả lệnh đáng ngờ và lệnh bị chặn đều kích hoạt sự chấp thuận của người dùng với các phát hiện đầy đủ về tirith (mức độ nghiêm trọng, tiêu đề, mô tả, các lựa chọn thay thế an toàn hơn). Người dùng có thể phê duyệt hoặc từ chối - lựa chọn mặc định là từ chối để giữ an toàn cho các tình huống không được giám sát.

### Bảo vệ tiêm tệp ngữ cảnh

Các tệp ngữ cảnh (AGENTS.md, .Cursorrules, SOUL.md) được quét để đưa vào lời nhắc trước khi được đưa vào lời nhắc hệ thống. Máy quét kiểm tra:
- Hướng dẫn bỏ qua/bỏ qua hướng dẫn trước
- Nhận xét HTML ẩn với các từ khóa đáng ngờ
- Cố gắng đọc bí mật (

.env

, 
`credentials

, 

.netrc

)
- Lọc thông tin xác thực qua 
`curl

- Ký tự Unicode vô hình (khoảng trắng có độ rộng bằng 0, ghi đè hai chiều)

Các tệp bị chặn hiển thị cảnh báo:

`
[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

`

## Các phương pháp thực hành tốt nhất để triển khai sản xuất

### Danh sách kiểm tra triển khai cổng
1. **Đặt danh sách cho phép rõ ràng** — không bao giờ sử dụng 
`GATEWAY_ALLOW_ALL_USERS=true
` trong sản xuất
2. **Sử dụng phần phụ trợ vùng chứa** — đặt 
`terminal.backend: Docker
` trong config.yaml
3. **Hạn chế giới hạn tài nguyên** — đặt giới hạn CPU, bộ nhớ và đĩa thích hợp
4. **Lưu trữ bí mật một cách an toàn** — giữ các khóa API trong 

~/.Hermes/.env
` với quyền truy cập tệp thích hợp
5. **Bật ghép nối DM** — sử dụng mã ghép nối thay vì mã hóa ID người dùng khi có thể
6. **Xem lại danh sách lệnh cho phép** — kiểm tra định kỳ 
`command_allowlist
` trong config.yaml
7. **Đặt 
`MESSAGING_CWD

** — không để tác nhân hoạt động từ các thư mục nhạy cảm
8. **Chạy với quyền không phải root** — không bao giờ chạy cổng với quyền root
9. **Theo dõi nhật ký** — kiểm tra 

~/.Hermes/logs/
` để phát hiện các nỗ lực truy cập trái phép
10. **Luôn cập nhật** — chạy 
`Hermes update
` thường xuyên để có các bản vá bảo mật

### Bảo mật khóa API

``` bash

# Set proper permissions on the .env file
chmod 600 ~/.Hermes/.env

# Keep separate keys for different services
# Never commit .env files to version control

`

### Cách ly mạng

Để bảo mật tối đa, hãy chạy cổng trên một máy hoặc VM riêng biệt. Đặt 
`terminal.backend: SSH
` trong 
`config.yaml

, sau đó cung cấp chi tiết máy chủ thông qua các biến môi trường trong 

~/.Hermes/.env

:

``` yaml

# ~/.Hermes/config.yaml
terminal:
  backend: SSH

`

`
``` bash

# ~/.Hermes/.env
TERMINAL_SSH_HOST=agent-worker.local
TERMINAL_SSH_USER=Hermes
TERMINAL_SSH_KEY=~/.SSH/Hermes_agent_key

`
``Chi tiết kết nối SSH tồn tại trong 

.env
` (không phải 
`config.yaml

) nên chúng không được đăng ký hoặc chia sẻ cùng với quá trình xuất hồ sơ. Điều này giữ cho các kết nối nhắn tin của cổng tách biệt với việc thực thi lệnh của tác nhân.

## Kiểm tra tư vấn chuỗi cung ứng

Hermes cung cấp một máy quét tư vấn tích hợp gắn cờ các gói Python trong venv đang hoạt động khớp với danh mục tuyển chọn gồm các phiên bản đã bị xâm phạm đã biết (sâu chuỗi cung ứng như vụ đầu độc 
`Mistralai 2.4.6
` tháng 5 năm 2026). Việc triển khai tồn tại trong 
`Hermes_CLI/security_advisories.py

.

Nó chạy như thế nào:
- **Biểu ngữ khởi động CLI.** Cảnh báo một dòng sẽ được in nếu có bất kỳ lời khuyên nào phù hợp, kèm theo con trỏ tới 
`Hermes doctor
` để biết cách khắc phục đầy đủ.
- **
`Hermes doctor

.** Hiển thị mọi tư vấn đang hoạt động với thông tin chi tiết về phiên bản và hướng dẫn khắc phục 2-4 bước.
- **Khởi động cổng.** Đã đăng nhập vào 
`gateway.log

; tin nhắn tương tác đầu tiên nhận được một biểu ngữ điều hành ngắn.

Mỗi lời khuyên mang một id ổn định. Khi bạn đã đọc và thực hiện theo nó, bạn có thể loại bỏ nó vĩnh viễn:

``` bash
Hermes doctor --ack <advisory-id

`
``Xác nhận được duy trì ở 
`config.security.acked_advisories
` và vẫn tồn tại khi khởi động lại. Các lời khuyên cũ được **không** xóa khỏi danh mục một cách có chủ ý — việc giữ nguyên chúng sẽ giúp các bản cài đặt mới được cảnh báo về các phiên bản bị nhiễm độc trước đây có thể vẫn được lưu vào bộ nhớ đệm trong máy nhân bản riêng tư.

Bản thân kiểm tra này chỉ dành cho stdlib và chạy từ một lần tra cứu 
`importlib.metadata.version()
` cho mỗi tư vấn, do đó, an toàn khi chạy trên mỗi lần khởi động.

### Cài đặt lười biếng các phụ thuộc tùy chọn

Nhiều tính năng (Mistral TTS, ElevenLabs, Honcho Memory, Bedrock, Slack, Matrix,…) phụ thuộc vào các gói Python mà không phải người dùng nào cũng cần. Hermes cài đặt những thứ này **một cách lười biếng** trong lần sử dụng đầu tiên thay vì háo hức với 
`Hermes-agent[all]

. Việc triển khai tồn tại trong 
`tools/lazy_deps.py

.

Sự đánh đổi khắc phục điều này:- **Tính dễ vỡ.** Khi phần phụ thuộc bắc cầu của một phần bổ sung không còn khả dụng trên PyPI (bị cách ly vì phần mềm độc hại, bị kéo đứt, quá trình tải lên bị hỏng), toàn bộ quá trình giải quyết 

[all]
` sẽ không thành công và các lượt cài đặt mới sẽ âm thầm quay trở lại mức bị loại bỏ — mất hơn 10 phần bổ sung không liên quan cùng một lúc. Cài đặt lười biếng sẽ cô lập từng phần phụ trợ để một dep bị nhiễm độc không thể phá vỡ các tính năng không liên quan.

- **Bloat.** Người dùng chỉ nói chuyện với một nhà cung cấp sẽ không còn lấy được hàng trăm gói hàng mà họ sẽ không bao giờ nhập nữa.

Nó hoạt động như thế nào:
1. Mô-đun phụ trợ gọi 
`ensure("feature.name")
` ở đầu đường dẫn nhập đầu tiên của nó.
2. Nếu thiếu dep, 
`ensure
` sẽ kiểm tra 
`security.allow_lazy_installs
` trong 
`config.yaml
` (
`true
` mặc định) và chạy 
`pip install
` trong phạm vi venv để biết thông số kỹ thuật được liệt kê cho phép.
3. Nếu quá trình cài đặt không thành công hoặc người dùng đã vô hiệu hóa cài đặt lười, lệnh gọi sẽ tăng 
`FeatureUnavailable
` với stderr pip thực tế và một con trỏ tại 
`Hermes tools

.

Đảm bảo an ninh được thực thi bởi 
`tools/lazy_deps.py

:

| Đảm bảo | Ý nghĩa của nó |
|---|---|
| Chỉ trong phạm vi Venv | Cài đặt mục tiêu 
`sys.executable
` trong venv đang hoạt động - không bao giờ là hệ thống Python |
| PyPI chỉ theo tên | Thông số kỹ thuật chấp nhận cú pháp 

"package>=1.0,<2"

. Không có 

--index-url

, 
`git+https://
` hoặc tệp: đường dẫn - 
`config.yaml
` độc hại không thể chuyển hướng cài đặt |
| Danh sách cho phép | Chỉ các thông số kỹ thuật xuất hiện trong bản đồ 
`LAZY_DEPS
` trong cây mới có thể được cài đặt qua đường dẫn này. Lỗi đánh máy trong tên tính năng KHÔNG có ngữ nghĩa cài đặt |
| Chọn không tham gia | Đặt 
`security.allow_lazy_installs: false
` để tắt hoàn toàn cài đặt thời gian chạy. Hữu ích cho các mạng bị hạn chế hoặc các tình thế bảo mật nghiêm ngặt |
| Không thử lại trong im lặng | Lỗi xuất hiện dưới dạng 
`FeatureUnavailable

 - không có bộ nhớ đệm ở trạng thái xấu, không có cơn bão thử lại |

Để tắt cài đặt thời gian chạy:

``` yaml

# ~/.Hermes/config.yaml
security:
  allow_lazy_installs: false

`
``Khi bị tắt, các chương trình phụ trợ cần các phần phụ trợ tùy chọn sẽ yêu cầu người dùng chạy cài đặt theo cách thủ công (
`pip install …

) hoặc chọn một chương trình phụ trợ khác thông qua 
`Hermes tools

.