SecTester.Scan 0.41.4

SecTester.Scan

The scan package can be used to obtain a config including credentials from different sources, and provide a simplified abstraction to handle events and commands.

Setup

$ dotnet add package SecTester.Scan

Usage

To start scanning your application, you have to configure and retrieve a ScanFactory as follows:

var scanFactory = serviceProvider.GetService<ScanFactory>();

To create a new scan, you have to define a target first (for details, see here):

var target = new Target("https://example.com");

The factory exposes the CreateScan method that returns a new Scan instance:

await using var result = scanFactory.CreateScan(new ScanSettings(
  target,
  new List<TestType>() { TestType.HeaderSecurity }));

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.

For example, you could call the WithTarget method to specify the target for the scan, the WithTests method to specify the tests to run, and the Build method to create a ScanSettings object with those settings.

Defining a target for attack

The target can accept the following options:

Url

• type: string

The server URL that will be used for the request. Usually the Url represents a WHATWG URL:

var target = new Target(
  "https://example.com"
);

If Url contains a query string, they will be parsed as search params:

const target = new Target(
  "https://example.com?foo=bar"
);

If you pass a Query parameter, it will override these which obtained from Url:

var target = new Target("https://example.com?foo=bar")
  .WithQuery(new Dictionary<string, string>() { { "bar", "foo" } });

Method

• type: string | HttpMethod

The request method to be used when making the request, GET by default:

var target = new Target("https://example.com")
  .WithMethod(HttpMethod.Delete);

Query

• type: IEnumerable<KeyValuePair<string, string>>

The query parameters to be sent with the request:

var target = new Target("https://example.com")
  .WithQuery(new Dictionary<string, string>()
  {
    {"hello", "world"},
    {"foo", "123"}
  });

This will override the query string in url.

It is possible to define a custom serializer for query parameters:

using Cysharp.Web;

var target = new Target("https://example.com")
  .WithQuery(new Dictionary<string, string>()
  {
    {"foo", "bar"},
    {"foo", "baz"}
  }, query => WebSerializer.ToQueryString(query));

Headers

• type: IEnumerable<KeyValuePair<string, IEnumerable<string>>>

The HTTP headers to be sent:

var target = new Target("https://example.com")
  .WithHeaders(new Dictionary<string, IEnumerable<string>>()
  {
    { "content-type", new List<string> { "application/json" } },
  });

Body

• type: string | HttpContent

The data to be sent as the request body. Makes sense only for POST, PUT, PATCH, and DELETE:

var target = new Target("https://example.com")
  .WithBody(@"{""foo"":""bar""}", "application/json");

You can use any derived class of HttpContent, such as MultipartContent, as request body as well:

var content = new MultipartFormDataContent {
  {
    new StringContent("Hello, world!", Encoding.UTF8, "text/plain"),
    "greeting"
  }
};
var target = new Target("https://example.com")
  .WithBody(content);

Managing a scan

The Scan provides a lightweight API to revise and control the status of test execution.

For instance, to get a list of found issues, you can use the issues method:

var issues = await scan.Issues();

To wait for certain conditions you can use the expect method:

await scan.Expect(Severity.High);
var issues = await scan.Issues();

It returns control as soon as a scan is done, timeout is gone, or an expectation is satisfied.

You can also define a custom expectation passing a function that accepts an instance of Scan as follows:

await scan.Expect(async scan => {
    var issues = await scan.Issues();

    return issues.Count() > 3;
});

You can use the Status method to obtain scan status, to ensure that the scan is done and nothing prevents the user to check for issues, or for other reasons:

await foreach (var state in scan.Status())
{
  // your code
}

This await foreach...in will work while a scan is active.

To stop scan, use the Stop method:

await scan.Stop();

To delete a scan while disposing, you just need to set the DeleteOnDispose option in the ScanOptions as follows:

await using var scan = scanFactory.CreateScan(settings, new ScanOptions { DeleteOnDispose = true });

await scan.Expect(Severity.High);

License

Copyright © 2022 Bright Security.

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