From 73d0423d613edd180580d093989a7ae094842f4c Mon Sep 17 00:00:00 2001 From: Nicolas Crocfer Date: Thu, 5 Feb 2026 12:07:28 +0100 Subject: [PATCH] feat: improve the concepts docs Signed-off-by: Nicolas Crocfer --- docs/concepts/core.md | 103 +++++++++++++++++++++++++++ docs/{ => concepts}/kb.md | 10 +-- docs/{ => concepts}/notifications.md | 14 ++-- docs/deployment.md | 8 +-- docs/guides/smtp_configuration.md | 2 +- docs/organizations_projects.md | 52 -------------- mkdocs.yml | 6 +- 7 files changed, 123 insertions(+), 72 deletions(-) create mode 100644 docs/concepts/core.md rename docs/{ => concepts}/kb.md (95%) rename docs/{ => concepts}/notifications.md (88%) delete mode 100644 docs/organizations_projects.md diff --git a/docs/concepts/core.md b/docs/concepts/core.md new file mode 100644 index 0000000..0744338 --- /dev/null +++ b/docs/concepts/core.md @@ -0,0 +1,103 @@ +# Fundamentals & Core Concepts + +## Organizations + +In OpenCVE, an **Organization** is the highest-level object. It represents your company or your team in OpenCVE. All resources — projects, users, subscriptions, notifications, and API usage — are managed at the organization level. + +Each user can belong to one or more organizations, with one of the following two roles: + +- **Member**, who can manage subscriptions (vendors and products). +- **Owner**, who has full control over the organization, including managing memberships. + +Organizations allow multiple users to collaborate while sharing quotas such as subscriptions and API calls. + +![OpenCVE Organizations](../images/opencve-organizations.png){.center style="width:90%"} + +## Projects + +Projects are the main building blocks of an organization in OpenCVE. Each organization can contain one or more Projects. + +A project allows you to: + +- Track the technologies you want to monitor for vulnerabilities, +- Configure notification channels to receive alerts, +- Generate reports and summaries of CVE activity, +- Assign users to CVEs and manage their status (e.g., analysis, risk acceptance). + +Projects help organizations structure their subscriptions in a way that matches their teams and workflows. Common use cases include: + +- **MSSPs** creating a project for each client (e.g., client1, client2, client3), +- **IT companies** creating projects for different technical teams (e.g., team-X, team-Y, team-Z), +- **Smaller organizations** splitting projects by role, for example one project for developers and another for sysadmins. + +![OpenCVE Projects](../images/opencve-projects.png){.center style="width:70%"} + +Each project operates independently, with its own dashboard to track vulnerabilities in its subscriptions. By splitting monitoring into projects, you can scope CVE exposure by product, team, customer, or environment, keeping a clear, focused view of what matters most. + +## Notifications + +Notifications are alerts triggered whenever a CVE appears or an existing CVE is updated, **and the CVE affects one of your tracked technologies (subscriptions)**. They ensure you stay informed about relevant vulnerabilities. + +A project can have one or more [notification channels](notifications.md), which define **how** notifications are delivered. + +OpenCVE currently supports: + +- `email` – send updates to configured addresses, +- `slack` – post updates to Slack channels, +- `webhook` – send updates via HTTP POST to external systems. + +Users can combine channels to fit their workflows. For example: + +- All updates can be sent to an API using a webhook, +- Critical CVEs (CVSS >= 9) can trigger an email to a mailing list. + +![OpenCVE Notification](../images/opencve-notification.png){.center style="width:90%"} + +!!! note + Additional channels, such as `Microsoft Teams`, are planned for future releases. + +## Reports + +Each project includes a **Reports** tab, which provides a daily summary of all activity related to the project's subscriptions (the technologies you track). + +![OpenCVE Report](../images/opencve-report.png){.center style="width:90%"} + +Daily reports give users a complete overview of what happened with their tracked technologies, helping teams stay informed and maintain visibility over time. + +!!! info + + Reports are different from notifications: + + - **Notifications** alert you in real time when a CVE matches your filters, + - **Daily reports** include all CVE updates for your subscriptions, providing a broader view of activity. + +## AI-Powered Report Summary + +In addition to raw reports, OpenCVE generates an **AI-powered summary** for each project. This summary highlights: + +- the most critical CVEs, +- priority areas, +- recommended actions. + +It allows users to quickly understand where to focus, without manually reviewing every vulnerability. + +![Report Summary](../images/guides/report_summaries/report-summary.png){.center style="width:100%"} + +## Users + +Users are members of your organization who can collaborate within OpenCVE. + +Each user can: + +- **Access** projects to view CVEs, reports, and summaries relevant to their subscriptions. +- **Collaborate** on vulnerability analysis, marking CVEs as reviewed, or sharing insights with the team. +- **Be assigned** responsibilities such as analysis, remediation tracking, or risk acceptance. + + +By assigning roles and responsibilities within projects, OpenCVE ensures **clear ownership** of vulnerabilities and **efficient collaboration** between security and engineering teams. + +## Subscriptions + +Subscriptions define the **technologies you monitor** for vulnerabilities, such as vendors, products, or software stacks (e.g., Fortinet, Cisco, WordPress, Terraform). + +Subscriptions allow teams to **prioritize** critical technologies, organize monitoring efficiently, and ensure consistent vulnerability tracking across all projects. diff --git a/docs/kb.md b/docs/concepts/kb.md similarity index 95% rename from docs/kb.md rename to docs/concepts/kb.md index e7ecffc..ced15c2 100644 --- a/docs/kb.md +++ b/docs/concepts/kb.md @@ -6,13 +6,13 @@ The Knowledge Base (KB) is at the core of how OpenCVE operates. It serves as a c The KB is hosted as a public GitHub repository at [https://github.com/opencve/opencve-kb](https://github.com/opencve/opencve-kb), so everyone can access it freely. -![KB Commit](images/kb/commit.png){.center style="width:75%"} +![KB Commit](../images/kb/commit.png){.center style="width:75%"} It is populated automatically by scripts that are not part of the public OpenCVE codebase. These scripts continuously pull data from the various providers, process it, and store the aggregated result in the KB. Then all OpenCVE instances fetch this KB to populate their own database. In the end, when you browse the web application, you browse the KB: -![CVE-2024-45409](images/kb/cve-2024-45409.png){.center style="width:75%"} +![CVE-2024-45409](../images/kb/cve-2024-45409.png){.center style="width:75%"} ## Objective @@ -64,15 +64,15 @@ In some cases the CVE data may differ from provider to provider. For example, this is the case for the weaknesses of the [CVE-2023-5176](https://github.com/opencve/opencve-kb/blob/main/2023/CVE-2023-5176.json) CVE. The NVD assigned it the `CWE-787` weakness ([source](https://nvd.nist.gov/vuln/detail/CVE-2023-5176)): -![NVD CVE-2023-5176 Weakness](images/kb/nvd_CVE-2023-5176_weakness.png){.center style="width:650px"} +![NVD CVE-2023-5176 Weakness](../images/kb/nvd_CVE-2023-5176_weakness.png){.center style="width:650px"} While RedHat assigned the `CWE-120` weakness ([source](https://access.redhat.com/security/cve/CVE-2023-5176)): -![Redhat CVE-2023-5176 Weakness](images/kb/redhat_CVE-2023-5176_weakness.png){.center style="width:550px"} +![Redhat CVE-2023-5176 Weakness](../images/kb/redhat_CVE-2023-5176_weakness.png){.center style="width:550px"} In this case OpenCVE merged the weaknesses information in the KB ([source](https://github.com/opencve/opencve-kb/blob/a2fac4fab1dba59e2c44abfb19ca43d7fd63c595/2023/CVE-2023-5176.json#L190-L199)): -![OpenCVE CVE-2023-5176 Weaknesses](images/kb/opencve_CVE-2023-5176_weaknesses.png){.center style="width:250px"} +![OpenCVE CVE-2023-5176 Weaknesses](../images/kb/opencve_CVE-2023-5176_weaknesses.png){.center style="width:250px"} This approach allows OpenCVE to present users with a single, unified value for critical fields, while still benefiting from the diversity of its data sources. diff --git a/docs/notifications.md b/docs/concepts/notifications.md similarity index 88% rename from docs/notifications.md rename to docs/concepts/notifications.md index 5349432..29435ff 100644 --- a/docs/notifications.md +++ b/docs/concepts/notifications.md @@ -10,7 +10,7 @@ OpenCVE then checks each project that has subscribed to these vendors and produc A project can have zero or multiple notifications. -![OpenCVE Notifications List](images/opencve-notifications-list.png){.center style="width:100%"} +![OpenCVE Notifications List](../images/opencve-notifications-list.png){.center style="width:100%"} ## Notification Filters @@ -22,7 +22,7 @@ The user can also decide to be notified based on the type of modification: wheth This allows users to receive notifications only for the changes that matter to them. Furthermore, they can configure one notification to send high-severity CVEs to a channel that is closely monitored, while sending all other notifications to a less-watched channel. -![OpenCVE Notification Filters](images/opencve-notification.png){.center style="width:100%"} +![OpenCVE Notification Filters](../images/opencve-notification.png){.center style="width:100%"} ## Notification Types @@ -35,11 +35,11 @@ This allows users to receive notifications only for the changes that matter to t This is the simplest type of notification. When a change is detected, an email is sent to the address configured in the settings. -![OpenCVE Email Notification](images/opencve-email-notification-form.png){.center style="width:70%"} +![OpenCVE Email Notification](../images/opencve-email-notification-form.png){.center style="width:70%"} Here is an example: -![OpenCVE Email Notification](images/opencve-email-notification.png){.center style="width:100%"} +![OpenCVE Email Notification](../images/opencve-email-notification.png){.center style="width:100%"} ### Slack @@ -54,11 +54,11 @@ https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX Simply provide this URL in the notification configuration to start receiving CVE updates in your chosen Slack channel: -![OpenCVE Slack Notification](images/opencve-slack-notification-form.png){.center style="width:70%"} +![OpenCVE Slack Notification](../images/opencve-slack-notification-form.png){.center style="width:70%"} Here is an example: -![OpenCVE Slack Notification](images/opencve-slack-notification.png){.center style="width:100%"} +![OpenCVE Slack Notification](../images/opencve-slack-notification.png){.center style="width:100%"} ### Webhook @@ -66,7 +66,7 @@ Webhook notifications allow users to interface with their own information system When a change is detected, a POST request is sent to the URL defined in the configuration. The user can also add custom headers if required by their system. -![OpenCVE Webhook Notification](images/opencve-webhook-notification.png){.center style="width:75%"} +![OpenCVE Webhook Notification](../images/opencve-webhook-notification.png){.center style="width:75%"}
Click to show a payload example diff --git a/docs/deployment.md b/docs/deployment.md index 0b375a1..23535f4 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -67,7 +67,7 @@ It will proceed with all the installation steps automatically. When all the step - on port 8080 for OpenCVE Airflow scheduler You can login with the username "xxx" and password "xxx". - 👋 Installation complete! Thank you for choosing OpenCVE! + 👋 Installation complete! Thank you for choosing OpenCVE! ``` @@ -184,7 +184,7 @@ Updating files: 100% (61734/61734), done. ### import-opencve-kb -This command imports the [OpenCVE KB](kb.md) in your database: +This command imports the [OpenCVE KB](concepts/kb.md) in your database: ``` ./install.sh import-opencve-kb @@ -258,7 +258,7 @@ This file exposes important settings used by the OpenCVE webserver: - `OPENCVE_DATABASE_URL`: the URI of the database. You need to update it if you have changed some of the postgresql parameters in the docker compose env file. The postgresql connection parameters need to be the same in both web and docker compose `.env` files. - `OPENCVE_SECRET_KEY`: this variable has to be replaced with a new secret when the web server is up the first time - `OPENCVE_*_REPO_PATH`: the paths of the repositories (KB, Mitre, NVD...) -- `OPENCVE_V1_DATABASE`: the URI of an OpenCVE v1 instance (used for [data migration](../guides/migrate_opencve_v1)) +- `OPENCVE_V1_DATABASE`: the URI of an OpenCVE v1 instance (used for [data migration](guides/migrate_opencve_v1.md)) **web/opencve/conf/settings.py** @@ -274,7 +274,7 @@ This file is used to configure the Airflow scheduler of OpenCVE. You can check the list of Airflow configurations [here](https://airflow.apache.org/docs/apache-airflow/stable/configurations-ref.html) to customize your Airflow instance. !!! info - You can refer to this [dedicated guide](../guides/smtp_configuration) to configure SMTP settings and enable email sending. + You can refer to this [dedicated guide](guides/smtp_configuration.md) to configure SMTP settings and enable email sending. ## Upgrade diff --git a/docs/guides/smtp_configuration.md b/docs/guides/smtp_configuration.md index 3b43c31..a07ae53 100644 --- a/docs/guides/smtp_configuration.md +++ b/docs/guides/smtp_configuration.md @@ -99,7 +99,7 @@ Repeat for confirmation: User "admin" created with role "Admin" ``` -Then access the Airflow UI in your browser (default port: **8080**, as per the [Deployment & Setup](../../deployment) guide) and trigger the `check_smtp` DAG: +Then access the Airflow UI in your browser (default port: **8080**, as per the [Deployment & Setup](../deployment.md) guide) and trigger the `check_smtp` DAG: ![Trigger check-smtp DAG](../images/guides/smtp_configuration/trigger-check-smtp-dag.png){.center style="width:100%"} diff --git a/docs/organizations_projects.md b/docs/organizations_projects.md deleted file mode 100644 index 0e70a57..0000000 --- a/docs/organizations_projects.md +++ /dev/null @@ -1,52 +0,0 @@ -# Organizations & Projects - -## Organizations - -In OpenCVE, an **Organization** is the highest-level object. Without an organization, a user cannot subscribe to products or vendors, nor receive notifications when a CVE appears or is updated. - -Each user can belong to one or more organizations, with one of the following two roles: - -- **Member**, who can manage subscriptions (vendors and products). -- **Owner**, who has full control over the organization, including managing memberships. - -![OpenCVE Organizations](images/opencve-organizations.png){.center style="width:90%"} - -## Projects - -An organization can have one or more **Projects**. - -Projects allow organizations to organize their subscriptions and [notifications](notifications.md) in a way that suits their structure and needs. Here are a few common use cases for projects: - -- An **MSSP (Managed Security Service Provider)** might create a project for each of their clients (e.g., client1, client2, client3). -- An **IT Companies** might create projects based on technical teams (e.g., team-X, team-Y, team-Z). -- A **smaller organization** could split projects by roles within the company, for instance, having one project for developers and another for sysadmins. - -![OpenCVE Projects](images/opencve-projects.png){.center style="width:70%"} - -Each project operates independently and has its own dashboard to track the evolution of vulnerabilities in its subscriptions. - -### Notifications - -A project can also have one or more **notifications**. Whenever a CVE appears, or when an existing CVE is updated, and if this CVE is associated to one of your subscription, a notification is sent through the designated channel. - -![OpenCVE Notification](images/opencve-notification.png){.center style="width:90%"} - -This flexibility allows users to be alerted through different channels (e.g., email, webhook) based on custom filters, for instance: - -- all the changes are sent to an API using the webhook notification, -- and a mail is also sent on a mailing-list for all the CVEs with a CVSS score >= 9. - -!!! note - OpenCVE supports for now 2 types of notifications: `email` and `webhook`. Others are planned for future releases, such as `slack` or `opsgenie` ones. - -### Reports - -Projects include a **Report** tab, which provides a daily summary of the activity related to a project's subscriptions: - -![OpenCVE Report](images/opencve-report.png){.center style="width:90%"} - -This feature helps users stay informed about what happened with their subscriptions on a day-to-day basis. - -!!! info - Reports differ from notifications: notifications alert you in real-time when a CVE is updated, but only if it matches your filters. - In contrast, daily reports include all CVE changes related to any product or vendor in your subscriptions, providing a broader overview of activity. diff --git a/mkdocs.yml b/mkdocs.yml index 3f51f0f..db52f81 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,9 +23,9 @@ nav: - Home: 'index.md' - Deployment & Setup: 'deployment.md' - Concepts: - - Organizations & Projects: 'organizations_projects.md' - - Knowledge Base (KB): 'kb.md' - - Notifications: 'notifications.md' + - Core Concepts: 'concepts/core.md' + - Knowledge Base (KB): 'concepts/kb.md' + - Notifications: 'concepts/notifications.md' - Guides: - Advanced Search: 'guides/advanced_search.md' - Custom Dashboards: 'guides/custom_dashboards.md'