libmacfin

⚠️ Pre-1.0 Development — M0–M6 milestones shipped. Not for production use.

libmacfin is a Rust library for network device fingerprinting. It probes a target IP (active/passive), produces a 64-bit SimHash device fingerprint with similarity scoring, and outputs device class, OS, brand, model, running services, and protocol stack metadata.

Design Goals

• Small binary: stripped ≤ 1.5 MB (opt-level = "z", lto = "fat", panic = "abort")
• Low memory: ≤ 8 MB resident, zero-copy rkyv + mmap data loading
• No internal threads: caller controls concurrency model
• Cross-language: unified extern "C" ABI for C/C++, Rust, Python, Java

Workspace Crates

Crate	Purpose
core	Traits, errors, scoring, ID codecs
probe	Probing engine (TCP/ICMP/UDP, banners, UPnP, SNMP, mDNS, RTSP, SIP) + 13 Prober trait data pipeline
ouidb	IEEE MA-L/M/S vendor lookup
signet	Protocol-stack signature matching (p0f-style + custom binary)
banner	Banner / version-string parsing (SSH, HTTP, FTP, SMTP, etc.)
branddb	Brand & model identification (12 signal classes, 50+ vendors, 1,000+ models)
ipgeo	Offline IP geolocation / ASN (MaxMind MMDB)
idgen	SimHash + BLAKE3 composite ID generator
matchr	Weighted multi-feature similarity matching + Top-K
datastore	Embedded read-only DB (rkyv / postcard, mmap load)
ffi-c	C ABI exposure layer (macfin_c static + dynamic lib + rlib)
sdk-rust	Rust SDK and examples (basic, batch, match_topk)

All crates communicate through libmacfin-core traits only; no direct inter-crate dependencies.

Language SDKs (M5)

Unified extern "C" ABI is the single source of truth; each language SDK is a thin wrapper plus examples.

SDK	Layout	Build
C / C++	sdk-c/ (CMake + Make)	make c
Python	sdk-python/ (ctypes, _macfin shim)	make python
Java	sdk-java/ (Maven, JNI)	make java
Rust	sdk-rust/ (cargo, idiomatic API)	cargo run --example batch -p libmacfin-sdk

Generated C header lives at sdk-c/include/libmacfin.h; regenerate via make header.

Benchmarks (M6)

Criterion-based harness under tools/bench/, covering size, memory, ID generation, and 1v1 / 1v10k matching throughput.

make bench-quick          # quick mode, ~30 s
make bench                # full criterion run

Latest measured numbers vs. spec targets are tracked in docs/M6-benchmark-report.md. Highlights from the most recent run:

• 1v10k matching: 8.89 ms (target ≤ 5 s — 562× headroom)
• ID generation (30 features): 4.94 µs (target ≤ 5 µs)
• Resident memory after branddb × 1000: 2.73 MB (target ≤ 8 MB)
• 1v1 matching: 1.04 µs (target ≤ 0.3 µs — flagged for optimization)
• macfin_c.dll: 524 KB (target ≤ 1.8 MB)

Documentation

Full v1 specification is split into six design documents under docs/:

1. Project Overview
2. Research & Library Selection
3. System Architecture
4. Brand & Model Identification
5. API & Data Format Spec
6. Build Plan

Auxiliary:

• M6 Benchmark Report — measured numbers vs. spec
• libmacfin Spec v1 (consolidated)
• tools/bench README — benchmark harness usage

Milestones

Phase	Status	Deliverable
M0 Docs	✅	6 design documents
M1 Skeleton	✅	Cargo workspace + 11 crates + CI
M2 Probing	✅	TCP/ICMP/UDP + banners + UPnP/SNMP/mDNS/RTSP/SIP + Nmap probes + Prober trait data pipeline
M3 Profiling	✅	OUIdb + signatures + branddb (50+ vendors, 1,000+ models) + ipgeo
M4 ID & Match	✅	SimHash 64-bit + string ID + similarity scoring + Top-K
M5 FFI	✅	macfin_c C ABI (static + dynamic + rlib) + C header + 4 language SDKs (C, Python, Java, Rust)
M6 Benchmarks	✅	Criterion bench harness (idgen / match / scan / memory) + docs/M6-benchmark-report.md

Build & Test

The top-level Makefile wraps the common workflows (规范 §6.10):

make all         # data + build + test
make data        # regenerate branddb / oui rkyv catalogs
make build       # cargo build --workspace --release
make test        # cargo test --workspace
make clippy      # cargo clippy --workspace --all-targets -- -D warnings
make fmt         # cargo fmt --all
make header      # regenerate sdk-c/include/libmacfin.h via cbindgen

License

• Code: MIT OR Apache-2.0
• Bundled data: respective upstream licenses (IEEE, p0f, Nmap, MaxMind). No commercial database is bundled; users download and load via libmacfin-datastore.