SecTester.Runner 0.32.1

SecTester.Scan

Run scanning for vulnerabilities just from your unit tests on CI phase.

Setup

$ dotnet add package SecTester.Runner

Step-by-step guide

Configure SDK

To start writing tests, first obtain a Bright token, which is required for the access to Bright API. More info about setting up an API key.

Then put obtained token into BRIGHT_TOKEN environment variable to make it accessible by default EnvCredentialProvider.

Refer to SecTester.Core documentation for the details on alternative ways of configuring credential providers.

Once it is done, create a configuration object. Single required option is Bright Hostname domain you are going to use, e.g. app.neuralegion.com as the main one:

using SecTester.Core;

var config = new Configuration("app.neuralegion.com");

Setup runner

To set up a runner, create SecRunner instance passing a previously created configuration as follows:

using SecTester.Core;
using SecTester.Runner;

var config = new Configuration("app.neuralegion.com");
await using var runner = SecRunner.Create(configuration);

After that, you have to initialize a SecRunner instance:

await runner.Init();

The runner is now ready to perform your tests, but you have to create a scan.

To dispose a runner, you just need to call the Clear or DisposeAsync method:

await runner.Clear();

// or

await runner.DisposeAsync();

Starting scan

To start scanning your application, first you have to create a SecScan instance, as shown below:

await using var scan = await runner.CreateScan(new ScanSettingsBuilder()
    .WithTests(new List<TestType> { TestType.Xss }));

Below you will find a list of parameters that can be used to configure a Scan:

We provide a fluent interface for building a ScanSettings object. To use it, you start by creating a ScanSettingsBuilder instance, and then you call its methods to specify the various settings you want to use for the scan as shown above.

Finally, run a scan against your application:

var target = new Target("https://localhost:8000/api/orders")
  .WithMethod(HttpMethod.Post)
  .WithBody(@"{ ""subject"": ""Test"", ""body"": ""<script>alert('xss')</script>"" }", "application/json");

await scan.Run(target);

The Run method takes a single argument (for details, see here), and returns promise that is resolved if scan finishes without any vulnerability found, and is rejected otherwise (on founding issue that meets threshold, on timeout, on scanning error).

If any vulnerabilities are found, they will be pretty-printed to stderr (depending on the testing framework) and formatted depending on chosen Formatter.

By default, each found issue will cause the scan to stop. To control this behavior you can set a severity threshold using the Threshold method:

scan.Threshold(Severity.High);

Now found issues with severity lower than High will not cause the scan to stop.

Sometimes either due to scan configuration issues or target misbehave, the scan might take much more time than you expect. In this case, you can provide a timeout for specifying maximum scan running time:

scan.Timeout(TimeSpan.FromSeconds(30));

In that case after 30 seconds, if the scan isn't finishing or finding any vulnerability, it will throw an error.

Usage sample

using System.Configuration;
using SecTester.Runner;
using SecTester.Scan;
using SecTester.Scan.Models;

public class SecRunnerFixture : IAsyncLifetime
{
  public SecRunner Runner { get; private set; }

  public async Task InitializeAsync()
  {
    var hostname = ConfigurationManager.AppSettings["BrightHost"];
    // create a test runner
    Runner = await SecRunner.Create(new SecTester.Core.Configuration(hostname));
    // initialize a test runner
    await Runner.Init();
  }

  public async Task DisposeAsync()
  {
    if (Runner is not null)
    {
      // clean up runner
      await Runner.DisposeAsync();
    }

    GC.SuppressFinalize(this);
  }
}

public class OrdersApiTests : IClassFixture<SecRunnerFixture>, IAsyncDisposable
{
  private readonly SecRunnerFixture _fixture;
  private readonly SecScan _test;

  public OrdersApiTests(SecRunnerFixture fixture)
  {
    _fixture = fixture;
    _test = _fixture
      .Runner
      .CreateScan(new ScanSettingsBuilder()
        .WithTests(new List<TestType> { TestType.Xss }))
      .Threshold(Severity.Medium)
      .Timeout(TimeSpan.FromMinutes(5));
  }

  public async ValueTask DisposeAsync()
  {
    await _fixture.DisposeAsync();
    GC.SuppressFinalize(this);
  }

  [Fact]
  public async Task Post_ApiOrder_ShouldNotHavePersistentXss()
  {
    var target = new Target("https://localhost:8000/api/orders")
      .WithMethod(HttpMethod.Post)
      .WithBody(@"{ ""subject"": ""Test"", ""body"": ""<script>alert('xss')</script>"" }", "application/json");

    await _test.Run(target);
  }

  [Fact]
  public async Task Get_ApiOrder_ShouldNotHaveReflectiveXss()
  {
    var target = new Target("https://localhost:8000/api/orders")
      .WithQuery(new Dictionary<string, string> { { "q", "<script>alert('xss')</script>" } });

    await _test.Run(target);
  }
}

License

Copyright © 2022 Bright Security.

This project is licensed under the MIT License - see the LICENSE file for details.