greenbone-scap-api 25.3.1

REST API on top of greenbone-scap

greenbone-scap-api

A REST API on top of greenbone-scap based on FastAPI to mirror the NIST NVD CVE API.

It provides a very similar CVE API compared to NVD NIST at https://services.nvd.nist.gov/rest/json/cves/2.0.

Table of Contents

• Requirements
  • Install using pipx
  • Install using pip
• Usage
• Settings
• Docker Compose
• Development
• Maintainer
• License

Requirements

Python 3.11 and later is supported.

Install using pipx

You can install the latest stable release of greenbone-scap-api from the Python Package Index (pypi) using pipx

python3 -m pipx install greenbone-scap-api

Install using pip

[!NOTE] The pip install command does no longer work out-of-the-box in newer distributions like Ubuntu 23.04 because of PEP 668. Please use the installation via pipx instead.

You can install the latest stable release of greenbone-scap-api from the Python Package Index (pypi) using pip

python3 -m pip install --user greenbone-scap-api

Usage

A simple web server to serve the API can be started by running greenbone-scap-api. The settings of the web server can be controlled via environment variables.

Internally the greenbone-scap-api script uses uvicorn

It's also possible to serve the API with uvicorn directly

uvicorn greenbone.scap.api.app:app --reload

Using uvicorn directly allows for more flexibility regarding the settings for serving the API.

After starting the web server the CVE API is available at http://127.0.0.1:8000/cves (by default). Interactive API docs are served at http://127.0.0.1:8000/docs.

Settings

greenbone-scap-api can be configured via the following environment variables

Name	Description	Default
DATABASE_USER	Username for the connection to the PostgreSQL database.	scap
DATABASE_PASSWORD	Username for the connection to the PostgreSQL database.
DATABASE_NAME	Name of the PostgreSQL database.	scap
DATABASE_HOST	Host where the PostgreSQL database is running. IP or DNS name.	127.0.0.1
DATABASE_PORT	Port on which the PostgreSQL database is listening.	5432
ECHO_SQL	Log SQL statements. true or 1 to enable.	disabled
API_HOST	IP address or DNS name to listen on	127.0.0.1
API_PORT	Port to listen on	8000
LOG_LEVEL	Log level for server output. Options are critical, error, warning, info, debug and trace.	info

Docker Compose

The API is easiest to use via the provided docker compose file. The compose file extends the compose file of greenbone-scap. Please take a look at the README of greenbone-scap for the initial setup of the containers.

For a quick setup the following commands can be used:

cd docker
echo "DATABASE_PASSWORD=my-super-safe-password" > .env
docker compose up

After starting the containers the CVE API is available at http://127.0.0.1:8000/cves (by default). Interactive API docs are served at http://127.0.0.1:8000/docs.

[!NOTE] On the initial startup all CVE will be downloaded from the NIST NVD CVE API Downloading the data may take several hours and due to unreliable servers at NIST may even fail. After a successful full download of the data at NIST, only the changed and new CVEs will be downloaded. To trigger a download docker compose up cve can be used.

Development

greenbone-scap-api uses poetry for its own dependency management and build process.

First install poetry via pipx

python3 -m pipx install poetry

Afterwards run

poetry install

in the checkout directory of greenbone-scap-api (the directory containing the pyproject.toml file) to install all dependencies including the packages only required for development.

Afterwards activate the git hooks for auto-formatting and linting via autohooks.

poetry run autohooks activate

Validate the activated git hooks by running

poetry run autohooks check

Maintainer

This project is maintained by Greenbone AG

License

Copyright (C) 2024 Greenbone AG

Licensed under the GNU Affero General Public License v3.0 or later.