IoT_PreTester_V46_Demo/README.md

# IoT PreTester 4.6 Demo

IoT PreTester 4.6 Demo is a partner-ready demonstration platform for security analysis of IoT network captures. A Django REST backend extracts and evaluates PCAP/PCAPNG traffic, while a Next.js frontend manages devices, starts analyses, and presents prioritized findings with packet-level evidence.

## Demo scope

- Upload and analyze `.pcap` and `.pcapng` captures.
- Detect credential exposure (FTP, Telnet, POP3, IMAP, SMTP, HTTP forms/JSON/Basic, MQTT, SNMP), secrets, suspicious traffic patterns, clear-text and legacy protocols (incl. MQTT, CoAP, RTSP, Modbus, TFTP), TLS issues (negotiated version/cipher, client capabilities, certificates), DNS anomalies, scanning, brute force, unprotected firmware transfers, and possible exfiltration.
- Present a complete observation inventory (device peers, hosts, endpoints, services, TLS posture, DNS, coverage) so nothing is overlooked even when no finding is raised.
- Review affected endpoints, evidence, packet references, severity, confidence, and recommendations.
- Export reports as Markdown, plain text, or JSON.
- Optionally run user-selected URL probes and offline hash checks.
- Manage demo devices, manufacturers, device types, and users.

Firmware binary analysis and historical prototype pages are intentionally not part of this demo.

## Requirements

- Docker Desktop or Docker Engine with Docker Compose
- At least 4 GB of free memory for the two application containers
- A modern web browser

No local Python, Node.js, tshark, nmap, or hashcat installation is required for the Docker workflow. For headless use outside Docker, install tshark (Wireshark 4.0 or newer) and `pip install -r requirements.txt`.

## Quick start

1. Create the local configuration:

   ```bash
   cp .env.example .env
   ```

2. Set secure values for `SECRET_KEY` and `DJANGO_SUPERUSER_PASSWORD` in `.env`.

3. Build and start the demo:

   ```bash
   docker compose up -d --build
   docker compose ps
   ```

4. Open [http://localhost:3000](http://localhost:3000) and sign in with the admin credentials from `.env`.

5. Open the sample device, upload [`demo_files/demo_capture.pcapng`](./demo_files/demo_capture.pcapng), enter the device IP and firmware metadata, then start the scan.

The initial image build can take several minutes because the backend includes network-analysis tools. The application is ready when both containers are healthy.

## Common commands

| Task | Command |
| --- | --- |
| Start | `docker compose up -d` |
| Stop | `docker compose stop` |
| Status | `docker compose ps` |
| Follow logs | `docker compose logs -f` |
| Run backend tests | `make test` |
| Rebuild | `docker compose up -d --build --force-recreate` |

Equivalent shortcuts are available through `make help`.

## Repository structure

```text
.
├── frontend/                         Next.js user interface
├── django_project/
│   ├── IoTAnalyzer/                   Django API and persistence adapters
│   ├── IoTPreTester/                  Django configuration
│   └── analyzer/                      Framework-independent analysis engine
├── demo_files/                        Partner-safe sample capture and wordlist
├── docker/                            Container entrypoints
├── ARCHITECTURE.md                    Architecture and security-detection design
├── docker-compose.yml                 Demo runtime
└── Makefile                           Convenience commands
```

## Headless analysis

The analysis core can also run without Django:

```bash
cd django_project
python -m analyzer.cli ../demo_files/demo_capture.pcapng -f md -o report.md
python -m analyzer.cli capture.pcapng -f json --device-ip 192.168.1.50 -o report.json
```

`--device-ip` marks the device under test: findings that involve it are attributed and sorted first, and the report's observation inventory lists every peer, service, TLS handshake and DNS name of that device. The web UI passes the IP entered at upload time automatically.

Exit code `0` means no high/critical findings, `2` means at least one high/critical finding, and `1` indicates an execution error.

## Logs and troubleshooting

| Where | What |
| --- | --- |
| `docker compose logs -f backend` | Application log (requests, analysis phases, errors with tracebacks) |
| `/app/logs/backend.log` in the backend container | Same log as a rotating file (10 MB × 5) |
| `/app/files/uploads/<capture>.analysis.log` | Complete log of one capture analysis; shown in the UI when an analysis fails |
| `GET /api/get_analysis_log/<file_id>` | Tail of that per-capture log |
| `GET /api/health` | tshark/hashcat/nmap availability, analyzer version, upload directory, log level |
| Browser console | Client log with API timings; `window.__iotpDumpLogs()` copies the last 300 entries |

Set `LOG_LEVEL=debug` in `.env` to log every detector step and the exact tshark command lines. Every API response carries an `X-Request-ID` header that also appears in the backend log line for that request. In the browser, `localStorage.setItem("iotp_log_level", "debug")` raises the client log level without a rebuild.

## Demo safety notes

- Only upload captures that you are authorized to inspect. Captures can contain credentials, tokens, personal data, and internal addresses.
- Active URL probing is started manually for selected endpoints. Do not probe third-party systems without permission.
- Hash recovery uses the deliberately small `demo_files/demo_wordlist.txt`. Supply an authorized external wordlist only when required.
- This configuration is intended for controlled demonstrations, not public internet exposure.
- Runtime data, uploaded captures, logs, and `.env` are excluded from version control.

## Documentation

- [`ARCHITECTURE.md`](./ARCHITECTURE.md) describes the data flow, detector model, and module boundaries.
- [`django_project/analyzer/README.md`](./django_project/analyzer/README.md) documents the standalone analysis package.

## Distribution

This repository is supplied as **IoT PreTester 4.6 Demo** for an agreed partner demonstration. No public license is granted by the repository; redistribution or commercial use requires the owner's written permission.