Packaging Go Applications

Veracode Packaging Requirements

Your Go applications must meet specific compilation requirements before you can submit them for scanning.

See Supported Languages and Platforms for instructions for other platforms.

You can analyze applications using Veracode Static Analysis or Veracode Software Composition Analysis (SCA) upload and scan, if licensed. For SCA agent-based scan requirements, see Using Veracode SCA with Programming Languages.

Supported Go Versions

Language Version
Go 1.x

Supported Go Frameworks and Libraries

Framework/Library Notes
Gorilla Includes support for mux, handlers, HTTP, session, and additional Gorilla components

Packaging Guidance for Go

Veracode uses functionality in the standard Go compiler when analyzing applications, and requires that the application is packaged in a structure that can be compiled. Package the source directory for a single compilable Go executable as a compressed ZIP archive, and structure it using these rules:

  • The ZIP archive must contain a single directory.
  • The top-level directory must include a GO file that contains a main() call, in addition to any other Go source files that the main package uses.
  • Veracode uses the vendoring functionality in Go to manage third-party libraries. When building an application with Go 1.11 or later, you can use the -mod=vendor option, or run the go mod vendor command to create the vendor directory.
    • You must place any third-party libraries or other internal packages in a subdirectory named vendor. For example: vendor/github.com/my_org/my_application
    • Any dependencies that the application uses must be in the vendor subdirectory.

    For more information, see How do I use vendoring with modules?

    If the top-level directory contains a go.mod file, Veracode Static Analysis uses the module directive to detect the module path. For example, the mymod folder in your application might include a go.mod file that contains module github.com/user/mymod. You can import github.com/user/mymod/stringutil even if you archive only the mymod folder, instead of the entire path github.com/user/mymod.

    For more information, see the go.mod Wiki page.

  • The application must not include any cgo dependencies or build tags that restrict the application to running only on a specific operating system.
  • Any packages that the application uses that are specific to the application must be contained in a subdirectory inside the app directory.

This example shows the structure of the submitted source files:

|__ app/
       |-- main.go
       |-- [other *.go files in package main]
       |-- [go.mod if used]
       |__ applicationpkg1/
           |-- [application package 1 *.go files]
       |__ applicationpkg2/
           |-- [application package 2 *.go files]
       |__ vendor/ [first- and third-party dependencies go in this folder]

If using Veracode Software Composition Analysis, follow the requirements for your package manager:

Dep
Include gopkg.lock in the root of your ZIP archive.
Glide
Include glide.lock in the root of your ZIP archive.
Go modules
Include go.sum in the root of your ZIP archive. Veracode recommends using Veracode SCA with Go version 1.14 or later so that it can use the content of the vendor directory to exclude non-vendored dependencies from scan results.
Godep
Include godeps/godeps.lock in the root of your ZIP archive.
Govendor
Include vendor/vendor.json in the root of your ZIP archive.

Upload Requirements

  • An upload must only contain one Go module.
  • You must split a multi-module project into separate uploads.

Veracode does not support uploading a source repository that includes the source for multiple discrete Go executables or multiple modules.

Veracode cannot analyze a Go module or package without a main() function.

Configuration for Different Structures

If the application you want to analyze has a package structure that does not match the upload requirements, you can include a file that describes the structure of the application.

In the root of the directory that you compress to form the ZIP archive, include a JSON file named veracode.json, with these optional properties:

MainRoot
Describes the import path relative to the enclosing directory where the main package is located. For example, if the root folder is named project, and the main file is in project/cmd/main, then the value for this configuration field is cmd/main.
MainPkgName
Describes if the name of the package containing the main() function for the application is something other than main.
FirstParty
Describes an array of import paths for first-party code that is located in the vendor directory.

This example shows of the veracode.json configuration file:

{
    "MainRoot": "cmd/app1",
    "MainPkgName": "app1",
    "FirstParty": [
        "github.company.com"
    ]
}

This example shows the application structure that uses a configuration file:

  |__ app/
  |-- veracode.json [configuration file describing the structure]
  |__ cmd/
     |__ app1
        |-- main.go
   |__ vendor/ [first- and third-party dependencies go in this folder]
      |__ golang.org/
      |__ gopkg.in/
      |__ github.com/
         |__ my_company/
            |__ firstpartypkg1/
            |__ firstpartypkg2/
         |__ 3rdparty
    

Details and Troubleshooting

Veracode uses the Go compiler to generate syntax trees to analyze the applications. The submitted archive is unzipped to an empty workspace directory. The $GOPATH environment variable is set to this workspace. Each directory in this workspace is scanned for a GO file containing a main() function, to identify the main package to compile the application.

You can validate that the application compiles by running the go build command after unzipping the file into a blank directory, or by running the go vet command on it to identify any issues with the structure of the directory and package layout. If the application is unable to compile after being unzipped into a blank directory, Veracode cannot analyze the application.

To better understand the use of the vendor folder, review the Go documentation.

If your application includes vendor dependencies that contain code in languages other than Go, you should remove them with this command:

find /<path>/app/vendor -type f -not -name '*.go' -delete

Veracode scans only GO files that have the GO extension.

When creating an archive of a Go application on macOS, the folder compression process creates hidden __MACOSX resource fork files that you must remove. To remove the hidden resource fork files:

  1. Run zipinfo my.zip on the Go application archive to view a list of its files.
  2. Review the list of files to verify that all resource fork files are removed.
  3. Remove resource fork files from an existing archive on macOS using this command: zip -d my.zip __MACOSX/*