1. Installation with installer
    1. Installation on Ubuntu
      1. Pre-installation checks
      2. Installation steps
      3. Upgrade an older version
      4. Install standalone corona
      5. Upgrade standalone Corona
      6. Limitations
    2. Installation on Windows
      1. Pre-installation checks
      2. Installation steps
      3. Upgrade an older version
      4. Install standalone corona
      5. Upgrade standalone corona
    3. Installation on Redhat Enterprise Linux or CentOS
      1. Pre-installation checks
      2. Installation steps
      3. Upgrade an older version
      4. Install standalone corona
      5. Upgrade standalone corona
      6. Limitations
  2. Installation with docker
    1. Requirements
    2. Download docker image from Embold release
    3. Installing Docker engine
    4. Steps to run Embold with docker-compose
    5. Installing Embold Docker image
    6. Installing Embold Docker and Corona (Embold Analyser) Docker for remote scan
  3. Embold behind proxy
    1. Embold through docker
    2. Embold through installer
  4. Backup & Restore
    1. Prerequisites for database backup
    2. Backup & restore on Windows
      1. Database backup
      2. Database restoration
    3. Backup & restore on Ubuntu/RHEL/CentOS
      1. Database backup
      2. Database restoration
  5. Post Installation Server Configuration
    1. Postgres Configuration
    2. Configuring Server Port
  6. C++ Configuration
    1. C++ Strict Mode
      1. Embold Trace
      2. Running analysis in strict mode
    2. C++ Fuzzy Mode
      1. Improving accuracy in fuzzy mode
      2. Additional parser options
  7. Integration with CI/CD tools
    1. Embold setup without CI Integration (Default setup)
    2. Remote Analysis
      1. Prerequisites
      2. Steps to run remote analysis
      3. Configuration for https enabled Embold
    3. GitLab Integration
      1. CI Integration pipeline
      2. Prerequisites
      3. Installations Steps
    4. Jenkins Integration
      1. Prerequisites
      2. Installation Steps
      3. Integration Modes
      4. Configure Plugin Logs
      5. Embold Quality Gate
      6. Update Embold Jenkins Plugin
      7. Coverlet Integration
      8. MSTest Integration
    5. SonarQube Integration
      1. Prerequisites
      2. Steps for Integrating SonarQube with Embold
      3. Configuration Notes
      4. Mapping between SonarQube and Embold severity
    6. TeamCity Integration
      1. Prerequisites
      2. Installation Steps
    7. IDE Plugins
      1. Eclipse Plugin
        1. Prerequisites
        2. Installation Steps
        3. Analysis of output
      2. IntelliJ Plugin
        1. Prerequisites
        2. Installation steps
        3. Analysis of output
        4. Code checker configuration
      3. Visual Studio Plugin
        1. Prerequisites
        2. Installation Steps
        3. User Authentication for Visual Studio Plugin
        4. Code Analysis on Visual Studio Plugin
        5. Analysis of output
        6. Limitations
      4. VS Plugin Marketplace Installation
        1. Prerequisites
        2. Installation steps
        3. Analysis of output
        4. Code Checker Configuration
    8. Embold CLI
      1. Prerequisites
      2. Configuration
      3. Embold CLI Commands
  8. Modules

Installation with installer

This guide will help you install and setup Embold on supported operating systems.
Note: We recommend you close your current browser window to make the installation process smooth.  
Yes No

Installation on Ubuntu

Before you begin, please verify that you have a supported version of Ubuntu here.

Yes No

Pre-installation checks

  • For seamless installation and execution, Embold should be installed on a clean machine/VM.
  • Embold works with Node.js version 10.22.1. Ensure that the machine on which Embold is getting installed has no Node.js installed.
  • To install .NET 3.0, run the following commands:
    wget -q https://packages.microsoft.com/config/ubuntu/16.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
    sudo dpkg -i packages-microsoft-prod.deb
    sudo apt-get update
    sudo apt-get install apt-transport-https
    sudo apt-get update
    sudo apt-get install dotnet-sdk-3.0
  • Any process or software update should be stopped, before establishing with Embold installation. To check if the ‘apt’ process is running run the following command:
    ps aux | grep apt
    To kill the ‘apt’ process use command:
    sudo kill -9
  • For more details, refer to the specifications section.
Yes No

Installation steps

Below are the steps to install Embold on Ubuntu.

Note: The version number (1.8.3.0) in installer file is mentioned as an example. You can use your applicable/newer version number.
  1. Download installer file from your Embold Account’s section > Releases tab > Installers. There will be one file with names similar to the following: ‘embold_ubuntu_1.8.3.0.run’.
  2. Make sure that installer file ‘embold_ubuntu_1.8.3.0.run’ has execution permission. To check the permissions of installer file, run the following command in terminal.
    ||
    If the file does not have the execution permission, use the following command to grant the permission.
    sudo chmod 755 embold_ubuntu_1.8.3.0.run
  3. Run installer using the command:
    sudo ./embold_ubuntu_1.8.3.0.run
    This will start the installation process.
  4. Accept the License Agreement to proceed. You can use tab and return/enter keys for navigation in any such prompt.
  5. For a fresh Embold installation, choose the option: “Install Embold and prerequisites“.
  6. Choose the Embold installation location.
  7. If you have multiple versions of Java installed on your computer/server, you can set JRE_HOME at the specified path.
  8. On the successful installation, a pop-up screen will be displayed. Embold will be accessible from the IP address mentioned in a pop-up.
  9. Activate Embold.
Yes No

Upgrade an older version

Before you upgrade Embold on Ubuntu, make sure no scans are in process and close all the browsers that are running Embold.

  1. Run the installer file. (refer installation steps).
  2. During installation, select “Reinstall / Upgrade Embold“.
  3. Select the Update option.
  4. Update is done.
Yes No

Install standalone corona

Below are the steps to install standalone corona on Ubuntu.

Note:
The version number (1.8.3.0) in installer file is mentioned as an example. You can use your applicable/newer version number.
  1. Download the installer file from your Embold Account’s section > Releases tab. There will be one file with a name similar to the following: ‘embold_ubuntu_1.8.3.0.run’.
  2. Make sure that installer file ‘embold_ubuntu_1.8.3.0.run’ has execution permission. To check the permissions of the installer file, run the following command in terminal.
    ||
    If the file does not have the execution permission, use the following command to grant the permission.
    sudo chmod 755 embold_ubuntu_1.8.3.0.run
  3. Run installer using the command.
    sudo ./embold_ubuntu_1.8.3.0.run
    This will start the installation process.
  4. Accept the License Agreement to proceed. You can use tab and return/enter keys for navigation.
  5. For a standalone Corona installation, choose option: ‘Install Corona’.
  6. Choose corona installation location.
  7. If you have multiple versions of Java installed on your computer/server, you can set JRE_HOME at the specified path.
  8. On the successful installation, logout and login from the system.
Yes No

Upgrade standalone Corona

Before you upgrade standalone corona on Ubuntu, make sure no scans are in process and close all the browsers that are running Embold.

  1. Run the installer. (refer installation steps).
  2. During installation, select “Reinstall / Update Corona”.
  3. Once upgraded logout and login from the system.
Yes No

Limitations

  • C# scans work on Ubuntu operating system only for .net core based repositories.
Yes No

Installation on Windows

Before you begin, please verify that you have a supported version of Windows here.

Yes No

Pre-installation checks

Following are the prerequisites for installing Embold on Windows:

  • Node.js version 10.21.0
  • .NET Framework 4.5
  • .NET Core 3.1
  • PowerShell version 5.1
  • Google chrome browser

For more information, refer specifications section.

Below are the pre-installation check steps:

.NET Version check:

  • Open PowerShell in admin mode and run below command:
    (Get-ItemProperty -Path 'HKLM:SoftwareMicrosoftNET Framework SetupNDPv4Full' -ErrorAction SilentlyContinue).Version -like '4.*'
  • If the above command is “True”, then the default framework is installed.
  • If the above command is “False”, then install .NET Framework 4.5 or a newer version.
Note:

  • .NET Framework 4.5 is the default version.

PowerShell version check:

  • Open PowerShell in admin mode and run below command to check the current version: $PSVersionTable.
  • If the version is not 5.1, install Windows Management Framework “Win7AndW2K8R2-KB3191566-x64.msu” placed under “..preInstallationsRequiredpowershell5.1 Win7AndW2K8R2-KB3191566-x64.zip”.
  • Ensure that PowerShell terminal is closed before installing.

Set PowerShell execution policy

  • After confirming PowerShell version to be 5.1, open PowerShell terminal as administrator and enter the command “Set-ExecutionPolicy RemoteSigned” and choose Yes in the flow.

Dependencies for C# language support:
If the user wants C# language support for Embold, follow the below steps:

  • Download preInstallationsRequired.SDK from your Embold Account’s section > Releases tab > windows section.
  • This package (preInstallationsRequired.SDK file) will have setup.
  • In addition to the list of pre-requisites, you can install more pre-requisites based on your requirements.

Note:

Note:

  • Ensure that the machine on which Embold is getting installed has no Node.js installed.
  • While installing .net framework, it may ask for user intervention. Choose all the default settings and complete the installation.
Yes No

Installation steps

Below are the steps to install Embold on Windows:

  1. Download the installer file from your Embold Account’s section > Releases tab > Installers. There will be file with name similar to the following: embold_windows_1.8.3.0.zip.
  2. Right-click the zip folder, click Properties > General tab.
  3. In the ‘Security‘ section, if the Security button is blocked, unblock it and then proceed with the unzipping of the file.
    Note:- If the security button is not blocked, you can directly proceed with the unzipping of the file.
  4. Unzip the embold_windows_1.8.3.0.zip file.
  5. Go to setup folder.
  6. Open command prompt in admin mode, change the directory (folder) using cd to the path (gammaWindowsInstallersetup) where setup.bat file is located and run the command:
    setup.bat
  7. This will install the pre-requisites for the gamma including required frameworks, tools, etc.
    The script will set all the required environment variables.
  8. On successful installation, Embold login page will be available at localhost:3000.
  9. Activate Embold.
Yes No

Upgrade an older version

Follow the above steps for upgrading Embold on Windows.

Yes No

Install standalone corona

Below are the steps to install standalone corona on Windows:

  1. Download installer file from your Embold Account’s section > Releases tab. There will be file : corona64_WindowsInstaller.zip .
  2. Right-click the zip folder, click Properties > General tab.
  3. In the ‘Security‘ section, if the Security button is blocked, unblock it and then proceed with the unzipping of the file.
    Note:- If the security button is not blocked, you can directly proceed with the unzipping of the file.
  4. Unzip the corona64_WindowsInstaller.zip file.
  5. Go to setup folder.
  6. Open command prompt in admin mode, change the directory (folder) using cd to the path (corona64_WindowsInstallersetup) where setupCorona64Bit.bat file is located and run the command:
    setupCorona64Bit.bat
  7. This will install the pre-requisites for the corona including required frameworks, tools, etc.
    The script will set all the required environment variables. The corona folder will be created under “c:ProgramDataGamma“.
  8. On successful installation, Embold login page will be available at localhost:3000.
  9. Activate Embold.
Yes No

Upgrade standalone corona

Follow the above steps for upgrading standalone corona on Windows.

Yes No

Installation on Redhat Enterprise Linux or CentOS

Before you begin, please verify that you have a supported version of Redhat Enterprise Linux (RHEL) or CentOS here.

Yes No

Pre-installation checks

  • For seamless installation and execution, Embold should be installed on a clean machine/VM.
  • Embold works with Node.js version 8.11.3. Ensure that the machine on which Embold is getting installed has no Node.js installed.
  • To check if the ‘yum’ process is running, run the following command:
    ps aux | grep yum
  • To install .NET 3.0 on RHEL, run the following commands:
    yum install rh-dotnet30 -y
    scl enable rh-dotnet30 bash
  • To install .NET 3.0 on CentOS, run the following commands:
    sudo rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm
    sudo yum install dotnet-sdk-3.0
  • For more details, refer to the specifications section.
Yes No

Installation steps

Below are the steps to install Embold on RHEL or CentOS.

Note: The version number (1.8.3.0) in installer file is mentioned as an example. You can use your applicable/newer version number.
  1. Download the installer file from your Embold Account’s section > Releases tab > Installers. There will be a file with a name similar to the following: ‘embold_centos_rhel_1.8.3.0.run’.
  2. Make sure that installer file ‘embold_centos_rhel_1.8.3.0.run’ has execution permission. To check the permissions of the installer file, run the following command in the terminal.
    ||
    If the file does not have the execution permission, use the following command to grant the permission.
    sudo chmod 755 embold_centos_rhel_1.8.3.0.run
  3. Run installer using the command:
    sudo ./embold_centos_rhel_1.8.3.0.run
    This will start the installation process.
  4. Accept the License Agreement to proceed. You can use tab and return/enter keys for navigation in any such prompt.
  5. For a fresh Embold installation, choose the option: “Install Embold and prerequisites“.
  6. Choose the Embold installation location.
  7. If you have multiple versions of Java installed on your computer/server, you can set JRE_HOME at the specified path.
  8. On the successful installation, a pop-up screen will be displayed. Embold will be accessible from the IP address mentioned in a pop-up.
  9. Activate Embold.
Yes No

Upgrade an older version

Before you upgrade Embold on Redhat Enterprise Linux or CentOS, make sure no scans are in process and close all the browsers that are running Embold.

  1. Run the installer file. (refer installation steps).
  2. During installation, select “Reinstall / Upgrade Embold“.
  3. Select Yes option if you want to reinstall Embold.
  4. Select the Update option.
  5. Update is done.
Yes No

Install standalone corona

Below are the steps to install standalone corona on RHEL or CentOS.

Note: The version number (1.8.3.0) in installer file is mentioned as an example. You can use your applicable/newer version number.
  1. Download installer file from your Embold Account’s section > Releases tab. There will be file with name similar to the following: ‘embold_centos_rhel_1.8.3.0.run’.
  2. Make sure that installer file ‘embold_centos_rhel_1.8.3.0.run’ has execution permission. To check the permissions of the installer file, run the following command in the terminal.
    ||
    If the file does not have the execution permission, use the following command to grant the permission.
    sudo chmod 755 embold_centos_rhel_1.8.3.0.run
  3. Run the installer using the command.
    sudo ./embold_centos_rhel_1.8.3.0.run
    This will start the installation process.
  4. Accept the License Agreement to proceed. You can use tab and return/enter keys for navigation.
  5. For a standalone Corona installation, choose option: ‘Install Corona’.
  6. Choose corona installation location.
  7. If you have multiple versions of Java installed on your computer/server, you can set JRE_HOME at the specified path.
  8. On the successful installation, logout and login from the system.
Yes No

Upgrade standalone corona

Before you upgrade standalone corona on Redhat Enterprise Linux or CentOS, make sure no scans are in process and close all the browsers that are running Embold.

  1. Run the installer. (refer installation steps).
  2. During installation, select “Reinstall / Update Corona”.
  3. Once upgraded logout and login from the system.
Yes No

Limitations

  • C# scans don’t work on Redhat Enterprise Linux/CentOS operating system.
Yes No

Installation with docker

Requirements

Operating System Requirements

For Docker based installation, any Linux distribution with Docker support is required. Further information on compatibility of Docker CE and EE can be found on the Docker help center: https://docs.docker.com/install/overview/.

Docker on Windows and Mac is currently not supported by Embold. 

Note: Docker based installation specifically needs CentOS 7.

Docker Hub Account Requirements

  • Embold is currently available in our private docker repository at https://hub.docker.com
  • In order to get access to the Embold container image, follow the steps below:
    • Send us your Docker ID via email.
    • We will provide access to the Embold image for the Docker ID you provide and send you a confirmation via email.
  • Proceed to install the Embold Docker Image (Refer section “Installing Embold Docker Image”) after you receive the confirmation.

Hardware Requirements

Computing

  • We recommend a minimum of 2 dedicated cores
  • For projects > 1 Mio. Lines of code 4 cores are recommended
  • For projects > 3 Mio. Lines of code 8 cores are recommended.


Memory

  • Minimum 8 GB RAM (dedicated)
  • For projects > 1 Mio. Lines of code 16 GB RAM are recommended 
  • For projects > 3 Mio. Lines of code 32 GB RAM are recommended.

Storage

  • Minimum of 100 GB storage 
  • Should be expandable to support a growing analysis history
  • The table below gives an indication on the growing storage requirements:
Lines of CodeStorage size of 1 full snapshot
100.000About 70-90MB
1.000.000About 700MB – 1.2GB
2.000.000About 1.2 – 2GB

Table 1:Storage estimations

Networking Requirements

During Installation

  • The instance needs to be accessible through SSH. 
  • Connectivity to the docker hub must be possible.

After Installation

  • One port needs to be exposed to access Embold via HTTP on the browser (by default port 3000)
  • For remote scans where scans run on a build machine and results are published to the Embold server, port 5432 also needs to be exposed
  • Connectivity to all external systems that should be integrated is required on the relevant ports-
    • This includes connectivity to the repositories (i.e. git, GitHub, GitLab, TFS, SVN) on the required ports (i.e. HTTPS, SSH)
    • If CI integration is required, connectivity between Embold on the CI system is required
    • If task management is required, connectivity between Embold and the task management system needs to be there (i.e. for Jira, Teamforge) 

Environment Variables

  • Requires the following environment flag: ACCEPT_EULA=Y

Yes No

Download docker image from Embold release

Download the docker-compose image and docker image from your Embold Account’s section > Releases tab > Docker > compose. There will be one .yml file with a name similar to the following: ‘docker-compose.yml’. and few .gz files with the pattern similar to the following: embold_X.X.X.X.tar.gz from which Docker images can be pulled.

Yes No

Installing Docker engine

Docker engine needs to be installed on the host prior to installing the Embold Docker image.

Note: Install only the stable version, not the nightly builds.

Depending on your OS, refer the following steps to setup Docker Engine.

A. Docker Engine on CentOS

Follow the steps listed at this link.

B. Docker Engine on Ubuntu

Follow the steps listed at this link.

Yes No

Steps to run Embold with docker-compose

Make sure you have docker id and necessary permission to Embold Technologies docker repository.

To create a docker hub account follow the below steps:

  1. Visit https://hub.docker.com/ to signup up to the Docker Hub.
  2. Enter the Docker Id, email address and password.
  3. Click Sign up.
  4. A verification link is sent to your registered email address.
  5. After verifying your email address, you can log in to the Docker Hub.
  6. To obtain the access for Embold repositories contact our support team at support@embold.io

Steps to run docker compose:

  1. Contact our support team at support@embold.io to obtain the docker-compose.yml file.
  2. Copy docker-compose.yml to local drive for e.g. /home/{user}/docker
  3. Run the below command:
    docker login
    Note: Login with user ID and password.
    mkdir -p /home/${USER}/docker/data -p /home/${USER}/docker/psql_data -p /home/${USER}/docker/logs
  4. Run below command:
    docker-compose up -d
    It will pull all the images from docker hub and then provide access to Embold service.
  5. You can access Embold at http://localhost:3000/.
  6. Use these steps to activate Embold.
Note:
After running docker-compose up -d command it approximately takes a minute to access Embold through browser.
Yes No

Installing Embold Docker image

Prerequisite:  

Your docker ID should be enabled for our private repository to download the Embold image. 

Note:

The tag name {VERSION} is mentioned as an example in below commands. You can use your latest preferred tag from docker. For example: tag name can be 1.7.0.0

Refer section Docker Hub Account Requirements before proceeding with Installation of Embold Docker image.

Login to Docker Hub from CLI

Login to docker using docker CLI using your docker ID and password when prompted:

$ docker login

Download and install the Embold Docker Image

docker run -m 8GB -d -p 3000:3000 -p 5432:5432 --name EMBOLD -e gamma_ui_public_host=http://localhost:3000 -e EMB_USE_NATIVE_PYPARSER=TRUE -e RISK_XMX=-Xmx1024m -e ACCEPT_EULA=Y -e ANALYSER_XMX=-Xmx3072m -v gamma_data:/opt/gamma_data -v gamma_psql_data:/var/lib/postgresql -v /home/${USER}/docker/logs:/opt/gamma/logs embold/gamma:${VERSION}

Note:If you didn’t add the current user to the docker group (sudo usermod -aG docker $(whoami)), you may need to run the above commands with sudo.

The above steps will download and install the Embold Docker Image.

You can then access Embold at: http://localhost:3000

Note:After executing the “docker run” command it may take upto 2 minutes for the Embold server to be up and running on port 3000.

Note:The memory settings (-m option, RISK_XMX, ANALYSER_XMX may need to be increased when analysing code bases larger than 1 million LOC)

Activate Embold

Once the above steps are performed, head to https://docs.embold.io/managing-license/#activating-gamma-onpremise to activate Embold.

Running a scan

Once Gamma is successfully activated, head to https://docs.embold.io/scans-snapshots/#steps-to-scan-a-repository to learn how to run your first scan.

Yes No

Installing Embold Docker and Corona (Embold Analyser) Docker for remote scan

This section provides general steps on how to run a remote scan (i.e. scan happens on a build machine, e.g. for C/C++ and results are pushed to the Embold server running as a Docker container 

Pre-requisites: You have set up the Embold Docker Server (Refer section “Installing Embold Docker Image”)

Note that this is an example setup which shows how the Embold Analyser Docker can be used to run a scan together with your build, assuming your build script is also runnable inside the docker container. Your actual build setup may vary (e.g. you may be running the build directly on a host machine, in which case you need to natively install the Embold Analyser component instead of using the docker image)

Download, install and run the Standalone Corona Docker Image

The following steps will download and install the Corona Docker image on remote machine from where remote scan will be initiated (e.g. the build machine)

$ docker run -it -e ANALYSIS_MODE=remote embold/corona:${VERSION} sh

Script which triggers Embold scan. The script can also be a custom script that internally builds the code, runs the unit test and calls Embold analysis.

Example:

$ docker run -it -e ANALYSIS_MODE=remote embold/corona:${VERSION} sh gamma-scan.sh
Yes No

Embold behind proxy

If Embold is located behind a proxy, additional information should be provided in the configuration file or docker command.

Yes No

Embold through docker

Use -e to pass environment variable or --env-file to provide file of environment variables.
e.g. with -e option

docker run -m 8GB -d -p 3000:3000 -p 5432:5432 --name EMBOLD -e ACCEPT_EULA=Y -e EMB_USE_NATIVE_PYPARSER=TRUE -e RISK_XMX=-Xmx1024m -e ANALYSER_XMX=-Xmx3072m -e no_proxy=localhost,127.0.0.0/8,::1 -e http_proxy=http://PROXY_IP:PROXY_PORT -e https_proxy=http://PROXY_IP:PROXY_PORT -e CATALINA_OPTS="-Dhttps.proxyHost=PROXY_IP -Dhttps.proxyPort=PROXY_PORT -Dhttp.proxyHost=PROXY_IP -Dhttp.proxyPort=PROXY_PORT -Dhttp.NoproxyHost='localhost|127.*|::1|192.168.*' -DGAMMA_ROOT=/opt/gamma -Xmx1024m -Djava.awt.headless=true -Djava.library.path=/usr/lib/x86_64-linux-gnu/jni/:/usr/lib64/" -v gamma_data:/opt/gamma_data -v gamma_psql_data:/var/lib/postgresql -v /home/${USER}/docker/logs:/opt/gamma/logs embold/gamma:${VERSION}

With --env-file option,
Use --env-file=env.list to read a file of environment variables.

env.list file looks like:

ACCEPT_EULA=Y
RISK_XMX=-Xmx1024m
ANALYSER_XMX=-Xmx3072m
http_proxy=http://PROXY_IP:PROXY_PORT
https_proxy=http://PROXY_IP:PROXY_PORT
no_proxy=localhost,127.0.0.0/8,::1
CATALINA_OPTS=-Dhttps.proxyHost=PROXY_IP -Dhttps.proxyPort=PROXY_PORT -Dhttp.proxyHost=PROXY_IP -Dhttp.proxyPort=PROXY_PORT -Dhttp.NoproxyHost='localhost|127.*|::1|192.168.*' -DGAMMA_ROOT=/opt/gamma -Xmx1024m -Djava.awt.headless=true -Djava.library.path=/usr/lib/x86_64-linux-gnu/jni/:/usr/lib64/
Note: Use your proxy host and port by replacing text “PROXY_IP” and “PROXY_PORT” respectively.
Yes No

Embold through installer

Modify /etc/default/gamma

1. Change CATALINA_OPTS environment variable with given settings:

export CATALINA_OPTS="-Dhttps.proxyHost=PROXY_IP -Dhttps.proxyPort=PROXY_PORT -Dhttp.proxyHost=PROXY_IP -Dhttp.proxyPort=PROXY_PORT -DGAMMA_ROOT=/opt/gamma -Xmx1024m -Djava.awt.headless=true -Djava.library.path=/usr/lib/x86_64-linux-gnu/jni/:/usr/lib64/"

2. Also add new environment variables as below:

export https_proxy=http://PROXY_IP:PROXY_PORT
export http_proxy=http://PROXY_IP:PROXY_PORT
export no_proxy='127.0.0.1,localhost'
Note: Use your proxy host and port by replacing text “PROXY_IP” and “PROXY_PORT” respectively.
Yes No

Backup & Restore

This guide will help you to backup your Embold data and restoring it. With this process, you can backup your source code, scans with all its pre-requisites.

Yes No

Prerequisites for database backup

  • The Embold version on the source and destination machines should be the same.
  • Stop Embold service on the destination machine.
  • You must have administrative privileges.
  • The script works with default database names as corona and gamma.
  • Share/mount the directory which shall be accessible to source machine if the backup/restore is been done on the remote machine.
  • Create a backup directory beforehand and provide write permissions where the backup is to be saved.
  • You must be aware of the Embold installation directory path for backup/restore on the same platforms.
  • In the case of Linux platform, to restore Embold, remove the password authentication from the remote destination.
Yes No

Backup & restore on Windows

This will include the information on database backup and restoration of the Windows operating system.

Yes No

Database backup

A. Database backup on windows

The databases from the source Embold machine is backed up using the following steps:

  1. Get the batch file at gamma_uidbscriptsscriptsbackup_restore.bat.
  2. Execute the file. A command prompt will be displayed. Follow the inquiries to backup the database.

B. Files backup on windows

The source files from the source Embold machine are backed up using the following steps:

  1. Get the batch file at gamma_uidbscriptsscriptsbackup_restore.bat.
  2. Execute the file. The command prompt will be displayed. Follow the inquiries to back up the source and logs.
  3. To back up the logs, provide the destination directory as shown in the below screens.
Yes No

Database restoration

A. Database restoration on windows

The databases from the source machine is restored using the following steps:

  1. Get the batch file at gamma_uidbscriptsscriptsbackup_restore.bat.
  2. Execute the file. The command prompt will be displayed. Follow the inquiries to restore the database.

B. Files restoration on windows

The source files from the source machine are restored using the following steps:

  1. Get the batch file at gamma_uidbscriptsscriptsbackuprestore.bat.
  2. Execute the file. The command prompt will be displayed. Follow the inquiries to back up the source and logs.
  3. To restore the logs provide the destination directory as shown in the below screen.
Yes No

Backup & restore on Ubuntu/RHEL/CentOS

This section gives information on database backup and restoration of Ubuntu/RHEL/CentOS

Yes No

Database backup

A. Database backup on Linux/RHEL/CentOS

The databases from the source Embold machine is backed up using the following steps:

  1. Get the shell file at /gamma_ui/dbscripts/scripts/backup_restore.sh.
  2. Execute the shell script with Postgres password.

For Example:
./backup_restore.sh
The command prompt will be displayed. Follow the inquiries to backup the database.

Note: The inputs to be provided are case sensitive.

B. Files backup on Linux/RHEL/CentOS

The source files from the source Embold machine are backed up using the following steps:

  1. Get the shell file at /gamma_ui/dbscripts/scripts/backup_restore.sh.
  2. Execute the file. The command prompt will be displayed. Follow the inquiries to back up the source and logs.
    Note:
    The inputs to be provided are case sensitive.

  3. To back up the logs, provide the destination directory as shown in the below screens.
Yes No

Database restoration

This section provides information for database restoration and file restoration.

A. Database restoration on Ubuntu/RHEL/CentOS

The databases from the source Embold machine is restored using the following steps:

  1. Get the shell file at /gamma_ui/dbscripts/scripts/backup_restore.sh
  2. Execute the file. The command prompt will be displayed. Follow the inquiries to restore the database.
Note: The inputs to be provided are case sensitive.

B. Files restoration on Ubuntu/RHEL/CentOS

The source files from the source machine are restored using the following steps:

  1. Get the shell file at /gamma_ui/dbscripts/scripts/backup_restore.sh
  2. Execute the file. The command prompt will be displayed. Follow the inquiries to back up the source and logs.
Note: The inputs to be provided are case sensitive.

For gamma_data and gamma/logs folders change the owner to Embold at the destination machine. Give 755 permission to gamma_data folder and gamma/logs folder.

To restore the logs provide the destination directory as shown in the below screens.

Yes No

Post Installation Server Configuration

This guide will allow you to do all the following steps after completing installations on all servers/operating systems.

Yes No

Postgres Configuration

Accessing database from different machines

  • Go to Postgres installation directory-> 9.6 -> data.
  • Postgres installation is usually located at the following location:
    • On Linux: /var/lib/pgsql
    • On Windows: C:/Program Files/PostgreSQL

Steps

  • Edit the postgresql.conf as shown below:
  • Edit pg_hba.conf in the IPv4 section as shown below:
  • To allow any user from any host to connect to the database “postgres”.
  • To allow any user from any host with IP address 192.168.2.x to connect to database “postgres”.

Commonly used authentication methods

  1. Trust: Allow the connection unconditionally. This method allows anyone that can connect to the PostgreSQL database server to login as any PostgreSQL user they wish, without the need for a password or any other authentication.
  2. Reject: Reject the connection unconditionally. This is useful for “filtering out” certain hosts from a group, for example, a reject line could block a specific host from connecting, while a later line allows the remaining hosts in a specific network to connect.
  3. md5: Require the client to supply an MD5-encrypted password for authentication.
  4. Password: Require the client to supply an unencrypted password for authentication. Since the password is sent in clear text over the network, this should not be used on untrusted networks.
  5. Peer: Obtain the client’s operating system username from the operating system and check if it matches the requested database username. This is only available for local connections. Refer section 19.3.7 for details.
  6. Cert: Authenticate using SSL client certificates. Refer section 19.3.10 for details. For more details refer to https://www.postgresql.org/docs/9.6/static/auth-pg-hba-conf.html.
Yes No

Configuring Server Port

Change the default port

By default, the Embold application is running on port 3000. To change this, you need to follow the steps listed below:

  • Go to the directory where the Embold is installed (based on the option selected during installation).
  • Edit gamma-config.json which can be found at the following location: /gamma_ui/config/gamma-config.json
    NOTE: For docker containers please use the “-e” notation to change the gamma-config.json file while deployment as environmental variables.
  • Find the “gamma_port” and change the value to the one you prefer.
    Example:
From To
“gamma_port”:3000“gamma_port”: <CUSTOMPORT>
  • Restart the Embold service for Linux environment.
    sudo service gamma restart
  • Restart the Embold service for windows environment.
    net stop Gamma_UI_Service
    net start Gamma_UI_Service

Enable the SSL port

To enable SSL port for Embold application, you need to follow the steps listed below:

  1. Go to the directory where gamma is installed (based on the option selected during installation).
  2. Copy the certificate and key to the following location:/ssl
  3. Edit gamma-config.json which can be found at the following location:/gamma_ui/config/gamma-config.json
  4. Find the “ssl” and change the value to the one you prefer, for instance-
FromTo
“ssl”:
{
“key”: “$GAMMA_ROOT/ssl/certificate.key”,
“cert”: “$GAMMA_ROOT/ssl/certificate.cert”,
“port”: 5443
}
“ssl”:
{
“key”: “$GAMMA_ROOT/ssl/certificate.key”,
“cert”: “$GAMMA_ROOT/ssl/certificate.cert”,
“port”: <CUSTOMPORT>
}
Yes No

C++ Configuration

For setting up an environment for C++, you can perform configuration steps for installing files, databases and so on.

Yes No

C++ Strict Mode

In strict mode, CXXParser uses a compilation database to parse files. Compilation database contains actual compile commands and options used to compile source files in a project which helps CXXParser in accurate parsing. Compilation database can be generated using build tools such as cmake, make, waf, scons, etc.

Yes No

Embold Trace

Introduction

Embold uses Compilation Database (CDB) to scan C/C++ repository in strict mode. Embold provides a tool ‘embold-trace’ to generate CDB from build process. Embold-trace tool facilitates users to configure which compilers to intercept during build. It then intercepts build process and generates CDB based on configured compilers.

Supported Platforms

Before you begin, please verify that you have a supported version of operating systems here.

Prerequisites

  • Linux
    strace: A tool for debugging and troubleshooting programs in Unix-like operating systems such as Linux.
    Read more about strace here.
  • Installation of strace
    For Ubuntu→ $ sudo apt-get install strace
    For CentOS/Red Hat→ $ sudo yum install strace

How to use

  • To run the embold-trace, run the below command:
    $ embold-trace [embold-trace-options] {your build command} [build-options]
  • Use `--help` to know more about the embold-trace options.

MSBuild on Windows

Embold-trace has two modes of operation for tracing MSBuild projects:

  1. Using .tlog files→Uses MSBuild generated tracker log files of the form CL.command.1.tlog to generate CDB
    This mode can be enabled using -t option of embold-trace
    $ embold-trace -t msbuild project.sln
  2. Trace files → Uses intermediate trace files to generate CDB.
    This is the default mode of operation

Output Directory

Embold-trace supports generating CDB in custom directory with option -o
$ embold-trace -o {custom/directory} msbuild project.sln

Configure embold-trace

Embold-trace uses json configuration files to configure compilers to intercept. There are two types of configuration files.

1. Top-level configuration file:

This file list down the compilers names to intercept and corresponding translation file name (excluding extension). Embold-trace provides compiler configuration for all the standard compilers.
The default name is ’embold-trace-default.json’

  • Source Extensions

The default configuration file lists supported extensions for C/C++ source files. Users should add the extension which needs to be supported to this configuration file. (if not already present)

  • Translation file:
    It contains the corresponding compiler options to specify include directory, include file and define macro.
    Key-Value description in translation json as follows :
KeyValueDescription Example
includeDirPrefix Option used to specify include directory-I (GNU Family)-I (GNU Family)
defineMacroPrefixOption used to define macro-D (GNU Family)-D (GNU Family)
includeFilePrefix Option used to include single file during compilation-include (GNU Family)-include (GNU Family)
sourceFilePrefix Prefix used to specify source files in compile commandPrefix used to specify source files in compile command. Green Hills Compiler uses flag --source to specify source file in compile command.
Example:
$ ease850 --source=abc.cpp
--source (GH Compiler)
optionFilePrefix Prefix used to specify build system options file. Options file contains compiler options for include directory, define macro etc.Instead of directly specifying options like -I, -D in compile commands, some compilers or build systems uses a special file called option file which contains compiler flags. This file is then provided in compile command using a prefix. The value of this key is that prefix.
Example:
$ cctc --option-file=option-file.txt abc.cpp
--option-file (Tasking Tri-core)
optionFilePatternA pattern to specify build system options file. Each build system or compiler has different name format for options file. So, a regex should be specified as value.Option files can also be specified using pattern instead of prefix. Example:
CMake build system generates response files whose names are like includes_CXX.rsp for C++ compilation and includes_C.rsp for C compilation. These files contain includes and define options required for compilation. And these response files are supplied usually using ‘@’ character at the start but not necessarily.
Example:
"command": "g++ @CMakeFiles/TestProject/includes_C.rsp -o CMakeFiles\ TestProject\test.o -c C:\TestProject\test.c"
A regex which match these file names should be provided as value of optionFilePattern in translation file. Then, if embold-trace finds such file pattern in compile command, then it replace the content of the option file in compile command for Embold to parse correctly.
.*includes_CXX.rsp (CMake Build)

Where to find

By default, all the provided configuration files (top-level and translation) are present in the directory where embold-trace binary is present. Any new translation file should also be added to the same directory.
However, you can keep all the configuration files in a separate directory. In this case, the top-level configuration file path should be given as input to embold-trace while invocation using option “-c
$ embold-trace -c [build-options]

2. Adding Non-Standard Compiler Name

If you have a standard compiler from the above list but a non-standard name, you must edit the default configuration file.

Example:
If a GCC compiler 4.9 is installed and compiler name is ‘gcc-4.9’
Then, add an entry to top-level configuration file.

Adding Unsupported Compiler

If your compiler is name is not found in top-level configuration file and it is not a standard compiler like GCC or Clang, then that compiler is non supported by embold-trace by default.

Supporting a non-supported compiler involves two steps:

  1. Add an entry in the top-level configuration file
  2. Add corresponding translation file

3. Add an entry in the top-level configuration file

An entry must be added to top-level configuration file for this compiler name and corresponding translation file name (excluding extension).

Example:
Suppose your new compiler name is ‘cctc’ which takes following options
“-inc” – to include directory
“-def” – to defining macro
“-ifile” – to include a file during compilation

Where, tasking_tricore is a JSON translation file named tasking_tricore .json in the same directory as top-level configuration file.

  • tasking_tricore json file will look like below:

Suppose the new compiler takes includeFile of the form @test/.includeDirs_c23dewff34.txt Hence, the regex provided is “.*.includesDirs_.*.txt”

Supported Compilers

CompilerCompiler nameTranslation config name
GCCgcc, g++, cc, c++, clanggnu.json
Clangclang, clang++gnu.json
Green Hills (GH)ease850
gh.json
Tasking Tri-corecctctasking_tricore.json
MSBuildcctctasking_tricore.json

Locate Compilation Database

After the build is finished successfully, the Compilation Database is generated in the current working directory where the build is run. A file named compile_command.json is the CDB. If the embold-trace successfully generates CDB, a log message will be printed displaying the number of compile entries in CDB.

Locate Configuration Files

By default, all the provided configuration files (top-level and translation) are present in the directory where the embold-trace binary is present. Any new translation file should also be added to the same directory.

However, you can keep all the configuration files in a separate directory. In this case, the top-level configuration file path should be given as input to embold-trace while invocation using option c”

$ embold-trace -c {top/level/config/file/path} {your build command} [build-options]

Configuring Unknown Compiler

Configuring embold-trace for an unknown compiler is an iterative process.

Steps to configure

  1. Run build using embold-trace (Check How to use section)
  2. After the build, embold-trace will print number of non-configured executable and log all the entries in a text file embold-trace-unknown-exe.txt. This file will be createdin current working directory. Not all the executable are compilers so user need to identify which ones are the compilers.
  3. If you found your compiler in non-configured list then go to next step else configuration is done no further action is needed
  4. Create a translation file for your compiler
  5. Add compiler name and translation file name entry to embold-trace-default.json
  6. Run embold-trace with trace file as input (No need to run build again)
  7. Go to step 2

Example: Configuring g++

Assumption: No compilers are configured.
Empty embold-trace-default.json

Our sample repository is cppcheck. We will build the repository using embold-trace and configure compiler g++ and create compilation database.

Step 1: Build repository using embold-trace

Step 2: Build output

As can be seen from above image, embold-trace intermediate trace file path is C:\Users\Hemant\AppData\Local\Temp\embold-trace-log_1590487077. Non-configured executable is 4 and they ate written to C:\Workspace\repos\cppcheck\build_make\embold-trace-unknown-exe.txt. Also, no commands have been intercepted as no compilers are configured.

Step 3: Inspect the contents of C:\Workspace\repos\cppcheck\build_make\embold-trace-unknown-exe.txt

There are 4 entries in unknown executable list. Not all executable are compilers only g++ is. So we will go to next step and configure g++.

Step 4: Create a translation file gnu.json (filename can be anything) for g++ compilers
For all GNU family compilers like gcc, g++
includeDirPrefix → -I
defineMacroPrefix → -D
includeFilePrefix → -include

So we will create gnu.json like this

Step 5: Add compiler name (g++) and translation file name (gnu) entry to embold-trace-default.json

Step 6: Rerun embold-trace with a new configuration and trace file as input

This time the compilation database is generated and non-configured executable count is reduced by 1 as we have configured g++ compiler. Also we didn’t run the build again. Contents of C:\Workspace\repos\cppcheck\build_make\embold-trace-unknown-exe.txt

There is no entry for g++. So g++ is configured correctly. Other executable are not required to be configured. So embold-trace configuration is complete and we got valid compilation database.

Step 7: No need to go to step 2

Likewise, we can configure any possible compiler iteratively

Non-configured Executable file format

Its a text file which provides hints to user regarding probable compilers in build. It contains unique executable path per line. Each line is further divided into 3 parts separated by semicolon. Meaning of each part is explained in below image.

As you can see, the first thing user need to check is whether the executable is compiler or not is by inspecting the second part, configure all* executable with “C“ first as they probably are compilers. And executable with most occurrences and “N“ might be custom compiler but they are can only be identified by build engineers.

*Some compiler executable internally also invokes another executable in that case we may ignore it like cc1plus. g++ internally invokes cc1plus.

Custom Source Extensions

By default, embold-trace supports following C/C++ extensions
“cc”,”c++”,”c”,”cpp”,”cxx”,”cplusplus”
However, user can add custom extensions like this

Here ‘850’ & ‘pc’ are custom C extensions and 'pcpp' is custom C++ extension

Yes No

Running analysis in strict mode

Set up your remote Embold instance. This is where your analysis results will be published. Follow the steps to set up remote analysis here.

  1. On your build machine, navigate to the base directory of your source folder. Generate the compilation database as explained here. You should be able to see a compile_commands.json file in your base directory.
  2. Install corona on your build machine as explained here for Ubuntu, Windows and RedHat Enterprise Linux/CentOS.
  3. Download repository configuration JSON from Embold UI (Projects > Repositories > Download repository configuration)
  4. Open and edit the gammascan_typical.json file. Provide the URL of your remote machine where the Embold is running and also, set your Embold username and password.
  5. Login to Embold. Create a project. Link the repository you want to scan. On your remote Embold instance navigate to the repository you want to scan.
  6. Go to “More information“. Copy the repository UID.
  7. In the repositories section, under the repository, set the UID value that is the copied value. Set the project name.
  8. In the sources section, set the value of baseDir as the base directory path of your source folder on your build machine. You can also give exclusions.
    e.g. If you want to exclude folders named “build” and “test”, simply give “.*build.*” , “.*test.*” in the exclusions section.
  9. Set the dataDir to any desired location on your build machine.
  10. If you wish to create a separate build folder for running trace-utility (intercept-build), you should use the –cdb additional option while running the scan.
    The compile_commands.json will be created inside your build directory and not in the base directory of your source folder. Since, the scanner looks for the compile_commands.json in the base directory by default, use the  –cdb option to specify the directory where your compile_commands.json is located.
  11. In “settings” section, under “additionalOptions” set the directory where compilation database resides.
    Example: –cdb=
  12. Go to the bin directory inside the scanboxwrapper.
    e.g. cd gamma/corona/scanboxwrapper/bin.
    Run below command:
    /gammascanner -c
    /home/user/gamma/corona/scanboxwrapper/examples/gammascan_typical.json
  13. After the analysis is complete, you should see the analysis results for your repository on your Embold instance. On your build machine, the last two log messages indicate that the remote analysis was successful.
  14. On your remote Embold instance, you will be able to see published results.
Yes No

C++ Fuzzy Mode

If any included file is not found in the source directory, cxxparser will throw a warning message which contains the location of missing include. Accuracy of the parser can be improved by providing the path to the directories which contain the missing files.

Yes No

Improving accuracy in fuzzy mode

  • Missing Includes
  1. Click on Projects option on the left side navigation pane.
  2. Inside your project, click on “” on the top right corner of your repository for viewing options.
  3. Click on Scan Configuration.
  4. Look for Additional Includes Directories label and add the directories in the text box provided.
  5. Click Save.
A comma-separated list of directories should be added in Scan Configuration pop-up window
  • Define macros

Macros can be defined with GCC like option format.
Example:
To define macro MY_MACRO -> –clang=”-DMY_MACRO=
Any option to compiler can be given with –clang=”

Yes No

Additional parser options

  • Exclusion filters

We can exclude particular source files by providing regular expression. Regular Expression Format: JavaScript

Examples:

  1. To filter out files containing “test” keyword -> “.*test.*”
  2. To filter out everything but one file -> “^(?!.*parse-this-file-only.cpp*$).*”
  3. Use escape character to match special characters like +, . -> “.*test.c++*”
A semi-colon list of regular expressions should be added in Scan Configuration pop-up window
  • Parsing invalid code

By default, invalid code parsing is enabled but, it can be disabled using the following option.
–parse-invalid-code=OFF

Note:
There is limited support for invalid code parsing, and it is prone to parser crash (very rare), so if for some codebase parser is crashing, please disable the invalid code parsing.
  • Recursive include header search

By default, parser searches for any header file recursively in all the sub-directories of the source folder. This can lead to incorrect results if there are multiple header files with the same name but in different folders.
To disable searching in all sub-directories use following option
—include-all=OFF

A semi-colon list of regular expressions should be added in Scan Configuration pop-up window
  • Upload additional include folder zip.
Upload includes zip folder in Scan Configuration pop-up window
Yes No

Integration with CI/CD tools

Embold is integrated into the Software Development Life Cycle (SDLC), enabling the early detection of code issues, design issues, etc. Embold scan can be automatically triggered after the source is built. Integration of Embold with CI/CD tools requires sign-in with the Embold Server deployed within the organization.

Yes No

Embold setup without CI Integration (Default setup)

Introduction

Default Embold can be set up without integration with any CI system but, can be connected to a version control system such as Git.

Components

In this case, Embold Server Host includes 2 components:

  1. Embold Server Web App and Services:
    This hosts the Embold Web App which is accessible from the browser and backend web services (used internally by Embold).
  2. Embold Analyser (code-name Corona):
    This is the analyser component that scans the code, runs the actual code analysis and publishes results to the Postgres DB. In this mode, Corona will access code pulled from the Git/SVN/TFS repo on the Embold Server Host, or uploaded as Zip file from the Web UI, and run the scan on the Embold Server host.
Yes No

Remote Analysis

Remote analysis is an alternate way of analysis with no UI intervention. Here, Embold analysis is done remotely, and results are published on Embold UI.

Yes No

Prerequisites

  • Install corona on your build machine (Ubuntu, Windows, RHEL/CentOS) as explained.
  • In order to give read, write and execute permission to a user running remote scan:
    • create a group ‘gamma’ with the help of following command: sudo groupadd gamma
    • Change the group of the gamma installation directory to ‘gamma’ sudo chgrp gamma -R /opt/gamma
    • Add permission to gamma installation directory: sudo chmod 774 -R /opt/gamma
    • Add a user, running remote scan, to ‘gamma’ group with following command: sudo usermod -a -G gamma user
    • Restart Embold sudo service gamma restart
  • Setup Embold Remote instance if not already available. This is where your analysis results will be published.

Note: Configuring Postgres SQL on your remote Embold instance is not applicable for Embold running on Docker.

  • Postgre SQL on your remote Embold instance should be configured using the following steps:
  • Go to Postgres installation directory -> 9.6 -> data -> open pg_hba.conf -> Add incoming connection of analysis machine with the trust method  (see the following sample screenshot).
  • Go to Postgres installation directory -> 9.6 -> data -> open postgresql.conf, Update the following line with the IP Address of analysis machine or ‘*’ for giving access to all machines, (Remove starting ‘#’ if present at this line).
  • Restart postgres service using following command- sudo service postgres restart
  • Reboot your system (this step is required for your CORONA_HOME and CORONA_LOG environment variables to be set). Echo $CORONA_HOME and $CORONA_LOG after rebooting and check if they have been set. If not, then refer to troubleshooting tips in the installing standalone corona section.
  • Create a subsystem on Embold UI to be analyzed.
Yes No

Steps to run remote analysis

  1. Login to Embold. Create a project. Link the repository you want to scan.
  2. On your remote Embold instance navigate to the repository you want to scan.
  3. Download configuration json from Embold UI, it resides in Project configuration.
  4. Open the JSON file. In the gammaAccess section, provide the URL of your remote machine where the Embold is running. Set your Embold username and password.
  5. Set the dataDir to any desired location on your build machine.
  6. Give write access to dataDir folder for particular user who will be running gammascanner bat/sh file.
  7. In the sources section, set the value of baseDir as the base directory path of your source folder on your build machine. You can also give exclusions (e.g. If you want to exclude folders named “build” and “test”, simply give “.*build.*” , “.*test.*” in the exclusions section).
  8. Add the list of modules to be run (e.g. pmd,cppcheck,gamma_cxx).
  9. Go to bin directory inside scanboxwrapper (e.g. cd gamma/corona/scanboxwrapper/bin ) then run:
    /gammascanner -c /home/user/gamma/corona/scanboxwrapper/config/examples/gammascan_typical.json
  10. After the analysis is complete, you will be able to see the analysis results for your repository on your gamma instance.
  11. On your remote Embold instance, you will be able to see published results.
Yes No

Configuration for https enabled Embold

  • Import the same set of certificates used for Embold in default jre keystore on standalone Corona machine.
  • Default jre path: Javajre1.8.0_171libsecurity.
  • Below is the command:
    “keytool -import -trustcacerts -alias gamma -file “ ”-keystore cacerts”
Yes No

GitLab Integration

After integrating Embold with GitLab, users can scan their code after every GitLab build pass. Users can also configure Embold modules (tools) using gamma_scansettings.json at the GitLab level.

Yes No

CI Integration pipeline

In this mode, Embold integrates with the CI system (Gitlab in this case) to run scans as part of the pipeline run. The following diagram shows the Embold setup with Gitlab:

In this case, the “Corona” component of Embold is deployed additionally on the Gitlab Runner host. The Corona component analyses code which was pulled on the Gitlab Runner during pipeline runs. If running C/C++ pipelines, it is recommended to run Corona in “strict” mode. This involves intercepting the build process to extract compiler command invocations, generating a compilation database, and using that database for the analysis. This approach results in maximum accuracy for C/C++ systems.

Note:
Optional but recommended for C/C++ – Modify the build script – Prefix the call to “make” with “intercept-build” python script which is shipped along with gamma package (refer C++ Strict mode section for more details)

Yes No

Prerequisites

  • Remote Analysis should work from GitLab machine (where GitLab runner is running) to Embold machine. (Refer Remote Analysis article).
Yes No

Installations Steps

  1. Install standalone Corona for  UbuntuWindows or RedHat Enterprise Linux/CentOS at your desired location (e.g. /opt/gamma ). It will be your GAMMA_ROOT folder.
  2. Recursively change the owner of the GAMMA_ROOT folder (e.g. /opt/gamma folder) to GitLab user (e.g. sudo chown -R gitlab-runner /opt/gamma)
  3. PostgreSQL on your remote Embold instance should be configured.
  4. Recursively give read/write/execute permission to the GAMMA_ROOT folder for GitLab users. (e.g. sudo chmod -R 744 /opt/gamma)
  5. Download and update scan configuration json from gamma UI
  6. Update the .gitlab-ci.yml file the source code. Refer below table.
  7. In case of running gcov, Gcovr should be installed on the build machine.
    With the above settings, when the runner is launched by Gitlab while executing the pipeline, it will now also include Embold code scans.
Operating system.gitlab-ci.yml changes
Windowsset GAMMA_ROOT= C:\workspace\gitlab\gitlab_corona
‘%GAMMA_ROOT%\corona\tools\bin\gitlab_wrapper.bat gammascan.json’
Linuxexport GAMMA_ROOT=/opt/gamma
$GAMMA_ROOT/corona/tools/bin/gitlab_wrapper.sh gammascan.json

GAMMA_ROOT is where the standalone corona is installed on the runner (GAMMA_ROOT should have a folder “corona” directly in it)

Yes No

Jenkins Integration

Embold Jenkins Plugin allows users to scan code after Jenkins build is triggered. Users can configure Embold modules from this plugin. The plugin requires sign-in with the Embold Server deployed within the organization.

Yes No

Prerequisites

  • Jenkins version 1.6.1.2 to 2.164.2
  • Remote Analysis should work from Jenkins machine (where build is happening) to Embold machine. (Refer Remote Analysis article).
  • Install standalone corona on build machine (master/node) (e.g. /opt/gamma. It will be your GAMMA_ROOT folder) (Refer steps for Ubuntu, Windows, Redhat).
  • For running gcov, Gcovr should be installed on the build machine.
  • JDK (Java Development Kit)
  • JAVA_HOME environment variable need to set for build machine (master or slave) which should point to /bin
Yes No

Installation Steps

  1. Download file from your Embold Account’s section > Releases tab > Plugins > CI_CD > jenkins. There will be file with a name similar to the following: embold_jenkins_1.8.3.0.hpi.
  2. Click on “Manage Jenkins” on Jenkins’s home page.
  3. Jump to the Advanced tab.
  4. Go to the Upload Plugin section and upload “embold_jenkins_1.8.3.0.hpi”.Click the “Upload” button.
  5. After Embold Jenkins Plugin is updated, Jenkins needs to be restarted.
Yes No

Integration Modes

  1. As Post Steps: Hooking into the build process so that Jenkins Job can be marked unstable if Embold’s quality gate check fails.
  2. As Post-build Actions:
    1. Hooking into Jenkins job workflow and gets triggered after the build is completed.
    2. In this mode, Embold Jenkins plugin will run irrespective, if the build has failed for any reason.


Yes No

Configure Plugin Logs

  1. Go to the Jenkins> Manage Jenkins> System log. (Steps to add logging support)
  2. Add new log recorder” for Jenkins Plugin.
  3. The Logger should be com.acellere.plugins and the log level should be mentioned as “All”.
  4. You should only view Embold Jenkins Plugin related logs.

Post steps configuration of Jenkins Plugin

  1. Go to the “Configure” page.
  2. Got to Post Steps and from Add post-build step dropdown list, select “GAMMA Jenkins Plugin” option.
  3. Embold configuration Page is displayed to the user. Specify valid Embold URL (http://IP address of Embold Server:3000).
  4. Click on the Add button for adding Embold Credentials.
  5. In the Jenkins Credentials Provider pop-up, from Kind dropdown, choose “GAMMA Credentials”.
  6. Specify Name and Description which could be any value (it can be your Repo name or job name).
  7. Generate an Embold Access Token from the deployed Embold application website and add the Access Token under the Token section. Refer this article for generating Embold Access Token.
  8. After adding the Jenkins Credentials, select the added credential from the dropdown of Embold Credentials.
  9. Fill up the details in Subsystems section:
    1. Subsystem UID: Repository UID. Can be obtained from Repository information in corresponding project on Embold. Incorrect UID will throw an error.
    2. Snapshot Label (Optional): Provide the snapshot level value for Embold analysis. You can also provide environment variable. For example: BUILD_NUMBER

Configure Jenkins Plugin as Post-build Action

  1. Go to Post build Actions tab and add GAMMA Jenkins Plugin.
  2. You should see the Embold configuration page.
  3. Provide the following details:
    1. Select ‘Username with password’ from the ‘Kind’ dropdown.
    2. Provide other details like Username, Password, ID and Description. Click on the Add button.
  4. Fill up the details in Subsystems section:
    1. Subsystem UID: Repository UID. Can be obtained from Repository information in corresponding project on Embold. Incorrect UID will throw an error.
    2. Snapshot Label (Optional): Provide the snapshot level value for Embold analysis. You can also provide environment variable. For example:  BUILD_NUMBER

Configure Analysis Configuration file for Embold Jenkins Pugin for both modes

  • Use Analysis configuration from Gamma:
  1. Embold analysis configuration file with name ‘.gammascan.json’ containing subsystem configuration will be picked at runtime from. Embold server associated with the Subsystem ID specified.
  2. With this option, the configuration file will take the default path for Junit and Clover.
  • Use Analysis configuration file from Source code base directory:
  1. Embold analysis configuration file with name ‘.gammascan.json’ containing subsystem configuration should be present in the base(root) directory.
    1. Windows: C:/Program Files (x86)/Jenkins/workspace/{Project_Name}/.gammascan.json
    2. Linux: /var/lib/Jenkins/workspaces/{Project_Name}/.gammascan.json
  • Use Analysis configuration from Jenkins:
  1. Login to Embold. Create a project. Link the repository you want to scan.
  2. On your remote Embold instance, navigate to the repository you want to scan. Click on “…”. Download configuration json from Embold UI.
  3. Update the following fields in json.
    1. Replace baseDir value with $WORKSPACE OR %WORKSPACE%
      Note: WORKSPACE = Jenkins workspace
    2. Give custom directory path for Data directory
      Note: Make sure Jenkins user has Write permission for dataDir.
  4. Give the analysis configuration JSON  in Jenkins UI. Click on the “Apply” button. Check if any errors are displayed in any configuration field. Click on the “Save” button.

For more information to understand .gammascan.json, refer to this article.

Steps for Master Slave:

  1. Go to Jenkins -> Manage Jenkins -> Manage Nodes (only required for master – slave configuration)
  2. Open the particular Slave Node (only required for master – slave configuration).
  3. Go to Configuration.
  4. Add new “CORONA_HOME” and “CORONA_LOG” environment variables.

Steps for master only

  1. Go to Jenkins -> Manage Jenkins -> Configure System page and add the following 3 environment variables in “Global properties” section (In a case of master slave add these variables into slave configuration)
  2. CORONA_HOME (Use the same CORONA_HOME path which is set by installer. Refer standalone corona installation for Ubuntu or RHEL/CentOS)
  3. CORONA_LOG (Use the same CORONA_LOG path which is set by installer. Refer standalone corona installation for Ubuntu or RHEL/CentOS.)
Yes No

Embold Quality Gate

Below are the steps to show Embold quality gate details as an HTML report on Jenkins:

  1. Master Environment: Go to Jenkins > Manage Jenkins > Configure System and then add JENKINS_BASE environment variable in Node properties. Add path of Jenkins base directory of master’s machine.
  2. Master-Slave Environment: Go to Jenkins > Manage Jenkins > Manage Nodes > Click on the Configuration button of a particular node (slave) and then add JENKINS_BASE environment variable in Node properties. Add path of Jenkins base directory of master’s machine.
  3. Enable CSS and Javascript for Jenkins.
    1. Windows: add -Dhudson.model.DirectoryBrowserSupport.CSP=”” for Jenkins war in Jenkins.xml.
      E.g.-Xrs -Xmx256m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -Dhudson.model.DirectoryBrowserSupport.CSP=”” -jar “%BASE%jenkins.war” –httpPort=8080 –webroot=”%BASE%war”
    2. Linux: For Debian distributions, update the file- /etc/default/Jenkins.
    3. Centos/RedHat Distributions update the file /etc/sysconfig/Jenkins. E.g. JENKINS_JAVA_OPTIONS=”-Djava.awt.headless=true -Dhudson.model.DirectoryBrowserSupport.CSP=”””
  4. Restart the Jenkins. Install HTML Publisher Jenkins plugin.
  5. Add a “Publish HTML reports” plugin. Make sure the HTML Publisher plugin should be executed/added after the Embold plugin.
  6. Add the required details in the HTML publisher configuration.
  7. After build success, you can check the HTML report into HTML Publisher.
Yes No

Update Embold Jenkins Plugin

  1. Go to Jenkins -> Manage Jenkins -> Manage Plugins. In the Advanced tab, upload the latest gamma-jenkins-plugin.hpi file.
  2. Restart Jenkins using http:///safeRestart.
Yes No

Coverlet Integration

For more information about the execution of Coverlet integration, refer to this article.

UI output of coverage through coverlet can be seen in the Coverage by components section as below:

For Linux users, please check below points:

There is an issue with MSBuild on Linux that affects the ability to escape quotes while specifying multiple comma-separated values. Linux MSBuild automatically translates to / in properties, tasks, etc. before using them, which means if you specified /p:CoverletOutputFormat="json,opencover” in an MSBuild script, it will be converted to /p:CoverletOutputFormat=/"json,opencover/" before execution. This yields an error similar to the following:
MSBUILD : error MSB1006: Property is not valid. [/home/vsts/work/1/s/default.proj]
Switch: opencover/

You’ll see this if directly consuming Linux MSBuild or if using the Azure DevOps MSBuild task on a Linux agent.

The workaround is to use the .NET Core Dotnet MSBuild command instead of using MSBuild directly. The issue is not present in Dotnet MSBuild and the script will run with correctly escaped quotes.

Note: Report directory in remote scan JSON shall point to XML generated by Dotnet test command. If the job is running from Jenkins, it shall reside in its workspace location. Usually, XML is generated where .csproj is located for that project.

Limitations

For more information, refer to this article.

Troubleshooting

  • Coverlet module logs are generated inside workspace/projectName/gamma_logs/{repositoryUID}/ext_coverlet.log
Yes No

MSTest Integration

This section will help you to integrate MSTest (.Net unit test framework) tool on your local instance.

Prerequisites

  • MSBuild version should be 15 or 16 depending on the type of source code that needs to be scanned.
  • MSTest (does not require Visual Studio) can be separately downloaded as Test Agent Module.

Assumption

  • MSTest/MSBuild should run in the client environment’s existing setup.

For more information about the execution of MSTest, refer to this article.

Limitations

  1. MSTest exe takes only a DLL executable; hence, the path of the executable is very specific to the arguments provided.

Troubleshooting

  1. In spite of having Visual Studio setup, if MSTest.exe is not present on your Jenkins machine, make sure you update the installation because you may have installed minimal components and not the full IDE. Also, sometimes the test components are explicitly loaded on drives, other than C drive. 
  2. If Embold analysis succeeds only with an “INITIALIZING GAMMASCANNER” success message and git exceptions for fetching the repository, the JSON given for the scan config is invalid.  
  3. MSTest module logs are generated inside workspace/projectName/gamma_logs/{repositoryUID}/ext_mstest.log

Building C# projects in Jenkins:

While building the project from Jenkins, the following errors may occur:

  1. MSBUILD : error MSB1009: Project file does not exist
  2. MSBUILD : error MSB1008: Project file does not exist

Solutions

%WORKSPACE% value has space in it ( C:/Program Files(x86/Jenkins/jobs/MSTest-Examples.Tests-Build/workspace) ), hence, it can break it into 2 arguments.

In this case, you need to move your Job’s workspace to a location that won’t have spaces in it. You can do in either of the following ways:

  1. Relocate your whole Jenkins’ installation out of “Program Files“,
  2. Or, Use custom workspace (click on the Advanced… button on the project configuration page, under Advanced Project Options)
Note: Make sure to replace %WORKSPACE% in MSBuildConfig build step with Custom Workspace value set in the above step.
Yes No

SonarQube Integration

SonarQube integration with Embold allows users to see code issues reported by SonarQube on Embold.

Yes No

Prerequisites

  • Make sure Sonar analysis for a particular project is completed and code issues are visible on Sonar UI.
Yes No

Steps for Integrating SonarQube with Embold

The following are the steps for running the SonarQube module with Remote Analysis:

  1. Download the JSON file from Embold. To know more about downloading configuration JSON from Embold UI, click here.
  2. Add the following config parameters for the SonarQube module in the code issue section.
    1. Specify the “Sonar User Token” for authentication.
    2. Specify the URL where SonarQube is running. This is a mandatory field.
    3. Specify the unique Sonar project key. This is a mandatory field.
    4. Specify one or more severities for which code issues will be fetched from SonarQube. If not specified, code issues for all the severities will be retrieved.
      Example: SonarQube default severity values are: BLOCKER, CRITICAL, MAJOR, MINOR and INFO.
Yes No

Configuration Notes

  • Criticality filter value can contain custom severities or can be blank.
  • Example: criticalityFilter=”blocker;severe;medium”

Note: Values should be separated using semicolon (;).

Yes No

Mapping between SonarQube and Embold severity

SonarEmbold
Blocker


Critical
CriticalHigh
MajorMedium
MinorLow
InfoInfo
Yes No

TeamCity Integration

TeamCity is a user-friendly Java-based build management and continuous integration server. Embold plugin integrates with TeamCity to:

  • Automatic code scan upon triggered builds.
  • Upload project’s code to Embold with scan results
  • Embold tab to view scan summary and trends.
Yes No

Prerequisites

  • ­­For seamless installation and execution, Embold should be installed on a clean Machine/VM.
  • Install standalone corona on build machine (master/node).
  • Requires an account to sign in to Embold from the browser. Please contact the administrator to create an account.
  • Download file from your Embold Account’s section > Releases tab > Plugins > CI_CD > teamcity. There will be a file with a name similar to the following: embold_teamcity_1.8.3.0.zip.
  • Embold uses the configuration file ‘.gammascan.json’ while analyzing the project. This file should be a part of the project to be analyzed.
  • You can download configuration JSON from Embold UI.
Note: It is optional to install Embold on the build machine.
Yes No

Installation Steps

  1. On the top right corner of the TeamCity home page, click Administration.
  2. On the left navigation panel under Server Administration, click Plugin List.
  3. On the Plugin List page, click Upload plugin zip. Upload the downloaded plugin.
  4. On successful uploading, Embold plugin is listed in the External plugins table.
  5. Go to the Home page. On the left navigation pane, click Embold to validate the user.
  6. Embold can be validated using either API token or Username, then click on the Test Connection button.
  7. On successful validation, “Connection successful” message is displayed.
  8. Click on the project and build that needs to be analyzed through Embold.
  9. Click on the Edit Configuration Setting of the build.
  10. On the left navigation pane, click Parameters > Add new parameter.
  11. Add the environmental variables env.GAMMA_HOME and env.GAMMA_DATA and click Save.
    1. env.GAMMA_HOME : Specify the location where corona is installed (e.g /opt/gamma/corona)
    2. env.GAMMA_DATA : Temporary directory location. (Used to store temporary data created while analyzing repository). Note: The directory should have write permissions.
  12. The environmental variables are added successfully.
  13. Go to the left navigation pane, Click Build Step: Embold > Add build setup.
  14. Choose Embold from the build runner drop-down list.
  15. There are 2 options through which scanning can be done:
    1. Using Configuration File: Configuration file can be obtained from Embold and need to be uploaded here.
    2. Using Subsystem ID: Obtain Subsystem ID from Embold.
      This step is optional if the user wants to run the scan using Subsystem UID.
  16. You have successfully added a new Embold Built setup.
  17. Click on the Run button to build the project.
  18. After building the project, click on the Overview tab to view the result, Artifacts tab to view the generated PDF and Embold tab to view the analyzed project in a graphical format.
Yes No

IDE Plugins

Embold IDE plugin allows developers to scan their code locally within the IDE environment and find issues in code as it is developed, before committing it to version control systems. Developers can install Embold IDE Plugin in their local eclipse/VS installation. The plugin requires sign-in with the Embold server deployed within the organization. It supports both windows and Linux OS.

Yes No

Eclipse Plugin

Prerequisites

  • Eclipse versions supported by Embold Eclipse Plugin are Mars, Neon, Oxygen.
  • Requires a valid Embold username and a password. This is the account you usually use to sign in to Embold from the browser. If you don’t have one, please contact the administrator to create an account for you.
  • Requires CPPCheck version 1.78 onwards to be installed for CPP analysis. Set CPPCheck in the environment variable. Verify if the environment variable is set or not by typing ‘cppcheck –version’ on the command line.
  • Install Corona through Embold Installer.
  • Make sure the Corona folder has right permission for the user running the Eclipse Plugin.
  • Requires Eclipse CDT plugin
Yes No

Installation Steps

  1. Download file from your Embold Account’s section > Releases tab > Plugins >IDE > eclipse. There will be file with a name similar to the following:  embold_eclipse_1.8.3.0.jar.
  2. Copy Embold plugin jar (embold_eclipse_1.8.3.0.jar) into “plugins” and “dropins” folder in Eclipse installation directory. e.g. C://Users//user//eclipse//jee-neon//eclipse//plugins.
    Note: Remove the existing Embold plugin jar if any and restart the eclipse.
  3. Start/Restart eclipse. This will automatically add a new Embold plugin.
  4. Enable Embold Analysis tool in the menu bar (After restarting Eclipse): Go to Windows -> Perspective -> Customize Perspective. Check the Embold Analysis option (if not checked yet). Then you will see the Analysis button on the toolbar in Eclipse as shown below:
  5. Configuration setup and authentication process:
    1. Click on Embold on the menu bar and click on Plugin Configuration.
    2. Set GAMMA_HOME path and fill GAMMA credentials for authentication.
    3. GAMMA_HOME path should refer to the path where corona was installed.
      e.g. D:/GammaHome/corona/
    4. Contact the administrator to get Embold the URL.
    5. Enter the valid username and password.
    6. Validate the Embold credentials after clicking on ‘Verify’ button.
  6. After authentication, Go to Embold > Settings option. Select language and modules to run (e.g. CPPCheck for CPP).
  7. Click on analysis button to run analysis.
Yes No

Analysis of output

After running an analysis successfully, view the results with the help of following views on Eclipse. These views can be opened as follows:

  1. Click on Window -> Show View -> Other.
  2. Open Embold / Gamma -> Click on Embold / Gamma related views

(e.g. Component Report View, Hotspot View, and Component Info View):

  • Component Report View:
    This view gives you all the code issues and design issues for the currently opened file (Java/CPP) in the editor.
  • Hotspot View:
     This view shows all the Hotspots in the project.
  • Component Info View:
    This view opens when you right click on any code issue or design issue and click on Show info option, it gives you information related to any code issue or design issue.
  • Design Issue Info (God Class)
  • Code Issue Info
  • Metric Details
    Hovering on icon ‘i’ on vertical bar in editor gives the metric details of respective component
Yes No

IntelliJ Plugin

Prerequisites

  • Java version: 1.8+
  • Supported Intellij version:
    • IntelliJ IDEA Community : 2019.3+
    • IntelliJ IDEA Educational: 2019.3+
    • IntelliJ IDEA Ultimate: 2019.3+
  • Android Studio version: 4.0+
  • Android Studio build: 193.2252+
Yes No

Installation steps

Install the Embold plugin from the IntelliJ IDEA marketplace.

This image has an empty alt attribute; its file name is IntelliJ_Installed-1.png

Embold plugin is now available at the marketplace.

Yes No

Analysis of output

In the Embold IntelliJ plugin, the code issues are highlighted on the fly, and quick feedback is provided.
This ensures that the code issues are fixed even before the code is committed.

The code issues with its recommended solution can be seen under the “Embold Issues Inspector” section.

This image has an empty alt attribute; its file name is Analyse_results.png

For example in the above screenshot, the code is analyzed at runtime, with the below output:

  • On the left side, you see the type of issue with its description, criticality, and other details. Whereas, when you click on a specific issue, detailed information with examples can be seen on the right side.

Code issues and anti-patterns’ count can be visualized graphically.
The below output is seen in the graphical representation:
1. Issues by its criticality– The issue count is calculated according to its criticality such as critical, high, medium, low and info level issues.
2. Issues by its type: Code issue and anti-pattern count is calculated.

Yes No

Code checker configuration

This section helps to understand the supported code checks for Java language. Embold code checks can be enabled and disabled according to user requirement.

Note: Currently, we support Embold Java Issues only; and does not support PMD issues and SpotBugs issues.

Critical Level Issues

RuleDescriptionExampleKPI
Compile Regex OncePattern object compiles the regular expressions which are passed to them and this compilation happens in the memory. If a regular expression is used many times, then this compilation should be performed only once.Non-compliant code:
Class Foo {
// This method can call multiple times
void findText(String inputText) {
Pattern pattern = Pattern.compile("(.*)(\\d+)(.*)");
Matcher matcher = pattern.matcher(inputText);
if(matcher.find()) {
MatchResult result = matcher.toMatchResult();
}
}
}


Compliant code:
Class Foo {
Pattern pattern = Pattern.compile("(.*)(\\d+)(.*)");

void findText(String inputText) {
Matcher matcher = pattern.matcher(inputText);
if(matcher.find()) {
MatchResult result = matcher.toMatchResult();
}
}
}
Efficiency
Disabled Spring Securitys CSRFCSRF protection is enabled by default in the Java configuration. Disabling CSRF protection can create a major security threat.
Cross-Site Request Forgery (CSRF) is an attack that forces an end user to execute unwanted actions on a web application in which they're currently authenticated.

More Info - OWASP Top 10 A6:2017 - Security Misconfiguration
CWE-352 - Cross-Site Request Forgery (CSRF)
Non-compliant code:
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

@Override
protected void configure(HttpSecurity http) throws Exception {
http.csrf().disable();
}
}


Compliant code:
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
// Do not disable CSRF
// http.csrf().disable();
}
}
Security
Resource LeakResource should be closed in finally block. Another way is to use try-with-resource. In case of either exception or no exception, close() should always be put in finally clause.Non-compliant code:
class Demo {

public void process1() {
try {
PrintWriter out = new PrintWriter(new BufferedWriter(new FileWriter("out.txt", true)));
out.println("the text");
out.close(); //close() is in try clause
} catch (IOException e) {
logger.error("resource is closed in try block",e);
}
}

//Non-compliant code
//resource is not closed anywhere
public void process2() {
try {
PrintWriter out = new PrintWriter(new BufferedWriter(new FileWriter("out.txt", true)));
out.println("the text");
} catch (IOException e) {
logger.error("Resource is not closed anywhere.",e);
}
}
}


Compliant code:
class Demo {
public void process2() {
printWriter out = null;
try {
out = new PrintWriter(new BufferedWriter(new FileWriter("out.txt", true)));
out.println("the text");
} catch (IOException e) {
logger.error("Resource is closed in finally block",e);
} finally {
if (out != null) {
out.close(); //close() is in finally clause
}
}
}

//compliant code
//try-with-resource statement
public void process3() {
try (PrintWriter out2 = new PrintWriter(new BufferedWriter(new FileWriter("out.txt", true)))) {
out2.println("the text");
} catch (IOException e) {
logger.error("try-with-resource",e);
}
}
}
Resource Utilization
Weak Cipher AlgorithmUse strong cryptographic algorithms as they are less vulnerable to brute force attacks among others.
For more information : : OWASP Top 10 2017 Category A3 - Sensitive Data Exposure
MITRE, CWE-327 - Use of a Broken or Risky Cryptographic Algorithm
Non-compliant code:
class CipherExample
{
public void foo()
{
try
{
Cipher c = Cipher.getInstance("DES"); // Or DESede, RC2, RC4 as these are known to be vulnerable
} catch (NoSuchAlgorithmException | NoSuchPaddingException e)
{
logger.error("Invalid algorithm",e);
}
}
}


Compliant code:

class CipherExample
{
public void foo()
{
try
{
Cipher c = Cipher.getInstance("AES/GCM/NoPadding"); // Compliant
} catch(NoSuchAlgorithmException|NoSuchPaddingException e)
{
logger.error("Invalid algorithm",e);
}
}
}
Security
Possible Thread Leak In Executor Service Thread leak can be possible if ExecutorService is not getting shutdown.There is a queue of tasks between client threads and thread pool. When the normal thread finishes the "run" method (Runnable or Callable), it will be passed to garbage collector for collection. But with ExecuterService, threads will be simply put on hold and they will not be selected for garbage collection. Therefore, the shutdown is needed for ExecutorService.
Non-compliant code:
class Demo {

//ExecutorService is not closed anywhere
public void process1() {
ExecutorService executorService = Executors.newSingleThreadExecutor();
executorService.execute(new Runnable() {
@Override
public void run() {
try {
doTask();
} catch (Exception e) {
logger.error("indexing failed", e);
}
}
});
}
}


Compliant code:
class Demo {

public void process2() {
ExecutorService executorService = Executors.newSingleThreadExecutor();
executorService.execute(new Runnable() {
@Override
public void run() {
try {
doTask();
} catch (Exception e) {
logger.error("indexing failed", e);
}
}
});
executorService.shutdown();
}
}

Resource Utilization
Non Private Field In Synchronized BlockNon-private, non-final field accessed in synchronized block indicates possibly partial synchronization, and does not protect direct access to the field from other parts of the system without synchronization.
Make the field private and/or final, and provide accessors which can enforce synchronization.

More Info - CWE-820 - Missing synchronization
Non-compliant code:
class NonPrivateFieldAccessInSynchronizedBlock {

protected List statuses = new ArrayList<>(); // or public
private Object lock = new Object();

void foo() {
// Some processing
synchronized(lock) {
statuses.add("Running");
}
}
// Some more processing
}


Compliant code
class NonPrivateFieldAccessInSynchronizedBlock {

private List statuses = new ArrayList<>();
private Object lock = new Object();

void foo() {
// Some processing
synchronized(lock) {
statuses.add("Running");
}

// Some more processing
}

void updateStatus(String status) {
synchronized(lock) {
statuses.add(status);
}
}
}
Robustness, Security
Database Should Be Password ProtectedDatabase connection should always be password protected. Attacker can access the sensitive data from the database, in case it is not secured by password.

More Info
- [OWASP Top 10 2017 Category A3] - Sensitive Data Exposure
- [MITRE, CWE-521] - Weak Password Requirements
Non-compliant code:
class CipherExample {
public void foo() {

Connection conn1 = DriverManager.getConnection("jdbc:derby:memory:myDB;create=true", "AppLogin", "");
Connection conn2 = DriverManager.getConnection("jdbc:derby:memory:myDB;create=true?user=user&password=");
Connection conn3 = DriverManager.getConnection("jdbc:derby:memory:myDB;create=true?user=user");
}
}


Compliant code
class CipherExample {
public void foo() {
Connection conn4 = DriverManager.getConnection("jdbc:derby:memory:myDB;create=true", "AppLogin", "password");
Connection conn5 = DriverManager.getConnection("jdbc:derby:memory:myDB;create=true?user=user&password=text");
Connection conn6 = DriverManager.getConnection("jdbc:derby:memory:myDB;create=true&password=text", "AppLogin", "");
}
}
Security

High-Level Issues

RuleDescriptionExampleKPI
Initialization Of Secure Random At Method Level"SecureRandom" should not be initialized in method. Every SecureRandom generation is seeded from some entropy pool. Creating a new SecureRandom method on every call might slow down the application as it might block the creation of seed. Use a statically created instance instead.Non-compliant code
class Demo {

public int generateSecureKey() {
SecureRandom secureRandom = new SecureRandom();
return secureRandom.nextInt();
}
}


Compliant code
class SecureRandomGenerator {
static SecureRandom secureRandom = new SecureRandom();
public int generateSecureKey() {
return secureRandom.nextInt();
}
}
Security
Security Sensitive RegexRegular expressions are security-sensitive. Evaluating regular expressions with input string can be an extremely CPU-intensive task. The regular expression naive algorithm builds a Nondeterministic Finite Automaton (NFA), the attacker might use the knowledge of states of finite state machine to look for applications that use regular expressions, containing an Evil Regex, and send a well-crafted input, that will hang the system. Alternatively, if a Regex itself is affected by a user input, the attacker can inject an Evil Regex, and make the system vulnerable.
Examples of Evil Patterns:
Examples of Evil pattern : 1) (a+)+ 2) ([a-zA-Z]+)* 3) (a|aa)+ 4) (a|a?)+ 5) (.*a){2} for x > 10

E.g
Pattern: /(a+)+b/;
Input string:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab
Instead use Pattern:(/a+b/) //fixed the hard-coded regex pattern to avoid possible captures, possessive quantifiers and back-references

To avoid possible attacks, if the regex pattern is defined with an user-controlled input, it should be sanitized in order to escape characters which are part of the regular expression syntax.

Non-compliant code
class Demo { public boolean validate1(javax.servlet.http.HttpServletRequest request) { String regex = " /(a+)+b/"; String input = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab"; input.matches(regex); //Noncompliant
}
}


Compliant code
class Demo { public boolean
{
validate2(javax.servlet.http.HttpServletRequest request)
{ String regex = "/a+b/"; String input = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab";
input.matches(Pattern.quote(regex)); // Compliant
} }

Efficiency, Security
Use Of System.err.println 1. System.err.println is an IO-operation and therefore is time consuming.
2. The better approach is to use a logging framework for a message queue.
3. Moreover, you can configure separate log files for different purposes.
Non-compliant code
class Demo {
public void process1() {
System.err.println("Error while processing");
}
}


Compliant code
class Demo {
public void process2() {
logger.error("Error while processing",e);
}
}
Analyzability
Invalid Logging Class Name Avoid incorrect class names while creating logger. Ignoring this may create confusion while analysing logs.
Non-compliant code
public class LoggingClass extends BaseChecker {
private static Logger logger = LogManager.getLogger(InvalidLoggingClass.class.getName());
}


Compliant code
public class LoggingClass extends BaseChecker {
private static Logger logger = LogManager.getLogger(LoggingClass.class.getName());
}

Analyzability
Use Of System.out.println 1.Sending messages to stdout is usually inappropriate in a production environment. E.g. If you are coding a GUI app, the information should be presented to the user and not to the stdout method anywhere.
2.System.out.println is an IO-operation and therefore is time consuming. The better approach is to use a logging framework for a message queue.
3.Moreover, you can configure separate log files for different purposes.
Non-compliant code
class Demo {
public void process1() {
//some statements
System.out.println("Some text");
}


Compliant code
public void process2() {
//some statements
logger.info("Some text");
}
}

Analyzability
Complex Regex PatternAvoid usage of complex Regex pattern as it involves heavy processing.In some cases complex Regex performance test shows that regex is significantly inefficient. //Non-compliant code
class Demo {
String regex = "(.*)(\\d+)(.*)";
Pattern p = Pattern.compile(regex);
}

Efficiency
Empty Catch BlockEmpty Catch Block finds instances where an exception is caught, but nothing is done. In most circumstances, this ignores an exception which should either be acted on or reported. Avoid keeping the catch block empty. // Non-compliant code
class Demo {

public void process1() {
try {
FileInputStream fis = new FileInputStream("/tmp/bugger");
} catch (IOException ioe) {
}
}


// compliant code
public void process2() {
try {
FileInputStream fis = new FileInputStream("/tmp/bugger");
} catch (IOException ex) {
logger.error("Inside catch block",ex);
}
}
}
Analyzability
Sensitive Info LoggedLogger is used for recording application activity. Information displayed on the logs is visible to different stakeholders. Avoid logging sensitive information such as password, key, social security number etc. Not complying may compromise the system security.Non-compliant code:
class Demo {
void process1(String password) {
//Displaying sensitive information in logs
logger.info("Password received "+ password);
}
}


Compliant code
class Demo {
void process1(String password) {
//doSomething
logger.info("Password received");
}
}
Security
Thread.sleep() In a Synchronized Block Or MethodCalling Thread.sleep() in a synchronized method/scope blocks the thread holding the lock, which can impact performance, or can even cause deadlocks. This is because Thread.sleep() does not cause a thread to release its locks.
Thread.sleep() should be called only outside of a synchronized method/scope. A better way for threads to yield execution time to other threads would be to use wait/notifyAll methods or the java.util.concurrent library.

More Info
CWE-833 - Deadlock
LCK09-J - Do not perform operations that can block while holding a lock
Non-compliant code:
class Demo {
// Non-compliant code
public void foo(){
synchronized(lock) {
while(waitForInit()){
try {
Thread.sleep(500);
} catch (InterruptedException e) { }
}
execute();
}
}


Compliant code
public void foo(){
synchronized(lock) {
while(waitForInit()){
try {
lock.wait(500);
} catch (InterruptedException e) { }
}
execute();
}
}
}
Efficiency

Medium Level Issues

RuleDescriptionExampleKPI
Return Empty Array Or Collection Instead Of Null Returning null value instead of an empty array or collection can lead to denial-of-service vulnerabilities when the client code fails to explicitly handle the null return value. For methods that return a set of values using an array or collection, returning an empty array or collection is an excellent alternative to returning a null value.

More Info
MET55-J - Return an empty array or collection instead of a null value for methods that return an array or collection

MSC19-C - For functions that return an array, prefer returning an empty array over a null value
Non-compliant code:
class Demo {
public static List getList() {
return null; // Non-compliant code
}

public static void main(String[] args) {
List results = getList();
for (Result result: results) { } // Need to add Nullity check to prevent NPE
}
}


Compliant code:
class Demo {
public static List getList() {
return Collections.emptyList(); // Compliant code
}

public static void main(String[] args) {
List results = getList();
for (Result result: results) { } // No need to add Nullity check to prevent NPE
}
}
Robustness
Preserve Stack Trace In LogsPreserve stack trace in logs. This will help to analyse the logs in case of any exception. Non-compliant code:
class Demo {
public void process1() {
try{
//some statements
} catch(Exception e) {
logger.error("Error while processing");
}
}
}


Compliant code:
class Demo {
public void process2() {
try {
//some statements
} catch(Exception e) {
logger.error("Error while processing",e);
}
}
}

Analyzability
Read Only TransactionSpring components support database transactions using "@Transactional" annotation. If readOnly attribute is not explicitly set to true, we will have read/write transactions for select queries. Hence, it is always recommended to explicitly specify the readOnly attribute.Non-Compliant Code:
class Demo {
public class UserRepository {
@Query("select username from users")
public List getAllUsers() {
}
}
}


Compliant Code:
class Demo {
@Transactional(readOnly=true)
public class UserRepository {
@Query("select username from users")
public List getAllUsers() {
}
}
//Compliant Code
public class UserRepository {
@Transactional(readOnly=true)
@Query("select username from users")
public List getAllUsers() {
}
}
}
Robustness
Unusual REST PracticeThe best practices while creating REST API's are :
1. URL should contain resources (E.g. nouns) only; not actions or verbs.

2. Singular and plural noun should not be mixed together.

3. Use plural noun only for all the resources.

4. Use GET method, instead of the POST method to fetch the data.

5. Use PUT, POST and DELETE methods to alter the state.
Non-compliant code
class Demo {
@RequestMapping("/users")
public class UserController{

@RequestMapping(value="/getUser")
public void getUser(){
}
}
}


Compliant code
class Demo {
@RequestMapping("/users")
public class UserController{

@RequestMapping(value="/{user}")
public void getUser() {
}
}
}
Maintainability

Low-Level Issues

RuleDescriptionExampleKPI
Log Level Info In Catch BlockThe catch block handles exception that occurs in associated try block. In this block, the logger level is expected to be as "error". This is a good list describing the log levels :
1. Debug : Used for development and testing.
2. Information : Used to output information that is useful to run and manage your system.
3. Warning : Used for handled 'exceptions' or other important log events.
4. Error : Used to log all unhandled exceptions. This is typically logged inside a catch block at the boundary of your application.
5. Fatal : Used for special exceptions/conditions where it is imperative that we can quickly pick out these events.
Non-compliant code:
class Demo {
public void process1() {
try {
//statements where exceptions may occur
} catch(Exception ex) {
logger.info("some information",ex);
}
}
}


Compliant code:
class Demo {
public void process2() {
try {
//statements where exceptions may occur
} catch(Exception ex) {
logger.error("some information",ex);
}
}
}
Analyzability
Non Thread Safe Field DeclarationA field declared inside the spring component should be thread safe. By default, beans in spring are singleton. Multiple threads accessing the same component may produce inconsistent results, if they access fields declared globally.Non-compliant code:
class Demo {
@Service
public class LoggingClass extends BaseChecker {
private Map map = new HashMap();
void modifyMap(){
map.add("key","value");
}
}
}


Compliant code:
class Demo {
@Service
public class LoggingClass extends BaseChecker {
void modifyMap(){
Map map = new HashMap();
map.add("key","value");
}
}
}

Robustness

Info Level Issues

RuleDescriptionExampleKPI
String Concatenation In LoggingInstead of string concatenation use parameterized logging. Concatenation is calculated before the condition check. If you call your logging framework multiple times which turns to be false, this effort will be a waste of time. E.g. if you call your logging framework 10K times conditionally and all of them evaluates to be false, concatenation will happen 10K times.Non-compliant code:
class Demo {
//If log level is not debug, then also string concatenation will happen.
public void process1() {
logger.debug("Comparing objects: " + object1 + " and " + object2);
}
}


Compliant code:
class Demo {
public void process2() {
//Compliant code
logger.debug("Comparing objects: {} and {}",object1, object2);
}
}
Efficiency
Tightly Coupled ClassA spring component such as repository, service and controller should auto-wire the interface, instead of its implementation class. Ignoring this, will increase tight coupling among the classes Non-compliant code:
class Demo {
@RequestMapping("/users")
public class UserController
{
@Autowire
UserServiceImpl userServiceImpl;
}
}

Compliant code:
class Demo {
@RequestMapping("/users")
public class UserController
{
@Autowire
UserService userService;
}
}
Maintainability
Yes No

Visual Studio Plugin

Prerequisites

  • Visual Studio versions supported by Embold Visual Studios Plugin: Visual Studios 2015 14.0.25431.01 Update 3, Visual Studios 2017 15.9.25, Visual Studios 2019 16.6.2.
  • A valid Embold user registered with the Embold Instance deployed for the organization. Please contact the administrator for creating a valid Embold user account.
  • Install Corona from Embold Installer.
  • Contact administrator to download gamma_ide_plugins.tar.gz file.
  • These files “embold_vs2015_1.2.vsix”, “embold_vs2017_1.2.vsix” and “embold_vs2019_1.2.vsix” are present in folder “visual studio” that are used for Embold-VSPlugin installation.
  • Before installing Embold Visual Studio Plugin ensure that all Visual Studio instances are closed.
  • Languages supported: C/C++, C#
  • Frameworks supported for C# Language: 
    • .NET Framework-based projects supported for Embold plugin for Visual Studios 2015 and Visual Studios 2017.  
    • .NET Framework, .NET Standard and .NET Core based projects supported with Embold Plugin for Visual Studios 2019
Yes No

Installation Steps

  1. Download the installer file from your Embold Account’s section > Releases tab > Plugins > IDE > visual_studio. There will be three file with names similar to the following: embold_vs2015_1.2.vsix, embold_vs2017_1.2.vsix, and embold_vs2019_1.2.vsix.
  2. Double click on the relevant vsix file version that is available for Visual Studio installed on the machine.
  3. Check the appropriate option (E.g. the Visual Studio 2017 option) from the given options and click “Install”.
  4. A successful installation message of the plugin will be displayed to the user. (E.g. Visual Studio 2017)
Yes No

User Authentication for Visual Studio Plugin

  1. Analysis can be done in 2 ways:
    1. Open Visual Studio and select open Project/Solution option in File-> Open Menu option OR
    2. Navigate to the solution which needs to be analysed and open the .sln file in Visual Studio.
  2. After opening a solution, if the Embold Visual Studio Plugin was installed successfully, the user should see the “Embold” Menu in the Visual Studio Menu bar.
  3. Inside the Settings Option, select the ”Gamma” option. There are two sub-options Analysis and User Registration.

A. Analysis

  • Here a user can configure the mode of analysis.
    Analyse on Save: Checking this option would enable the user to analyse the file on every “Save” operation.
    • Scan Type
      • Full Scan: This is a fresh scan option where user can analyse the source code irrespective of any scan history.
      • Incremental Scan: This option will enable incremental analysis of a single file or set of files with reference to the previous full scan analysis. Currently, only “Full” Analysis mode is supported.
    • External Tools
      • CPP Check: For a C++ project, the user can check the CPP Check option to enable CPP Check and see the code issues in the Component Issues View inside the Visual Studio instance.
      • Clang Static Analysis: Not yet supported.
    • Logging
      • File Logging: Checking this option enables the user to get file logs as per the instance. The logs can be found at the following location: “C:UsersTestUserAppDataLocalAcellerePluginsVS”
      • Name Obfuscation: Checking this option generates obfuscated logs at the above location.

B. User Registration

  1. Corona Home Directory: Refer to the path where Corona is installed.
  2. Embold URL: The Embold URL should be given in the below format: 
    “http://emboldServer:3000”. Here “emboldServer” is the Embold Server deployed for the organization.
  3. User ID: This is the authenticated mail address of an Embold user registered on the Embold Server deployed for an organization.
  4. Password: Enter the valid password for the account registered for the User ID mentioned above.
  5. Verify:
    1. It is mandatory to get these credentials verified by clicking on the “Verify” button. Users will get a “Verified” message on successful verification.
    2. Ensure that a valid Embold User’s Embold server instance is up before entering the credentials; else user will get the “Embold server not reachable” status as shown below.
    3. Once the user is authenticated to use the plugin, a message “Embold is ready” will be displayed to the user in the leftmost corner of the Visual Studio status bar. It will indicate that the user can now proceed with code analysis.
Yes No

Code Analysis on Visual Studio Plugin

  1. Various options are provided to enable the user in getting a detailed analysis report. Embold analysis helps the user get all the Dependencies and Inter-dependencies between classes and methods. It is recommended that the user does a complete scan using the “Analyse Solution” option first and later the user can run scans on individual files that are modified. Below options are available for scanning the source code: Analyse Solution: The entire solution is scanned using this option. This is the currently recommended option.
  2. On selecting any analysis option, the ”Analysing” status message is displayed on the leftmost corner of the status bar and also a processing box appears as long as the analysis is in progress. The time taken for analysis is dependent on the scanning option selected and the size of code to be analysed.
  3. On successful analysis, an “Analysis completed” message will be displayed on the output tool window of Visual Studio.
  4. If the analysis fails due to any reason, the “Analysis failed” status will be displayed on the Embold output tool window.
  5. The user can also stop analysis in between by using the “Stop Analysis” option from the Embold Menu on the Menu bar. An “Analysis Aborted” status will be notified on this operation in the same Embold Output Tool Window.
Yes No

Analysis of output

After running analysis successfully, results can be viewed through the following views:

  • Hotspot View:
    Click on Embold -> Hotspot View: This view shows all the Hotspots in the project.
  • Component Issues Summary View:
    Click on Embold -> Component Issues Summary View: This view gives all the code issues and design issues for the currently opened file in editor.
  • Component Issues Summary View:
    Right-click on a particular issue in Component Issue Summary View -> ShowInfo: This view gives detailed information related to the code or design issue.
  • Metric adornments:
    The four-blue coloured ellipses above Classes and Methods shows the Metrics Issues and the Design Issues related that particular Class or Method. Hovering over this adornment will display the analysis similar to below image.

Yes No

Limitations

  • Currently, Embold Visual Studio Plugin does not support the analysis of both C# and C++ code together in a single solution.
  • Users cannot analyse the same code in multiple instances of Visual Studio’s.
Yes No

VS Plugin Marketplace Installation

Prerequisites

  • Supported Visual Studio version: VS2019
  • Supported Visual Studio OS: Windows
  • Supported Language: C#
Yes No

Installation steps

Install the Embold plugin from the marketplace.

While it is getting installed, the pop-up window is displayed as below:

Embold plugin is now available in the marketplace.

Yes No

Analysis of output

In the Embold Visual Studio plugin, the code issues are highlighted on the fly, and quick feedback is provided. This ensures that the code issues are fixed even before the code is committed.
Moreover, the code issues are suppressed and suppression information occurs where the violation occurs.

The code issues detected on the fly can be seen under the “Error List” section. Users can collapse/expand specific issues accordingly.

For example in the above screenshot (E.g. under Error List > Warnings“) section, the code is analyzed at runtime, with the below output:

  • Under Error List, various types of errors with its error code, description, suppression state, and other details will be displayed. Whereas, when you click on a specific issue, detailed information can be seen in this documentation link.
Yes No

Code Checker Configuration

Code Issue NameDescriptionExample
MethodLinesOfCodeVoilationRuleMethod having high number of lines of code(LOC)/statements are harder to understand and may violate single responsibility principle. Consider refactoring the method to modular methods.

The default threshold for maximum allowed LOC/statements for a method is 50. When the LOC/statements for a method exceeds the threshold limit, the violation is notified.
Non-complaint code:
///
/// Loads the module definition into a project content.
///

/// Unresolved type system representing the assembly
[CLSCompliant(false)]
public IUnresolvedAssembly LoadModule(ModuleDefinition moduleDefinition)
{
if (moduleDefinition == null)
throw new ArgumentNullException("moduleDefinition");

this.currentModule = moduleDefinition;

// Read assembly and module attributes
IList assemblyAttributes = new List();
IList moduleAttributes = new List();
AssemblyDefinition assemblyDefinition = moduleDefinition.Assembly;
if (assemblyDefinition != null) {
AddAttributes(assemblyDefinition, assemblyAttributes);
}
AddAttributes(moduleDefinition, moduleAttributes);

assemblyAttributes = interningProvider.InternList(assemblyAttributes);
moduleAttributes = interningProvider.InternList(moduleAttributes);

this.currentAssembly = new CecilUnresolvedAssembly(assemblyDefinition != null ? assemblyDefinition.Name.FullName : moduleDefinition.Name, this.DocumentationProvider);
currentAssembly.Location = moduleDefinition.FullyQualifiedName;
currentAssembly.AssemblyAttributes.AddRange(assemblyAttributes);
currentAssembly.ModuleAttributes.AddRange(assemblyAttributes);

// Register type forwarders:
foreach (ExportedType type in moduleDefinition.ExportedTypes) {
if (type.IsForwarder) {
int typeParameterCount;
string ns = type.Namespace;
string name = ReflectionHelper.SplitTypeParameterCountFromReflectionName(type.Name, out typeParameterCount);
ns = interningProvider.Intern(ns);
name = interningProvider.Intern(name);
var typeRef = new GetClassTypeReference(GetAssemblyReference(type.Scope), ns, name, typeParameterCount);
typeRef = interningProvider.Intern(typeRef);
var key = new TopLevelTypeName(ns, name, typeParameterCount);
currentAssembly.AddTypeForwarder(key, typeRef);
}
}

// Create and register all types:
CecilLoader cecilLoaderCloneForLazyLoading = LazyLoad ? new CecilLoader(this) : null;
List cecilTypeDefs = new List();
List typeDefs = new List();
foreach (TypeDefinition td in moduleDefinition.Types) {
this.CancellationToken.ThrowIfCancellationRequested();
if (this.IncludeInternalMembers || (td.Attributes & TypeAttributes.VisibilityMask) == TypeAttributes.Public) {
string name = td.Name;
if (name.Length == 0)
continue;

if (this.LazyLoad) {
var t = new LazyCecilTypeDefinition(cecilLoaderCloneForLazyLoading, td);
currentAssembly.AddTypeDefinition(t);
RegisterCecilObject(t, td);
} else {
var t = CreateTopLevelTypeDefinition(td);
cecilTypeDefs.Add(td);
typeDefs.Add(t);
currentAssembly.AddTypeDefinition(t);
// The registration will happen after the members are initialized
}
}
}
// Initialize the type's members:
for (int i = 0; i < typeDefs.Count; i++) {
InitTypeDefinition(cecilTypeDefs[i], typeDefs[i]);
}

AddToTypeSystemTranslationTable(this.currentAssembly, assemblyDefinition);
// Freezing the assembly here is important:
// otherwise it will be frozen when a compilation is first created
// from it. But freezing has the effect of changing some collection instances
// (to ReadOnlyCollection). This hidden mutation was causing a crash
// when the FastSerializer was saving the assembly at the same time as
// the first compilation was created from it.
// By freezing the assembly now, we ensure it is usable on multiple
// threads without issues.
currentAssembly.Freeze();

var result = this.currentAssembly;
this.currentAssembly = null;
this.currentModule = null;
return result;
}
CyclomaticComplexityForMethodVoilationRuleCyclomatic Complexity (CC) is a measure of the program's complexity achieved by measuring the number of linearly independent paths through a program's source code. The number of linearly independent paths also means the minimum number of paths that should be tested. The more paths, the higher the number of test cases that need to be implemented. Consider splitting this method into smaller methods.
The default threshold for the maximum allowed Cyclomatic Complexity for a method is 15. When the Cyclomatic Complexity for a method exceeds the threshold limit, the violation is notified.
Non-compliant code:
static bool Compare(object val1, object val2, Type type)
{
if (val1 == val2)
return true;
if (val1 == null || val2 == null)
return false;
if (type == typeof(ResolveResult)) {
return IsEqualResolveResult((ResolveResult)val1, (ResolveResult)val2);
} else if (type == typeof(IVariable) || type == typeof(IParameter)) {
return IsEqualVariable((IVariable)val1, (IVariable)val2);
} else if (type == typeof(MethodListWithDeclaringType)) {
var l1 = (MethodListWithDeclaringType)val1;
var l2 = (MethodListWithDeclaringType)val2;
return object.Equals(l1.DeclaringType, l2.DeclaringType)
&& Compare(l1, l2, type.BaseType);
} else if (type.IsArray || type.IsGenericType && (type.GetGenericTypeDefinition() == typeof(List<>) || type.GetGenericTypeDefinition() == typeof(ReadOnlyCollection<>) || type.GetGenericTypeDefinition() == typeof(IList<>) || type.GetGenericTypeDefinition() == typeof(ICollection<>) || type.GetGenericTypeDefinition() == typeof(IEnumerable<>))) {
Type elementType = type.IsArray ? type.GetElementType() : type.GetGenericArguments()[0];
object[] arr1 = ((IEnumerable)val1).Cast().ToArray();
object[] arr2 = ((IEnumerable)val2).Cast().ToArray();
if (arr1.Length != arr2.Length)
return false;
for (int i = 0; i < arr1.Length; i++) {
if (!Compare(arr1[i], arr2[i], elementType))
return false;
}
return true;
} else {
if (object.Equals(val1, val2))
return true;
else if (val1 is Conversion && val2 is Conversion && ((Conversion)val1).IsAnonymousFunctionConversion && ((Conversion)val2).IsAnonymousFunctionConversion)
return true;
else
return false;
}
}
InvalidLoggingClassNameRuleConsider creating the logger name in context to the current class name.Non-Compliant code:

class ExampleClass
{
private static ILog logger = LogManager.GetLogger("otherClass");
static void Main(string[] args)
{
try
{
logger.Info("");
}
catch (Exception e)
{
}
}
}


Compliant code:

class ExampleClass
{
private static ILog logger = LogManager.GetLogger("ExampleClass");
static void Main(string[] args)
{
try
{
logger.Info("");
}
catch (Exception e)
{
}
}
}
WeakEncryptionCheckRuleWeak encryption algorithms provide very little security and insufficient protection for sensitive data hence it is recommended to use a more secure encryption algorithm, such as AES.Non-compliant code :

using (var tripleDES = new TripleDESCryptoServiceProvider()) //Noncompliant
{
//...
}


Compliant code :

AesManaged aes = new AesManaged
{
KeySize = 128,
BlockSize = 128,
Padding = PaddingMode.PKCS7
};
VulnerableEncryptionModeCheckRuleSecure the encryption mode by combining Cipher Block Chaining with an authenticity check (HMAC-SHA256 for example) on the ciphertext.Non-compliant code :

AesManaged aes = new AesManaged
{
KeySize = 128,
BlockSize = 128,
Mode = CipherMode.ECB, // Noncompliant
Padding = PaddingMode.PKCS7
};
CsrfTokenCheckRuleThe action might be vulnerable to CSRF attack. It is advisable to check if it is secured with [ValidateAntiForgeryToken] attribute globally.Non-compliant code:
[HttpPost]
public IActionResult ChangePassword()
{
// ...
return View();
}


Compliant code:

[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult ChangePassword()
{
// ...
return View();
}
DisposableTypePublicallyExposedRuleDisposable types should not be publicly exposed as properties or fields.Non-compliant code:
public IDisposable Test { get { return null; } }
DoNotChangeLoopVariablesRuleDo not change a loop variable inside the loop. Changing variable inside the loop may cause inconsistent behavior and a possible runtime exception.Non-compliant code
void TestForLoopVariableChange()
{
for (int i = 0; i < 20; i++)
{
i = 14;
}
}
AsyncMethodShouldNotHaveThreadSleepRuleAn asynchronous method should not use a synchronous thread sleep mechanism. Thread.Sleep blocks the current thread; instead, use Task.Delay. Task.Delay pauses execution but will free the thread for other execution.Non-compliant code

Task MyMethod()
{
Thread.Sleep(1000);
}


Compliant code:

Task MyMethod1()
{
await Task.Delay(1000);
}
CatchBlockShouldThrowExceptionRuleA catch block should throw exceptions instead of eating the exception. Swallowing an exception without re-throwing it's details, tampers the origin of exception and makes debugging difficult.Non-compliant code:

{
// do something
}
catch(Exception e)
{
Log.Error("Exception occured");
}


Compliant code:

{
// do something
}
catch (Exception ex)
{
Log.Error("Exception occured");
throw;
}
EmptyCatchBlockRuleCode should not swallow exceptions using generic catch blocks like catch {} or catch(Exception){}.Non-compliant code:

Something()
{
try
{
// do something
}
catch
{
}
}


Compliant code:

try
{
// do something
}
catch(Exception e)
{
Log.Info("Exception occured");
}
FinallyBlockShouldNotThrowExceptionRuleThrowing an exception from a finally block may hide an exception thrown from the try or catch block. Non-compliant code

Something()
{
var value = 1;
try
{
// do something
}
catch (System.ArgumentException)
{
// do something
}
finally
{
Increment(ref value);
throw new System.Exception($"Unbecoming exception No {value}");
}
}
IneffectiveExceptionHandlingRuleWhile handling exceptions, the 'Message' property does not contain any useful information which can assist in debugging the cause for the exception. Useful information can be extracted from the 'InnerException' property and should be used while handling and logging exceptions. Non-compliant code:
public static void Foo()
{
try
{
new object();
}
catch (Exception e)
{
Console.WriteLine(e.Message);
}
}
UsingMoreSpecificExceptionTypeRuleThrow statements should not directly use types such as Exception, SystemException, and ApplicationException because they are too vague and don't have information about the failure reason. Use more specific types of exceptions or create your own that represents a given exceptional situation. Having a specific type for all types of failures makes logs filtering and aggregating much easier. Custom exception types allow also to convey in semantic form more contextual information inside the exception object.Non-compliant code :

try
{
// do something
}
catch (ArgumentException)
{
throw new ArgumentException($"Hiding the original exception {value}");
}


Compliant code :

try
{
//some code here
}
catch (ArgumentException ex)
{
throw new CustomException("", ex);
}
MultiThreading_AcquireLockInsideTryRuleWhen manually managing scope of locking by directly calling methods responsible for acquiring and releasing the lock , ensure that the lock is acquired inside try clause.Non-compliant code :

class MyClass
{
private readonly object myLockObj = new object();
public void MyMethod()
{
Monitor.Enter(myLockObj);
}
}


Compliant code :

class MyClass
{
private readonly object myLockObj = new object();
public void MyMethod()
{
var lockAcquired = false;
try
{
lockAcquired = Monitor.TryEnter(myLockObj);
}
finally
{
if (lockAcquired)
Monitor.Exit(myLockObj);
}
}
}
MultiThreading_MethodLevelSynchronizationRuleDo not lock on the publicly accessible member as it can result in a deadlock.Type encapsulating access to a resource that requires synchronization should ensure that resource is not public.Non-compliant code:

[MethodImpl(MethodImplOptions.Synchronized)]
public void DoFirstThing()
{
//some code here
}
MultiThreading_NoLockOnPublicMembersRuleDo not lock on the publicly accessible member as it can result in a deadlock. Type encapsulating access to a resource that requires synchronization; it should be ensured that synchronization should be encapsulated.Non-compliant code :

public class SomeObject
{
public void SomeOperation()
{
lock(this)
{
//Access instance variables
}
}
}
MultiThreading_ReleaseLockInsideFinallyRuleWhen manually managing the scope of locking by directly calling methods responsible for acquiring and releasing, ensure that the lock is released inside the finally clause to ensure that the lock is manually released in case of any exception.Non-compliant code :

class MyClass
{
private readonly object myLockObj = new object();
public void MyMethod()
{
try
{
Monitor.Enter(myLockObj);
}
catch(Exception ex)
{
...
...
}
Monitor.Exit(myLockObj);
}
}


Compliant code :

class MyClass
{
private readonly object myLockObj = new object();
public void MyMethod()
{
try
{
Monitor.Enter(myLockObj);
}
catch(Exception ex)
{
...
...
}
finally
{
Monitor.Exit(myLockObj);
}
}
}
DontCallVirtualMethodsInConstructorRuleWhen a virtual method is called, the actual type that executes the method is not selected until run time. When a constructor calls a virtual method, it's possible that the type that invokes the method has not been initialized yet.Non-compliant code :

DontCallVirtualMethodsInConstructorRule_Test
{
DontCallVirtualMethodsInConstructorRule_Test()
{
A();
}
public virtual void A() { }
}


Compliant code :

class DontCallVirtualMethodsInConstructorRule_Test
{
DontCallVirtualMethodsInConstructorRule_Test()
{
var test = new DontCallVirtualMethodsInConstructorRule_Test();
test.A();
}
public virtual void A() { }
}
DateTimeNowUsageRuleStoring date/time values in UTC makes the data transportable, as the data is no longer tied to a particular time zone. To get the current date and time in UTC, it is recommended to use DateTime.UtcNow instead of DateTime.NowNon-compliant code:
void Main1(string[] args)
{
var dateTime = DateTime.Now;
}


Compliant code:
void Main1(string[] args)
{
var dateTime = DateTime.UtcNow;
}
DoNotReturnNullFromMethodRuleA method returning values representing strings or collections or task should never be null. The consumer of the APIs returning NULL would break if not handled.Non-compliant code :

public IEnumerable GetProductIds(int brandId)
{
var products = productService.GetProductsForBrand(brandId);
if (products == null || !products.Any())
{
return null;
}
return products.Select(p => p.Id);
}

Compliant code :

public IEnumerable GetProductIds(int brandId)
{
var products = productService.GetProductsForBrand(brandId);

if (products == null)
{
return Enumerable.Empty();
}

return products.Select(p => p.Id);
}
UseArrayEmptyAPIRuleWhile initializing an array, avoid using 'new T[0]'. Instead use 'Array.Empty' & '()' to avoid unnecessary allocation.Non-compliant code :

public void UseEmptyArrayForInit_Test()
{
var variable1 = new int[0];
}


Compliant code :

public void UseEmptyArrayForInit_Test()
{
var variable1 = Array.Empty();
}
MakeMethodStaticRuleIf a method is not referencing any instance variable and if you are not creating a virtual/abstract/new or partial method and if it is not a method override, your instance method may be changed to a static method. Therefore we recommend declaring the method as static.Non-compliant code:
public void Foo()
{
Console.WriteLine("A::Foo()");
}


Compliant code:
public static void Foo()
{
Console.WriteLine("A::Foo()");
}
ClassImplementsICloneableCheckRuleICloneable does not define which kind of cloning is done - deep or shallow copies. Therefore we recommend defining your Clone() or Copy() methods and document whether they perform deep or shallow copying instead of using ICloneable interface.Non-compliant code
public class Person : ICloneable
{
public int Age;
public string Name;
public Person(int age, string name)
{
Age = age;
Name = name;
}
public string ToString()
{
return "(" + age + "," + name + ")";
}
public virtual object Cloning()
{
return new Person(age, name);
}
object ICloneable.Clone()
{
return Cloning();
}
}


Compliant code :

public class IdInfo
{
public int IdNumber;
public IdInfo(int IdNumber)
{
this.IdNumber = IdNumber;
}
}
public class Person
{
public int Age;
public string Name;
public IdInfo IdInfo;
public Person ShallowCopy()
{
return (Person) this.MemberwiseClone();
}
public Person DeepCopy()
{
Person other = (Person) this.MemberwiseClone();
other.IdInfo = new IdInfo(IdInfo.IdNumber);
other.Name = String.Copy(Name);
return other;
}
}
public class Example
{
public static void Main()
{
Person p1 = new Person();
p1.Age = 35;
p1.Name = "John";
p1.IdInfo = new IdInfo(10076);
Person p2 = p1.ShallowCopy();
Console.WriteLine("Original values of p1 and p2:");
Console.WriteLine("p1 instance values:");
DisplayValues(p1);
}
public static void DisplayValues(Person p)
{
Console.WriteLine("Name: {0:s}, Age: {1:d}", p.Name, p.Age);
Console.WriteLine("Value: {0:d}", p.IdInfo.IdNumber);
}
}
SwitchWithoutDefaultRuleThe switch statement should include a default clause.Non-compliant code :

switch (value)
{
case 1:
Console.WriteLine(1);
break;
case 2:
Console.WriteLine(2);
break;
}


Compliant code :

switch (value)
{
case 1:
Console.WriteLine(1);
break;
case 2:
Console.WriteLine(2);
break;
default:
Console.WriteLine(0);
break;
}
DoNotHideInheritedMembersRuleOn hiding an inherited member using the "new" modifier, the derived version of the member replaces the base version.Non-compliant code :

BaseClass
{
public string BaseMethod()
{
return "is Base";
}
}
class Derviedclass : BaseClass
{
//Hides inherited member
public new string BaseMethod()
{
return "is Derived";
}
}


Compliant code variant 1:

class BaseClass
{
public virtual string BaseMethod()
{
return "is Base";
}
}
class Derviedclass : BaseClass
{
public override string BaseMethod()
{
return "is Derived";
}
}


Compliant code variant 2:

class BaseClass
{
public string BaseMethod()
{
return "is Base";
}
}
class Derviedclass : BaseClass
{
public string DerivedMethod()
{
return "is Derived";
}
}
UsingContextWhileThrowingExceptionRuleWhile throwing an exception, add contextual information that can be used for constructing an appropriate error message. The rule ensures using context-aware constructors in throw statements.Non-compliant code :

try
{
// do something
}
catch (Exception ex)
{
// do something
throw;
}


Compliant code :

``` try { // do something } catch (Exception ex) { // do something throw new Exception ("Put more context here", ex) }
UsingInnerExceptionInNewExceptionThrownRuleCatch block could throw another exception that would be more meaningful for the clients. When throwing a new exception from the catch clause, always pass caught exception as an innerException parameter for the new exception.Non-compliant code :

public void Test()
{
try
{
//some code here
}
catch (Exception ex)
{
throw new CustomException("");
}
}


Compliant code :

public void Test()
{
try
{
//some code here
}
catch (Exception ex)
{
throw new CustomException("", ex);
}
}
DisposableFieldNotDisposedRuleThe class having disposable field should call the dispose method of the field.Non-compliant code :

public class TypeA : IDisposable
{
protected virtual void Dispose(bool disposing)
{
if (disposing)
{
// Dispose managed resources
}
}
// Disposable types implement a finalizer.
}
public class TypeB : IDisposable
{
// Assume this type has some unmanaged resources.
TypeA aFieldOfADisposableType = new TypeA();
private bool disposed = false;
protected virtual void Dispose(bool disposing)
{
if (!disposed)
{
disposed = true;
if (disposing)
{
GC.SuppressFinalize(this);
}
}
}
// Disposable types implement a finalizer.
}


Compliant code :

protected virtual void Dispose(bool disposing)
{
if (!disposed)
{
// Dispose of resources held by this instance.
aFieldOfADisposableType.Dispose();
disposed = true;
// Suppress finalization of this disposed instance.
if (disposing)
{
GC.SuppressFinalize(this);
}
}
}
DisposablesShouldCallSuppressFinalizeRuleClasses implementing IDisposable should call the GC.SuppressFinalize method in their finalize method to avoid any finalizer from being called. This rule should be followed even if the class does not have a finalizer as a derived class could have one.Non-compliant code :

public class MyType : System.IDisposable
{
void IDisposable.Dispose()
{
Dispose(true);
}
protected virtual void Dispose(bool disposing)
{
}
}


Compliant code :
``` public class MyType : System.IDisposable { void IDisposable.Dispose() { Dispose(true); System.GC.SuppressFinalize(this); } protected virtual void Dispose(bool disposing) { } }
ClassMustBeSealedRuleA class should be marked as sealed class if there is no inheritor from the class.Non-compliant code :

class Calculations
{
public int Add(int a, int b)
{
return a + b;
}
}
class Program
{
static void Main(string[] args)
{
Calculations calc = new Calculations();
int total = calc.Add(6, 4);
Console.WriteLine("Total = " + total.ToString());
}
}

Compliant code :

sealed class Calculations
{
public int Add(int a, int b)
{
return a + b;
}
}
class Program
{
static void Main(string[] args)
{
Calculations calc = new Calculations();
int total = calc.Add(6, 4);
Console.WriteLine("Total = " + total.ToString());
}
}
Yes No

Embold CLI

The Embold CLI, analyses modified files or a complete repository.
It also generates a report containing code issues, design issues, and metrics.

Yes No

Prerequisites

  • A valid Embold account is required. Contact the administrator to create an account.
  • Git version (recommended version 2.18.0) should be installed.
  • The project to be analysed should be a git repository.
  • NodeJS (version 10.21) For JavaScript/Typescript repository analysis.
  • Install CORONA through the installer. Verify if CORONA_HOME environment variable is set.
Yes No

Configuration

  1. Edit the file $CORONA_HOME/coronacli/config/cli.properties to add username, password and server address. Contact the administrator to get the username and password.
    Example :gamma.username= example@embold.io
    gamma.password=password123 *
    gamma.url= https://embold.io/
  2. $CORONA_HOMEtoolsbin should be added in PATH environment variable.
Yes No

Embold CLI Commands

Syntax:
gamma-analyse [options]

Options:
The Embold CLI provides multiple options like:

  1. – f : Analyses all the files in the current directory.
  2. – l : Specifies the language used while filtering the files during analysis.(Mandatory)
    Languages supported are: Java, CPP, C_Sharp, Python, Javascript, Typescript, Go, Objective_C, Kotlin, PHP, Solidity and SQL.
  3. – o : By default, generates the output on the console. Other options are CSV and XML.
  4. – h : Displays the usage.

Usages of Embold CLI:
Following are different usages of the Embold CLI:

  1. gamma-analyse -l Java: Analyses all the staged, unstaged and the untracked Java files in the current directory and the output is displayed on the console.
  2. gamma-analyse -f -l CPP: Analyses all the CPP files in the current directory and the output is displayed on the console.
  3. . gamma-analyse -o -l Python: Analyses all the modified Python files in the current directory and by default displays the output on the console.
  4. gamma-analyse -o CSV -l Python: Analyse all the modified Python files in the current directory and generates the output in CSV file. This file is by default saved in the base directory.
  5. gamma-analyse -o XML -f -l CPP: Analyses all the modified CPP files in the current directory and generates output in XML file. This file is by default saved in the base directory.
  6. gamma-analyse -o CSV -f -l PHP: Analyses all the modified PHP files in the current directory and generates the output in CSV format.
Yes No

Modules

Embold supports below modules:

Module NameModule TypeLanguageAvailabilityPre-requisites
PMDcodeissues Java On-premise / Cloud-
SpotbugscodeissuesJava On-premise / CloudUser should generate Spotbugs report (xmls) before analysis
FindsecbugscodeissuesJava On-premise / CloudUser should generate Findsecbugs report ( xmls) before analysis
Sonar codeissuesJava On-premiseSonar should be setup and configured
Clover coverageJavaOn-premiseUser should generate clover report (xmls) before analysis
Junit unittestJavaOn-premiseUser should generate junit report (xmls) before analysis
cppcheckcodeissuesCppOn-premise / Cloud-
gamma_cxxcodeissuesCpp On-premise / Cloud-
Gcov coverageCppOn-premiseUser should generate gcov report (xmls) before analysis
GtestunittestCppOn-premiseUser should generate gtest report ( xmls) before analysis
Gamma_cs codeissuesCSharp On-premise / Cloud-
JshintcodeissuesJavascriptOn-premise / Cloud-
EslintcodeissuesJavascriptOn-premise / Cloud-
TslintcodeissuesTypescriptOn-premise / Cloud-
Pylint
codeissuesPython On-premise / Cloud-
GometalintercodeissuesGoOn-premise / Cloud-
Phpcs
codeissuesPHPOn-premise / Cloud-
PhpmdcodeissuesPHPOn-premise / Cloud-
SqlcheckcodeissuesSQLOn-premise / Cloud-
Gamma_JavacodeissuesJavaOn-premise / Cloud-
Yes No
Suggest Edit