IoT_PreTester_V46_Demo/ARCHITECTURE.md

IoT PreTester 4.6 Demo — Architecture

Purpose and boundary

IoT PreTester 4.6 Demo analyzes existing .pcap and .pcapng files and turns packet-level observations into prioritized security findings. It is intentionally limited to network-capture analysis. Live capture, streaming, and firmware binary analysis are outside the demo scope.

Runtime components

Component	Responsibility
Next.js frontend	Authentication flow, device administration, capture upload, findings display, report download, and optional deep-analysis controls
Django REST backend	API, validation, persistence, user/device administration, and integration with the analysis core
analyzer package	Django-independent capture extraction, detection, scoring, provenance, and report rendering
SQLite	Demo persistence for devices, files, findings, extracted artifacts, and analysis status
tshark/pyshark	Protocol dissection and normalized capture extraction
nmap/hashcat	Optional, explicitly initiated endpoint probing and offline hash recovery

Analysis flow

1. The frontend sends the capture and metadata to the authenticated Django API.
2. Django validates the upload, stores it in a dedicated volume, and creates the database records.
3. extract_pyshark.py parses the capture once into a normalized CaptureContext.
4. Ten independent detectors evaluate that shared context.
5. The engine deduplicates and prioritizes findings, then attaches capture, packet, stream, and artifact provenance.
6. Django persists the result and extracted URL/hash artifacts.
7. The frontend displays findings and can request Markdown, text, or JSON reports.
8. Optional URL/hash enrichment runs only for artifacts selected by the user.

Analysis package

django_project/analyzer/
├── context.py              Normalized capture data model
├── extract_pyshark.py      PCAP/PCAPNG extraction
├── engine.py               Detector orchestration and result assembly
├── findings.py             Shared finding taxonomy
├── provenance.py           Packet- and stream-level evidence references
├── scoring.py              Deduplication and prioritization
├── artifacts.py            URL and hash extraction
├── detectors/              Independent detection rules
├── enrich/                 Optional active enrichment
├── reporting/              Markdown, text, and JSON output
└── tests/                  Synthetic unit and regression tests

The package does not import Django. pyshark and external tools are loaded only at the integration points that need them, so detector tests can run on synthetic contexts without tshark.

Finding model

Every detector produces the same core fields: ID, title, category, severity, confidence, affected device, source and destination, protocol, port, time range, evidence, risk description, recommendation, packet references, and stream references.

Severity measures the potential impact if a finding is true. Confidence measures how strongly the capture supports it. Keeping these dimensions separate prevents low-confidence indicators from being presented as confirmed critical events.

Detector set

1. Plaintext credentials
2. Password hashes and challenge-response material
3. Session tokens and secrets
4. Malware or command-and-control beaconing
5. Possible data exfiltration
6. Man-in-the-middle and local network manipulation
7. Insecure or unexpected protocols
8. Weak or obsolete TLS
9. DNS anomalies and tunneling indicators
10. Brute force, scanning, and suspicious file transfer

Design decisions

• Parse each capture once and share normalized records across all detectors.
• Keep detector logic isolated from persistence, presentation, and external tools.
• Preserve evidence provenance so every finding can be traced back to the capture.
• Keep active probing opt-in because authorization can differ from authorization to inspect a capture.
• Use a small demo wordlist by default to keep distribution compact and behavior predictable.
• Store complete analysis results as JSON while keeping extracted artifacts and job status queryable.

Known demo limitations

• SQLite and in-process background threads are suitable for a controlled demo, not horizontal production scaling.
• Capture quality and protocol encryption directly limit what can be detected.
• URL probes observe the endpoint at probe time, which can differ from capture time.
• The demo does not provide live packet capture, multi-tenant isolation, or production identity-provider integration.