Quy tắc
Ngôn ngữ so khớp — tool glob, mệnh đề argument, danh sách egress,
sanitizer, và chuỗi.
MCP server
Đăng ký và kiểm soát các Model Context Protocol server đằng sau một
gateway được audit duy nhất.
Skills
Quét và chấm điểm rủi ro các khả năng mà agent của bạn cài đặt trước
khi chúng có thể chạy.
1. Firewall là gì
Một AI agent không chỉ sinh ra văn bản — nó hành động. Nó gọishell.exec, truy vấn db.query, fetch một URL, nạp một community skill,
hoặc định tuyến một cuộc gọi tool qua một MCP server của bên thứ ba. Mỗi
cái trong số đó là một hành động có hậu quả ngoài đời thực, và guardrail ở
tầng prompt không thể thấy chúng.
Firewall là một chính sách có tên, theo phạm vi workspace mà
gateway đánh giá trên mọi cuộc gọi tool. Bạn soạn một chính sách một lần,
liên kết một API key với nó (hoặc đặt một cái làm mặc định của workspace),
và từ đó về sau mọi cuộc gọi tool mà key đó phát ra đều được kiểm tra đối
với chính sách — trước khi nó đến được tool.
Mỗi chính sách là một danh sách quy tắc có thứ tự. Một quy tắc quyết
định một điều — nó áp dụng cho những cuộc gọi tool nào (một glob tên
tool, tùy chọn thu hẹp theo một skill và theo một bề mặt thực thi) và làm
gì với chúng (một verdict: allow, audit, deny, sanitize, giữ lại chờ
phê duyệt, hoặc giới hạn chi phí). Engine duyệt các quy tắc theo thứ tự ưu
tiên, match đầu tiên thắng, và fallback về verdict mặc định của chính
sách nếu không có gì khớp.
Chỉnh sửa một chính sách có hiệu lực trên mọi key liên kết với nó ở
lần gọi kế tiếp. Không triển khai lại. Không đổi code agent. Chính sách
được thực thi ở gateway — agent của bạn vẫn phát ra các cuộc gọi tool y
như trước.
Phát hiện diễn ra ở gateway, ở lần dùng đầu tiên. Firewall nằm trên
đường relay LLM, không phải bên trong package manager hay filesystem của
agent bạn. Một tool, MCP server, hoặc skill mà một agent tự cài đặt được
bắt ở lần đầu tiên cuộc gọi của nó vượt qua gateway — không phải lúc cài
đặt. Đây là chủ đích: đó là điểm nghẽn duy nhất thấy mọi provider, mọi
agent, và mọi cuộc gọi tool bất kể khả năng đó đến đó bằng cách nào.
2. Bốn bề mặt thực thi
Mỗi cuộc gọi tool được đánh giá đối với đúng một bề mặt — điểm trong vòng đời request nơi firewall thấy nó:| Bề mặt | Nó thấy cái gì |
|---|---|
inbound | Các tool mà một agent quảng bá tới mô hình trên request (định nghĩa tool). Cho phép bạn block một tool nguy hiểm trước khi mô hình kịp chọn nó. |
response | Các tool_calls mà mô hình phát ra trong câu trả lời của nó. |
mcp | Một tools/call được dispatch qua Firewall MCP gateway hoặc được đánh giá qua SDK hook. |
egress | Một đích đến mạng đi ra ngoài (host / IP / CIDR) được một tool báo cáo — bề mặt SSRF và rò rỉ dữ liệu. |
3. Khái niệm cốt lõi
| Khái niệm | Định nghĩa |
|---|---|
| Chính sách | Một tập quy tắc có tên, theo phạm vi workspace. Có enabled, is_default, một default_verdict, và một cờ shadow_mode. |
| Quy tắc | Một kiểm tra bên trong một chính sách: một priority, một match tool/skill, một surface tùy chọn, một predicate argument tùy chọn, và một verdict. Xem Quy tắc. |
| Verdict | Hành động mà một quy tắc (hoặc mặc định) tạo ra — xem §4. |
| Verdict mặc định | Áp dụng khi không có quy tắc nào khớp. Một trong allow, audit (mặc định), hoặc deny. |
| Shadow mode | Chính sách đánh giá và ghi log nhưng không bao giờ block — mọi verdict thực thi bị hạ cấp thành audit và lý do được thêm tiền tố [shadow] would …. Công tắc triển khai an toàn của bạn. |
| Observe mode | Một thiết lập ở cấp workspace. Khi một request phân giải về không có chính sách và observe mode đang bật, cuộc gọi được cho phép nhưng được ghi log như một khoảng trống độ phủ — đó là cái nuôi dữ liệu cho chế độ xem Discovered-tools. |
Phạm vi và phân giải
Các chính sách phân giải y hệt Guardrails và API key — chia sẻ theo workspace khi bạn có một workspace đang hoạt động. Với bất kỳ cuộc gọi tool nào, gateway phân giải chính sách theo thứ tự này:- Liên kết key — nếu key đang gọi có một
firewall_policy_id, chính sách đó áp dụng (khi nó tồn tại và được bật). - Mặc định workspace — ngược lại, chính sách
is_defaultđã bật của workspace sẽ áp dụng. - Cả hai đều không — không thực thi. Với observe mode bật, cuộc gọi được cho phép và ghi log như một khoảng trống; với nó tắt, cuộc gọi được cho phép một cách im lặng (giống hệt từng byte với một workspace chưa bao giờ bật tính năng này).
Fail-open trên cái chưa biết, fail-closed trên cái mơ hồ. Nếu việc
phân giải chính sách gặp một lỗi thoáng qua, gateway suy giảm về
observe/allow thay vì làm gián đoạn traffic. Nhưng ở nơi mà không thực
thi sẽ đánh bại chính quy tắc — một báo cáo egress không có đích đến dùng
được, một kho phê duyệt không thể tiếp cận, một skill mà quyền sở hữu của
nó không thể phân giải — engine fail closed (deny hoặc giữ lại). Tính
sẵn sàng được bảo toàn; an toàn không bị âm thầm bỏ qua trong các trường
hợp quan trọng.
4. Verdict
Một quy tắc (hoặc verdict mặc định) tạo ra một trong các giá trị:| Verdict | Nó làm gì |
|---|---|
allow | Cho cuộc gọi đi qua. Được ghi log. |
audit | Cho phép, nhưng ghi lại để xem xét. default_verdict mặc định — quan sát mọi thứ, không block gì cả, cho đến khi bạn sẵn sàng. |
deny | Block cuộc gọi. Agent thấy một lỗi tool (hoặc HTTP 400 trên bề mặt inbound). |
sanitize | Redact các chuỗi con đã khớp khỏi argument của tool (secrets, PII) và chuyển tiếp cuộc gọi đã làm sạch. Xem sanitizer. Trên bề mặt inbound — nơi chưa có argument tại thời điểm gọi — sanitize leo thang thành một block. |
pending_approval | Giữ cuộc gọi lại cho một con người. Agent nhận một phản hồi “held”; một reviewer phê duyệt hoặc từ chối ngoài luồng; agent gửi lại với một token phê duyệt dùng một lần. Xem §7. |
cap_cost | Deny một khi mức chi tiêu tích lũy của lần chạy agent vượt quá mức trần tính bằng cents theo từng quy tắc. Một cầu dao ngắt mạch cho các vòng lặp mất kiểm soát. |
deny / sanitize / pending_approval đều bị hạ cấp
thành audit để bạn có thể đo lường tác động của một chính sách trước khi
nó thay đổi traffic.
5. Một cuộc gọi tool được đánh giá thế nào
- Một cuộc gọi tool đến gateway (được quảng bá inbound, phát ra trong một response, dispatch qua MCP gateway, hoặc được báo cáo như egress).
- Engine phân giải chính sách đang hoạt động (§3).
- Nó duyệt các quy tắc của chính sách theo thứ tự ưu tiên (priority thấp hơn trước; hòa nhau thì phân định theo rule id). Một quy tắc khớp khi surface của nó, glob tên tool, glob tên skill tùy chọn, các mệnh đề argument tùy chọn, và phạm vi egress tùy chọn của nó tất cả đều khớp.
- Match đầu tiên thắng → verdict của quy tắc áp dụng. Nếu không quy
tắc nào khớp →
default_verdictcủa chính sách. - Nếu cuộc gọi thuộc sở hữu của một skill
được kiểm soát, chế độ thực thi của skill được áp dụng lên trên — một
skill ở chế độ
blockbuộc một deny; một skill ở chế độquarantineleo thang bất cứ thứ gì thấp hơn deny lên thànhpending_approval. - Quyết định được ghi log như một sự kiện firewall (trừ khi đó là một dry run), tương quan với lần chạy agent và session.
6. Một block trông như thế nào
Một cuộc gọi bị từ chối trên bề mặt inbound trả về HTTP 400 với một thân lỗi định dạng OpenAI, mã lỗifirewall_blocked, và một thông báo
nêu tên tool và lý do — vd: tool "shell.exec" blocked by firewall: destructive shell command. Lỗi mang theo metadata có cấu trúc (mã lý
do, các yếu tố rủi ro, điểm số) và được đánh dấu skip-retry (chạy lại
cùng một cuộc gọi sẽ chỉ bị block lại).
Một cuộc gọi được dispatch qua MCP gateway bị block như một lỗi tool
(firewall deny: <reason>) thay vì một thất bại truyền tải, nên mô hình
thấy sự từ chối và có thể phản ứng — chọn một tool khác, hỏi người dùng,
hoặc dừng lại — thay vì crash.
Một cuộc gọi bị giữ lại (pending_approval) trả về HTTP 400 với mã
firewall_approval_pending và một approval id mà client poll dựa vào.
7. Phê duyệt bởi con người (HITL)
Một verdictpending_approval biến một cuộc gọi tool thành một cuộc xem
xét ngoài luồng:
- Engine xếp vào hàng đợi một bản ghi phê duyệt và trả về một phản hồi “held” mang theo id của nó; cuộc gọi không đến được tool.
- Một reviewer giải quyết nó — từ console (Developer+), hoặc qua một webhook callback ký HMAC tới hệ thống phê duyệt của riêng bạn.
- Agent của bạn (hoặc MCP SDK) poll approval id; một khi được phê
duyệt nó gửi lại cuộc gọi gốc với một header dùng một lần
X-OrcaRouter-Firewall-Approval, và gateway cho nó đi qua đúng lần đó.
rule_changed để reviewer biết ngữ cảnh đã dịch chuyển.
8. Cấp độ tự chủ — một công tắc cho toàn bộ tư thế của bạn
Tinh chỉnh chính sách theo từng quy tắc là con đường chính xác; cấp độ tự chủ là con đường nhanh. Một điều khiển duy nhất thay thế một cách nguyên tử tư thế Firewall và Guardrails của workspace bạn trong một transaction, với hoàn tác một cú nhấp:| Cấp độ | Tư thế |
|---|---|
tight | Block shell phá hủy, secrets trong argument, và egress SSRF (mặc định deny); guardrail PII Shield + Secrets Blocker bật; observe mode tắt. |
balanced | Audit shell phá hủy, flag PII; observe mode tắt. Tư thế khởi đầu được khuyến nghị. |
permissive | Không có chính sách thực thi, không có guardrail; observe mode bật để bạn vẫn thấy mọi thứ. |
9. Phát hiện bất thường
Vượt ra ngoài các quy tắc tĩnh, Firewall học hình dạng dùng tool bình thường của mỗi workspace và gắn cờ các sai lệch trên một feed mà viewer có thể đọc:- Spike tốc độ / chi phí — hoạt động theo từng tool được chấm điểm đối
với một baseline theo giờ-trong-tuần đã học (trung bình trượt 14
ngày), nên “100 cuộc gọi
db.querylúc 3 giờ sáng Chủ nhật” nổi bật ngay cả khi mỗi cuộc gọi đơn lẻ đều được cho phép. retry_loop— một agent dồn dập cùng một tool đang thất bại.novel_path— một chuyển tiếp tool-sang-tool mà workspace này chưa bao giờ thực hiện trước đây.
10. Khả năng quan sát
Firewall để lại một dấu vết bạn có thể hành động dựa vào, tất cả đều theo phạm vi workspace:| Bề mặt | Nó cho bạn cái gì |
|---|---|
| Events | Mọi lần đánh giá, có thể lọc theo verdict, surface, tool, run, và session. Bản ghi thô đằng sau mọi thứ khác. |
| Runs & sessions | Các sự kiện được gộp theo lần chạy agent hoặc cuộc hội thoại — phân tích verdict, các tool và mô hình riêng biệt, lần thấy đầu/cuối. Chế độ xem “agent này thực sự đã làm gì”. |
| Discovered tools | Mọi tool mà workspace đã thấy, được gắn cờ covered (một quy tắc áp dụng) hoặc gap (không có gì áp dụng). Điều khiển việc soạn chính sách từ traffic thực tế. |
| Simulate | Xem trước những gì một cấp độ tự chủ sẽ thay đổi trước khi bạn áp dụng nó. |
| Test | Dry-run một chính sách đối với một cuộc gọi tool mẫu và xem verdict, quy tắc đã khớp, và lý do — không có gì được persist, không có gì được dispatch. |
| Audit | Mọi thay đổi chính sách, quy tắc, và cài đặt ghi một hàng audit (workspace + trung tâm) sau khi thay đổi được commit. Secrets và rule blob không bao giờ được ghi log. |
11. Quan hệ với phần còn lại của gateway
| Bề mặt | Phối hợp với Firewall thế nào? |
|---|---|
| Guardrails | Các mặt phẳng bổ trợ. Guardrails sàng lọc văn bản prompt/response; Firewall kiểm soát các hành động tool. Cả hai có thể áp dụng cho một request. Cấp độ tự chủ đặt cả hai cùng lúc. |
| Routing | Độc lập. Routing chọn mô hình/kênh; firewall phán xét các cuộc gọi tool bất kể mô hình nào phục vụ chúng. |
| API keys | Một key liên kết với một chính sách qua firewall_policy_id; liên kết nằm trên key trong gateway. Không có liên kết thì fallback về mặc định của workspace. |
| MCP gateway | Firewall chính là MCP gateway — mọi server bạn đăng ký đều dispatch tools/call của nó qua engine. |
| Skills | Chế độ thực thi của một skill được kiểm soát cưỡi lên trên verdict của quy tắc, nên một skill bị quarantine sẽ bị giữ lại ngay cả khi không có quy tắc nào nêu tên các tool của nó. |
12. Kết nối một agent với gateway Firewall
Có hai cách để một cuộc gọi tool đến được engine:- MCP gateway — trỏ MCP client của bạn (Claude Desktop, Cursor, một
agent framework) vào
https://api.orcarouter.ai/api/v1/firewall/mcp. Gateway phơi bày các tool của mọi server đã đăng ký có thể tiếp cận được, được đặt namespace<server>.<tool>, và đánh giá mỗitools/callinline. Xem MCP server. - Evaluate hook — gọi
POST /api/v1/firewall/evaluatetừ vòng lặp agent của riêng bạn trước khi dispatch một cuộc gọi tool, và hành động dựa trên verdict.
403 trên các route này.
13. Tham chiếu API
Mọi route console đều theo phạm vi workspace qua ngữ cảnh workspace và thực thi RBAC nhất quán: đọc và các sandbox test/simulate mở cho mọi thành viên; ghi yêu cầu Developer+.Chính sách & cài đặt
| Method & path | Vai trò | Mục đích |
|---|---|---|
GET /api/workspace/firewall/settings | Member | Đọc cài đặt firewall của workspace (observe mode, mặc định). |
PUT /api/workspace/firewall/settings | Developer+ | Cập nhật cài đặt. |
GET /api/workspace/firewall/policies | Member | Liệt kê chính sách (với số lượng quy tắc + key liên kết). |
GET /api/workspace/firewall/policies/:id | Member | Chi tiết một chính sách đơn lẻ. |
POST /api/workspace/firewall/policies | Developer+ | Tạo một chính sách. |
PUT /api/workspace/firewall/policies | Developer+ | Cập nhật một chính sách. |
DELETE /api/workspace/firewall/policies/:id | Developer+ | Xóa một chính sách (409 nếu vẫn còn key liên kết). |
Tư thế, preset & sandbox
| Method & path | Vai trò | Mục đích |
|---|---|---|
GET /api/workspace/firewall/presets | Member | Các preset quy tắc built-in. |
POST /api/workspace/firewall/autonomy | Developer+ | Áp dụng một cấp độ tự chủ. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | Hoàn tác một thay đổi tự chủ. |
GET /api/workspace/firewall/simulate | Member | Xem trước một cấp độ tự chủ (?level=). |
POST /api/workspace/firewall/test | Developer+ | Dry-run một chính sách đối với một cuộc gọi tool mẫu. |
Khả năng quan sát
| Method & path | Vai trò | Mục đích |
|---|---|---|
GET /api/workspace/firewall/discovered-tools | Member | Các tool đã thấy, gắn cờ covered / gap. |
GET /api/workspace/firewall/events | Developer+ | Liệt kê các sự kiện firewall (có thể lọc). |
GET /api/workspace/firewall/events/by-request/:request_id | Developer+ | Các sự kiện cho một request. |
GET /api/workspace/firewall/events/aggregate | Developer+ | Gộp runs / sessions. |
GET /api/workspace/firewall/trace/by-run | Developer+ | Các node trace cho một lần chạy (?run_id=). |
GET /api/workspace/firewall/anomalies | Member | Feed bất thường (?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | Snooze feed bất thường. |
Gateway (máy-tới-máy)
Các route này chạy trên một token có phạm vi firewall-gateway, không phải session console:| Method & path | Mục đích |
|---|---|
POST /api/v1/firewall/evaluate | Verdict trước dispatch cho một cuộc gọi tool. |
POST /api/v1/firewall/evaluate_plan | Kiểm tra trước thực thi cho một kế hoạch nhiều bước. |
ANY /api/v1/firewall/mcp | Endpoint MCP gateway hợp nhất. |
GET /api/v1/firewall/approvals/:id | Poll trạng thái phê duyệt của một cuộc gọi bị giữ lại. |
POST /api/v1/firewall/approvals/:id/callback | Callback phê duyệt ký HMAC. |
14. FAQ
Sẽ ra sao nếu không có chính sách nào phân giải trên một cuộc gọi tool?
Sẽ ra sao nếu không có chính sách nào phân giải trên một cuộc gọi tool?
Với observe mode tắt, hành vi giống hệt từng byte với một workspace
chưa bao giờ bật tính năng này — không có gì bị block hoặc ghi log. Với
observe mode bật, cuộc gọi được cho phép nhưng được ghi lại như một
khoảng trống độ phủ để nó xuất hiện trong Discovered tools.
Làm sao để tôi triển khai một chính sách một cách an toàn?
Làm sao để tôi triển khai một chính sách một cách an toàn?
Bật shadow mode. Chính sách đánh giá và ghi log chính xác như nó sẽ
làm trong production, nhưng mọi verdict thực thi bị hạ cấp thành
audit và lý do được thêm tiền tố [shadow] would …. Theo dõi các chế
độ xem events và runs, xác nhận nó kích hoạt trên những gì bạn mong đợi
và không kích hoạt trên những gì bạn không mong đợi, rồi tắt shadow mode
để bắt đầu thực thi.Một cuộc gọi tool bị block có tốn quota không?
Một cuộc gọi tool bị block có tốn quota không?
Một block inbound kích hoạt trước cuộc gọi mô hình thượng nguồn, nên nó
không tốn token mô hình. Các verdict audit / allow không thay đổi
billing. Một quy tắc
cap_cost bản thân nó là một điều khiển billing —
nó deny một khi mức chi tiêu của lần chạy vượt qua mức trần cents của
bạn.Firewall hay Guardrails — tôi dùng cái nào?
Firewall hay Guardrails — tôi dùng cái nào?
Cả hai, cho các tầng khác nhau. Guardrails sàng lọc văn bản trong
prompt và response (PII, secrets, jailbreak). Firewall kiểm soát
các hành động một agent thực hiện (tool nào, MCP server nào, host nào).
Một request có thể đi qua cả hai. Cấp độ tự chủ
tight cấu hình chúng
cùng nhau.Việc thực thi có được đảm bảo cho mọi tool mà một agent chạy không?
Việc thực thi có được đảm bảo cho mọi tool mà một agent chạy không?
Firewall thực thi trên các cuộc gọi tool vượt qua gateway — đường relay,
MCP gateway, và evaluate hook. Một tool mà agent của bạn thực thi hoàn
toàn bên trong tiến trình của chính nó, không bao giờ chạm tới gateway,
nằm ngoài tầm nhìn của firewall. Mục tiêu thiết kế là biến gateway thành
con đường được audit duy nhất cho các cuộc gọi quan trọng (các tool qua
trung gian mô hình, dispatch MCP, egress mạng); định tuyến những cái đó
qua nó và chúng được kiểm soát.
Xem thêm
Muốn đi sâu hơn về bảo mật agent? Các hướng dẫn Bảo mật agent (Zero Trust) đặt tính năng này vào một quy trình zero-trust.Bảo mật agent (Zero Trust)
Playbook firewall agent zero-trust — allow-list tool, kiểm tra tham số, và kiểm soát egress.
Baseline Secure Agents
Một công tắc đặt tư thế Firewall và Guardrails của bạn cùng nhau.