The familiar Windows command shell (Cmd.exe) is a distinct shell from the Windows Explorer interface. While it is still sometimes called the "DOS" prompt, it has been changed and improved well beyond its original DOS roots. In addition to having a significantly improved internal command set, it even supports primitive looping and error detection and can invoke any console-mode application available. While not as cute or obviously full featured as Windows Explorer, the command shell provides critical interactive task composition abilities missing from the GUI. You can rapidly recall and repeat commands, and you can create new tools by chaining old tools together instantly using its internal pipelining system.

To see a list of internal commands supported by Cmd.exe, open a command shell window and type help. External command-line tools are not shown in this listing but can typically be investigated using standard command-line help switches; although the help switches vary, most console applications on Windows use /?, /h, or -? to invoke help.

In contrast, although windowed applications are easy to invoke by clicking and often have internal task-specific time-saving conveniences, there is no way to record individual command sequences and repeat them. Nor is there a way to chain commands together in an immediate, ad-hoc fashion. You can mimic this with some third-party applications, but there is no easy or standard method for combining multiple graphical applications or actions into a single, repeatable, sequence of steps—which is something that the command shell and batch files make simple and easy. The command shell can use any tool that will provide console output, including graphical applications.

Active Scripting is the Microsoft COM-based open scripting interface technology. It enables users to mix scriptable applications and different scripting languages. Microsoft includes scripting engines for two Active Scripting languages with Windows Server 2003: VBScript and JScript. Windows Server 2003 also includes several host applications, including the Windows Scripting Host (WSH). WSH has both a console host, Cscript.exe, and a GUI mode host, Wscript.exe. WSH provides a core set of facilities to support application-like use, including input/output handling, argument parsing, and an optional help system.

Windows Script Host uses the Component Object Model, or COM, for real work. COM, from a scripting perspective, is a standard for software component interfaces. If a component implements the proper COM interfaces, scripts can talk to it without worrying about whether the component is a compiled library or application, a service, or another script. A typical Windows Server install has hundreds of scriptable components. Two technologies with COM interfaces are particularly critical. The Active Directory Services Interface (ADSI) acts as a scripting gateway to directory services. Windows Management Instrumentation (WMI) provides a standard model for accessing fine-grained information about system elements and, in many cases, lets you manipulate those elements as well.

The Windows Server 2003 command shell has additions, changes, and usage details documented in its help file. You can access these by typing %WINDIR%Help tcmds.chm at a command prompt. There are 64 documented new external command-line tools. These include several WSH scripts focused on IIS and printer management, a large set of Active Directory tools, and miscellaneous other tools, including sc (services); tasklist and taskkill (process management); and takeown, inuse, and openfiles (file management). Help for these and other commands is available by invoking the command with its help switch, usually /?. Some new tools use the POSIX-style -? for their help switch instead.

Windows Server 2003 uses version 5.6 of WSH, VBScript, and JScript. This version has been available since 2001 for all supported operating systems, and WSH and the scripting engines are part of the updateable core feature set of Windows, so it technically has no new unique features. WSH scripts have been affected, however, by significant changes in default Distributed COM (DCOM) security.

All remote COM access, including ADSI and WMI, is affected by DCOM’s increased authentication security and the presence of firewalls. The default security level used for authenticating clients has changed from connection-level to packet-level. Because the authentication level is negotiated, the changes don’t affect tools unless one side insists on a lower security level than the other system will accept. Client-side firewalls affect asynchronous connections because they require a separate connection and an exclusion for the specific remote host or the ports used.

There are roughly 350 new classes and 4000 distinct new properties and methods in WMI’s root/cimv2 namespace on a default Windows Server 2003 domain controller. Unfortunately, there is no system-based help on these new elements. We’ve included Scriptomatic on the CD, which will allow you to browse through classes and properties on a Windows Server 2003 system as a useful starting point. You can search class names on MSDN at http://msdn.microsoft.com for specifics of the class or search the TechNet Script Center at http://www.microsoft.com/technet/scriptcenter/default.mspx. The TechNet Script Center will usually provide code samples as well.

On the CD

Look for the Scriptomatic tool on the CD in the Tools folder.

One solution that has some fringe benefits is to not handle authentication within the script, but to use the RunAs command or schtasks alternate credentials arguments instead. By using this approach, you don’t need to write or maintain code for managing the user’s credentials, or worry about specifying the user’s credentials explicitly within the script. Troubleshooting problems is also simplified because it’s clear that everything is happening with permissions derived from the executing account.

Many tools that handle alternative authentication allow you to specify a password on the command line. This is a bad practice and should be avoided. If someone has permission to enumerate processes, he or she can also read the entire command line of processes running on a server. Further, even momentary access to your console will let a user see the cleartext password as typed on the command line.

Most tools that provide this kind of support will automatically prompt for a password if it isn’t provided or if you enter the password switch with no argument.

Windows XP and Windows Server 2003 have a new COM object written specifically to allow hidden password entry. You must be running the script from the command line for this to work, but this new COM object allows you to enter the password on the command line with no visible text, as shown in the following three examples:

VBScript

Dim ScriptPW, pw
Set ScriptPW = CreateObject("ScriptPW.Password")
pw = ScriptPW.GetPassword

JScript

var ScriptPW, pw;
ScriptPW = new ActiveXObject("ScriptPW.Password");
pw = ScriptPW.GetPassword();

Perl

use Win32::OLE;
$ScriptPW = Win32::OLE->CreateObject("ScriptPW.Password");
$pw = $ScriptPW->GetPassword();

When you type a command such as regedit at the command prompt, the command processor (Cmd.exe) first checks for an internal match—this is how names of internal commands such as dir are found. The command processor next looks in the current directory for files with the base name regedit and one of the file extensions listed in the %PATHEXT% command shell variable, in the order they are listed in the variable. If it isn’t found, it looks through each folder listed in the %PATH% variable in the order they are listed in the variable, and in each folder it checks against that base name plus the list of file extensions listed in %PATHEXT%. This process continues until it finds a matching name or it runs out of folders to search.

Executables always use the shell’s search mechanism for discovery. This applies to WSH scripts launching an external process using WScript.Shell’s Run method, for example, because the external process is just inheriting the shell. Because the local directory will always be searched first for commands, you need to exercise caution when changing your working directory in a script. Any arbitrary path might contain malicious executables with names of commands you are likely to invoke. An equally serious problem is that there are often multiple versions of files on a system, and invoking an external command after a directory change can pick up the wrong version of a file. To avoid this problem, you have two basic solutions:

To prevent accidental executable substitution, you should qualify executable paths rather than using just bare names. At its simplest, qualification can just specify executable type by including the file suffix—for example, you would use Regedit.exe instead of regedit to ensure you don’t find regedit.com instead. For increased control, you can specify a fully qualified path and use well-known environment variables in the path to make the invocation work on nonstandard system configurations. For example, %SYSTEMROOT%system32 egedit.exe will always find regedit.exe, even if Windows is installed in D:WinSafe instead of C:Windows.

Real World: Making Sure %PATH% Is Limited and Has Strong Permissions

As we’ve mentioned, the command processor searches for commands by looking in all the folders listed in %PATH%. The only three standard folders in the path are the system folder, Windows itself, and the WMI folder; if your system drive is C they will be: C:WINDOWSsystem32;C:WINDOWS;C:WINDOWSSystem32Wbem.

Unfortunately, some applications will add themselves to your search path automatically without asking; sometimes they are added at the front of the path, so they are searched first. This can cause slowdowns as a result of extra folders being searched first. If an application that adds itself to your path has an incompatible version of a critical dynamic-link library (DLL) in its folder, it might even cause other applications to fail when they try to use the incompatible version. Even worse, some applications open security holes by adding paths that other users might have permission to write to. A malicious file with a common name such as "regedit" in one of these locations can easily be invoked by an administrator, opening the entire system to possible exploitation.

To guard against this, take the following precautions:

• Whenever you install new software, after a reboot check the system path by typing path at a command prompt. If an application has added itself, consider removing it; at the very least, make sure it is added to the tail end of the path.

• Carefully check the security settings on folders that you do want to remain in your path. Only privileged users who normally should be able to administer the computer should have permission to write or modify files. (Permission for reading and executing is fine.)

The pathext variable is also occasionally modified by application installs, and it might not need some elements that it contains by default. For example, encoded JScript (.JSE) and VBScript (.VBE) files are considered executables, but Windows does not have any tools shipped in this form. If you don’t use encoded scripts, you can remove .JSE and .VBE from the %PATHEXT% variable to prevent invoking encoded scripts. Another simple security trick that can shut down some attack vectors is to reverse the order of .EXE and .COM on %PATHEXT%. This will prevent a malicious program from inserting itself higher in the executable order by adding a .COM version of a common .EXE file. As with removing encoded scripts from known executable types, you should check the effects of switching .COM and .EXE files against your supported systems; some application suites use a .COM file as a launch wrapper for their .EXE and might have critical impairments if the .EXE is launched directly.

If you use many command-line tools and want them consistently available from a predictable location, you should put the standard tools you use in a folder that is added to your path. This isn’t an exception to the general practices for path management; rather, it should be a directory modifiable by administrators only and one that follows the core system directories in the path statement. For consistent access across several machines such as a group of servers, you can use Distributed File System (DFS) to synchronize content, or you can create the folder on a single server and then share the folder. Map the folder as a drive letter and then add the map to your logon script to make it consistently available. (We like to store our generally available scripts in a folder we share as "Tools" and have that automatically mapped to the T: drive.) As obsolete as we might wish drive-mapping to be, drive letters are still necessary for many command-line tools that refer to their own location; the command shell needs a drive location, not a Uniform Naming Convention (UNC) path for current directory references.

Console WSH scripts have three objects automatically available for input and output operations: WScript.StdIn, WScript.StdOut, and WScript.StdErr. These objects correspond to the familiar UNIX streams of STDIN, STDOUT, and STDERR, respectively. These objects are actually text streams, functionally identical to the TextStream object used for file reading and writing in WSH. Use WScript.StdIn to read data you are processing, WScript.StdOut to write new data you create, and WScript.StdErr to emit error or tracing information. These streams will work correctly in all contexts where you use console script invocation. Your script won’t care whether it is reading input from a file or a previous command; you can log output information by redirecting it to a file and still get console output. In the most extreme case of redirection, you’re actually getting to use three files without all the messy coding to open them from the Scripting.FileSystemObject:

cscript myscript.vbs < in.txt 2> err.log 1> out.log

The MsgBox function in VBScript supports optional parameters for displaying different buttons, selecting a default, setting a window icon and window modality, and providing a clickable reference to a help file topic. This is the real point behind MsgBox: providing necessary context-sensitive information to a user that needs confirmation and possibly needs to make a decision. If you really need this functionality at multiple points in the script, MsgBox is the function you want and the script would be a poor candidate for full automation anyway.

In any other roles, MsgBox is bad news. If a script is running in batch processing mode with WSH’s //B option, MsgBox will always cause a failure when encountered. MsgBox will cause a script to hang or fail if it’s used when a GUI can’t be presented—such as when running as a scheduled task, in a service account, or remotely via a console session. With arbitrarily large amounts of data coming out of it, MsgBox is even useless for interactive roles; users must click repeatedly to continue processing.

If a MsgBox-using script doesn’t use the return button-click information for anything, you can generally fix it instantly by replacing MsgBox with WScript.StdOut.WriteLine. If the message was customized with other arguments, you can comment those out. If you don’t need the message for your output, just comment out the whole line.

If you want a script to write to your console window when run from Cscript.exe and pop up a box when run from Wscript.exe, and if you don’t care whether output is displayed when using scripts in batch mode, WSH’s native Echo method allows this. The WScript.Echo statement will pop up a message window if run from the GUI WSH host Wscript.exe, and it will write output to the standard output stream if run from the console WSH host Cscript.exe. If WSH is run in batch mode, WScript.Echo output is always suppressed no matter what host you are using; this makes it a bad choice for output redirection from a noninteractive script.

WScript.Echo statements are usually straightforward to convert to WScript.StdOut.WriteLine statements, but Echo has a special feature that the StdOut WriteLine doesn’t: Echo will take multiple comma-separated arguments and output them with an automatic space. To adapt WScript.Echo statements for use with WScript.StdOut.WriteLine, you need to replace each argument-separating comma with & " " & in VBScript or + " " + in JScript.

Scripts that run periodically on a schedule or that make significant changes that might not be otherwise recorded explicitly are candidates for logging. Too much detail can be useless, but a single event containing a critical piece of information can be useful at each standard exit point from these key scripts; at the least, you will know when the script was run and where. LogEvent always writes to the application log; its first argument is the event type. Use 0 for an information event, 2 for a warning, and 1 for an actual error. You can use the following generic code for almost any script to track normal exit events by placing this at the end of the script code or before any explicit WScript.Quit statements:

VBScript:
Set WshShell = CreateObject("WScript.Shell")
WshShell.LogEvent 0, "script exit: " & WScript.ScriptFullName
JScript:
new ActiveXObject("WScript.Shell").LogEvent(0,
    "script exit: " + WScript.ScriptFullName);
Perl:
use Win32::OLE;
Win32::OLE->CreateObject("WScript.Shell")->
    LogEvent(0,  "script exit: " . Win32::GetFullPathName( $0 ));

With VBScript in particular, it is common to see the statement On Error Resume Next at the start of scripts, which effectively tells WSH to ignore all runtime errors regardless of the consequences. This is a bad practice and lazy coding, and it can cause completely unpredictable consequences.

If you expect your script to encounter error events, handle them if at all possible. And if it will be normal to encounter reasonable errors in particular sections of the script, you should turn on error suppression immediately before it is needed, and then continue the current task only if errors are known and can clearly be handled. Whatever you do, you should turn error suppression back off immediately.

GUI-focused or single-run scripts typically treat errors that prevent core operation as critical errors. Console scripts designed for batch use might not work well with this model. For example, a script for changing an account password on a specific computer needs to connect to the computer, authenticate, get an account reference, and then set the new password. Any error in this process means the password change failed, so there’s no point in continuing. However, if we’re handling dozens of password updates at once, we don’t want to halt the whole chain of events for reasonable errors such as specific machines being unavailable or the particular user not being present on one of the machines. The following simplified code for a password update script demonstrates this approach. We suppress errors just long enough to try connecting and get an error result. If there is no error, we set the password. If we get a normal error—such as insufficient permissions, no machine available, or the account doesn’t exist—we write a message to the error stream. If we get any other error whatsoever, it represents an unknown situation, possibly even a major problem, and we actually quit after writing an error.

Function ChangePassword (computer, name, newpass)
    On Error Resume Next
    Dim user: Set user = GetObject("WinNT://" & computer _
        & "/" & name & ",user")
    Dim result: result = Err.Number
    On Error Goto 0
    Select Case result
        Case 0
            user.SetPassword(newpass): user.SetInfo
        Case &H46, &H80070035, &H800708AD
            WScript.StdErr.WriteLine "Failure: " & computer
        Case Else
            WScript.StdErr.WriteLine computer_
                & " FAILURE Unknown error returned: 0x" & Hex(result)
            WScript.Quit 999
    End Select
    ChangePassword = result
End Function

If you choose to make a script terminate as a result of a critical failure, give it a non-zero exit code. In the case of WSH scripts, it’s a good idea to make the exit code something other than 1. Some invoking applications will handle more process shutdown details for you if they see a nonzero exit code. You should avoid using an exit code of 1 for a WSH script because WSH returns an error of 1 if it chooses to shut down on its own. One option is to pass along the script error, which we could have done by using the WScript.Quit result. Because high-numeric codes such as ADSI errors might not be rendered correctly, we used 999 as a generic unknown error code.

When a script is running noninteractively, you won’t see what problems it encountered unless you take explicit steps to log the errors. If you want to log errors when a script is run noninteractively but just let them go to the screen from an interactive session, you can test the interactive status of your script. The WScript.Interactive property is false if the script is running noninteractively, so you can then use LogEvent as detailed in the Input and Output Handling section to log the error.

WMI’s endless classes and properties change in every release of Windows; it’s impossible to document them in detail without creating an entire reference work. Fortunately, you can explore them directly using Scriptomatic from the Scripting Center. Version 2.0 of Scriptomatic is available at: http://www.microsoft.com/technet/scriptcenter/tools/scripto2.mspx and on the CD that accompanies this book. Scriptomatic gives you a complete list of all WMI classes available on a specific computer and can automatically generate scripts to sample output data.

One of the reasons WMI has a bad reputation is the sheer mass of code required for the simplest invocations. A better alternative for immediate use is the wmic command-line tool. WMIC provides many conveniences, including short aliases that help with the lengthy WMI calls, but at first glance it might appear difficult to use. If you’re used to script-based WMI calls and already know a specific class and property you want information from, you can get what you want with a command of the form wmic path <class> get <property>. For example, wmic path win32_operatingsystem get buildnumber would return the BuildNumber property exposed by the WMI Win32_OperatingSystem class.

Many WMI sample scripts explicitly set authentication and impersonation levels. In scripting examples, this is typically used following the winmgmts: moniker in curly brackets {}. For example, a call that sets both of these levels might look like this:

Set wmi = GetObject("winmgmts:{impersonationLevel=impersonate," _
    & "authenticationLevel=pktPrivacy}!root/cimv2")

Although you might occasionally want to change these security settings, if you don’t have a specific reason for doing so, it’s usually best to eliminate them. This allows WMI to use the systemwide default impersonation level settings and negotiate the authentication level with the remote system. If you specify levels too low (as some legacy scripts do), WMI scripts might fail. This also makes WMI calls much more compact, because the line of script just shown reduces to

Set wmi = GetObject("winmgmts:!root/cimv2")

Working with COM objects might involve either accessing a pre-existing instance of an object or creating a new instance. In general, most components are created by you when needed and then shut down when you’re done with them (sometimes automatically). ADSI and WMI are both exceptions because you access them through running services. Creating a new instance in any scripting language works out to calling an underlying CoCreateInstance API; getting access to a running object such as the WMI interface reduces to calling the GetActiveObject API. To illustrate how this is done, we’ll demonstrate working with both a common COM class and WMI.

The COM class we’ll use as an example is WshShell, which has a common name or programmatic identifier used in WSH scripts of "WScript.Shell". One of its properties is CurrentDirectory, which can be used to both read and set the current shell directory. It also has a method named LogEvent for writing to the Windows Application event log. To get the running instances of COM objects, we’ll use the WMI winmgmts moniker and the path to a WMI namespace. We’ll create a reference to the namespace used most commonly by administrators, the root/cimv2 namespace, and then query WMI for the name and startup mode of all services.

First, let’s look at an example in VBScript:

Dim WshShell: Set WshShell = CreateObject("WScript.Shell")
Dim dir: dir = WshShell.CurrentDirectory
WshShell.CurrentDirectory = "C:	emp"
Dim wmi: Set wmi = GetObject("winmgmts://./root/cimv2")
Dim results: Set results = wmi.execQuery( _
  "select Name,PathName,ProcessId from Win32_Service")

Note that when not capturing a result from a method as shown next, VBScript does not use parentheses around the method’s argument list:

WshShell.LogEvent 0, "Started in directory " & dir

VBScript uses physical line endings for statement terminations. To put two statements on one line, you use the colon (:); and to break a single line across two physical lines, you insert an underscore (_) at the end of the physical line. It uses the ampersand (&) to append one string to another. One final peculiarity that is very important is that it is not case-sensitive. The WMI method ExecQuery was written in the preceding code as execQuery, but it still works.

The JScript requirements are somewhat different than VBScript’s. VBScript’s CreateObject maps to the new ActiveXObject syntax. In addition, JScript uses the backslash () as an escape character, so literal backslashes in strings need to be doubled to escape them. Either double quotes or single quotes can be used as quoting characters, as long as they are correctly paired. Finally, when you call a method it must have its arguments enclosed by parentheses.

var WshShell; WshShell = new ActiveXObject("WScript.Shell");
var dir = WshShell.CurrentDirectory;
WshShell.CurrentDirectory = 'C:\temp';
var wmi = GetObject('winmgmts://./root/cimv2'),
var results = wmi.ExecQuery(
'select Name,PathName,ProcessId from Win32_Service'),
WshShell.LogEvent(4, "Start in directory: " + dir);

Perl uses CreateObject (though with a rather different syntax) just as VBScript does, but first you need to "use" the Win32::OLE module. Backslashes are an escape character again, and statement termination uses semicolons just as JScript does. Finally, when setting a property on a COM object (such as WshShell’s CurrentDirectory property), you use the same bracket notation as you would with setting a hashtable value.

use Win32::OLE;
$WshShell = Win32::OLE->CreateObject("WScript.Shell");
$dir = $WshShell->CurrentDirectory;
$WshShell->{CurrentDirectory} = 'C:\temp';
$wmi = Win32::OLE->GetObject("winmgmts://./root/cimv2");
$results = $wmi->ExecQuery(
  "select Name,PathName,ProcessId from Win32_Service");
$WshShell->LogEvent(4, "Start in directory: $dir");