Mira_Firmware_Loader/docs/scanner_docs.md

Tài liệu Kỹ thuật: Cơ chế Quét IP trên Mạng (Network Scanner)

1. Tổng quan

Thành phần quét IP trong scanner.py dò tìm và liệt kê tất cả thiết bị đang hoạt động trên một dải mạng (ví dụ: 192.168.1.0/24), trả về danh sách chứa IP và MAC Address của từng thiết bị.

Để đảm bảo tỷ lệ phát hiện cao trên mọi hệ điều hành (Windows, macOS, Linux), scanner kết hợp 3 giai đoạn:

1. Ping Sweep — đánh thức thiết bị, điền ARP cache
2. Đọc bảng ARP hệ điều hành (arp -a) — không cần quyền Admin
3. Scapy ARP broadcast — bổ sung thiết bị chặn ICMP

Bước 2 và 3 chạy song song để giảm tổng thời gian scan.

---

2. Luồng hoạt động chính (Hàm scan_network)

Bước 1 — Ping Sweep

• Gọi _ping_sweep(network): gửi ICMP Echo Request đồng thời tới toàn bộ host trong dải mạng.
• Mỗi thiết bị phản hồi sẽ khiến hệ điều hành tự ghi MAC vào ARP Cache.
• Sau khi sweep xong, chờ 0.3s để OS kịp finalize ARP cache (giảm từ 1s trước đây).

Bước 2 + 3 — ARP Table & Scapy (song song)

• Hai hàm _collect_arp() và _collect_scapy() được submit vào ThreadPoolExecutor(max_workers=2) và chạy đồng thời:
  • _collect_arp(): đọc arp -a, parse regex lấy IP + MAC.
  • _collect_scapy(): gửi ARP broadcast, nhận phản hồi trực tiếp từ thiết bị.
• Kết quả merge theo IP: ARP table làm nền, Scapy bổ sung IP còn thiếu.

Bước 4 — Trả về kết quả

• Danh sách sort tăng dần theo IP: [{"ip": "192.168.1.2", "mac": "aa:bb:cc:dd:ee:ff"}, ...]

---

3. Phân tích chi tiết các hàm

_ping_one(ip, is_win)

Ping một IP đơn lẻ với timeout tối ưu theo nền tảng:

OS	Lệnh	Timeout wait	Timeout process
Windows	ping -n 1 -w 300	300ms	2s
macOS	ping -c 1 -W 500	500ms (đơn vị ms)	2s
Linux	ping -c 1 -W 1	1s (đơn vị giây)	2s

macOS và Linux dùng cùng flag -W nhưng đơn vị khác nhau — được xử lý tách biệt theo sys.platform.

_ping_sweep(network, progress_cb)

• Tạo ThreadPoolExecutor(max_workers=len(hosts)) — toàn bộ host ping đồng thời, không batching.
• Giới hạn an toàn: chỉ chạy với subnet /24 trở xuống (num_addresses <= 256).
• Gọi progress_cb(done, total) sau mỗi ping để UI cập nhật thanh tiến độ.

_collect_arp() (nội bộ trong scan_network)

Đọc và parse output arp -a, hỗ trợ đa nền tảng:

• Windows: Regex nhận dạng dạng cc-2d-21-a5-85-b0 dynamic, chuẩn hóa MAC sang cc:2d:21:a5:85:b0.
• macOS/Linux: Regex nhận dạng dạng (192.168.1.1) at aa:bb:cc:dd:ee:ff, bỏ qua entry (incomplete).

_collect_scapy() (nội bộ trong scan_network)

• Gửi ARP Who-has broadcast (Ether/ARP qua srp) với timeout 1s (giảm từ 2s).
• Stderr bị redirect tạm thời khi import scapy để tránh spam log ra console.
• Tự động bỏ qua nếu scapy không khả dụng (không có Npcap / không có quyền root).

---

4. So sánh hiệu năng (trước và sau tối ưu)

Thay đổi	Trước	Sau
Ping workers	100 (batching ~3 đợt)	len(hosts) (~254, tất cả cùng lúc)
Ping timeout — Windows	600ms	300ms
Ping timeout — macOS	1ms (sai đơn vị)	500ms
Sleep sau ping sweep	1.0s	0.3s
ARP + Scapy	Tuần tự	Song song
Scapy timeout	2s	1s
Tổng thời gian scan /24	~5–7s	~1.5–2s

---

5. Ưu & Nhược điểm

Ưu điểm:

• Tỷ lệ phát hiện thiết bị cao nhờ kết hợp 3 lớp.
• Không cần quyền Admin/Root — ping sweep + ARP table vẫn tìm được ~90% thiết bị.
• Tương thích đa nền tảng (Windows/macOS/Linux) qua xử lý riêng từng OS.
• ARP table và Scapy chạy song song → không cộng dồn thời gian chờ.

Nhược điểm:

• Vẫn cần sleep(0.3s) để OS kịp ghi ARP cache sau ping sweep.
• Thiết bị tắt hoàn toàn cả ICMP lẫn ARP sẽ không bị phát hiện.
• Spawn ~254 process ping đồng thời trên Windows có overhead cao hơn Unix do Windows tạo process chậm hơn.