community.windows.win_audit_rule (2.2.0) — module

Install collection

Install with ansible-galaxy collection install community.windows:==2.2.0

Add to requirements.yml

  collections:
    - name: community.windows
      version: 2.2.0

Description

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.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Add registry audit rule
  community.windows.win_audit_rule:
    path: HKLM:\software
    user: BUILTIN\Users
    rights: delete
    audit_flags: 'success'

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Remove filesystem audit rule
  community.windows.win_audit_rule:
    path: C:\inetpub\wwwroot\website
    user: BUILTIN\Users
    state: absent

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Remove registry audit rule
  community.windows.win_audit_rule:
    path: HKLM:\software
    user: BUILTIN\Users
    state: absent

Inputs

    
path:
    aliases:
    - dest
    - destination
    description:
    - Path to the file, folder, or registry key.
    - Registry paths should be in Powershell format, beginning with an abbreviation for
      the root such as, C(HKLM:\Software).
    required: true
    type: path

user:
    description:
    - The user or group to adjust rules for.
    required: true
    type: str

state:
    choices:
    - absent
    - present
    default: present
    description:
    - Whether the rule should be C(present) or C(absent).
    - For absent, only I(path), I(user), and I(state) are required.
    - Specifying C(absent) will remove all rules matching the defined I(user).
    type: str

rights:
    description:
    - Comma separated list of the rights desired. Only required for adding a rule.
    - If I(path) is a file or directory, rights can be any right under MSDN FileSystemRights
      U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx).
    - If I(path) is a registry key, rights can be any right under MSDN RegistryRights
      U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx).
    elements: str
    required: true
    type: list

audit_flags:
    choices:
    - Failure
    - Success
    description:
    - Defines whether to log on failure, success, or both.
    - To log both define as comma separated list "Success, Failure".
    elements: str
    required: true
    type: list

inheritance_flags:
    choices:
    - ContainerInherit
    - ObjectInherit
    default: ContainerInherit,ObjectInherit
    description:
    - 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 C(none).
    - For more information on the choices see MSDN PropagationFlags enumeration at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx).
    elements: str
    type: list

propagation_flags:
    choices:
    - None
    - InherityOnly
    - NoPropagateInherit
    default: None
    description:
    - 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 U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx).

Outputs

current_audit_rules:
  description:
  - The current rules on the defined I(path)
  - Will return "No audit rules defined on I(path)"
  returned: always
  sample: "{\n  \"audit_flags\": \"Success\",\n  \"user\": \"Everyone\",\n  \"inheritance_flags\"\
    : \"False\",\n  \"is_inherited\": \"False\",\n  \"propagation_flags\": \"None\"\
    ,\n  \"rights\": \"Delete\"\n}\n"
  type: dict
path_type:
  description:
  - The type of I(path) being targetted.
  - Will be one of file, directory, registry.
  returned: always
  type: str

See also

• community.windows.win_audit_policy_system