IBM Rational AppScan eXtensions Framework

Overview

eXtensions

	What are Rational AppScan eXtensions?
	Build your own eXtensions
	Publishing your eXtensions
	Code samples
	Pyscan
	Frequently asked questions
	Download

IBM® Rational® AppScan is a leading suite of automated Web application security solutions that scan and test for common Web application vulnerabilities. Unlike other solutions that inundate users with vulnerability data, Rational AppScan provides intelligent fix recommendations and advanced remediation capabilities, such as comprehensive task lists necessary to fix vulnerabilities uncovered during the scan and improve an organization's overall security posture. The Rational AppScan eXtensions Framework helps you extend new functionality to Rational AppScan and advance your automated Web application security solution.

Rational AppScan eXtensions are software add-ons that extend new functionality to Rational AppScan. They can add anything from a minor utility that performs a simple task, to a full blown application that performs many complex actions. By using eXtensions, users can customize Rational AppScan to their own needs, just the way they like it. Here are some examples of things you can perform using the Rational AppScan eXtensions Framework:

1. Make Rational AppScan better fit your process (e.g. export results to defect tracking systems, write your own report export format, etc.)
2. Add small features to Rational AppScan (e.g. send Email/Pager/SMS notifications)
3. Innovate big features to make Rational AppScan perform new things for you (e.g. compare files found by Rational AppScan to files on server, to see if you missed some and improve your coverage)
4. Package your own proprietary expertise into the automated process (e.g. exploit when issue is found)
5. Just have fun (e.g. Make Rational AppScan vocalize different events, or open a game of Solitaire while a scan is running)

Back to top

You can find the SDK Documentation under Downloads and also under the /Docs directory in your AppScan Installation directory.

To begin writing your own eXtension, you first have to add the following namespaces to your project's source code:

• Watchfire.AppScan;
• Watchfire.AppScan.Scan;
• Watchfire.AppScan.Events;
• Watchfire.AppScan.Extensions;
• Watchfire.AppScan.Scan.Events;

This is done by adding the following lines of code to the beginning of your source file:

• using Watchfire.AppScan;
• using Watchfire.AppScan.Scan;
• using Watchfire.AppScan.Events;
• using Watchfire.AppScan.Extensions;
• using Watchfire.AppScan.Scan.Events;

In addition, you should add Rational AppScan's Public SDK DLL (C:\Program Files\IBM\Rational AppScan\AppScanSDK.dll) to your project's References--Figure 1.

In order to supply extension information, your project may include an XML file (should be named "info.xml"), containing information that will be presented in the Extension Manager (more information in the next section and in the sample code below).

Your new Rational AppScan eXtension should implement the IExtensionLogic interface (Figure 3).

There are three different ways for the extension to integrate into Rational AppScan, as defined by the interface:

1. On initialization: when Rational AppScan starts, it loads the extension, and calls its Load() method
2. As part of Load() implementation: the extension may register to handle SDK events, so when the events are raised, extension code is executed
3. User actions: the extension (optionally) defines menu entries to be displayed in Rational AppScan's menus. When a user selects an entry, a designated extension code is executed.

Back to top

If you would like your eXtension (or download location) to be published and linked from our IBM Rational AppScan eXtensions Framework pages, please email us at: wfwebmaster@ca.ibm.com.

When you have completed your eXtension, you should package it for reuse with Rational AppScan. Packaging of the eXtension is done in the following way:

1. Create a directory with your extension's name (e.g. MyExt)
2. Place the extension DLL and the optional info.xml information file in the directory
3. You can place any additional directories and files inside the /MyExt directory as well
4. Zip the directory using WinZip
5. After launching Rational AppScan, click on Tools > Extensions > Extension Manager > Install Extension, and add the new extension to Rational AppScan

Optionally, you can manually create a directory for your extension under "Application Data: TODO", and put your DLL and info.xml file into this directory. This replaces the installation process.

Back to top

Listing 1 demonstrates how to implement an extension that registers to a Rational AppScan event, using the Rational AppScan eXtensions Framework.

                            
using System;

using System.Collections.Generic;

using System.Windows.Forms;

 

using Watchfire.AppScan;

using Watchfire.AppScan.Scan;

using Watchfire.AppScan.Events;

using Watchfire.AppScan.Extensions;

using Watchfire.AppScan.Scan.Events;

 

namespace MyExtension1

{

    /// <summary>

    /// SayIt main implementation class.

    /// implementing the IExtensionLogic interface

    /// </summary>

    public class MyExtension : IExtensionLogic

    {

       /// <summary>

       /// extension initialization. typically called on AppScan's startup

      /// </summary>

     /// <param name="appScan">
         main application object the extension is loaded into
         </param>

     /// <param name="extensionDir">
         extension's working directory
         </param>

     public void Load
         (IAppScan appscan, IAppScanGui appScanGui, string extensionDir)

       {

                  appScan = appscan;

                  RegisterToAppScanEvents();

            }

 

            /// <summary>

            /// Register to AppScan events

            /// </summary>

            private void RegisterToAppScanEvents()

            {

                  appScan.Scan.StateChanged += Scan_StateChanged;

            }

 

            #region event handlers

 

            private void Scan_StateChanged(object sender, StateChangedEventArgs e)

            {

                  if (e.CurrentState == ScanOperationState.Exploring)

                  {

                        MessageBox.Show("Now Exploring");

                  }

            }

 

            #endregion event handlers

 

            #region private members

 

            IAppScan appScan;

 

            #endregion private members

 

            #region other IExtensionLogic operations

 

            /// <summary>

            /// retrieves data about current available ext-version

            /// </summary>

            /// <param name="targetApp">app this extension is designated for</param>

            /// <param name="targetAppVersion">current version of targetApp</param>

            /// <returns>
                update data of most recent extension version, or null if no data was 
               found, or feature isn't supported. it is valid to return update data of 
               current version. extension-update will take place only if returned value 
               indicaes a newer version
               </returns>

            public ExtensionVersionInfo GetUpdateData
                  (Edition targetApp, Version targetAppVersion)

            {

                  return null;

            }

 

            #endregion other IExtensionLogic operations

           

      }

}
                            
                        

Listing 2 demonstrates how to add new menu items to Rational AppScan. The first menu item is added to the Tools > Extensions menu, and the second is added as an Issue context menu item (right-click on an Issue).

                            
using System;

using System.Collections.Generic;

using System.Windows.Forms;

 

using Watchfire.AppScan;

using Watchfire.AppScan.Events;

using Watchfire.AppScan.Extensions;

using Watchfire.AppScan.Scan.Data;

 

namespace MyExtension1

{

      /// <summary>

      /// GuiDemo main implementation class.

      /// implementing the IExtensionLogic interface

      /// </summary>
                                    
      public class GuiDemo : IExtensionLogic

      {

            #region Initialization

           
            /// <summary>

            /// extension initialization. typically called on AppScan's startup

            /// </summary>

            /// <param name=
            "appScan">main application object the extension is loaded into</param>

            /// <param name="extensionDir">extension's working directory</param>

            public void Load
              (IAppScan appscan, IAppScanGui appScanGui, string extensionDir)

             {

                  InitGuiHooks();

                  RegisterGuiHooks(appScanGui);

            }

 

            /// <summary>

            /// Creates the menu entries objects

            /// </summary>

            private void InitGuiHooks()

            {

                  extMenuItems = CreateMenuItems(); 
                  // Create a (Tools->Extension) menu entry collection

                  IssueMenuItems = CreateIssueContextMenuItems(); 
                 // Create a context-menu entry collection

            }
            
             /// <summary>

            ///  Add menu entries to AppScan

            /// </summary>

            /// <param name="appScanGui"></param>

            private void RegisterGuiHooks(IAppScanGui appScanGui)

            {

                  foreach 
                      (IMenuItem<EventArgs> item in extMenuItems)

                        appScanGui.ExtensionsMenu.Add(item);

 

                  foreach 
                       (IMenuItem<IssuesEventArgs> item in IssueMenuItems)

                        appScanGui.IssueContextMenu.Add(item);

            }

 

            #endregion Initialization

 

            #region GUI itmes construction

 

            private ICollection<IMenuItem<EventArgs>> CreateMenuItems()

            {

             mainExtMenuItem = new MenuItem
             <EventArgs>(messagePrefix + "Hello!", DelegateEmpty);

             List<IMenuItem<EventArgs>> items = 
             new List<IMenuItem<EventArgs>>();

             items.Add(mainExtMenuItem);

             return items;

            }
            
             private ICollection<IMenuItem<IssuesEventArgs>> CreateIssueContextMenuItems()

            {

            mainIssuesExtMenuItem = 
            new MenuItem<IssuesEventArgs>(messagePrefix + "Operation 1", DelegateIssue1);

            List<IMenuItem<IssuesEventArgs>> items = 
            new List<IMenuItem<IssuesEventArgs>>();

           items.Add(mainIssuesExtMenuItem);

           return items;

            }

            #endregion GUI itmes construction

            #region delegates

            /// <summary>

            /// Tools-Extensions menu entry action

            /// </summary>

            /// <param name="args"></param>

            private static void DelegateEmpty(EventArgs args)

            {

                  MessageBox.Show("Hello!", messageTitle);

            }
            
             /// <summary>

            /// Issue-context menu entry action

            /// </summary>

            /// <param name="args"></param>

            private void DelegateIssue1(IssuesEventArgs args)

            {

                  DoDelegateIssue(1, args.issues);

            }

 

            private static void DoDelegateIssue(int num, ICollection<IIssue> issues)

            {

             if (issues != null)

               {

               MessageBox.Show
              ("Issue operation " + num.ToString() 
                 + " issues count: " + issues.Count, messageTitle);

              }

             else

             MessageBox.Show
             ("Issue operation " + num.ToString() 
                + " issues list is empty", messageTitle);

            }
            
            #endregion delegates 

            #region data members 

            IMenuItem<EventArgs> mainExtMenuItem;

            IMenuItem<IssuesEventArgs> mainIssuesExtMenuItem; 

            ICollection<IMenuItem<EventArgs>> extMenuItems;

            ICollection<IMenuItem<IssuesEventArgs>> IssueMenuItems;

 

            const string messageTitle = "GuiDemo ";

            const string messagePrefix = "GuiDemo: ";

 

            #endregion data members

 

            #region other

 

            /// <summary>

            /// retrieves data about current available ext-version

            /// </summary>

            /// <param name="targetApp">app this extension is designated for</param>

            /// <param name="targetAppVersion">current version of targetApp</param>

            /// <returns>
                update data of most recent extension version, 
                or null if no data was found, or feature isn't supported. 
                It is valid to return update data of current version. 
                extension-update will take place only if returned value indicates 
                a newer version
               </returns>

            public ExtensionVersionInfo GetUpdateData
            (Edition targetApp, System.Version targetAppVersion)

            {

                  return null;

            }

 

            #endregion other

 

      }

}


 
                                          

Listing 3 shows an example of an info.xml file.

                            
<?xml version="1.0"?>

 

<WatchfireExtension>

 

  <!-- Front End MetaData -->

  <FullName>MyExt</FullName>

  <Description>Sample Extensions that does nothing</Description>

  <Version>1.0</Version>

  <Author>Author Name</Author>

  <Copyright>My Copyright info</Copyright>

  <HomepageURL>http://www.watchfire.com/</HomepageURL>

  <IconFile>MyExt.gif</IconFile>

  <MainDllFile>MyExt.dll</MainDllFile>

 

  <!-- Target Application this extension can install into,

       with minimum and maximum supported versions. -->

  <TargetEdition>

   

    <!-- supported values: AppScanAuditors, AppScanDev, AppScanQA, AppScanXM, All -->

    <ID>All</ID>

   

    <MinCompatibleVersion>7.5</MinCompatibleVersion>

    <MaxCompatibleVersion>7.9</MaxCompatibleVersion>

 

  </TargetEdition>

 

</WatchfireExtension>
                        

Back to top

Coupling Rational AppScan with the powerful capabilities of Python™ scripts -- one of the most advanced, established, and yet easy to learn scripting languages used by penetration testers -- give users an unprecedented platform for extending security testing. Pyscan is a revolutionary new way to leverage the power of Rational AppScan without the limitations of a user interface. Integrating Python scripting within Rational AppScan's configuration framework produces a level of customization previously unavailable to security professionals and penetration testers. Users can now harness core Web application scanning functions, such as Rational AppScan Advanced Session Management, a reporting and scanning engine, to customize a scan for a specific audit.

Targeted, real-time penetration testing

Pyscan leverages the Advanced Session Management engine of Rational AppScan to establish and maintain login state while enabling Python scripting via Rational AppScan's engine in order to expose potential Web application vulnerabilities. All results are immediately reported in Rational AppScan's Security Issues view. Users can invoke customized scripted Web application attacks that previously were not feasible through manual penetration testing efforts alone. Examples of such scripts include finding suspicious content, scriptable rules, or HTTP fuzzing.

Pyscan comes installed with Rational AppScan v7.5, but in case you need to install it again, you can download the eXtension file.

In order to get started with Pyscan, we have created a small sample Python script called PyscanUtils.py, which contains several useful functions. Load this sample script by going to the File menu, choose Open, and point to the PyscanUtils.py script. In the new IDE window that will open with the script, go to the Run menu, and choose Run Module. The script can also run by hitting F5 in the Open menu.

Back to top

How/Where do I download and install Rational AppScan eXtensions?
You can download free Rational AppScan eXtensions by linking to the IBM Rational AppScan eXtensions Framework from the IBM developerWorks site at: http://www.ibm.com/developerworks/rational/products/appscan/

What's the advantage for me, as a developer, to use Rational AppScan eXtensions in my projects?
Rational AppScan eXtensions allow you to integrate your own knowledge and code into the automated scanning process while leveraging Rational AppScan as a platform for Web application security scanning and reporting. Your own utilities can now make use of Rational AppScan's crawling engine, advanced reporting, powerful communication layer (e.g. SSL support, Client Side Certificates, Advanced Session State Management, etc.) and automated testing capabilities.

Who can write Rational AppScan eXtensions?
Users who own a copy of Rational AppScan 7.5 (or above) can immediately start developing their own extensions by using Rational AppScan's public SDK and the Rational AppScan eXtensions Framework, which comes bundled with documentation and code samples.

What is the Rational AppScan Public Software Development Kit (SDK)?
The Rational AppScan Public SDK is a programming package which enables you to develop applications that integrate with Rational AppScan closely. The SDK provides interface specifications and API libraries to Rational AppScan as well as thorough documentation and code samples of how to use them.

Rational AppScan's Public SDK is ideal for those who wish to integrate their own applications with the industry's leading Web application security scanner. It is available to end users of Rational AppScan, as well as value-added resellers (VARs) and independent software vendors.

You can write your own applications (or Rational AppScan eXtensions) using the Rational AppScan Public SDK in any language that is .NET-CLR compliant (e.g. C#, VB.NET, VB or J#). In addition, you can use the SDK with the Python scripting language, using PyScan, an integration between Python and Rational AppScan that comes built-in with Rational AppScan v7.5.

Where can I find the Rational AppScan SDK documentation?
You can find the SDK Documentation under the Downloads section, and also under the /Docs directory in your Rational AppScan Installation directory.

Is there a discussion forum that I can visit to ask questions about eXtensions to the broader community?
You can post your questions in the Rational AppScan forum on developerWorks.

	Information about download methods

Back to top