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

New in version 2.5.

- Synopsis
- Parameters
- See Also
- Examples
- Return Values
- Status

## Synopsis

- Used to apply audit rules to files, folders or registry keys.
- Once applied, it will begin recording the user who performed the operation defined into the Security Log in the Event viewer.
- The behavior is designed to ignore inherited rules since those cannot be adjusted without first disabling the inheritance behavior. It will still print inherited rules in the output though for debugging purposes.

## 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
string

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 string / required |  | The user or group to adjust rules for.

## See Also

See also

win_audit_policy_system – Used to make changes to the system wide Audit Policy
  The official documentation on the win_audit_policy_system module.

## 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 not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Noah Sparks (@nwsparks)

Hint

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