@sectester/core
Version:
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.
199 lines (138 loc) • 6.41 kB
Markdown
# @sectester/core
[](https://codeclimate.com/github/NeuraLegion/sectester-js/maintainability)
[](https://codeclimate.com/github/NeuraLegion/sectester-js/test_coverage)
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
```bash
npm i -s @sectester/core
```
## Usage
### Configuration
First, you need to generate a new instance of `Configuration`.
```ts
import { Configuration } from '@sectester/core';
const config = new Configuration({
hostname: 'app.brightsec.com',
projectId: 'your project ID',
credentials: {
token: 'your API key'
}
});
```
After that, you can resolve the configuration using the IoC container.
```ts
const config = config.container.resolve(Configuration);
```
#### Options
Configuration can be customized using the following options:
```ts
export interface ConfigurationOptions {
hostname?: string;
projectId?: string;
credentials?: Credentials;
logLevel?: LogLevel;
credentialProviders?: CredentialProvider[];
}
```
The default configuration is as follows:
```js
{
logLevel: LogLevel.ERROR,
credentialProviders: [new EnvCredentialProvider()];
}
```
#### hostname
- type: `string`
Set the hostname (domain name) used to establish a connection.
```ts
import { Configuration } from '@sectester/core';
const config = new Configuration({
hostname: 'app.brightsec.com'
});
```
> [!NOTE]
> If you omit the `hostname` parameter, 'app.brightsec.com' will be used by default.
#### projectId
- type: `string`
Set the ID of the project you want to work with.
```ts
import { Configuration } from '@sectester/core';
const config = new Configuration({
// ...
projectId: 'your project ID'
});
```
> [!TIP]
> The project ID can be found in the URL of the project page. For example, in the URL `https://app.brightsec.com/projects/1234`, the project ID is `1234`. We recommend using the dedicated project ID for each application.
> [!WARNING]
> If you omit the `projectId` parameter, we will use the default project ID. This is not recommended especially if you have multiple projects.
#### logLevel
- type: `LogLevel`
Set the maximum log level to report.
```ts
import { Configuration, LogLevel } from '@sectester/core';
const config = new Configuration({
// ...
logLevel: LogLevel.ERROR
});
```
#### credentials
- type: `Credentials`
Set credentials for accessing the application.
```ts
import { Configuration } from '@sectester/core';
const config = new Configuration({
// ...
credentials: {
token: 'your API key'
}
});
```
More info about [setting up an API key](https://docs.brightsec.com/docs/manage-your-personal-account#manage-your-personal-api-keys-authentication-tokens)
#### credentialProviders
- type: `CredentialProvider[]`
Allows you to provide credentials that are loaded at 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.
```ts
import { Configuration, EnvCredentialProvider } from '@sectester/core';
const credentialsProvider = new EnvCredentialProvider();
const config = new Configuration({
// ...
credentialProviders: [credentialsProvider]
});
```
### ApiClient
The `ApiClient` interface and its implementation `FetchApiClient` provide a robust way to handle HTTP requests with built-in retry logic, rate limiting, and error handling.
```ts
import { FetchApiClient } from '@sectester/core';
const client = new FetchApiClient({
baseUrl: 'https://app.brightsec.com',
apiKey: 'your-api-key',
timeout: 5000 // optional, defaults to 5000ms
});
// Make a request
const response = await client.request('/api/v1/scans');
```
The `FetchApiClient` includes the following features:
- Automatic retry for idempotent requests (GET, HEAD, PUT, DELETE, OPTIONS, TRACE)
- Rate limiting handling with automatic retry based on 'Retry-After' header
- Configurable timeout
- API key authentication
- Automatic handling of redirects (status 409)
- JSON content type by default
The client can be configured using the following options:
| Option | Type | Default | Description |
| ------------ | -------------------------------------------- | ------------------------------------------------------------ | --------------------------------------- |
| baseUrl | string | - | Base URL for all API requests |
| apiKey | string | - | API key for authentication |
| apiKeyPrefix | string | 'Api-Key' | Prefix used in the Authorization header |
| timeout | number | 5000 | Request timeout in milliseconds |
| userAgent | string | sectester-js/<version> | User agent string |
| retry | [RetryOptions](./src/api/RetryHandler.ts#L5) | See [FetchApiClient.ts](./src/api/FetchApiClient.ts#L32-L35) | Retry options for the client |
## License
Copyright © 2025 [Bright Security](https://brightsec.com/).
This project is licensed under the MIT License - see the [LICENSE file](LICENSE) for details.