Sentinel

Sentinel is a framework that enables automated security testing via a suite of industry standard test frameworks and security tools.

It is built on Cucumber and Node.js. This allows for security test cases to be defined in Gherkin/BDD syntax making them human readable and self documenting. The idea is that we make security testing a concept that is approachable(tests written by developers, testers, security guys), repeatable(when integrated with your CI/CD pipelines) and auditable(when used to gather evidence in compliancy initiatives).

Sentinel was inspired by existing security frameworks(Gauntlt, Mittn, BDD-Security) but we felt the need to provide our own flavour to security testing with a modern javascript and docker based environment.

Features

Sentinel is currently integrated with

• Automated security scanners - Open Zap, SSLyze and snyk to find security vulnerabilities in your web applications.
• Selenium/WebDriver and Node.js for implementing browser and API based automated tests.
• Docker/Compose that enables drop-in isolation of integrated components during runtime. It also enables what we call the Bring-Your-Own-Container(s) feature, which gives consumers of Sentinel the capability to attach their web applications/services as containers onto Sentinels' networking infrastructure.
• Reporting tools.

It has been designed from ground-up to be completely extensible.

Quickstart

We want to get you off the ground and started as quick as possible in just a few steps. Running commands below on your shell will install Node.js, Docker and Sentinel running security tests against a local containerized website.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/nintexplatform/sentinel/master/bin/install-dependencies.sh)"
git clone https://github.com/nintexplatform/sentinel-example.git && cd sentinel-example
npm install 
npm run test

On Linux, run the install-dependencies script under sudo for root privileges.

Once the tests have completed, you can find a generated report under sentinel-example/report directory

We've introduced an example use case of Sentinel in the sentinel-example repo

Getting Started

To install the framework:

1. Install prequisites
2. Install Sentinel via npm

Install Prerequisites

These prerequisites must be installed first.

1. Node.js Version 7+
2. Docker
3. Docker Compose

Alternatively, for Docker + Compose, you can also install Docker for Mac or Windows which is a fast and easy way to get Docker + Compose.

-or-

Use our quick-install script

sh -c "$(curl -fsSL https://raw.githubusercontent.com/nintexplatform/sentinel/master/bin/install-dependencies.sh)"

Install Sentinel via npm

npm install -g sentinel-ast

From this point, see the For Developers section below on how to use Sentinel.

For Developers

Sentinel CLI

Getting Sentinel to run is simple and done primarily through a global(if npm installed with -g) CLI.

sentinel

  Usage: sentinel [options] [command]


  Options:

    -V, --version  output the version number
    -h, --help     output usage information


  Commands:

    init                             Initializes configuration & test templates in the current directory
    run-compose [COMMAND] [ARGS...]  Runs docker compose commands
    run-cucumber [options] [DIR]     Runs cucumber tests
    start-services [options]         Starts services in its containers
    stop-services [options]          Stops services and its containers

sentinel init

• From an empty directory, you should always run this command first. It initializes the current directory with a default config.env, feature templates and config json files.
• The default parameters in config.env are explained below. They should be configured prior to starting up the services.

sentinel start-services

• This command starts all integrated services as containers.

sentinel stop-services

• This command stops all containers hosting integrated services.

sentinel run-compose

• This command proxies the CLI arguments to Docker compose.

sentinel run-cucumber

• This command proxies the CLI arguments to Cucumber-js.

Integrations

The framework ships with a few integrated components out of the box. If they are hosted within containers, we refer to them as services.

Cucumber Report

Adds cucumber hooks to create a report at the end of a test run.
Integrates the Cucumber Html Reporter

Slack

Adds hooks to post results at the end of a test run to Slack.

Node

This is a general purpose Node.js container that tests are run in.
It reads environment variables from config.env Node Version 7+

Selenium WebDriver

The node Selenium WebDriver package.
It has cucumber hooks to configure the webdriver and adds the driver instance to the world.
It also has a docker service for running a chrome container for remote control of the browser.

SSLyze

A service which can be used for running a SSLyze scan against a host.
GitHub

Zap

A service which hosts OWASP ZAP.
GitHub

Snyk

A service which can be used for packages and dependency scanning projects. snyk.io

Enabling integrations

Enabling integrations and loading up additional services is managed via a config file. It needs to be created in the root folder of the project that references Sentinel, as .sentinel.json

Sample .sentinel.json :

{
  "integrations": {
    "whitelist": [
      "node",
      "docker",
      "cucumber-report",
      "selenium",
      "sslyze",
      "zap"
    ],
    "customServices": [
        "./nodegoat-app/docker-compose.yml"
    ]
  }
}

Extensibility

Extending the framework starts with packaging your new component as a sub-directory within the /integration directory. These components can hook into the Sentinel runtime in a number of ways.

• Cucumber support files
  Any files found in a components cucumber folder gets required when starting tests.
  This can be used to add step definitions, modify the world, add hooks etc.
  (Refer to /integration/selenium)
• Docker container/service
  Required binaries, cli tools, etc can be exposed as a webservice by adding a compose-*.yml file in the integrations folder. This lets you define containers that can host the cli and allows test code to use REST calls to access it by service name. (Refer to /integration/sslyze)
• Javascript module
  You can create reusable Page Objects or interfaces needed to communicate to services by including the classes and exporting them from the index.js in the framework's root directory. By doing so, consumers of the Sentinel framework can have access to these objects at runtime.
  (Refer to /integration/zap)

Environment Variables

| Integration | Name | Description | Required | Default / Optional Values | |---------------------|-----------------------------|--------------------------------|----------|-------------| | sslyze | SSLYZE_SERVER_URL | Url to sslyze api server | false | http://sslyze:8081/ | | zap | ZAP_SERVER_URL | Url to zap api server | false | http://zap:8080/ | | zap | ZAP_MAX_DEPTH | zap crawling max depth | false | 5 | | zap | ZAP_THREAD_DEPTH | zap thread number | false | 5 | | snyk | SNYK_TOKEN | Auth token for snyk| false | | | snyk | SNYK_URL | Url to snyk api server | false | http://snyk:8086/ | | application | AUT_SERVER_URL | Url to application under test | true | https://nodegoat:4000 | | selenium | SELENIUM_BROWSER | Webdriver capabilities | false | chrome | | selenium | SELENIUM_REMOTE_URL | Webdriver url | true | http://selenium:4444/wd/hub | | selenium | SELENIUM_REMOTE_CAPABILITY | For remote selenium services | false | ./remoteSelenium.config.template.json | | selenium | WEBDRIVER_PAGE_TIMEOUT | Webdriver page load timeout | false | 45000 | | selenium | WEBDRIVER_LONG_TIMEOUT | Timeout for long running step | false | 30000 | | selenium | EXECUTION_ENVIRONMENT | For zap proxy | false | local (default) / proxy / remote | | cucumber | FEATURE_DIR | Feature file location | false | ./features/ | | cucumber | CUCUMBER_LONG_TIMEOUT | timeout for cucumber steps | false | 30000 | | cucumber-report | CUCUMBER_REPORT_DIR | path to store reports | false | ./report/ | | slack | SLACK_FEATURE | ON or OFF the process | false | 'ON' / 'OFF' (default) |
| slack | SLACK_WEBHOOK_URI | Specify the Incoming webhooks url - Reference | false | - |