Sentinel automated security testing framework
npm install sentinel-ast
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.
It has been designed from ground-up to be completely extensible.
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.
``bash`
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
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
`bash`
sh -c "$(curl -fsSL https://raw.githubusercontent.com/nintexplatform/sentinel/master/bin/install-dependencies.sh)"
`bash`
npm install -g sentinel-ast
From this point, see the For Developers section below on how to use Sentinel.
Getting Sentinel to run is simple and done primarily through a global(if npm installed with -g) CLI.
` bash
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.
Sample
:
`
{
"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 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`)| 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 | - |