Bảo mật ví đại lý của bạn trước khi ra mắt.
Đi vào sản xuất với thanh toán đại lý không phải là cùng một danh sách kiểm tra như một tích hợp API bình thường. Thêm: một lựa chọn loại ví có chủ đích, một chính sách chi tiêu được điều chỉnh (không phải mặc định), vòng quay bí mật API và webhook theo một chu kỳ đã nêu, một cuộc kiểm tra nhật ký hàng tuần, và một sách hướng dẫn phản ứng sự cố đã được thực hành ít nhất một lần. Nếu không có những điều này, bạn sẽ giao hàng và học theo cách khó khăn.
Trước khi bạn bắt đầu.
- Một tích hợp tác nhân hoạt động từ đầu đến cuối trong thử nghiệm - xem thêm-thanh-toán-cho-tác-nhân và thử-nghiệm-không-có-tiền-thật.
- Các kiểm soát chi tiêu đã được cấu hình - xem kiểm soát chi tiêu (hướng dẫn này giả định rằng một chính sách đã được thiết lập).
- Một trình quản lý bí mật (AWS Secrets Manager, GCP Secret Manager, Vault, 1Password, v.v.) - các bí mật trong các tệp .env là không đủ.
- Một kỹ sư trực ca được xác định rõ ràng với quyền truy cập quản trị vào bảng điều khiển ví.
- 15 phút tập trung. Danh sách kiểm tra dưới đây không phải là lý tưởng - hãy làm từng dòng một.
Chạy danh sách kiểm tra trước khi ra mắt.
Mười một mục. Mỗi mục là một câu hỏi có/không với một chủ sở hữu duy nhất. Nếu bất kỳ mục nào chưa được kiểm tra, đừng đưa vào hoạt động - hãy làm việc để hoàn thành mục đó trước. Chi phí của một mục bị bỏ lỡ trong sản xuất luôn lớn hơn chi phí hoàn thành nó ngay bây giờ.
# Pre-launch security checklist for agent wallets.
[ ] Wallet type chosen with reasoned trade-offs (smart wallet vs EOA).
[ ] Spend permission set in the dashboard: an allowance per period + a per-transaction cap.
[ ] API keys scoped to the minimum the agent needs (read_wallet_metadata / pay_bills / receive_money).
[ ] All API keys stored in a secret manager (not env files committed to git).
[ ] Test keys and live keys cannot be swapped (boot-time prefix check in place).
[ ] Webhook secret rotated within the last 90 days (webhooks.rotateSecret).
[ ] Webhook URL pointed at production, not a tunnel.
[ ] Audit review scheduled; alerting in place for unusual events.
[ ] A spike of rejected payments triggers an alert (>5/hour from one agent).
[ ] Incident runbook exists, has been read by someone other than the author.
[ ] One person other than you knows how to revoke an API key in < 5 minutes.Lên lịch xoay vòng khóa API và bí mật webhook.
Hàng quý là nhịp độ mặc định; xoay vòng ngay lập tức khi có bất kỳ điều gì: nghi ngờ rò rỉ, sự ra đi của kỹ sư chính, sự cố an ninh ở nơi khác trong công ty. Mẫu hai khóa cho phép bạn thay đổi khóa mà không có thời gian chết: tạo khóa mới, triển khai nó ở mọi nơi, xác minh, sau đó thu hồi khóa cũ.
// One-time key rotation script. Run quarterly, on lead departure, on suspected leak.
import { createClient } from "@blockchain0x/node";
const client = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! });
async function rotate() {
// Scope the new key to only what the agent needs.
const fresh = await client.apiKeys.create({
name: `prod-${new Date().toISOString().slice(0, 10)}`,
scopes: ["read_wallet_metadata", "pay_bills", "receive_money"],
});
console.log("NEW KEY:", fresh.secret); // Store in secret manager NOW.
// Wait until the new key is deployed and verified working, THEN:
// await client.apiKeys.revoke(OLD_KEY_ID); // (or apiKeys.rotate in one call)
}# One-time key rotation script. Run quarterly, on lead departure, on suspected leak.
from blockchain0x import Client
import datetime, os
client = Client() # reads BLOCKCHAIN0X_API_KEY
def rotate():
fresh = client.api_keys.create(body={
"name": f"prod-{datetime.date.today().isoformat()}",
"scopes": ["read_wallet_metadata", "pay_bills", "receive_money"],
})
print("NEW KEY:", fresh["secret"]) # Store in secret manager NOW.
# Wait until new key is deployed and verified, THEN:
# client.api_keys.revoke(OLD_KEY_ID) # (or api_keys.rotate in one call)Các bí mật ký Webhook xoay vòng tương tự qua bảng điều khiển - kích hoạt một bí mật thứ hai, triển khai lại trình xử lý để chấp nhận cả hai, sau đó ngừng sử dụng bí mật cũ. Cả hai đều theo chu kỳ hàng quý với nhắc nhở lịch.
Thiết lập đánh giá kiểm toán hàng tuần.
Ba điều cần xem xét mỗi tuần: các đối tác mới (bất cứ điều gì chưa thấy trước đây đều xứng đáng với một kiểm tra tâm lý 30 giây), các khoản thanh toán bị từ chối (quyền chi tiêu đã thực hiện công việc của nó - liệu đại lý có bị kẹt ở đâu không?), và các khoản thanh toán ngoài giờ (một khoản thanh toán vào lúc 3 giờ sáng từ một đại lý mà nominal chỉ hoạt động trong giờ làm việc là loại tín hiệu bắt được các cuộc tấn công tiêm sớm).
// Weekly audit query over the webhook events YOU persisted (payment.received /
// payment.sent). There is no transactions.list API - your own store is the log.
const since = Date.now() - 7 * 24 * 60 * 60 * 1000;
const events = await db.paymentEvents.findMany({ where: { receivedAt: { gte: since } } });
const newCounterparties = events.filter((e) => e.counterpartyFirstSeen);
const offHours = events.filter((e) => {
const h = new Date(e.receivedAt).getUTCHours();
return h < 5 || h > 22;
});
// Reconcile anything that looks off against the chain:
// const tx = await client.transactions.get(event.txHash);
console.log({ newCounterparties, offHours });from datetime import datetime, timedelta, timezone
# Query your own persisted webhook events - the SDK has transactions.get(id),
# not a list endpoint, so your event store is the audit log.
since = datetime.now(timezone.utc) - timedelta(days=7)
events = db.payment_events.where(received_at__gte=since)
new_counterparties = [e for e in events if e.counterparty_first_seen]
off_hours = [e for e in events if not (5 <= e.received_at.hour <= 22)]
# Reconcile against the chain when something looks off:
# tx = client.transactions.get(event.tx_hash)
print({"new_counterparties": new_counterparties, "off_hours": off_hours})Viết (và thực hành) sổ tay sự cố.
Một runbook chỉ tốt như cách nó được thử nghiệm gần đây. Dưới đây là mẫu - sao chép nó vào wiki của nhóm bạn, chỉnh sửa cho các thông số cụ thể của bạn và lên lịch một buổi diễn tập 30 phút trong quý tiếp theo. Thời gian nó; sửa chữa bất cứ điều gì mà buổi diễn tập tiết lộ là thiếu.
# Incident response runbook - Agent wallet compromise (suspected or confirmed)
## Trigger
Any of:
- Unrecognised counterparty receiving > $10 USDC.
- > 50 rejected payment attempts from one agent in an hour.
- Engineer reports they cannot account for a recent payment.
- A leaked API key surfaces in a public scan.
## Step 1 - Stop the bleeding (< 5 minutes)
- Revoke the suspect API key: dashboard, or apiKeys.revoke / apiKeys.rotate.
- Revoke the agent's spend permission in the dashboard (allowance to zero).
- A revoked key cannot move funds and a revoked permission authorizes nothing.
## Step 2 - Preserve evidence (< 15 minutes)
- Pull the last 24h from the dashboard activity log and your stored events.
- Note the agent's spend permission as it was at the time of the incident.
- Note the timestamps of any unrecognised payments and their txHash on Base
(fetch with transactions.get).
## Step 3 - Communicate (< 30 minutes)
- Inform the on-call lead and finance.
- If customer funds are affected, draft a notification template (do not send
until investigation is far enough along to be accurate).
## Step 4 - Root cause and remediation (24-72 hours)
- Determine: leaked key, compromised webhook secret, prompt-injection
bypass, integration bug, or other.
- Rotate every secret that could have been exposed.
- Tighten the spend permission (lower the allowance or per-transaction cap).
- File a post-mortem with timeline, RCA, and follow-ups.Năm điều khiến các đội gặp khó khăn trong sự cố sản xuất đầu tiên.
Đối xử với một đại lý mới như 'giống như đại lý cũ'
Mỗi tác nhân có hồ sơ riêng, khóa riêng, chính sách chi tiêu riêng. Nếu bạn tái sử dụng các khóa giữa các tác nhân 'bởi vì chúng tương tự', một sự thỏa hiệp khóa đơn lẻ sẽ ảnh hưởng đến mọi tác nhân cùng một lúc. Tạo một hồ sơ tác nhân mới mất một cuộc gọi API; sự cô lập theo từng tác nhân xứng đáng với phút mà nó tốn để thực hiện đúng.
Quyền chi tiêu được xác định bằng ước lượng, không phải bằng dữ liệu
Chọn khoản trợ cấp và giới hạn theo giao dịch từ một dự đoán và một trong hai điều xảy ra: quá thấp và tác nhân sẽ chạm đến giới hạn giữa ngày mỗi ngày trong khi bạn gỡ lỗi 'thanh toán bị từ chối'; quá cao và kiểm soát chỉ là hình thức. Trong tuần đầu tiên, hãy xem xét chi tiêu hàng ngày thực tế và đặt khoản trợ cấp ở mức 2-3 lần - không 1 lần (quá chặt) và không 100 lần (thực sự không giới hạn). Đây là một thay đổi trong bảng điều khiển, vì vậy việc điều chỉnh lại là rẻ.
Bí mật ký webhook không bao giờ được thay đổi
Một sự cố rò rỉ bí mật webhook có nghĩa là một kẻ tấn công có thể giả mạo các webhook trông giống như các sự kiện payment.received hợp pháp, điều này có thể đánh lừa bộ xử lý của bạn giao công việc mà chưa bao giờ được thanh toán. Thay đổi bí mật (webhooks.rotateSecret) theo cùng chu kỳ với các khóa API (hàng quý) hoặc bất kỳ lúc nào bạn nghi ngờ về việc lộ thông tin, và luôn xác minh các giao hàng với webhooks.verify so với bí mật hiện tại.
Nhật ký kiểm toán mà không ai đọc
Một nhật ký kiểm toán chỉ ghi lại mọi thứ nếu có ai đó xem nó. Hầu hết các nhóm bật nhật ký, không bao giờ xem nó và phát hiện ra các vấn đề từ khiếu nại của khách hàng. Lên lịch một cuộc xem xét hàng tuần 15 phút: các đối tác mới, các khoản thanh toán bị từ chối, các khoản thanh toán ngoài giờ. Chi phí rất nhỏ; thời gian phát hiện giảm từ tuần xuống còn ngày.
Không có bài tập trên sổ tay sự cố
Một runbook chưa bao giờ được thực hiện là hư cấu. Chọn một ngày hàng quý, mô phỏng một kịch bản rò rỉ khóa, đo thời gian cần thiết để thu hồi và kiểm soát. Bài tập đầu tiên luôn tiết lộ điều gì đó bị thiếu (kỹ sư biết cách quay vòng đang trong kỳ nghỉ, runbook nằm sau một liên kết Notion đã hết hạn). Tốt hơn là tìm thấy điều đó trong một bài tập hơn là vào lúc 3 giờ sáng trong một sự cố thực sự.
Sau khi thẻ an ninh.
An ninh không bao giờ hoàn thành, nhưng phần còn lại của ngăn xếp hoạt động được hưởng lợi từ một cơ sở sạch sẽ. Thắt chặt kiểm soát chi tiêu khi dữ liệu sử dụng thực tế tích lũy, củng cố xử lý webhook chống lại tải, và xác minh danh tính đại lý để các đối tác tin tưởng hồ sơ công khai của bạn.
Thiết lập các kiểm soát chi tiêu của agent mà vẫn tồn tại sau khi bị tiêm nhắc
Các mẫu webhook mà các nhà phát triển thường hỏi nhất
Kiếm huy hiệu xác minh GitHub và miền
Tài liệu đầy đủ tại docs.blockchain0x.com. Từ điển liên quan: Coinbase Smart Wallet. Bề mặt sản phẩm: Ví tác nhân.