diff --git a/src/assets/advisory-affected-packages.png b/src/assets/advisory-affected-packages.png new file mode 100644 index 00000000..0991dc20 Binary files /dev/null and b/src/assets/advisory-affected-packages.png differ diff --git a/src/assets/advisory-cvss-calculator.png b/src/assets/advisory-cvss-calculator.png new file mode 100644 index 00000000..8602bd3c Binary files /dev/null and b/src/assets/advisory-cvss-calculator.png differ diff --git a/src/assets/advisory-detail-draft.png b/src/assets/advisory-detail-draft.png new file mode 100644 index 00000000..903be508 Binary files /dev/null and b/src/assets/advisory-detail-draft.png differ diff --git a/src/assets/advisory-dialog-metadata.png b/src/assets/advisory-dialog-metadata.png new file mode 100644 index 00000000..5b5e99e2 Binary files /dev/null and b/src/assets/advisory-dialog-metadata.png differ diff --git a/src/assets/advisory-list-page.png b/src/assets/advisory-list-page.png new file mode 100644 index 00000000..cfd04b85 Binary files /dev/null and b/src/assets/advisory-list-page.png differ diff --git a/src/assets/advisory-nav-menu.png b/src/assets/advisory-nav-menu.png new file mode 100644 index 00000000..2178c20b Binary files /dev/null and b/src/assets/advisory-nav-menu.png differ diff --git a/src/pages/how-to-guides/vulnerability-management/_meta.ts b/src/pages/how-to-guides/vulnerability-management/_meta.ts index eac5abd0..26c52ff6 100644 --- a/src/pages/how-to-guides/vulnerability-management/_meta.ts +++ b/src/pages/how-to-guides/vulnerability-management/_meta.ts @@ -1,4 +1,7 @@ export default { + 'create-security-advisories': { + title: 'Create Security Advisories', + }, 'csaf-common-security-advisory-framework': { title: 'CSAF - Common Security Advisory Framework', }, diff --git a/src/pages/how-to-guides/vulnerability-management/create-security-advisories.mdx b/src/pages/how-to-guides/vulnerability-management/create-security-advisories.mdx new file mode 100644 index 00000000..a5e8c97e --- /dev/null +++ b/src/pages/how-to-guides/vulnerability-management/create-security-advisories.mdx @@ -0,0 +1,161 @@ +--- +title: Create a Security Advisory in DevGuard +description: "Author, publish and withdraw a security advisory in DevGuard — write your own vulnerability reports, score them with CVSS and share them as CSAF documents." +seo: + robots: index,follow + og: + image: /og-image.png + type: article + schema: + type: TechArticle + keyword_primary: security advisory +lang: en-US +ignoreChecks: null +--- + +import { Callout } from '@document-writing-tools/kernux-theme' + +# Create and Publish a Security Advisory + +A **security advisory** in DevGuard lets you author, score and publish your *own* vulnerability reports for a repository. Unlike the VEX documents DevGuard generates automatically from scanner findings, a security advisory is written by a human — it is the vendor statement you issue when *your* software is affected by a vulnerability and you want to communicate it to your users in a standardized way. + +Every advisory you publish is served through DevGuard's [CSAF](/how-to-guides/vulnerability-management/csaf-common-security-advisory-framework) provider tree, so downstream consumers receive it in the same machine-readable format as any other advisory in the ecosystem. + +## Prerequisites + +Before you create a security advisory, make sure you have: + +- **A repository (asset) with at least one ref**: Advisories are scoped to a specific repository. The menu entry only appears once a ref exists. +- **Admin permissions**: Only organization or repository admins can create, edit, publish, withdraw or delete an advisory. Everyone with read access can view published advisories. +- **The vulnerability details at hand**: A title and description, the affected package(s) with their affected and patched version ranges, and — ideally — a CVSS vector for scoring. +- **Public vulnerability data enabled** (for publishing): To distribute advisories through the CSAF feed, the repository must have vulnerability sharing turned on. See [CSAF in DevGuard](/how-to-guides/vulnerability-management/csaf-common-security-advisory-framework#enabling-csaf-reports). + +## When to Use a Security Advisory + +DevGuard produces two kinds of vulnerability statements. Understanding the difference helps you pick the right tool: + +| | Auto-generated VEX | Security advisory | +|---|---|---| +| **Source** | Derived from detected dependency vulnerabilities | Manually authored by you | +| **Answers** | "Am I affected by *someone else's* CVE?" | "*My* product has a vulnerability — here it is" | +| **Content** | Product status per detected CVE | Title, description, CVSS, affected packages | +| **Identifier** | The upstream CVE ID | A DevGuard ID `DGSA--` | +| **Published as** | `csaf_vex` document | `csaf_security_advisory` document | + +Both are published side by side through the same CSAF endpoints, giving consumers one unified feed that covers machine-detected CVEs *and* your human-authored advisories. + + + Use a security advisory when you are the maintainer/vendor of the affected component and need to disclose a vulnerability in *your* release. Use the automatic VEX flow to communicate how *upstream* CVEs affect your product. + + +## The Security Advisory Lifecycle + +A security advisory moves through three visibility states. It always starts as a private **draft** that you can freely edit, and once it is correct you publish it. A published advisory is public and immutable — if it later needs to be revoked you withdraw it, which keeps it visible but marks it as no longer valid. + +```mermaid +graph LR + A[Draft
private & editable] -->|Publish Draft| B[Public
immutable & shared via CSAF] + A -->|Delete Draft| D[Deleted] + B -->|Withdraw Advisory| C[Withdrawn
public but marked invalid] + + style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000 + style B fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000 + style C fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#000 + style D fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000 +``` + +| State | Meaning | Available actions | +|-------|---------|-------------------| +| **Draft** | Private, only visible inside DevGuard, fully editable | Change, Publish, Delete | +| **Public** | Published to the CSAF feed, no longer editable | Withdraw | +| **Withdrawn** | Stays public but is flagged as revoked and locked | — | + +## Where to Find Security Advisories + +Navigate to your repository and open the **Security Advisory** entry in the asset side menu (shield icon). It sits alongside the risk views (Dependency Risks, Code Risks, License Risks) and the Artifacts view. + +![DevGuard asset side menu with the Security Advisory entry highlighted](../../../assets/advisory-nav-menu.png) + +This opens the advisory list for the current repository and ref. The list is organized into **Draft**, **Public** and **Withdrawn** tabs, and — as an admin — you get a **Create Security Advisory** button in the top-right corner. Each row shows the advisory title and its CVSS severity. + +![Security advisory list page showing the Draft, Public and Withdrawn tabs and the Create button](../../../assets/advisory-list-page.png) + +## Create a Security Advisory + +Click **Create Security Advisory** to open the creation dialog. The dialog guides you through three steps. + +### Step 1 — Describe the vulnerability + +On the first step you enter the core metadata of the advisory: + +- **Title** *(required)* — a concise summary of the issue. +- **Description** *(required)* — the full write-up in Markdown. A `### Summary` / `### Details` structure works well. +- **Severity** *(required)* — one of *Critical, High, Medium, Low, None*. This field is filled automatically and locked when you provide a CVSS vector string. +- **Vector string** — the CVSS vector (for example `CVSS:4.0/AV:N/AC:L/...`). If you don't know it by heart, use the built-in calculator in the next step. + +![Security advisory creation dialog with title, description, severity and vector fields](../../../assets/advisory-dialog-metadata.png) + +### Step 2 — Calculate the CVSS vector (optional) + +If you need help scoring the vulnerability, open the **Calculate vector string** helper. You can switch between **CVSS 3.1** and **CVSS 4.0**, pick a value for each metric, and DevGuard shows the resulting base score and severity live. Applying the calculation writes the vector back into the form and derives the severity automatically. + +![CVSS calculator inside the advisory dialog with a version toggle and live base score](../../../assets/advisory-cvss-calculator.png) + +### Step 3 — Add the affected packages + +Finally, list the packages affected by the advisory (up to ten). For each package you provide: + +- **Ecosystem** — for example `go`, `npm` or `pypi`. +- **Package name** — the package identifier. +- **Affected versions** — the version where the vulnerability was introduced. +- **Patched version** — the version that fixes it. + +DevGuard turns these into standardized version ranges (`vers:` notation) in the published document and adds a *vendor fix* remediation pointing at the patched version. + +![Affected packages step of the advisory dialog with ecosystem, package name and version range fields](../../../assets/advisory-affected-packages.png) + +Click **Create Draft Advisory** to save. The new advisory appears under the **Draft** tab. + +## Manage, Publish and Withdraw + +Open an advisory from the list to reach its detail page. It shows the rendered description, the affected-package table (with affected and patched version columns) and a sidebar with the severity, the CVSS vector and the individual base metrics. + +The available actions depend on the current state. + +### Draft actions + +A draft shows a **Draft** badge and three admin actions: + +- **Change Draft** — reopens the dialog prefilled so you can edit any field. +- **Publish Draft** — makes the advisory public. After confirmation it is served through the CSAF feed and can no longer be edited. +- **Delete Draft** — permanently removes the draft. + +![Security advisory detail page for a draft, showing the Change, Publish and Delete actions](../../../assets/advisory-detail-draft.png) + + + Publishing is irreversible in the sense that a public advisory can no longer be edited — you can only **withdraw** it. Double-check the title, description, severity and affected packages before you confirm. + + +Every state change asks for confirmation so you don't publish or withdraw an advisory by accident. + +### Published and withdrawn advisories + +A published advisory carries a green **Published** badge and offers a single action, **Withdraw Advisory**. Withdrawing keeps the advisory publicly reachable — so anyone who already referenced it still finds it — but marks it as withdrawn and locks it against further changes. + +## How the Advisory Is Published + +When you publish an advisory, DevGuard exposes it through the organization's CSAF provider tree — the same one that carries the automatically generated VEX documents. Concretely: + +- The advisory receives a DevGuard identifier of the form **`DGSA--`** (DevGuard Security Advisory). +- It is rendered on the fly as a canonical **`csaf_security_advisory`** JSON document at TLP:WHITE, with a product tree built from your affected packages, `known_affected` product statuses and a `vendor_fix` remediation for the patched version. +- It is listed next to the CVE-based documents in the CSAF `index.txt`, the `changes.csv` and the per-year index — so consumers discover it automatically. +- Like any CSAF document it can be fetched as plain JSON or with an OpenPGP signature (`.asc`) and checksums (`.sha256` / `.sha512`). + +For the full endpoint structure, aggregator and provider-metadata details, see [CSAF in DevGuard](/how-to-guides/vulnerability-management/csaf-common-security-advisory-framework#accessing-csaf-data). + +## Related Documentation + +- [CSAF in DevGuard](/how-to-guides/vulnerability-management/csaf-common-security-advisory-framework) — how advisories are distributed and consumed +- [Sync External Upstream Data](/how-to-guides/vulnerability-management/sync-external-data) — ingest VEX and advisories from other providers +- [Track Fix Progress](/how-to-guides/vulnerability-management/track-fix-progress) — monitor remediation of detected vulnerabilities +- [Customize Risk Scores](/how-to-guides/vulnerability-management/customize-risk-scores) — adjust risk based on your context