56 lines
2.0 KiB
Markdown
56 lines
2.0 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_pyshark.py` builds the context through tshark/pyshark.
|
|
- `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 --packet-limit 100000
|
|
```
|
|
|
|
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")
|
|
print(render(result, "md"))
|
|
|
|
# Detector logic can also be tested without tshark.
|
|
synthetic_result = AnalysisEngine().analyze_context(CaptureContext())
|
|
```
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
python -m unittest analyzer.tests.test_analyzer -v
|
|
```
|
|
|
|
The unit suite uses synthetic contexts and does not require tshark.
|
|
|
|
## 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/`.
|