Bảo mật

Aki MCP Server giữ quyền truy cập theo điều kiện của bạn

Vì server có thể đối mặt với Internet công khai, bảo mật được thiết kế sẵn từ gốc, không phải thêm vào sau. Đây là những gì bảo vệ bạn, và cả những đánh đổi bạn phải chịu trách nhiệm.

Gặp từ chưa biết? Những từ bạn sẽ gặp

Whitelist nghiêm ngặt, không phải blocklist

Công cụ shell chỉ chạy lệnh bạn cho phép rõ ràng. Blocklist dễ lọt vì mặc định là cho phép; whitelist thì an toàn khi có sự cố.

  • Fail-safe: lệnh lạ hoặc mới bị chặn tự động.
  • Bề mặt tối thiểu: chỉ đúng các lệnh bạn duyệt mới chạy được.
  • Chi tiết tới subcommand: git chỉ giới hạn ở status/log/diff/show.
  • Là guardrail, không phải bức tường: allowlist giữ một AI bất cẩn hay quá hăng trong các lệnh bạn đã duyệt, nhưng tự nó không chặn được prompt injection. Tool file ghi được ~/.aki/mcpsv/setting.json trong các thư mục mặc định và nới rộng danh sách, nên hãy giữ kín passphrase và token, và xem lại ai đang có quyền truy cập.
  • Đường dẫn trong câu lệnh không bị rào: run_cmd chỉ bắt đầu trong các thư mục được phép, nhưng đường dẫn ghi trong chính câu lệnh không bị đối chiếu với chúng; tham số trỏ tới file chứa thông tin xác thực bị từ chối. Lệnh chạy bằng quyền người dùng của bạn.
  • Ưu tiên kiểm tra: các binary nhiều cờ có thể thoát khỏi chế độ chỉ-đọc bị cố tình loại ra, và các dạng ghi của git (branch -D, tag -d, remote set-url, --output=) bị từ chối mặc định.

Triết lý thiết kế: tiện dụng trước, guardrail sau. Allowlist bảo vệ trước model yếu hoặc quá hăng. Nó không phải ổ khóa chống lại chính bạn, chủ máy.

Xác thực và phân quyền

  • Mọi lệnh gọi /mcp cần Bearer token OAuth 2.1 hợp lệ. Không có kiểu token-in-URL.
  • Mọi AI web đăng nhập bằng OAuth đều nhập passphrase và tự đăng ký qua DCR (RFC 7591), nên không có Client ID hay Secret nào để dán; ChatGPT và Grok đăng ký như public client, Notion như confidential client. Client ID/Secret cấp sẵn mà akimcp in ra lúc khởi động vẫn còn, làm phương án dự phòng cho client cần một cặp cố định. Đăng nhập của Gemini chưa được kiểm trên một phiên thật.
  • Chỉ redirect URI của các client đã biết được chấp nhận (claude.ai, chatgpt.com, grok.com, proxy OAuth redirect của Google cho Gemini, các host callback cố định của Notion dưới notion.so và notion.com, và đúng callback https://search.clickup-prod.com/connect/mcp của ClickUp, khớp chính xác hostname qua https nên domain giả mạo bị loại), cùng mọi địa chỉ https bạn thêm trong tab Other AI (sign-in) của panel. Mỗi địa chỉ được đọc đúng như trình duyệt sẽ đi theo: %2e%2e và các mẹo tương tự được giải trước khi kiểm tra, còn địa chỉ chứa #, tên người dùng hay mật khẩu bị từ chối. Mỗi lần đăng nhập đều kiểm tra lại địa chỉ, nên xóa một địa chỉ sẽ chặn các lần đăng nhập mới qua nó, và trang xác nhận ghi rõ lần đăng nhập quay về đâu. Client vẫn phải qua màn hình consent bằng passphrase và PKCE trước khi nhận token.
  • Một access token dùng chung (hiệu lực một năm) phục vụ mọi client, nên panel hiển thị và roll nó ở một chỗ.
  • Các file đăng nhập (tokens.json, danh sách token đã thu hồi và passphrase.txt) được ghi trọn vẹn hoặc không ghi gì, nên máy sập hay đầy ổ đĩa không làm file nào bị rỗng, và file passphrase.txt rỗng được thay bằng passphrase mới thay vì cho passphrase trống đi qua.
  • Ngoài ra, panel cấp token tạm thời, mỗi chat web một cái: mỗi token 4 giờ, và nút +30 min cạnh token còn sống cộng thêm nửa giờ mỗi lần bấm, còn ô Last used cho biết lúc nào, từ địa chỉ nào và app nào. Mỗi token bị thu hồi bởi chính chat, bằng nút Revoke trong panel, bởi Roll & sign out all clients, hoặc khi khởi động lại; token đã hết hạn hay bị thu hồi thì không sống lại. Chúng không bao giờ đổi token dùng chung.

Tự chặn dò mật khẩu và nhìn rõ

Gatekeeper giới hạn tần suất thử sai, và mục “Security & connection limits” của panel cho thấy ai đang giữ quyền truy cập và ai đã dùng.

  • 5 lần sai, bị chặn 15 phút: 5 thông tin xác thực bị từ chối trong 60 giây (sai passphrase, sai client secret, Bearer không hợp lệ ở /mcp) sẽ chặn người gọi 15 phút, trả 429 kèm Retry-After.
  • Chặn tràn đăng ký: 100 lần POST /register trong 10 phút cũng bị chặn, và danh sách client ngừng tăng ở mức 500.
  • Mỗi người gọi được đếm theo địa chỉ mà ingress của nó ghi: Cloudflare Tunnel theo CF-Connecting-IP, Tailscale Funnel theo phần tử cuối của X-Forwarded-For, edge riêng của bạn (PUBLIC_ORIGIN) theo một trong hai. Header mà ingress không ghi sẽ bị bỏ qua, nên client không tự chọn được khóa của mình (từ 3.0.1).
  • Lần gọi đầu không kèm thông tin xác thực thì không bị đếm: client MCP mở đầu bằng một yêu cầu không có bearer để đọc thử thách đăng nhập 401. Từ 3.1.0, yêu cầu đó không bị đếm và không ghi vào nhật ký bảo mật, nên kết nối lại dồn dập không làm client bị chặn. Bearer sai thì vẫn bị đếm.
  • Client thật an toàn: Bearer token hợp lệ không bao giờ bị tính hay từ chối, lỗi giao thức hoặc đường dẫn lạ cũng không bị tính.
  • Bạn tự chỉnh: mọi ngưỡng đều chỉnh được ở mục “Security & connection limits” của panel, nơi liệt kê người gọi bị chặn kèm nút Release.
  • Thấy tất cả: bảng Clients (lần đầu thấy, lần duyệt gần nhất, lần cấp token gần nhất, địa chỉ và agent), Active now, và 200 dòng mới nhất của security.log. Bấm tiêu đề cột để sắp xếp mọi bảng trong panel; Clients và Active now còn có ô lọc chữ, số dòng và Refresh, riêng Clients có thêm lọc theo trạng thái.
  • Bí mật được che: passphrase và access token hiện dạng dấu chấm kèm nút con mắt, ảnh chụp màn hình không lộ gì.

Nếu lộ bí mật

Panel biến việc dọn dẹp thành vài cú bấm. Chọn dòng khớp với thứ bị lộ.

  • Passphrase bị nhìn thấy: Roll passphrase, rồi Roll & sign out all clients.
  • Access token bị nhìn thấy: Roll & sign out all clients.
  • Có client lạ trong danh sách: cả hai lần roll, rồi kết nối lại các AI bạn tin.
  • Connector không còn dùng: Revoke & roll trong bảng Clients. Nút này gỡ client và đổi token dùng chung, nên các cách cài dùng Bearer như Buda và snippet Claude Code, Codex, Cursor cần token mới.

Thông tin xác thực không lọt vào kết quả của tool

Các file chứa bí mật của chính akimcp bị đóng với mọi tool, và bí mật nào vẫn lọt vào kết quả, từ các file đó hay từ file dự án như .env, sẽ bị che trước khi tới nhà cung cấp AI.

  • File thông tin xác thực bị đóng: công cụ file không đọc cũng không ghi tokens.json, passphrase.txt, oauth-client.json, oauth-dcr-clients.json hay cloudflared-cred.json. run_cmd và task_start từ chối lệnh nhắc tới các file này, còn search_content bỏ chúng khỏi kết quả.
  • Che thông tin ở mọi kết quả: mọi giá trị dạng token lấy từ các file đó, passphrase và panel token trong instance.json đều hiện là [redacted], kể cả trong thông báo lỗi và trước khi output dài bị cắt. Nhờ vậy một lệnh grep -r lỡ quét thư mục dữ liệu, hay một bản sao nằm trong log của task, cũng không làm lộ bí mật.
  • Bí mật trong file dự án, che theo hình dạng: mọi kết quả còn che giá trị của dòng NAME=value có tên chứa một phần như TOKEN, SECRET, KEY, PASSWORD, AUTH hoặc COOKIE, và ở bất kỳ đâu trong văn bản: token bot Telegram, khóa sk-, GitHub, Slack, Postman, Google hay AWS, giá trị Bearer, mật khẩu trong URL và khóa riêng PEM. $reference vẫn giữ nguyên, nên script đọc bí mật vẫn sửa được, còn write_file và edit_file từ chối ghi [redacted] vào file đang chứa giá trị bị che, nên lệnh sửa không ghi đè được giá trị thật.
  • Chặn sai sót, không chặn được model cố tình: bí mật mang tên trung tính (CHAT_ID=) hoặc ở dạng khác (password: trong YAML) vẫn hiện nguyên văn, bản sao đã mã hóa (nén hoặc base64) sẽ không bị nhận ra, và model nào tự mở rộng allowlist tới một shell đầy đủ thì đọc được mọi thứ bạn đọc được. setting.json vẫn đọc và ghi được có chủ đích, để AI chỉnh thư mục và allowlist khi bạn nhờ.

Mỗi tầng bảo vệ điều gì

Một gatekeeper, bearer cả trên loopback

Gatekeeper trên 127.0.0.1:9999 là lối vào duy nhất cho cả client local và (qua ingress tùy chọn) client từ xa; mọi tool chạy in-process phía sau, và Bearer token bắt buộc ngay cả trên loopback.

Panel chỉ ở local

Control panel bind vào 127.0.0.1:9998, cần token mỗi lần chạy, và không bao giờ được đẩy ra edge công khai.

Fetch chống SSRF

Bộ fetch LAN chặn cloud metadata, IP link-local, scheme không phải HTTP, kèm giới hạn dung lượng và thời gian.

Bí mật ở chế độ 0600

Passphrase, client secret và token nằm trong ~/.aki/mcpsv/ ở mode 0600, ngoài repo, không bao giờ vào git.

Mặc định AI làm được và không làm được gì

Mặc định được phép

Chạy bộ shell ưu tiên kiểm tra, đọc và tìm file trong thư mục được phép, và mọi hành động đều là tool call hiện rõ. Một số helper dev duyệt sẵn (npm run, open, sips, ffmpeg) có thể ghi.

Mặc định không thể

Chạy lệnh ngoài allowlist, chạy các dạng ghi của git, ghi vào thư mục script tin cậy qua công cụ file, chạm tới panel local, hay gọi mạng ra ngoài tùy ý.

Đánh đổi thật lòng bạn phải biết

  • Gốc file mặc định là toàn bộ thư mục home ($HOME) cộng ~/.aki và ~/.claude. Hãy thu hẹp trong panel trên máy nhạy cảm.
  • ~/.claude được cấp ở mức thư mục, nên token phiên và lịch sử chat bên trong cũng nằm trong tầm với. Gỡ bằng cách sửa trực tiếp danh sách thư mục.
  • Bất kỳ lệnh ghi nào bạn thêm vào allowlist (ví dụ git commit) là trách nhiệm của bạn và làm rộng bề mặt.
  • Với một token dùng chung, Remove only đăng xuất client nhưng chưa phải thu hồi tức thì. Revoke & roll gỡ client và đổi token để cắt quyền ngay.
  • Bộ giới hạn tần suất nằm trong bộ nhớ, nên khởi động lại sẽ xóa danh sách bị chặn. Tên client do client tự khai, nên hãy tin cột địa chỉ và thời gian hơn nhãn tên.
  • Sau Tailscale Funnel, bộ chặn tin phần tử cuối của X-Forwarded-For. Việc Funnel ghi địa chỉ thật của người gọi vào đó được đọc từ mã nguồn của Tailscale, chưa thấy trên một request Funnel thật; header của Cloudflare Tunnel đã được xem trực tiếp.
  • Gemini đang thử nghiệm: bản 3.1 đăng nhập lại được (chưa kiểm trên phiên thật), nhưng ở các lần thử trước dùng tool chưa ổn định.

Thu hồi truy cập bất cứ lúc nào từ mục “Security & connection limits” của panel: Revoke & roll client (đăng ký chưa từng nhận token chỉ có nút Delete). Nếu nghi lộ bí mật, dùng Roll & sign out all clients.