User Guide
==========


Complete guide to using VulnerabilityHub for vulnerability management.

Table of Contents
-----------------

- `Dashboard Overview <#dashboard-overview>`_
- `Uploading Scans <#uploading-scans>`_
- `Managing Contact Persons <#managing-contact-persons>`_
- `Sending Reports <#sending-reports>`_
- `Email Templates <#email-templates>`_
- `Viewing Analytics <#viewing-analytics>`_
- `Contact Person Self-Service <#contact-person-self-service>`_

Dashboard Overview
------------------


After logging in, you'll see the main dashboard with:
- **Recent Scans**: Latest vulnerability scans uploaded
- **Statistics**: Total vulnerabilities, hosts, critical issues
- **Quick Actions**: Upload scan, manage contacts, send reports

Uploading Scans
---------------


Via Web Interface
~~~~~~~~~~~~~~~~~


1. Navigate to **Scans** → **Upload**
2. Click **Choose File** and select your Greenbone XML report
3. Click **Upload**
4. Wait for processing (progress indicator shown)
5. View results in the scans list

Supported Formats
~~~~~~~~~~~~~~~~~

- **Greenbone/OpenVAS XML** reports (parsed for vulnerabilities)
- **PDF** reports (stored, grouped with XML)
- **HTML** reports (stored, grouped with XML)
- **ZIP** archives (bulk processing of mixed formats)
- File size limit: 100MB (configurable)

.. note::
   PDF and HTML uploads are stored but not parsed. They are grouped with XML 
   files sharing the same base filename for unified management.

Report Grouping
~~~~~~~~~~~~~~~

Files with the same base filename are automatically grouped:

- ``audit_2025.xml`` + ``audit_2025.pdf`` → Grouped as "audit_2025"
- Each format appears as a badge in the Manage Reports view
- Download or delete individual formats or entire groups

Conflict Resolution
~~~~~~~~~~~~~~~~~~~

When uploading a file that already exists:

1. The upload shows an **orange "Conflict"** status
2. Click **Refresh** icon to overwrite the existing file
3. Click **Close** icon to cancel the upload

What Gets Extracted
~~~~~~~~~~~~~~~~~~~

- Vulnerabilities (CVE IDs, severity, descriptions)
- Affected hosts (IP addresses, hostnames)
- Products (CPE identifiers)
- Sources and locations

Managing Contact Persons
------------------------


Contact persons are individuals responsible for specific IP addresses who receive vulnerability notifications.

Adding Contact Persons Manually
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


1. Go to **Manage** → **Contact Persons**
2. Click **Add Contact Person**
3. Fill in:
   - **Name**: Full name
   - **Email**: Contact email address
   - **IP Addresses**: Comma-separated list or use chips
4. Click **Save**

Bulk Import via CSV
~~~~~~~~~~~~~~~~~~~


1. Go to **Manage** → **Contact Persons**
2. Click **Upload CSV**
3. Select your CSV file with columns:

   .. code-block:: text

      name,email,ips
      John Doe,john@example.com,"192.168.1.1,192.168.1.2"
      Jane Smith,jane@example.com,10.0.0.1

4. Click **Upload**
5. Review import results (created/updated/conflicts)

Advanced Import Options
~~~~~~~~~~~~~~~~~~~~~~~


**Database Import**:

.. code-block:: bash

   curl -X POST "http://localhost:8000/contact-persons/import" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "source_type": "database",
       "connection_string": "postgresql://user:pass@host/db",
       "query": "SELECT name, email, ips FROM contacts"
     }'


**Script Import**:

.. code-block:: bash

   curl -X POST "http://localhost:8000/contact-persons/import" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "source_type": "script",
       "script_path": "/path/to/fetch_contacts.sh"
     }'


Conflict Resolution
~~~~~~~~~~~~~~~~~~~


When re-importing contacts, the system detects manual changes:
- **Skip Conflicts** (default): Preserves manual edits
- **Force Import**: Overwrites all fields
- Conflicts are logged for review

Sending Reports
---------------


Automatic Notifications
~~~~~~~~~~~~~~~~~~~~~~~


After uploading a scan, the system automatically:
1. Identifies affected IP addresses
2. Finds associated contact persons
3. Generates magic links (24-hour expiry)
4. Sends email notifications

Magic Links
~~~~~~~~~~~


Magic links provide secure, time-limited access to reports:

- **Format**: ``http://server:port/reports/{hash}``
- **Expiry**: 24 hours from first access
- **Access Logging**: Every access is recorded
- **Multiple access**: Can be accessed multiple times within 24h

.. warning::
   **Security**: Magic links can only be used by the assigned contact person. 
   If another user clicks the link, they will receive a **403 Forbidden** error.
   This prevents unauthorized access if links are forwarded.

Accepting or Declining Reports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When accessing a report via magic link:

1. **Accept**: Confirm responsibility and download the report
2. **Decline**: Open a dispute for admin review

.. note::
   Both actions require the logged-in user's email to match a contact person 
   assigned to the report's IP addresses.

Monitoring Sent Reports
~~~~~~~~~~~~~~~~~~~~~~~


1. Go to **Reports** → **Sent Reports**
2. View dashboard showing:
   - Report name and recipient
   - Sent date
   - Status (Sent/Accessed/Expired)
   - Access count
   - Time remaining

Alert System
~~~~~~~~~~~~


Reports not accessed within 72 hours are highlighted:
- **Red border** around the row
- **Red background** for visibility
- Alerted rows sorted to top

Email Templates
---------------


Customize notification emails sent to contact persons.

Viewing Templates
~~~~~~~~~~~~~~~~~


1. Go to **Manage** → **Mail Templates**
2. See list of available templates:
   - ``new_report`` - New vulnerability report notification

Editing Templates
~~~~~~~~~~~~~~~~~


1. Click **Edit** on a template
2. Modify:
   - **Subject**: Email subject line
   - **Body**: Email content (supports placeholders)
3. Click **Save**

Available Placeholders
~~~~~~~~~~~~~~~~~~~~~~


- ``{name}`` - Contact person's name
- ``{ip_address}`` - Affected IP address
- ``{magic_link}`` - Secure report access link

Example Template
~~~~~~~~~~~~~~~~


**Subject**: ``New Vulnerability Report for {ip_address}``

**Body**:

.. code-block:: bash

   Hello {name},
   
   A new vulnerability report has been generated for the system with IP address {ip_address}.
   
   You can access the report using the following secure link:
   {magic_link}
   
   This link will expire 24 hours after first access.
   
   Best regards,
   Security Team


Viewing Analytics
-----------------


Grafana Dashboards
~~~~~~~~~~~~~~~~~~


1. Navigate to **Report Metrics** or access Grafana directly
2. Available dashboards:
   - **Vulnerability Reports**: Detailed analysis
   - **Service Status**: System health

Key Metrics
~~~~~~~~~~~


- **Top Vulnerable Hosts**: Ranked by severity
- **Severity Distribution**: Pie chart of High/Medium/Low
- **Trend Analysis**: Historical vulnerability counts
- **Predictions**: ML-based 30-day forecasts

Filtering Data
~~~~~~~~~~~~~~


Use dashboard variables to filter:
- **Institution**: Select specific organization
- **Severity**: Filter by High/Medium/Low
- **Time Range**: Custom date ranges
- **Host**: Focus on specific IP/hostname


Contact Person Self-Service
---------------------------


Contact persons can manage their own information without admin access.

Logging In
~~~~~~~~~~


1. Admin generates a login token:

   .. code-block:: bash

      curl -X POST "http://localhost:8000/contact-persons/{id}/generate-token" \\
        -H "Authorization: Bearer $ADMIN_TOKEN"

2. Contact person visits: ``http://localhost:8080/contact-login?token={token}``
3. Automatically logged in

Managing Profile
~~~~~~~~~~~~~~~~


1. After login, go to **Profile**
2. Edit:
   - Name
   - Email address
   - Assigned IP addresses
3. Click **Save**

Restrictions
~~~~~~~~~~~~


Contact persons can only:
- View and edit their own profile
- Manage their assigned IP addresses
- Cannot change password (token-based auth)
- Cannot access admin functions


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


Reports Not Sending
~~~~~~~~~~~~~~~~~~~


**Check**:
1. SMTP configuration in ``.env``
2. Contact person has valid email
3. IP address is correctly assigned
4. Email template exists

**Logs**:

.. code-block:: bash

   docker-compose logs backend | grep "email"


Magic Links Not Working
~~~~~~~~~~~~~~~~~~~~~~~


**Verify**:
1. ``BACKEND_URL`` is set correctly in ``.env``
2. Link hasn't expired (24h from first access)
3. Check access logs for errors


Import Conflicts
~~~~~~~~~~~~~~~~


**Resolution**:
1. Review conflict report after import
2. Manually resolve critical conflicts
3. Use "Force Import" only if intentional
4. Check ``contact_person_changes`` table for audit trail