Add: documentation for NASL WMI functions (#1276)

doc/manual/nasl/built-in-functions/wmi-functions/index.md

@@ -0,0 +1,13 @@
+# WMI Functions
+
+## GENERAL
+
+Provides WMI (Windows Management Instrumentation) functionalities via calling functions of a appropriate library.
+The API offers three groups of functions:
+1. WMI_FUNCTIONS: run all-purpose queries
+2. WMI_RSOP_FUNCTIONS (RSoP = Resultant Set of Policy): run RSoP queries
+3. WMI_REGISTRY_FUNCTIONS: read and write values from/to the registry
+
+In order to be able to use the WMI functions, **[openvas-smb](https://github.com/greenbone/openvas-smb)** has to be installed before.
+
+## TOC

doc/manual/nasl/built-in-functions/wmi-functions/wmi_close.md

@@ -0,0 +1,29 @@
+# wmi_close
+
+## NAME
+
+**wmi_close** - closes an opened WMI handle
+
+## SYNOPSIS
+
+*bool* **wmi_close**(wmi_handle: *int*);
+
+**wmi_close** takes one named argument
+
+## DESCRIPTION
+
+This function closes a before opened WMI handle. A WMI handle can be opened with **[wmi_connect(3)](wmi_connect.md)**.
+
+The named *wmi_handle* argument is a *int* containing a representation of a WMI handle.
+
+## RETURN VALUE
+
+*TRUE* on success, *NULL* on failure or error.
+
+## ERRORS
+
+The named argument *wmi_handle* is missing or 0.
+
+## SEE ALSO
+
+**[wmi_connect(3)](wmi_connect.md)**

doc/manual/nasl/built-in-functions/wmi-functions/wmi_connect.md

@@ -0,0 +1,85 @@
+# wmi_connect
+
+## NAME
+
+**wmi_connect** - Connect to a WMI service on the current target system
+
+## SYNOPSIS
+
+*int* **wmi_connect**(username: *string*, password: *string*, ns: *string*, option: *string*);
+*int* **wmi_connect_rsop**(username: *string*, password: *string*, option: *string*);
+*int* **wmi_connect_reg**(username: *string*, password: *string*, option: *string*);
+
+## DESCRIPTION
+
+**wmi_connect** connects to a WMI service on the current target system into a specified namespace.
+
+**wmi_connect_rsop** connects to a WMI service on the current target system into the RSOP namespace.
+
+**wmi_connect_reg** connects to a WMI service on the current target system into the registry namespace.
+
+A WMI handler is returned, which is used to run commands on the target system. A opened handler must be closed by calling **[wmi_close(3)](wmi_close.md)**.
+
+The named argument *username* contains the user login.
+
+The named argument *password* contains the password.
+
+The optional named argument *ns* contains the namespace to use. The default namespace is *root\\cimv2*.
+
+The optional named argument *option* is a *string* containing options for the WMI connection. The option must be given in the format "\[opt1, opt2, ...\]". here a list of all options:
+- sign: Use RPC integrity authentication level
+- seal: Enable RPC privacy (encryption) authentication level
+- connect: Use RPC connect level authentication (auth, but no sign or seal)
+- spnego: Use SPNEGO instead of NTLMSSP authentication
+- ntlm: Use plain NTLM instead of SPNEGO or NTLMSSP
+- krb5: Use Kerberos instead of NTLMSSP authentication
+- validate: Enable the NDR validator
+- print: Enable debug output of packets
+- padcheck: Check reply data for non-zero pad bytes
+- bigendian: Use big endian for RPC
+- smb2: Use SMB2/3 for named pipes
+
+## RETURN VALUE
+
+An *int* representing the WMI handle or *NULL* on error.
+
+## ERRORS
+
+One of the named arguments *username* or *password* are missing or empty.
+
+Unable to get IP of target system.
+
+WMI connection failed or missing WMI support.
+
+## EXAMPLE
+1. Integrated example of an :
+```c#
+usrname = get_kb_item( "SMB/login" );
+passwd  = get_kb_item( "SMB/password" );
+
+if(!usrname || !passwd) exit( 0 );
+
+domain = get_kb_item( "SMB/domain" );
+if( domain ) usrname = domain + '\\' + usrname;
+
+opts = "[sign]";
+handle = wmi_connect(username:usrname, password:passwd, options:opts);
+
+if( ! handle ) exit( 0 );
+
+a = wmi_query( wmi_handle:handle, query:"select * from Win32_ComputerSystem");
+display (a);
+
+wmi_close( wmi_handle:handle );
+
+set_kb_item( name:"WMI/access_successful", value:TRUE );
+set_kb_item( name:"SMB_or_WMI/access_successful", value:TRUE );
+```
+
+## NOTE
+
+In order to be able to use the WMI client of the openvas-scanner, **[openvas-smb](https://github.com/greenbone/openvas-smb)** has to be installed.
+
+## SEE ALSO
+
+**[wmi_close(3)](wmi_close.md)**

doc/manual/nasl/built-in-functions/wmi-functions/wmi_connect_reg.md

@@ -0,0 +1,85 @@
+# wmi_connect_reg
+
+## NAME
+
+**wmi_connect_reg** - Connect to a WMI service on the current target system to the registry namespace
+
+## SYNOPSIS
+
+*int* **wmi_connect**(username: *string*, password: *string*, ns: *string*, option: *string*);
+*int* **wmi_connect_rsop**(username: *string*, password: *string*, option: *string*);
+*int* **wmi_connect_reg**(username: *string*, password: *string*, option: *string*);
+
+## DESCRIPTION
+
+**wmi_connect** connects to a WMI service on the current target system into a specified namespace.
+
+**wmi_connect_rsop** connects to a WMI service on the current target system into the RSOP namespace.
+
+**wmi_connect_reg** connects to a WMI service on the current target system into the registry namespace.
+
+A WMI handler is returned, which is used to run commands on the target system. A opened handler must be closed by calling **[wmi_close(3)](wmi_close.md)**.
+
+The named argument *username* contains the user login.
+
+The named argument *password* contains the password.
+
+The optional named argument *ns* contains the namespace to use. The default namespace is *root\\cimv2*.
+
+The optional named argument *option* is a *string* containing options for the WMI connection. The option must be given in the format "\[opt1, opt2, ...\]". here a list of all options:
+- sign: Use RPC integrity authentication level
+- seal: Enable RPC privacy (encryption) authentication level
+- connect: Use RPC connect level authentication (auth, but no sign or seal)
+- spnego: Use SPNEGO instead of NTLMSSP authentication
+- ntlm: Use plain NTLM instead of SPNEGO or NTLMSSP
+- krb5: Use Kerberos instead of NTLMSSP authentication
+- validate: Enable the NDR validator
+- print: Enable debug output of packets
+- padcheck: Check reply data for non-zero pad bytes
+- bigendian: Use big endian for RPC
+- smb2: Use SMB2/3 for named pipes
+
+## RETURN VALUE
+
+An *int* representing the WMI handle or *NULL* on error.
+
+## ERRORS
+
+One of the named arguments *username* or *password* are missing or empty.
+
+Unable to get IP of target system.
+
+WMI connection failed or missing WMI support.
+
+## EXAMPLE
+1. Integrated example of an :
+```c#
+usrname = get_kb_item( "SMB/login" );
+passwd  = get_kb_item( "SMB/password" );
+
+if(!usrname || !passwd) exit( 0 );
+
+domain = get_kb_item( "SMB/domain" );
+if( domain ) usrname = domain + '\\' + usrname;
+
+opts = "[sign]";
+handle = wmi_connect(username:usrname, password:passwd, options:opts);
+
+if( ! handle ) exit( 0 );
+
+a = wmi_query( wmi_handle:handle, query:"select * from Win32_ComputerSystem");
+display (a);
+
+wmi_close( wmi_handle:handle );
+
+set_kb_item( name:"WMI/access_successful", value:TRUE );
+set_kb_item( name:"SMB_or_WMI/access_successful", value:TRUE );
+```
+
+## NOTE
+
+In order to be able to use the WMI client of the openvas-scanner, **[openvas-smb](https://github.com/greenbone/openvas-smb)** has to be installed.
+
+## SEE ALSO
+
+**[wmi_close(3)](wmi_close.md)**

doc/manual/nasl/built-in-functions/wmi-functions/wmi_connect_rsop.md

@@ -0,0 +1,85 @@
+# wmi_connect_rsop
+
+## NAME
+
+**wmi_connect_rsop** - Connect to a WMI service on the current target system to the RSoP namespace
+
+## SYNOPSIS
+
+*int* **wmi_connect**(username: *string*, password: *string*, ns: *string*, option: *string*);
+*int* **wmi_connect_rsop**(username: *string*, password: *string*, option: *string*);
+*int* **wmi_connect_reg**(username: *string*, password: *string*, option: *string*);
+
+## DESCRIPTION
+
+**wmi_connect** connects to a WMI service on the current target system into a specified namespace.
+
+**wmi_connect_rsop** connects to a WMI service on the current target system into the RSoP namespace.
+
+**wmi_connect_reg** connects to a WMI service on the current target system into the registry namespace.
+
+A WMI handler is returned, which is used to run commands on the target system. A opened handler must be closed by calling **[wmi_close(3)](wmi_close.md)**.
+
+The named argument *username* contains the user login.
+
+The named argument *password* contains the password.
+
+The optional named argument *ns* contains the namespace to use. The default namespace is *root\\cimv2*.
+
+The optional named argument *option* is a *string* containing options for the WMI connection. The option must be given in the format "\[opt1, opt2, ...\]". here a list of all options:
+- sign: Use RPC integrity authentication level
+- seal: Enable RPC privacy (encryption) authentication level
+- connect: Use RPC connect level authentication (auth, but no sign or seal)
+- spnego: Use SPNEGO instead of NTLMSSP authentication
+- ntlm: Use plain NTLM instead of SPNEGO or NTLMSSP
+- krb5: Use Kerberos instead of NTLMSSP authentication
+- validate: Enable the NDR validator
+- print: Enable debug output of packets
+- padcheck: Check reply data for non-zero pad bytes
+- bigendian: Use big endian for RPC
+- smb2: Use SMB2/3 for named pipes
+
+## RETURN VALUE
+
+An *int* representing the WMI handle or *NULL* on error.
+
+## ERRORS
+
+One of the named arguments *username* or *password* are missing or empty.
+
+Unable to get IP of target system.
+
+WMI connection failed or missing WMI support.
+
+## EXAMPLE
+1. Integrated example of an :
+```c#
+usrname = get_kb_item( "SMB/login" );
+passwd  = get_kb_item( "SMB/password" );
+
+if(!usrname || !passwd) exit( 0 );
+
+domain = get_kb_item( "SMB/domain" );
+if( domain ) usrname = domain + '\\' + usrname;
+
+opts = "[sign]";
+handle = wmi_connect(username:usrname, password:passwd, options:opts);
+
+if( ! handle ) exit( 0 );
+
+a = wmi_query( wmi_handle:handle, query:"select * from Win32_ComputerSystem");
+display (a);
+
+wmi_close( wmi_handle:handle );
+
+set_kb_item( name:"WMI/access_successful", value:TRUE );
+set_kb_item( name:"SMB_or_WMI/access_successful", value:TRUE );
+```
+
+## NOTE
+
+In order to be able to use the WMI client of the openvas-scanner, **[openvas-smb](https://github.com/greenbone/openvas-smb)** has to be installed.
+
+## SEE ALSO
+
+**[wmi_close(3)](wmi_close.md)**

doc/manual/nasl/built-in-functions/wmi-functions/wmi_query.md

@@ -0,0 +1,32 @@
+# wmi_query
+
+## NAME
+
+**wmi_query** - perform a WQL query
+
+## SYNOPSIS
+
+*string* **wmi_query**(wmi_handle: *int*, query: *string*);
+*string* **wmi_query_rsop**(wmi_handle: *int*, query: *string*);
+
+## DESCRIPTION
+
+This function takes a wmi handle and performs a WQL query on it. WQL is the WMI Query Language.
+
+The named argument *wmi_handle* is an *int* representing a connection to a WMI server. This connection can be opened with on of the **[wmi_connect(3)](wmi_connect.md)** functions.
+
+The named argument *query* is a *string* containing the query to perform.
+
+## RETURN VALUE
+
+The result of the query as *string*, *NULL* on error.
+
+## ERRORS
+
+The named argument *wmi_handle* is missing
+
+Unable to run query
+
+## SEE ALSO
+
+**[wmi_connect(3)](wmi_connect.md)**

doc/manual/nasl/built-in-functions/wmi-functions/wmi_query_rsop.md

@@ -0,0 +1,35 @@
+# wmi_query
+
+## NAME
+
+**wmi_query_rsop** - perform a WQL RSoP query
+
+## SYNOPSIS
+
+*string* **wmi_query**(wmi_handle: *int*, query: *string*);
+*string* **wmi_query_rsop**(wmi_handle: *int*, query: *string*);
+
+
+## DESCRIPTION
+
+**wmi_query** performs a WQL query on a WMI connection. WQL is the WMI Query Language.
+
+**wmi_query_rsop** performs a WQL RSoP query on a WMI connection.
+
+The named argument *wmi_handle* is an *int* representing a connection to a WMI server. This connection can be opened with on of the **[wmi_connect(3)](wmi_connect.md)** functions.
+
+The named argument *query* is a *string* containing the query to perform.
+
+## RETURN VALUE
+
+The result of the query as *string*, *NULL* on error.
+
+## ERRORS
+
+The named argument *wmi_handle* is missing
+
+Unable to run query
+
+## SEE ALSO
+
+**[wmi_connect(3)](wmi_connect.md)**

doc/manual/nasl/built-in-functions/wmi-functions/wmi_reg_create_key.md

@@ -0,0 +1,27 @@
+# wmi_reg_create_key
+
+## NAME
+
+**wmi_reg_create_key** - create registry key
+
+## SYNOPSIS
+
+*bool* **wmi_reg_create_key**(wmi_handle: *int*, key: *string*);
+
+**wmi_reg_create_key** takes two named arguments.
+
+## DESCRIPTION
+
+This functions creates a new key in the registry.
+
+The named argument *wmi_handle* is an *int* representing a connection to a WMI server. This connection can be opened with on of the **[wmi_connect(3)](wmi_connect.md)** functions.
+
+The named argument *key* is a *string* containing the new key to create.
+
+## RETURN VALUE
+
+*TRUE* on success, *FALSE* on failure
+
+## SEE ALSO
+
+**[wmi_connect(3)](wmi_connect.md)**