@sectester/repeater
Package to manage repeaters and their lifecycle.
Repeaters are mandatory for scanning targets on a local network. More info about repeaters.
Setup
npm i -s @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 as constructor argument.
import { Configuration } from '@sectester/core';
import { RepeaterFactory } from '@sectester/repeater';
const configuration = new Configuration({
hostname: 'app.neuralegion.com'
});
const repeaterFactory = new RepeaterFactory(configuration);
The factory exposes the createRepeater
method that returns a new Repeater
instance:
const repeater = await repeaterFactory.createRepeater();
You can customize some properties, e.g. name prefix or description, passing options as follows:
const repeater = await repeaterFactory.createRepeater({
namePrefix: 'my-repeater',
description: 'My repeater'
});
The createRepeater
method accepts the options described below:
Option | Description |
---|---|
namePrefix |
Enter a name prefix that will be used as a constant part of the unique name. By default, sectester . |
description |
Set a short description of the Repeater. |
requestRunnerOptions |
Custom the request runner settings that will be used to execute requests to your application. |
projectId |
Specify the project ID to associate the Repeater with. |
disableRandomNameGeneration |
Disable random name generation for the Repeater's name. |
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:
export interface RequestRunnerOptions {
timeout?: number;
proxyUrl?: string;
headers?: Record<string, string | string[]>;
allowedMimes?: string[];
maxContentLength?: number;
reuseConnection?: boolean;
}
The RepeaterFactory
also provides a method to create a Repeater
instance using an existing repeater ID. You can use the createRepeaterFromExisting
method to accomplish this:
const existingRepeaterId = '<your repater ID>';
const repeater = await repeaterFactory.createRepeaterFromExisting(
existingRepeaterId
);
This method retrieves the existing repeater's details from the cloud using its ID and returns a Repeater
instance associated with the specified ID.
You can also customize the request runner options for the existing repeater by passing them as options:
const existingRepeaterId = '<your repater ID>';
const repeater = await repeaterFactory.createRepeaterFromExisting(
existingRepeaterId,
{
requestRunnerOptions: {
timeout: 10000,
maxContentLength: 200,
allowedMimes: ['text/html']
}
}
);
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:
import { Configuration } from '@sectester/core';
import { RepeaterFactory, Repeater } from '@sectester/repeater';
describe('Scan', () => {
let repeater!: Repeater;
beforeAll(async () => {
const configuration = new Configuration({
hostname: 'app.neuralegion.com'
});
repeater = await new RepeaterFactory(configuration).createRepeater();
await repeater.start();
});
afterAll(() => repeater.stop());
it('should be not vulnerable', () => {
// run scan of local target passing `repeater.repeaterId` to scan config
});
});
Implementation details
Under the hood Repeater
register ExecuteRequestEventHandler
in bus,
which in turn uses the RequestRunner
to proceed with request:
export interface RequestRunner {
protocol: Protocol;
run(request: Request): Promise<Response>;
}
Package contains RequestRunner
implementations for both HTTP and WS protocols.
To support other protocol new class implementation of RequestRunner
should be registered in global IoC container:
import { container } from 'tsyringe';
container.register(RequestRunner, {
useClass: 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.