Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update YAML configuration file examples of qa-ctl use guide documentation #2071

Closed
Tracked by #2021
, #2299
...
fernandolojano opened this issue Oct 19, 2021 · 3 comments
Closed
Tracked by #2021
, #2299
...

Update YAML configuration file examples of qa-ctl use guide documentation #2071

fernandolojano opened this issue Oct 19, 2021 · 3 comments
Assignees
@fernandolojano
Labels
docs Add or improve documentation tool/qactl

Comments

@fernandolojano
Copy link
Contributor

fernandolojano commented Oct 19, 2021 •
edited
Loading

The current YAML configuration file examples given in the use guide documentation for qa-ctl were created for a previous version of the tool, so these examples aren't working when using them as configuration files for the new version. It is needed to update the examples of the documentation so they can be used without any possible errors
@fernandolojano fernandolojano self-assigned this Oct 19, 2021
@fernandolojano fernandolojano changed the title QA-CTL: Update yaml configuration files example of qa-ctl use guide QA-CTL: Update YAML configuration files example of qa-ctl use guide Oct 19, 2021
@fernandolojano fernandolojano added qa-ctl/v0.2 docs Add or improve documentation labels Oct 19, 2021
@fernandolojano fernandolojano changed the title QA-CTL: Update YAML configuration files example of qa-ctl use guide Update YAML configuration files example of qa-ctl use guide documentation Oct 19, 2021
@fernandolojano fernandolojano changed the title Update YAML configuration files example of qa-ctl use guide documentation Update YAML configuration file examples of qa-ctl use guide documentation Oct 19, 2021
@jmv74211 jmv74211 mentioned this issue Oct 20, 2021
Closed
22 tasks
@fernandolojano
Copy link
Contributor Author

As for now, this is the new YAML configuration examples approach. As it can be seen, more examples were added in order to cover all possible use cases for every section.

YAML configuration file examples

Now, there are going to be shown some examples of YAML files separated by use cases.

Deployment section

  • Deploying a vagrant box with the Ubuntu 20.04 system provided by qa-ctl team:

    yaml configuration 
    deployment:
  host_1:
    provider:
      vagrant:
        enabled: true
        vagrantfile_path: /tmp/wazuh_qa_ctl
        vagrant_box: qactl/ubuntu_20_04
        vm_memory: 1024
        vm_cpu: 1
        vm_name: test1
        vm_system: linux
        label: test1
        vm_ip: 10.150.50.2

  • Deploying a vagrant box with the CentOS 8 system provided by qa-ctl team:

    yaml configuration 
    deployment:
  host_1:
    provider:
      vagrant:
        enabled: true
        vagrantfile_path: /tmp/wazuh_qa_ctl
        vagrant_box: qactl/centos_8
        vm_memory: 1024
        vm_cpu: 1
        vm_name: test2
        vm_system: linux
        label: test2
        vm_ip: 10.150.50.20

Provision section

For all of the next examples, the Wazuh branch from where the QA framework will be downloaded is master, if a different branch is needed, you only need to modify the field called wazuh_qa_branch.

Wazuh Manager case uses

  • Provisioning a vagrant machine with Wazuh manager using an S3 URL :

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.2
      wazuh_deployment:
        type: package
        target: manager
        s3_package_url: https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-manager/wazuh-manager_4.2.3-1_amd64.deb
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

  • Provisioning a vagrant machine with a Wazuh manager using a local existent package:

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.2
      wazuh_deployment:
        type: package
        target: manager
        local_package_path: /tmp/wazuh-manager_4.2.3-1_amd64.deb
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

  • Provisioning a vagrant machine with a Wazuh manager obtained from the sources of the Wazuh repository:

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.2
      wazuh_deployment:
        type: sources
        target: manager
        wazuh_branch: master # Will be used for obtaining the wazuh installation files
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

  • Provisioning a vagrant machine with a Wazuh manager using a specific system, version, revision and repository:

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.2
      wazuh_deployment:
        type: package
        target: manager
        system: deb
        version: 4.2.4
        revision: 0.10557
        repository: test
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

Wazuh Agent case uses

  • Provisioning a vagrant machine with Wazuh agent using an S3 URL:

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.3
      wazuh_deployment:
        type: package
        target: agent
        manager_ip: 10.150.50.2
        s3_package_url: https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.2.4-1_arm64.deb
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

  • Provisioning a vagrant machine with a Wazuh agent using a local existent package:

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.3
      wazuh_deployment:
        type: package
        target: agent
        manager_ip: 10.150.50.2
        local_package_path: /tmp/wazuh-agent_4.2.4-1_arm64.deb
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

  • Provisioning a vagrant machine with a Wazuh agent obtained from the sources of the Wazuh repository.

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.3
      wazuh_deployment:
        type: sources
        target: agent
        manager_ip: 10.150.50.2
        wazuh_branch: master # Will be used for obtaining the wazuh installation files
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

  • Provisioning a vagrant machine with a Wazuh agent using a specific system, version, revision and repository:

    yaml configuration 
    provision:
  hosts:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.3
      wazuh_deployment:
        type: package
        target: agent
        system: deb
        version: 4.2.4
        revision: 0.10557
        repository: test
        installation_files_path: /tmp
        health_check: true
      qa_framework:
        wazuh_qa_branch: master
        qa_workdir: /tmp/wazuh_qa_ctl

Testing section

  • Run test general_settings_enabled in a Wazuh manager from a vagrant box

    yaml configuration 
    tests:
  host_1:
    host_info:
      connection_method: ssh
      user: vagrant
      password: vagrant
      connection_port: 22
      ansible_python_interpreter: /usr/bin/python3
      system: deb
      installation_files_path: /tmp
      host: 10.150.50.2
    test:
      type: pytest
      path:
        test_files_path: /wazuh-qa/tests/integration/test_vulnerability_detector/test_general_settings/test_general_settings_enabled.py
        run_tests_dir_path: /wazuh-qa/test/integration
        test_results_path: /tmp/wazuh_qa_ctl/test_general_settings_enabled_resutls/

  • Run test cors in a Wazuh manager from a vagrant box

    yaml configuration 
    tests:
  host_1:
    host_info:
      connection_method: ssh
      user: vagrant
      password: vagrant
      connection_port: 22
      ansible_python_interpreter: /usr/bin/python3
      system: deb
      installation_files_path: /tmp
      host: 10.150.50.2
    test:
      type: pytest
      path:
        test_files_path: /wazuh-qa/tests/integration/test_api/test_config/test_cors/test_cors.py
        run_tests_dir_path: /wazuh-qa/test/integration
        test_results_path: /tmp/wazuh_qa_ctl/test_general_settings_enabled_resutls/

  • Run test cors in a Wazuh manager from a vagrant box

    yaml configuration 
    tests:
  host_1:
    host_info:
      connection_method: ssh
      user: vagrant
      password: vagrant
      connection_port: 22
      ansible_python_interpreter: /usr/bin/python3
      system: deb
      installation_files_path: /tmp
      host: 10.150.50.2
    test:
      type: pytest
      path:
        test_files_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration/test_active_response/test_execd/test_execd_restart.py
      run_tests_dir_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration
      test_results_path: /tmp/wazuh_qa_ctl/test_execd_restart_results

  • Run test cache in a Wazuh manager from a vagrant box

    yaml configuration 
    tests:
  host_1:
    host_info:
      connection_method: ssh
      user: vagrant
      password: vagrant
      connection_port: 22
      ansible_python_interpreter: /usr/bin/python3
      system: deb
      installation_files_path: /tmp
      host: 10.150.50.2
    test:
      type: pytest
      path:
        test_files_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration/test_api/test_config/test_cache/test_cache.py
      run_tests_dir_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration
      test_results_path: /tmp/wazuh_qa_ctl/test_cache_resutls

  • Run test execd_firewall_drop in a Wazuh manager from a vagrant box

    yaml configuration 
    tests:
  host_1:
    host_info:
      connection_method: ssh
      user: vagrant
      password: vagrant
      connection_port: 22
      ansible_python_interpreter: /usr/bin/python3
      system: deb
      installation_files_path: /tmp
      host: 10.150.50.2
    test:
      type: pytest
      path:
        test_files_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration/test_active_response/test_execd/test_execd_firewall_drop.py
      run_tests_dir_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration
      test_results_path: /tmp/wazuh_qa_ctl/test_execd_firewall_drop_results

@fernandolojano
Copy link
Contributor Author

There are some things worth mentioning:

  • While this task was being done, there has been discovered some new parameters that qa-ctl is using but aren't registered in the qa-ctl schema validator, thus, there is no validation for the new parameters. As a result, the schema might need to be updated
  • Now there are examples for almost every case of use. However, there might be more complex cases that aren't mentioned in this list and that might need to be added as well.
  • As this new approach covers all the sections, the examples of a complete YAML file configuration have been discarded, but It might be useful to add full examples with all the qa-ctl sections (Deployment, provisioning and testing). That is an idea that needs to be discussed in the qa-ctl team.

@fernandolojano
Copy link
Contributor Author

fernandolojano commented Oct 28, 2021 •
edited
Loading

As for now, this is the new YAML configuration examples approach. As it can be seen, more examples were added to cover all possible use cases for every section.

YAML configuration file examples

Now, there are going to be shown some examples of YAML files separated by use cases.

Deployment section

The most mentionable fields for the deployment section are vagrant_box and vagrantfile_path.
These fields are used to determine the name of the box and the location of the vagrantfile that is going to be used. As for the vagrant_box field, any available box can be used, but qa-ctl provides some boxes that are ready to use with this tool. The name of these boxes are: qactl/ubuntu_20_04, qactl/centos_8 and qactl/windows_2019

  • Deploying a single virtual machine instance:

    yaml configuration 
    deployment:
  host_1:
    provider:
      vagrant:
        enabled: true
        vagrantfile_path: /tmp/wazuh_qa_ctl
        vagrant_box: qactl/ubuntu_20_04  # Any vagrant box can be used
        vm_memory: 512
        vm_cpu: 1
        vm_name: test1
        vm_system: linux
        label: test1
        vm_ip: 10.150.50.2

  • Deploying multiple virtual machines at once:

    yaml configuration 
    deployment:
  host_1:
    provider:
      vagrant:
        enabled: true
        vagrantfile_path: /tmp/wazuh_qa_ctl
        vagrant_box: qactl/centos_8
        vm_memory: 1024
        vm_cpu: 1
        vm_name: test2
        vm_system: linux
        label: test2
        vm_ip: 10.150.50.10
  host_2:
    provider:
      vagrant:
        enabled: true
        vagrantfile_path: /tmp/wazuh_qa_ctl
        vagrant_box: windows_server
        vm_memory: 2048
        vm_cpu: 2
        vm_name: test3
        vm_system: windows
        label: test3
        vm_ip: 10.150.50.11

Important note: The vm_name can not be repeated, every deployed instance has to have a different name. The IP declared in the field vm_ip cannot be used by two VMs at the same time.

Provision section

This yaml section has three different sub-sections: host_info, wazuh_deployment and qa_framework

Host info section

This section contains the necessary information for being able to make a connection with the host where the provisioning stage is going to be made. The host_info section is always required and its absence will make the qa-ctl validation parameters stage fail.

yaml configuration 
  host_info:
    connection_method: ssh  # Or winrm for windows virtual machines
    user: vagrant
    password: vagrant
    connection_port: 22
    ansible_python_interpreter: /usr/bin/python3
    system: deb # This field changes depending on the system of the VM
    installation_files_path: /tmp
    host: 10.150.50.2 # IP from the VM

Wazuh deployment section

This section handles all the info needed for provisioning the VM host with Wazuh manager or agent. There are several ways to install Wazuh: using an S3 URL, from a local downloaded package, from the file sources available on the wazuh repository and by using a specific system, version, revision and repository.

  • Provisioning an instance with Wazuh manager using an S3 URL:

    yaml configuration 
      wazuh_deployment:
    type: package
    target: manager
    s3_package_url: https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-manager/wazuh-manager_4.2.3-1_amd64.deb
    installation_files_path: /tmp
    wazuh_install_path: /var/ossec # This is an optional field
    health_check: true # This is an optional field

  • Provisioning an instance with a Wazuh manager using a local existent package:

    yaml configuration 
      wazuh_deployment:
    type: package
    target: manager
    local_package_path: /tmp/wazuh-manager_4.2.3-1_amd64.deb
    installation_files_path: /tmp

  • Provisioning an instance with a Wazuh manager obtained from the sources of the Wazuh repository:

    yaml configuration 
      wazuh_deployment:
    type: sources
    target: manager
    wazuh_branch: master # Will be used for obtaining the wazuh installation files
    installation_files_path: /tmp

  • Provisioning an instance with a Wazuh manager using a specific system, version, revision and repository:

    yaml configuration 
      wazuh_deployment:
    type: package
    target: manager
    system: deb
    version: 4.2.4
    revision: 0.10557
    repository: test
    installation_files_path: /tmp

  • Provisioning an instance with Wazuh agent:

    yaml configuration 
      wazuh_deployment:
    type: package
    target: agent
    manager_ip: 10.150.50.2
    s3_package_url: https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-manager/wazuh-agent.2.3-1_amd64.deb
    installation_files_path: /tmp

Important note: For provisioning, a host with a Wazuh agent, the field target needs to be changed to agent and there will be a new field required called manager_ip that indicates the IP of the manager that the new agent will be connected with.

QA framework section

This section is used for provisioning the host with the Framework of QA. The example given below is a generic one that will use the master branch for getting the repository files, and locate them in the path specified in the qa_workdir field.

yaml configuration 
  qa_framework:
    wazuh_qa_branch: master
    qa_workdir: /tmp/wazuh_qa_ctl

Testing section

The Testing is composed with an always required host_info section that contains the same fields as the Provisioning stage host_info section. Plus, there is a section called test with the fields needed for launching a test.

  • Run test cors

    yaml configuration 
      test:
    type: pytest # As for now, this is the only available type
    path:
      test_files_path: /wazuh-qa/tests/integration/test_api/test_config/test_cors/test_cors.py # Full location path of the test 
      run_tests_dir_path: /wazuh-qa/test/integration                                           # Path to the folder where to run the tests
      test_results_path: /tmp/wazuh_qa_ctl/test_general_settings_enabled_resutls/              # Path where the results of the tests will be stored

Note: The fields test_files_path and run_test_dir_path are paths that are going to be used in the VM instance, whereas the test_results_path is a path that is going to be used in the host machine where qa-ctl was launched.

Complete YAML configuration files examples

Here you can find some examples of YAML configuration files that are fully completed on every section and ready to use.

  • Run test cache

    yaml configuration 
      deployment:
    host_1:
      provider:
        vagrant:
          enabled: true
          vagrantfile_path: /tmp/wazuh_qa_ctl
          vagrant_box: qactl/ubuntu_20_04
          vm_memory: 1024
          vm_cpu: 1
          vm_name: manager_test_cache_1635415018.925661
          vm_system: linux
          label: manager_test_cache_1635415018.925661
          vm_ip: 10.150.50.2
  provision:
    hosts:
      host_1:
        host_info:
          connection_method: ssh
          user: vagrant
          password: vagrant
          connection_port: 22
          ansible_python_interpreter: /usr/bin/python3
          system: deb
          installation_files_path: /tmp
          host: 10.150.50.2
        wazuh_deployment:
          type: package
          target: manager
          s3_package_url: https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-manager/wazuh-manager_4.2.4-1_amd64.deb
          installation_files_path: /tmp
          health_check: true
        qa_framework:
          wazuh_qa_branch: 2023-qa-ctl-documented-test-validation
          qa_workdir: /tmp/wazuh_qa_ctl
  tests:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.2
      test:
        type: pytest
        path:
          test_files_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration/test_api/test_config/test_cache/test_cache.py
          run_tests_dir_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration
          test_results_path: /tmp/wazuh_qa_ctl/test_cache_1635415018.92588

  • Run test execd restart

    yaml configuration 
      deployment:
    host_1:
      provider:
        vagrant:
          enabled: true
          vagrantfile_path: /tmp/wazuh_qa_ctl
          vagrant_box: qactl/ubuntu_20_04
          vm_memory: 1024
          vm_cpu: 1
          vm_name: agent_test_execd_restart_1635415139.489418
          vm_system: linux
          label: agent_test_execd_restart_1635415139.489418
          vm_ip: 10.150.50.3
    host_2:
      provider:
        vagrant:
          enabled: true
          vagrantfile_path: /tmp/wazuh_qa_ctl
          vagrant_box: qactl/ubuntu_20_04
          vm_memory: 1024
          vm_cpu: 1
          vm_name: manager_test_execd_restart_1635415139.489418
          vm_system: linux
          label: manager_test_execd_restart_1635415139.489418
          vm_ip: 10.150.50.4
  provision:
    hosts:
      host_1:
        host_info:
          connection_method: ssh
          user: vagrant
          password: vagrant
          connection_port: 22
          ansible_python_interpreter: /usr/bin/python3
          system: deb
          installation_files_path: /tmp
          host: 10.150.50.3
        wazuh_deployment:
          type: package
          target: agent
          s3_package_url: https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.2.4-1_amd64.deb
          installation_files_path: /tmp
          health_check: true
          manager_ip: 10.150.50.4
        qa_framework:
          wazuh_qa_branch: 2023-qa-ctl-documented-test-validation
          qa_workdir: /tmp/wazuh_qa_ctl
      host_2:
        host_info:
          connection_method: ssh
          user: vagrant
          password: vagrant
          connection_port: 22
          ansible_python_interpreter: /usr/bin/python3
          system: deb
          installation_files_path: /tmp
          host: 10.150.50.4
        wazuh_deployment:
          type: package
          target: manager
          s3_package_url: https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-manager/wazuh-manager_4.2.4-1_amd64.deb
          installation_files_path: /tmp
          health_check: true
        qa_framework:
          wazuh_qa_branch: 2023-qa-ctl-documented-test-validation
          qa_workdir: /tmp/wazuh_qa_ctl
  tests:
    host_1:
      host_info:
        connection_method: ssh
        user: vagrant
        password: vagrant
        connection_port: 22
        ansible_python_interpreter: /usr/bin/python3
        system: deb
        installation_files_path: /tmp
        host: 10.150.50.3
      test:
        type: pytest
        path:
          test_files_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration/test_active_response/test_execd/test_execd_restart.py
          run_tests_dir_path: /tmp/wazuh_qa_ctl/wazuh-qa/tests/integration
          test_results_path: /tmp/wazuh_qa_ctl/test_execd_restart_1635415139.489715

@jmv74211 jmv74211 closed this as completed Nov 4, 2021
@jmv74211 jmv74211 mentioned this issue Dec 3, 2021
Merged
60 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@fernandolojano fernandolojano

Labels
docs Add or improve documentation tool/qactl
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@jmv74211 @fernandolojano