Scanner-Cli - A Projection Security/Vulnerability/Risk Scanning Tool

The Hawkeye scanner-cli is a projection security, vulnerability as well as full general gamble highlighting tool. It is meant to hold upwardly integrated into your pre-commit hooks as well as your pipelines.

Running as well as configuring the scanner
The Hawkeye scanner-cli assumes that your directory construction is such that it keeps the toolchain's files on top level. Roughly, this is what it boils downwards to:

• Node.js projects have got a package.json on top level
• Ruby projects volition have got a Gemfile on top level
• Python projects volition have got a requirements.txt on top level
• PHP projects volition have got a composer.lock on top level
• Java projects volition have got a build (gradle) or target (maven) folder, as well as include .java as well as .jar files

This is non exhaustive equally sometimes tools require farther files to exist. To empathise how the modules produce upwardly one's hear whether they tin handgrip a project, delight cheque the How it works department as well as the modules folder.

Docker (recommended)
The docker picture is hands-down the easiest agency to the scanner. Please authorities annotation that your projection root (e.g. $PWD) needs to hold upwardly mounted to /target.

docker run --rm -v $PWD:/target hawkeyesec/scanner-cli

The docker fix is also the recommended agency to run the scanner inwards your CI pipelines. This is an instance of running Hawkeye against ane of your projects inwards GoCD:

                                                pull             hawkeyesec/scanner-cli                                                -c             docker run --rm -v $PWD:/target hawkeyesec/scanner-cli                                                 

npm
You tin install as well as run hawkeye inwards a Node.js projection via

npm install --save-dev @hawkeyesec/scanner-cli npx hawkeye scan

This method is recommended inwards a Node.js project, where the other toolchains (e.g. python, ruby) are non required.
With this method, it is also recommended to invoke the scanner inwards a git pre-commit claw (e.g. via the pre-commit package) to neglect the commit if issues are found.

Configuration Files (recommended)
You tin configure the scanner via .hawkeyerc as well as .hawkeyeignore files inwards your projection root.
The .hawkeyerc file is a JSON file that allows yous to configure ...

• the modules to run,
• the writers to use, and
• the failure threshold

{     "all": true|false,     "staged": true|false,     "modules": ["files-ccnumber", "java-owasp", "java-find-secbugs"],     "sumo": "http://your.sumologic.foobar/collector",     "http": "http://your.logger.foobar/collector",     "json": "log/results.json",     "failOn": "low"|"medium"|"high"|"critical",     "showCode": true|false }

The .hawkeyeignore file is a collection of regular expressions matching paths as well as module mistake codes to exclude from the scan, as well as is equivalent to using the --exclude flag. Lines starting amongst # are regarded equally comments.
Please authorities annotation that whatever particular charaters reserved inwards regular expressions (-[]{}()*+?.,^$|#\s) demand to hold upwardly escaped when used equally a literal!
Please also authorities annotation that the module mistake codes are normally non shown, since they are non primarily relevant for the user. If yous desire to exclude a for certain faux positive, yous tin display the module mistake codes amongst the flag --show-code or the showCode belongings inwards the .hawkeyerc.

^test/  # this is a comment  ^README.md

The CLI
Use hawkeye modules to listing the available modules as well as their status.

> npx hawkeye modules [info] Version: v1.4.0 [info] Module Status [info] Enabled:   files-ccnumber [info]            Scans for suspicious file contents that are probable to incorporate credit carte du jour numbers [info] Enabled:   files-contents [info]            Scans for suspicious file contents that are probable to incorporate secrets [info] Disabled:  files-entropy [info]            Scans files for strings amongst high entropy that are probable to incorporate passwords [info] Enabled:   files-secrets [info]            Scans for suspicious filenames that are probable to incorporate secrets [info] Enabled:   java-find-secbugs [info]            Finds mutual security issues inwards Java code amongst findsecbugs [info] Enabled:   java-owasp [info]            Scans Java projects for gradle/maven dependencies amongst known vulnerabilities amongst the OWASP dependency checker [info] Enabled:   node-crossenv [info]            Scans node projects for known malicious crossenv dependencies [info] Enabled:   node-npmaudit [info]            Checks node projects for dependencies amongst known vulnerabilities [info] Enabled:   node-npmoutdated [info]            Checks node projects for outdated npm modules [info] Enabled:   node-yarnaudit [info]            Checks yarn projects for dependencies amongst known vulnerabilities [info] Enabled:   node-yarnoutdated [info]            Checks node projects for outdated yarn modules [info] Enabled:   php-security-checker [info]            Checks whether the composer.lock contains dependencies amongst known vulnerabilities using security-checker [info] Enabled:   python-bandit [info]            Scans for mutual security issues inwards Python code amongst bandit. [info] Enabled:   python-piprot [info]            Scans python dependencies for out of appointment packages [info] Enabled:   python-safety [info]            Checks python dependencies for known security vulnerabilities amongst the security tool. [info] Enabled:   ruby-brakeman [info]            Statically analyzes Rails code for security issues amongst Brakeman. [info] Enabled:   ruby-bundler-scan [info]            Scan for Ruby gems amongst known vulnerabilities using bundler```  Use `hawkeye scan` to kicking off a scan: 

npx hawkeye scan --help [info] Version: v1.3.0 Usage: hawkeye-scan [options]

Options: -a, --all Scan all files, regardless if a git repo is found. Defaults to tracked files inwards git repositories. -t, --target [/path/to/project] The place to scan. Defaults to $PWD. -f, --fail-on [low|medium|high|critical] Set the marker at which hawkeye returns non-zero condition codes. Defaults to low. -m, --module [module name] Run specific module. Defaults to all applicable modules. -e, --exclude [pattern] Specify ane or to a greater extent than exclusion patterns (eg. test/*). Can hold upwardly specified multiple times. -j, --json [/path/to/file.json] Write findings to file. -s, --sumo [https://sumologic-http-connector] Write findings to SumoLogic. -H, --http [https://your-site.com/api/results] Write findings to a given url. --show-code Shows the code the module uses for reporting, useful for ignoring for certain faux positives -g, --staged Scan alone git-staged files. -h, --help output usage information

 # Results  #### Exit Codes  The scanner-cli responds amongst the next move out codes:  * Exit code 0 indicates no findings higher upwardly or equal to the minimum threshold were found. * Exit code 1 indicates that issues were constitute higher upwardly or equal to the minimum threshold. * Exit code 42 indicates that an unexpected mistake happened somewhere inwards the program. This is probable a põrnikas as well as should non happen. Please cheque the log output as well as study a bug.  #### Redirecting the console output  If yous wishing to redirect the console logger output, the recommended method is latching onto stdout. In this example, we're making role of both JSON as well as stdout results:  ```bash docker run --rm -v $PWD:/target hawkeyesec/scanner-cli -j hawkeye-results.json -f critical 2>&1 | tee hawkeye-results.txt

Console output
By default, the scanner outputs its results to the console inwards tabular form.

Sumologic
The results tin hold upwardly sent to a SumoLogic collector of your choice. In this example, nosotros have got a collector amongst a unmarried HTTP source.

hawkeye scan --sumo https://collectors.us2.sumologic.com/receiver/v1/http/your-http-collector-url

In SumoLogic, search for _collector="hawkeye" | json auto:

Any HTTP endpoint
Similar to the SumoLogic example, the scanner tin ship the results to whatever given HTTP endpoint that accepts POST messages.

hawkeye scan --http http://your.logging.foobar/endpoint

The results volition hold upwardly sent amongst User-Agent: hawkeye. Similar to the console output, the next JSON volition hold upwardly POSTed for each finding:

{   "module": "files-contents",   "level": "critical",   "offender": "testfile3.yml",   "description": "Private cardinal inwards file",   "mitigation": "Check trace number: 3" }

How it works
Hawkeye is designed to hold upwardly extensible yesteryear adding modules as well as writers.

• Add modules inwards the modules folder.
• Add writers inwards the writers folder.

Modules
Modules are basically niggling bits of code that either implement their ain logic, or wind a 3rd political party tool as well as standardise the output. They alone run if the required criteria are met. For example: The npm outdated module would alone run if a package.json is detected inwards the scan target - equally a result, yous don't demand to nation Hawkeye what type of projection yous are scanning.

Generic Modules

• files-ccnumber: Scans for suspicious file contents that are probable to incorporate credit carte du jour numbers
• files-contents: Scans for suspicious file contents that are probable to incorporate secrets
• files-entropy: Scans files for strings amongst high entropy that are probable to incorporate passwords. Entropy scanning is disabled yesteryear default because of the high number of faux positives. It is useful to scan codebases every forthwith as well as and hence for keys, inwards which instance delight run it delight using the -m files-entropy switch.
• files-secrets: Scans for suspicious filenames that are probable to incorporate secrets

Java

• java-find-secbugs: Finds mutual security issues inwards Java code amongst findsecbugs
• java-owasp: Scans Java projects for gradle/maven dependencies amongst known vulnerabilities amongst the OWASP dependency checker

Node.js

• node-crossenv: Scans node projects for known malicious crossenv dependencies
• node-npmaudit: Checks node projects for dependencies amongst known vulnerabilities amongst npm audit
• node-npmoutdated: Checks node projects for outdated npm modules amongst npm outdated
• node-yarnaudit: Checks yarn projects for dependencies amongst known vulnerabilities amongst yarn audit
• node-yarnoutdated: Checks node projects for outdated yarn modules amongst yarn outdated

PHP

• php-security-checker: Checks whether the composer.lock contains dependencies amongst known vulnerabilities using security-checker

Python

• python-bandit: Scans for mutual security issues inwards Python code amongst bandit.
• python-piprot: Scans python dependencies for out of appointment packages amongst piprot
• python-safety: Checks python dependencies for known security vulnerabilities amongst the security tool.

Ruby

• ruby-brakeman: Statically analyzes Rails code for security issues amongst Brakeman.
• ruby-bundler-scan: Scan for Ruby gems amongst known vulnerabilities using bundler

Adding a module
If yous have got an persuasion for a module, delight experience costless opened upwardly a characteristic asking inwards the issues section. If yous have got a flake of fourth dimension left, delight reckon sending us a push clit request. To encounter modules work, delight caput over to the modules folder to disclose how things are working.

Download Scanner-Cli