From 56044c0a79e3cc3b6ba60d753d1b01136bf9d123 Mon Sep 17 00:00:00 2001 From: Florian Wilhelm Date: Mon, 1 Dec 2025 10:40:03 +0100 Subject: [PATCH] Restructure the API docs to make triage easier to use Related to https://github.com/gardenlinux/glvd/issues/156 --- src/docs/asciidoc/index.adoc | 119 +++++++++++++++++------------------ 1 file changed, 59 insertions(+), 60 deletions(-) diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index 22536a3..8a5a8c6 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -5,23 +5,59 @@ Garden Linux Authors :source-highlighter: highlightjs :toc: -== Overview - This document describes the HTTP API endpoints of the Garden Linux Vulnerability Database (GLVD). -CAUTION: This document and the API are work in progress and subject to change at any time. +Find out more about GLVD at https://security.gardenlinux.org and https://github.com/gardenlinux/glvd. -== API Endpoints +This document provides real HTTP requests and responses captured from API tests. +The data shown is based on unit tests and may differ from production data, but the structure of requests and responses remains consistent. -=== List All Garden Linux Releases +== Triage Data -Retrieve all known Garden Linux releases: +Triage is the process where the Garden Linux security team evaluates security vulnerabilities (CVEs) to determine their impact on Garden Linux releases. +Getting Triage data is one of the main features of the GLVD API. -include::{snippets}/getAllGardenLinuxVersions/curl-request.adoc[] +=== List Triages for a Garden Linux Release + +Retrieve triaged security vulnerabilities for a Garden Linux release. + +include::{snippets}/triagesGardenlinux/curl-request.adoc[] Example response: -include::{snippets}/getAllGardenLinuxVersions/http-response.adoc[] +include::{snippets}/triagesGardenlinux/http-response.adoc[] + +=== Get Triages for a CVE + +Retrieve triage information for a specific CVE by its ID. + +include::{snippets}/triagesCve/curl-request.adoc[] + +Example response: + +include::{snippets}/triagesCve/http-response.adoc[] + +=== Get Triages for a Debian Source Package + +Retrieve triage information for all CVEs related to a Debian source package. + +include::{snippets}/triagesPackage/curl-request.adoc[] + +Example response: + +include::{snippets}/triagesPackage/http-response.adoc[] + +=== List All Triages + +Retrieve a list of triages regardless of the Garden Linux release. + +include::{snippets}/triagesList/curl-request.adoc[] + +Example response: + +include::{snippets}/triagesList/http-response.adoc[] + +== CVE Data === List CVEs by Distribution @@ -57,16 +93,6 @@ Example response: include::{snippets}/getCveForPackagesPut/http-response.adoc[] -=== List Packages in a Distribution - -Retrieve a list of packages for a given distribution. - -include::{snippets}/getPackages/curl-request.adoc[] - -Example response: - -include::{snippets}/getPackages/http-response.adoc[] - === Get Vulnerabilities for a Package Retrieve vulnerabilities for a specific package. @@ -97,9 +123,10 @@ Example response: include::{snippets}/getPackagesByVulnerability/http-response.adoc[] -=== Get CVE Details with Context +=== Get CVE Details with Triage Data Retrieve information about a CVE by its ID. +If triage data is available for this CVE, it is included in the response. include::{snippets}/getCveDetailsWithContexts/curl-request.adoc[] @@ -130,62 +157,34 @@ Example response: include::{snippets}/getCveDetailsNonDebian/http-response.adoc[] -=== Get Release Notes - -Retrieve information about fixed security vulnerabilities in a new minor release. - -include::{snippets}/releaseNotes/curl-request.adoc[] - -Example response: - -include::{snippets}/releaseNotes/http-response.adoc[] - -=== Get Patch Release Notes (Legacy) - -Retrieve information about fixed security vulnerabilities in a new patch release. - -include::{snippets}/patchReleaseNotes/curl-request.adoc[] - -Example response: - -include::{snippets}/patchReleaseNotes/http-response.adoc[] - -=== List Triages for a Garden Linux Release - -Retrieve triaged security vulnerabilities for a Garden Linux release. - -include::{snippets}/triagesGardenlinux/curl-request.adoc[] - -Example response: - -include::{snippets}/triagesGardenlinux/http-response.adoc[] +== Garden Linux Release Data -=== Get Triages for a CVE +=== List All Garden Linux Releases -Retrieve triage information for a specific CVE by its ID. +Retrieve all known Garden Linux releases in GLVD. -include::{snippets}/triagesCve/curl-request.adoc[] +include::{snippets}/getAllGardenLinuxVersions/curl-request.adoc[] Example response: -include::{snippets}/triagesCve/http-response.adoc[] +include::{snippets}/getAllGardenLinuxVersions/http-response.adoc[] -=== Get Triages for a Debian Source Package +=== List Packages in a Distribution -Retrieve triage information for all CVEs related to a Debian source package. +Retrieve a list of packages for a given distribution. -include::{snippets}/triagesPackage/curl-request.adoc[] +include::{snippets}/getPackages/curl-request.adoc[] Example response: -include::{snippets}/triagesPackage/http-response.adoc[] +include::{snippets}/getPackages/http-response.adoc[] -=== List All Triages +=== Get Release Notes -Retrieve a list of triages regardless of the Garden Linux release. +Retrieve information about fixed security vulnerabilities in a minor release of Garden Linux. -include::{snippets}/triagesList/curl-request.adoc[] +include::{snippets}/releaseNotes/curl-request.adoc[] Example response: -include::{snippets}/triagesList/http-response.adoc[] +include::{snippets}/releaseNotes/http-response.adoc[]