# 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/`:

```bash
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

```python
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

```bash
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/`.