User Guide

Complete guide to using VulnerabilityHub for vulnerability management.

Table of Contents

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. Per-host PDF/HTML reports are also matched to a master XML by configured filename patterns or same-base filename fallback. Filename patterns are the preferred way to distinguish recurring scans of the same network, and already linked visual reports are not moved by later XML uploads. Only unique matches are linked automatically; ambiguous matches remain available for admin review.

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

  • Per-host visual reports with an explicit XML match use the matched host IP for notifications, access authorization, and vulnerability counts

  • Ambiguous or unmatched per-host reports remain pending and appear as action required in the Sent Reports dashboard

Visual Report Matching Cascade

When a PDF or HTML visual report is uploaded, VulnerabilityHub keeps the visual report as its own Scan record and tries to link it to a master XML through report_file_matches. Existing matched visual reports are treated as fixed: later rescans of the same network do not move them to a newer XML.

The automatic linker is deliberately conservative. It only creates a matched link when it can identify exactly one XML scan and exactly one host IP inside that XML. Otherwise the visual report stays pending as unmatched or ambiguous and requires admin review from Manage → Disputes.

        flowchart TD
   A[PDF or HTML visual report uploaded] --> B{Already has a matched link?}
   B -- Yes --> C[Keep existing XML and host assignment]
   B -- No --> D[Extract visual filename context]
   D --> D1[Configured visual filename pattern]
   D --> D2[Base filename fallback]
   D1 --> E[Load XML candidates]
   D2 --> E
   E --> F[Extract XML filename context and host inventory]
   F --> G{Any XML candidates?}
   G -- No --> U[Mark unmatched and create a missing XML dispute]
   G -- Yes --> H[Try match methods in priority order]
   H --> H1[Parsed filename family plus host IP suffix]
   H1 --> H2[Same base filename as XML]
   H2 --> J{Exactly one XML and one host IP?}
   J -- Host IP --> M[Save matched visual, XML, host IP, and method]
   J -- Multiple XMLs or hosts --> A1[Mark ambiguous for admin review]
   J -- No match at any priority --> U
   M --> N[Notify only contacts responsible for the matched host IP]
   A1 --> O[No notification is sent]
   U --> O

The priority order is:

  1. Filename pattern family: active patterns parse a base report name, optional date, and optional host IP. A visual report such as 2026-02-01_campus_198.51.100.5.html links to 2026-02-01_campus.xml when that XML contains the host IP. Master visual reports without a host suffix are also accepted by explicit visual patterns such as 2026-02-01_campus.html and campus_master.pdf; they still need a unique host inference or an admin selection before delivery.

  2. Same base filename: campus.html or campus.pdf links to campus.xml when the host can be inferred from the visual report or the XML contains exactly one host.

The matching process no longer uses a fixed upload-date window. Older reports can be uploaded later as long as their filenames follow an active pattern or share the XML base filename. If a filename does not match any active pattern, the upload screen warns the admin before upload. ZIP uploads bypass that warning because the archive contents are inspected after extraction. When a visual report cannot be linked automatically, the missing-XML dispute form prefills the host field with the parsed filename or report-text IP when exactly one can be identified.

Admins may intentionally leave the host field empty when linking a true master visual report. The UI shows a warning before saving this link because the visual will be authorized for every contact responsible for an IP in the linked XML.

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:

    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:

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 with configurable retention expiry 4. Sends email notifications

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:

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 after the configured retention window.

Best regards,
Security Team

Viewing Analytics

Insights Overview

  1. Navigate to Insights

  2. Use the built-in overview to explore: - Quick Wins: Prioritized remediation candidates - Top Vulnerable Hosts: Ranked by risk - Severity Distribution: High/Medium/Low breakdown - Trend Analysis: Historical vulnerability counts and forecasts

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

Insights current-state metrics use the latest XML scan day as the source of truth. For one institution, current totals and breakdowns come only from that institution’s latest scan date in the selected range. For All institutions, the overview combines each institution’s latest XML scan activity separately.

Warning

Avoid uploading partial CIDR scans or single-host verification scans as if they were complete institution reports. With the current naive model, an incomplete latest XML scan can make older findings disappear from Insights even when those hosts were simply not scanned.

Filtering Data

Use the Insights filters to narrow the view: - Institution: Select specific organization - Severity: Filter by High/Medium/Low - Time Range: Custom date ranges - Host: Focus on specific IP/hostname - Product: Focus on a specific OS or application - Vulnerability: Drill into a specific finding

Insights and Quick Wins

The Insights view provides an intelligent analysis of your vulnerability data, helping you prioritize remediation efforts.

Quick Wins

Quick Wins are high-impact, low-effort vulnerabilities that the system identifies as top priorities for remediation. They are scored based on:

  • Severity: Critical issues get higher priority.

  • Exposure: Findings affecting multiple hosts are prioritized.

  • Actionability: Issues with known CVEs or clear solutions are ranked higher.

For a detailed breakdown of how these are calculated, see the Insights and Quick Wins page.

FAQ

Why do vulnerability counts stay high after fixes?

Insights reflects uploaded XML scan data. If an institution has a high number of CVEs in its latest XML scan and you never upload a newer complete XML scan for that institution, VulnerabilityHub has no evidence that the findings were fixed. Rescan after remediation and upload the new XML, otherwise Insights, trends, and current totals can remain stale or misleading.

Should XML uploads always be complete scans?

Yes, for the current implementation. Treat XML uploads as complete institution snapshots. The current Insights model uses the latest XML scan day as the source of truth, so partial CIDR scans, single-host verification scans, or other smaller XML uploads can replace the current view for an institution and make non-scanned hosts appear clean.

Can visual reports be host based?

Yes. PDF and HTML visual reports may be either per-host reports or complete master visual reports. XML files are the structured source for analytics, matching, notifications, and access decisions. Visual reports are delivery artifacts and can be linked to one host in an XML or, after an explicit admin warning, to every host in the XML.

Why did a visual report not send notifications?

Unmatched or ambiguous visual reports do not send notifications. A visual report is delivered only when it is linked to exactly one XML context, or when an admin explicitly links it as a master visual for all hosts in the XML. Review pending visuals under Manage -> Disputes.

Why are filename patterns important?

Filename patterns are how recurring scans of the same network are separated from older or newer scan generations. Use stable names with a date, facility, and host suffix where appropriate, for example 2026-02-01_campus_198.51.100.5.html for a host visual and 2026-02-01_campus.xml for the master XML.

Can old reports be uploaded later?

Yes. Old XML or visual reports can be uploaded later, but their filenames still need enough context for matching. Existing matched visual reports stay pinned to their original XML and are not moved automatically when a newer rescan is uploaded.

What happens when IPs have no contact or institution mapping?

The upload is kept, but the system opens disputes for missing responsibility or institution mappings. Notifications are withheld where the responsible contact cannot be determined. Resolve these disputes before relying on delivery status.

Why can institution mapping changes take a moment to appear everywhere?

Saving an institution is immediate, but report assignment refreshes run in the background for affected scans. This keeps the UI responsive while historical scan metadata and institution disputes are updated.

Contact Person Self-Service

Contact persons can manage their own information without admin access.

Logging In

  1. Admin generates a login token:

    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:

docker-compose logs backend | grep "email"

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