Skip to content
Marcin Kozlowski edited this page Sep 6, 2024 · 25 revisions

Welcome to the betterscan-ce wiki!

What it does

It is a Code and Infrastructure (IaC) and Cloud-native Scanning/SAST/Static Analysis/Linting solution using many tools/Scanners with One Report. You can also add any tool to it. Currently, it supports many languages and tech stacks.

betterscan-concept

Fig. 1 Betterscan concept diagram

If you like it, please fork/watch/contribute. This will ensure continuous development

Run this command in your code directory (checkout from Git - .git folder needs to be there, if you work with the normal directory, make the Git repo out of it git init && git add . && git commit etc):

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli.sh)

or for an HTML report:

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli-html.sh)

That's it. You just checked your code for 2,300+ Checks (Defects, Vulnerabilities, Best Practices, Secrets - 166+ secret types) and 4,000+ YARA rules for Antidebug, Antivm, CVE, Exploits Kits, Malware, Web shells, and APTs.

FYI Above will maintain state via (.checkmate folder). Only new commits will be checked.

Use cases for you

This solutions should be part of DevOps/DevSecOps/Platform Engineering efforts. You can "shift left" your security efforts using below and providing tools to developers.

Local installation on your laptop

Just run for CLI:

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli.sh)

or for an HTML report:

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli-html.sh)

It will maintain state in .checkmate folder. First run can be longer, next should be very fast. Just re-run the same command on the next iteration.

Azure DevOps Integration

To integrate BetterScan with Azure DevOps, you can do the following:

  1. Install the Azure DevOps SARIF SAST Scans Tab extension.
  2. Add this job to your azure-pipelines.yml:
  - job: SAST
    displayName: Static Application Security Test (SAST)
    condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
    pool:
      vmImage: 'ubuntu-latest'
    container: 'sunsolution/betterscan-worker-cli:latest'
    steps:
    - script: |
        sudo apt-get update
        sudo apt-get install git-lfs
      displayName: Install git LFS
      
    - checkout: self
      persistCredentials: true

    - script: |
        set -e
        git config --global --add safe.directory $(Build.SourcesDirectory)
        git config --global user.email "azuredevops@microsoft.com"
        git config --global user.name "Azure DevOps" 
        git checkout -b $(Build.SourceBranchName)
        sudo CODE_DIR=$(Build.SourcesDirectory) checkmate init
        sudo CODE_DIR=$(Build.SourcesDirectory) checkmate git init
        sudo CODE_DIR=$(Build.SourcesDirectory) checkmate git analyze --branch $(Build.SourceBranchName)
        sudo CODE_DIR=$(Build.SourcesDirectory) checkmate issues html
      displayName: Static Application Security Test (SAST)
      env:
        CODE_DIR: '$(Build.SourcesDirectory)'

    - task: PublishBuildArtifacts@1
      displayName: Publish SAST report
      inputs:
        PathtoPublish: $(Build.SourcesDirectory)
        ArtifactName: CodeAnalysisLogs

    - script: |
        git add .checkmate/db.sqlite
        git add report.html
        git commit -m '[ci skip] update checkmate db'
        git push origin $(Build.SourceBranchName):$(Build.SourceBranch)
      displayName: Commit and Push checkmate db

Platforms & OS'es

It is platform independent (Python). Multibuilds are available (amd64, aarch64)

Usage

More info in the Wiki:

https://github.com/tcosolutions/betterscan-ce/wiki

Usage

You can plug it anywhere on your CI/CD pipeline as a command.

With Betterscan one command, you add 6,300+ checks using different scanners (Betterscan is a "Meta" scanner in that sense, with supporting smart snapshots and other goodies. It is not just running tools always on full code)

Betterscan works in CLI mode. Run a binary in Docker in your own CI/CD pipeline (whatever it is) in Quality Gates that will output line by line (scanner and findings) on checkout code from Git (folder)

Quick Install

Plain CLI output

Just run this command (it will take care of everything):

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli.sh)

See the script source for commands.

HTML CLI output

Just run this command (it will take care of everything):

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli-html.sh)

report will be in the directory under report.html

See the script source for commands.

SARIF output

Just run this command (it will take care of everything):

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli-html.sh)

report will be in the directory under report.sarif

See the script source for commands.

JSON output

Just run this command (it will take care of everything):

sh <(curl https://raw.githubusercontent.com/tcosolutions/betterscan-ce/main/cli-html.sh)

report will be in the directory under report.json

See the script source for commands.

Platform with Webinterface and workers

Docker

If you need CI/CD and Web Interface, you need Docker-Compose installed as well, if you don't already have it.

Run in command prompt:

git clone git@github.com:tcosolutions/betterscan.git
cd betterscan/dockerhub
docker compose up

or Kubernetes (minukube also)

Under betterscan-chart

Please install under name betterscan

helm repo add betterscan-repo https://marcinguy.github.io/betterscan-chart
helm repo update
helm install betterscan betterscan-repo/betterscan

Open up the Browser to:

http://localhost:5000

Detailed explanation

Build Docker image Worker-CLI and run checkmate from there. Below is a sample flow:

CLI Mode only

  1. Clone the repo i.e into /tmp/samplecode
  2. set env var CODE_DIR i.e export CODE_DIR=/tmp/samplecode. This env var should point to your Git cloned repo dir. Set LIC env var.
  3. Cd into it (this is important!)
  4. Run checkmate init
  5. Run checkmate git init
  6. Run checkmate git analyze

Run checkmate issues

This will be shown

Loading plugin: git
Loading plugin: trojansource
Loading plugin: bandit
Loading plugin: brakeman
Loading plugin: semgrep
Loading plugin: tfsec
Loading plugin: kubescape
Loading plugin: semgrepeslint
Loading plugin: graudit
Loading plugin: text4shell
Loading plugin: gostaticcheck

There is a DockerHub image also for it ready.

docker pull tcosolutions/betterscan-ce:worker-cli

You can run the Commands with docker as below:

$ docker run -ti  sunsolution/betterscan-worker-cli:latest checkmate
Loading plugin: git
Loading plugin: trojansource
Loading plugin: bandit
Loading plugin: brakeman
Loading plugin: semgrep
Loading plugin: tfsec
Loading plugin: kubescape
Loading plugin: semgrepeslint
Loading plugin: graudit
Loading plugin: text4shell
Loading plugin: gostaticcheck
Usage: checkmate [command] [command] [...] [args]

Type "checkmate help" for help

Under the hood

Bandit, Brakeman, gostaticcheck, semgrep, njsscan, log4shell via custom semgrep rule, kubescape, graudit, flawfinder, find sec bugs, eslint, tfsec and other(s). Some were modified. See LICENSE for licensing and acknoweledgements.

Major features

Betterscan uses static analysis (semantic and graph analysis) to find bugs and defects.

  • Betterscan supports Cloud-native and Infrastructure Scanning
  • Betterscan supports secrets Scanning (166+ secret types)
  • Betterscan scans for 4,000 rules for Antidebug, Antivm, Crypto, CVE, Exploits Kits, Malware and Web shells, APTs
  • Betterscan can be extended with any tool producing JSON output (any binary, in any technology/language/product)
  • Betterscan is open Source
  • Betterscan supports scanning only changed files (differential analysis). You can store state in Database (PostgreSQL, MySQL/MariaDB, Oracle, Microsoft SQL Server) or in you Git repo.
  • Outputs in CLI, HTML, SARIF, JSON
  • Betterscan uses many tools adding up to 6,300+ checks which also semgrep as one of the tools

Welcome to Betterscan CE (Community Edition)!

Betterscan is based on QuantifedCode. Available as a CLI (to run as a command and get outputs in Terminal or HTML, SARIF outputs)

Currently supports: PHP, Java, Scala, Python, PERL, Ruby, C, C++, Swift, Kotlin, Apex (Salesforce), GO, Infrastructure as a Code (IaC) Security and Best Practices (Docker, Kubernetes (k8s), Terraform AWS, GCP, Azure), Secret Scanning (166+ secret types), Trojan Source, Open Source and Proprietary Checks (total ca. 6,000+ checks). Checks for misconfigurations across all major (and some minor) cloud providers (AWS Checks, Azure Checks, GCP Checks, CloudStack Checks, DigitalOcean Checks, GitHub Checks, Kubernetes Checks, OpenStack Checks, Oracle Checks)

Advantages:

  • Many tools, one report (unification)
  • Dismiss, and collaborate on findings. Mark false-positives
  • Enable/disable each individual check in Checkers
  • ca. 6,300+ checks now (Linters, Static Code Analysis/Code Scanning, YARA ca. 4000 YARA binary matching/textual matching rules for Antidebug, Antivm, Crypto, CVE, Exploits Kits, Malware and Webshells, APTs )
  • any tool outputting JSON can be added
  • fast (checks only new code on recheck)
  • you can store state in Database (PostgreSQL, MySQL/MariaDB, Oracle, Microsoft SQL Server) or in you Git repo.
  • Outputs in CLI, HTML, SARIF, JSON.
  • Git support (HTTPS/TLS and SSH). For private repositories only SSH.
  • Swiss army knife tool/SIEM for Code Scanning
  • 100% Code transparency & full control of your code

Contribute

Contributing

Feel free to use, recommend improvements, or contribute to new implementations.

Licensing

Betterscan's QuantifiedCode parts remain released under BSD-3 Clause License. However, modifications are released under AGPL-3.0 (see LICENSE in the repo for more details)