SecTester.Repeater 0.25.0

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 RepeaterFactory constructed with Configuration instance.

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

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<RepeaterFactory>();
    _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 register RequestExecutingEventHandler in bus, which in turn uses the RequestRunner to proceed with request:

public interface RequestRunner
{
  Protocol Protocol
{
  get;
}

Task<Response> Run(Request request);
}

We are going to provide RequestRunner implementations for both HTTP and WS protocols soon.

To support other protocol new class implementation of RequestRunner should be registered in the IoC container:

collection.AddScoped<RequestRunner, CustomProtocolRequestRunner>();

Limitations

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

License

Copyright © 2022 Bright Security.

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