build 4.6 Demo

2026-08-19 08:04:59 +02:00
commit ff8f1ca989
123 changed files with 17696 additions and 0 deletions
@@ -0,0 +1,81 @@
+# 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
+
+```text
+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.