Norad
The norad gem is a command line interface (CLI) to create new security tests and interface with an instance of norad. Currently, the project only contains code to create new security tests.
Dependencies
To use this tool to create new security tests, the only dependencies is Docker. The easiest way to install Docker is through the community edition.
The above site contains all the necessary information to install Docker on a Mac, Windows, or Linux machines.
Installation
This utility can be installed simply by:
$ gem install norad_cli
Once installed, a norad executable should be available.
Usage
The norad executable has several subcommands to aid a developer in creating security tests. The tool contains a help interface to provide information about the available subcommand and options. An example of the available help:
$ norad help
Commands:
norad help [COMMAND] # Describe available commands or one specific command
norad repo <command> # Commands for norad security repos housing security tests.
norad sectest <command> # Commands to create new security tests.
Additional help for subcommands (e.g. repo or sectest) is available by:
$ norad repo help
Commands:
norad repo create REPONAME # Create a new norad security test repository called REPONAME
norad repo help [COMMAND] # Describe subcommands or one specific subcommand
Individual help for a command is available with:
$ norad repo create --help
Usage:
norad create REPONAME
Create a new norad security test repository called REPONAME
Repo Subcommand
The repo subcommand creates a new git repository to house new security tests. It is a helper command which ensures new repositories conform to standard layout and ci best practices. To create a new repository for housing multiple security tests:
$ norad repo create asig-security
Initializing a new norad security test repository
create asig-security/base
create asig-security/spec
License the repo under Apache 2? y
Who is the copyright holder (Default: Cisco Systems, Inc.)?
create asig-security/LICENSE
create asig-security/.gitlab.ci.yml
create asig-security/.gitignore
create asig-security/CONTRIBUTING.md
create asig-security/README.md
The user will be prompted whether to license the code under Apache 2 and for the copyright holder. The norad framework is released under the Apache 2 license, test content is not required to be licensed the same.
As shown, a new directory, asig-security, has been created and multiple files created. Changing directory into asig-security and running git status shows a new git repository waiting for an initial commit:
$ git status
On branch master
Initial commit
Untracked files:
(use "git add <file>..." to include in what will be committed)
.gitignore
.gitlab.ci.yml
CONTRIBUTING.md
LICENSE
README.md
nothing added to commit but untracked files present (use "git add" to track)
The repo command is only useful when starting an entirely new repository to house multiple security tests! For general security test development inside of an existing repository see the below sectest subcommand.
Sectest Subcommand
The sectest subcommand is where general security test tool development occurs. The sectest subcommand can scaffold a new security test, build security test docker images, test images, execute a security test, and create a seed file for important into a Norad instance. A listing of the current commands is:
$ norad help sectest
Commands:
norad sectest build # Build all sectest images and specs for the entire repository
norad sectest build:all SECTESTNAME # Build sectest images for SECTESTNAME and all testing images for SECTESTNAME
norad sectest build:image SECTESTNAME # Build the docker image for the security test SECTESTNAME
norad sectest build:specs SECTESTNAME # Build the spec images (test images) for the security test SECTESTNAME
norad sectest execute SECTESTNAME # Execute SECTESTNAME against an arbitrary target
norad sectest help [COMMAND] # Describe subcommands or one specific subcommand
norad sectest scaffold TESTNAME # Create a new security test with standard files + testing
norad sectest seed # Create the containers.rb seed to import into the api
norad sectest spec # Run all rspec tests for the entire repo (all sectests)
norad sectest spec:image SECTESTNAME # Run the rspec tests for SECTESTNAME
norad sectest validate # Validate all manifest.yml and readme.md
norad sectest validate:image SECTESTNAME # Validate SECTESTNAME manifest.yml and readme.md
Sectest Execute Command
The execute command enables users to run any SECTESTNAME container against an arbitrary target. To see the available options for the subcommand, run:
$ norad sectest -h execute
Usage:
norad execute SECTESTNAME
Options:
-d, [--debug], [--no-debug] # Turn on debugging messages (e.g. Docker build logs to stdout)
-f, [--format], [--no-format] # Print the JSON results formatted
-r, [--registry=REGISTRY] # The Docker registry for Docker images
# Default: norad-registry.cisco.com:5000
-v, [--version=VERSION] # The version of the sectest container to build
# Default: latest
Execute SECTESTNAME against an arbitrary target
Since the execute command runs arbitrary SECTESTNAME containers, it must support dynamically setting options for those containers. Therefore, the command supports gathering and printing help with any SECTESTNAME container. To get the help for a container run:
$ norad sectest execute SECTESTNAME -h
The execute subcommand reads the SECTESTNAME's manifest.yml to determine all available options. An example of this behavior is:
$ norad sectest execute sec-ops-sudo -h
Usage:
norad execute sec-ops-sudo
Options:
-d, [--debug], [--no-debug] # Turn on debugging messages (e.g. Docker build logs to stdout)
-f, [--format], [--no-format] # Print the JSON results formatted
-r, [--registry=REGISTRY] # The Docker registry for Docker images
# Default: norad-registry.cisco.com:5000
-v, [--version=VERSION] # The version of the sectest container to build
# Default: latest
-t, [--target=TARGET] # The IP or FQDN of the host to test
-u, [--ssh-user=SSH_USER] # If the sectest requires authentication, then the username for authentication
-p, [--port=PORT] # The port to use for testing
-k, [--ssh-key=SSH_KEY] # If the sectest requires authentication, then the path to the ssh key file
Execute sec-ops-sudo against an arbitrary target
Development
Contributing
Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/norad/cli