HCL.AppScan.AUDIT 1.0.0

AppScan Unit-Level DAST Intelligence Tester - AUDIT

1. Introduction

Name: AppScan Unit-Level DAST Intelligence Tester - AUDIT
Version: 1.0.0
Description: Run quick, targeted Dynamic Application Security Testing (DAST) within your Integrated Development Environment (IDE). AUDIT performs fast DAST scans on specific endpoints, ideal for evaluating incremental code changes. This function allows early detection and remediation of vulnerabilities, minimizing security risks during development.
Purpose: AUDIT integrates security testing into unit testing phases, aiding developers in promptly identifying and addressing security vulnerabilities, thus enhancing the security and efficiency of the development process.
Key Features: Fast and precise vulnerability scanning.

System requirements

• OS:
  • Microsoft® Windows® Server 2025: Standard.
  • Microsoft® Windows® Server 2022: Standard and Datacenter.
  • Microsoft® Windows® 11: Pro and Enterprise.
  • Microsoft® Windows® 10: Pro and Enterprise.
    Note: In general, any OS that is End of life (EOL) is not supported.
• .Net 8.0 or later

2. Installation

Prerequisite:

1. HCL AppScan DAST Scanner 10.9.0: Go to My HCLSoftware and download the AppscanDASTSDK-Win.zip package, which is also available as part of AppScan Standard 10.9.0.
2. AppScan Standard license (either CLS or LLS)

Visual Studio

1. Right click on your project.
2. Click on Manage NuGet
3. In the Browse tab, search for HCL.AppScan.AUDIT and install it for your selected project.

Installing through Command Line Interface (CLI) on Windows

1. Verify that you have .Net 8.0 or later installed and configured in your path.

   dotnet --version
   

2. Navigate to the project folder
3. Install the HCL.AppScan.AUDIT package

   dotnet add package HCL.AppScan.AUDIT --version 1.0.0
   

3. Getting Started

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

Quick startup

using HCL.AppScan.AUDIT;

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

        Scanner = new Scanner(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
        ScanResults scanResults = Scanner.Scan(httpRequestMessage);
        //Asserting the results using MSTest (Choose which Unit test framework fits best)
        Assert.IsFalse(scanResults.HasVulnerabilities(Severity.High), scanResults.ToString(DetailLevel.Detailed));
    }
}

4. API Documentation

Classes

<a name="Scanner"></a>

Scanner

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

Methods

• Scanner(Configuration? config = null)

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

• Scan(HttpRequestMessage httpRequestMessage, ScanConfig? scanConfig = null)

  • 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: ScanResults - The results of the scan.
  • Example:

    var httpRequest = new HttpRequestMessage(HttpMethod.Get, "https://example.com/api");
    var scanResults = Scanner.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: ScanResults - 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 = Scanner.Scan(uri, rawRequest);
    

• Dispose()

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

Properties

• Config
  • Description: Gets the configuration for the Scanner instance.
  • Type: Configuration

<a name="Configuration"></a>

Configuration

Description: Represents the configuration for the Scanner 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 it is assumed that the license is already configured through AppScan Standard/App Scan CLI.
  • Type: string?
  • Default Value: null <a name="ScanResults"></a>

ScanResults

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

Methods

• ScanResults(string xmlReportPath)

  • Description: Initializes a new instance of the ScanResults 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. <a name="ScanConfig"></a>

ScanConfig

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

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

<a name="Severity"></a>

Severity

Description: Represents the severity levels of issues.

• Values
  • Informational
  • Low
  • Medium
  • High
  • Critical <a name="DetailLevel"></a>

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.