reverse-engineering-api

name	reverse-engineering-api
description	Dùng khi website không có API phù hợp, endpoint đổi, cần phân tích HAR, hoặc cần tạo hay sửa client API reverse.
compatibility	Dùng Chrome DevTools MCP với Chrome profile cục bộ, hoặc nhận file HAR do user cung cấp.
metadata	{"author":"reverse-api-engineer","version":"1.1"}

Reverse Engineering API

Mục tiêu

Tìm endpoint thật từ traffic trình duyệt và biến thành client Python có thể bảo trì.

Chỉ làm với tài khoản, phiên đăng nhập, và dữ liệu mà user có quyền truy cập hợp lệ.

Khi dùng

Dùng khi:

• KiotViet đổi endpoint.
• kiotviet-client trả 400, 404, hoặc sai payload.
• Có HAR mới cần phân tích.
• Cần thêm endpoint chưa có trong client.

Không dùng để bypass đăng nhập, captcha, chống bot, giới hạn, hoặc phân quyền.

Luồng chuẩn

1. Mở Chrome profile cục bộ bằng script start_chrome_mcp.py.
2. Kết nối bằng Chrome DevTools MCP.
3. Nếu cần, để user đăng nhập trực tiếp trong Chrome.
4. Dùng MCP kiểm tra localStorage, network, hoặc lưu HAR thủ công từ DevTools.
5. Chạy har_filter.py để bỏ static, analytics, CDN.
6. Chạy har_analyze.py để lấy endpoint, header, query, body.
7. So sánh analysis với client hiện tại.
8. Vá client nhỏ nhất.
9. Chạy har_validate.py nếu có analysis JSON.
10. Chạy lệnh nghiệp vụ thật ở chế độ an toàn.

Lệnh

Mở Chrome bằng profile lưu trong thư mục hiện tại:

test -d ~/.venv/claude || uv venv ~/.venv/claude
~/.venv/claude/bin/python .agents/skills/reverse-engineering-api/scripts/start_chrome_mcp.py \
  --retailer "$KIOTVIET_RETAILER"

Sau đó dùng Chrome DevTools MCP:

list_pages
take_snapshot
evaluate_script
list_network_requests
get_network_request

Profile mặc định nằm ở .browser-profiles/kiotviet trong thư mục đang chạy. Profile này đã được ignore vì có thể chứa phiên đăng nhập.

Khi cần đồng bộ .env, đọc kf-accessToken và FingerPrintKey bằng MCP. Không in token ra câu trả lời. Chỉ ghi token vào .env.

Khi cần HAR, dùng DevTools trong Chrome để export HAR. Lưu HAR vào data/har/<run_id>/capture.har. data/ đã được ignore vì HAR có thể chứa token.

Sau khi ghi HAR, chạy phân tích:

test -d ~/.venv/claude || uv venv ~/.venv/claude
~/.venv/claude/bin/python .agents/skills/reverse-engineering-api/scripts/har_filter.py \
  input.har \
  --output filtered.har \
  --stats
~/.venv/claude/bin/python .agents/skills/reverse-engineering-api/scripts/har_analyze.py \
  filtered.har \
  --output analysis.json
~/.venv/claude/bin/python .agents/skills/reverse-engineering-api/scripts/har_validate.py \
  .agents/skills/kiotviet-client/scripts/api_client.py \
  analysis.json

Phân loại request

Ưu tiên request:

• host api-man1.kiotviet.vn.
• path chứa /api/ hoặc /reportapi/.
• response JSON.
• request có Authorization, Retailer, BranchId, FingerPrintKey.

Bỏ qua:

• ảnh, CSS, JS, font.
• analytics.
• tracking.
• CDN.
• request không liên quan nghiệp vụ.

Auth

Đọc references/AUTH_PATTERNS.md khi thấy token, cookie, CSRF, hoặc header đặc biệt.

Với KiotViet, chú ý:

• Authorization.
• Retailer.
• BranchId.
• x-retailer-code.
• x-group-id.
• FingerPrintKey.

Không ghi giá trị thật vào docs hoặc report.

HAR

Đọc references/HAR_ANALYSIS.md khi cần hiểu cấu trúc HAR.

Nếu HAR chứa token thật:

1. Không commit HAR.
2. Không copy token vào skill.
3. Chỉ trích xuất pattern header, path, body.
4. Lưu analysis đã redact nếu cần.

Output mong đợi

Sau khi sửa endpoint, báo:

• endpoint thay đổi.
• method thay đổi.
• header hoặc payload cần thêm.
• file đã sửa.
• lệnh verify đã chạy.
• rủi ro còn lại.

Không làm

• Không tạo client mới nếu chỉ cần vá kiotviet-client.
• Không hard-code token, retailer, branch, group.
• Không giữ HAR thô trong repo.
• Không sửa payload ghi dữ liệu nếu chưa có report và xác nhận.