Post Installation Server Configuration

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

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.

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>
}

C++ Configuration

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

C++ Strict Mode

In strict mode, CXXParser uses 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.

Compilation database

Introduction

A compilation database is a JSON file (compile_commands.json is the default name), which consists of an array of command objects. Each command object consists of:

  • A compilation database is a JSON file (compile_commands.json is the default name), which consists of an array of command objects. Each command object consists of:
    • Directory: The working directory of the compilation. All paths specified in the command or file fields must be either absolute or relative to this directory.
    • File: Source file to be compiled.
    • Command: The compile command executed.
  • Example:

Compilation database generation

  • Using CMake (version 3.5 and above):
  1. For projects that use CMake, passing -DCMAKE_EXPORT_COMPILE_COMMANDS=ON to cmake command generates the compile_commands.json file into the current directory.
    Note: This option is implemented only by Makefile Generators and the Ninja. It is ignored by other generators.
    Example:
    $ cd path/to/source/directory
    $ cmake [options] -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Using intercept-build:

  1. Introduction: Intercept-build uses two modes to generate the compilation database:
    1. Use a special library to intercept compiler calls during the build process.
    2. Use compiler wrappers to intercept compiler calls during the build process.
      The 1st mode is available only on FreeBSD, Linux and OSX. Where library preload is available from the dynamic loader. Security extension/modes on different operating systems might disable library preload. In this case, the build behaves normally, but the result compilation database will be empty. (Notable examples for enabled security modes are: SIP on OS X Captain and SELinux on Fedora, RHEL and CentOS.) The program checks the security modes for SIP and falls back to the next mode.
      Note: Refer the troubleshooting section below to solve the problem above.
      The 2nd mode works only if the build process respects the CC and CXX environment variables. (Some build process can override these variables as command line parameter only. This case you need to pass the compiler wrappers manually. e.g.: intercept-build –override-compiler make CC=intercept-cc CXX=intercept-c++ all where the original build command would have been make all only.) This is the default behavior, which can be enforced with the –override-compiler lag.
  2. Portability: Intercept-build should be quite portable on UNIX operating systems. It has been tested on FreeBSD, GNU/Linux and OS X.
  3. Prerequisites: python interpreter (version 2.7, 3.3, 3.4, 3.5)
  4. Location: The intercept-build tool is packaged along with the distribution archive (corona).
  5. Steps to generate a compilation database:
    1. Unzip the distribution zip which contains the intercept-build tool at this location – corona/cxxparser/trace-utility/bin
    2. Prepend intercept-build to build command:
      $ cd path/to/source/directory
      $ corona/cxxparser/trace-utility/bin/intercept-build
    3. Examples:
      $ cd path/to/source/directory
      $ make clean
      $ intercept-build make
      $ cd path/to/source/directory
      $ scons –c
      $ intercept-build scons
      $ cd path/to/source/directory
      $ gmake clean
      $ intercept-build gmake
  6. Examples of using custom compiler:
    When build system uses CC variable and it is defined as environment variable
    $ intercept-build --use-cc=""pathtocompilerexecutable"" make
    When build system uses CC variable and it is defined as command line parameter (inside build script)
    $ intercept-build --use-cc=""pathtocompilerexecutable"" make CC=intercept-cc
    When build system uses e.g.: MP_CC (other than CC) variable and its defined as command line parameter (inside build script)
    $ intercept-build --use-cc=""pathtocompilerexecutable"" make MP_CC=intercept-cc
    The output file called compile_commands.json will be found in the current directory.
  7. Common issues
    1. Problems caused by environment overriding: Because intercept-build uses LD_PRELOAD or DYLD_INSERT_LIBRARIES environment variables, it does not append to it, but overrides it. So, builds that are using these variables might not work.
    2. Troubleshooting: To overcome the empty compilation database problem on Fedora, CentOS and RHEL you should disable SELinux.
      To disable SELinux, follow the procedure below:
      1. Configure SELINUX=disabled in the /etc/selinux/config file:
      2. Reboot your system. After reboot, confirm that the get enforce command returns Disabled.
      3. Run intercept build.
  8. Using WAF: WAF is a Python-based framework for configuring, compiling and installing applications. WAF build system has inbuilt support for generating a compilation database.
    Add an option under ‘configure’ step in top-level wscript file as shown in image attached.
    Also, WAF is module-based, so clang_compilation_database.py module should be present in the lib folder.
    Location of lib folder should look like the following:
    [project-top-level-directory] /waflib/extras/
    compile_commands.json should be generated after a successful build.

Generating compilation database for Visual Studio projects

VSProjectParser is a utility to generate compilation database from Visual Studio Solution or Project files.

Location: This utility is kept under corona/cxxparser/bin

Portability:  Should be working on Windows operating systems and tested on Windows 7 and 10.

Prerequisites:

  1. Visual C++ Redistributable for Visual Studio 2015 https://www.microsoft.com/en-us/download/details.aspx?id=48145.
  2. Microsoft Build Tools 2015 https://www.microsoft.com/en-us/download/details.aspx?id=48159.
Note:
1. The above prerequisites are installed as part of Visual Studio 2015 installation.
2. If VS 2015 is not installed, then these can be installed as standalone tools via mentioned link.

How to use:To generate a CDB from solution or project file goes like this:
$ VSProjectParser.exe

To generate a CDB from folder containing solution or project file goes like this:
$VSProjectParser.exe

Generated CDB can be used to run strict mode analysis. For more details refer to this link.

Limitations: The `VSProjectParser` tool supports solution and project files for Visual Studio 2010 onwards.Hence only newer extensions .sln and .vcxproj are supported.

Known problems: As this tool skips missing project imports the generated CDB may not capture complete compile commands.

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. Follow the steps to set up remote scan
  2. 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.
  3. In “settings” section, under “additionalOptions” set the directory where compilation database resides.
    Example: –cdb=
  4. If the scan is successful you should see “ANALYSIS SUCCESS”. On your build machine, the last two log messages indicate that the remote analysis was successful.
  5. On your remote Embold instance, you will be able to see published results.

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.

Improving accuracy in fuzzy mode

Steps to navigate to Scan Configuration Option:

  1. Click on Projects option on the left side navigation pane.
  2. Inside your project, click on a repository and then click on three dots “” on the top right corner. Select the Scan configuration option.

Scan Configuration window consists of:

  1. Exclusion
  2. Additional Options
  3. Inclusion
  4. Includes

Exclusion:

We can exclude particular source files by providing regular expressions. 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 >> exclusion

Additional Options:

  • 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, the 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 the following option
—include-all=OFF

semi-colon list of regular expressions should be added in Scan Configuration pop-up window >> Additional Options
  • 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=””

Inclusion

  • comma-separated list of regular expressions should be added in Scan Configuration pop-up window >> inclusion

Includes

  • Look for Includes label and upload zip of include files.
  • Click Save.

Additional parser options

  • Exclusion filters

We can exclude particular source files by providing regular expressions. 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

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.

Embold setup without CI Integration (Default setup)

Introduction

Default BrowserStack Code Quality 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, BrowserStack Code Quality Server Host includes 2 components:

  1. BrowserStack Code Quality Server Web App and Services: This hosts the BrowserStack Code Quality Web App which is accessible from the browser and backend web services (used internally by BrowserStack Code Quality).
  2. BrowserStack Code Quality scanner (Remote Scan): This is the analyser component that scans the code, runs the actual code analysis and publishes results to the Postgres DB.

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.

Prerequisites

  • 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.
  • Create a subsystem on Embold UI to be analyzed.

To know more information about remote scans, check this out here.

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.

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”

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.

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)

Prerequisites

  • Remote Analysis should work from GitLab machine (where GitLab runner is running) to Embold machine. (Refer Remote Scan for more info).

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)

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.

Prerequisites

  • Jenkins version 2.289+.
  • Remote Scan should work from Jenkins machine (where build is happening) to Embold machine.
  • Download Embold scanner from your Embold Customer Portal > Releases tab > CLI. There will be one file with names similar to the following: ‘browserstack-codequality-scanner.tar.gz’.
  • 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

Installation Steps

Embold integration in Jenkins can be done using 2 approaches:

  1. Using Embold plugin (Check limitations) or
  2. Using Embold CLI / Remote scan

Jenkins Plugin

Limitation in Jenkins Embold plugin:

  1. It is not supported in pipeline jobs.
  2. Embold scanner packages will not update automatically, you need to replace the new Embold scanner folder for every new release.

Installation steps

  1. Untar embold-scanner-1.0.0-archive.tar.gz to some location on Jenkins master/slave.
  2. Add the environment variables CORONA_HOME, CORONA_LOG,EMBOLD_SCANNER_HOME .
    1. CORONA_HOME: Specify the location where Embold packages will be downloaded (e.g /opt/gamma/corona).
    2. CORONA_LOG: Specify the location where logs for Embold Analysis will be generated.
      Note: The directory should have write permissions.
  3. Download Jenkins plugin 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-Plugin-1.9.17.0.hpi.
  4. Click on “Manage Jenkins” on Jenkins’s home page.
  5. Jump to the Advanced tab.
  6. Go to the Upload Plugin section and upload “Embold-Jenkins-Plugin-1.9.17.0.hpi”.Click the “Upload” button.
  7. After Embold Jenkins Plugin is updated, Jenkins needs to be restarted.

Using CLI

Installation using Embold CLI / Remote scan

  1. Download the embold-scanner binaries from Embold control panel.
  2. Put the binaries in some directory where Jenkins user can access them (Make sure that the Jenkins user has read-write-execute permission).
  3. Select Execute shell / Execute Windows batch command depending on OS where your job is running. (For pipeline jobs you can add following command in pipeline steps after build steps )
  4. Add a following command in ‘Command’ section
    1. For Windows, run the below command:
      <Embold scanner path>/embold-scanner.bat -c <repository configuration path>/repository-configuration.json -u <Embold server URL> -t <Embold token> -sh <unique path where scanner packages will be downloaded> -r <Embold repository UID> -l <custom log directory>
    2. For Linux, run the below command:
      <Embold scanner path>/embold-scanner -c <repository configuration path>/repository-configuration.json -u <Embold server URL> -t <Embold token> -sh <unique path where scanner packages will be downloaded> -r <Embold repository UID> -l <custom log directory>

      For E.g.
      /var/jenkins_home/embold-scanner-1.0.0/bin/embold-scanner -c ./repository-configuration.json -u http://192.168.2.38:3001/ -t eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTYyODA2NTAxOTcyMSwiaWF0IjoxNjI4MDY1MDE5fQ.RehuKmSsWu7BaRvNgKGBMreOsy4d1GHXju53ujAr5QQLqqOOG48_sf7l4L_9aHcq40_hSWSiMR2coR4kXTJutPQ -sh ./embold -r 75b058cd126d1316af094632dfc47b01 -l ./logs
Note:
Make sure your Embold scanner package path (argument for -sh) is unique for each job

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.

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. Go to Post Steps and from Add post-build step dropdown list, select “
    Embold 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 Embold Jenkins Plugin.
  2. You should see the Embold Jenkins configuration page.
  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 Analysis Configuration file for Embold Jenkins Pugin for both modes

  • Use Analysis configuration from Embold:
  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 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 repository-configuration.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 the new environment variables CORONA_HOMECORONA_LOG and EMBOLD_SCANNER_HOME.

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. Add the environment variables CORONA_HOMECORONA_LOG and EMBOLD_SCANNER_HOME.
    1. CORONA_HOME : Specify the location where Embold Analyzer will be downloaded (e.g /opt/gamma/corona).
    2. CORONA_LOG : Specify the location where logs for Embold Analysis will be generated. Note: The directory should have write permissions.
    3. EMBOLD_SCANNER_HOME: Specify the path till embold-scanner.

Embold Quality Gate

Below are the steps to show Embold 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.

Update Embold Jenkins Plugin

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

Sonar Integration

Prerequisites

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

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.

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 (;).

Mapping between SonarQube and Embold severity

SonarEmbold
Blocker


Critical
CriticalHigh
MajorMedium
MinorLow
InfoInfo

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.

 

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.

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, then click on the Test Connection button.
  7. On successful validation, the “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, env.GAMMA_DATA and env.EMBOLD_SCANNER_HOME. 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.
    3. env.EMBOLD_SCANNER_HOME: Specify the location for scanner home.
  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.

IDE Plugins

BrowserStack Code Quality 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 BrowserStack Code Quality IDE Plugin in their local eclipse/VS installation. The plugin requires sign-in with the BrowserStack Code Quality server deployed within the organization. It supports both windows and Linux OS.

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

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:  site.zip.
  2. Extract zip file at any location
    For e.g : /Users/admin/Embold/Site
  3. Go to “Help” -> “Install new software”
  4. Click on “Add” button
  5. Click on local button.
  6. Browse parent dir of extracted zip.
  7. Click on Add.
  8. Check the “Embold Eclipse Feature”
  9. Accept ‘Terms and conditions’
  10. Finish and Restart Eclipse
  11. Enable the Embold Analysis tool in the menu bar (After restarting Eclipse): Go to Window -> Preferences > Embold settings.
  12. Configuration setup and authentication process:
    1. Set Embold Home path and fill Embold credentials for authentication.
      Embold Home path should refer to the path where corona was installed.
      e.g. D:/GammaHome/corona/
    2. Contact the administrator to get Embold the URL.
    3. Enter the Embold Authentication Token.
    4. Validate the Embold credentials and click on ‘Apply and close’ button.
  13. After authentication, Go to Embold Settings > Scan Configuration option. Select language and modules to run (e.g. CPPCheck for CPP).
  14. Click on Embold analysis icon from the menu bar to run analysis.

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 -> Click on Embold 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 ruler icon on vertical bar in editor gives the metric details of respective component

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

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.vsixembold_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)

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. fter 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. Embold Access Token: This is a personnel access token to access Embold APIs authentically.
  4. 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.

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.

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.

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.

Embold CLI

Embold Analyse, analyses modified files or a complete repository.

It also generates a report containing code issues, anti-patterns, and metrics.

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.

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 : embold.username= example@embold.io
    embold.password=password123 *
    gamma.url= https://embold.io/
  2. $CORONA_HOMEtoolsbin should be added in PATH environment variable.

Embold CLI Commands

Syntax:
embold-analyse [options]

Options:
Embold Analyse 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. It is stored under this path: $CORONA_HOME/temp/Corona/EmboldIssues.csv
  4. – h : Displays the usage.

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

  1. embold-analyse -l Java: Analyses all the staged, unstaged, and untracked Java files in the current directory, and the output is displayed on the console.
  2. embold-analyse -f -l CPP: Analyses all the CPP files in the current directory and the output is displayed on the console.
  3. embold-analyse -o -l Python: Analyses all the modified Python files in the current directory and by default displays the output on the console.
  4. embold-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 $CORONA_HOME/temp/Corona/EmboldIssues.csv.
  5. embold-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 $CORONA_HOME/temp/Corona/EmboldIssues.csv.
  6. embold-analyse -o CSV -f -l PHP: Analyses all the modified PHP files in the current directory and generates the output in CSV format.

Modules

BrowserStack Code Quality 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-
Suggest Edit