Awesome

SecTester SDK Demo

Table of contents

• About this project
• About SecTester
• Setup
  • Fork and clone this repo
  • Get a Bright API key
  • Explore the demo application
  • A full configuration example
  • Recommended tests
  • Example of a CI configuration
• Documentation & Help
• Contributing
• License

About this project

This is a demo project for the SecTester JS SDK framework, with some installation and usage examples. We recommend forking it and playing around, that’s what it’s for!

About SecTester

Bright is a developer-first Dynamic Application Security Testing (DAST) scanner.

SecTester is a new tool that integrates our enterprise-grade scan engine directly into your unit tests.

With SecTester you can:

• Test every function and component directly
• Run security scans at the speed of unit tests
• Find vulnerabilities with no false positives, before you finalize your Pull Request

Trying out Bright’s SecTester is free 💸, so let’s get started!

⚠️ Disclaimer

The SecTester project is currently in beta as an early-access tool. We are looking for your feedback to make it the best possible solution for developers, aimed to be used as part of your team’s SDLC. We apologize if not everything will work smoothly from the start, and hope a few bugs or missing features will be no match for you!

Thank you! We appreciate your help and feedback!

Setup

Fork and clone this repo

1. Press the ‘fork’ button to make a copy of this repo in your own GH account
2. In your forked repo, clone this project down to your local machine using either SSH or HTTP

Get a Bright API key

1. Register for a free account at Bright’s signup page
2. Optional: Skip the quickstart wizard and go directly to User API key creation
3. Create a Bright API key (check out our doc on how to create a user key)
4. Save the Bright API key
   1. We recommend using your Github repository secrets feature to store the key, accessible via the Settings > Security > Secrets > Actions configuration. We use the ENV variable called BRIGHT_TOKEN in our examples
   2. If you don’t use that option, make sure you save the key in a secure location. You will need to access it later on in the project but will not be able to view it again.
   3. More info on how to use ENV vars in Github actions

⚠️ Make sure your API key is saved in a location where you can retrieve it later! You will need it in these next steps!

Explore the demo application

Navigate to your local version of this project. Then, in your command line, install the dependencies:

$ npm ci

The whole list of required variables to start the demo application is described in .env.example file. The template for this .env file is available in the root folder.

After that, you can easily create a .env file from the template by issuing the following command:

$ cp .env.example .env

Once this template is done, copying over (should be instantaneous), navigate to your .env file, and paste your Bright API key as the value of the BRIGHT_TOKEN variable.

BRIGHT_TOKEN = <your_API_key_here>

To initialize DB schema, you should execute a migration, as shown here:

$ npm run migration:up

Finally, perform this command in terminal to run the application:

$ npm start

Note: Alternatively, you can quickly run the SecTester SDK Demo app using Docker:

docker build -t sectester-js-demo-image . && docker run --name sectester-js-demo -p 3000:3000 -d sectester-js-demo-image

While having the application running, open a browser and type http://localhost:3000/api, and hit enter. You should see the Swagger UI page for that application that allows you to test the RESTFul CRUD API, like in the following screenshot:

If you need the JSON schema for any reason, such as for discovery purposes, it can be accessed at: http://localhost:3000/api-json.

To explore the Swagger UI:

• Click on the POST /users endpoint
• Click on the "Try it out" button
• Click on the blue "Execute" button
• Then you should see a view similar to the following, where you can see the JSON returned from the API:

Then you can start tests with SecTester against these endpoints as follows (make sure you use a new terminal window, as the original is still running the API for us!)

$ npm run test:sec

You will find tests written with SecTester in the ./test/sec folder.

This can take a few minutes, and then you should see the result, like in the following screenshot:

 FAIL  test/sec/users.e2e-spec.ts (453.752 s)
  /users
    POST /
      ✓ should not have XSS (168279 ms)
    GET /:id
      ✕ should not have SQLi (282227 ms)

  ● /users › GET /:id › should not have SQLi

    IssueFound: Target is vulnerable

    Issue in Bright UI:   https://app.brightsec.com/scans/mKScKCEJRq2nvVkzEHUArB/issues/4rXuWAQTekbJfa9Rc7vHAX
    Name:                 SQL Injection: Blind Boolean Based
    Severity:             High
    Remediation:
    If available, use structured mechanisms that automatically enforce the separation between data and code. These mechanisms may be able to provide the relevant quoting, encoding, and validation automatically, instead of relying on the developer to provide this capability at every point where output is generated. Process SQL queries using prepared statements, parameterized queries, or stored procedures. These features should accept parameters or variables and support strong typing. Do not dynamically construct and execute query strings within these features using 'exec' or similar functionality, since this may re-introduce the possibility of SQL injection
    Details:
    A SQL injection attack consists of insertion or 'injection' of a SQL query via the input data from the client to the application. A successful SQL injection exploit can read sensitive data from the database, modify database data (Insert/Update/Delete), execute administration operations on the database (such as shutdown the DBMS), recover the content of a given file present on the DBMS file system and in some cases issue commands to the operating system. SQL injection attacks are a type of injection attack, in which SQL commands are injected into data-plane input in order to effect the execution of predefined SQL commands, In a BLIND SQLi scenario there is no response data, but the application is still vulnerable via boolean-based (10=10) and other techniques.
    Extra Details:
    ● Injection Points
        Parameter: #1* (URI)
            Type: boolean-based blind
            Title: AND boolean-based blind - WHERE or HAVING clause
            Payload: http://localhost:56774/users/1 AND 2028=2028
        Database Banner: 'postgresql 14.3 on x86_64-pc-linux-musl, compiled by gcc (alpine 11.2.1_git20220219) 11.2.1 20220219, 64-bit'

    References:
    ● https://cwe.mitre.org/data/definitions/89.html
    ● https://www.owasp.org/index.php/Blind_SQL_Injection
    ● https://brightsec.com/blog/blind-sql-injection/

      at SecScan.assert (../packages/runner/src/lib/SecScan.ts:59:13)
          at runMicrotasks (<anonymous>)
      at SecScan.run (../packages/runner/src/lib/SecScan.ts:37:7)
      at Object.<anonymous> (sec/users.e2e-spec.ts:71:7)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 passed, 2 total
Snapshots:   0 total
Time:        453.805 s
Ran all test suites matching /test\/sec/i.

A full configuration example

Now you will look under the hood to see how this all works. In the following example, we will test the app we just set up for any instances of SQL injection. Jest is provided as the testing framework, that provides assert functions and test-double utilities that help with mocking, spying, etc.

To start the webserver within the same process with tests, not in a remote environment or container, we use Nest.js testing utilities. You don’t have to use Nest.js, but it is what we chose for this project. The code is as follows:

test/sec/users.e2e-spec.ts

import { UsersModule } from '../../src/users';
import config from '../../src/mikro-orm.config';
import { INestApplication } from '@nestjs/common';
import { Test, TestingModule } from '@nestjs/testing';
import { MikroOrmModule } from '@mikro-orm/nestjs';

describe('/users', () => {
  let app!: INestApplication;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [UsersModule, MikroOrmModule.forRoot(config)]
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  afterAll(() => app.close());
});

The @sectester/runner package provides a set of utilities that allows scanning the demo application for vulnerabilities. Let's expand the previous example using the built-in SecRunner class:

let runner!: SecRunner;
let app!: INestApplication;

// ...

beforeEach(async () => {
  runner = new SecRunner({ hostname: 'app.brightsec.com' });

  await runner.init();
});

afterEach(() => runner.clear());

To set up a runner, create a SecRunner instance on the top of the file, passing a configuration as follows:

import { SecRunner } from '@sectester/runner';

const runner = new SecRunner({ hostname: 'app.brightsec.com' });

After that, you have to initialize a SecRunner instance:

await runner.init();

The runner is now ready to perform your tests. To start scanning your endpoint, first, you have to create a SecScan instance. We do this with runner.createScan as shown in the example below.

Now, you will write and run your first unit test!

Let's verify the GET /users/:id endpoint for SQLi:

describe('GET /:id', () => {
  it('should not have SQLi', async () => {
    await runner
      .createScan({
        tests: [TestType.SQLI]
      })
      .run({
        method: 'GET',
        url: `${baseUrl}/users/1`
      });
  });
});

This will raise an exception when the test fails, with remediation information and a deeper explanation of SQLi, right in your command line!

Let's look at another test for the POST /users endpoint, this time for XSS.

describe('POST /', () => {
  it('should not have XSS', async () => {
    await runner
      .createScan({
        tests: [TestType.XSS]
      })
      .run({
        method: 'POST',
        url: `${baseUrl}/users`,
        body: { firstName: 'Test', lastName: 'Test' }
      });
  });
});

As you can see, writing a new test for XSS follows the same pattern as SQLi.

Finally, to run a scan against the endpoint, you have to obtain a port to which the server listens. For that, we should adjust the example above just a bit:

let runner!: SecRunner;
let app!: INestApplication;
let baseUrl!: string;

beforeAll(async () => {
  // ...

  const server = app.getHttpServer();

  server.listen(0);

  const port = server.address().port;
  const protocol = app instanceof Server ? 'https' : 'http';
  baseUrl = `${protocol}://localhost:${port}`;
});

Now, you can use the baseUrl to set up a target:

await scan.run({
  method: 'GET',
  url: `${baseUrl}/users/1`
});

By default, each found issue will cause the scan to stop. To control this behavior you can set a severity threshold using the threshold method. Since SQLi (SQL injection) is considered to be high severity issue, we can pass Severity.HIGH for stricter checks:

scan.threshold(Severity.HIGH);

To avoid long-running test, you can specify a timeout, to say how long to wait before aborting it:

scan.timeout(300000);

To make sure that Jest won't abort tests early, you should align a test timeout with a scan timeout as follows:

jest.setTimeout(300000);

To clarify an attack surface and speed up the test, we suggest making clear where to discover parameters according to the source code.

src/users/users.service.ts

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  public findOne(@Param('id') id: number): Promise<User | null> {
    return this.usersService.findOne(id);
  }
}

For the example above, it should look like this:

const scan = runner.createScan({
  tests: [TestType.SQLI],
  attackParamLocations: [AttackParamLocation.PATH]
});

Finally, the test should look like this:

it('should not have SQLi', async () => {
  await runner
    .createScan({
      tests: [TestType.SQLI],
      attackParamLocations: [AttackParamLocation.PATH]
    })
    .threshold(Severity.MEDIUM)
    .timeout(300000)
    .run({
      method: 'GET',
      url: `${baseUrl}/users/1`
    });
});

Here is a completed test/sec/users.e2e-spec.ts file with all the tests and configuration set up.

import { UsersModule } from '../../src/users';
import config from '../../src/mikro-orm.config';
import { SecRunner } from '@sectester/runner';
import { AttackParamLocation, Severity, TestType } from '@sectester/scan';
import { INestApplication } from '@nestjs/common';
import { Test, TestingModule } from '@nestjs/testing';
import { ConfigModule } from '@nestjs/config';
import { MikroOrmModule } from '@mikro-orm/nestjs';
import { Server } from 'https';

describe('/users', () => {
  const timeout = 300000;
  jest.setTimeout(timeout);

  let runner!: SecRunner;
  let app!: INestApplication;
  let baseUrl!: string;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [
        UsersModule,
        ConfigModule.forRoot(),
        MikroOrmModule.forRoot(config)
      ]
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();

    const server = app.getHttpServer();

    server.listen(0);

    const port = server.address().port;
    const protocol = app instanceof Server ? 'https' : 'http';
    baseUrl = `${protocol}://localhost:${port}`;
  });

  afterAll(() => app.close());

  beforeEach(async () => {
    runner = new SecRunner({ hostname: process.env.BRIGHT_HOSTNAME! });

    await runner.init();
  });

  afterEach(() => runner.clear());

  describe('POST /', () => {
    it('should not have XSS', async () => {
      await runner
        .createScan({
          tests: [TestType.XSS],
          attackParamLocations: [AttackParamLocation.BODY]
        })
        .threshold(Severity.MEDIUM)
        .timeout(timeout)
        .run({
          method: 'POST',
          url: `${baseUrl}/users`,
          body: { firstName: 'Test', lastName: 'Test' }
        });
    });
  });

  describe('GET /:id', () => {
    it('should not have SQLi', async () => {
      await runner
        .createScan({
          tests: [TestType.SQLI],
          attackParamLocations: [AttackParamLocation.PATH]
        })
        .threshold(Severity.MEDIUM)
        .timeout(timeout)
        .run({
          method: 'GET',
          url: `${baseUrl}/users/1`
        });
    });
  });
});

Full documentation can be found in the @sectester/runner README.

Recommended tests

Example of a CI configuration

You can integrate this library into any CI you use, for that you will need to add the BRIGHT_TOKEN ENV vars to your CI. Then add the following to your github actions configuration:

steps:
  - name: Run sec tests
    run: npm run test:sec
    env:
      BRIGHT_TOKEN: ${{ secrets.BRIGHT_TOKEN }}
      BRIGHT_HOSTNAME: app.brightsec.com

For a full list of CI configuration examples, check out the docs below.

Documentation & Help

• Full documentation available at: https://docs.brightsec.com/
• Join our Discord channel and ask anything!

Contributing

Please read contributing guidelines here.

License

Copyright © 2022 Bright Security.

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