VulnerabilityHub - A tool dedicated to process, analyze and propagate

项目说明

![codecov]()
![E2E Tests]()
!GitHub branch status
!GitHub last commit

<p align="center">
<img src="src/frontend/app/src/assets/.svg" alt=" logo" width="">
</p>

> [!CAUTION]
> is currently pre-alpha. Every 0.x release, including
> the planned v0.1.0, is a prerelease and may contain breaking changes. It is
> not recommended for production use. Stable maintenance begins with v1.0.0.

management platform with automated scanning, ML-powered predictions, and comprehensi.

<di="margin: auto; text-align: center;">
<a style="font-size: 20px;" href=" View Docs >></i></u></a>
</div>

Features

Quick Start

For a production-style installation, download the deployment archive from the
desired GitHub Release.
It contains a docker-compose.release.yml pinned to the exact released image
digests, an en example, checksums, image metadata, and upgrade
instructions. No source checkout or local image build is required.

The commands below start a de checkout:

If you want to include demo data for exploration or showcase purposes, run:

When the de LDAP server is running, the demo script also creates demo
LDAP users and stores an enabled admin LDAP connection. The directory is
reachable from containers at ldap://ldap:389 and from the host at
ldap://localhost:1389; the default bind is
cn=admin,dc=example,dc=org / admin, and seeded LDAP users use
LdapUserPass123! unless DEMO_LDAP_USER_PASSWORD is set.

First Use

Upon first usage or database refresh, no user is a in the backend. Using the frontend you will be requested to setup an initial admin account which you can later on remove if need be.

Documentation

📚 Read the Full Documentation

Key Capabilities

Management

Contact Person System

Reporting & Notifications

Insights Data Semantics

The Insights o treats the latest XML scan day as the current source of truth.
For a selected institution, current totals, breakdowns, top hosts, and quick wins
are calculated only from that institution's latest scan date in the selected time
range. For the complete o across all institutions, the same widgets combine
the latest XML scan activity for each institution indi.

Upload complete institution scans for accurate current-state reporting. Partial
CIDR scans, single-host scans, or other incomplete uploads can make
omitted findings disappear from the current Insights view because the latest scan
XML day is considered authoritative for the affected institution. A complete
clean XML scan with zero findings will therefore clear that institution from
current finding totals.

FAQ

Why do counts stay high after we fix issues?

Insights reflects uploaded XML scan data. If an institution has a high number of
CVEs in its latest XML scan and you ne a newer complete XML scan for
that institution, the platform has no e 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 now. 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 scans, or other smaller XML uploads can
replace the current view for an institution and make non-scanned hosts appear
clean.

Can reports be host based?

Yes. PDF and HTML reports may be either per-host reports or complete
master reports. XML files are the structured source for analytics,
matching, notifications, and access decisions. 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 report not send notifications?

Unmatched or ambiguous reports do not send notifications. A report
is delivered only when it is linked to exactly one XML context, or when an admin
explicitly links it as a master for all hosts in the XML. Review pending
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 and 2026-02-01_campus.xml for the master XML.

Can old reports be uploaded later?

Yes. Old XML or reports can be uploaded later, but their filenames still
need enough context for matching. Existing matched reports stay pinned to
their original XML and are not mo 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. Resol disputes before relying on delivery status.

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

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

Support

Local De

Prerequisites

Running with Frontend Hot-Reload

For a better frontend de experience with hot-reloading, follow these steps:

1. Launch Services: Run the following command from the project root to start the backend, database, and other services.

2. Stop the frontend container:

3. Na to Frontend Directory:

4. Install Dependencies:

5. Run the De:

The frontend will now be a at (or another port specified by Vite) and will automatically reload when you make changes to the source code. The backend is already configured to run on hot-reload in its containerized form.

Backend Tests

The default backend pytest run is the fast unit suite. It excludes tests marked db, so it does not need Docker or a li:

DB-backed backend integration tests run separately against MariaDB. The runner starts a fresh Docker Compose database, executes src/database/.sql, runs only tests marked db, and removes the test stack afterwards:

Set BACKEND_E2E_SKIP_CLEANUP=1 to keep the database container and after a run for debugging.

End-to-End Tests

The end-to-end smoke suite starts the backend stack in Docker dev mode, launches the Vite frontend, and a broader admin flow: initial admin bootstrap, login success and failure handling, profile updates, password rotation, institution and contact-person management, XML upload, sent-report notification resend, retention reset, authorized report pickup, responsibility disputes, unauthorized access rejection, and cleanup.

Run it locally with:

The fresh-stack runner explicitly uses EN, independent of your local .env. To bootstrap, profile updates, and password rotation with production CSRF protection enabled:

CI runs both the de suite and production auth checks through bash scripts/e2e/run-with-retry.sh. A failed run gets one retry with a freshly reset Docker stack; two failed attempts fail the pipeline. Local runs remain single-attempt unless you use this wrapper.

To watch the browser while the suite runs, use:

If you already started the backend stack yourself, you can run only the browser suite with:

test:e2e:local is the full fresh-stack entrypoint. test:e2e:local:headed does the same reset, but shows the browser live. test:e2e and test:e2e:headed assume the de are already running and that the e2e database has already been reset.

If you run only test:e2e against a manually started stack, the browser suite also expects MailHog to be reachable for email-link assertions. By default it checks , or you can o that with MAILHOG_UI_PORT / E2E_MAILHOG_PORT.

项目信息

开发语言：Python

Star 数：10

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A tool dedicated to process, analyze and propagate arbitrary vulnerability scanner reports!展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。