Name | Date | Size | #Lines | LOC | ||
---|---|---|---|---|---|---|
.. | 03-May-2022 | - | ||||
gvmtools/ | H | 03-May-2022 | - | 1,157 | 782 | |
scripts/ | H | 03-May-2022 | - | 7,743 | 5,566 | |
tests/ | H | 03-May-2022 | - | 2,608 | 1,996 | |
LICENSE | H A D | 27-Oct-2021 | 34.3 KiB | 675 | 553 | |
PKG-INFO | H A D | 27-Oct-2021 | 7.9 KiB | 243 | 175 | |
README.md | H A D | 27-Oct-2021 | 6.7 KiB | 215 | 149 | |
pyproject.toml | H A D | 27-Oct-2021 | 2 KiB | 79 | 71 | |
setup.py | H A D | 03-May-2022 | 7.8 KiB | 37 | 28 |
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