wntAuditAdd

Adds or updates System Access Control List [SACL, a.k.a. audit] records for a resource.

Syntax:

wntAuditAdd(server-name, resource/share-name, account-name,object-type, access-string [, flags])

Parameters:

(s) server-name: Name of a network file server or empty string ("") to indicate the current machine.

(s) resource/share-name: Identifies the object to be modified.

(s) account-name: Name of a user or a group to whom access is being granted. If necessary, it can be fully qualified as 'server\user'.

(i) object-type: Identifies the object type of the 'resource/share-name' object. See below.

(i) access-string: The type of access that is being granted. See below.

(i) flags: [optional] Controls behavior of the function. See below.

Returns:

(i) 1 [@TRUE] or 0 [@FALSE]. See below.

Server-Name

All attempts to work with permissions or auditing settings on remote computers will require that those remote computers have the "Server" service running.

Object-Type

* Note: the object types 301, 302, 303 and 401 cannot be used to manipulate ACLs on resources that are located on a Win2K system. Whenever one of these object types is specified for a resource on a Win2K system, the object type will automatically be converted to either "300" or "400" as is appropriate. This restriction was implemented due to the fact that Win2K does have inheritable ACLs that do get automatically propagated to all child objects under a folder or registry key. Allowing a user to explicitly add/remove an ACE [which is also inheritable] to/from an entire hierarchy of folders & files or registry keys could have a negative effect by creating unexpected types of access or auditing ACLs.

Access-string:

'Access-string' specifies the type of access that is being granted. Unlike wntAccessAdd(), which has pre-defined access-string values, the function wntAuditAdd() does not have predefined access-string values. Only a delimited list of one or more specific 'access-records' is supported. The reason for this is that auditing is only enabled/disabled by an administrator and it is an advanced topic to discuss & understand. Auditing ACEs basically have to be created by determining exactly which types of access are to be audited and then by applying these ACEs to the specified objects with the wntAuditAdd() function. Examining the pre-defined access-string values that are documented for use with the wntAccessAdd() function may help to determine which particular types of access need to be audited when attempting to audit a general type of access such as "read", "write", "execute", "list", "change" / "modify" or "delete".

Specific access-string values are described below:

This can be a single record, or a list of records (maximum of 100) delimited with vertical bars (|). Each record is in the format:

record-type:access-flags:access-rights

where 'record-type', 'access-flags', and 'access-rights' are each a decimal number, separated with colons ( : ).

It is not expected that most users will want to manually create or edit 'access-records' strings. Instead, you can use the wntAuditGet() function to return an 'access-records' string in the proper format for use with this function. This is useful for transferring developing an auditing ACE to use with wntAuditAdd() after having manually created the ACE with an administration program like the Windows Explorer or with REGEDT32.EXE.

A brief description of the fields in the 'access-records' string follows. Please note that any detailed explanation is beyond the scope of this document, but might be obtained from the WIN32 SDK programmers' documentation available from Microsoft and other publishers.

'record-type' (aka., ACE Type) (one of the following):

The ACE types 0 - 2 are commonly used. The NT extender can report on ACE types 0 - 8, but it can only manage ACE types 0 - 2 w/respect to wnt[Access|Audit][Add|Del]().

Note For auditing ACEs, only ACEs of type "Audit ACE type" [type 2 ACEs] are valid.

'access-flags' (0, or, one or more of the following):

You can specify 0, or, one or more of the following flags, by combining them with the bitwise OR ('|') operator. These are the access flags.

Note For auditing ACEs, either one or both of the SUCCESSFUL_ACCESS_ACE_TYPE or FAILED_ACCESS_ACE_TYPE flag bits must be set. If both bits are set, then any type of access, either successful or failed which matches any of the bits enabled in the access-rights mask value of the ACE will result in an audit event being logged on the system. If only one of these bits is enabled then the only matching access attempts of the appropriate type [either successful or failed] will cause an audit event being logged on the system. No auditing events will be logged if the system security policy is not set to enable auditing. Auditing of successful and failed access attempts is separately configurable for each type of auditing. If successful access or failed access auditing is disabled in the system security policy then the corresponding types of ACEs will be ignored if they are applied to objects on the system.

'access-rights' (one or more of the following, usually several, depending on the object type.)

Multiple access-rights values may be bit-wise OR'd together to combine them into a single access mask value.

Note: For all practical purposes, this is a complete list of the individual access rights mask bits and their corresponding values. Some of the bits have different constant names associated with them if the bits are applicable to more than one object type.

Refer to the wntAccessAdd() function for a list of common combinations of the various access rights mask bits.

If any audit records already exist in the SACL for 'resource/share-name' for the specified 'account-name', they will be removed before adding the records specified by 'access-string'.

Flags

The flags value is an integer bit mask value. The values of different flag bits may be bit-wise OR'd together if multiple flag bits are to be "set" [e.g. enabled] at the same time. The following flag bits are valid:

Return value

The return value of wntAuditAdd() will be 1 [@TRUE] if it successfully processes all of the resources that were specified.

Certain object types, namely folders & files and registry keys, can have recursive processing performed to add an ACE to the SACL of multiple objects, such as when an entire subdirectory tree is processed or when a branch of the registry is processed. Also, on Win2K, ACL inheritance may cause recursive processing to happen even though only a single folder or registry key has had its SACL modified. If recursive processing is done and one or more child objects cannot have their SACLs properly accessed/modified, then wntAuditAdd() will return a value of 0 [@FALSE]. The wntLastErrMsg() function should be called with an error code of "-1" specified to get the list of objects that could not be properly processed.

Please note that it is possible for wntAuditAdd() to return a zero value and not cause the script to abort with an error. The only time that wntAuditAdd() will raise an error that needs to be trapped with the use of ErrorMode(@OFF) is when the specific resource/share-name that has been specified cannot have its SACL modified properly. Any other errors that occur during recursive processing of child objects simply result in wntAuditAdd() returning a zero value [@FALSE]. It is the programmer's responsibility to check the return value of wntAuditAdd() and then execute any error handling code should a zero value be returned.

Note:

To use wntAuditAdd() to change the audit settings on a file on a remote server (ie, not the local machine), you need to specify the file name as a UNC, e.g.:

wntAuditAdd("server2", "\\server2\C$\test", "Everyone", 300, accessstring)

("C$" and "D$" are standard admin shares to "C:\" and "D:\", etc.)

Note: It is not possible for WinNT v3.51/v4.0 to properly manage the permissions on a remote Win2K [or newer] systems. Attempting to use the wnt[Access|Audit]*() functions on WinNT v3.51/v4.0 to view/modify the permissions on a remote Win2K [or newer] system will result in error 716 [Win2K or newer required] being raised.

Example:

; Load Appropriate Extender
AddExtender('wwwnt34i.dll',0,'wwwnt64i.dll')


;This example sets the auditing on the folder
;"C:\TEMP" on the current machine so that any member
;of the group "Everybody" who attempts to list the
;contents of the folder and fails will cause an audit
;event to be generated.
;
;Please note that this audit ACE applies to the folder
;"C:\TEMP", but it will not be inherited by any child
;folders under "C:\TEMP". To make the ACE inheritable by
;subfolders, the flags value of "128" must be bit-wise
;OR'd with the flag value "2" to get a flags value of "130".
;
wntAuditAdd("","C:\TEMP","Everybody",300, "2:128:1179817",0)
Exit

See Also:

wntAuditDel, wntAuditGet, wntAuditList, wntAuditMod, About SID [Security Identifier] values&