Name | greenbone-scap-api JSON |
Version |
0.0.1
JSON |
| download |
home_page | None |
Summary | REST API on top of greenbone-scap |
upload_time | 2024-03-21 10:39:50 |
maintainer | None |
docs_url | None |
author | Greenbone |
requires_python | <4.0,>=3.11 |
license | AGPL-3.0-or-later |
keywords |
|
VCS |
|
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
![Greenbone Logo](https://www.greenbone.net/wp-content/uploads/gb_new-logo_horizontal_rgb_small.png)
# greenbone-scap-api <!-- omit in toc -->
[![GitHub releases](https://img.shields.io/github/release/greenbone/greenbone-scap-api.svg)](https://github.com/greenbone/greenbone-scap-api/releases)
[![PyPI release](https://img.shields.io/pypi/v/greenbone-scap-api.svg)](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/).
It provides a similar CVE API to [NVD NIST](https://nvd.nist.gov/developers/vulnerabilities)
at https://services.nvd.nist.gov/rest/json/cves/2.0.
## Table of Contents <!-- omit in toc -->
- [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 API](https://services.nvd.nist.gov/rest/json/cves/2.0).
> 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
Raw data
{
"_id": null,
"home_page": null,
"name": "greenbone-scap-api",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Greenbone",
"author_email": "info@greenbone.net",
"download_url": "https://files.pythonhosted.org/packages/e5/2d/dade657f826a9dc606694994271869480e6b8641dd60ee2692b6105ca90f/greenbone_scap_api-0.0.1.tar.gz",
"platform": null,
"description": "![Greenbone Logo](https://www.greenbone.net/wp-content/uploads/gb_new-logo_horizontal_rgb_small.png)\n\n# greenbone-scap-api <!-- omit in toc -->\n\n[![GitHub releases](https://img.shields.io/github/release/greenbone/greenbone-scap-api.svg)](https://github.com/greenbone/greenbone-scap-api/releases)\n[![PyPI release](https://img.shields.io/pypi/v/greenbone-scap-api.svg)](https://pypi.org/project/greenbone-scap-api/)\n\nA REST API on top of [greenbone-scap](https://github.com/greenbone/greenbone-scap)\nbased on [FastAPI](https://fastapi.tiangolo.com/).\n\nIt provides a similar CVE API to [NVD NIST](https://nvd.nist.gov/developers/vulnerabilities)\nat https://services.nvd.nist.gov/rest/json/cves/2.0.\n\n## Table of Contents <!-- omit in toc -->\n\n- [Requirements](#requirements)\n - [Install using pipx](#install-using-pipx)\n - [Install using pip](#install-using-pip)\n- [Usage](#usage)\n- [Settings](#settings)\n- [Docker Compose](#docker-compose)\n- [Development](#development)\n- [Maintainer](#maintainer)\n- [License](#license)\n\n## Requirements\n\nPython 3.11 and later is supported.\n\n### Install using pipx\n\nYou can install the latest stable release of **greenbone-scap-api** from the\n[Python Package Index (pypi)][pypi] using [pipx]\n\n python3 -m pipx install greenbone-scap-api\n\n### Install using pip\n\n> [!NOTE]\n> The `pip install` command does no longer work out-of-the-box in newer\n> distributions like Ubuntu 23.04 because of [PEP 668](https://peps.python.org/pep-0668).\n> Please use the [installation via pipx](#install-using-pipx) instead.\n\nYou can install the latest stable release of **greenbone-scap-api** from the\n[Python Package Index (pypi)][pypi] using [pip]\n\n python3 -m pip install --user greenbone-scap-api\n\n## Usage\n\nA simple web server to serve the API can be started by running\n`greenbone-scap-api`. The settings of the web server can be controlled via\n[environment variables](#settings).\n\nInternally the `greenbone-scap-api` script uses [uvicorn](https://www.uvicorn.org/)\n\nIt's also possible to serve the API with uvicorn directly\n\n```\nuvicorn greenbone.scap.api.app:app --reload\n```\n\nUsing uvicorn directly allows for more flexibility regarding the [settings](https://www.uvicorn.org/settings/)\nfor serving the API.\n\nAfter starting the web server the CVE API is available at `http://127.0.0.1:8000/cves`\n(by default). [Interactive API docs](https://github.com/swagger-api/swagger-ui)\nare served at `http://127.0.0.1:8000/docs`.\n\n## Settings\n\n**greenbone-scap-api** can be configured via the following environment variables\n\n| Name | Description | Default |\n| ----------------- | ----------------------------------------------------------------------------------------------------- | --------- |\n| DATABASE_USER | Username for the connection to the PostgreSQL database. | scap |\n| DATABASE_PASSWORD | Username for the connection to the PostgreSQL database. | |\n| DATABASE_NAME | Name of the PostgreSQL database. | scap |\n| DATABASE_HOST | Host where the PostgreSQL database is running. IP or DNS name. | 127.0.0.1 |\n| DATABASE_PORT | Port on which the PostgreSQL database is listening. | 5432 |\n| ECHO_SQL | Log SQL statements. `true` or `1` to enable. | disabled |\n| API_HOST | IP address or DNS name to listen on | 127.0.0.1 |\n| API_PORT | Port to listen on | 8000 |\n| LOG_LEVEL | Log level for server output. Options are `critical`, `error`, `warning`, `info`, `debug` and `trace`. | `info` |\n\n## Docker Compose\n\nThe API is easiest to use via the provided [docker compose](https://docs.docker.com/compose/)\nfile. [The compose file](./docker/compose.yml) extends the compose file of\n[greenbone-scap](https://github.com/greenbone/greenbone-scap/blob/main/docker/compose.yml).\nPlease take a look at the [README of greenbone-scap](https://github.com/greenbone/greenbone-scap?tab=readme-ov-file#docker-compose)\nfor the initial setup of the containers.\n\nFor a quick setup the following commands can be used:\n\n```sh\ncd docker\necho \"DATABASE_PASSWORD=my-super-safe-password\" > .env\ndocker compose up\n```\n\nAfter starting the containers the CVE API is available at `http://127.0.0.1:8000/cves`\n(by default). [Interactive API docs](https://github.com/swagger-api/swagger-ui)\nare served at `http://127.0.0.1:8000/docs`.\n\n> [!NOTE]\n> On the initial startup all CVE will be downloaded from the [NIST NVD API](https://services.nvd.nist.gov/rest/json/cves/2.0).\n> Downloading the data may take several hours and due to unreliable servers at\n> NIST may even fail. After a successful full download of the data at NIST, only\n> the changed and new CVEs will be downloaded. To trigger a download\n> `docker compose up cve` can be used.\n\n## Development\n\n**greenbone-scap-api** uses [poetry] for its own dependency management and build\nprocess.\n\nFirst install poetry via [pipx]\n\n python3 -m pipx install poetry\n\nAfterwards run\n\n poetry install\n\nin the checkout directory of **greenbone-scap-api** (the directory containing the\n`pyproject.toml` file) to install all dependencies including the packages only\nrequired for development.\n\nAfterwards activate the git hooks for auto-formatting and linting via\n[autohooks].\n\n poetry run autohooks activate\n\nValidate the activated git hooks by running\n\n poetry run autohooks check\n\n## Maintainer\n\nThis project is maintained by [Greenbone AG][Greenbone]\n\n## License\n\nCopyright (C) 2024 [Greenbone AG][Greenbone]\n\nLicensed under the [GNU Affero General Public License v3.0 or later](LICENSE).\n\n[Greenbone]: https://www.greenbone.net/\n[poetry]: https://python-poetry.org/\n[pip]: https://pip.pypa.io/\n[pipx]: https://pypa.github.io/pipx/\n[autohooks]: https://github.com/greenbone/autohooks\n[pypi]: https://pypi.org\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "REST API on top of greenbone-scap",
"version": "0.0.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "29f06c708b7f75117d0b0f23351b662f65a738e23a2bc2bd79b9cfa465159f2a",
"md5": "843c6645e9dacb94ee0d0d9bc389cdb2",
"sha256": "dd478bca8775b1f50a5b7a873e1b599fce0ea810e14f16adb796998c31839747"
},
"downloads": -1,
"filename": "greenbone_scap_api-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "843c6645e9dacb94ee0d0d9bc389cdb2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 25096,
"upload_time": "2024-03-21T10:39:48",
"upload_time_iso_8601": "2024-03-21T10:39:48.884290Z",
"url": "https://files.pythonhosted.org/packages/29/f0/6c708b7f75117d0b0f23351b662f65a738e23a2bc2bd79b9cfa465159f2a/greenbone_scap_api-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e52ddade657f826a9dc606694994271869480e6b8641dd60ee2692b6105ca90f",
"md5": "853ff0d1e531d2a7021df0eb1ae0d3f5",
"sha256": "65cd00ffa57cee277b824a140697af6e4a501d583e28f46d4082f9df6df6b318"
},
"downloads": -1,
"filename": "greenbone_scap_api-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "853ff0d1e531d2a7021df0eb1ae0d3f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 23825,
"upload_time": "2024-03-21T10:39:50",
"upload_time_iso_8601": "2024-03-21T10:39:50.533438Z",
"url": "https://files.pythonhosted.org/packages/e5/2d/dade657f826a9dc606694994271869480e6b8641dd60ee2692b6105ca90f/greenbone_scap_api-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-21 10:39:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "greenbone-scap-api"
}