Added win_reg_stat module (#19145)

CHANGELOG.md

@@ -238,6 +238,7 @@ Ansible Changes By Release
   * win_find
   * win_path
   * win_psexec
+  * win_reg_stat
   * win_say
   * win_shortcut
 - xbps

lib/ansible/modules/windows/win_reg_stat.ps1

@@ -0,0 +1,150 @@
+#!powershell
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# WANT_JSON
+# POWERSHELL_COMMON
+
+$ErrorActionPreference = "Stop"
+
+$params = Parse-Args $args -supports_check_mode $true
+$key = Get-AnsibleParam $params "key" -FailIfEmpty $true
+$property = Get-AnsibleParam $params "property" -FailIfEmpty $false -default $null
+
+$result = @{
+    win_reg_stat = @{}
+    changed = $false
+    warnings = @()
+}
+
+Function Get-NetHiveName($hive) {
+    # Will also check that the hive passed in the path is a known hive
+    switch ($hive.ToUpper()) {
+        "HKCR" {"ClassesRoot"}
+        "HKCC" {"CurrentConfig"}
+        "HKCU" {"CurrentUser"}
+        "HKLM" {"LocalMachine"}
+        "HKU" {"Users"}        
+        default {"unsupported"}
+    }
+}
+
+Function Get-PropertyType($hive, $path, $property) {
+    $type = (Get-Item REGISTRY::$hive\$path).GetValueKind($property)
+    switch ($type) {
+        "Binary" {"REG_BINARY"}
+        "String" {"REG_SZ"}
+        "DWord" {"REG_DWORD"}
+        "QWord" {"REG_QWORD"}
+        "MultiString" {"REG_MULTI_SZ"}
+        "ExpandString" {"REG_EXPAND_SZ"}
+        "None" {"REG_NONE"}
+        default {"Unknown"}
+    }
+}
+
+Function Get-PropertyObject($hive, $net_hive, $path, $property) {
+    $value = (Get-ItemProperty REGISTRY::$hive\$path).$property
+    $type = Get-PropertyType -hive $hive -path $path -property $property
+    If ($type -eq 'REG_EXPAND_SZ') {
+        $raw_value = [Microsoft.Win32.Registry]::$net_hive.OpenSubKey($path).GetValue($property, $false, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+    } ElseIf ($type -eq 'REG_BINARY' -or $type -eq 'REG_NONE') {
+        $raw_value = @()
+        foreach ($byte in $value) {
+            $hex_value = ('{0:x}' -f $byte).PadLeft(2, '0')
+            $raw_value += "0x$hex_value"
+        }
+    } Else {
+        $raw_value = $value
+    }
+
+    $object = New-Object PSObject @{
+        raw_value = $raw_value
+        value = $value
+        type = $type
+    }
+
+    $object
+}
+
+Function Test-RegistryProperty($hive, $path, $property) {
+    Try {
+        $type = (Get-Item REGISTRY::$hive\$path).GetValueKind($property)
+    } Catch {
+        $type = $null
+    }
+
+    If ($type -eq $null) {
+        $false
+    } Else {
+        $true
+    }
+}
+
+# Will validate the key parameter to make sure it matches known format
+if ($key -match "^([a-zA-Z_]*):\\(.*)$") {
+    $hive = $matches[1]
+    $path = $matches[2]
+} else {
+    Fail-Json $result "key does not match format 'HIVE:\KEY_PATH'"
+}
+
+# Used when getting the actual REG_EXPAND_SZ value as well as checking the hive is a known value
+$net_hive = Get-NetHiveName -hive $hive
+if ($net_hive -eq 'unsupported') {
+    Fail-Json $result "the hive in key is '$hive'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
+}
+
+if (Test-Path REGISTRY::$hive\$path) {
+    if ($property -eq $null) {
+        $property_info = @{}
+        $properties = Get-ItemProperty REGISTRY::$hive\$path
+
+        foreach ($property in $properties.PSObject.Properties) {
+            # Powershell adds in some metadata we need to filter out
+            $real_property = Test-RegistryProperty -hive $hive -path $path -property $property.Name
+            if ($real_property -eq $true) {
+                $property_object = Get-PropertyObject -hive $hive -net_hive $net_hive -path $path -property $property.Name 
+                $property_info.Add($property.Name, $property_object)
+            }            
+        }
+
+        $sub_keys = @()
+        $sub_keys_raw = Get-ChildItem REGISTRY::$hive\$path -ErrorAction SilentlyContinue
+
+        foreach ($sub_key in $sub_keys_raw) {
+            $sub_keys += $sub_key.PSChildName
+        }
+
+        $result.win_reg_stat.exists = $true
+        $result.win_reg_stat.sub_keys = $sub_keys
+        $result.win_reg_stat.properties = $property_info
+    } else {
+        $exists = Test-RegistryProperty -hive $hive -path $path -property $property
+        if ($exists -eq $true) {
+            $propertyObject = Get-PropertyObject -hive $hive -net_hive $net_hive -path $path -property $property
+            $result.win_reg_stat.exists = $true
+            $result.win_reg_stat.raw_value = $propertyObject.raw_value
+            $result.win_reg_stat.value = $propertyObject.value
+            $result.win_reg_stat.type = $propertyObject.type
+        } else {
+            $result.win_reg_stat.exists = $false
+        }
+    }
+} else {
+    $result.win_reg_stat.exists = $false
+}
+
+Exit-Json $result

lib/ansible/modules/windows/win_reg_stat.py

@@ -0,0 +1,120 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2016, Ansible, inc
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# this is a windows documentation stub.  actual code lives in the .ps1
+# file of the same name
+
+ANSIBLE_METADATA = {'status': ['preview'],
+                    'supported_by': 'community',
+                    'version': '1.0'}
+
+DOCUMENTATION = r'''
+---
+module: win_reg_stat
+version_added: "2.3"
+short_description: returns information about a Windows registry key or property of a key
+description:
+- Like M(win_file), M(win_reg_stat) will return whether the key/property exists.
+- It also returns the sub keys and properties of the key specified.
+- If specifying a property name through I(property), it will return the information specific for that property.
+options:
+    key:
+        description:
+        - The full registry key path including the hive to search for.
+        required: true
+    property:
+        description:
+        - The registry property name to get information for, the return json will not include the sub_keys and properties entries for the I(key) specified.
+        required: false
+
+author: "Jordan Borean (@jborean93)"
+'''
+
+EXAMPLES = r'''
+# Obtain information about a registry key using short form
+- win_reg_stat:
+    key: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
+  register: current_version
+
+# Obtain information about a registry key property
+- win_reg_stat:
+    key: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
+    property: CommonFilesDir
+  register: common_files_dir
+'''
+
+RETURN = r'''
+changed:
+    description: Whether anything was changed.
+    returned: always
+    type: boolean
+    sample: True
+win_reg_stat:
+    description: Information about the registry key or property specified.
+    returned: success
+    type: dictionary
+    contains:
+        exists:
+             description: States whether the registry key/property exists.
+             returned: success and path/property exists
+             type: boolean
+             sample: True
+        properties:
+            description: A list of all the properties and their values in the key.
+            returned: success, path exists and property not specified
+            type: list
+            sample: [
+                "binary_property" : {
+                    "raw_value": ["0x01", "0x16"],
+                    "type": "REG_BINARY",
+                    "value": [1, 22]
+                },
+                "multi_string_property" : {
+                    "raw_value": ["a", "b"],
+                    "type": "REG_MULTI_SZ",
+                    "value": ["a", "b"]
+                }
+            ]
+        sub_keys:
+            description: A list of all the sub keys of the key specified.
+            returned: success, path exists and property not specified
+            type: list
+            sample: [
+                "AppHost",
+                "Casting",
+                "DateTime"
+            ]
+        raw_value:
+            description: Returns the raw value of the registry property, REG_EXPAND_SZ has no string expansion, REG_BINARY or REG_NONE is in hex 0x format.
+              REG_NONE, this value is a hex string in the 0x format.
+            returned: success, path/property exists and property specified
+            type: string
+            sample: '%ProgramDir%\\Common Files'
+        type:
+            description: The property type.
+            returned: success, path/property exists and property specified
+            type: string
+            sample: "REG_EXPAND_SZ"
+        value:
+            description: The value of the property.
+            returned: success, path/property exists and property specified
+            type: string
+            sample: 'C:\\Program Files\\Common Files'
+'''

test/integration/targets/win_reg_stat/aliases

@@ -0,0 +1 @@
+windows/ci/group1

test/integration/targets/win_reg_stat/files/test_reg.reg

@@ -0,0 +1,24 @@
+Windows Registry Editor Version 5.00
+
+[HKEY_CURRENT_USER\Test]
+
+[HKEY_CURRENT_USER\Test\nested]
+"string"="test"
+"binary"=hex:01,16
+"dword"=dword:00000001
+"qword"=hex(b):01,00,00,00,00,00,00,00
+"multi"=hex(7):61,00,2c,00,20,00,62,00,00,00,63,00,00,00,00,00
+"expand"=hex(2):25,00,77,00,69,00,6e,00,64,00,69,00,72,00,25,00,5c,00,64,00,69,\
+  00,72,00,00,00
+
+[HKEY_CURRENT_USER\Test\nested\nest1]
+"dontcare"=""
+
+[HKEY_CURRENT_USER\Test\nested\nest2]
+
+
+[HKEY_CURRENT_USER\Test\single]
+"string1"=""
+"string2"="abc123"
+"none"=hex(0):
+"none1"=hex(0):00

test/integration/targets/win_reg_stat/meta/main.yml

@@ -0,0 +1,2 @@
+dependencies:
+  - prepare_win_tests

test/integration/targets/win_reg_stat/tasks/main.yml

@@ -0,0 +1,317 @@
+---
+- name: make sure win output dir exists
+  win_file:
+    path: "{{win_output_dir}}"
+    state: directory
+
+- name: template out test registry structure
+  win_copy:
+    src: test_reg.reg
+    dest: "{{win_output_dir}}\\raw_test_reg.reg"
+
+- name: convert the line endings to the windows variant
+  win_shell: Get-Content "{{win_output_dir}}\raw_test_reg.reg" | Set-Content "{{win_output_dir}}\test_reg.reg"
+
+- name: import test registry structure
+  win_regmerge:
+    path: "{{win_output_dir}}\\test_reg.reg"
+
+- name: get value of expand string %windir%
+  win_command: powershell.exe $env:windir
+  register: win_dir_value
+
+- name: expect failure when not passing in key option
+  win_reg_stat:
+    property: a
+  register: actual
+  failed_when: "actual.msg != 'Missing required argument: key'"
+
+- name: expect failure when passing in an invalid hive
+  win_reg_stat:
+    key: ABCD:\test
+  register: actual
+  failed_when: actual.msg != "the hive in key is 'ABCD'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
+
+- name: get known nested reg key structure for testing with short hive form
+  win_reg_stat:
+    key: HKCU:\Test\nested
+  register: actual_short
+
+- name: get known nested reg key structure for testing with quoted yaml
+  win_reg_stat:
+    key: "HKCU:\\Test\\nested"
+  register: actual_quoted
+
+- name: set expected value for reg structure
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        properties:
+          binary: { raw_value: ["0x01", "0x16"], type: 'REG_BINARY', value: [1, 22] }
+          dword: { raw_value: 1, type: 'REG_DWORD', value: 1 }
+          expand: { raw_value: '%windir%\dir', type: 'REG_EXPAND_SZ', value: "{{win_dir_value.stdout_lines[0]}}\\dir" }
+          multi: { raw_value: ['a, b', 'c'], type: 'REG_MULTI_SZ', value: ['a, b', 'c'] }
+          qword: { raw_value: 1, type: 'REG_QWORD', value: 1 }
+          string: { raw_value: 'test', type: 'REG_SZ', value: 'test' }
+        sub_keys:
+        - nest1
+        - nest2
+
+- name: validate test
+  assert:
+    that:
+    - "actual_short == expected"
+    - "actual_quoted == expected"
+
+- name: get known reg key with no sub keys but some properties
+  win_reg_stat:
+    key: HKCU:\Test\single
+  register: actual
+
+- name: set expected value for reg key with no sub keys but some properties
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        properties:
+          none: { raw_value: [], type: 'REG_NONE', value: [] }
+          none1: { raw_value: ["0x00"], type: 'REG_NONE', value: [0] }
+          string1: { raw_value: '', type: 'REG_SZ', value: '' }
+          string2: { raw_value: 'abc123', type: 'REG_SZ', value: 'abc123' }
+        sub_keys: []
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get known reg key without sub keys and properties
+  win_reg_stat:
+    key: HKCU:\Test\nested\nest2
+  register: actual
+
+- name: set expected value for reg key without sub keys or properties
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        properties: {}
+        sub_keys: []
+  register: expected
+
+- name: validate test
+  assert:
+    that:
+      - "actual == expected"
+
+- name: get non-existant reg key
+  win_reg_stat:
+    key: HKCU:\Test\Thispathwillneverexist
+  register: actual
+
+- name: set expected value for non-existant reg key
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: false
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get string property
+  win_reg_stat:
+    key: HKCU:\Test\nested
+    property: string
+  register: actual
+
+- name: set expected string property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: 'test'
+        type: 'REG_SZ'
+        value: 'test'
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get expand string property
+  win_reg_stat:
+    key: HKCU:\Test\nested
+    property: expand
+  register: actual
+
+- name: set expected expand string property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: '%windir%\dir'
+        type: 'REG_EXPAND_SZ'
+        value: "{{win_dir_value.stdout_lines[0]}}\\dir"
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get multi string property
+  win_reg_stat:
+    key: HKCU:\Test\nested
+    property: multi
+  register: actual
+
+- name: set expected multi string property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: ['a, b', 'c']
+        type: 'REG_MULTI_SZ'
+        value: ['a, b', 'c']
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get binary property
+  win_reg_stat:
+    key: HKCU:\Test\nested
+    property: binary
+  register: actual
+
+- name: set expected binary property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: ["0x01", "0x16"]
+        type: 'REG_BINARY'
+        value: [1, 22]
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get dword property
+  win_reg_stat:
+    key: HKCU:\Test\nested
+    property: dword
+  register: actual
+
+- name: set expected dword property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: 1
+        type: 'REG_DWORD'
+        value: 1
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get qword property
+  win_reg_stat:
+    key: HKCU:\Test\nested
+    property: qword
+  register: actual
+
+- name: set expected qword property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: 1
+        type: 'REG_QWORD'
+        value: 1
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get none property
+  win_reg_stat:
+    key: HKCU:\Test\single
+    property: none
+  register: actual
+
+- name: set expected none property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: []
+        type: 'REG_NONE'
+        value: []
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get none with value property
+  win_reg_stat:
+    key: HKCU:\Test\single
+    property: none1
+  register: actual
+
+- name: set expected none with value property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: true
+        raw_value: ["0x00"]
+        type: 'REG_NONE'
+        value: [0]
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: get non-existance property
+  win_reg_stat:
+    key: HKCU:\Test\single
+    property: doesnotexist
+  register: actual
+
+- name: set expected non-existance property
+  set_fact:
+    expected:
+      changed: false
+      win_reg_stat:
+        exists: false
+
+- name: validate test
+  assert:
+    that:
+    - "actual == expected"
+
+- name: remove registry entry
+  win_regedit:
+    key: HKCU:\Test
+    state: absent

test/integration/test_win_group3.yml

@@ -7,3 +7,4 @@
     - { role: win_async_wrapper, tags: ["test_win_async_wrapper", "test_async_wrapper", "test_win_async_status", "test_async_status"] }
     - { role: win_shell, tags: test_win_shell }
     - { role: win_command, tags: test_win_command }
+    - { role: win_reg_stat, tags: test_win_reg_stat }