adding_scanner.md

Overview

Salus is a tool for coordinating the execution of security Scanners. Salus supports multiple scanners like Bandit, Brakeman, Semgrep, etc, however as new programming languages get introduced there is always a need to add new scanners to Salus.

This document describes the steps needed to add a new Scanner to Salus

Steps

This section describes high-level check-list style steps for adding a programming language specific security scanner to Salus

Pre Check

• Evaluate various scanners available for scanning security vulnerabilities for a programming language and select the best one to integrate. This allows us to have a single high quality scanner compared to multiple low quality scanners.
• Please review the LICENSE specified by the scanner or open source libraries or projects that will be included. Libraries with permissive LICENSE such as Apache License 2.0 can be included while libraries with restrictive LICENSE cannot be included.

Implementation

• Update Dockerfile to install any dependencies that are required to run the scanner. Sample PR.
• Implement the scanner by adding a new class to lib/salus/scanners/. Use CargoAudit implementation for reference.
  • run function implements the core logic of the scanner.
  • should_run? function implements logic of when to run a scanner. Update lib/salus/repo.rb with the IMPORTANT files we look for.
  • We also want to implement certain functions such as supported_languages and scanner_type to be in spec.
  • For more information, refer CUSTOM SALUS.
• Implement configuration options for Salus scanner that are exposed by the underlying scanner. We aim for the Salus scanner to be non-opinionated as this allows the end users to override and implement their own configs. Use NPMAudit for reference.
• Implement Exception logic to allow users to exclude certain findings.
  • fetch_exception_ids built in function will return the list of ids specified in salus.yaml.
  • Use Bandit for reference.
• Add SARIF report generation logic as this allows us to combine results from different scanners in a standardized format. Sample implementation for reference.
• Implement unit tests for the scanner implemented. Sample test case implementation.

Documentation

• Add/Update Documentation: Make sure to add a scanner specific documentation in salus/docs/scanners. Sample GoOSV documentation.

References

• GradleOSV scanner support Pull Request: #563