https://github.com/greenbone/greenbone-scap-api
REST API build on top of greenbone-scap
https://github.com/greenbone/greenbone-scap-api
api cpe cve fastapi greenbone nist nvd openvas python rest scap vulnerabilities
Last synced: 6 months ago
JSON representation
REST API build on top of greenbone-scap
- Host: GitHub
- URL: https://github.com/greenbone/greenbone-scap-api
- Owner: greenbone
- License: agpl-3.0
- Created: 2024-03-20T15:54:24.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-07T06:20:21.000Z (6 months ago)
- Last Synced: 2025-04-07T07:26:35.149Z (6 months ago)
- Topics: api, cpe, cve, fastapi, greenbone, nist, nvd, openvas, python, rest, scap, vulnerabilities
- Language: Python
- Homepage:
- Size: 976 KB
- Stars: 0
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# greenbone-scap-api
[](https://github.com/greenbone/greenbone-scap-api/releases)
[](https://pypi.org/project/greenbone-scap-api/)
A REST API on top of [greenbone-scap](https://github.com/greenbone/greenbone-scap)
based on [FastAPI](https://fastapi.tiangolo.com/) to mirror the [NIST NVD CVE API].
It provides a very similar CVE API compared to [NVD NIST](https://nvd.nist.gov/developers/vulnerabilities)
at [https://services.nvd.nist.gov/rest/json/cves/2.0][NIST NVD CVE API].
## Table of Contents
- [Requirements](#requirements)
- [Install using pipx](#install-using-pipx)
- [Install using pip](#install-using-pip)
- [Usage](#usage)
- [Settings](#settings)
- [Docker Compose](#docker-compose)
- [Development](#development)
- [Maintainer](#maintainer)
- [License](#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)][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](https://peps.python.org/pep-0668).
> Please use the [installation via pipx](#install-using-pipx) instead.
You can install the latest stable release of **greenbone-scap-api** from the
[Python Package Index (pypi)][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](#settings).
Internally the `greenbone-scap-api` script uses [uvicorn](https://www.uvicorn.org/)
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](https://www.uvicorn.org/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](https://github.com/swagger-api/swagger-ui)
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](https://docs.docker.com/compose/)
file. [The compose file](./docker/compose.yml) extends the compose file of
[greenbone-scap](https://github.com/greenbone/greenbone-scap/blob/main/docker/compose.yml).
Please take a look at the [README of greenbone-scap](https://github.com/greenbone/greenbone-scap?tab=readme-ov-file#docker-compose)
for the initial setup of the containers.
For a quick setup the following commands can be used:
```sh
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](https://github.com/swagger-api/swagger-ui)
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][Greenbone]
## License
Copyright (C) 2024 [Greenbone AG][Greenbone]
Licensed under the [GNU Affero General Public License v3.0 or later](LICENSE).
[Greenbone]: https://www.greenbone.net/
[poetry]: https://python-poetry.org/
[pip]: https://pip.pypa.io/
[pipx]: https://pypa.github.io/pipx/
[autohooks]: https://github.com/greenbone/autohooks
[pypi]: https://pypi.org
[NIST NVD CVE API]: https://services.nvd.nist.gov/rest/json/cves/2.0