• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

gvmtools/H03-May-2022-1,157782

scripts/H03-May-2022-7,7435,566

tests/H03-May-2022-2,6081,996

LICENSEH A D27-Oct-202134.3 KiB675553

PKG-INFOH A D27-Oct-20217.9 KiB243175

README.mdH A D27-Oct-20216.7 KiB215149

pyproject.tomlH A D27-Oct-20212 KiB7971

setup.pyH A D03-May-20227.8 KiB3728

README.md

1![Greenbone Logo](https://www.greenbone.net/wp-content/uploads/gb_logo_resilience_horizontal.png)
2
3# Greenbone Vulnerability Management Tools <!-- omit in toc -->
4[![GitHub releases](https://img.shields.io/github/release-pre/greenbone/gvm-tools.svg)](https://github.com/greenbone/gvm-tools/releases)
5[![PyPI release](https://img.shields.io/pypi/v/gvm-tools.svg)](https://pypi.org/project/gvm-tools/)
6[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/greenbone/gvm-tools/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/greenbone/gvm-tools/?branch=master)
7[![code test coverage](https://codecov.io/gh/greenbone/gvm-tools/branch/master/graph/badge.svg)](https://codecov.io/gh/greenbone/gvm-tools)
8[![Build and test](https://github.com/greenbone/gvm-tools/actions/workflows/ci-python.yml/badge.svg)](https://github.com/greenbone/gvm-tools/actions/workflows/ci-python.yml)
9
10The Greenbone Vulnerability Management Tools `gvm-tools`
11are a collection of tools that help with remote controlling a
12Greenbone Security Manager (GSM) appliance and its underlying Greenbone
13Vulnerability Management (GVM) framework. The tools aid in accessing the
14communication protocols GMP (Greenbone Management Protocol) and OSP
15(Open Scanner Protocol).
16
17This module is comprised of interactive and non-interactive clients.
18The programming language Python is supported directly for interactive scripting.
19But it is also possible to issue remote GMP/OSP commands without programming in
20Python.
21
22
23## Table of Contents <!-- omit in toc -->
24- [Documentation](#documentation)
25- [Installation](#installation)
26  - [Version](#version)
27  - [Requirements](#requirements)
28  - [Install using pip](#install-using-pip)
29- [Usage](#usage)
30  - [gvm-cli](#gvm-cli)
31    - [Examples](#examples)
32  - [gvm-script](#gvm-script)
33    - [Example script](#example-script)
34    - [More example scripts](#more-example-scripts)
35  - [gvm-pyshell](#gvm-pyshell)
36    - [Example program use](#example-program-use)
37- [Support](#support)
38- [Maintainer](#maintainer)
39- [Contributing](#contributing)
40- [License](#license)
41
42## Documentation
43
44The documentation for `gvm-tools` can be found at
45[https://gvm-tools.readthedocs.io/](https://gvm-tools.readthedocs.io/). Please
46refer to the documentation for more details as this README just
47gives a short overview.
48
49## Installation
50
51See the [documentation](https://gvm-tools.readthedocs.io/en/latest/install.html)
52for all supported installation options.
53
54### Version
55
56Please consider to always use the **newest** version of `gvm-tools` and `python-gvm`.
57We freqently update this projects to add features and keep them free from bugs.
58This is why installing `gvm-tools` using pip is recommended.
59
60**To use `gvm-tools` with an old GMP version (7, 8, 9) you must use a release version**
61**that is `<21.06`, combined with an `python-gvm` version `<21.05`.**
62**In the `21.06` release the support of these older versions has been dropped.**
63
64### Requirements
65
66Python 3.7 and later is supported.
67
68### Install using pip
69
70You can install the latest stable release of gvm-tools from the Python Package
71Index using [pip](https://pip.pypa.io/):
72
73    pip install --user gvm-tools
74
75## Usage
76
77There are several clients to communicate via GMP/OSP.
78
79All clients have the ability to build a connection in various ways:
80
81    * Unix Socket
82    * TLS Connection
83    * SSH Connection
84
85### gvm-cli
86
87This tool sends plain GMP/OSP commands and prints the result to the standard
88output.
89
90#### Examples
91
92Return the current protocol version used by the server:
93
94```
95gvm-cli socket --xml "<get_version/>"
96```
97
98Return all tasks visible to the GMP user with the provided credentials:
99
100```
101gvm-cli --gmp-username foo --gmp-password bar socket --xml "<get_tasks/>"
102```
103
104Read a file with GMP commands and return the result:
105
106```
107gvm-cli --gmp-username foo --gmp-password bar socket myfile.xml
108```
109
110Note that `gvm-cli` will by default print an error message and exit with a
111non-zero exit code when a command is rejected by the server. If this kind of
112error handling is not desired, the unparsed XML response can be requested using
113the `--raw` parameter:
114
115```
116gvm-cli socket --raw --xml "<authenticate/>"
117
118```
119
120### gvm-script
121
122This tool has a lot more features than the simple `gvm-cli` client. You
123have the possibility to create your own custom gmp or osp scripts with commands
124from the [python-gvm library](https://github.com/greenbone/python-gvm) and from
125Python 3 itself.
126
127#### Example script
128
129```
130# Retrieve current GMP version
131version = gmp.get_version()
132
133# Prints the XML in beautiful form
134from gvmtools.helper import pretty_print
135pretty_print(version)
136
137# Retrieve all tasks
138tasks = gmp.get_tasks()
139
140# Get names of tasks
141task_names = tasks.xpath('task/name/text()')
142pretty_print(task_names)
143```
144
145#### More example scripts
146
147There is a growing collection of gmp-scripts in the
148["scripts/"](scripts/) folder.
149Some of them might be exactly what you need and all of them help writing
150your own gmp scripts.
151
152### gvm-pyshell
153
154This tool is for running gmp or osp scripts interactively. It provides the same
155API as [gvm-script](#gvm-script) using the
156[python-gvm library](https://github.com/greenbone/python-gvm).
157
158#### Example program use
159
160Connect with given credentials via a unix domain socket and open an interactive
161shell:
162
163```
164gvm-pyshell --gmp-username user --gmp-password pass socket
165```
166
167Connect through SSH connection and open the interactive shell:
168
169```
170gvm-pyshell --hostname 127.0.0.1 ssh
171```
172
173## Support
174
175For any question on the usage of `gvm-tools` or gmp scripts please use the
176[Greenbone Community Portal](https://community.greenbone.net/c/gmp). If you
177found a problem with the software, please
178[create an issue](https://github.com/greenbone/gvm-tools/issues) on GitHub.
179
180## Maintainer
181
182This project is maintained by [Greenbone Networks GmbH](https://www.greenbone.net/).
183
184## Contributing
185
186Your contributions are highly appreciated. Please
187[create a pull request](https://github.com/greenbone/gvm-tools/pulls) on GitHub.
188For bigger changes, please discuss it first in the
189[issues](https://github.com/greenbone/gvm-tools/issues).
190
191For development you should use [poetry](https://python-poetry.org/)
192to keep you python packages separated in different environments. First install
193poetry via pip
194
195    pip install --user poetry
196
197Afterwards run
198
199    poetry install
200
201in the checkout directory of `gvm-tools` (the directory containing the
202`pyproject.toml` file) to install all dependencies including the packages only
203required for development.
204
205Afterwards active the git hooks for auto-formatting and linting via
206[autohooks](https://github.com/greenbone/autohooks).
207
208    poetry run autohooks activate --force
209
210## License
211
212Copyright (C) 2017-2021 [Greenbone Networks GmbH](https://www.greenbone.net/)
213
214Licensed under the [GNU General Public License v3.0 or later](LICENSE).
215