AppScan.DAST.UnitTester 1.0.0-alpha

AppScan DAST Unit Tester

1. Introduction

Name: AppScan DAST Unit Tester
Version: 1.0.0
Description: Run DAST scans on endpoints using AppScan
Purpose: AppScan DAST Unit Tester — a utility that enables developers to run fast, targeted DAST scans on incremental code changes as a unit test within the IDE, helping them identify and fix vulnerabilities before merging.
Key Features: Fast and precise vulnerability scanning.

System requirements

• OS - Windows
• AppScan CLI
• .Net Core 8.0 or later
• AppScan Standard license (LLS or CLS)

2. Installation

Downloading DAST package from MHS

Visual Studio

1. Right click on your project.
2. Manage NuGet…
3. In the Browse tab, search for AppScan DAST Unit Tester..

CLI

Verify that you have .Net Core 8.0+ installed and configured in your path.

Navigate to your project folder.

dotnet --version

Install the AppScan.DAST.UnitTester package

dotnet add package AppScan.DAST.UnitTester

3. Getting Started

After installing the NuGet, the next step is to define the Unit tests and configure AppScan DAST Unit Tester for running the tests. Here is a quick example

Quick startup

using HCL.AppScan;

[TestClass]
public class Example
{
    private AppScanDev AppScanDev;
    private string BaseUrl = "https://demo.testfire.net";
    [ClassInitialize]
    public static void ClassInit(TestContext context)
    {
        AppScanDevConfig config = new AppScanDevConfig()
        {
            AppScanInstallDir = @"C:\Program Files (x86)\HCL\AppScan Standard"
        };

        AppScanDev = new AppScanDev(config);
    }

    [TestMethod]
    public void TestApiTransfer()
    {
        //Build an HttpRequestMessage
        Uri uri = new Uri(BaseUrl + "/api/transfer");
        var body = new
        {
            fromAccount = "800002",
            toAccount = "800003",
            transferAmount = "100"
        };
        
        HttpRequestMessage httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, uri)
        {
            Content = new StringContent(JsonConvert.SerializeObject(body), Encoding.UTF8, "application/json")
        };

        httpRequestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<AuthToken>");

        //Calling AppScan to test the desired endpoint
        var appScanResults = AppScanDev.Scan(httpRequestMessage);
        //Asserting the results using MSTest (Choose which Unit test framework fits best)
        Assert.IsFalse(appScanResults.HasVulnerabilities(Severity.High), appScanResults.ToString(DetailLevel.Detailed));
    }
}

4. API Documentation

Classes

AppScanDev

Description: Provides functionality to interact with the AppScanCMD executable for scanning HTTP requests.

Methods

• AppScanDev(AppScanDevConfig? config = null, ScanConfig? scanConfig = null)

  • Description: The constructor of this class
  • Parameters:
    • config: AppScanDevConfig? - The configuration for the AppScanDev instance. If not provided, a default configuration will be used.

• Scan(HttpRequestMessage httpRequestMessage)

  • Description: Scans an HTTP request message and returns the scan results.
  • Parameters:
    • httpRequestMessage: HttpRequestMessage - The HTTP request message to scan.
    • scanConfig: ScanConfig? - Optional configuration for the scan. If not provided, a default configuration will be used.
  • Returns: AppScanResults - The results of the scan.
  • Example:

    var httpRequest = new HttpRequestMessage(HttpMethod.Get, "https://example.com/api");
    var scanResults = appScanDev.Scan(httpRequest);
    

• Scan(Uri uri, string httpRequest, ScanConfig? scanConfig = null)

  • Description: Scans an HTTP request represented by a URI and raw HTTP request string.
  • Parameters:
    • uri: Uri - The URI of the HTTP request.
    • httpRequest: string - The raw HTTP request string.
    • scanConfig: ScanConfig? - Optional configuration for the scan. If not provided, a default configuration will be used.
  • Returns: AppScanResults - The results of the scan.
  • Exceptions:
    • ArgumentNullException - Thrown if the uri is null.
    • ArgumentException - Thrown if the httpRequest string is null or empty.
  • Example:

    var uri = new Uri("https://example.com/api");
    string rawRequest = "GET /api HTTP/1.1\r\nHost: example.com\r\n\r\n";
    var scanResults = appScanDev.Scan(uri, rawRequest);
    

• Dispose()

  • Description: Releases the resources used by the AppScanDev instance.

Properties

• Config
  • Description: Gets the configuration for the AppScanDev instance.
  • Type: AppScanDevConfig

AppScanDevConfig

Description: Represents the configuration for the AppScanDev class.

Properties

• AppScanInstallDir

  • Description: Gets or sets the installation directory of AppScan.
  • Type: string
  • Default Value: C:\Program Files (x86)\HCL\AppScan Standard

• TestPolicyFile

  • Description: Gets or sets the path to the test policy file.
  • Type: string
  • Default Value: C:\Program Files (x86)\HCL\AppScan Standard\Policies\The Vital Few.policy

• BaseTemplate

  • Description: Gets or sets the base template for the scan. If null, the default template will be used.
  • Type: string
  • Default Value: null

• ReuseAppScanProcess

  • Description: Gets or sets a value indicating whether to reuse the AppScan process for multiple scans or to run each scan in a new AppScan process.
  • Type: bool
  • Default Value: true

• LicenseUrl

  • Description: Gets or sets the URL for the AppScan license. If null, the license will not be configured, and it will be assumed that the license was already configured.
  • Type: string?
  • Default Value: null

AppScanResults

Description: Represents the results of an AppScan scan, including issues and their details.

Methods

• AppScanResults(string xmlReportPath)

  • Description: Initializes a new instance of the AppScanResults class by parsing the specified XML report file.
  • Parameters:
    • xmlReportPath: string - Path to the XML report file.
  • Exceptions:
    • ArgumentNullException - Thrown if the xmlReportPath is null or empty.
    • FileNotFoundException - Thrown if the XML report file does not exist.
    • InvalidOperationException - Thrown if the XML report file cannot be parsed.

• HasVulnerabilities(Severity minSeverity)

  • Description: Determines whether any issues were found with a severity greater than or equal to the specified minimum severity.
  • Parameters:
    • minSeverity: Severity - The minimum severity to check for.
  • Returns: bool - true if issues of the minSeverity were found; otherwise, false.

• ToString()

  • Description: Returns a printable representation of the results with a default detail level (Summary).
  • Returns:string - A summary of the scan results.

• ToString(DetailLevel detailLevel)

  • Description: Returns a printable representation of the results with the specified detail level.
  • Parameters:
    • detailLevel: DetailLevel - The level of detail to include in the result.
  • Returns: string - A detailed representation of the scan results.

Properties

• Issues
  • Description: Gets the list of issues found during the scan.
  • Type: IEnumerable<Issue>
  • Exceptions:
    • InvalidOperationException - Thrown if issues have not been initialized.

ScanConfig

Description: Represents the configuration for running a scan using AppScanDev.

Properties

• ScanOutputPath
  • Description: Gets or sets the output path for the scan, including the name of the scan. This path specifies where the scan results will be saved.
  • Type: string?
  • Example:

    var scanConfig = new ScanConfig
    {
        ScanOutputPath = "C:\\Scans\\example.scan"
    };
    

Enums

Severity

Description: Represents the severity levels of issues.

• Values
  • Informational
  • Low
  • Medium
  • High
  • Critical

DetailLevel

Description: Represents the level of detail for the scan results.

• Values:
  • Short - Display only the total number of issues.
  • Summary - Display the number of issues per severity.
  • Detailed - Display all the found issue types.
  • Full - Display a fully detailed report.