User Guide

Complete guide to using VulnerabilityHub for vulnerability management.

Table of Contents

Dashboard Overview
Uploading Scans
Managing Contact Persons
Sending Reports
Email Templates
Viewing Analytics
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

Navigate to Scans → Upload
Click Choose File and select your Greenbone XML report
Click Upload
Wait for processing (progress indicator shown)
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:

The upload shows an orange “Conflict” status
Click Refresh icon to overwrite the existing file
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

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

Bulk Import via CSV

Go to Manage → Contact Persons
Click Upload CSV

Select your CSV file with columns:

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

Click Upload
Review import results (created/updated/conflicts)

Advanced Import Options

Database Import:

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:

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:

Accept: Confirm responsibility and download the report
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

Go to Reports → Sent Reports
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

Go to Manage → Mail Templates
See list of available templates: - new_report - New vulnerability report notification

Editing Templates

Click Edit on a template
Modify: - Subject: Email subject line - Body: Email content (supports placeholders)
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:

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

Navigate to Report Metrics or access Grafana directly
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

Admin generates a login token:

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

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

Managing Profile

After login, go to Profile
Edit: - Name - Email address - Assigned IP addresses
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:

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