WAFB - Roadmap verso Parità Funzionale con AndroidQF

📊 Stato Attuale (v0.1.0) - Aggiornato Gennaio 2026

✅ Completamente Implementato

Core ADB Infrastructure (100%)

• ✅ ADBConnection con WebUSB
• ✅ ADBDevice (device properties, battery, network, storage, memory, sensors)
• ✅ ADBCommands (centralizzazione comandi shell, packages, logcat, bugreport, file operations)
• ✅ Error handling robusto (ADBError, ADBConnectionError, ADBDeviceNotFoundError, ADBCommandError)
• ✅ Logger con livelli (debug, info, warn, error)
• ✅ Stream helpers (readStreamAsText, readStreamAsBytes, retry logic)
• ✅ Root detection (isRooted())

Acquisition Base System (100%)

• ✅ BaseAcquirer con pattern riutilizzabile
  • Progress tracking standardizzato
  • Hash computation (SHA-256)
  • File download automatico
  • Error handling uniforme
  • Timestamp e metadata
• ✅ AcquisitionProgress interface
• ✅ AcquisitionResult interface
• ✅ AcquisitionMetadata system

Acquisition Modules Implementati (6/16 = 37.5%)

1. ✅ BugreportAcquirer

   • Supporto bugreportz (zip) e legacy (text)
   • Fallback automatico
   • Cleanup file temporanei
   • Hash computation

2. ✅ PackagesAcquirer

   • Lista completa pacchetti
   • Details per package (version, install time, etc.)
   • Permissions extraction
   • System/user package detection
   • JSON export strutturato

3. ✅ LogcatAcquirer

   • Multi-buffer support
   • Filtering avanzato
   • Stats extraction (errors, warnings, info counts)
   • Time range detection
   • Metadata export

4. ✅ SystemInfoAcquirer

   • Device properties complete
   • Battery information
   • Network status
   • Storage information
   • Memory information
   • Sensors enumeration
   • System properties (getprop)

5. ✅ RootBinariesAcquirer

   • Detection binari root (su, busybox, magisk, supersu, etc.)
   • Path identification
   • JSON export

6. ✅ EnvAcquirer

   • Environment variables
   • Text export

UI & State Management (100%)

• ✅ AcquisitionStore (Zustand)
  • Session management
  • Multi-acquisition tracking
  • Progress aggregation
  • Device capabilities detection
• ✅ Store tests completi (>95% coverage)
• ✅ Device/session lifecycle management

Testing Infrastructure (60%)

• ✅ Unit tests per utils (logger, errors, stream-helpers) - 100% coverage
• ✅ Unit tests per ADB (connection, device, commands) - >85% coverage
• ✅ Unit tests per stores (acquisitionStore) - >95% coverage
• ✅ Test helpers e mocks completi
• ✅ Vitest configurato con coverage reporting
• ⚠️ Integration tests presenti ma skipped (richiedono device reale)
• ❌ Unit tests per acquisition modules - MANCANTI
• ❌ E2E tests - MANCANTI
• ❌ Snapshot tests per format compatibility - MANCANTI

Overall Test Coverage: ~65% (target: >80%)

---

❌ Cosa Manca per Parità Funzionale

Critical Gaps (Bloccano MVP)

1. Core Acquisition Modules (10/16 mancanti = 62.5%)

• ❌ GetpropAcquirer
• ❌ SELinuxAcquirer
• ❌ SettingsAcquirer
• ❌ MountsAcquirer
• ❌ DumpsysAcquirer
• ❌ SystemLogsAcquirer
• ❌ ProcessesAcquirer
• ❌ ServicesAcquirer
• ❌ APKExtractor
• ❌ FilesAcquirer

2. Data Security & Chain of Custody

• ⚠️ Hash computation (SHA-256 solo, mancano MD5, SHA-1, SHA-512)
• ❌ hashes.csv centralizzato
• ❌ Encryption (Age)
• ❌ acquisition.json metadata standardizzato
• ❌ audit.log - chain of custody completa

3. Export & Compatibility

• ❌ AndroidQF-compatible directory structure
• ❌ AcquisitionPackager class
• ❌ ZIP export finale
• ❌ Schema validation
• ❌ MVT integration/documentation

4. Testing Robusto

• ❌ Unit tests per acquisition modules
• ❌ Integration tests funzionanti
• ❌ E2E tests (Playwright/Cypress)
• ❌ Snapshot tests
• Target: >80% overall coverage (attuale: ~65%)

Nice-to-Have (Non Bloccano MVP)

• ❌ BackupAcquirer (complesso)
• ❌ DatabasesAcquirer (requires root)
• ❌ CommunicationsAcquirer (requires root)
• ❌ BrowserAcquirer (requires root)
• ❌ MediaAcquirer (large data)
• ❌ NetworkAcquirer avanzato
• ❌ Collector binary (performance optimization)
• ❌ Analysis engine
• ❌ Report generation (HTML/PDF)

---

🎯 Roadmap Completa

FASE 1: Core Acquisition Modules (6 settimane)

Priorità: ALTA - Fondamentale per parità funzionale

Sprint 1 (2 settimane) - "System Foundation"

Goal: Completare acquisizioni di base sistema

• GetpropAcquirer (2 giorni)

  • Wrapper per ADBCommands.getprop()
  • Export JSON strutturato
  • Comparison con baseline (opzionale)
  • Output: getprop.json
  • Dependencies: Nessuna (usa API esistente)

• SELinuxAcquirer (1 giorno)

  • getenforce per status
  • sestatus -v per dettagli
  • Detection permissive/disabled (security risk)
  • Output: selinux.json
  • Dependencies: ADBCommands.shell()

• SettingsAcquirer (3 giorni)

  • settings list global
  • settings list secure
  • settings list system
  • Parsing strutturato per categoria
  • Anomaly detection (baseline comparison)
  • Output: settings.json
  • Dependencies: ADBCommands.shell()

• MountsAcquirer (2 giorni)

  • mount + /proc/mounts
  • Parsing: device, mountpoint, filesystem, options
  • Detection montaggi anomali (rw su system, hidden partitions)
  • Output: mounts.json
  • Dependencies: ADBCommands.shell()

• Tests per Sprint 1 (3 giorni)

  • Unit tests per i 4 moduli
  • Mock ADBDevice
  • Verify output format
  • Target coverage: >80%

Deliverable Sprint 1: 10/16 moduli completi (62.5%)

---

Sprint 2 (2 settimane) - "Processes & Services"

Goal: Informazioni runtime e debugging

• ProcessesAcquirer (4 giorni)

  • ps -A -o PID,PPID,UID,NAME,STATE,%CPU,%MEM,WCHAN
  • Parsing strutturato con metadata completi
  • Detection processi sospetti (pattern matching su names)
  • Correlazione con packages (via UID)
  • Output: processes.json
  • Dependencies: PackagesAcquirer per correlazione

• ServicesAcquirer (3 giorni)

  • service list
  • dumpsys activity services
  • Parsing e mapping servizi-processi-packages
  • Detection servizi anomali
  • Output: services.json
  • Dependencies: ProcessesAcquirer, PackagesAcquirer

• DumpsysAcquirer (3 giorni)

  • dumpsys completo
  • Focus servizi chiave:
    • package, activity, window
    • alarm, battery, wifi, telephony
  • Parsing per servizio
  • Output: dumpsys/ directory (file per servizio)
  • Dependencies: ADBCommands.shell()

• Tests per Sprint 2 (3 giorni)

  • Unit tests per ProcessesAcquirer
  • Unit tests per ServicesAcquirer
  • Unit tests per DumpsysAcquirer
  • Integration test workflow

Deliverable Sprint 2: 13/16 moduli completi (81.25%)

---

Sprint 3 (2 settimane) - "Filesystem & Logs"

Goal: Chain of custody e filesystem enumeration

• SystemLogsAcquirer (2 giorni)

  • /data/anr/ (ANR reports) - requires root
  • /data/log/ - requires root
  • /proc/kmsg, /proc/last_kmsg
  • /sys/fs/pstore/console-ramoops
  • Graceful fallback se no root
  • Output: system_logs/ directory
  • Dependencies: Root detection

• FilesAcquirer (5 giorni) ⚠️ PERFORMANCE CRITICAL

  • Listing ricorsivo con find:
    • /sdcard/ (sempre accessibile)
    • /system/, /vendor/, /data/ (requires root, fallback)
  • Metadata: path, size, permissions, timestamps (atime, mtime, ctime), owner/group
  • Hash selettivo (solo file critici configurabili)
  • ⚠️ LENTO su /sdcard/ - considerare collector binary
  • Output: files.json (structured tree)
  • Dependencies: Root detection per path privilegiati

• Hashing Completo (2 giorni)

  • Estendere a MD5, SHA-1, SHA-512 oltre SHA-256
  • Generare hashes.csv centralizzato per tutti i file
  • Format: file,md5,sha1,sha256,sha512
  • Dependencies: Tutte le acquisizioni

• Chain of Custody (2 giorni)

  • Implementare acquisition.json standardizzato:

    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp_start": "2024-01-15T10:30:00Z",
      "timestamp_end": "2024-01-15T10:45:30Z",
      "device": { "model": "...", "android_version": "...", ... },
      "wafb_version": "0.2.0",
      "operator": "optional",
      "modules_executed": [ ... ],
      "hashes": { "algorithm": "sha256", "files": { ... } }
    }
    

  • audit.log - ogni comando eseguito con timestamp
  • Dependencies: Tutte le acquisizioni

• Tests per Sprint 3 (2 giorni)

  • Unit tests SystemLogsAcquirer
  • Unit tests FilesAcquirer (mock filesystem)
  • Tests hash computation
  • Tests acquisition.json generation

Deliverable Sprint 3: 15/16 moduli completi (93.75%), chain of custody ✅

---

Sprint 4 (1 settimana) - "APK Extraction"

Goal: Completare tutti i core acquisition modules

• APKExtractor (5 giorni) ⚠️ COMPLESSO

  • Per ogni package: pm path <package>
  • Pull APK: ADBCommands.readFile(path)
  • Hash multipli: MD5, SHA-1, SHA-256, SHA-512
  • Signature verification: parsing certificato da dumpsys package
  • Metadata: package name, version, install location, first/last install time, signature
  • Output: apks/ directory + apks_metadata.json
  • Dependencies: PackagesAcquirer, hash computation

• Tests e Integration Tests (2 giorni)

  • Unit tests APKExtractor
  • Integration test: full workflow multi-module
  • Error handling tests
  • Hash verification tests

Deliverable Sprint 4: 16/16 moduli completi (100%) 🎉

---

FASE 2: Export & Packaging (2 settimane)

Priorità: ALTA - Necessario per compatibility AndroidQF

Sprint 5 (1 settimana) - "Export & AndroidQF Compatibility"

• AcquisitionPackager Class (3 giorni)

  • Creazione struttura directory AndroidQF-compatible:

    acquisition_<uuid>/
    ├── acquisition.json      # Metadata
    ├── hashes.csv           # All file hashes
    ├── bugreport.zip
    ├── packages.json
    ├── logcat.txt
    ├── getprop.json
    ├── settings.json
    ├── mounts.json
    ├── selinux.json
    ├── env.txt
    ├── system_info.json
    ├── root_binaries.json
    ├── processes.json
    ├── services.json
    ├── dumpsys/
    │   ├── package.txt
    │   ├── activity.txt
    │   └── ...
    ├── system_logs/
    │   └── ...
    ├── files.json
    ├── apks/
    │   ├── com.example.app.apk
    │   └── ...
    └── apks_metadata.json
    

  • ZIP finale con compressione
  • Dependencies: Tutte le acquisizioni completate

• Schema Validation (2 giorni)

  • JSON schema per acquisition.json
  • Validation automatica prima export
  • Error reporting per format issues

• MVT Compatibility Tests (1 giorno)

  • Test output con MVT
  • Documentazione integrazione
  • Script helper: wafb-to-mvt.sh

Deliverable Sprint 5: Export AndroidQF-compatible ✅

---

FASE 3: Security & Encryption (1 settimana)

Priorità: ALTA - Production-ready security

Sprint 6 (1 settimana) - "Encryption & Security Hardening"

• Age Encryption Integration (3 giorni)

  • Integrare age-wasm
  • Encrypt ogni file acquisito automaticamente
  • Output: *.age files
  • Supporto multiple recipient keys
  • Dependencies: Export completato

• UI per Encryption Configuration (2 giorni)

  • Input per public key(s)
  • Toggle encrypt on/off
  • Key management (storage sicuro in browser)
  • Verification workflow

• Security Audit (2 giorni)

  • Review permissions richieste
  • Audit data handling
  • Secure deletion dati non encrypted
  • Documentazione security best practices

Deliverable Sprint 6: Production-ready security ✅

---

FASE 4: Testing Robusto (1.5 settimane)

Priorità: ALTA - Quality assurance

Sprint 7 (1.5 settimane) - "Test Coverage Completo"

• Unit Tests per Acquisition Modules (3 giorni)

  • Tests per tutti i 16 moduli
  • Mock ADBDevice con output realistici
  • Verify JSON output format
  • Error handling scenarios
  • Target: >80% coverage per ogni modulo

• Integration Tests (2 giorni)

  • Setup mock device environment
  • Test full workflow: connect → select → acquire → export
  • Test multi-module parallel acquisition
  • Test error recovery e retry logic
  • Test hash computation end-to-end

• Snapshot Tests (2 giorni)

  • Capture output examples da androidqf reale
  • Snapshot tests per format compatibility
  • JSON schema validation automatica
  • Regression detection

• E2E Tests Setup (3 giorni)

  • Setup Playwright o Cypress
  • Test complete user flows:
    1. Device connection via WebUSB
    2. Module selection UI
    3. Acquisition con progress tracking
    4. Download results
    5. Verify output structure
  • CI/CD integration

Deliverable Sprint 7: >80% overall test coverage ✅

---

📊 Milestone Summary

Fase	Durata	Deliverable	Status
Attuale	-	6/16 moduli, test infra	✅ DONE
Fase 1	6 settimane	16/16 moduli + chain of custody	⏳ TODO
Fase 2	2 settimane	AndroidQF export compatibility	⏳ TODO
Fase 3	1 settimana	Production security	⏳ TODO
Fase 4	1.5 settimane	>80% test coverage	⏳ TODO
TOTALE PARITÀ	10.5 settimane	Production-ready v0.2.0	🎯 TARGET

---

🎯 Timeline to Parity

Parità Funzionale Base (16 core modules):

• 6 settimane (Sprint 1-4)
• Completamento: ~Marzo 2026

Parità Completa con AndroidQF (export, security, testing):

• 10.5 settimane (~2.5 mesi)
• Completamento: ~Fine Marzo 2026

Release v0.2.0 Production-Ready:

• Target: Aprile 2026

---

🚀 Advanced Features (Post-Parità) - FASE 5+

FASE 5: Performance Optimization (Optional - 4 settimane)

• Collector Binary Implementation
  • Scelta linguaggio: Rust (raccomandato) o Go
  • Cross-compilation per ARM64, ARM, x86, x86_64
  • Moduli:
    • File listing ottimizzato (10-50x più veloce di find)
    • Process enumeration dettagliata
    • Network connections real-time
    • Service enumeration
  • Deploy automatico su device
  • Fallback a shell commands se deployment fallisce
  • Benefit: Performance drasticamente migliori per FilesAcquirer

---

FASE 6: Root-Only Modules (Optional - 2 settimane)

• DatabasesAcquirer (5 giorni)

  • Enumerate: /data/data/<package>/databases/*.db
  • Pull databases interessanti (WhatsApp, SMS, Contacts, Chrome)
  • SQLite schema extraction
  • Output: databases/ + databases_metadata.json
  • Requires: Root access mandatory

• CommunicationsAcquirer (4 giorni)

  • SMS/MMS: /data/data/com.android.providers.telephony/databases/mmssms.db
  • Call logs: calllog.db
  • Contacts: contacts2.db
  • Parsed + raw database export
  • Requires: Root + DatabasesAcquirer

• BrowserAcquirer (3 giorni)

  • Chrome History: /data/data/com.android.chrome/app_chrome/Default/History
  • Cookies, bookmarks, webview data
  • Requires: Root + DatabasesAcquirer

---

FASE 7: Large Data Handling (Optional - 1 settimana)

• MediaAcquirer (4 giorni)

  • Enumerate (no pull): /sdcard/DCIM/, /sdcard/Pictures/, /sdcard/Download/
  • Metadata only: path, size, timestamps
  • Optional: hash selected files
  • Optional: thumbnail extraction
  • ⚠️ Non pull all media (too large)
  • Output: media.json metadata

• NetworkAcquirer Advanced (3 giorni)

  • WiFi configs: /data/misc/wifi/wpa_supplicant.conf (requires root)
  • Active connections: netstat -an
  • ARP cache: ip neigh
  • Routing table: ip route
  • Interface details: ip addr

---

FASE 8: Backup Acquisition (Optional - 1 settimana)

⚠️ PROBLEMA: adb backup non funziona via WebUSB standard

• BackupAcquirer (5 giorni) - REQUIRES RESEARCH
  • Studio protocollo ADB backup
  • Implementazione alternativa o workaround
  • Parsing formato .ab (Android Backup)
  • Selective extraction (SMS, contacts, etc.)
  • Potrebbe richiedere: Collector binary o approccio completamente diverso

---

FASE 9: Analysis & Reporting (Optional - 4 settimane)

• Analysis Engine (2 settimane)

  • IOC database integrato
  • Pattern matching su packages, processes, files, settings
  • Anomaly detection (baseline comparison, statistical analysis)
  • Suspicious patterns identification
  • Timeline construction e correlazione eventi

• Report Generation (2 settimane)

  • HTML Report interattivo:
    • Device info, findings, IOCs, timeline
    • Navigazione sezioni
    • Export standalone
  • PDF Report professionale:
    • Grafici e tabelle
    • Chain of custody inclusa
    • Executive summary
  • Risk scoring e recommendations

---

FASE 10: Collaboration & Automation (Optional - 2 settimane)

• Multi-User Support (1 settimana)

  • Session sharing
  • Collaborative analysis
  • Comments/annotations

• Automation (1 settimana)

  • Batch acquisition (multiple devices)
  • Scheduled acquisitions
  • CI/CD integration per automated testing

---

🧪 Testing Strategy

Current Status

• ✅ Unit tests: utils (100%), ADB core (>85%), stores (>95%)
• ⚠️ Acquisition modules: ~0% coverage
• ❌ Integration tests: skipped (require device)
• ❌ E2E tests: non implementati

Target Coverage (Post Sprint 7)

• Core (ADB, utils): >90% ✅ già raggiunto
• Stores: >90% ✅ già raggiunto
• Acquisitions: >80% 🎯 target
• Overall: >85% 🎯 target

Test Types da Implementare

1. Unit Tests Acquisition Modules (Sprint 7)

describe('GetpropAcquirer', () => {
  it('should acquire getprop data');
  it('should format output as JSON');
  it('should report progress correctly');
  it('should compute hash if configured');
  it('should handle errors gracefully');
});
// Replicare per tutti i 16 moduli

2. Integration Tests (Sprint 7)

describe('Full Acquisition Workflow', () => {
  it('should execute multiple modules in sequence');
  it('should generate valid acquisition.json');
  it('should compute all hashes correctly');
  it('should create AndroidQF-compatible structure');
  it('should handle partial failures gracefully');
});

3. Snapshot Tests (Sprint 7)

describe('Output Format Compatibility', () => {
  it('acquisition.json matches AndroidQF schema');
  it('packages.json matches expected format');
  it('processes.json matches expected format');
  // etc per ogni output type
});

4. E2E Tests (Sprint 7)

describe('User Acquisition Flow', () => {
  it('should connect device via WebUSB');
  it('should display device information');
  it('should select acquisition modules');
  it('should execute acquisition with progress');
  it('should download final ZIP');
  it('should verify output structure');
});

---

📋 Dependencies & Prerequisites

Technical Prerequisites

• ✅ WebUSB API support (Chrome/Edge)
• ✅ Crypto API for hashing
• ✅ IndexedDB per temporary storage (if needed)
• ⏳ Age-wasm per encryption (Sprint 6)

Device Prerequisites

• Android device con USB debugging enabled
• ADB server desktop must be stopped (adb kill-server)
• USB cable collegato

Optional Prerequisites

• Root access per alcuni moduli (graceful fallback se assente)
• SELinux permissive per file access esteso (graceful fallback)

---

🔧 Architecture Decisions

Design Principles (Validated)

✅ BaseAcquirer pattern - Ottimo per riutilizzo codice
✅ ADBCommands centralized - Previene duplicazione e semplifica testing
✅ Progress tracking uniforme - UX consistente
✅ Zustand stores - State management efficace

Future Decisions (Post-Parità)

⏳ Collector binary: Rust vs Go - decide in Sprint 8+
⏳ Backup strategy: Research protocollo ADB backup alternatives
⏳ Analysis engine: Local vs cloud processing

---

📚 References & Resources

AndroidQF Study

• AndroidQF GitHub
• Source files chiave:
  • acquisition.go - orchestration
  • modules/*.go - individual collectors
  • collector/ - Go binary source

Forensics Standards

• MVT Documentation
• NIST SP 800-101r1: Mobile Device Security Guidelines
• ISO/IEC 27037:2012: Digital Evidence Guidelines

Technical References

• ADB Protocol Internals
• WebUSB Specification
• Age Encryption
• @yume-chan/adb Documentation

---

💡 Lessons Learned

From AndroidQF

• ✅ Directory structure ben pensata → seguire schema
• ✅ Collector binary = game changer performance
• ⚠️ Molte features richiedono root → graceful fallback essenziale
• ⚠️ adb backup non via WebUSB → serve workaround

From WAFB Development

• ✅ BaseAcquirer pattern scalabile
• ✅ Centralized commands previene bugs
• ✅ Progress tracking visuale = punto di forza vs CLI
• ⚠️ Test coverage acquisition modules = priorità
• ⚠️ Export format standardization = critico per compatibility

Key Takeaways

1. Test-driven development per nuovi moduli → evita regressioni
2. Schema validation per output → garantisce compatibility
3. Graceful degradation → user experience anche senza root
4. Performance monitoring → tracciare tempi acquisizione
5. Documentation first → ogni modulo ben documentato

---

🎯 Success Metrics

Technical KPIs

• Feature Parity: 16/16 core modules (100%) 🎯
• Test Coverage: >85% overall 🎯
• Performance: <5min full acquisition (avg device) 🎯
• Reliability: <1% failure rate 🎯
• Compatibility: 100% AndroidQF format match 🎯

User KPIs

• Time to First Acquisition: <3min from device connect 🎯
• Documentation: Complete API docs + 5+ tutorials 🎯
• Community: 10+ contributors, 100+ GitHub stars (6 months) 🎯

Quality KPIs

• Bug Reports: <5 critical bugs in production
• Security Audits: Pass external security review
• Performance Benchmarks: Within 20% of native ADB

---

🚀 Immediate Next Steps (This Week)

Day 1-2: Test Infrastructure

1. ✅ Create comprehensive test mocks per acquisitions
2. ✅ Setup test helpers per ADBDevice/ADBCommands
3. ✅ Write example tests per 1-2 existing modules

Day 3-4: GetpropAcquirer

1. 🎯 Write tests first (TDD approach)
2. 🎯 Implement GetpropAcquirer
3. 🎯 Verify JSON output format
4. 🎯 Add to acquisition registry

Day 5: SELinuxAcquirer

1. 🎯 Write tests
2. 🎯 Implement acquirer
3. 🎯 Quick win - boost morale!

Week Goal: 8/16 modules complete (50%), test coverage >70%

---

📅 Release Plan

v0.2.0 - "Feature Parity" (Target: Aprile 2026)

• ✅ All 16 core acquisition modules
• ✅ AndroidQF-compatible export
• ✅ Production security (encryption, chain of custody)
• ✅ >85% test coverage
• ✅ Complete documentation

v0.3.0 - "Performance" (Target: Giugno 2026)

• Collector binary implementation
• 10x faster file enumeration
• Optimized multi-module parallel execution

v0.4.0 - "Advanced Features" (Target: Settembre 2026)

• Root-only modules (databases, communications, browser)
• Media acquirer
• Backup acquirer (se possibile)

v1.0.0 - "Production Stable" (Target: Fine 2026)

• Analysis engine
• Report generation
• Community-tested, production-proven
• Comprehensive documentation ecosystem

---

🤝 Contributing

Questa roadmap è in evoluzione. Contributi benvenuti per:

• Nuovi acquisition modules
• Performance optimizations