SecTester.Repeater 0.41.3

SecTester.Repeater

Package to manage repeaters and their lifecycle.

Repeaters are mandatory for scanning targets on a local network. More info about repeaters.

Setup

$ dotnet add package SecTester.Repeater

Usage

To establish a secure connection between the Bright cloud engine and a target on a local network, you just need to use the IRepeaterFactory constructed with Configuration instance.

var repeaterFactory = serviceProvider.GetService<IRepeaterFactory>();

The factory exposes the CreateRepeater method that returns a new Repeater instance:

await using var repeater = await repeaterFactory.CreateRepeater();

You can customize some properties, e.g. name prefix or description, passing options as follows:

await using var repeater = await repeaterFactory.CreateRepeater(new RepeaterOptions {
  NamePrefix = 'my-repeater',
  Description = 'My repeater'
});

The CreateRepeater method accepts the options described below:

The default requestRunnerOptions is as follows:

{
    "timeout": 30000, 
    "maxContentLength": 100,
    "reuseConnection": false,
    "allowedMimes": [
        "text/html",
        "text/plain",
        "text/css",
        "text/javascript",
        "text/markdown",
        "text/xml",
        "application/javascript",
        "application/x-javascript",
        "application/json",
        "application/xml",
        "application/x-www-form-urlencoded",
        "application/msgpack",
        "application/ld+json",
        "application/graphql"
      ]
}

The RequestRunnerOptions exposes the following options that can used to customize the request runner's behavior: RequestRunnerOptions.cs

The Repeater instance provides the Start method. This method is required to establish a connection with the Bright cloud engine and interact with other services.

await repeater.Start();

To dispose of the connection, stop accepting any incoming commands, and handle events, you can call the Stop method if the Repeater instance is started:

await repeater.Stop();

Repeater instance also has a RepeaterId field, that is required to start a new scan for local targets.

Usage in unit tests

There are multiple strategies of how to run a repeater: before-all or before-each (recommended). The two most viable options are running before all the tests vs running before every single test.

Below you can find the implementation of before-each strategy:

public class ScanTests: IAsyncDisposable, IAsyncLifetime
{
  // ...
  private readonly Repeater _repeater;

  public ScanTests()
  {
    // ...
    var repeaterFactory = serviceProvider.GetService<IRepeaterFactory>();
    _repeater = repeaterFactory.CreateRepeater();
  }

  public async Task InitializeAsync()
  {
     await _repeater.Start();
  }

  public async ValueTask DisposeAsync()
  {
    await _repeater.DisposeAsync();

    GC.SuppressFinalize(this);
  }

  [Fact]
  public void BeNotVulnerable()
  {
    // run scan of local target passing `repeater.repeaterId` to scan config
  }
}

Implementation details

Under the hood Repeater uses the IRequestRunner to proceed with request:

public interface IRequestRunner
{
  Protocol Protocol
{
  get;
}

Task<IResponse> Run(IRequest request);
}

The package provide a single RequestRunner implementations for HTTP protocol. To add support for other protocols, new implementation of IRequestRunner should be registered in the IoC container:

collection.AddScoped<IRequestRunner, CustomProtocolRequestRunner>();

Limitations

Custom scripts and self-signed certificates (see Bright CLI) are not supported yet.

License

Copyright © 2022 Bright Security.

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