IoT_PreTester_V46_Demo/django_project/analyzer/README.md

IoT PreTester 4.6 Demo analysis core

analyzer is the framework-independent network-capture analysis package used by both the Django backend and the command-line interface. It accepts .pcap or .pcapng files, normalizes protocol data once, runs independent detectors, and renders Markdown, text, or JSON reports.

Main modules

• context.py defines the normalized CaptureContext records.
• extract_tshark.py builds the context by streaming tshark -T ek output (two passes: metadata, then clear-text payloads).
• tls_tables.py maps tshark's numeric cipher-suite and version values to names.
• allowlist.py lists expected provider domains used to lower severity.
• inventory.py builds the complete observation inventory.
• detectors/ contains one detection concern per module.
• engine.py runs detectors and assembles the final result.
• scoring.py deduplicates and prioritizes findings.
• provenance.py attaches artifacts and packet/stream references.
• artifacts.py extracts URL and hash artifacts from the shared context.
• enrich/ provides optional URL probing and hash recovery.
• reporting/ renders md, txt, and json output.

Command line

From django_project/:

python -m analyzer.cli ../demo_files/demo_capture.pcapng
python -m analyzer.cli capture.pcapng -f json -o report.json
python -m analyzer.cli capture.pcapng -f txt --device-ip 192.168.1.50
python -m analyzer.cli capture.pcapng -f json --packet-limit 100000
python -m analyzer.cli capture.pcapng -v --log-file analysis.log   # debug log on stderr and in a file

Exit codes are 0 for no high/critical findings, 2 when at least one high/critical finding exists, and 1 for execution errors.

Python API

from analyzer import AnalysisEngine, render
from analyzer.context import CaptureContext

result = AnalysisEngine().analyze_pcap("capture.pcapng", device_ip="192.168.1.50")
print(render(result, "md"))
print(result.inventory["device"])

# Detector logic can also be tested without tshark.
synthetic_result = AnalysisEngine().analyze_context(CaptureContext())

Tests

python -m unittest analyzer.tests.test_analyzer analyzer.tests.test_regressions -v

The unit suite uses synthetic contexts and does not require tshark. test_regressions.py also runs the real extractor against demo_files/demo_capture.pcapng when tshark is installed (set ANALYZER_DEMO_DIR to point at another demo directory).

Configuration

Variable	Default	Meaning
TSHARK_PATH	tshark on PATH	tshark binary used for extraction
CAPTURE_PACKET_LIMIT	0	Packets to read; 0 reads the whole capture
CAPTURE_MAX_TEXT_PAYLOADS	50000	Retained clear-text payload entries
CAPTURE_MAX_PAYLOAD_CHARS	16384	Characters kept per payload entry
ANALYZER_BENIGN_DOMAINS	empty	Extra provider domain suffixes for allowlist.py

Adding a detector

1. Add a focused module under detectors/.
2. Inherit from BaseDetector, apply @register, and return shared Finding objects from detect().
3. Import the module from detectors/__init__.py.
4. Add focused tests under tests/.