SecTester.Scan 0.29.2

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:

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.