@sectester/scan

The package defines a simple public API to manage scans and their expectations.

Setup

npm i -s @sectester/scan

Usage

To start scanning your application, you have to create a ScanFactory as follows:

import { Configuration } from '@sectester/core';
import { ScanFactory } from '@sectester/scan';

const config = new Configuration({
  hostname: 'app.neuralegion.com'
});

const scanFactory = new ScanFactory(config);

To create a new scan, you have to define a target first (for details, see here):

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com'
});

The factory exposes the createScan method that returns a new Scan instance:

import { TestType } from '@sectester/scan';

const scan = await scanFactory.createScan({
  target,
  tests: [TestType.HEADER_SECURITY]
});

Below you will find a list of parameters that can be used to configure a Scan:

Defining a target for attack

The target can accept the following options:

url

• type: string

The server URL that will be used for the request. Usually the url represents a WHATWG URL:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com'
});

If url contains a query string, they will be parsed as search params:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com?foo=bar'
});

console.log(target.queryString); // foo=bar

If you pass a query parameter, it will override these which obtained from url:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com?foo=bar',
  query: '?bar=foo'
});

console.log(target.queryString); // bar=foo

method

• type: string | HttpMethod

The request method to be used when making the request, GET by default:

import { Target, HttpMethod } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com',
  method: HttpMethod.DELETE
});

query

• type: string | URLSearchParams | Record

The query parameters to be sent with the request:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com',
  query: {
    hello: 'world',
    foo: '123'
  }
});

console.log(target.queryString); // hello=world&foo=123

If you need to pass an array, you can do it using a URLSearchParams instance:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com',
  query: new URLSearchParams([
    ['key', 'a'],
    ['key', 'b']
  ])
});

console.log(target.queryString); // key=a&key=b

> This will override the query string in url.

It is possible to define a custom serializer for query parameters:

import { Target } from '@sectester/scan';
import { stringify } from 'qs';

const target = new Target({
  url: 'https://example.com',
  query: { a: ['b', 'c', 'd'] },
  serializeQuery(params: Record): string {
    return stringify(params);
  }
});

console.log(target.queryString); // a[0]=b&a[1]=c&a[2]=d

headers

• type: Record

The HTTP headers to be sent:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com',
  headers: {
    'content-type': 'application/json'
  }
});

body

• type: unknown

The data to be sent as the request body. Makes sense only for POST, PUT, PATCH, and DELETE:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com',
  body: {
    foo: 'bar'
  }
});

You can use FormData objects, such as form-data, as request body as well:

import { Target } from '@sectester/scan';
import FormData from 'form-data';

const form = new FormData();
form.append('greeting', 'Hello, world!');

const target = new Target({
  url: 'https://example.com',
  body: form
});

It is possible to set a form as body using an instance of URLSearchParams:

import { Target } from '@sectester/scan';

const target = new Target({
  url: 'https://example.com',
  body: new URLSearchParams('foo=bar')
});

Managing a scan

The Scan provides a lightweight API to revise and control the status of test execution.

For instance, to get a list of found issues, you can use the issues method:

const issues = await scan.issues();

To wait for certain conditions you can use the expect method:

await scan.expect(Severity.HIGH);
const issues = await scan.issues();

> It returns control as soon as a scan is done, timeout is gone, or an expectation is satisfied.

You can also define a custom expectation passing a function that accepts an instance of Scan as follows:

await scan.expect((scan: Scan) => scan.done);

It might return a Promise instance as well:

await scan.expect(async (scan: Scan) => {
  const issues = await scan.issues();

  return issues.length > 3;
});

You can use the status method to obtain scan status, to ensure that the scan is done and nothing prevents the user to check for issues, or for other reasons:

for await (const state of scan.status()) {
  // your code
}

> This for...of will work while a scan is active.

To stop scan, use the stop method:

await scan.stop();

To dispose a scan, you just need to call the dispose method:

await scan.dispose();

License

Copyright © 2024 Bright Security.

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