72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
# 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/`.
|