diff --git a/docs/conf.py b/docs/conf.py index 38326c37..09fe9c8d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,15 +17,15 @@ import os import sys -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath("..")) import gvmtools # -- Project information ----------------------------------------------------- -project = 'gvm-tools' -copyright = '2018-2020, Greenbone AG' -author = 'Greenbone AG' +project = "gvm-tools" +copyright = "2018-2023, Greenbone AG" +author = "Greenbone AG" version = gvmtools.get_version() release = version @@ -41,22 +41,22 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.githubpages', - 'sphinx.ext.napoleon', + "sphinx.ext.autodoc", + "sphinx.ext.githubpages", + "sphinx.ext.napoleon", + "myst_parser", ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +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 = [".md", ".rst"] # The master toctree document. -master_doc = 'index' +master_doc = "index" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -83,7 +83,7 @@ html_css_files = ["custom.css"] html_logo = "_static/logo.svg" -html_static_path = ['_static'] +html_static_path = ["_static"] repo_url = "https://github.com/greenbone/gvm-tools/" @@ -139,7 +139,7 @@ # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'gvm-toolsdoc' +htmlhelp_basename = "gvm-toolsdoc" # -- Options for LaTeX output ------------------------------------------------ latex_elements = { @@ -162,10 +162,10 @@ latex_documents = [ ( master_doc, - 'gvm-tools.tex', - 'gvm-tools Documentation', - 'Greenbone AG', - 'manual', + "gvm-tools.tex", + "gvm-tools Documentation", + "Greenbone AG", + "manual", ) ] @@ -174,7 +174,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [(master_doc, 'gvm-tools', 'gvm-tools Documentation', [author], 1)] +man_pages = [(master_doc, "gvm-tools", "gvm-tools Documentation", [author], 1)] # -- Options for Texinfo output ---------------------------------------------- @@ -185,12 +185,12 @@ texinfo_documents = [ ( master_doc, - 'gvm-tools', - 'gvm-tools Documentation', + "gvm-tools", + "gvm-tools Documentation", author, - 'gvm-tools', - 'One line description of project.', - 'Miscellaneous', + "gvm-tools", + "One line description of project.", + "Miscellaneous", ) ] @@ -210,7 +210,7 @@ # epub_uid = '' # A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] +epub_exclude_files = ["search.html"] # -- Extension configuration ------------------------------------------------- diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 00000000..74e41ff1 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,172 @@ +(config)= + +# Configuration + +```{versionchanged} 2.0 +``` + +By default, {program}`gvm-tools` {ref}`programs ` are evaluating the +{file}`~/.config/gvm-tools.conf` +[ini style](https://docs.python.org/3/library/configparser.html#supported-ini-file-structure) +config file since version 2.0. The name of the used config file can be set using the +{command}`-c/--config` command line switch. + +## Settings + +The configuration file consists of sections, each led by a {code}`[section]` +header, followed by key/value entries separated by a {code}`=` character. +Whitespaces between key and value are ignored, i.e., {code}`key = value` is the +same as {code}`key=value`. + +Currently five sections are evaluated: + +- {ref}`Main section ` +- {ref}`GMP section ` +- {ref}`Socket section ` +- {ref}`TLS section ` +- {ref}`SSH section ` + +(main-section)= + +```{rubric} Main Section +``` + +The main section allows changing the default connection timeout besides +defining variables for {ref}`interpolation`. + +```ini +[main] +timeout = 60 +``` + +(gmp-section)= + +```{rubric} GMP Section +``` + +The GMP section allows setting the default user name and password for +[Greenbone Management Protocol (GMP)](https://community.greenbone.net/t/about-the-greenbone-management-protocol-gmp-category/83) +based communication. + +```ini +[gmp] +username=gmpuser +password=gmppassword +``` + +(socket-config-section)= + +```{rubric} Socket Section +``` + +This section is only relevant if the {ref}`socket connection type +` is used. + +The socket section allows setting the default path to the Unix Domain socket of +{term}`gvmd`. It must not be confused with the socket path to the redis server +used by {term}`openvas`. + +```ini +[unixsocket] +socketpath=/run/gvmd/gvmd.sock +``` + +(tls-config-section)= + +```{rubric} TLS Section +``` + +This section is only relevant if the {ref}`TLS connection type +` is used. + +The TLS section allows setting the default port, TLS certificate file, TLS key +file and TLS certificate authority file. + +```ini +[tls] +port=1234 +certfile=/path/to/tls.cert +keyfile=/path/to/tls.key +cafile=/path/to/tls.ca +``` + +(ssh-config-section)= + +```{rubric} SSH Section +``` + +This section is only relevant if the {ref}`SSH connection type ` +is used. + +The SSH section allows setting the default SSH port, SSH user name and SSH +password. + +```ini +[ssh] +username=sshuser +password=sshpassword +port=2222 +``` + +```{rubric} Comments +``` + +Configuration files may also contain comments by using the special character +{code}`#`. A comment should be placed on a separate line above or below the +setting. + +```ini +[main] +# connection timeout of 120 seconds +timeout=120 +``` + +(interpolation)= + +```{rubric} Interpolation +``` + +The configuration file also supports the [interpolation of values](https://docs.python.org/3/library/configparser.html#interpolation-of-values). +It is possible to define values in the {code}`[main]` section and reference +them via a {code}`%()s` syntax. Additionally, values of the +same section can be referenced. + +```ini +[main] +my_first_name=John + +[gmp] +my_last_name=Smith +username=%(my_first_name)s%(my_last_name)s +``` + +Using this syntax will set the gmp user name setting to `JohnSmith`. + +## Example + +Full example configuration: + +```ini +[main] +# increased timeout to 5 minutes +timeout = 300 +tls_path=/data/tls +default_user=johnsmith + +[gmp] +username=%(default_user)s +password=choo4Gahdi2e + +[unixsocket] +socketpath=/run/gvmd/gvmd.sock + +[tls] +port=1234 +certfile=%(tls_path)s/tls.cert +keyfile=%(tls_path)s/tls.key +cafile=%(tls_path)s/tls.ca + +[ssh] +username=%(default_user)s +password=Poa8Ies1iJee +``` diff --git a/docs/config.rst b/docs/config.rst deleted file mode 100644 index acdc984b..00000000 --- a/docs/config.rst +++ /dev/null @@ -1,174 +0,0 @@ -.. _config: - -Configuration -============= - -.. versionchanged:: 2.0 - -By default, :program:`gvm-tools` :ref:`programs ` are evaluating the -:file:`~/.config/gvm-tools.conf` -`ini style `_ -config file since version 2.0. The name of the used config file can be set using the -:command:`-c/--config` command line switch. - -Settings --------- - -The configuration file consists of sections, each led by a :code:`[section]` -header, followed by key/value entries separated by a :code:`=` character. -Whitespaces between key and value are ignored, i.e., :code:`key = value` is the -same as :code:`key=value`. - -Currently five sections are evaluated: - -* :ref:`Main section ` -* :ref:`GMP section ` -* :ref:`Socket section ` -* :ref:`TLS section ` -* :ref:`SSH section ` - -.. _main_section: - -.. rubric:: Main Section - -The main section allows changing the default connection timeout besides -defining variables for :ref:`interpolation`. - -.. code-block:: ini - - [main] - timeout = 60 - - -.. _gmp_section: - -.. rubric:: GMP Section - -The GMP section allows setting the default user name and password for -`Greenbone Management Protocol (GMP) -`_ -based communication. - -.. code-block:: ini - - [gmp] - username=gmpuser - password=gmppassword - - -.. _socket_config_section: - -.. rubric:: Socket Section - -This section is only relevant if the :ref:`socket connection type -` is used. - -The socket section allows setting the default path to the Unix Domain socket of -:term:`gvmd`. It must not be confused with the socket path to the redis server -used by :term:`openvas`. - -.. code-block:: ini - - [unixsocket] - socketpath=/run/gvmd/gvmd.sock - - -.. _tls_config_section: - -.. rubric:: TLS Section - -This section is only relevant if the :ref:`TLS connection type -` is used. - -The TLS section allows setting the default port, TLS certificate file, TLS key -file and TLS certificate authority file. - -.. code-block:: ini - - [tls] - port=1234 - certfile=/path/to/tls.cert - keyfile=/path/to/tls.key - cafile=/path/to/tls.ca - - -.. _ssh_config_section: - -.. rubric:: SSH Section - -This section is only relevant if the :ref:`SSH connection type ` -is used. - -The SSH section allows setting the default SSH port, SSH user name and SSH -password. - -.. code-block:: ini - - [ssh] - username=sshuser - password=sshpassword - port=2222 - -.. rubric:: Comments - -Configuration files may also contain comments by using the special character -:code:`#`. A comment should be placed on a separate line above or below the -setting. - -.. code-block:: ini - - [main] - # connection timeout of 120 seconds - timeout=120 - - -.. _interpolation: - -.. rubric:: Interpolation - -The configuration file also supports the `interpolation of values -`_. -It is possible to define values in the :code:`[main]` section and reference -them via a :code:`%()s` syntax. Additionally, values of the -same section can be referenced. - -.. code-block:: ini - - [main] - my_first_name=John - - [gmp] - my_last_name=Smith - username=%(my_first_name)s%(my_last_name)s - -Using this syntax will set the gmp user name setting to `JohnSmith`. - -Example -------- - -Full example configuration: - -.. code-block:: ini - - [main] - # increased timeout to 5 minutes - timeout = 300 - tls_path=/data/tls - default_user=johnsmith - - [gmp] - username=%(default_user)s - password=choo4Gahdi2e - - [unixsocket] - socketpath=/run/gvmd/gvmd.sock - - [tls] - port=1234 - certfile=%(tls_path)s/tls.cert - keyfile=%(tls_path)s/tls.key - cafile=%(tls_path)s/tls.ca - - [ssh] - username=%(default_user)s - password=Poa8Ies1iJee diff --git a/docs/connectiontypes.md b/docs/connectiontypes.md new file mode 100644 index 00000000..36e3e324 --- /dev/null +++ b/docs/connectiontypes.md @@ -0,0 +1,73 @@ +(connection-types)= + +# Connection Types + +Before being able to talk to a remote {term}`GMP` or {term}`OSP` server using +one of the {ref}`provided command line clients `, the user +has to choose a connection type for establishing a communication channel. +Currently three different connection types are supported for being used as +transport protocol: + +> - {ref}`TLS – tls ` +> - {ref}`SSH – ssh ` +> - {ref}`Unix Domain Socket – socket ` + +For the most common use case (querying {term}`gvmd` via +{term}`GMP` on the same host) the {ref}`socket connection +` should be chosen. The other connection types require +some setup and possible adjustments at the server side, if no {term}`Greenbone OS ` +based system is used. + +(socket-connection-type)= + +## Using a Unix Domain Socket + +The Unix Domain Socket is the default connection type of {term}`gvmd` in the +{term}`Greenbone Community Edition`. It is only usable when running the +client tool on the same host as the daemon. + +The location and name of the Unix Domain Socket provided by {term}`gvmd` highly +depends on the environment and {term}`Greenbone Community Edition` installation. + +For current releases of the Greenbone Community Edition 21.4 and 22.4 the +socket should be found at {file}`/run/gvmd/gvmd.sock`. + +For {term}`GOS 4 ` the path is either {file}`/run/openvas/openvasmd.sock` or +{file}`/usr/share/openvas/gsa/classic/openvasmd.sock` and for +{term}`GOS 5 ` and later the path is either {file}`/run/gvm/gvmd.sock` or +{file}`/usr/share/gvm/gsad/web/gvmd.sock`. + +{term}`OSPd based scanners ` may be accessed via Unix Domain Sockets as well. +The location and name of these sockets is configurable and depends on the used +OSPd scanner implementation. + +(don-t-use-sudo)= + +```{warning} +Accessing a Unix Domain Socket requires sufficient Unix file permissions for +the user running the {ref}`command line interface tool `. + +Please do not start a tool as **root** user via {command}`sudo` or {command}`su` only to +be able to access the socket path. Instead, adjust the +socket file permissions, e.g. by setting the {command}`--listen-owner`, +{command}`--listen-group` or {command}`--listen-mode` arguments of +{term}`gvmd`. +``` + +(tls-connection-type)= + +## Using TLS + +The TLS connection type was the default connection type for remote and local +communication in {term}`GOS 3.1 ` and before. It is used to secure the +transport protocol connection of {term}`GMP` or {term}`OSP`. It requires to +provide a TLS certificate file, TLS key file and TLS certificate authority file. + +(ssh-connection-type)= + +## Using SSH + +Since {term}`GOS 4 `, SSH is the default connection type for secure remote +communication with the manager daemon via {term}`GMP`. The {term}`Greenbone +Management Protocol ` is tunneled through SSH and forwarded to +{term}`gvmd`. diff --git a/docs/connectiontypes.rst b/docs/connectiontypes.rst deleted file mode 100644 index 873fb564..00000000 --- a/docs/connectiontypes.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _connection_types: - -Connection Types -================ - -Before being able to talk to a remote :term:`GMP` or :term:`OSP` server using -one of the :ref:`provided command line clients `, the user -has to choose a connection type for establishing a communication channel. -Currently three different connection types are supported for being used as -transport protocol: - - * :ref:`TLS – tls ` - * :ref:`SSH – ssh ` - * :ref:`Unix Domain Socket – socket ` - -For the most common use case (querying :term:`gvmd` via -:term:`GMP` on the same host) the :ref:`socket connection -` should be chosen. The other connection types require -some setup and possible adjustments at the server side, if no :term:`Greenbone OS ` -based system is used. - - -.. _socket_connection_type: - -Using a Unix Domain Socket --------------------------- - -The Unix Domain Socket is the default connection type of :term:`gvmd` in the -:term:`Greenbone Community Edition`. It is only usable when running the -client tool on the same host as the daemon. - -The location and name of the Unix Domain Socket provided by :term:`gvmd` highly -depends on the environment and :term:`Greenbone Community Edition` installation. - -For current releases of the Greenbone Community Edition 21.4 and 22.4 the -socket should be found at :file:`/run/gvmd/gvmd.sock`. - -For :term:`GOS 4 ` the path is either :file:`/run/openvas/openvasmd.sock` or -:file:`/usr/share/openvas/gsa/classic/openvasmd.sock` and for -:term:`GOS 5 ` and later the path is either :file:`/run/gvm/gvmd.sock` or -:file:`/usr/share/gvm/gsad/web/gvmd.sock`. - -:term:`OSPd based scanners ` may be accessed via Unix Domain Sockets as well. -The location and name of these sockets is configurable and depends on the used -OSPd scanner implementation. - -.. _don_t_use_sudo: - -.. warning:: - - Accessing a Unix Domain Socket requires sufficient Unix file permissions for - the user running the :ref:`command line interface tool `. - - Please do not start a tool as **root** user via :command:`sudo` or :command:`su` only to - be able to access the socket path. Instead, adjust the - socket file permissions, e.g. by setting the :command:`--listen-owner`, - :command:`--listen-group` or :command:`--listen-mode` arguments of - :term:`gvmd`. - - -.. _tls_connection_type: - -Using TLS ---------- - -The TLS connection type was the default connection type for remote and local -communication in :term:`GOS 3.1 ` and before. It is used to secure the -transport protocol connection of :term:`GMP` or :term:`OSP`. It requires to -provide a TLS certificate file, TLS key file and TLS certificate authority file. - - -.. _ssh_connection_type: - -Using SSH ---------- - -Since :term:`GOS 4 `, SSH is the default connection type for secure remote -communication with the manager daemon via :term:`GMP`. The :term:`Greenbone -Management Protocol ` is tunneled through SSH and forwarded to -:term:`gvmd`. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..4c5d2d25 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,140 @@ +# Glossary + +```{glossary} +gvmd + + Management daemon shipped with {term}`GVM 10 ` and later. + Abbreviation for **G**reenbone **V**ulnerability **M**anager + **D**aemon. + +openvassd + + Scanner daemon used by {term}`GVM 10 ` and before. It listens for + incoming connections via OTP and starts scan processes to run the + actual vulnerability tests. It collects the results and reports them to the + management daemon. With {term}`GVM 11 ` it has been converted into + the {term}`openvas` application by removing the daemon and OTP parts. + Abbreviation for **OpenVAS** **S**canner **D**aemon. + +openvas + + Scanner application executable to run vulnerability tests against targets + and to store scan results into a redis database. Used in + {term}`GVM 11 ` and later. It has originated from the + {term}`openvassd` daemon. + +OSPd + + A [framework](https://github.com/greenbone/ospd) for several scanner + daemons speaking the {term}`Open Scanner Protocol (OSP) `. + +ospd-openvas + + A {term}`OSP ` scanner daemon managing the {term}`openvas ` + executable for reporting scan results to the management daemon {term}`gvmd`. + Used in {term}`GVM 11 ` and later. + +GOS + + Greenbone Operating System, the operating system of the + {term}`Greenbone Enterprise` Appliance. It provides the commercial version + of the {term}`Greenbone Community Edition` with enterprise support and + features. + +GSM + + Greenbone Security Manager (GSM) is the former name of our commercial + product line {term}`Greenbone Enterprise` as hardware or virtual appliances. + +GMP + + The Greenbone Management Protocol (GMP) is an XML-based communication + protocol provided by {term}`gvmd`. It provides an API to create, read, update + and delete scans and vulnerability information. + +OSP + + The Open Scanner Protocol is an XML-based communication protocol provided by + {term}`ospd-openvas`. It provides an API to start scans, get {term}`VT` + information and to receive scan results. + +GVM + + The {term}`Greenbone Community Edition` consists of several services. This + software framework has been named Greenbone Vulnerability Management (GVM) + in the past. + +Greenbone Community Edition + + The Greenbone Community Edition covers the actual releases of the Greenbone + application framework for vulnerability scanning and vulnerability + management provided as open-source software to the community. The Greenbone + Community Edition is adopted by external third parties, e.g., if the + software framework is provided by a Linux distribution, it is build from the + Greenbone Community Edition. It is developed as part of the commercial + {term}`Greenbone Enterprise` product line. Sometimes referred to as the + OpenVAS framework. + +GVM9 + + [Version 9](https://community.greenbone.net/t/gvm-9-end-of-life-initial-release-2017-03-07/211) + of the {term}`Greenbone Community Edition`. Also known as **OpenVAS 9**. + Used in the {term}`GOS 4 ` series. + +GVM10 + + [Version 10](https://community.greenbone.net/t/gvm-10-old-stable-initial-release-2019-04-05/208) of the + {term}`Greenbone Community Edition`. Used in {term}`GOS 5 `. + +GVM11 + + [Version 11](https://community.greenbone.net/t/gvm-11-stable-initial-release-2019-10-14/3674) of the + {term}`Greenbone Community Edition`. Used in {term}`GOS 6 `. + +GVM20.08 + + [Version 20.08](https://community.greenbone.net/t/gvm-20-08-stable-initial-release-2020-08-12/6312) of the + {term}`Greenbone Community Edition`. Used in {term}`GOS 20.08 `. First + version using [Calendar Versioning](https://calver.org/) + +GVM21.4 + + [Version 21.4](https://community.greenbone.net/t/gvm-21-04-oldstable-initial-release-2021-04-16/8942) of the + {term}`Greenbone Community Edition`. Used in {term}`GOS 21.04 `. + +GVM22.4 + + [Version 22.4](https://community.greenbone.net/t/greenbone-community-edition-22-4-stable-initial-release-2022-07-25/12638) of the + {term}`Greenbone Community Edition`. Used in {term}`GOS 22.04 `. + +Greenbone Enterprise + + Greenbone Enterprise is the [Greenbone product line for on-premises solutions](https://www.greenbone.net/en/product-comparison/). + Included are virtual or hardware Greenbone Enterprise Appliances with the + {term}`Greenbone Operating System (GOS)`, the + {term}`Greenbone Community Edition` framework, and the + {term}`Greenbone Enterprise Feed`. + +Greenbone Community Feed + + The Greenbone Community Feed is the freely available feed for vulnerability + information licensed as open-source. It contains basic scan configurations, + report formats, port lists and the most important vulnerability tests. The + provided data is updated on a daily basis with no warranty or promises for + fixes or completeness. + +Greenbone Enterprise Feed + + The Greenbone Enterprise Feed is the commercial feed provided by + Greenbone Networks containing additional enterprise features like + vulnerability tests for enterprise products, policy and compliance checks, + extensive reports formats and special scan configurations. + The feed comes with a service-level agreement ensuring support, quality + assurance and availability. + +VT + + Vulnerability Tests (VTs), also known as Network Vulnerability Tests + (NVTs), are scripts written in the NASL programming language to detect + vulnerabilities at remote hosts. +``` diff --git a/docs/glossary.rst b/docs/glossary.rst deleted file mode 100644 index ab627e11..00000000 --- a/docs/glossary.rst +++ /dev/null @@ -1,121 +0,0 @@ -Glossary -======== - -.. glossary:: - - gvmd - Management daemon shipped with :term:`GVM 10 ` and later. - Abbreviation for **G**\reenbone **V**\ulnerability **M**\anager - **D**\aemon. - - openvassd - Scanner daemon used by :term:`GVM 10 ` and before. It listens for - incoming connections via OTP and starts scan processes to run the - actual vulnerability tests. It collects the results and reports them to the - management daemon. With :term:`GVM 11 ` it has been converted into - the :term:`openvas` application by removing the daemon and OTP parts. - Abbreviation for **OpenVAS** **S**\canner **D**\aemon. - - openvas - Scanner application executable to run vulnerability tests against targets - and to store scan results into a redis database. Used in - :term:`GVM 11 ` and later. It has originated from the - :term:`openvassd` daemon. - - OSPd - A `framework `_ for several scanner - daemons speaking the :term:`Open Scanner Protocol (OSP) `. - - ospd-openvas - A :term:`OSP ` scanner daemon managing the :term:`openvas ` - executable for reporting scan results to the management daemon :term:`gvmd`. - Used in :term:`GVM 11 ` and later. - - GOS - Greenbone Operating System, the operating system of the - :term:`Greenbone Enterprise` Appliance. It provides the commercial version - of the :term:`Greenbone Community Edition` with enterprise support and - features. - - GSM - Greenbone Security Manager (GSM) is the former name of our commercial - product line :term:`Greenbone Enterprise` as hardware or virtual appliances. - - GMP - The Greenbone Management Protocol (GMP) is an XML-based communication - protocol provided by :term:`gvmd`. It provides an API to create, read, update - and delete scans and vulnerability information. - - OSP - The Open Scanner Protocol is an XML-based communication protocol provided by - :term:`ospd-openvas`. It provides an API to start scans, get :term:`VT` - information and to receive scan results. - - GVM - The :term:`Greenbone Community Edition` consists of several services. This - software framework has been named Greenbone Vulnerability Management (GVM) - in the past. - - Greenbone Community Edition - The Greenbone Community Edition covers the actual releases of the Greenbone - application framework for vulnerability scanning and vulnerability - management provided as open-source software to the community. The Greenbone - Community Edition is adopted by external third parties, e.g., if the - software framework is provided by a Linux distribution, it is build from the - Greenbone Community Edition. It is developed as part of the commercial - :term:`Greenbone Enterprise` product line. Sometimes referred to as the - OpenVAS framework. - - GVM9 - `Version 9 `_ - of the :term:`Greenbone Community Edition`. Also known as **OpenVAS 9**. - Used in the :term:`GOS 4 ` series. - - GVM10 - `Version 10 `_ of the - :term:`Greenbone Community Edition`. Used in :term:`GOS 5 `. - - GVM11 - `Version 11 `_ of the - :term:`Greenbone Community Edition`. Used in :term:`GOS 6 `. - - GVM20.08 - `Version 20.08 `_ of the - :term:`Greenbone Community Edition`. Used in :term:`GOS 20.08 `. First - version using `Calendar Versioning `_ - - GVM21.4 - `Version 21.4 `_ of the - :term:`Greenbone Community Edition`. Used in :term:`GOS 21.04 `. - - GVM22.4 - `Version 22.4 `_ of the - :term:`Greenbone Community Edition`. Used in :term:`GOS 22.04 `. - - Greenbone Enterprise - Greenbone Enterprise is the `Greenbone product line for on-premises solutions - `_. - Included are virtual or hardware Greenbone Enterprise Appliances with the - :term:`Greenbone Operating System (GOS)`, the - :term:`Greenbone Community Edition` framework, and the - :term:`Greenbone Enterprise Feed`. - - Greenbone Community Feed - The Greenbone Community Feed is the freely available feed for vulnerability - information licensed as open-source. It contains basic scan configurations, - report formats, port lists and the most important vulnerability tests. The - provided data is updated on a daily basis with no warranty or promises for - fixes or completeness. - - Greenbone Enterprise Feed - The Greenbone Enterprise Feed is the commercial feed provided by - Greenbone Networks containing additional enterprise features like - vulnerability tests for enterprise products, policy and compliance checks, - extensive reports formats and special scan configurations. - The feed comes with a service-level agreement ensuring support, quality - assurance and availability. - - VT - Vulnerability Tests (VTs), also known as Network Vulnerability Tests - (NVTs), are scripts written in the NASL programming language to detect - vulnerabilities at remote hosts. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..570be511 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,23 @@ +# gvm-tools: Remote Control of Your Greenbone Vulnerability Manager (GVM) + +The Greenbone Vulnerability Management Tools, or {program}`gvm-tools` in short, +are a collection of tools that help with controlling a [Greenbone +Enterprise Appliance](https://www.greenbone.net/en/product-comparison/) +and Greenbone Community Edition installations remotely. + +Essentially, the tools aid accessing the communication protocols +{term}`Greenbone Management Protocol (GMP) ` +and {term}`Open Scanner Protocol (OSP) `. + +```{note} +{program}`gvm-tools` requires at least Python 3.9. +``` + +```{toctree} +install +connectiontypes +tools +config +scripting +glossary +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 5e452522..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -gvm-tools: Remote Control of Your Greenbone Vulnerability Manager (GVM) -======================================================================= - -The Greenbone Vulnerability Management Tools, or :program:`gvm-tools` in short, -are a collection of tools that help with controlling a `Greenbone -Enterprise Appliance `_ -and Greenbone Community Edition installations remotely. - -Essentially, the tools aid accessing the communication protocols -:term:`Greenbone Management Protocol (GMP) ` -and :term:`Open Scanner Protocol (OSP) `. - -.. note:: :program:`gvm-tools` requires at least Python 3.9. - -.. toctree:: - install - connectiontypes - tools - config - scripting - glossary diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..29c7ff95 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,108 @@ +(installation)= + +# Installation of gvm-tools + +```{note} +The current universally applicable installation process for Python is using +the [pipx] installer tool in conjunction with the [pypi] package repository. +``` + +## Installing the Latest Stable Release of gvm-tools + +For installing the latest stable release of {program}`gvm-tools` from the +[Python Package Index](https://pypi.org/), [pipx], [pip] or [poetry] can be +used. + +(using-pipx)= + +### Using pipx + +You can install the latest release of **gvm-tools** using [pipx]. + +```shell +python3 -m pipx install gvm-tools +``` + +On Debian based Distributions like Ubuntu and Kali [pipx] itself can be +installed via + +```shell +sudo apt install pipx +``` + +### Using pip + +```{note} +The {command}`pip install` command does no longer work out-of-the-box in newer +distributions like Ubuntu 23.04 or Debian 12 because of [PEP 668](https://peps.python.org/pep-0668). +Please use the {ref}`installation via pipx ` instead. +``` + +The following command installs {program}`gvm-tools` system wide: + +```shell +python3 -m pip install gvm-tools +``` + +A system wide installation usually requires admin permissions. Therefore, +{program}`gvm-tools` may only be installed for the +[current user](https://docs.python.org/3/library/site.html#site.USER_BASE) +via: + +```shell +python3 -m pip install --user gvm-tools +``` + +For further details and additional installation options, please take a look at +the documentation of [pip]. + +### Using poetry + +To avoid polluting the system and user namespaces with Python packages and to +allow installing different versions of the same package at the same time, +[python virtual environments](https://docs.python.org/3/library/venv.html) +have been introduced. + +[poetry] is a tool combining the use of virtual environments and handling +dependencies elegantly. + +Please follow the [poetry documentation](https://python-poetry.org/docs/#installation) +to install the tool. + +To install {program}`gvm-tools` into a virtual environment, defaulting into +the folder `.venv`, the following command need to be executed: + +```shell +poetry install +``` + +Afterwards, the environment containing the installed {program}`gvm-tools` can be +activated by running: + +```shell +poetry shell +``` + +It is also possible to run single commands within the virtual environment: + +```shell +poetry run gvm-cli -h +``` + +## Getting the Source + +The source code of **python-gvm** can be found at +[GitHub](https://github.com/greenbone/python-gvm). + +To clone this public repository and install from source for the current user run +the following commands: + +```shell +git clone git://github.com/greenbone/gvm-tools.git && cd gvm-tools +python3 -m pip install -e . +``` + +[pip]: https://pip.pypa.io/en/stable/ +[pipx]: https://pypa.github.io/pipx/ +[poetry]: https://python-poetry.org/ +[pypi]: https://pypi.org/ diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 4ec9418b..00000000 --- a/docs/install.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. _installation: - -Installation of gvm-tools -========================= - -The current universally applicable installation process for Python is using -the `pip`_ installer tool in conjunction with the `pypi`_ package repository. - -Installing the Latest Stable Release of gvm-tools -------------------------------------------------- - -For installing the latest stable release of :program:`gvm-tools` from the -`Python Package Index `_, `pipx`_, `pip`_ or `poetry`_ can be -used. - -.. note:: - - Using pipx is the recommended installation method. - - -.. _using-pipx: - -Using pipx -^^^^^^^^^^ - -You can install the latest release of **gvm-tools** using `pipx`_. - -.. code-block:: shell - - python3 -m pipx install gvm-tools - -On Debian based Distributions like Ubuntu and Kali `pipx`_ itself can be -installed via - -.. code-block:: shell - - sudo apt install pipx - -Using pip -^^^^^^^^^ - -.. note:: - - The :command:`pip install` command does no longer work out-of-the-box in newer - distributions like Ubuntu 23.04 or Debian 12 because of `PEP 668 `_. - Please use the :ref:`installation via pipx ` instead. - -The following command installs :program:`gvm-tools` system wide: - -.. code-block:: shell - - python3 -m pip install gvm-tools - -A system wide installation usually requires admin permissions. Therefore, -:program:`gvm-tools` may only be installed for the -`current user `_ -via: - -.. code-block:: shell - - python3 -m pip install --user gvm-tools - -For further details and additional installation options, please take a look at -the documentation of `pip`_. - -Using poetry -^^^^^^^^^^^^ - -To avoid polluting the system and user namespaces with Python packages and to -allow installing different versions of the same package at the same time, -`python virtual environments `_ -have been introduced. - -`poetry`_ is a tool combining the use of virtual environments and handling -dependencies elegantly. - -Please follow the `poetry documentation `_ -to install the tool. - -To install :program:`gvm-tools` into a virtual environment, defaulting into -the folder `.venv`, the following command need to be executed: - -.. code-block:: shell - - poetry install - -Afterwards, the environment containing the installed :program:`gvm-tools` can be -activated by running: - -.. code-block:: shell - - poetry shell - -It is also possible to run single commands within the virtual environment: - -.. code-block:: shell - - poetry run gvm-cli -h - -Getting the Source ------------------- - -The source code of **python-gvm** can be found at -`GitHub `_. - -To clone this public repository and install from source for the current user run -the following commands: - -.. code-block:: shell - - git clone git://github.com/greenbone/gvm-tools.git && cd gvm-tools - python3 -m pip install -e . - -.. _pip: https://pip.pypa.io/en/stable/ -.. _pipx: https://pypa.github.io/pipx/ -.. _poetry: https://python-poetry.org/ -.. _pypi: https://pypi.org/ diff --git a/docs/scripting.md b/docs/scripting.md new file mode 100644 index 00000000..9be712d9 --- /dev/null +++ b/docs/scripting.md @@ -0,0 +1,285 @@ +(scripting)= + +# Scripting + +(xml-scripting)= + +## XML Scripting + +```{note} +XML scripting via {program}`gvm-cli` should only be considered for +simpler use cases. {ref}`Greenbone Management Protocol (GMP) or +Open Scanner Protocol (OSP) scripts ` are often more +powerful and easier to write. +``` + +Scripting via {program}`gvm-cli` is directly based on [GMP](https://docs.greenbone.net/API/GMP/gmp-22.04.html) +and [OSP](https://docs.greenbone.net/API/OSP/osp-22.04.html). Both protocols make +use of XML command requests and corresponding responses. + +A typical example for using GMP is the automatic scan of a new +system. In the example below, it is assumed that an Intrusion Detection +System (IDS) that monitors the systems in the Demilitarized Zone (DMZ) and immediately +discovers new systems and unusual, new TCP ports is in use. If such an +event is being discovered, the IDS should automatically initiate a scan +of the new system. This can be done with the help of a script. + +1. Starting point is the IP address of the new suspected system. For this IP + address, a target needs to be created on the {term}`Greenbone Enterprise` + Appliance. + + If the IP address is saved in the environment variable {envvar}`IPADDRESS` by + the IDS, the respective target can be created: + +```shell +> gvm-cli socket --xml "Suspect Host"$IPADDRESS"" + +``` + +See {command}`create_target` command for all [details](https://docs.greenbone.net/API/GMP/gmp-22.04.html#command_create_target). + +2. Create a task using the default *Full and Fast* scan configuration with + UUID {token}`daba56c8-73ec-11df-a475-002264764cea` and the previously generated + target: + +```shell +> gvm-cli socket --xml "Scan Suspect Host" + +``` + +See {command}`create_task` command for all [details](https://docs.greenbone.net/API/GMP/gmp-22.04.html#command_create_task). + +3. Start the task using the UUID return from the last response: + +```shell +> gvm-cli socket --xml "" +0f9ea6ca-abf5-4139-a772-cb68937cdfbb +``` + +See {command}`start_task` command for all [details](https://docs.greenbone.net/API/GMP/gmp-22.04.html#command_start_task). + +→ The task is running. The response returns the UUID of the report which will +contain the results of the scan. + +4. Display the current status of the task: + +```shell +> gvm-cli socket --xml "" + +... +Running98 ... +... + +``` + +See {command}`get_tasks` command for all [details](https://docs.greenbone.net/API/GMP/gmp-22.04.html#command_get_tasks). + +→ As soon as the scan is completed, the full report is available and can be +displayed. + +5. Display the full report: + +```shell +> gvm-cli socket --xml "" + +... + +``` + +See {command}`get_reports` command for all [details](https://docs.greenbone.net/API/GMP/gmp-22.04.html#command_get_reports). + +6. Additionally, the report can be downloaded in a specific report format instead + of plain XML. + + List all report formats: + +```shell +> gvm-cli socket --xml "" + +... + +``` + +See {command}`get_report_formats` command for all [details](https://docs.greenbone.net/API/GMP/gmp-22.04.html#command_get_report_formats). + +7. Download the report in the desired format. + + Example: download the report as a PDF file: + +```shell +> gvm-cli socket --xml "" +``` + +```{note} +Please be aware that the PDF is returned as [base64 encoded](https://en.wikipedia.org/wiki/Base64) content of the +*\\* element in the XML response. +``` + +(gvm-scripting)= + +## GVM Scripts + +```{versionchanged} 2.0 +``` + +Scripting of {term}`Greenbone Management Protocol (GMP) ` and {term}`Open Scanner Protocol +(OSP) ` via {program}`gvm-script` or interactively via +{program}`gvm-pyshell` is based on the [python-gvm] library. Please take a look +at [python-gvm] for further details about the API. + +```{note} +By convention, scripts using {term}`GMP` are called *GMP scripts* and +are files with the ending {file}`.gmp.py`. Accordingly, *OSP scripts* with the +ending {file}`.osp.py` are using {term}`OSP`. Technically both protocols could be +used in one single script file. +``` + +The following sections are using the same example as it was used in +{ref}`XML Scripting ` where it was assumed that an Intrusion Detection +System (IDS) that monitors the systems in the Demilitarized Zone (DMZ) and immediately discovers +new systems and unusual, new TCP ports is in use. The IDS will provide the +IP address of a new system to the GMP script. + +1. Define the function that should be called when the script is + started by adding the following code to a file named {file}`scan-new-system.gmp.py`: + +```python3 +if __name__ == '__gmp__': + main(gmp, args) +``` + +→ The script is only called when being run as a GMP script. The +{dfn}`gmp` and {dfn}`args` variables are provided by {program}`gvm-cli` or +{program}`gvm-pyshell`. {dfn}`args` contains arguments for the script, e.g., the +user name and password for the GMP connection. The most important aspect about the example +script is that it contains the {dfn}`argv` property with the list of additional script +specific arguments. The {dfn}`gmp` variable contains a connected and +authenticated instance of a [Greenbone Management Protocol class](https://greenbone.github.io/python-gvm/api/gmp.html#module-gvm.protocols.gmp). + +2. The main function begins with the following code lines: + +```python3 +def main(gmp: Gmp, args: Namespace) -> None: + # check if IP address is provided to the script + # argv[0] contains the script name + if len(args.argv) <= 1: + print('Missing IP address argument') + return 1 + + ipaddress = args.argv[1] +``` + +→ The main function stores the first argument passed to the script as the {envvar}`ipaddress` +variable. + +3\. Add the logic to create a target, create a new scan task for the target, +start the task and print the corresponding report ID: + +```python3 +ipaddress = args.argv[1] + +target_id = create_target(gmp, ipaddress) + +full_and_fast_scan_config_id = 'daba56c8-73ec-11df-a475-002264764cea' +openvas_scanner_id = '08b69003-5fc2-4037-a479-93b440211c73' +task_id = create_task( + gmp, + ipaddress, + target_id, + full_and_fast_scan_config_id, + openvas_scanner_id, +) + +report_id = start_task(gmp, task_id) + +print( + f"Started scan of host {ipaddress}. Corresponding report ID is {report_id}" +) +``` + +For creating the target from an IP address (DNS name is also possible), the +following is used. Since target names must be unique, the current date and time in +ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm) is added: + +```python3 +def create_target(gmp, ipaddress): + import datetime + + # create a unique name by adding the current datetime + name = f"Suspect Host {ipaddress} {str(datetime.datetime.now())}" + response = gmp.create_target(name=name, hosts=[ipaddress]) + return response.get('id') +``` + +The function for creating the task is defined as: + +```python3 +def create_task(gmp, ipaddress, target_id, scan_config_id, scanner_id): + name = f"Scan Suspect Host {ipaddress}" + response = gmp.create_task( + name=name, + config_id=scan_config_id, + target_id=target_id, + scanner_id=scanner_id, + ) + return response.get('id') +``` + +Finally, the function to start the task and get the report ID: + +```python3 +def start_task(gmp, task_id): + response = gmp.start_task(task_id) + # the response is + # id + return response[0].text +``` + +For getting a PDF document of the report, a second script {file}`pdf-report.gmp.py` +can be used: + +```python3 +from base64 import b64decode +from pathlib import Path + + +def main(gmp: Gmp, args: Namespace) -> None: + # check if report id and PDF filename are provided to the script + # argv[0] contains the script name + if len(args.argv) <= 2: + print('Please provide report ID and PDF file name as script arguments') + return 1 + + report_id = args.argv[1] + pdf_filename = args.argv[2] + + pdf_report_format_id = "c402cc3e-b531-11e1-9163-406186ea4fc5" + response = gmp.get_report( + report_id=report_id, report_format_id=pdf_report_format_id + ) + + report_element = response[0] + # get the full content of the report element + content = "".join(report_element.itertext()) + + # convert content to 8-bit ASCII bytes + binary_base64_encoded_pdf = content.encode('ascii') + # decode base64 + binary_pdf = b64decode(binary_base64_encoded_pdf) + + # write to file and support ~ in filename path + pdf_path = Path(pdf_filename).expanduser() + pdf_path.write_bytes(binary_pdf) + + print('Done.') + + +if __name__ == '__gmp__': + main(gmp, args) +``` + +## Example Scripts + +All example scripts can be found at [GitHub](https://github.com/greenbone/gvm-tools/tree/main/scripts). + +[python-gvm]: https://greenbone.github.io/python-gvm/ diff --git a/docs/scripting.rst b/docs/scripting.rst deleted file mode 100644 index c02da88b..00000000 --- a/docs/scripting.rst +++ /dev/null @@ -1,299 +0,0 @@ -.. _scripting: - -Scripting -========= - -.. _xml_scripting: - -XML Scripting -------------- - -.. note:: XML scripting via :program:`gvm-cli` should only be considered for - simpler use cases. :ref:`Greenbone Management Protocol (GMP) or - Open Scanner Protocol (OSP) scripts ` are often more - powerful and easier to write. - -Scripting via :program:`gvm-cli` is directly based on `GMP -`_ and `OSP -`_. Both protocols make -use of XML command requests and corresponding responses. - -A typical example for using GMP is the automatic scan of a new -system. In the example below, it is assumed that an Intrusion Detection -System (IDS) that monitors the systems in the Demilitarized Zone (DMZ) and immediately -discovers new systems and unusual, new TCP ports is in use. If such an -event is being discovered, the IDS should automatically initiate a scan -of the new system. This can be done with the help of a script. - -1. Starting point is the IP address of the new suspected system. For this IP - address, a target needs to be created on the :term:`Greenbone Enterprise` - Appliance. - - If the IP address is saved in the environment variable :envvar:`IPADDRESS` by - the IDS, the respective target can be created: - -.. code-block:: shell - - > gvm-cli socket --xml "Suspect Host"$IPADDRESS"" - - -See :command:`create_target` command for all `details -`__. - -2. Create a task using the default *Full and Fast* scan configuration with - UUID :token:`daba56c8-73ec-11df-a475-002264764cea` and the previously generated - target: - -.. code-block:: shell - - > gvm-cli socket --xml "Scan Suspect Host" - - -See :command:`create_task` command for all `details -`__. - - -3. Start the task using the UUID return from the last response: - -.. code-block:: shell - - > gvm-cli socket --xml "" - 0f9ea6ca-abf5-4139-a772-cb68937cdfbb - -See :command:`start_task` command for all `details -`__. - -→ The task is running. The response returns the UUID of the report which will -contain the results of the scan. - -4. Display the current status of the task: - -.. code-block:: shell - - > gvm-cli socket --xml "" - - ... - Running98 ... - ... - - -See :command:`get_tasks` command for all `details -`__. - -→ As soon as the scan is completed, the full report is available and can be -displayed. - -5. Display the full report: - -.. code-block:: shell - - > gvm-cli socket --xml "" - - ... - - -See :command:`get_reports` command for all `details -`__. - -6. Additionally, the report can be downloaded in a specific report format instead - of plain XML. - - List all report formats: - -.. code-block:: shell - - > gvm-cli socket --xml "" - - ... - - -See :command:`get_report_formats` command for all `details -`__. - -7. Download the report in the desired format. - - Example: download the report as a PDF file: - -.. code-block:: shell - - > gvm-cli socket --xml "" - -.. note:: Please be aware that the PDF is returned as `base64 encoded - `_ content of the - ** element in the XML response. - - -.. _gvm_scripting: - -GVM Scripts ------------ - -.. versionchanged:: 2.0 - -Scripting of :term:`Greenbone Management Protocol (GMP) ` and :term:`Open Scanner Protocol -(OSP) ` via :program:`gvm-script` or interactively via -:program:`gvm-pyshell` is based on the `python-gvm`_ library. Please take a look -at `python-gvm`_ for further details about the API. - -.. note:: By convention, scripts using :term:`GMP` are called *GMP scripts* and - are files with the ending :file:`.gmp.py`. Accordingly, *OSP scripts* with the - ending :file:`.osp.py` are using :term:`OSP`. Technically both protocols could be - used in one single script file. - -The following sections are using the same example as it was used in -:ref:`XML Scripting ` where it was assumed that an Intrusion Detection -System (IDS) that monitors the systems in the Demilitarized Zone (DMZ) and immediately discovers -new systems and unusual, new TCP ports is in use. The IDS will provide the -IP address of a new system to the GMP script. - -1. Define the function that should be called when the script is - started by adding the following code to a file named :file:`scan-new-system.gmp.py`: - -.. code-block:: python3 - - if __name__ == '__gmp__': - main(gmp, args) - -→ The script is only called when being run as a GMP script. The -:dfn:`gmp` and :dfn:`args` variables are provided by :program:`gvm-cli` or -:program:`gvm-pyshell`. :dfn:`args` contains arguments for the script, e.g., the -user name and password for the GMP connection. The most important aspect about the example -script is that it contains the :dfn:`argv` property with the list of additional script -specific arguments. The :dfn:`gmp` variable contains a connected and -authenticated instance of a `Greenbone Management Protocol class -`_. - -2. The main function begins with the following code lines: - -.. code-block:: python3 - - def main(gmp: Gmp, args: Namespace) -> None: - # check if IP address is provided to the script - # argv[0] contains the script name - if len(args.argv) <= 1: - print('Missing IP address argument') - return 1 - - ipaddress = args.argv[1] - -→ The main function stores the first argument passed to the script as the :envvar:`ipaddress` -variable. - -3. Add the logic to create a target, create a new scan task for the target, -start the task and print the corresponding report ID: - -.. code-block:: python3 - - ipaddress = args.argv[1] - - target_id = create_target(gmp, ipaddress) - - full_and_fast_scan_config_id = 'daba56c8-73ec-11df-a475-002264764cea' - openvas_scanner_id = '08b69003-5fc2-4037-a479-93b440211c73' - task_id = create_task( - gmp, - ipaddress, - target_id, - full_and_fast_scan_config_id, - openvas_scanner_id, - ) - - report_id = start_task(gmp, task_id) - - print( - f"Started scan of host {ipaddress}. Corresponding report ID is {report_id}" - ) - -For creating the target from an IP address (DNS name is also possible), the -following is used. Since target names must be unique, the current date and time in -ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm) is added: - -.. code-block:: python3 - - def create_target(gmp, ipaddress): - import datetime - - # create a unique name by adding the current datetime - name = f"Suspect Host {ipaddress} {str(datetime.datetime.now())}" - response = gmp.create_target(name=name, hosts=[ipaddress]) - return response.get('id') - - -The function for creating the task is defined as: - -.. code-block:: python3 - - def create_task(gmp, ipaddress, target_id, scan_config_id, scanner_id): - name = f"Scan Suspect Host {ipaddress}" - response = gmp.create_task( - name=name, - config_id=scan_config_id, - target_id=target_id, - scanner_id=scanner_id, - ) - return response.get('id') - - -Finally, the function to start the task and get the report ID: - -.. code-block:: python3 - - def start_task(gmp, task_id): - response = gmp.start_task(task_id) - # the response is - # id - return response[0].text - - -For getting a PDF document of the report, a second script :file:`pdf-report.gmp.py` -can be used: - -.. code-block:: python3 - - from base64 import b64decode - from pathlib import Path - - - def main(gmp: Gmp, args: Namespace) -> None: - # check if report id and PDF filename are provided to the script - # argv[0] contains the script name - if len(args.argv) <= 2: - print('Please provide report ID and PDF file name as script arguments') - return 1 - - report_id = args.argv[1] - pdf_filename = args.argv[2] - - pdf_report_format_id = "c402cc3e-b531-11e1-9163-406186ea4fc5" - response = gmp.get_report( - report_id=report_id, report_format_id=pdf_report_format_id - ) - - report_element = response[0] - # get the full content of the report element - content = "".join(report_element.itertext()) - - # convert content to 8-bit ASCII bytes - binary_base64_encoded_pdf = content.encode('ascii') - # decode base64 - binary_pdf = b64decode(binary_base64_encoded_pdf) - - # write to file and support ~ in filename path - pdf_path = Path(pdf_filename).expanduser() - pdf_path.write_bytes(binary_pdf) - - print('Done.') - - - if __name__ == '__gmp__': - main(gmp, args) - - - -.. _python-gvm: https://greenbone.github.io/python-gvm/ - -Example Scripts ---------------- - -All example scripts can be found at `GitHub -`_. diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 00000000..2aed1496 --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,188 @@ +(tools)= + +# Provided Tools + +Currently, {program}`gvm-tools` comes with three command line interface +programs: + +- {ref}`gvm-cli ` +- {ref}`gvm-script ` +- {ref}`gvm-pyshell ` + +All of these programs are clients communicating either via +{term}`Greenbone Management Protocol (GMP) ` +or {term}`Open Scanner Protocol (OSP) `. The +{ref}`connection ` is established using a +{ref}`TLS `, {ref}`SSH ` or +{ref}`Unix Domain Socket ` communication channel. + +All tools take several arguments and parameters. {program}`gvm-tools` allows +setting defaults for most of these in a configuration file. See {doc}`config` +for details about the possible settings and capabilities. + +(gvm-cli)= + +## gvm-cli + +{program}`gvm-cli` is a low level tool which offers sending and receiving +commands and responses for the XML-based {term}`GMP ` and {term}`OSP ` +directly via the command line. It is intended for {ref}`simple scripting ` +via shell. + +```shell +> gvm-cli --help +usage: gvm-cli [-h] [-c [CONFIG]] + [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] + [--timeout TIMEOUT] [--gmp-username GMP_USERNAME] + [--gmp-password GMP_PASSWORD] [-V] + CONNECTION_TYPE ... + +optional arguments: + -h, --help show this help message and exit + -c [CONFIG], --config [CONFIG] + Configuration file path (default: ~/.config/gvm- + tools.conf) + --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}] + Activate logging (default level: None) + --timeout TIMEOUT Response timeout in seconds, or -1 to wait + indefinitely (default: 60) + --gmp-username GMP_USERNAME + Username for GMP service (default: '') + --gmp-password GMP_PASSWORD + Password for GMP service (default: '') + -V, --version Show version information and exit + +connections: + valid connection types + + CONNECTION_TYPE Connection type to use + ssh Use SSH to connect to service + tls Use TLS secured connection to connect to service + socket Use UNIX Domain socket to connect to service +``` + +Examples: + +```shell +> gvm-cli socket --xml "" +7.0 + +> gvm-cli socket --xml "" + +... + + +> gvm-cli socket < commands.xml +``` + +(gvm-script)= + +## gvm-script + +```{versionadded} 2.0 +``` + +{program}`gvm-script` allows running {ref}`gvm scripts ` +which are Python based scripts calling the [python-gvm API]. Depending on the +{command}`--protocol` argument a global gmp or osp object is passed to the +script. + +```{note} +{program}`gvm-script` is only available with {program}`gvm-tools` version 2.0 and beyond. +``` + +```shell +usage: gvm-script [-h] [-c [CONFIG]] + [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] + [--timeout TIMEOUT] [--gmp-username GMP_USERNAME] + [--gmp-password GMP_PASSWORD] [-V] [--protocol {GMP,OSP}] + CONNECTION_TYPE ... + +optional arguments: + -h, --help show this help message and exit + -c [CONFIG], --config [CONFIG] + Configuration file path (default: ~/.config/gvm- + tools.conf) + --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}] + Activate logging (default level: None) + --timeout TIMEOUT Response timeout in seconds, or -1 to wait + indefinitely (default: 60) + --gmp-username GMP_USERNAME + Username for GMP service (default: '') + --gmp-password GMP_PASSWORD + Password for GMP service (default: '') + -V, --version Show version information and exit + --protocol {GMP,OSP} Service protocol to use (default: GMP) + +connections: + valid connection types + + CONNECTION_TYPE Connection type to use + ssh Use SSH to connect to service + tls Use TLS secured connection to connect to service + socket Use UNIX Domain socket to connect to service +``` + +(gvm-pyshell)= + +## gvm-pyshell + +{program}`gvm-pyshell` is a tool to use the [python-gvm API] interactively. +Running the tool will open a Python interpreter in the [interactive mode](https://docs.python.org/3/tutorial/interpreter.html#interactive-mode) +providing a global gmp or osp object depending on the {command}`--protocol` +argument. + +The interactive shell can be exited with: + +- {kbd}`Ctrl+D` on Linux or +- {kbd}`Ctrl+Z` on Windows + +```shell +> gvm-pyshell --help +usage: gvm-pyshell [-h] [-c [CONFIG]] + [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] + [--timeout TIMEOUT] [--gmp-username GMP_USERNAME] + [--gmp-password GMP_PASSWORD] [-V] [--protocol {GMP,OSP}] + CONNECTION_TYPE ... + +optional arguments: + -h, --help show this help message and exit + -c [CONFIG], --config [CONFIG] + Configuration file path (default: ~/.config/gvm- + tools.conf) + --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}] + Activate logging (default level: None) + --timeout TIMEOUT Response timeout in seconds, or -1 to wait + indefinitely (default: 60) + --gmp-username GMP_USERNAME + Username for GMP service (default: '') + --gmp-password GMP_PASSWORD + Password for GMP service (default: '') + -V, --version Show version information and exit + --protocol {GMP,OSP} Service protocol to use (default: GMP) + +connections: + valid connection types + + CONNECTION_TYPE Connection type to use + ssh Use SSH to connect to service + tls Use TLS secured connection to connect to service + socket Use UNIX Domain socket to connect to service +``` + +Example: + +```python +> gvm-pyshell socket +GVM Interactive Console 2.0.0 API 1.0.0. Type "help" to get information about functionality. +>>> gmp.get_protocol_version() +'7' +>>> gmp.get_version().get('status') +'200' +>>> gmp.get_version()[0].text +'7.0' +>>> [t.find('name').text for t in tasks.xpath('task')] +['Scan Task', 'Simple Scan', 'Host Discovery'] +``` + +[python-gvm api]: https://greenbone.github.io/python-gvm/ diff --git a/docs/tools.rst b/docs/tools.rst deleted file mode 100644 index 76421dce..00000000 --- a/docs/tools.rst +++ /dev/null @@ -1,194 +0,0 @@ -.. _tools: - -Provided Tools -============== - -Currently, :program:`gvm-tools` comes with three command line interface -programs: - -* :ref:`gvm-cli ` -* :ref:`gvm-script ` -* :ref:`gvm-pyshell ` - -All of these programs are clients communicating either via -:term:`Greenbone Management Protocol (GMP) ` -or :term:`Open Scanner Protocol (OSP) `. The -:ref:`connection ` is established using a -:ref:`TLS `, :ref:`SSH ` or -:ref:`Unix Domain Socket ` communication channel. - -All tools take several arguments and parameters. :program:`gvm-tools` allows -setting defaults for most of these in a configuration file. See :doc:`config` -for details about the possible settings and capabilities. - -.. _gvm_cli: - -gvm-cli -------- - -:program:`gvm-cli` is a low level tool which offers sending and receiving -commands and responses for the XML-based :term:`GMP ` and :term:`OSP ` -directly via the command line. It is intended for :ref:`simple scripting ` -via shell. - -.. code-block:: shell - - > gvm-cli --help - usage: gvm-cli [-h] [-c [CONFIG]] - [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] - [--timeout TIMEOUT] [--gmp-username GMP_USERNAME] - [--gmp-password GMP_PASSWORD] [-V] - CONNECTION_TYPE ... - - optional arguments: - -h, --help show this help message and exit - -c [CONFIG], --config [CONFIG] - Configuration file path (default: ~/.config/gvm- - tools.conf) - --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}] - Activate logging (default level: None) - --timeout TIMEOUT Response timeout in seconds, or -1 to wait - indefinitely (default: 60) - --gmp-username GMP_USERNAME - Username for GMP service (default: '') - --gmp-password GMP_PASSWORD - Password for GMP service (default: '') - -V, --version Show version information and exit - - connections: - valid connection types - - CONNECTION_TYPE Connection type to use - ssh Use SSH to connect to service - tls Use TLS secured connection to connect to service - socket Use UNIX Domain socket to connect to service - - -Examples: - -.. code-block:: shell - - > gvm-cli socket --xml "" - 7.0 - - > gvm-cli socket --xml "" - - ... - - - > gvm-cli socket < commands.xml - - -.. _gvm_script: - -gvm-script ----------- - -.. versionadded:: 2.0 - -:program:`gvm-script` allows running :ref:`gvm scripts ` -which are Python based scripts calling the `python-gvm API`_. Depending on the -:command:`--protocol` argument a global gmp or osp object is passed to the -script. - -.. note:: :program:`gvm-script` is only available with :program:`gvm-tools` version 2.0 and beyond. - -.. code-block:: shell - - usage: gvm-script [-h] [-c [CONFIG]] - [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] - [--timeout TIMEOUT] [--gmp-username GMP_USERNAME] - [--gmp-password GMP_PASSWORD] [-V] [--protocol {GMP,OSP}] - CONNECTION_TYPE ... - - optional arguments: - -h, --help show this help message and exit - -c [CONFIG], --config [CONFIG] - Configuration file path (default: ~/.config/gvm- - tools.conf) - --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}] - Activate logging (default level: None) - --timeout TIMEOUT Response timeout in seconds, or -1 to wait - indefinitely (default: 60) - --gmp-username GMP_USERNAME - Username for GMP service (default: '') - --gmp-password GMP_PASSWORD - Password for GMP service (default: '') - -V, --version Show version information and exit - --protocol {GMP,OSP} Service protocol to use (default: GMP) - - connections: - valid connection types - - CONNECTION_TYPE Connection type to use - ssh Use SSH to connect to service - tls Use TLS secured connection to connect to service - socket Use UNIX Domain socket to connect to service - - -.. _gvm_pyshell: - -gvm-pyshell ------------ - -:program:`gvm-pyshell` is a tool to use the `python-gvm API`_ interactively. -Running the tool will open a Python interpreter in the `interactive mode -`_ -providing a global gmp or osp object depending on the :command:`--protocol` -argument. - -The interactive shell can be exited with: - -* :kbd:`Ctrl+D` on Linux or -* :kbd:`Ctrl+Z` on Windows - -.. code-block:: shell - - > gvm-pyshell --help - usage: gvm-pyshell [-h] [-c [CONFIG]] - [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] - [--timeout TIMEOUT] [--gmp-username GMP_USERNAME] - [--gmp-password GMP_PASSWORD] [-V] [--protocol {GMP,OSP}] - CONNECTION_TYPE ... - - optional arguments: - -h, --help show this help message and exit - -c [CONFIG], --config [CONFIG] - Configuration file path (default: ~/.config/gvm- - tools.conf) - --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}] - Activate logging (default level: None) - --timeout TIMEOUT Response timeout in seconds, or -1 to wait - indefinitely (default: 60) - --gmp-username GMP_USERNAME - Username for GMP service (default: '') - --gmp-password GMP_PASSWORD - Password for GMP service (default: '') - -V, --version Show version information and exit - --protocol {GMP,OSP} Service protocol to use (default: GMP) - - connections: - valid connection types - - CONNECTION_TYPE Connection type to use - ssh Use SSH to connect to service - tls Use TLS secured connection to connect to service - socket Use UNIX Domain socket to connect to service - - -Example: - -.. code-block:: python - - > gvm-pyshell socket - GVM Interactive Console 2.0.0 API 1.0.0. Type "help" to get information about functionality. - >>> gmp.get_protocol_version() - '7' - >>> gmp.get_version().get('status') - '200' - >>> gmp.get_version()[0].text - '7.0' - >>> [t.find('name').text for t in tasks.xpath('task')] - ['Scan Task', 'Simple Scan', 'Host Discovery'] - -.. _python-gvm API: https://greenbone.github.io/python-gvm/ diff --git a/poetry.lock b/poetry.lock index b4ed3acd..0a233f60 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1025,6 +1025,25 @@ files = [ {file = "mccabe-0.7.0.tar.gz", hash = "sha256:348e0240c33b60bbdf4e523192ef919f28cb2c3d7d5c7794f74009290f236325"}, ] +[[package]] +name = "mdit-py-plugins" +version = "0.4.0" +description = "Collection of plugins for markdown-it-py" +optional = false +python-versions = ">=3.8" +files = [ + {file = "mdit_py_plugins-0.4.0-py3-none-any.whl", hash = "sha256:b51b3bb70691f57f974e257e367107857a93b36f322a9e6d44ca5bf28ec2def9"}, + {file = "mdit_py_plugins-0.4.0.tar.gz", hash = "sha256:d8ab27e9aed6c38aa716819fedfde15ca275715955f8a185a8e1cf90fb1d2c1b"}, +] + +[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" @@ -1047,6 +1066,32 @@ files = [ {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"}, ] +[[package]] +name = "myst-parser" +version = "2.0.0" +description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser," +optional = false +python-versions = ">=3.8" +files = [ + {file = "myst_parser-2.0.0-py3-none-any.whl", hash = "sha256:7c36344ae39c8e740dad7fdabf5aa6fc4897a813083c6cc9990044eb93656b14"}, + {file = "myst_parser-2.0.0.tar.gz", hash = "sha256:ea929a67a6a0b1683cdbe19b8d2e724cd7643f8aa3e7bb18dd65beac3483bead"}, +] + +[package.dependencies] +docutils = ">=0.16,<0.21" +jinja2 = "*" +markdown-it-py = ">=3.0,<4.0" +mdit-py-plugins = ">=0.4,<1.0" +pyyaml = "*" +sphinx = ">=6,<8" + +[package.extras] +code-style = ["pre-commit (>=3.0,<4.0)"] +linkify = ["linkify-it-py (>=2.0,<3.0)"] +rtd = ["ipython", "pydata-sphinx-theme (==v0.13.0rc4)", "sphinx-autodoc2 (>=0.4.2,<0.5.0)", "sphinx-book-theme (==1.0.0rc2)", "sphinx-copybutton", "sphinx-design2", "sphinx-pyscript", "sphinx-tippy (>=0.3.1)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.8.2,<0.9.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"] +testing = ["beautifulsoup4", "coverage[toml]", "pytest (>=7,<8)", "pytest-cov", "pytest-param-files (>=0.3.4,<0.4.0)", "pytest-regressions", "sphinx-pytest"] +testing-docutils = ["pygments", "pytest (>=7,<8)", "pytest-param-files (>=0.3.4,<0.4.0)"] + [[package]] name = "packaging" version = "23.1" @@ -1258,6 +1303,55 @@ gendocs = ["pytoolconfig[doc]", "sphinx (>=4.5.0)", "sphinx-autodoc-typehints (> global = ["platformdirs (>=1.4.4)"] validation = ["pydantic (>=1.7.4)"] +[[package]] +name = "pyyaml" +version = "6.0.1" +description = "YAML parser and emitter for Python" +optional = false +python-versions = ">=3.6" +files = [ + {file = "PyYAML-6.0.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d858aa552c999bc8a8d57426ed01e40bef403cd8ccdd0fc5f6f04a00414cac2a"}, + {file = "PyYAML-6.0.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:fd66fc5d0da6d9815ba2cebeb4205f95818ff4b79c3ebe268e75d961704af52f"}, + {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:69b023b2b4daa7548bcfbd4aa3da05b3a74b772db9e23b982788168117739938"}, + {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:81e0b275a9ecc9c0c0c07b4b90ba548307583c125f54d5b6946cfee6360c733d"}, + {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba336e390cd8e4d1739f42dfe9bb83a3cc2e80f567d8805e11b46f4a943f5515"}, + {file = "PyYAML-6.0.1-cp310-cp310-win32.whl", hash = "sha256:bd4af7373a854424dabd882decdc5579653d7868b8fb26dc7d0e99f823aa5924"}, + {file = "PyYAML-6.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d"}, + {file = "PyYAML-6.0.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6965a7bc3cf88e5a1c3bd2e0b5c22f8d677dc88a455344035f03399034eb3007"}, + {file = "PyYAML-6.0.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:f003ed9ad21d6a4713f0a9b5a7a0a79e08dd0f221aff4525a2be4c346ee60aab"}, + {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:42f8152b8dbc4fe7d96729ec2b99c7097d656dc1213a3229ca5383f973a5ed6d"}, + {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:062582fca9fabdd2c8b54a3ef1c978d786e0f6b3a1510e0ac93ef59e0ddae2bc"}, + {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d2b04aac4d386b172d5b9692e2d2da8de7bfb6c387fa4f801fbf6fb2e6ba4673"}, + {file = "PyYAML-6.0.1-cp311-cp311-win32.whl", hash = "sha256:1635fd110e8d85d55237ab316b5b011de701ea0f29d07611174a1b42f1444741"}, + {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"}, + {file = "PyYAML-6.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:50550eb667afee136e9a77d6dc71ae76a44df8b3e51e41b77f6de2932bfe0f47"}, + {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1fe35611261b29bd1de0070f0b2f47cb6ff71fa6595c077e42bd0c419fa27b98"}, + {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:704219a11b772aea0d8ecd7058d0082713c3562b4e271b849ad7dc4a5c90c13c"}, + {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:afd7e57eddb1a54f0f1a974bc4391af8bcce0b444685d936840f125cf046d5bd"}, + {file = "PyYAML-6.0.1-cp36-cp36m-win32.whl", hash = "sha256:fca0e3a251908a499833aa292323f32437106001d436eca0e6e7833256674585"}, + {file = "PyYAML-6.0.1-cp36-cp36m-win_amd64.whl", hash = "sha256:f22ac1c3cac4dbc50079e965eba2c1058622631e526bd9afd45fedd49ba781fa"}, + {file = "PyYAML-6.0.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:b1275ad35a5d18c62a7220633c913e1b42d44b46ee12554e5fd39c70a243d6a3"}, + {file = "PyYAML-6.0.1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:18aeb1bf9a78867dc38b259769503436b7c72f7a1f1f4c93ff9a17de54319b27"}, + {file = "PyYAML-6.0.1-cp37-cp37m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:596106435fa6ad000c2991a98fa58eeb8656ef2325d7e158344fb33864ed87e3"}, + {file = "PyYAML-6.0.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:baa90d3f661d43131ca170712d903e6295d1f7a0f595074f151c0aed377c9b9c"}, + {file = "PyYAML-6.0.1-cp37-cp37m-win32.whl", hash = "sha256:9046c58c4395dff28dd494285c82ba00b546adfc7ef001486fbf0324bc174fba"}, + {file = "PyYAML-6.0.1-cp37-cp37m-win_amd64.whl", hash = "sha256:4fb147e7a67ef577a588a0e2c17b6db51dda102c71de36f8549b6816a96e1867"}, + {file = "PyYAML-6.0.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:1d4c7e777c441b20e32f52bd377e0c409713e8bb1386e1099c2415f26e479595"}, + {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a0cd17c15d3bb3fa06978b4e8958dcdc6e0174ccea823003a106c7d4d7899ac5"}, + {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:28c119d996beec18c05208a8bd78cbe4007878c6dd15091efb73a30e90539696"}, + {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7e07cbde391ba96ab58e532ff4803f79c4129397514e1413a7dc761ccd755735"}, + {file = "PyYAML-6.0.1-cp38-cp38-win32.whl", hash = "sha256:184c5108a2aca3c5b3d3bf9395d50893a7ab82a38004c8f61c258d4428e80206"}, + {file = "PyYAML-6.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:1e2722cc9fbb45d9b87631ac70924c11d3a401b2d7f410cc0e3bbf249f2dca62"}, + {file = "PyYAML-6.0.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:9eb6caa9a297fc2c2fb8862bc5370d0303ddba53ba97e71f08023b6cd73d16a8"}, + {file = "PyYAML-6.0.1-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:c8098ddcc2a85b61647b2590f825f3db38891662cfc2fc776415143f599bb859"}, + {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5773183b6446b2c99bb77e77595dd486303b4faab2b086e7b17bc6bef28865f6"}, + {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b786eecbdf8499b9ca1d697215862083bd6d2a99965554781d0d8d1ad31e13a0"}, + {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bc1bf2925a1ecd43da378f4db9e4f799775d6367bdb94671027b73b393a7c42c"}, + {file = "PyYAML-6.0.1-cp39-cp39-win32.whl", hash = "sha256:faca3bdcf85b2fc05d06ff3fbc1f83e1391b3e724afa3feba7d13eeab355484c"}, + {file = "PyYAML-6.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:510c9deebc5c0225e8c96813043e62b680ba2f9c50a08d3724c7f28a747d1486"}, + {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"}, +] + [[package]] name = "requests" version = "2.31.0" @@ -1718,4 +1812,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = "^3.9" -content-hash = "dce69c26fe1d7155ad0d0e7c995fedcdaa4afd03e6ec628d2a4658a8adedcb37" +content-hash = "b37d1c3ccc1b9c80b362e8c0cce0b2f38a3123ebbd7b39b7e1a7dc3d3b7eea4a" diff --git a/pyproject.toml b/pyproject.toml index 30aebd74..e186c4c9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -51,6 +51,7 @@ coverage = ">=7.2" rope = ">=1.9.0" furo = ">=2023.3.27" sphinx-autobuild = ">=2021.3.14" +myst-parser = ">=2.0.0" [tool.black] line-length = 80