Skip to content

Latest commit

 

History

History
344 lines (244 loc) · 13.6 KB

README.md

File metadata and controls

344 lines (244 loc) · 13.6 KB
Raw

Ansible Collection - datadope.discovery

The main goal of this collection is to provide the tools to discover the software that is running on the target hosts.

This is achieved using software_facts ansible module (actually, it is an ansible action as it is executed in the ansible controller). A role and a playbook are also provided so users of these collection may use them out-of-the-box.

Some additional modules and roles are provided as they are needed to run the software discovery.

Additional documentation for this collection is available in the docs folder.

Provided artifacts

Modules

software_facts

The main module in the collection. This module is in charge of discovering the software running in the target hosts among a set of supported software types.

As pointed before, the execution of this module is done in the controller so, it is actually an ansible action. This is possible because all the information needed to discover the software is provided to this module as input arguments. Being an action implies that the module definition is located in a python .py file located in the collection modules dir. while actual action implementation is located in action dir.

The information needed for these arguments is collected using other ansible modules, most of them are modules available in the ansible community. Some of them weren't available and have been implemented in this collection.

Although the main process of this module is run in the controller, as previously said, one of this module feature is the ability to execute custom operations to enrich the information discovered for the software instance. Some of these operations could be executed in the target hosts.

More details in Software Discovery procedure.

See definition, implementation and doc.

process_facts

This module gets the list of processes that are being executed in the target hosts.

Supported platforms

  • Linux
  • HP-UX
  • AIX
  • Solaris

See implementation and doc.

connection_facts

This module provides information of the existing connections of a Linux machine, including PID, process name and commandline.

See implementation and doc.

win_process_facts

This module provides the same information as process_facts, but it supports Windows target hosts.

Windows modules are implemented using PowerShell. But module definition must be provided in a python file.

See definition, implementation and doc.

win_package_facts

This module provides the packages installed in the target hosts. It returns the same information as ansible's core module ansible.builtin.package_facts, but it supports Windows target hosts.

Windows modules are implemented using PowerShell. But module definition must be provided in a python file.

See definition, implementation and doc.

win_hyperv_facts

This module provides target host's Hyper-V virtual machines information.

Windows modules are implemented using PowerShell. But module definition must be provided in a python file.

See definition, implementation and doc.

win_connection_facts

This module provides information of the existing connections of a Windows machine, including PID, process name and commandline.

See definition, implementation and doc.

sunos_listen_ports_facts

This module gather facts on processes listening on TCP and UDP ports. It returns the same information as ansible's community general community.general.listen_ports_facts, but it supports Solaris (SunOS)target hosts.

See implementation and doc.

file_parser

This module provides tools to parse different types of configuration files.

Supported software configuration files types

  • Apache Webserver
  • HAProxy
  • Keepalived
  • nginx

See implementation and doc.

check_connection

This module tries to establish a connection from the target host to the port of an address and check if the connection can be established.

See implementation and doc.

snmp_facts

This module provides information about a device through the SNMP protocol by providing a template with the OIDs configured.

See implementation and doc.

Roles

software_discovery

This role executes all the steps to discover the software running in the target hosts. It reads the necessary input data: processes, packages, docker containers,... from the target and passes the obtained information to the software_discovery module.

See implementation and doc.

docker_containers

This role is in charge of obtaining the docker containers running in the target host (if docker is running in the hosts). This information is an input for the software_discovery module.

This role tries to use modules from ansible's community.docker collection to get the data. But modules of this collection require a python library that is not always installed in the target machine, so a fallback mechanism has been implemented using ansible command module to execute the CLI command docker. Both mechanisms return the same information of the discovered docker containers.

See implementation and doc.

hyperv_vms

This role checks if the target machine runs Hyper-V. If the result is positive, then it starts the Hyper-V virtual machine's information extraction.

See implementation and doc.

snmp_discovery

This role executes a SNMP discovery in every target host. It will try to discover the device using the IP and UDP port through the SNMP protocol and provide valuable information about the network devices.

See implementation and doc.

connections_discovery

This role automatically runs the corresponding connection facts module for the target host according to the operating system (Windows or Linux). The information gathered is provided as an ansible fact with key connections that will contain a list of connections.

See implementation and doc.

Playbooks

software_discovery.yml

This playbook is an out-of-the-box playbook to run the software_discovery role and execute discovery in the target hosts determined by the ansible inventory.

Additionally, it provides the capability to generate output files that may be used as skeletons to create unit tests to test the discovery of a software type procedure.

See implementation and doc.

Other artifacts

Filters path_join and split have been implemented to support versions of ansible before their builtin support.

Software Discovery procedure

Providing a command line regex (cmd_regexp) to identify the running software instance may be enough to support a new software type. Although more information would be needed to get more detailed info about the discovered software such as configuration options, running databases,... Most of this extra information will depend on the type of software so a mechanism for running customized operations for each software type has been implemented. Field custom_tasks is used to get these operations that will be executed to enrich the information collected for each software instance.

Without custom tasks, some information will be available for every discovered software, such as:

  • The main OS process associated to the software instance.
  • Port or ports where the software instance is listening.
  • If the software instance is running in a docker container, information about that container.
  • The package or packages used to install the software (if available).
  • Some version info obtained from the docker or the packages.

This information can be enriched with custom information for each software type. The additional information provided for each software will depend on the software type.

There would be two ways to implement these custom operations:

  • Provide a python module implementing SoftwareDiscoveryPlugin that executes these custom operations. Only one custom task executing this plugin would be needed.
  • Use the provided plugins to create a list of tasks that perform the operations needed to obtain the desired data.

The latter option is the preferred one as the custom operations are defined in a declarative way, using yaml the same way as for creating ansible roles. So it will be easy for ansible users to understand and create these custom tasks.

Creating python plugins should be used only when there's no way to implement an operation using current plugins, or it will be difficult and the readability of the custom tasks will be affected significantly.

Detailed information about creating custom tasks can be found in customization.md.

Supported software types

Supported software types must be included in the variable software_discovery__software_list at software_discovery role default vars because this is the default value of this var, and it is the one used by the role or playbook (if not explicitly overridden).

  • AWX Task
  • AWX Web
  • Apache ActiveMQ
  • Apache Tomcat Servlet Engine
  • Apache WebServer
  • Chrony ntp service
  • Docker
  • Dynatrace Server
  • ElasticSearch
  • Filebeat
  • Grafana
  • HAProxy
  • HPE Data Protector
  • Hobbit
  • IIS
  • IOMetrics SLAtor
  • IOMetrics Visualizer API
  • InfluxDB
  • JBoss Application Server
  • Jolokia Proxy
  • KeepAliveD
  • Logstash
  • MariaDB DatabaseServer
  • Memcached
  • Microsoft SQL Server
  • MongoDB
  • MuleSoft AppServer
  • MySQL DatabaseServer
  • Nagios NRPE
  • Nginx WebServer
  • Oracle DatabaseServer
  • Oracle Listener
  • Oracle Management Agent
  • PHP-fpm
  • Panda Security Protection
  • Patrol Agent
  • Patroni
  • PostgreSQL Database
  • Redis
  • SAP CCMS
  • SAP HANA DatabaseServer
  • SAPcontrol
  • Skydive Analyzer
  • Sybase ASE
  • Sybase IQ
  • Sybase Replication Server
  • Telegraf
  • Xymon
  • Zabbix Server

License

GNU General Public License v3.0 or later

See COPYING to see the full text.

Author Information

Datadope (@datadope-io)

You can contact Datadope in info@datadope.io.

Contribution

Please send suggestions or pull requests to make this collection better.

We plan to increase the number of supported software types and platforms, but the necessities and priorities are very different, so we will be very happy to receive contributions for new software types support, enrich already supported software types, improvements, issues...

You can find more information on how to develop and test this collection in docs/development_environment.md.

How to implement a new software type and execute custom tasks to provide specific information for a discovered software instance is deeply explained in docs/customization.md and how to create tests for new software types is explained in docs/creating_auto_test.md.

See CONTRIBUTING.md for more information about contribution guidelines.

Please, contact us if you need more information to submit your contributions.