win_audit_rule - Adds an audit rule to files, folders, or registry keys

New in version 2.5.

Synopsis

Parameters

Parameter Choices/Defaults Comments
audit_flags
list

required
    Choices:
  • Failure
  • Success
Defines whether to log on failure, success, or both.
To log both define as comma separated list "Success, Failure".
inheritance_flags
list
    Choices:
  • ContainerInherit
  • ObjectInherit
Default:
ContainerInherit,ObjectInherit
Defines what objects inside of a folder or registry key will inherit the settings.
If you are setting a rule on a file, this value has to be changed to none.
For more information on the choices see MSDN PropagationFlags enumeration at https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx.
path
path

required
Path to the file, folder, or registry key.
Registry paths should be in Powershell format, beginning with an abbreviation for the root such as, 'hklm:\software'.

aliases: dest, destination
propagation_flags
    Choices:
  • None ←
  • InherityOnly
  • NoPropagateInherit
Propagation flag on the audit rules.
This value is ignored when the path type is a file.
For more information on the choices see MSDN PropagationFlags enumeration at https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx.
rights
list

required
Comma separated list of the rights desired. Only required for adding a rule.
If path is a file or directory, rights can be any right under MSDN FileSystemRights https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx.
If path is a registry key, rights can be any right under MSDN RegistryRights https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx.
state
    Choices:
  • absent
  • present ←
Whether the rule should be present or absent.
For absent, only path, user, and state are required.
Specifying absent will remove all rules matching the defined user.
user
required
The user or group to adjust rules for.

Examples

- name: add filesystem audit rule for a folder
  win_audit_rule:
    path: C:\inetpub\wwwroot\website
    user: BUILTIN\Users
    rights: write,delete,changepermissions
    audit_flags: success,failure
    inheritance_flags: ContainerInherit,ObjectInherit

- name: add filesystem audit rule for a file
  win_audit_rule:
    path: C:\inetpub\wwwroot\website\web.config
    user: BUILTIN\Users
    rights: write,delete,changepermissions
    audit_flags: success,failure
    inheritance_flags: None

- name: add registry audit rule
  win_audit_rule:
    path: HKLM:\software
    user: BUILTIN\Users
    rights: delete
    audit_flags: 'success'

- name: remove filesystem audit rule
  win_audit_rule:
    path: C:\inetpub\wwwroot\website
    user: BUILTIN\Users
    state: absent

- name: remove registry audit rule
  win_audit_rule:
    path: HKLM:\software
    user: BUILTIN\Users
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
current_audit_rules
dictionary
always
The current rules on the defined path
Will return "No audit rules defined on path"

Sample:
{ "audit_flags": "Success", "user": "Everyone", "inheritance_flags": "False", "is_inherited": "False", "propagation_flags": "None", "rights": "Delete" }
path_type
string
always
The type of path being targetted.
Will be one of file, directory, registry.



Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • Noah Sparks (@nwsparks)

Hint

If you notice any issues in this documentation you can edit this document to improve it.