API WAF

Tổng quan

Địa chỉ gốc của các endpoint trên trang này:

https://cloudmoon.net/api/v1

Giá đại lý: Danh mục, báo giá và lệnh mua trả về (và trừ ví) giá đã trừ chiết khấu theo cấp đại lý; gia hạn theo GIÁ GHI TRÊN ĐƠN (giá lúc mua — đã trừ chiết khấu khi ấy); đổi chu kỳ ghi giá chu kỳ mới đã trừ chiết khấu như lúc mua cho lần gia hạn kế. — xem mục Tài khoản đại lý.

Mua & xác minh tên miền

Mỗi đơn WAF bảo vệ đúng một tên miền — tên miền gốc hoặc một tên miền con, không nhận wildcard (bảo vệ cả www. thì mua thêm một đơn cho tên ấy). Lệnh mua kiểm hết, trừ ví và dựng cấu hình bảo vệ ngay trong lượt gọi; bạn chỉ còn trỏ bản ghi A (mục Trỏ DNS & HTTPS).

1. POST /waf/verify-domain với {domain} (khoá Toàn quyền — cấp mã là một lệnh ghi): mua mới cần bằng chứng bạn quản lý tên miền. Đã có ⇒ verified: true ngay, proof = registered_here (đúng tên miền ấy mua tại đây, đang chạy và còn hạn trong tài khoản — tên miền mẹ không tính cho tên miền con) hoặc txt (đã xác minh TXT trong 7 ngày). Chưa có ⇒ record: bản ghi TXT tên _waf-verify.<tên miền>, giá trị là mã 32 ký tự riêng cho cặp tài khoản + tên miền (gọi lại vẫn ra đúng mã ấy).
2. Thêm bản ghi TXT tại nơi quản lý DNS của tên miền, rồi gọi lại kèm check: true ⇒ verified: true (kiểm đạt dùng được cho lệnh mua trong 7 ngày), hoặc verified: false + result: not_found (chưa thấy TXT đúng tên) · wrong_value (có TXT đúng tên nhưng không giá trị nào khớp mã — dán đúng mã, không thêm dấu nháy hay khoảng trắng) · cname (tên ấy là một CNAME — bản ghi phải là TXT đặt trực tiếp đúng tên). Lượt vừa cấp mã chưa tra DNS (checked: false).
3. GET /waf/products: cycles (chu kỳ đang bán, ngắn → dài) · pricing[chu kỳ] = amount (số sẽ trừ — đã trừ chiết khấu đại lý) · amount_original · months · per_month · in_stock (còn chỗ trên máy chủ bảo vệ). POST /waf/quote với cùng thân lệnh mua (khoá Chỉ đọc gọi được) chạy đúng bộ kiểm của lệnh mua rồi trả amount, time_expire dự kiến và enough — không trừ tiền, không giữ chỗ hay giữ giá.
4. POST /waf/buy với {domain, backend_upstream, billing_cycle?, name?} và header Idempotency-Key ⇒ HTTP 200, provision_status: "ready", charged: true, order_code và dns — bản ghi A cần trỏ.

• HTTP 202 provision_status: "provisioning" + charged: true: tiền đã trừ, đơn đã có, nhưng máy chủ bảo vệ chưa xác nhận xong cấu hình — đừng mua lại; hệ thống tự hoàn tất (thử lại mỗi vài phút). Hỏi info thưa thôi tới ready. Hạn của đơn tính từ lúc mua, kể cả khi còn provisioning.
• Lời chối ở bước kiểm chưa trừ đồng nào: 409 DOMAIN_NOT_VERIFIED (chưa có bằng chứng — data.record = bản ghi TXT đã cấp, null nếu chưa cấp mã: gọi verify-domain) · 409 DOMAIN_IN_USE (tên miền đang được một WAF khác bảo vệ, hoặc cấu hình cũ của nó chưa gỡ xong — chỉ báo khi bạn đã có bằng chứng quyền tên miền) · 409 OUT_OF_STOCK (hết chỗ) · 409 PRICE_CHANGED (giá vừa tăng giữa lúc kiểm và lúc trừ — data.price_buy = số mới; báo giá lại rồi gửi lệnh mới với Idempotency-Key mới) · 402 (thiếu tiền) · 400 (tên miền, backend, chu kỳ hoặc tên không hợp lệ — sửa theo msg).
• Ngoại lệ: 400 FAILED ở lệnh mua có thể là giao dịch chưa rõ kết quả — đừng mua lại ngay: đối chiếu GET /waf/list hoặc liên hệ hỗ trợ; gửi lại cùng Idempotency-Key nhận lại đúng lỗi ấy.
• domain được chuẩn hoá trước khi kiểm: chữ thường; bỏ http(s)://, đường dẫn, cổng và dấu chấm cuối; tên miền quốc tế chuyển sang punycode. Tối đa 253 ký tự (xác minh TXT cần thêm chỗ cho _waf-verify. ⇒ tối đa 241). name — tên gợi nhớ, tối đa 200 ký tự (dài hơn bị chối, không bị cắt), bỏ trống = tên miền. billing_cycle bỏ trống = onemonth.
• Đơn mới bật sẵn tự gia hạn (billing.renew_auto: "on") — chỉ muốn một kỳ thì gọi POST /waf/auto-renew với enabled: false. Ngày mua đã tính là lượt gia hạn của ngày ấy: gia hạn được từ 0 giờ hôm sau.
• Xác minh: mỗi tên miền cách nhau tối thiểu 10 giây giữa hai lần kiểm (429 COOLDOWN) · tối đa 30 lần kiểm / giờ và 30 tên miền mới / 24 giờ cho mỗi tài khoản (429 RATE_LIMITED) · tra DNS hỏng ⇒ 503 UNAVAILABLE (thử lại). Đừng gửi check: true trước khi thêm bản ghi: hệ thống DNS có thể nhớ "chưa có" một thời gian (tới vài phút hoặc lâu hơn, tuỳ cấu hình DNS của tên miền). verify-domain không cho biết tên miền có đang được bảo vệ hay không.

Trỏ DNS & HTTPS

• Đơn ready ⇒ tạo bản ghi A cho đúng tên miền của đơn, trỏ về dns.value (= server_ip ở list / info) — địa chỉ IP máy chủ bảo vệ của đơn, không phải IP máy chủ gốc. Lệnh mua không tự sửa DNS: tới khi bản ghi mới có hiệu lực (thường 5–30 phút, tuỳ TTL), truy cập vẫn đi thẳng tới máy chủ gốc.
• Truy cập vào tên miền ⇒ qua máy chủ bảo vệ ⇒ lọc tấn công ⇒ chuyển phần sạch về backend_upstream.
• HTTPS — tuỳ cách trỏ DNS:
  • Qua proxy Cloudflare (đám mây cam) + chế độ SSL/TLS "Flexible" — cách khuyên dùng: có HTTPS ngay, không cần chứng chỉ trên WAF — Cloudflare cấp HTTPS cho người truy cập, chặng Cloudflare → máy chủ bảo vệ đi qua cổng 80. Chế độ "Full" / "Full (strict)" ⇒ Cloudflare báo lỗi 525. Khi bật proxy, máy chủ bảo vệ chỉ thấy IP của Cloudflare: src_ip ở logs và top_ips ở stats là IP Cloudflare (đổi theo từng lượt), không phải IP người truy cập.
  • Trỏ bản ghi A thẳng (tắt proxy — đám mây xám — hoặc DNS khác): src_ip / top_ips là IP thật của người truy cập, nhưng hiện chỉ có HTTP (cổng 80). API không cấp chứng chỉ.
• Ẩn IP gốc thật sự: cấu hình tường lửa của máy chủ gốc chỉ cho phép IP máy chủ bảo vệ (server_ip) vào cổng web. Ai còn biết IP gốc thì vẫn đánh thẳng được, vòng qua WAF.

Máy chủ gốc (backend)

• backend_upstream = địa chỉ máy chủ thật của website: http:// hoặc https:// + IP công khai hoặc tên miền + cổng (bỏ trống cổng = 80 với http · 443 với https; bỏ trống scheme = http). Đường dẫn / query không được giữ — hệ thống lưu dạng scheme://IP:cổng.
• Tên miền được phân giải (IPv4) lúc lưu và lưu thành IP — máy chủ gốc đổi IP thì gọi set-backend lại. IPv6 chưa hỗ trợ.
• Bị chối (400 BAD_REQUEST): địa chỉ nội bộ, loopback, các dải đặc biệt / không công khai, địa chỉ hạ tầng của hệ thống, tên miền không phân giải được. Ngoại lệ: website đặt trên hosting tại đây dùng làm backend được (cổng 80 / 443). Hệ thống tạm không kiểm được địa chỉ ⇒ 503 UNAVAILABLE (chưa đổi gì — thử lại).
• POST /waf/set-backend với {order_code, backend_upstream}: lưu rồi áp ngay — applied: true = máy chủ bảo vệ đã nhận; false = đã lưu, hệ thống áp tiếp ở nền (vài phút). Gửi lại đúng backend đang dùng = áp lại cấu hình (tự chữa khi cấu hình lệch).
• Đơn tạm ngưng ⇒ 409 RENEW_REQUIRED (gia hạn trước) · đơn mua xong mà cấu hình bảo vệ chưa dựng xong (lệnh mua trả 202) ⇒ 409 PROVISIONING · đơn hết hạn / đã xoá ⇒ 409 ORDER_EXPIRED.

Trạng thái đơn

list / info có provision_status (cùng order_status):

• allowed_actions (ở cả list lẫn info) — lệnh GHI làm được ngay lúc này, cùng luật với các nút trên trang quản lý WAF: renew · auto_renew · change_cycle · set_backend · delete. Tên nào vắng mặt thì lệnh ấy đang bị chối: đơn tạm ngưng không có set_backend; từ renew_deadline mất renew + auto_renew; đơn đang rao bán trên chợ mất change_cycle + delete; đơn expired rỗng. Chỉ xét trạng thái đơn — không tính nhịp (mục Nhịp thao tác), lượt gia hạn trong ngày hay số dư.
• dns {type: "A", name, value} — bản ghi cần trỏ; null khi đơn đã hết hạn / đã xoá.
• billing: price_buy (giá ghi trên đơn) · price_renew (số lần gia hạn kế sẽ trừ — null khi trạng thái đơn không cho gia hạn; đã gia hạn hôm nay hay thiếu tiền không làm nó null) · billing_cycle · months · renew_auto · time_buy · time_expire. info thêm renew_until (hạn mới nếu gia hạn ngay — dự tính) và renew_deadline (hạn chót gia hạn = time_expire + 7 ngày).
• list trả mọi đơn đang thuộc tài khoản — mua trên web lẫn qua API, nhận chuyển quyền — kể cả đơn đã hết hạn / đã xoá cho tới khi bị xoá hẳn; lọc bằng ?status= active · pending_expired · expired.

Gia hạn & tạm ngưng

• POST /waf/renew với {order_code} gia hạn một chu kỳ (chu kỳ ghi trên đơn) và trừ ví ngay: amount = billing.price_renew — giá ghi trên đơn (giá lúc mua, đã trừ chiết khấu khi ấy; đổi chu kỳ thì là giá chu kỳ mới). Hạn mới = max(bây giờ, hạn cũ) + số tháng của chu kỳ (tháng lịch: onemonth = 1 · sixmonth = 6 · oneyear = 12 · twoyear = 24 · threeyear = 36). Báo giá: quote với {"type": "renew", "order_code": "…"}.
• Mỗi đơn một lượt gia hạn mỗi ngày, tính cả ngày mua, gia hạn trên web và tự gia hạn ⇒ 429 COOLDOWN, Retry-After tới 0 giờ. Giá ghi trên đơn vừa tăng hoặc chu kỳ vừa đổi giữa lúc kiểm và lúc trừ (một lệnh đổi chu kỳ chen giữa) ⇒ 409 PRICE_CHANGED (data.price_buy · data.billing_cycle), chưa trừ tiền. Chu kỳ thôi bán không chặn gia hạn đơn đang có.
• Đổi chu kỳ (POST /waf/change-cycle, {order_code, billing_cycle}): áp cho lần gia hạn kế — không trừ tiền, không đổi hạn hiện tại (amount: 0); price_buy = giá chu kỳ mới hiện hành, đã trừ chiết khấu đại lý của tài khoản. Cùng chu kỳ đang dùng ⇒ thành công, không đổi gì (changed: false) · chu kỳ không đang bán ⇒ 400 · đơn đang rao bán trên chợ ⇒ 409 LISTED_ON_MARKETPLACE · đơn hết hạn ⇒ 409 ORDER_EXPIRED.
• Tự gia hạn (billing.renew_auto — đơn mới bật sẵn; đặt bằng POST /waf/auto-renew với enabled là boolean — lệnh ĐẶT giá trị, gửi lại cùng giá trị không lật ngược): mỗi giờ, từ lúc còn 7 ngày hoặc ít hơn tới time_expire — kể cả khi đơn đã tạm ngưng, cho tới hạn chót — hệ thống thử gia hạn một chu kỳ, giữ chu kỳ và giá ghi trên đơn; số dư thiếu ⇒ bỏ lượt, thử lại giờ sau.
• Hết hạn: qua time_expire mà chưa gia hạn ⇒ ở lượt kiểm kế tiếp (mỗi 6 giờ) đơn chuyển pending_expired (suspended): truy cập qua WAF bị chặn (lỗi tạm thời khi áp lệnh chặn ⇒ hệ thống tự áp lại sau ít phút), cấu hình + IP + tên miền giữ nguyên. Gia hạn trước renew_deadline (7 ngày sau hạn) ⇒ đơn hoạt động lại và truy cập được mở lại — reopened: true (đã mở) · false (đã gia hạn, đang mở lại ở nền); null = đơn không bị tạm ngưng.
• Từ renew_deadline không gia hạn được nữa (409 ORDER_EXPIRED) — ở lượt kiểm sau đó đơn chuyển expired: cấu hình bảo vệ bị gỡ, tên miền được nhả (mua WAF mới cho nó được khi gỡ xong). Đơn expired bị xoá hẳn khỏi list 30 ngày sau time_expire.

Log tấn công & thống kê

• GET /waf/logs — sự kiện tấn công đã ghi nhận, mới nhất trước: host · src_ip (IP nguồn — tên miền bật proxy Cloudflare thì là IP của Cloudflare, mục Trỏ DNS & HTTPS) · attack_type (sqli · xss · rce · ssrf · xxe · ssti · file_inclusion · path_traversal · deserialization · backdoor · scanner · file_upload · other) · action (1 = đã chặn, cùng nghĩa với blocked: true) · url_path (tối đa 500 ký tự) · risk_level (1 thấp · 2 trung bình · 3 cao; 0 = chưa xếp mức) · event_time + time (ISO 8601). Không lưu header, thân hay payload của lượt truy cập.
• Không truyền order_code ⇒ mọi log của tài khoản; có order_code ⇒ log của tên miền hiện tại của đơn ấy (đơn đã hết hạn / đã xoá không còn tên miền ⇒ danh sách rỗng — log cũ vẫn có trong danh sách toàn tài khoản). Phân trang limit (1–200, mặc định 50) + page.
• Log về theo nhịp kéo từ máy chủ bảo vệ (khoảng 5 phút, có thể lâu hơn lúc tải cao) và được giữ 30 ngày. Mỗi sự kiện gán cho đơn đang giữ tên miền lúc ghi nhận: mua lại một tên miền bằng đơn mới không thấy log đời trước của tài khoản khác; chuyển quyền thì log đã có đi theo đơn sang người nhận.
• GET /waf/stats?order_code=… — lưu lượng hôm nay (từ 0 giờ, giờ Việt Nam) của đúng tên miền: total_requests · blocked · passed (= tổng − chặn) · top_ips (tối đa 5 IP bị chặn nhiều nhất hôm nay ⇒ số lượt — luôn là object; sau proxy Cloudflare là IP Cloudflare) · synced_at (lúc lấy số) · stale (true = đang trả số cũ hơn 60 giây). Số làm mới tối đa mỗi 60 giây; lượt truy cập mới hiện vào số sau khoảng 1–2 phút.
• Chưa lấy được số ⇒ available: false và ba số là null — không có nghĩa là không có truy cập. top_ips lấy từ log đã kéo nên có thể lệch ba số kia vài phút.

Luật riêng

• Phạm vi bảo vệ: WAF bảo vệ tầng ứng dụng (L7) — lọc SQLi / XSS / RCE / quét lỗ hổng — và ẩn IP máy chủ gốc. KHÔNG chống tấn công DDoS băng thông lớn (L3/L4): loại đó cần hạ tầng lọc chuyên dụng.
• Xoá (POST /waf/delete, confirm = đúng order_code): đơn chuyển expired ngay, cấu hình bảo vệ được gỡ (có thể hoàn tất sau ít phút) — không hoàn tiền, không khôi phục được. Đơn đang rao bán trên chợ ⇒ 409 LISTED_ON_MARKETPLACE · đã hết hạn / đã xoá ⇒ 409 ORDER_EXPIRED.
• Dịch vụ WAF tạm dừng bán: products · price · verify-domain · báo giá mua mới · lệnh mua nhận 503 SERVICE_DISABLED (GET /services/status báo waf: false); mọi lệnh trên đơn đang có vẫn chạy bình thường.
• Hết chỗ: products vẫn bày sản phẩm với in_stock: false (?in_stock=1 ⇒ danh sách rỗng) — báo giá / lệnh mua ⇒ 409 OUT_OF_STOCK; trang mua trên web cùng lúc bày băng "tạm hết chỗ" và khoá nút mua. Đơn đang có không bị ảnh hưởng.
• Giới hạn lệnh mua (mỗi tài khoản): tối đa 10 lượt mua WAF mỗi giờ — đếm cả lượt mua trên web (429 RATE_LIMITED), tính riêng với các sản phẩm khác. Số dư xét lệnh mua là số dư khả dụng — đã trừ tiền các lệnh mua Cloud VPS còn chờ tạo máy.
• Không làm qua API: chuyển đơn sang tài khoản khác (xác nhận qua email trên web) · rao bán trên chợ · chuyển sang máy chủ bảo vệ khác — dùng trang quản lý WAF trên web hoặc liên hệ hỗ trợ.
• Chạy thử (X-Sandbox: 1): lệnh mua trả mã SANDBOX… (21 ký tự) — đơn mẫu tên miền sandbox-….example, IP máy chủ bảo vệ + backend thuộc dải tài liệu 203.0.113.0/24, chu kỳ lấy từ mã, giá dựng lại từ bảng giá hiện hành mỗi lần hỏi. X-Sandbox-Scenario: PROVISION_FAILED ⇒ 202 provisioning; info của mã ấy về ready sau khoảng 60 giây. Gia hạn đơn mẫu vừa tạo ⇒ 429 COOLDOWN như thật (mua xong không gia hạn trong ngày) · logs mẫu rỗng · stats mẫu là số giả. verify-domain chạy thử không cấp mã mới, không tra DNS. Với order_code thật, stats chạy thử chỉ đọc số đã lưu, không hỏi máy chủ bảo vệ. Không lưu gì: mã không có trong list.

Nhịp thao tác trên cùng một WAF

Các lệnh trên cùng một WAF phải cách lệnh trước một khoảng tối thiểu — nhịp này chỉ áp cho lệnh gửi qua API, để chặn lệnh gửi lặp. Các việc trong cùng một dòng dùng chung một đồng hồ. Gửi sớm hơn ⇒ 429 COOLDOWN (header Retry-After cho biết còn bao nhiêu giây); gửi trong lúc máy đang xử lý lệnh khác ⇒ 429 IN_PROGRESS.

Mã lỗi riêng

Ngoài các mã lỗi chung của mọi endpoint, trang này còn có các mã dưới đây. Hãy rẽ nhánh theo code.