ShellServe™ Web Services Guide

Overview

ShellServe is a web service option of PShellExec and allows users to access and execute PowerShell scripts from a web browser on any device. ShellServe is free software and portions of it are covered by the GNU Affero General Public License.

A web page ShellServe.html opens in the default web browser when the ShellServe service is started from PShellExec. Intranet users can access ShellServe using this web page or the API. Users must be authorized and have intranet and/or internet network access to ShellServe, as shown in the diagram and described below.

        ___________________       ___________________        __________________        __________________
       |  Internet Users   |     |        IIS 7      |      | ShellServe Host  |      |  Intranet Users  |
       |      Browser      |<===>| [ShellServe.aspx] |<====>|__________________|<====>| [ShellServe.html]|
       |___________________|     |___________________|      |    PShellExec    |      |  ShellServe API  |
                                                            |__________________|      |__________________|

$PSExecOut is a variable made available to ShellServe. The response users would like to see from the remote execution of a script should be assigned to $PSExecOut. See SQLInfo.ps1 and SysInfo.ps1 for examples of $PSExecOut use. These example scripts can produce HTML or text formatted output based on the user provided arguments.

Users can enter the full path of a script file, when it is other than the default script folder (starting folder of PShellExec).

ShellServe Administration and Security

An administrator starts PShellExec on a designated system and selects the ShellServe tab to configure and then start the web service. ShellServe remains active until a service administrator stops the service or exits PShellExec.
The administrator has full control of the URL that hosts the service, the service key and the service tokens' expiration time period. ShellServe access is available only to users who obtain from the service administrator the full URL of the ShellServe host and service key. The service key allows authorized users to request their own service tokens required by ShellServe to execute scripts. The service token expiration time is set by an administrator in PShellExec with the following values:

Expire > 0	Tokens expire after the number specified in seconds. ShellServe users need to request a new token upon expiration.
Expire = 0	Tokens do not expire. No need to request new tokens between service requests.
Expire < 0	A negative value sets a limit on the total number (not per user) of requests to execute scripts. For example, a value of -2 will shut down ShellServe automatically after two execute requests, making the service unavailable.

An option to log ShellServe transactions keeps details of the service requests in a file ShellServe.log. Firewalls on the system hosting ShellServe should be configured to allow local network users to reach it through administrator designated ports.

Configuring IIS 7

Internet access to the service can be configured on Windows based systems running IIS version 7 or later, using the setup command that comes with PShellExec and via the IIS Manager (Start -> Run -> inetmgr). The web.config file <appSettings> that allow internet users to access ShellServe should be configured as follows:

ShellServeUrl	Provides the URL for ShellServe - set to the URL address in PShellExec when starting ShellServe.
ShellServeUser	User name for login to ShellServe. The default name is info.
ShellServePwd	User password for login to ShellServe. The default password is ShellServe.

The source code for the ShellServe site includes ShellServe.aspx.cs in the ShellServe (App_Data) install folder. Users are free to make changes according to their user authentication and login requirements. All ShellServe responses are based on the $PSExecOut variable value assignments made by the user scripts, as noted in the Overview section above.

The ShellServe API

This section provides information for users who plan to access the ShellServe web service using a program interface of their choice.
The web services are exposed and accessed with RESTful style interactions, supported via HTTP POST methods. The ShellServe web service currently handles two API requests: newtoken and execute. These service requests appear as part of the URL and are described below. All other information associated with each request is sent as part of the POST, in the body of the request message as content-type: application/x-www-form-urlencoded. Response from the web services is in XML format.

Service Tokens

To access the services API users must first obtain a valid token, using a service key. The key is provided by the ShellServe administrator to authorized users. The token is required for all execute requests. Service tokens expire according to a ShellServe administrator setting.
A newtoken can be requested in HTML as:

         <form id='myForm' method='post' action='http://10.8.99.20:8562/newtoken'>
         <input type='hidden' name='key' value='LetMeIn123'>
         <input type="submit" value="Request Token" />
         </form>

The service responds in XML as:

         <ShellServe request='newtoken'>
         <status>OK</status>
         <token>78ah80e120f</token>
         </ShellServe>

The status will show an error when the key is invalid.
An equivalent newtoken request using PowerShell is:

	$url = "http://10.8.99.20:8562/ShellServe/newtoken" # <- your URL address
	$parameters = "key=78ah80e120f" # your key value
	$http_request = New-Object -ComObject Msxml2.XMLHTTP
	$http_request.open('POST', $url, $false)
	$http_request.setRequestHeader("Content-type", "application/x-www-form-urlencoded")
	$http_request.setRequestHeader("Content-length", $parameters.length.toString())
	$http_request.setRequestHeader("Connection", "close")
	$http_request.send($parameters)
	# output status & token
	$http_request.statusText
	$http_request.responseText
	$xmldata=[xml] $http_request.responseText
	if ($xmldata.ShellServe.status -eq 'OK') {
		$xmldata.ShellServe.token
	}

Execute Script Requests

An valid, unexpired token is required for the Execute Script option, in addition to a valid URL for the service.
The Script File name is also a required entry. Users can enter the script name or the full path of the script file residing on the ShellServe host.
Script Arguments, Script Password and Compressed(zip) are optional and depend on the user script.

Here is an example of a execute request, specified in HTML:

         <form method='post' action='http://10.8.99.20:8562/ShellServe/exec'>
         <input type='hidden' name='token' value='78ah80e120f'>
         <input type='hidden' name='script' value='mytest.ps1.bin'>
         <input type='hidden' name='args' value='one,two,3'> <!-- Optional -->
         <input type='hidden' name='pwd' value='_9utwo2Be'>  <!-- Optional -->
         <input type='hidden' name='zip' value='1'>  <!-- Optional -->
         <input type="submit" value="ShellServe Request" />
         </form>

A service response example:

    <ShellServe request='exec'>
    <status>OK</status>
    <script>SQLInfo.ps1</script>
    <response>6/1/2012 4:57:03 AM  Starting up database 'master'.
        6/1/2012 4:57:04 AM  Starting up database 'mssqlsystemresource'.
        6/1/2012 4:57:05 AM  Starting up database 'model'.
        6/1/2012 4:57:06 AM  Starting up database 'msdb'.
        6/1/2012 4:57:06 AM  Starting up database 'AdventureWorks'.
        6/1/2012 4:57:06 AM  Starting up database 'DATA'.
        6/1/2012 4:57:09 AM  Starting up database 'tempdb'.
        6/1/2012 4:57:14 AM  Error: 50000, Severity: 16, State: 1.
    </response>
    </ShellServe>

Tweets by @infoSpectrumInc