python-gvm 24.3.0__tar.gz → 24.7.0__tar.gz

python_gvm-24.7.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.1
+Name: python-gvm
+Version: 24.7.0
+Summary: Library to communicate with remote servers over GMP or OSP
+Home-page: https://github.com/greenbone/python-gvm/
+License: GPL-3.0-or-later
+Author: Greenbone AG
+Author-email: info@greenbone.net
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: lxml (>=4.5.0)
+Requires-Dist: paramiko (>=2.7.1)
+Project-URL: Documentation, https://greenbone.github.io/python-gvm/
+Project-URL: Repository, https://github.com/greenbone/python-gvm/
+Description-Content-Type: text/markdown
+
+![Greenbone Logo](https://www.greenbone.net/wp-content/uploads/gb_new-logo_horizontal_rgb_small.png)
+
+# Greenbone Vulnerability Management Python Library <!-- omit in toc -->
+
+[![GitHub releases](https://img.shields.io/github/release-pre/greenbone/python-gvm.svg)](https://github.com/greenbone/python-gvm/releases)
+[![PyPI release](https://img.shields.io/pypi/v/python-gvm.svg)](https://pypi.org/project/python-gvm/)
+[![code test coverage](https://codecov.io/gh/greenbone/python-gvm/branch/main/graph/badge.svg)](https://codecov.io/gh/greenbone/python-gvm)
+[![Build and test](https://github.com/greenbone/python-gvm/actions/workflows/ci.yml/badge.svg)](https://github.com/greenbone/python-gvm/actions/workflows/ci.yml)
+
+The Greenbone Vulnerability Management Python API library (**python-gvm**) is a
+collection of APIs that help with remote controlling Greenbone Community Edition
+installations and Greenbone Enterprise Appliances. The library essentially
+abstracts accessing the communication protocols Greenbone Management Protocol
+(GMP) and Open Scanner Protocol (OSP).
+
+## Table of Contents <!-- omit in toc -->
+
+- [Documentation](#documentation)
+- [Installation](#installation)
+  - [Version](#version)
+  - [Requirements](#requirements)
+  - [Install using pip](#install-using-pip)
+- [Example](#example)
+- [Support](#support)
+- [Maintainer](#maintainer)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Documentation
+
+The documentation for python-gvm can be found at
+[https://greenbone.github.io/python-gvm/](https://greenbone.github.io/python-gvm/).
+Please always take a look at the documentation for further details. This
+**README** just gives you a short overview.
+
+## Installation
+
+### Version
+
+Please consider to always use the **newest** version of `gvm-tools` and `python-gvm`.
+We frequently update this projects to add features and keep them free from bugs.
+This is why installing `python-gvm` using pip is recommended.
+
+> [!IMPORTANT]
+> To use `python-gvm` with GMP version of 7, 8 or 9 you must use a release version
+> that is `<21.5`. In the `21.5` release the support of these versions has been
+> dropped.
+
+> [!IMPORTANT]
+> To use `python-gvm` with  GMP version 20.8 or 21.4 you must use a release version
+> that is `<24.6`. In the `24.6` release the support of these versions has been
+> dropped.
+
+### Requirements
+
+Python 3.9 and later is supported.
+
+### Install using pip
+
+You can install the latest stable release of python-gvm from the Python Package
+Index using [pip](https://pip.pypa.io/):
+
+    python3 -m pip install --user python-gvm
+
+## Example
+
+```python3
+from gvm.connections import UnixSocketConnection
+from gvm.protocols.gmp import Gmp
+from gvm.transforms import EtreeTransform
+from gvm.xml import pretty_print
+
+connection = UnixSocketConnection()
+transform = EtreeTransform()
+
+with Gmp(connection, transform=transform) as gmp:
+    # Retrieve GMP version supported by the remote daemon
+    version = gmp.get_version()
+
+    # Prints the XML in beautiful form
+    pretty_print(version)
+
+    # Login
+    gmp.authenticate('foo', 'bar')
+
+    # Retrieve all tasks
+    tasks = gmp.get_tasks()
+
+    # Get names of tasks
+    task_names = tasks.xpath('task/name/text()')
+    pretty_print(task_names)
+```
+
+## Support
+
+For any question on the usage of python-gvm please use the
+[Greenbone Community Forum](https://forum.greenbone.net/c/building-from-source-under-the-hood/gmp/11). If you
+found a problem with the software, please
+[create an issue](https://github.com/greenbone/python-gvm/issues)
+on GitHub.
+
+## Maintainer
+
+This project is maintained by [Greenbone AG](https://www.greenbone.net/).
+
+## Contributing
+
+Your contributions are highly appreciated. Please
+[create a pull request](https://github.com/greenbone/python-gvm/pulls) on GitHub.
+For bigger changes, please discuss it first in the
+[issues](https://github.com/greenbone/python-gvm/issues).
+
+For development you should use [poetry](https://python-poetry.org)
+to keep you python packages separated in different environments. First install
+poetry via pip
+
+```shell
+python3 -m pip install --user poetry
+```
+
+Afterwards run
+
+```shell
+poetry install
+```
+
+in the checkout directory of python-gvm (the directory containing the
+`pyproject.toml` file) to install all dependencies including the packages only
+required for development.
+
+The python-gvm repository uses [autohooks](https://github.com/greenbone/autohooks)
+to apply linting and auto formatting via git hooks. Please ensure the git hooks
+are active.
+
+    $ poetry install
+    $ poetry run autohooks activate --force
+
+## License
+
+Copyright (C) 2017-2024 [Greenbone AG](https://www.greenbone.net/)
+
+Licensed under the [GNU General Public License v3.0 or later](LICENSE).
+

python_gvm-24.7.0/README.md

@@ -0,0 +1,142 @@
+![Greenbone Logo](https://www.greenbone.net/wp-content/uploads/gb_new-logo_horizontal_rgb_small.png)
+
+# Greenbone Vulnerability Management Python Library <!-- omit in toc -->
+
+[![GitHub releases](https://img.shields.io/github/release-pre/greenbone/python-gvm.svg)](https://github.com/greenbone/python-gvm/releases)
+[![PyPI release](https://img.shields.io/pypi/v/python-gvm.svg)](https://pypi.org/project/python-gvm/)
+[![code test coverage](https://codecov.io/gh/greenbone/python-gvm/branch/main/graph/badge.svg)](https://codecov.io/gh/greenbone/python-gvm)
+[![Build and test](https://github.com/greenbone/python-gvm/actions/workflows/ci.yml/badge.svg)](https://github.com/greenbone/python-gvm/actions/workflows/ci.yml)
+
+The Greenbone Vulnerability Management Python API library (**python-gvm**) is a
+collection of APIs that help with remote controlling Greenbone Community Edition
+installations and Greenbone Enterprise Appliances. The library essentially
+abstracts accessing the communication protocols Greenbone Management Protocol
+(GMP) and Open Scanner Protocol (OSP).
+
+## Table of Contents <!-- omit in toc -->
+
+- [Documentation](#documentation)
+- [Installation](#installation)
+  - [Version](#version)
+  - [Requirements](#requirements)
+  - [Install using pip](#install-using-pip)
+- [Example](#example)
+- [Support](#support)
+- [Maintainer](#maintainer)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Documentation
+
+The documentation for python-gvm can be found at
+[https://greenbone.github.io/python-gvm/](https://greenbone.github.io/python-gvm/).
+Please always take a look at the documentation for further details. This
+**README** just gives you a short overview.
+
+## Installation
+
+### Version
+
+Please consider to always use the **newest** version of `gvm-tools` and `python-gvm`.
+We frequently update this projects to add features and keep them free from bugs.
+This is why installing `python-gvm` using pip is recommended.
+
+> [!IMPORTANT]
+> To use `python-gvm` with GMP version of 7, 8 or 9 you must use a release version
+> that is `<21.5`. In the `21.5` release the support of these versions has been
+> dropped.
+
+> [!IMPORTANT]
+> To use `python-gvm` with  GMP version 20.8 or 21.4 you must use a release version
+> that is `<24.6`. In the `24.6` release the support of these versions has been
+> dropped.
+
+### Requirements
+
+Python 3.9 and later is supported.
+
+### Install using pip
+
+You can install the latest stable release of python-gvm from the Python Package
+Index using [pip](https://pip.pypa.io/):
+
+    python3 -m pip install --user python-gvm
+
+## Example
+
+```python3
+from gvm.connections import UnixSocketConnection
+from gvm.protocols.gmp import Gmp
+from gvm.transforms import EtreeTransform
+from gvm.xml import pretty_print
+
+connection = UnixSocketConnection()
+transform = EtreeTransform()
+
+with Gmp(connection, transform=transform) as gmp:
+    # Retrieve GMP version supported by the remote daemon
+    version = gmp.get_version()
+
+    # Prints the XML in beautiful form
+    pretty_print(version)
+
+    # Login
+    gmp.authenticate('foo', 'bar')
+
+    # Retrieve all tasks
+    tasks = gmp.get_tasks()
+
+    # Get names of tasks
+    task_names = tasks.xpath('task/name/text()')
+    pretty_print(task_names)
+```
+
+## Support
+
+For any question on the usage of python-gvm please use the
+[Greenbone Community Forum](https://forum.greenbone.net/c/building-from-source-under-the-hood/gmp/11). If you
+found a problem with the software, please
+[create an issue](https://github.com/greenbone/python-gvm/issues)
+on GitHub.
+
+## Maintainer
+
+This project is maintained by [Greenbone AG](https://www.greenbone.net/).
+
+## Contributing
+
+Your contributions are highly appreciated. Please
+[create a pull request](https://github.com/greenbone/python-gvm/pulls) on GitHub.
+For bigger changes, please discuss it first in the
+[issues](https://github.com/greenbone/python-gvm/issues).
+
+For development you should use [poetry](https://python-poetry.org)
+to keep you python packages separated in different environments. First install
+poetry via pip
+
+```shell
+python3 -m pip install --user poetry
+```
+
+Afterwards run
+
+```shell
+poetry install
+```
+
+in the checkout directory of python-gvm (the directory containing the
+`pyproject.toml` file) to install all dependencies including the packages only
+required for development.
+
+The python-gvm repository uses [autohooks](https://github.com/greenbone/autohooks)
+to apply linting and auto formatting via git hooks. Please ensure the git hooks
+are active.
+
+    $ poetry install
+    $ poetry run autohooks activate --force
+
+## License
+
+Copyright (C) 2017-2024 [Greenbone AG](https://www.greenbone.net/)
+
+Licensed under the [GNU General Public License v3.0 or later](LICENSE).

python_gvm-24.7.0/gvm/__version__.py

@@ -0,0 +1,5 @@
+# pylint: disable=invalid-name
+
+# THIS IS AN AUTOGENERATED FILE. DO NOT TOUCH!
+
+__version__ = "24.7.0"

python_gvm-24.7.0/gvm/_enum.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2024 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+from enum import Enum as PythonEnum
+from typing import Any, Optional, Type, TypeVar
+
+from gvm.errors import InvalidArgument
+
+Self = TypeVar("Self", bound="Enum")
+
+
+class Enum(PythonEnum):
+    """
+    Base class for Enums in python-gvm
+    """
+
+    @classmethod
+    def _missing_(cls: Type[Self], value: Any) -> Optional[Self]:
+        if isinstance(value, PythonEnum):
+            return cls.from_string(value.name)
+        return cls.from_string(str(value) if value else None)
+
+    @classmethod
+    def from_string(
+        cls: Type[Self],
+        value: Optional[str],
+    ) -> Optional[Self]:
+        """
+        Convert a string value into an Enum instance
+
+        If value is None or empty None is returned
+        """
+        if not value:
+            return None
+
+        try:
+            return cls[value.replace(" ", "_").upper()]
+        except KeyError:
+            raise InvalidArgument(
+                f"Invalid argument {value}. "
+                f"Allowed values are {','.join(e.name for e in cls)}."
+            ) from None
+
+    def __str__(self) -> str:
+        return self.value

python_gvm-24.7.0/gvm/connections/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2024 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from ._connection import DEFAULT_TIMEOUT, GvmConnection
+from ._debug import DebugConnection
+from ._ssh import (
+    DEFAULT_HOSTNAME,
+    DEFAULT_KNOWN_HOSTS_FILE,
+    DEFAULT_SSH_PASSWORD,
+    DEFAULT_SSH_PORT,
+    DEFAULT_SSH_USERNAME,
+    SSHConnection,
+)
+from ._tls import DEFAULT_GVM_PORT, TLSConnection
+from ._unix import DEFAULT_UNIX_SOCKET_PATH, UnixSocketConnection
+
+__all__ = (
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_UNIX_SOCKET_PATH",
+    "DEFAULT_GVM_PORT",
+    "DEFAULT_HOSTNAME",
+    "DEFAULT_KNOWN_HOSTS_FILE",
+    "DEFAULT_SSH_PASSWORD",
+    "DEFAULT_SSH_USERNAME",
+    "DEFAULT_SSH_PORT",
+    "DebugConnection",
+    "GvmConnection",
+    "SSHConnection",
+    "TLSConnection",
+    "UnixSocketConnection",
+)

python_gvm-24.7.0/gvm/connections/_connection.py

@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: 2024 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import logging
+import socket as socketlib
+from abc import ABC, abstractmethod
+from time import time
+from typing import Optional, Protocol, Union, runtime_checkable
+
+from gvm.errors import GvmError
+
+BUF_SIZE = 16 * 1024
+
+DEFAULT_TIMEOUT = 60  # in seconds
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class GvmConnection(Protocol):
+    """
+    Python `protocol <https://docs.python.org/3/library/typing.html#typing.Protocol>`_
+    for GvmConnection classes.
+    """
+
+    def connect(self) -> None:
+        """Establish a connection to a remote server"""
+
+    def disconnect(self) -> None:
+        """Send data to the connected remote server
+
+        Arguments:
+            data: Data to be send to the server. Either utf-8 encoded string or
+                bytes.
+        """
+
+    def send(self, data: bytes) -> None:
+        """Send data to the connected remote server
+
+        Args:
+            data: Data to be send to the server as bytes.
+        """
+
+    def read(self) -> bytes:
+        """Read data from the remote server
+
+        Returns:
+            data as bytes
+        """
+
+    def finish_send(self):
+        """Indicate to the remote server you are done with sending data"""
+
+
+class AbstractGvmConnection(ABC):
+    """
+    Base class for establishing a connection to a remote server daemon.
+
+    Arguments:
+        timeout: Timeout in seconds for the connection. None to
+            wait indefinitely
+    """
+
+    def __init__(self, timeout: Optional[Union[int, float]] = DEFAULT_TIMEOUT):
+        self._socket: Optional[socketlib.SocketType] = None
+        self._timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+
+    def _read(self) -> bytes:
+        if self._socket is None:
+            raise GvmError("Socket is not connected")
+
+        return self._socket.recv(BUF_SIZE)
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Establish a connection to a remote server"""
+        raise NotImplementedError
+
+    def send(self, data: bytes) -> None:
+        """Send data to the connected remote server
+
+        Args:
+            data: Data to be send to the server as bytes.
+        """
+        if self._socket is None:
+            raise GvmError("Socket is not connected")
+
+        self._socket.sendall(data)
+
+    def read(self) -> bytes:
+        """Read data from the remote server
+
+        Returns:
+            data as bytes
+        """
+        break_timeout = (
+            time() + self._timeout if self._timeout is not None else None
+        )
+
+        data = self._read()
+
+        if not data:
+            # Connection was closed by server
+            raise GvmError("Remote closed the connection")
+
+        if break_timeout and time() > break_timeout:
+            raise GvmError("Timeout while reading the response")
+
+        return data
+
+    def disconnect(self) -> None:
+        """Disconnect and close the connection to the remote server"""
+        try:
+            if self._socket is not None:
+                self._socket.close()
+        except OSError as e:
+            logger.debug("Connection closing error: %s", e)
+
+    def finish_send(self):
+        """Indicate to the remote server you are done with sending data"""
+        if self._socket is not None:
+            # shutdown socket for sending. only allow reading data afterwards
+            self._socket.shutdown(socketlib.SHUT_WR)

python_gvm-24.7.0/gvm/connections/_debug.py

@@ -0,0 +1,74 @@
+# SPDX-FileCopyrightText: 2024 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import logging
+
+from ._connection import GvmConnection
+
+logger = logging.getLogger("gvm.connections.debug")
+
+
+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
+    <https://docs.python.org/3/howto/logging.html#logging-basic-tutorial>`_
+    for further details.
+
+    Example:
+
+    .. code-block:: python
+
+        import logging
+
+        logging.basicConfig(level=logging.DEBUG)
+
+        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):
+        """
+        Create a new DebugConnection instance.
+
+        Args:
+            connection: GvmConnection to observe
+        """
+        self._connection = connection
+
+    def read(self) -> bytes:
+        data = self._connection.read()
+
+        logger.debug("Read %s characters. Data %r", len(data), data)
+
+        self.last_read_data = data
+        return data
+
+    def send(self, data: bytes) -> None:
+        self.last_send_data = data
+
+        logger.debug("Sending %s characters. Data %r", len(data), data)
+
+        return self._connection.send(data)
+
+    def connect(self) -> None:
+        logger.debug("Connecting")
+
+        return self._connection.connect()
+
+    def disconnect(self) -> None:
+        logger.debug("Disconnecting")
+
+        return self._connection.disconnect()
+
+    def finish_send(self) -> None:
+        logger.debug("Finish send")
+
+        self._connection.finish_send()