SecTester.Core 0.41.1

SecTester.Core

The core 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.Core

Usage

Configuration

First, you need to generate a new instance of Configuration.

var config = new Configuration(
    hostname: "app.brightsec.com",
    credentials: new Credentials("your API key"));

You can also register the configuration using the dependency injection framework providing information that will be used to construct other clients.

public void ConfigureServices(IServiceCollection services)
{
  services.AddSecTesterConfig("app.brightsec.com");
  // or
  services.AddSecTesterConfig(config);
}

Options

Configuration can be customized using the following options:

public interface IConfiguration {
  string Hostname
  {
    get;
  }
  Credentials? Credentials
  {
    get;
  }
  IEnumerable<ICredentialProvider>? CredentialProviders
  {
    get;
  }
  LogLevel LogLevel {
    get;
  }
}

The default configuration is as follows:

{
  credentialProviders = new List<ICredentialProvider> { new EnvCredentialProvider() }
}

hostname

• type: string

Set the application name (domain name), that is used to establish connection with.

var config = new Configuration(hostname: "app.brightsec.com");

credentials

• type: Credentials

Set credentials to access the application.

var config = new Configuration(
  // ...
  credentials: new Credential("your API key"));

More info about setting up an API key

credentialProviders

• type: ICredentialProvider[]

Allows you to provide credentials and load it in runtime. The configuration will invoke one provider at a time and only continue to the next if no credentials have been located. For example, if the process finds values defined via the BRIGHT_TOKEN environment variables, the file at .sectesterrc will not be read.

EnvCredentialProvider

Use this provider to read credentials from the following environment variable: BRIGHT_TOKEN

If the BRIGHT_TOKEN environment variable is not set or contains a falsy value, it will return undefined.

var credentialsProvider = new EnvCredentialProvider();
var config = new Configuration(
  // ...
  credentialProviders: new List<ICredentialProvider> { credentialsProvider });

Messages

Message is used for syncing state between SDK, application and/or external services. This functionality is done by sending messages outside using a concrete implementation of Dispatcher.

Depending on the type of derived class from the Message, it might be addressed to only one consumer or have typically multiple consumers as well. When a message is sent to multiple consumers, the appropriate event handler in each consumer handles the message.

The Message is a data-holding class, but it implements a Visitor pattern to allow clients to perform operations on it using a visitor class (see Dispatcher) without modifying the source.

For instance, you can dispatch a message in a way that is more approach you or convenient from the client's perspective.

public record Ping : Event
{
  public readonly string Status;
}

var @event = new Ping("connected");

// using a visitor pattern
await @event.Execute(dispatcher);

// or directly
await dispatcher.execute(@event);

The same is applicable for the Event. You just need to use the EventDispatcher instead of CommandDispatcher.

Each message have a correlation ID to ensure atomicity. The regular UUID is used, but you might also want to consider other options.

Request-response

The request-response message (aka Command) style is useful when you need to exchange messages between various external services. Using Command you can easily ensure that the service has actually received the message and sent a response back.

To create an instance of Command use the abstract class as follows:

public record RequestOptions
{
  public string Url;
  public string Method;
  public Dictionary<string, string>? headers;
  public string? Body;
}

public record RequestOutput
{
  public int Status;
  public Dictionary<string, string>? headers;
  public string? Body;
}

private record Request(RequestOptions Payload) : Command<RequestOutput>
{
  public RequestOptions Payload = Payload;
}

To adjust its behavior you can use next options:

Publish-subscribe

When you just want to publish events without waiting for a response, it is better to use the Event. The ideal use case for the publish-subscribe model is when you want to simply notify another service that a certain condition has occurred.

To create an instance of Event use the abstract class as follows:

public record Issue
{
  public string Name;
  public string Details;
  public string Type;
  public string? Cvss;
  public string? Cwe;
}

private record IssueDetected(Issue Issue) : Event
{
  public Issue Issue = Issue;
}

To adjust its behavior you can use next options:

To create an event handler, you should implement the Handler interface and use the IoC container to register a handler using the interface as a provider:

public class IssueDetectedHandler : EventHandler<Issue>
{
  public Task<Unit> Handle(IssueDetected @event)
  {
    // implementation
    return Unit.Task;
  }
}

It is not possible to register multiple event handlers for a single event pattern.

As soon as the IssueDetected event appears, the event handler takes a single argument, the data passed from the client (in this case, an event payload which has been sent over the network).

License

Copyright © 2022 Bright Security.

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