diff --git a/docs/api/api.rst b/docs/api/api.md similarity index 70% rename from docs/api/api.rst rename to docs/api/api.md index a51b204ce..278fd53c2 100644 --- a/docs/api/api.rst +++ b/docs/api/api.md @@ -1,7 +1,6 @@ -.. _api: +(api)= -Developer Interface -=================== +# Developer Interface This part of the documentation covers all public interfaces of python-gvm. @@ -10,11 +9,11 @@ classes for establishing a communication to a remote server, protocol modules to talk the communication languages, possible raised errors, additional utilities and xml helpers. -.. toctree:: - - main - connections - transforms - protocols - errors - other +```{toctree} +main +connections +transforms +protocols +errors +other +``` diff --git a/docs/api/connections.rst b/docs/api/connections.md similarity index 65% rename from docs/api/connections.rst rename to docs/api/connections.md index 97af68a54..1b28bda79 100644 --- a/docs/api/connections.rst +++ b/docs/api/connections.md @@ -1,21 +1,32 @@ -.. _connections: +(connections)= -Connections ------------ +# Connections +```{eval-rst} .. automodule:: gvm.connections +``` +```{eval-rst} .. autoclass:: GvmConnection :members: +``` +```{eval-rst} .. autoclass:: SSHConnection :members: +``` +```{eval-rst} .. autoclass:: TLSConnection :members: +``` +```{eval-rst} .. autoclass:: UnixSocketConnection :members: +``` +```{eval-rst} .. autoclass:: DebugConnection :members: +``` diff --git a/docs/api/errors.rst b/docs/api/errors.md similarity index 53% rename from docs/api/errors.rst rename to docs/api/errors.md index d6debeff0..fb78ce7cc 100644 --- a/docs/api/errors.rst +++ b/docs/api/errors.md @@ -1,7 +1,8 @@ -.. _errors: +(errors)= -Errors -====== +# Errors +```{eval-rst} .. automodule:: gvm.errors :members: +``` diff --git a/docs/api/gmp.md b/docs/api/gmp.md new file mode 100644 index 000000000..f00cfd57c --- /dev/null +++ b/docs/api/gmp.md @@ -0,0 +1,19 @@ +(gmp)= + +# GMP + +```{eval-rst} +.. automodule:: gvm.protocols.gmp +``` + +```{eval-rst} +.. autoclass:: GMP + :members: +``` + +```{toctree} +:maxdepth: 1 + +gmpv224 +gmpv225 +``` diff --git a/docs/api/gmp.rst b/docs/api/gmp.rst deleted file mode 100644 index 851383ee6..000000000 --- a/docs/api/gmp.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _gmp: - - -GMP -^^^ -.. automodule:: gvm.protocols.gmp - -.. autoclass:: GMP - :members: - -.. toctree:: - :maxdepth: 1 - - gmpv224 - gmpv225 diff --git a/docs/api/gmpv224.rst b/docs/api/gmpv224.md similarity index 82% rename from docs/api/gmpv224.rst rename to docs/api/gmpv224.md index 57183d621..2a7c72b2e 100644 --- a/docs/api/gmpv224.rst +++ b/docs/api/gmpv224.md @@ -1,93 +1,131 @@ -.. _gmpv224: +(gmpv224)= -GMP v22.4 -^^^^^^^^^ +# GMP v22.4 +```{eval-rst} .. automodule:: gvm.protocols.gmp._gmp224 +``` +## Protocol -Protocol --------- - +```{eval-rst} .. autoclass:: gvm.protocols.gmp.GMPv224 :members: :inherited-members: +``` -Enums ------ +## Enums +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.AlertCondition :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.AlertEvent :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.AlertMethod :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.AliveTest :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.CredentialFormat :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.CredentialType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.EntityType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.FeedType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.FilterType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.HostsOrdering :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.HelpFormat :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.InfoType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.PermissionSubjectType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.PortRangeType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.ReportFormatType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.ScannerType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.SnmpAuthAlgorithm :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.SnmpPrivacyAlgorithm :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v224.TicketStatus :members: :undoc-members: +``` diff --git a/docs/api/gmpv225.rst b/docs/api/gmpv225.md similarity index 84% rename from docs/api/gmpv225.rst rename to docs/api/gmpv225.md index 34d1f717c..6105b28c4 100644 --- a/docs/api/gmpv225.rst +++ b/docs/api/gmpv225.md @@ -1,115 +1,156 @@ -.. _gmpv225: +# GMP v22.5 -GMP v22.5 -^^^^^^^^^ +(gmpv225)= +```{eval-rst} .. automodule:: gvm.protocols.gmp._gmp225 +``` -Protocol --------- +## Protocol +```{eval-rst} .. autoclass:: gvm.protocols.gmp.GMPv225 :members: :inherited-members: +``` -Enums ------ +## Enums +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.AlertCondition :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.AlertEvent :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.AlertMethod :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.AliveTest :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.CredentialFormat :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.CredentialType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.EntityType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.FeedType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.FilterType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.HostsOrdering :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.HelpFormat :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.InfoType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.PermissionSubjectType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.PortRangeType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.ReportFormatType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.ResourceType :members: :undoc-members: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.ScannerType :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.SnmpAuthAlgorithm :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.SnmpPrivacyAlgorithm :members: :undoc-members: :no-index: +``` +```{eval-rst} .. autoclass:: gvm.protocols.gmp.requests.v225.TicketStatus :members: :undoc-members: :no-index: +``` diff --git a/docs/api/main.rst b/docs/api/main.md similarity index 53% rename from docs/api/main.rst rename to docs/api/main.md index 2843321e3..cbb66640f 100644 --- a/docs/api/main.rst +++ b/docs/api/main.md @@ -1,10 +1,15 @@ -.. _main: +(main)= -Main -==== +# Main +```{eval-rst} .. automodule:: gvm +``` +```{eval-rst} .. autodata:: __version__ +``` +```{eval-rst} .. autofunction:: get_version +``` diff --git a/docs/api/ospv1.rst b/docs/api/ospv1.md similarity index 64% rename from docs/api/ospv1.rst rename to docs/api/ospv1.md index e16afd450..35153311f 100644 --- a/docs/api/ospv1.rst +++ b/docs/api/ospv1.md @@ -1,10 +1,13 @@ -.. _ospv1: +(ospv1)= -OSP v1 -^^^^^^ +# OSP v1 +```{eval-rst} .. automodule:: gvm.protocols.ospv1 +``` +```{eval-rst} .. autoclass:: Osp :members: :inherited-members: +``` diff --git a/docs/api/other.rst b/docs/api/other.md similarity index 61% rename from docs/api/other.rst rename to docs/api/other.md index 1f8910cd6..86a3f39c1 100644 --- a/docs/api/other.rst +++ b/docs/api/other.md @@ -1,11 +1,13 @@ -Utils ------ +# Utils +```{eval-rst} .. automodule:: gvm.utils :members: +``` -XML ---- +# XML +```{eval-rst} .. automodule:: gvm.xml :members: +``` diff --git a/docs/api/protocols.md b/docs/api/protocols.md new file mode 100644 index 000000000..587379e20 --- /dev/null +++ b/docs/api/protocols.md @@ -0,0 +1,32 @@ +# Protocols + +(protocols)= + +```{eval-rst} +.. automodule:: gvm.protocols +``` + +```{toctree} +:maxdepth: 1 + +gmp +ospv1 +``` + +## Dynamic + +To dynamically use the supported GMP version of the manager daemon see +{mod}`gvm.protocols.gmp` for details. + +## "latest" protocols + +```{eval-rst} +.. automodule:: gvm.protocols.latest + +``` + +## "next" protocols + +```{eval-rst} +.. automodule:: gvm.protocols.next +``` diff --git a/docs/api/protocols.rst b/docs/api/protocols.rst deleted file mode 100644 index 7e1458ce6..000000000 --- a/docs/api/protocols.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _protocols: - -Protocols ---------- - -.. automodule:: gvm.protocols - -.. toctree:: - :maxdepth: 1 - - gmp - ospv1 - -Dynamic -^^^^^^^ - -To dynamically use the supported GMP version of the manager daemon see -:mod:`gvm.protocols.gmp` for details. - -"latest" protocols -^^^^^^^^^^^^^^^^^^ - -.. automodule:: gvm.protocols.latest - - -"next" protocols -^^^^^^^^^^^^^^^^ - -.. automodule:: gvm.protocols.next diff --git a/docs/api/transforms.rst b/docs/api/transforms.md similarity index 51% rename from docs/api/transforms.rst rename to docs/api/transforms.md index 51eef919c..b7eee7609 100644 --- a/docs/api/transforms.rst +++ b/docs/api/transforms.md @@ -1,7 +1,8 @@ -.. _transforms: +(transforms)= -Transforms -========== +# Transforms +```{eval-rst} .. automodule:: gvm.transforms :members: +``` diff --git a/docs/conf.py b/docs/conf.py index 4805d42cc..a750be7f7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,19 +47,22 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.githubpages", "sphinx.ext.napoleon", ] +myst_enable_extensions = ["colon_fence"] +myst_heading_anchors = 3 + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" +source_suffix = {".rst": "restructuredtext"} # The master toctree document. master_doc = "index" diff --git a/docs/index.rst b/docs/index.md similarity index 50% rename from docs/index.rst rename to docs/index.md index 9a606f428..409987759 100644 --- a/docs/index.rst +++ b/docs/index.md @@ -1,29 +1,30 @@ -Greenbone Vulnerability Management Python Library -================================================= +# Greenbone Vulnerability Management Python Library **python-gvm** is the official python library to control Greenbone Community Edition installations and Greenbone Enterprise Appliances remotely. -.. note:: **python-gvm** requires at least Python 3.9. Python 2 is not supported. +:::{note} +**python-gvm** requires at least Python 3.9. Python 2 is not supported. +::: -User Guide ----------- +## User Guide This sections explains how to install **python-gvm** and shows example use cases. -.. toctree:: - :maxdepth: 2 +```{toctree} +:maxdepth: 2 - install - usage +install +usage +``` -The API Documentation ---------------------- +## The API Documentation Information about specific functions, classes, or methods can be found in this part of the documentation. -.. toctree:: - :maxdepth: 2 +```{toctree} +:maxdepth: 2 - api/api +api/api +``` diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000..1c449ddae --- /dev/null +++ b/docs/install.md @@ -0,0 +1,60 @@ +(install)= + +# Installation of python-gvm + +For installing the latest stable release of **python-gvm**, [pip], [poetry] +or [pipenv] can be used. + +If an application or library that uses **python-gvm** internally is developed, +it is often better to choose [poetry] for handling the dependencies. + +## Using pip + +For installing **python-gvm** using [pip] run: + +``` +python3 -m pip install python-gvm +``` + +## Using poetry + +For installing **python-gvm** using [poetry] run: + +``` +poetry add python-gvm +``` + +If the usage of [poetry] is not familiar, its documentation can be found at +. + +## Using pipenv + +For installing **python-gvm** using [pipenv] run: + +``` +pipenv install python-gvm +``` + +If [pipenv] is not used yet, head over to the pipenv website for +installation instructions. + +## Getting the Source + +The source code of **python-gvm** can be found at +[GitHub](https://github.com/greenbone/python-gvm). + +To clone the public repository run: + +``` +git clone git://github.com/greenbone/python-gvm +``` + +Once there is a copy of the source, it can be embedded it the own application as follows: + +``` +python3 -m pip install -e /path/to/python-gvm +``` + +[pip]: https://pip.pypa.io/en/stable/ +[pipenv]: https://pipenv.readthedocs.io/en/latest/ +[poetry]: https://python-poetry.org/ diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 7e1453c89..000000000 --- a/docs/install.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _install: - -Installation of python-gvm -========================== - -For installing the latest stable release of **python-gvm**, `pip`_, `poetry`_ -or `pipenv`_ can be used. - -If an application or library that uses **python-gvm** internally is developed, -it is often better to choose `poetry`_ for handling the dependencies. - -Using pip ---------- - -For installing **python-gvm** using `pip`_ run:: - - python3 -m pip install python-gvm - -Using poetry ------------- - -For installing **python-gvm** using `poetry`_ run:: - - poetry add python-gvm - -If the usage of `poetry`_ is not familiar, its documentation can be found at -https://python-poetry.org/docs/. - -Using pipenv ------------- - -For installing **python-gvm** using `pipenv`_ run:: - - pipenv install python-gvm - -If `pipenv`_ is not used yet, head over to the pipenv website for -installation instructions. - -Getting the Source ------------------- - -The source code of **python-gvm** can be found at -`GitHub `_. - -To clone the public repository run:: - - git clone git://github.com/greenbone/python-gvm - -Once there is a copy of the source, it can be embedded it the own application as follows:: - - python3 -m pip install -e /path/to/python-gvm - -.. _pip: https://pip.pypa.io/en/stable/ -.. _pipenv: https://pipenv.readthedocs.io/en/latest/ -.. _poetry: https://python-poetry.org/ diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 000000000..01bddddbb --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,339 @@ +(usage)= + +# Usage + +## Introduction + +To communicate with a remote server via one of the +{ref}`GVM protocols ` it is required to decide which transport +protocol should be used for the {ref}`connection `. Currently two protocols +– namely +{py:class}`GMP ` and +{py:class}`OSP ` – and three connection types – namely +{py:class}`TLS `, +{py:class}`SSH ` and +{py:class}`Unix domain socket ` – +are available. + +## Using GMP + +The **Greenbone Management Protocol (GMP)** is the protocol implemented by the +[Greenbone Vulnerability Manager Daemon – gvmd](https://github.com/greenbone/gvmd). +It is also used by the [Greenbone Security Assistant Daemon](https://github.com/greenbone/gsad) +to request all of its information from **gvmd**. + +### Making a Simple Request + +To create a request, a {ref}`connection ` type has to be chosen. +The decision depends on the location and configuration of the remote **gvmd** +server. For local communication {py:class}`Unix domain socket ` +fits best. The simplest command is to request the **GMP** version used by the +remote **gvmd**. + +#### Step by Step + +The following shows the process of a simple request in more detail. + +1. Import the necessary classes: + +```python +from gvm.connections import UnixSocketConnection +from gvm.protocols.gmp import Gmp +``` + +2. Specify the path to the Unix domain socket in the file system: + +:::{note} +If **gvmd** is provided by a package of the distribution, it should +be `/run/gvmd/gvmd.sock`. If **gvmd** was built from source and did not set +a prefix, the default path can be used by setting `path = None`. +::: + +```python +path = '/run/gvmd/gvmd.sock' +``` + +3. Create a connection and a gmp object: + +```python +connection = UnixSocketConnection(path=path) +``` + +4. Establish a connection to be able to make a request on **gvmd**. To automatically connect and disconnect, a Python + [with statement](https://docs.python.org/3/reference/datamodel.html#with-statement-context-managers) should be used. + +:::{note} +By default all request methods of the {py:class}`gmp ` +object return the response as UTF-8 encoded string. +::: + +5. Obtain the protocol version of the **gvmd** by printing the response of the unprivileged command `*get_version*`: + +```python +with Gmp(connection=connection) as gmp: + print(gmp.get_version()) +``` + +#### Full Example + +```python +from gvm.connections import UnixSocketConnection +from gvm.protocols.gmp import Gmp + +# path to unix socket +path = '/run/gvmd/gvmd.sock' +connection = UnixSocketConnection(path=path) + +# using the with statement to automatically connect and disconnect to gvmd +with Gmp(connection=connection) as gmp: + # get the response message returned as a utf-8 encoded string + response = gmp.get_version() + + # print the response message + print(response) +``` + +On success the response will look as follows: + +```xml +9.0 +``` + +### Privileged Request + +Most requests to **gvmd** require permissions to access data. Therefore it is +required to authenticate against **gvmd**. + +#### Step by Step + +1. Import the necessary classes: + +```python +from gvm.connections import UnixSocketConnection +from gvm.protocols.gmp import Gmp +``` + +2. Create a connection: + +```python +path = '/run/gvmd/gvmd.sock' +connection = UnixSocketConnection(path=path) +``` + +3. In this case, an [Etree Element] should be obtained from the response to be able to + extract specific information. + + To do so, pass a {py:mod}`transform ` to the {py:class}`Gmp ` + constructor. Additionally, a {py:class}`GvmError ` should be raised if the status of the + response was not *ok*. Therefore choose a {py:class}`EtreeCheckCommandTransform `: + +```python +from gvm.transforms import EtreeCheckCommandTransform + +transform = EtreeCheckCommandTransform() +``` + +:::{note} +By choosing a {py:class}`EtreeCheckCommandTransform ` it is ensured that calling a privileged command always fails, e.g. calling + +```python +with Gmp(connection=connection, transform=transform) as gmp: + gmp.get_task() +``` + +without being authenticated will throw an error now. +::: + +5. Set a user name and a password for authentication: + +```python +username = 'foo' +password = 'bar' +``` + +6. Create a connection, do the authentication, request all tasks + with 'weekly' in their name and list their full names: + +```python +from gvm.errors import GvmError + +try: + with Gmp(connection=connection, transform=transform) as gmp: + gmp.authenticate(username, password) + + tasks = gmp.get_tasks(filter_string='name~weekly') + + for task in tasks.xpath('task'): + print(task.find('name').text) + +except GvmError as e: + print('An error occurred', e) +``` + +#### Full Example + +```python +import sys + +from gvm.connections import UnixSocketConnection +from gvm.errors import GvmError +from gvm.protocols.gmp import Gmp +from gvm.transforms import EtreeCheckCommandTransform + +path = '/run/gvmd/gvmd.sock' +connection = UnixSocketConnection(path=path) +transform = EtreeCheckCommandTransform() + +username = 'foo' +password = 'bar' + +try: + tasks = [] + + with Gmp(connection=connection, transform=transform) as gmp: + gmp.authenticate(username, password) + + tasks = gmp.get_tasks(filter_string='name~weekly') + + for task in tasks.xpath('task'): + print(task.find('name').text) + +except GvmError as e: + print('An error occurred', e, file=sys.stderr) +``` + +## Using OSP + +The **Open Scanner Protocol (OSP)** is a communication protocol implemented by +a base class for scanner wrappers [Open Scanner Protocol Daemon – ospd](https://github.com/greenbone/ospd). +**OSP** creates a unified interface for different security scanners and makes +their control flow and scan results consistently available under the +[Greenbone Vulnerability Manager Daemon – gvmd](https://github.com/greenbone/gvmd). +In many ways, **OSP** is similar to **Greenbone Management Protocol (GMP)**: +XML-based, stateless and with a non-permanent connection. + +### Making a Simple Request + +To create a request you have to choose a {ref}`connection ` type. +The decision depends on the location and configuration of the remote +**ospd-wrapper** server. For local communication {py:class}`Unix domain socket ` +fits best, but also a {py:class}`secure TLS connection ` +is possible. +The simplest command is to request the server version. + +#### Step by Step + +1. Import the necessary classes: + +```python +from gvm.connections import UnixSocketConnection +from gvm.protocols.latest import Osp +``` + +2. The path to the Unix domain socket in the file system is given during the start + of the ospd-wrapper. + + Specify the path to the Unix domain socket in the file system: + +```python +path = '/tmp/ospd-wrapper.sock' +``` + +3. Create a connection and an osp object: + +```python +connection = UnixSocketConnection(path=path) +osp = Osp(connection=connection) +``` + +4. Establish a connection to be able to make a request on **ospd-wrapper**. + To automatically connect and disconnect, a Python [with statement](https://docs.python.org/3/reference/datamodel.html#with-statement-context-managers) + should be used. + +:::{note} +By default all request methods of the {py:class}`osp ` +object return the response as UTF-8 encoded string. +::: + +5. Obtain the **OSP** protocol version, the **ospd** base implementation class and + the **ospd-wrapper** server version by printing the response of the command `get_version`: + +```python +with osp: + print(osp.get_version()) +``` + +#### Full Example + +```python +from gvm.connections import UnixSocketConnection +from gvm.protocols.latest import Osp + +# path to unix socket +path = '/var/run/ospd-wrapper.sock' +connection = UnixSocketConnection(path=path) +osp = Osp(connection=connection) + +# using the with statement to automatically connect and disconnect to ospd +with osp: + # get the response message returned as a utf-8 encoded string + response = osp.get_version() + + # print the response message + print(response) +``` + +On success the response will look as follows: + +```xml +OSP1.2OSPd1.4b1some-wrapperWrapper 6.0beta+2 +``` + +## Debugging + +Sometimes networking setups can be complex and hard to follow. Connections may +be aborted randomly or an invalid command may have arrived at the server side. +Because of this, it may be necessary to debug the connection handling and especially +the protocol commands. + +**python-gvm** uses the [logging] package internally. To enable a +simple debug output appended to a *debug.log* file the following code can be +used: + +```python +import logging + +logging.basicConfig(filename='debug.log', level=logging.DEBUG) +``` + +With this simple addition it is already possible to debug ssh connection problems. + +But what if a response did not contain the expected data and it is important to know +in detail which command has been send to the server? + +In this case it is necessary to wrap the actual connection in a +{py:class}`DebugConnection ` class. + +Example using GMP: + +```python +from gvm.connections import UnixSocketConnection, DebugConnection +from gvm.protocols.gmp import Gmp + +path = '/run/gvmd/gvmd.sock' +socketconnection = UnixSocketConnection(path=path) +connection = DebugConnection(socketconnection) + +with Gmp(connection=connection) as gmp: + gmp.get_version() +``` + +With this change the file *debug.log* will contain something as follows: + +``` +DEBUG:gvm.connections:Sending 14 characters. Data +DEBUG:gvm.connections:Read 97 characters. Data 9.0 +``` + +[etree element]: https://docs.python.org/3/library/xml.etree.elementtree.html#element-objects +[logging]: https://docs.python.org/3/library/logging.html diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index ae4390fb0..000000000 --- a/docs/usage.rst +++ /dev/null @@ -1,347 +0,0 @@ -.. _usage: - -Usage -===== - -Introduction ------------- - -To communicate with a remote server via one of the -:ref:`GVM protocols ` it is required to decide which transport -protocol should be used for the :ref:`connection `. Currently two protocols -– namely -:py:class:`GMP ` and -:py:class:`OSP ` – and three connection types – namely -:py:class:`TLS `, -:py:class:`SSH ` and -:py:class:`Unix domain socket ` – -are available. - -Using GMP ---------- - -The **Greenbone Management Protocol (GMP)** is the protocol implemented by the -`Greenbone Vulnerability Manager Daemon – gvmd `_. -It is also used by the `Greenbone Security Assistant Daemon `_ -to request all of its information from **gvmd**. - -Making a Simple Request -^^^^^^^^^^^^^^^^^^^^^^^ - -To create a request, a :ref:`connection ` type has to be chosen. -The decision depends on the location and configuration of the remote **gvmd** -server. For local communication :py:class:`Unix domain socket ` -fits best. The simplest command is to request the **GMP** version used by the -remote **gvmd**. - -Step by Step -"""""""""""" - -The following shows the process of a simple request in more detail. - -1. Import the necessary classes: - -.. code-block:: python - - from gvm.connections import UnixSocketConnection - from gvm.protocols.gmp import Gmp - -2. Specify the path to the Unix domain socket in the file system: - -.. note:: If **gvmd** is provided by a package of the distribution, it should - be ``/run/gvmd/gvmd.sock``. If **gvmd** was built from source and did not set - a prefix, the default path can be used by setting ``path = None``. - -.. code-block:: python - - path = '/run/gvmd/gvmd.sock' - -3. Create a connection and a gmp object: - -.. code-block:: python - - connection = UnixSocketConnection(path=path) - -4. Establish a connection to be able to make a request on **gvmd**. To automatically connect and disconnect, a Python - `with statement `_ should be used. - -.. note:: By default all request methods of the :py:class:`gmp ` - object return the response as UTF-8 encoded string. - -5. Obtain the protocol version of the **gvmd** by printing the response of the unprivileged command ``*get_version*``: - -.. code-block:: python - - with Gmp(connection=connection) as gmp: - print(gmp.get_version()) - -Full Example -"""""""""""" - -.. code-block:: python - - from gvm.connections import UnixSocketConnection - from gvm.protocols.gmp import Gmp - - # path to unix socket - path = '/run/gvmd/gvmd.sock' - connection = UnixSocketConnection(path=path) - - # using the with statement to automatically connect and disconnect to gvmd - with Gmp(connection=connection) as gmp: - # get the response message returned as a utf-8 encoded string - response = gmp.get_version() - - # print the response message - print(response) - -On success the response will look as follows: - -.. code-block:: xml - - 9.0 - -Privileged Request -^^^^^^^^^^^^^^^^^^ - -Most requests to **gvmd** require permissions to access data. Therefore it is -required to authenticate against **gvmd**. - -Step by Step -"""""""""""" - -1. Import the necessary classes: - -.. code-block:: python - - from gvm.connections import UnixSocketConnection - from gvm.protocols.gmp import Gmp - -2. Create a connection: - -.. code-block:: python - - path = '/run/gvmd/gvmd.sock' - connection = UnixSocketConnection(path=path) - -3. In this case, an `Etree Element`_ should be obtained from the response to be able to - extract specific information. - - To do so, pass a :py:mod:`transform ` to the :py:class:`Gmp ` - constructor. Additionally, a :py:class:`GvmError ` should be raised if the status of the - response was not *ok*. Therefore choose a :py:class:`EtreeCheckCommandTransform `: - -.. code-block:: python - - from gvm.transforms import EtreeCheckCommandTransform - - transform = EtreeCheckCommandTransform() - -.. note:: By choosing a :py:class:`EtreeCheckCommandTransform ` it is ensured that calling a privileged command always fails, e.g. calling - - .. code-block:: python - - with Gmp(connection=connection, transform=transform) as gmp: - gmp.get_task() - - without being authenticated will throw an error now. - -5. Set a user name and a password for authentication: - -.. code-block:: python - - username = 'foo' - password = 'bar' - -6. Create a connection, do the authentication, request all tasks - with 'weekly' in their name and list their full names: - -.. code-block:: python - - from gvm.errors import GvmError - - try: - with Gmp(connection=connection, transform=transform) as gmp: - gmp.authenticate(username, password) - - tasks = gmp.get_tasks(filter_string='name~weekly') - - for task in tasks.xpath('task'): - print(task.find('name').text) - - except GvmError as e: - print('An error occurred', e) - -.. _Etree Element: - https://docs.python.org/3/library/xml.etree.elementtree.html#element-objects - -Full Example -"""""""""""" - -.. code-block:: python - - import sys - - from gvm.connections import UnixSocketConnection - from gvm.errors import GvmError - from gvm.protocols.gmp import Gmp - from gvm.transforms import EtreeCheckCommandTransform - - path = '/run/gvmd/gvmd.sock' - connection = UnixSocketConnection(path=path) - transform = EtreeCheckCommandTransform() - - username = 'foo' - password = 'bar' - - try: - tasks = [] - - with Gmp(connection=connection, transform=transform) as gmp: - gmp.authenticate(username, password) - - tasks = gmp.get_tasks(filter_string='name~weekly') - - for task in tasks.xpath('task'): - print(task.find('name').text) - - except GvmError as e: - print('An error occurred', e, file=sys.stderr) - -Using OSP ---------- - -The **Open Scanner Protocol (OSP)** is a communication protocol implemented by -a base class for scanner wrappers `Open Scanner Protocol Daemon – ospd `_. -**OSP** creates a unified interface for different security scanners and makes -their control flow and scan results consistently available under the -`Greenbone Vulnerability Manager Daemon – gvmd `_. -In many ways, **OSP** is similar to **Greenbone Management Protocol (GMP)**: -XML-based, stateless and with a non-permanent connection. - -Making a Simple Request -^^^^^^^^^^^^^^^^^^^^^^^ - -To create a request you have to choose a :ref:`connection ` type. -The decision depends on the location and configuration of the remote -**ospd-wrapper** server. For local communication :py:class:`Unix domain socket ` -fits best, but also a :py:class:`secure TLS connection ` -is possible. -The simplest command is to request the server version. - -Step by Step -"""""""""""" - -1. Import the necessary classes: - -.. code-block:: python - - from gvm.connections import UnixSocketConnection - from gvm.protocols.latest import Osp - -2. The path to the Unix domain socket in the file system is given during the start - of the ospd-wrapper. - - Specify the path to the Unix domain socket in the file system: - -.. code-block:: python - - path = '/tmp/ospd-wrapper.sock' - -3. Create a connection and an osp object: - -.. code-block:: python - - connection = UnixSocketConnection(path=path) - osp = Osp(connection=connection) - -4. Establish a connection to be able to make a request on **ospd-wrapper**. - To automatically connect and disconnect, a Python `with statement `_ - should be used. - -.. note:: By default all request methods of the :py:class:`osp ` - object return the response as UTF-8 encoded string. - -5. Obtain the **OSP** protocol version, the **ospd** base implementation class and - the **ospd-wrapper** server version by printing the response of the command ``get_version``: - -.. code-block:: python - - with osp: - print(osp.get_version()) - -Full Example -"""""""""""" - -.. code-block:: python - - from gvm.connections import UnixSocketConnection - from gvm.protocols.latest import Osp - - # path to unix socket - path = '/var/run/ospd-wrapper.sock' - connection = UnixSocketConnection(path=path) - osp = Osp(connection=connection) - - # using the with statement to automatically connect and disconnect to ospd - with osp: - # get the response message returned as a utf-8 encoded string - response = osp.get_version() - - # print the response message - print(response) - -On success the response will look as follows: - -.. code-block:: xml - - OSP1.2OSPd1.4b1some-wrapperWrapper 6.0beta+2 - -Debugging ---------- - -Sometimes networking setups can be complex and hard to follow. Connections may -be aborted randomly or an invalid command may have arrived at the server side. -Because of this, it may be necessary to debug the connection handling and especially -the protocol commands. - -**python-gvm** uses the `logging`_ package internally. To enable a -simple debug output appended to a *debug.log* file the following code can be -used: - -.. code-block:: python - - import logging - - logging.basicConfig(filename='debug.log', level=logging.DEBUG) - - -With this simple addition it is already possible to debug ssh connection problems. - -But what if a response did not contain the expected data and it is important to know -in detail which command has been send to the server? - -In this case it is necessary to wrap the actual connection in a -:py:class:`DebugConnection ` class. - -Example using GMP: - -.. code-block:: python - - from gvm.connections import UnixSocketConnection, DebugConnection - from gvm.protocols.gmp import Gmp - - path = '/run/gvmd/gvmd.sock' - socketconnection = UnixSocketConnection(path=path) - connection = DebugConnection(socketconnection) - - with Gmp(connection=connection) as gmp: - gmp.get_version() - -With this change the file *debug.log* will contain something as follows:: - - DEBUG:gvm.connections:Sending 14 characters. Data - DEBUG:gvm.connections:Read 97 characters. Data 9.0 - -.. _logging: - https://docs.python.org/3/library/logging.html diff --git a/gvm/__init__.py b/gvm/__init__.py index c2816af30..de04787c3 100644 --- a/gvm/__init__.py +++ b/gvm/__init__.py @@ -5,17 +5,15 @@ """ Main module of python-gvm. """ + from .__version__ import __version__ def get_version() -> str: - """Returns the version of python-gvm as a string in `PEP440`_ compliant - format. + """Returns the version of python-gvm as a string in + `PEP440 `_ compliant format. Returns: Current version of python-gvm - - .. _PEP440: - https://www.python.org/dev/peps/pep-0440 """ return __version__ diff --git a/gvm/connections/_debug.py b/gvm/connections/_debug.py index 75df08794..fe4de63b8 100644 --- a/gvm/connections/_debug.py +++ b/gvm/connections/_debug.py @@ -13,9 +13,9 @@ class DebugConnection: """Wrapper around a connection for debugging purposes Allows to debug the connection flow including send and read data. Internally - it uses the python `logging`_ framework to create debug messages. Please - take a look at `the logging tutorial - `_ + it uses the python `logging `_ + framework to create debug messages. Please take a look at + `the logging tutorial `_ for further details. Example: @@ -29,9 +29,6 @@ class DebugConnection: socket_connection = UnixSocketConnection(path='/var/run/gvm.sock') connection = DebugConnection(socket_connection) gmp = Gmp(connection=connection) - - .. _logging: - https://docs.python.org/3/library/logging.html """ def __init__(self, connection: GvmConnection): diff --git a/gvm/connections/_tls.py b/gvm/connections/_tls.py index de519ad70..f0fc1e1f1 100644 --- a/gvm/connections/_tls.py +++ b/gvm/connections/_tls.py @@ -41,17 +41,14 @@ def __init__( hostname: DNS name or IP address of the remote TLS server. port: Port for the TLS connection. Default is 9390. certfile: Path to PEM encoded certificate file. See - `python certificates`_ for details. - cafile: Path to PEM encoded CA file. See `python certificates`_ + `python certificates `_ for details. + cafile: Path to PEM encoded CA file. See `python certificates `_ for details. - keyfile: Path to PEM encoded private key. See `python certificates`_ + keyfile: Path to PEM encoded private key. See `python certificates `_ for details. password: Password for the private key. If the password argument is not specified and a password is required it will be interactively prompt the user for a password. - - .. _python certificates: - https://docs.python.org/3/library/ssl.html#certificates """ super().__init__(timeout=timeout) diff --git a/gvm/protocols/__init__.py b/gvm/protocols/__init__.py index 3be775ebf..832369419 100644 --- a/gvm/protocols/__init__.py +++ b/gvm/protocols/__init__.py @@ -5,13 +5,16 @@ """ Package for supported Greenbone Protocol versions. -Currently `GMP version 22.04`_, `GMP version 22.05`_ +Currently GMP version 22.4, `GMP version 22.5`_, +`GMP version 22.6`_, `GMP version 22.7`_ and `OSP version 1`_ are supported. -.. _GMP version 22.04: - https://docs.greenbone.net/API/GMP/gmp-22.04.html -.. _GMP version 22.05: - https://docs.greenbone.net/API/GMP/gmp-22.05.html +.. _GMP version 22.5: + https://docs.greenbone.net/API/GMP/gmp-22.5.html +.. _GMP version 22.6: + https://docs.greenbone.net/API/GMP/gmp-22.6.html +.. _GMP version 22.7: + https://docs.greenbone.net/API/GMP/gmp-22.7.html .. _OSP version 1: https://docs.greenbone.net/API/OSP/osp-1.2.html """ diff --git a/gvm/protocols/_protocol.py b/gvm/protocols/_protocol.py index 310a7597e..ab37b91b0 100644 --- a/gvm/protocols/_protocol.py +++ b/gvm/protocols/_protocol.py @@ -86,10 +86,7 @@ def connect(self) -> None: Normally connect is not called directly. Either it is called automatically when sending a protocol command or when using a - `with statement`_. - - .. _with statement: - https://docs.python.org/3/reference/datamodel.html#with-statement-context-managers + `with statement `_. """ if not self.is_connected(): self._connection.connect() diff --git a/gvm/protocols/gmp/_gmp.py b/gvm/protocols/gmp/_gmp.py index 0f2026718..10ce179f8 100644 --- a/gvm/protocols/gmp/_gmp.py +++ b/gvm/protocols/gmp/_gmp.py @@ -25,8 +25,7 @@ class GMP(GvmProtocol[T]): """Dynamically select supported GMP protocol of the remote manager daemon. - Must be used as a `Context Manager - `_ + Must be used as a `Context Manager `_ Example: @@ -42,7 +41,6 @@ class GMP(GvmProtocol[T]): # or gvm.protocols.gmp.GMPv227 # depending on the supported GMP version of the remote manager daemon resp = gmp.get_tasks() - """ def __init__( @@ -57,15 +55,12 @@ def __init__( Args: connection: Connection to use to talk with the remote daemon. See :mod:`gvm.connections` for possible connection types. - transform: Optional transform `callable`_ to convert response data. - After each request the callable gets passed the plain response data + transform: Optional transform `callable `_ + to convert response data. After each request the callable gets passed the plain response data which can be used to check the data and/or conversion into different representations like a xml dom. See :mod:`gvm.transforms` for existing transforms. - - .. _callable: - https://docs.python.org/3/library/functions.html#callable """ super().__init__(connection, transform=transform) self._gmp: Optional[SUPPORTED_GMP_VERSIONS] = None diff --git a/gvm/protocols/gmp/_gmp224.py b/gvm/protocols/gmp/_gmp224.py index 77ac5366c..fc45bd293 100644 --- a/gvm/protocols/gmp/_gmp224.py +++ b/gvm/protocols/gmp/_gmp224.py @@ -127,15 +127,13 @@ def __init__(self, *args, **kwargs): Args: connection: Connection to use to talk with the remote daemon. See :mod:`gvm.connections` for possible connection types. - transform: Optional transform `callable`_ to convert response data. + transform: Optional transform `callable `_ + to convert response data. After each request the callable gets passed the plain response data which can be used to check the data and/or conversion into different representations like a xml dom. See :mod:`gvm.transforms` for existing transforms. - - .. _callable: - https://docs.python.org/3/library/functions.html#callable """ super().__init__(*args, **kwargs) self.types = to_dotted_types_dict(_TYPE_FIELDS) @@ -3141,7 +3139,7 @@ def create_schedule( *, comment: Optional[str] = None, ) -> T: - """Create a new schedule based in `iCalendar`_ data. + """Create a new schedule based in `iCalendar `_ data. Example: Requires https://pypi.org/project/icalendar/ @@ -3173,16 +3171,13 @@ def create_schedule( Args: name: Name of the new schedule - icalendar: `iCalendar`_ (RFC 5545) based data. + icalendar: `iCalendar `_ (RFC 5545) based data. timezone: Timezone to use for the icalendar events e.g Europe/Berlin. If the datetime values in the icalendar data are missing timezone information this timezone gets applied. Otherwise the datetime values from the icalendar data are displayed in this timezone comment: Comment on schedule. - - .. _iCalendar: - https://tools.ietf.org/html/rfc5545 """ return self._send_request_and_transform_response( Schedules.create_schedule( @@ -3255,16 +3250,14 @@ def modify_schedule( Args: schedule_id: UUID of the schedule to be modified name: Name of the schedule - icalendar: `iCalendar`_ (RFC 5545) based data. + icalendar: `iCalendar `_ + (RFC 5545) based data. timezone: Timezone to use for the icalendar events e.g Europe/Berlin. If the datetime values in the icalendar data are missing timezone information this timezone gets applied. Otherwise the datetime values from the icalendar data are displayed in this timezone comment: Comment on schedule. - - .. _iCalendar: - https://tools.ietf.org/html/rfc5545 """ return self._send_request_and_transform_response( Schedules.modify_schedule( diff --git a/gvm/protocols/gmp/_gmp225.py b/gvm/protocols/gmp/_gmp225.py index d43f75106..747a801c7 100644 --- a/gvm/protocols/gmp/_gmp225.py +++ b/gvm/protocols/gmp/_gmp225.py @@ -37,15 +37,13 @@ def __init__(self, *args, **kwargs): Args: connection: Connection to use to talk with the remote daemon. See :mod:`gvm.connections` for possible connection types. - transform: Optional transform `callable`_ to convert response data. + transform: Optional transform `callable `_ + to convert response data. After each request the callable gets passed the plain response data which can be used to check the data and/or conversion into different representations like a xml dom. See :mod:`gvm.transforms` for existing transforms. - - .. _callable: - https://docs.python.org/3/library/functions.html#callable """ super().__init__(*args, **kwargs) diff --git a/gvm/protocols/gmp/_gmp226.py b/gvm/protocols/gmp/_gmp226.py index cad24f905..28d9436e7 100644 --- a/gvm/protocols/gmp/_gmp226.py +++ b/gvm/protocols/gmp/_gmp226.py @@ -45,15 +45,12 @@ def __init__(self, *args, **kwargs): Args: connection: Connection to use to talk with the remote daemon. See :mod:`gvm.connections` for possible connection types. - transform: Optional transform `callable`_ to convert response data. + transform: Optional transform `callable `_ to convert response data. After each request the callable gets passed the plain response data which can be used to check the data and/or conversion into different representations like a xml dom. See :mod:`gvm.transforms` for existing transforms. - - .. _callable: - https://docs.python.org/3/library/functions.html#callable """ super().__init__(*args, **kwargs) diff --git a/gvm/protocols/next.py b/gvm/protocols/next.py index 711aaf477..ba0372179 100644 --- a/gvm/protocols/next.py +++ b/gvm/protocols/next.py @@ -7,7 +7,7 @@ This module exposes the latest supported protocols of GVM including versions not yet released as stable. -The provided Gmp class implements the latest `Greenbone Management Protocol`. +The provided Gmp class implements the latest Greenbone Management Protocol. The provided Osp class implements the latest Open Scanner Protocol. For details about the possible supported protocol versions please take a look at @@ -16,9 +16,6 @@ Exports: - :py:class:`gvm.protocols.gmp.GMPv227` - :py:class:`gvm.protocols.ospv1.Osp` - -.. _Greenbone Management Protocol: - https://docs.greenbone.net/API/GMP/gmp.html """ from .gmp import ( diff --git a/poetry.lock b/poetry.lock index ae50b8080..cf96797fb 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 2.1.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 2.1.2 and should not be changed by hand. [[package]] name = "alabaster" @@ -468,7 +468,7 @@ description = "Cross-platform colored terminal text." optional = false python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7" groups = ["dev"] -markers = "platform_system == \"Windows\" or sys_platform == \"win32\"" +markers = "sys_platform == \"win32\" or platform_system == \"Windows\"" files = [ {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"}, {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"}, @@ -823,6 +823,7 @@ description = "Read metadata from Python packages" optional = false python-versions = ">=3.9" groups = ["dev"] +markers = "python_version < \"3.10\"" files = [ {file = "importlib_metadata-8.7.0-py3-none-any.whl", hash = "sha256:e5dd1551894c77868a30651cef00984d50e1002d06942a7101d34870c5f02afd"}, {file = "importlib_metadata-8.7.0.tar.gz", hash = "sha256:d13b81ad223b890aa16c5471f2ac3056cf76c5f10f82d6f9292f0b415f389000"}, @@ -1115,6 +1116,27 @@ files = [ {file = "markupsafe-3.0.2.tar.gz", hash = "sha256:ee55d3edf80167e48ea11a923c7386f4669df67d7994554387f84e7d8b0a2bf0"}, ] +[[package]] +name = "mdit-py-plugins" +version = "0.4.2" +description = "Collection of plugins for markdown-it-py" +optional = false +python-versions = ">=3.8" +groups = ["dev"] +markers = "python_version >= \"3.10\"" +files = [ + {file = "mdit_py_plugins-0.4.2-py3-none-any.whl", hash = "sha256:0c673c3f889399a33b95e88d2f0d111b4447bdfea7f237dab2d488f459835636"}, + {file = "mdit_py_plugins-0.4.2.tar.gz", hash = "sha256:5f2cd1fdb606ddf152d37ec30e46101a60512bc0e5fa1a7002c36647b09e26b5"}, +] + +[package.dependencies] +markdown-it-py = ">=1.0.0,<4.0.0" + +[package.extras] +code-style = ["pre-commit"] +rtd = ["myst-parser", "sphinx-book-theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + [[package]] name = "mdurl" version = "0.1.2" @@ -1193,6 +1215,34 @@ files = [ {file = "mypy_extensions-1.1.0.tar.gz", hash = "sha256:52e68efc3284861e772bbcd66823fde5ae21fd2fdb51c62a211403730b916558"}, ] +[[package]] +name = "myst-parser" +version = "4.0.1" +description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser," +optional = false +python-versions = ">=3.10" +groups = ["dev"] +markers = "python_version >= \"3.10\"" +files = [ + {file = "myst_parser-4.0.1-py3-none-any.whl", hash = "sha256:9134e88959ec3b5780aedf8a99680ea242869d012e8821db3126d427edc9c95d"}, + {file = "myst_parser-4.0.1.tar.gz", hash = "sha256:5cfea715e4f3574138aecbf7d54132296bfd72bb614d31168f48c477a830a7c4"}, +] + +[package.dependencies] +docutils = ">=0.19,<0.22" +jinja2 = "*" +markdown-it-py = ">=3.0,<4.0" +mdit-py-plugins = ">=0.4.1,<1.0" +pyyaml = "*" +sphinx = ">=7,<9" + +[package.extras] +code-style = ["pre-commit (>=4.0,<5.0)"] +linkify = ["linkify-it-py (>=2.0,<3.0)"] +rtd = ["ipython", "sphinx (>=7)", "sphinx-autodoc2 (>=0.5.0,<0.6.0)", "sphinx-book-theme (>=1.1,<2.0)", "sphinx-copybutton", "sphinx-design", "sphinx-pyscript", "sphinx-tippy (>=0.4.3)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.9.0,<0.10.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"] +testing = ["beautifulsoup4", "coverage[toml]", "defusedxml", "pygments (<2.19)", "pytest (>=8,<9)", "pytest-cov", "pytest-param-files (>=0.6.0,<0.7.0)", "pytest-regressions", "sphinx-pytest"] +testing-docutils = ["pygments", "pytest (>=8,<9)", "pytest-param-files (>=0.6.0,<0.7.0)"] + [[package]] name = "packaging" version = "25.0" @@ -1258,14 +1308,14 @@ type = ["mypy (>=1.14.1)"] [[package]] name = "pontos" -version = "25.3.3" +version = "25.4.0" description = "Common utilities and tools maintained by Greenbone Networks" optional = false python-versions = "<4.0,>=3.9" groups = ["dev"] files = [ - {file = "pontos-25.3.3-py3-none-any.whl", hash = "sha256:99e52a848503a9ae9be735850d9767002bce4311d222d4af5d8d48049648c1b8"}, - {file = "pontos-25.3.3.tar.gz", hash = "sha256:fdcda184536727a185922c862ce7e3913213e698f6e9a3d5aa76605235855769"}, + {file = "pontos-25.4.0-py3-none-any.whl", hash = "sha256:3559c2066bd8c8dda1360cbe05b29af41ac2e949e684a0196f4ca040a192e912"}, + {file = "pontos-25.4.0.tar.gz", hash = "sha256:04f19a044fba60c6a72116b463de1d8fba17e688763b52b2fce3b3a935515fef"}, ] [package.dependencies] @@ -1349,6 +1399,70 @@ files = [ [package.dependencies] six = ">=1.5" +[[package]] +name = "pyyaml" +version = "6.0.2" +description = "YAML parser and emitter for Python" +optional = false +python-versions = ">=3.8" +groups = ["dev"] +markers = "python_version >= \"3.10\"" +files = [ + {file = "PyYAML-6.0.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:0a9a2848a5b7feac301353437eb7d5957887edbf81d56e903999a75a3d743086"}, + {file = "PyYAML-6.0.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:29717114e51c84ddfba879543fb232a6ed60086602313ca38cce623c1d62cfbf"}, + {file = "PyYAML-6.0.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8824b5a04a04a047e72eea5cec3bc266db09e35de6bdfe34c9436ac5ee27d237"}, + {file = "PyYAML-6.0.2-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7c36280e6fb8385e520936c3cb3b8042851904eba0e58d277dca80a5cfed590b"}, + {file = "PyYAML-6.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ec031d5d2feb36d1d1a24380e4db6d43695f3748343d99434e6f5f9156aaa2ed"}, + {file = "PyYAML-6.0.2-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:936d68689298c36b53b29f23c6dbb74de12b4ac12ca6cfe0e047bedceea56180"}, + {file = "PyYAML-6.0.2-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:23502f431948090f597378482b4812b0caae32c22213aecf3b55325e049a6c68"}, + {file = "PyYAML-6.0.2-cp310-cp310-win32.whl", hash = "sha256:2e99c6826ffa974fe6e27cdb5ed0021786b03fc98e5ee3c5bfe1fd5015f42b99"}, + {file = "PyYAML-6.0.2-cp310-cp310-win_amd64.whl", hash = "sha256:a4d3091415f010369ae4ed1fc6b79def9416358877534caf6a0fdd2146c87a3e"}, + {file = "PyYAML-6.0.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:cc1c1159b3d456576af7a3e4d1ba7e6924cb39de8f67111c735f6fc832082774"}, + {file = "PyYAML-6.0.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:1e2120ef853f59c7419231f3bf4e7021f1b936f6ebd222406c3b60212205d2ee"}, + {file = "PyYAML-6.0.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5d225db5a45f21e78dd9358e58a98702a0302f2659a3c6cd320564b75b86f47c"}, + {file = "PyYAML-6.0.2-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5ac9328ec4831237bec75defaf839f7d4564be1e6b25ac710bd1a96321cc8317"}, + {file = "PyYAML-6.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3ad2a3decf9aaba3d29c8f537ac4b243e36bef957511b4766cb0057d32b0be85"}, + {file = "PyYAML-6.0.2-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:ff3824dc5261f50c9b0dfb3be22b4567a6f938ccce4587b38952d85fd9e9afe4"}, + {file = "PyYAML-6.0.2-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:797b4f722ffa07cc8d62053e4cff1486fa6dc094105d13fea7b1de7d8bf71c9e"}, + {file = "PyYAML-6.0.2-cp311-cp311-win32.whl", hash = "sha256:11d8f3dd2b9c1207dcaf2ee0bbbfd5991f571186ec9cc78427ba5bd32afae4b5"}, + {file = "PyYAML-6.0.2-cp311-cp311-win_amd64.whl", hash = "sha256:e10ce637b18caea04431ce14fabcf5c64a1c61ec9c56b071a4b7ca131ca52d44"}, + {file = "PyYAML-6.0.2-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:c70c95198c015b85feafc136515252a261a84561b7b1d51e3384e0655ddf25ab"}, + {file = "PyYAML-6.0.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ce826d6ef20b1bc864f0a68340c8b3287705cae2f8b4b1d932177dcc76721725"}, + {file = "PyYAML-6.0.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1f71ea527786de97d1a0cc0eacd1defc0985dcf6b3f17bb77dcfc8c34bec4dc5"}, + {file = "PyYAML-6.0.2-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9b22676e8097e9e22e36d6b7bda33190d0d400f345f23d4065d48f4ca7ae0425"}, + {file = "PyYAML-6.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:80bab7bfc629882493af4aa31a4cfa43a4c57c83813253626916b8c7ada83476"}, + {file = "PyYAML-6.0.2-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:0833f8694549e586547b576dcfaba4a6b55b9e96098b36cdc7ebefe667dfed48"}, + {file = "PyYAML-6.0.2-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8b9c7197f7cb2738065c481a0461e50ad02f18c78cd75775628afb4d7137fb3b"}, + {file = "PyYAML-6.0.2-cp312-cp312-win32.whl", hash = "sha256:ef6107725bd54b262d6dedcc2af448a266975032bc85ef0172c5f059da6325b4"}, + {file = "PyYAML-6.0.2-cp312-cp312-win_amd64.whl", hash = "sha256:7e7401d0de89a9a855c839bc697c079a4af81cf878373abd7dc625847d25cbd8"}, + {file = "PyYAML-6.0.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:efdca5630322a10774e8e98e1af481aad470dd62c3170801852d752aa7a783ba"}, + {file = "PyYAML-6.0.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:50187695423ffe49e2deacb8cd10510bc361faac997de9efef88badc3bb9e2d1"}, + {file = "PyYAML-6.0.2-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0ffe8360bab4910ef1b9e87fb812d8bc0a308b0d0eef8c8f44e0254ab3b07133"}, + {file = "PyYAML-6.0.2-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:17e311b6c678207928d649faa7cb0d7b4c26a0ba73d41e99c4fff6b6c3276484"}, + {file = "PyYAML-6.0.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:70b189594dbe54f75ab3a1acec5f1e3faa7e8cf2f1e08d9b561cb41b845f69d5"}, + {file = "PyYAML-6.0.2-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:41e4e3953a79407c794916fa277a82531dd93aad34e29c2a514c2c0c5fe971cc"}, + {file = "PyYAML-6.0.2-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:68ccc6023a3400877818152ad9a1033e3db8625d899c72eacb5a668902e4d652"}, + {file = "PyYAML-6.0.2-cp313-cp313-win32.whl", hash = "sha256:bc2fa7c6b47d6bc618dd7fb02ef6fdedb1090ec036abab80d4681424b84c1183"}, + {file = "PyYAML-6.0.2-cp313-cp313-win_amd64.whl", hash = "sha256:8388ee1976c416731879ac16da0aff3f63b286ffdd57cdeb95f3f2e085687563"}, + {file = "PyYAML-6.0.2-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:24471b829b3bf607e04e88d79542a9d48bb037c2267d7927a874e6c205ca7e9a"}, + {file = "PyYAML-6.0.2-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d7fded462629cfa4b685c5416b949ebad6cec74af5e2d42905d41e257e0869f5"}, + {file = "PyYAML-6.0.2-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d84a1718ee396f54f3a086ea0a66d8e552b2ab2017ef8b420e92edbc841c352d"}, + {file = "PyYAML-6.0.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9056c1ecd25795207ad294bcf39f2db3d845767be0ea6e6a34d856f006006083"}, + {file = "PyYAML-6.0.2-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:82d09873e40955485746739bcb8b4586983670466c23382c19cffecbf1fd8706"}, + {file = "PyYAML-6.0.2-cp38-cp38-win32.whl", hash = "sha256:43fa96a3ca0d6b1812e01ced1044a003533c47f6ee8aca31724f78e93ccc089a"}, + {file = "PyYAML-6.0.2-cp38-cp38-win_amd64.whl", hash = "sha256:01179a4a8559ab5de078078f37e5c1a30d76bb88519906844fd7bdea1b7729ff"}, + {file = "PyYAML-6.0.2-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:688ba32a1cffef67fd2e9398a2efebaea461578b0923624778664cc1c914db5d"}, + {file = "PyYAML-6.0.2-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:a8786accb172bd8afb8be14490a16625cbc387036876ab6ba70912730faf8e1f"}, + {file = "PyYAML-6.0.2-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d8e03406cac8513435335dbab54c0d385e4a49e4945d2909a581c83647ca0290"}, + {file = "PyYAML-6.0.2-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f753120cb8181e736c57ef7636e83f31b9c0d1722c516f7e86cf15b7aa57ff12"}, + {file = "PyYAML-6.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3b1fdb9dc17f5a7677423d508ab4f243a726dea51fa5e70992e59a7411c89d19"}, + {file = "PyYAML-6.0.2-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:0b69e4ce7a131fe56b7e4d770c67429700908fc0752af059838b1cfb41960e4e"}, + {file = "PyYAML-6.0.2-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:a9f8c2e67970f13b16084e04f134610fd1d374bf477b17ec1599185cf611d725"}, + {file = "PyYAML-6.0.2-cp39-cp39-win32.whl", hash = "sha256:6395c297d42274772abc367baaa79683958044e5d3835486c16da75d2a694631"}, + {file = "PyYAML-6.0.2-cp39-cp39-win_amd64.whl", hash = "sha256:39693e1f8320ae4f43943590b49779ffb98acb81f788220ea932a6b6c51004d8"}, + {file = "pyyaml-6.0.2.tar.gz", hash = "sha256:d584d9ec91ad65861cc08d42e834324ef890a082e591037abe114850ff7bbc3e"}, +] + [[package]] name = "requests" version = "2.32.3" @@ -1756,6 +1870,7 @@ description = "Backport of pathlib-compatible object wrapper for zip files" optional = false python-versions = ">=3.9" groups = ["dev"] +markers = "python_version < \"3.10\"" files = [ {file = "zipp-3.21.0-py3-none-any.whl", hash = "sha256:ac1bbe05fd2991f160ebce24ffbac5f6d11d83dc90891255885223d42b3cd931"}, {file = "zipp-3.21.0.tar.gz", hash = "sha256:2c9958f6430a2040341a52eb608ed6dd93ef4392e02ffe219417c1b28b5dd1f4"}, @@ -1772,4 +1887,4 @@ type = ["pytest-mypy"] [metadata] lock-version = "2.1" python-versions = "^3.9.2" -content-hash = "95612b9c0fab79c11650ea68c99433fb4927a139be5bd0202bd246979d70c785" +content-hash = "5a19a437b167240b91207d5d281549beffcb24ee414425a88d3b6371bf7c96ad" diff --git a/pyproject.toml b/pyproject.toml index 2ff9c257f..4f7be4f49 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,6 +45,7 @@ furo = ">=2022.6.21" lxml-stubs = "^0.5.1" types-paramiko = "^3.4.0.20240205" git-cliff = "^2.8.0" +myst-parser = { version = "^4.0.0", python = "^3.10" } [tool.black] line-length = 80