Demo Data Generation
=====================

This guide explains how to generate demonstration data for testing and development purposes.

Overview
--------

The ``generate_demo_data.py`` script creates realistic test data based on a **University/Faculty** theme, including:

- **Users**: Admin and regular users (Profs, Students, IT Support)
- **Contact Persons**: Departments and individuals with IP and CIDR assignments
- **Hosts**: Servers with rich metadata (OS, Hostnames)
- **Scans**: Vulnerability reports (XML, PDF, HTML) with linked products, locations, and sources.
- **Linked Reports**: Scenarios where XML, PDF, and HTML reports share the same report ID/filename.
- **Trend Data**: Historical scan data generated daily for the last 30 days
- **Access Logs**: Simulated usage history

Prerequisites
-------------

The script must be run inside the Docker backend container to access the database.

Running the Script
------------------

Basic Usage
~~~~~~~~~~~

.. code-block:: bash

   docker exec vulnerability-scanner-backend-1 python /app/generate_demo_data.py

First-Time Setup
~~~~~~~~~~~~~~~~

If the script is not yet in the container (e.g. if you modified it locally), copy it first:

.. code-block:: bash

   docker cp src/backend/generate_demo_data.py vulnerability-scanner-backend-1:/app/
   docker exec vulnerability-scanner-backend-1 python /app/generate_demo_data.py

Generated Data
--------------

Users
~~~~~

The script creates the following demo users. 

**Default Password**: ``DemoPass123!``

.. list-table::
   :header-rows: 1
   :widths: 20 30 30 20

   * - Username
     - Full Name
     - Email
     - Role
   * - **prof_mueller**
     - Prof. Dr. Thomas Müller
     - thomas.mueller@uni.de
     - Admin
   * - **dr_schmidt**
     - Dr. Anna Schmidt
     - anna.schmidt@uni.edu
     - User
   * - **stud_weber**
     - Maximilian Weber
     - max.weber@student.uni.edu
     - User
   * - **admin_fischer**
     - Klaus Fischer
     - klaus.fischer@rz.uni.edu
     - Admin
   * - **user_bib**
     - Bibliothek EDV
     - edv@bibliothek.uni.edu
     - User
   * - **user_rz**
     - IT Support RZ
     - it-support@rz.uni.edu
     - Admin

Contact Persons
~~~~~~~~~~~~~~~

Contact persons are created to demonstrate IP and CIDR ownership:

1. **Prof. Dr. Thomas Müller**
   - IPs: ``192.0.2.10``, ``192.0.2.11``, ...

2. **IT Rechenzentrum**
   - CIDR: ``192.0.2.0/24``, ``198.51.100.0/24``, ``203.0.113.0/24`` (Network Wide)

3. **Fakultät Informatik**
   - IPs: ``203.0.113.1``, ``203.0.113.2``
   - CIDR: ``203.0.113.0/24``

4. **Bibliothek**
   - IPs: ``198.51.100.40``

Hosts & Metadata
~~~~~~~~~~~~~~~~

Hosts are enriched with realistic metadata:

- **Hostname**: e.g., ``webserver01.informatik.uni.edu``
- **OS**: e.g., ``Ubuntu 22.04 LTS``, ``Debian 11``, ``Windows Server 2019``

Linked Data:
- **Products**: ``OpenSSH 8.2p1``, ``Apache/2.4.41``, etc.
- **Locations**: ``tcp/80``, ``tcp/443``, etc.
- **Sources**: ``NVT Feed``, ``CVE Feed``

Historical Trend Data
~~~~~~~~~~~~~~~~~~~~~

To populate the **Vulnerability Trend** dashboard, the script generates:

- **Daily Scans**: For the last 30 days
- **Target**: ``Fakultät für Informatik`` (webserver01)
- **Varying Severity**: Random mix of High/Medium/Low vulnerabilities to show trend lines.

Scan Scenarios
~~~~~~~~~~~~~~

Specific scenarios are created to test logic:

- **Unaccessed Report**: A report created 1 day ago that has never been opened (testing notifications).
- **Linked Reports**: A full set (XML, PDF, HTML) for ``Rechenzentrum`` to test UI grouping.
- **Orphan Reports**: Standalone PDF or HTML files (e.g. ``Legacy_Scan_2023.pdf``) to test individual file handling.
- **Unknown Owner**: A report for an IP (``192.0.2.199``) not assigned to any contact.
- **Legacy Scan**: Old scan from >30 days ago.

Resetting Demo Data
-------------------

The script is idempotent for inserts (skips existing IDs/Emails), but for a clean slate:

.. code-block:: bash

   # Stop containers
   docker compose down -v
   
   # Restart
   docker compose up -d

   # Re-run script
   docker exec vulnerability-scanner-backend-1 python /app/generate_demo_data.py

Troubleshooting
---------------

**UnboundLocalError**: If you see an error about `vuln_objs`, ensure you are using the latest version of the script where vulnerability creation is ordered *before* the trend data loop.