The capture Section

Coverity on Polaris captures files for analysis using the following techniques:

For each version of Coverity, Coverity on Polaris Supported Platforms, Languages, and Compilers (under Compatibility and Support Information) shows types of capture available for each supported language.

Build Capture

Build capture means that Coverity on Polaris observes your project as it is built, determining which source files need analysis. A build capture requires the build and clean commands.

Syntax

capture:
  build:
    cleanCommands:
    - shell: [clean-command-component1, clean-command-component2, clean-command-component3...]
    buildCommands:
    - shell: [build-command-component1, build-command-component2, build-command-component3...]
    coverity:
      cov-build: 
       - "<--option1>"
       - "<value1>"
       - "<--option2>"[--option1, --option2]
      skipFiles:
       - "@File1"
       - "File2"
      cov-configure: 
        - "<--option1>"
        - "<value1>"
        - "<--option2>"

Example for Build Capture

capture: 
  build: 
    cleanCommands: 
    - shell: [mvn, -B, -f, pom.xml, clean] 
    buildCommands: 
    - shell: [mvn, -B, -f, pom.xml, install] 
    coverity: 
      cov-build: [--disable-aspnetcompiler] 
      skipFiles: 
      - "@File1.java" 
      - "File2.java"
      cov-configure: [--xml-option=prepend_arg@Go:--suppress_emit=value]

Examples for buildCommand and cleanCommand by language

Build Capture-C/C++

For a C or C++ application with a Makefile, make clean is a typical clean command, and make is a typical build command.

capture:
  build:
    cleanCommands:
    - shell: [make, -f, Makefile, clean]
    buildCommands:
    - shell: [make, -f, Makefile]

With this configuration, Coverity on Polaris cleans your project by running make -f Makefile clean, then builds it using make -f Makefile.

Build Capture-C#

Note: If MSbuild.exe is not in the PATH, then its full location must be provided.

capture:
  build:
    cleanCommands:
    - shell: [msbuild, NameOfYourProject.csproj, '/t:Clean']
    buildCommands:
    - shell: [msbuild, NameOfYourProject.csproj, '/t:Build']

Build Capture-Gradle

capture:
  build:
    cleanCommands:
    - shell: [gradle, -b, build.gradle, --no-daemon, clean]
    buildCommands:
    - shell: [gradle, -b, build.gradle, --no-daemon, build]

Build Capture-Java/Maven Project

capture:
   build:
     cleanCommands:
     - shell: [mvn, -B, -f, pom.xml, clean]
     buildCommands:
     - shell: [mvn, -B, -f, pom.xml, install]

Build Capture-Ant

capture:
  build:
    cleanCommands:
    - shell: [ant, -f, build.xml, clean]
    buildCommands:
    - shell: [ant, -f, build.xml]

Build Capture-Swift

capture:
  build:
    cleanCommands:
    - shell: [xcodebuild, -project, CryptoSwift.xcodeproj, clean]
    buildCommands:
    - shell: [xcodebuild, -project, CryptoSwift.xcodeproj, build]

Example for passing options to cov-build

capture:
  build:
    coverity:
      cov-build: ["--cached-jars-file", "/tzy/swip-openapi-lib.d2gsjf8w.metadata"]

Examples for skipFiles

skipFiles with Perl regex argument

You can exclude files and directories from a build capture by using the skipFiles property and a Perl regex argument. Coverity on Polaris CLI uses this regex to generate a new compiler configuration, which will be used with cov-build for capture. Coverity does not compile the files or directories that match the regex argument.

capture:
  build:
    cleanCommands:
    - shell: [mvn, -f, pom.xml, clean]
    buildCommands:
    - shell: [mvn, -f, pom.xml, install] 
    coverity: 
      skipFiles: ["regex1", "@java:regex2"]   

The match is partial: use ^ and $ to match boundaries.

The [@language] option specifies that the switch is to be added for compiler variants within the given language. Valid values are:

• C
• C++
• Java
• CS
• ObjC
• ObjC++

The skipFiles settings in the preceding example include a search in Java files, using "regex2" as a regular expression; the search for "regex1" is not limited by the language contained in the files.

skipFiles with no cov-build

capture:
  build:
    buildCommands: []
    cleanCommands: []
    coverity:
      cov-build: null
      skipFiles:
      - "<file1>"
      - "<file2>"

skipFiles macOS/Linux example

capture:
  build:
    coverity:
      skipFiles:
      - "@java:AbstractLessonTest.java"
      - "LabelDebuggerTest.java"
      - "@java:/webgoat-container/src/test/java/org/owasp/webgoat/plugins/PluginTe[a-zA-z]*.java"
      - "/webgoat-container/src/test/java/org/owasp/webgoat/util/LabelManager[a-zA-z]*Test.java"

Example for skipping Go files using cov-configure

In the example, the cov-configure command skips GO files.

capture:
  build:
    coverity:
      cov-build: [--disable-aspnetcompiler]
      skipFiles:
      - "@File1.java"
      - "File2.java"
      cov-configure: [--xml-option=prepend_arg@Go:--suppress_emit=value]

Filesystem Capture

Filesystem captures directly from the disk. It does not require observing a build command, and it allows control over the directories or file names to be included or excluded in analysis.

This is useful for source code is not compiled or explicitly built. For example, JavaScript and Python are both interpreted at run time. Software written in these languages is never "built," so build capture does not apply. Likewise, in other cases, compiled build artifacts, such as Java WAR or EAR files, can provide valuable information during analysis.

Syntax

capture: 
  fileSystem: 
    language: 
      extensions: [extension] 
      files: 
      - directory: /directory   

Examples

Generic Examples

capture:
  fileSystem:
     ears:
       extensions: [ear]
       files:
       - directory: ${project.projectDir}
     java:
       files:
       - directory: ${project.projectDir}
     javascript:
       files:
       - directory: "."
       - includeRegex: "han.*\\.js"
       - excludeRegex: ""
       extensions:
       - "js"
       - "xsjs"
       - "xsjslib"
       - "map"
       - "html"
       - "htm"
       - "vue"
       - "jsx"
    typescript:
      files:
      - directory: ${project.projectDir}    
    php:
      files:
     - directory: ${project.projectDir}
    python:
      files:
      - directory: ${project.projectDir}
    ruby:
      files:
      - directory: ${project.projectDir}
    wars:
      extensions: [war]
      files:
      - directory: ${project.projectDir}

Python and JavaScript Example

The following example configuration captures Python files in the pysrc subdirectory with the extension py.

In addition, JavaScript files with extension js in the subdirectory widget-main are captured with the exception of files that begin with mock.

capture:
  fileSystem:
    python:
      extensions: [py]
        files:
        - directory: pysrc
    javascript:
      extensions: [js]
        files:
        - directory: widget-main
          excludeRegex: '[/\\]mock.*[.]js$'        

Java Source Files Example

Filesystem capture for Java source files is a special case because you must remove the build section of the configuration file in addition to configuring the capture section.

The following is an example of setting up the capture section for Java filesystem capture.

capture:
  fileSystem:
     java:
       files:
       - directory: ${project.projectDir}

idir Capture

If you already have a valid idir directory (you've analyzed the project with Coverity previously) and don't want to wait to capture source files again, you can use idirCapture. Coverity on Polaris CLI checks the idir for compatibility with your current version of Coverity.

Syntax

capture:
  coverity:
    idirCapture: 
      idirPath: "/path/to/existing/idir"

Buildless Capture

Buildless capture works by recursively searching for:

• Project files under a specific project directory (Project Mode).
• Source files based on the file extension (Source Mode). Searches for known source files where the language is determined by filename extension.

Only one mode can be specified for buildless capture; the options are project and source. Specifying more than one mode results in an error message.

The Supported Platforms, Languages, and Compilers (under Compatibility and Support Information) show the languages supported for buildless capture. You can specify the languages you want to capture and you can exclude specific build files as needed.

Syntax

capture:
  coverity:
    buildless:
      project:
        languages:
        - "java"
        - "javascript"
      sourceMode:
        sourceDirOptions:
        - "<--option1>"
        - "<value1>"
        - "<--option2>"
        - "<value2>"
        sourceDir: "source/directory/path/"

Examples

In the following example, only Java and JavaScript files are captured. Files associated with build.gradle are excluded.

capture:
   coverity:
     buildless:
        project:
           languages:
            - "java"
            - "javascript"
            excludes:
            - build.gradle

This example shows TypeScript captured in Project Mode.

capture:
  build:
    cleanCommands:
    - shell: [mvn, -B, -f, pom.xml, clean]
    buildCommands:
    - shell: [mvn, -B, -f, pom.xml, install]
  coverity:
    buildless:
       project:
          languages:
           - "typescript"
analyze:
  mode: central
install:
  coverity:
    version: 
serverUrl: https://qa.dev.cop.blackduck.com/        

The following example shows how to set up buildless capture with source mode .

capture:
  coverity:
    buildless:
      sourceMode:
         sourceDirOptions:
         - "--language"
         - "java"
         sourceDir:"source/direcotry/path/ 

Auto-Capture

The auto-capture option should be placed in the polaris.yml file, under the Coverity capture settings as shown below.

Syntax

capture:
  coverity:
    autoCapture: enable | disable

Coverity Dynamic Analysis for web app security

The cov-security-da command runs a dynamic analysis of Java and .NET bytecode and a separate dynamic analysis of JavaScript templates. The Java/.NET analysis invokes certain string-manipulation functions to detect whether they correctly escape or sanitize unsafe values. The JavaScript template analysis dynamically renders observed template files to detect interpolation sites that could be vulnerable to XSS.

Syntax

capture:
  coverity:
    cov-security-da: "enable" | "disable"