ContextQMD
Back to Gitlabhq

Sec section analyzer development

doc/development/sec/analyzer_development_guide.md

18.11.254.3 KB
Original Source

Analyzers are shipped as Docker images to execute within a CI pipeline context. This guide describes development and testing practices across analyzers.

Shared modules

There are a number of shared Go modules shared across analyzers for common behavior and interfaces:

  • The command Go package implements a CLI interface.
  • The common project provides miscellaneous shared modules for logging, certificate handling, and directory search capabilities.
  • The report Go package's Report and Finding structs marshal JSON reports.
  • The template project scaffolds new analyzers.

How to use the analyzers

Analyzers are shipped as Docker images. For example, to run the Semgrep Docker image to scan the working directory:

  1. cd into the directory of the source code you want to scan.

  2. Run docker login registry.gitlab.com and provide username plus personal or project access token with at least the read_registry scope.

  3. Run the Docker image:

    shell
    docker run \
    --interactive --tty --rm \
    --volume "$PWD":/tmp/app \
    --env CI_PROJECT_DIR=/tmp/app \
    -w /tmp/app \
    registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep:latest /analyzer run

  4. The Docker container generates a report in the mounted project directory with a report filename corresponding to the analyzer category. For example, SAST generates a file named gl-sast-report.json.

Analyzers development

To update the analyzer:

  1. Modify the Go source code.
  2. Build a new Docker image.
  3. Run the analyzer against its test project.
  4. Compare the generated report with what's expected.

Here's how to create a Docker image named analyzer:

shell
docker build -t analyzer .

For example, to test secret detection run the following:

shell
wget https://gitlab.com/gitlab-org/security-products/ci-templates/-/raw/master/scripts/compare_reports.sh
sh ./compare_reports.sh sd test/fixtures/gl-secret-detection-report.json test/expect/gl-secret-detection-report.json \
| patch -Np1 test/expect/gl-secret-detection-report.json && Git commit -m 'Update expectation' test/expect/gl-secret-detection-report.json
rm compare_reports.sh

You can also compile the binary for your own environment and run it locally but analyze and run probably won't work since the runtime dependencies of the analyzer are missing.

Here's an example based on SpotBugs:

shell
go build -o analyzer
./analyzer search test/fixtures
./analyzer convert test/fixtures/app/spotbugsXml.Xml > ./gl-sast-report.json

Secure stage CI/CD Templates and components

The secure stage is responsible for maintaining the following CI/CD Templates and Components:

Changes must always be made to both the CI/CD template and component for your group, and you must also determine if the changes need to be applied to the latest CI/CD template.

Analyzers are also referenced in the Secure-Binaries.gitlab-ci.yml file for offline environments. Ensure this file is also kept in sync when doing changes.

Execution criteria

Enabling SAST requires including a pre-defined template to your GitLab CI/CD configuration.

The following independent criteria determine which analyzer needs to be run on a project:

  1. The SAST template uses rules:exists to determine which analyzer will be run based on the presence of certain files. For example, the Brakeman analyzer runs when there are .rb files and a Gemfile.
  2. Each analyzer runs a customizable match interface before it performs the actual analysis. For example: Flawfinder checks for C/C++ files.
  3. For some analyzers that run on generic file extensions, there is a check based on a CI/CD variable. For example: Kubernetes manifests are written in YAML, so Kubesec runs only when SCAN_KUBERNETES_MANIFESTS is set to true.

Step 1 helps prevent wastage of compute quota that would be spent running analyzers not suitable for the project. However, due to technical limitations, it cannot be used for large projects. Therefore, step 2 acts as final check to ensure a mismatched analyzer is able to exit early.

How to test the analyzers

Video walkthrough of how dependency scanning analyzers are using downstream pipeline feature to test analyzers using test projects:

<i class="fa-youtube-play" aria-hidden="true"></i> How Sec leverages the downstream pipeline feature of GitLab to test analyzers end to end

<!-- Video published on 2019-10-09 -->

Testing local changes

To test local changes in the shared modules (such as command or report) for an analyzer you can use the go mod replace directive to load command with your local changes instead of using the version of command that has been tagged remotely. For example:

shell
go mod edit -replace gitlab.com/gitlab-org/security-products/analyzers/command/v3=/local/path/to/command

Alternatively you can achieve the same result by manually updating the go.mod file:

plaintext
module gitlab.com/gitlab-org/security-products/analyzers/awesome-analyzer/v2

replace gitlab.com/gitlab-org/security-products/analyzers/command/v3 => /path/to/command

require (
    ...
    gitlab.com/gitlab-org/security-products/analyzers/command/v3 v2.19.0
)

Testing local changes in Docker

To use Docker with replace in the go.mod file:

  1. Copy the contents of command into the directory of the analyzer. cp -r /path/to/command path/to/analyzer/command.
  2. Add a copy statement in the analyzer's Dockerfile: COPY command /command.
  3. Update the replace statement to make sure it matches the destination of the COPY statement in the step above: replace gitlab.com/gitlab-org/security-products/analyzers/command/v3 => /command

Testing container orchestration compatibility

Users may use tools other than Docker to orchestrate their containers and run their analyzers, such as containerd, Podman, or skopeo. To ensure compatibility with these tools, we periodicically test all analyzers using a scheduled pipeline. A Slack alert is raised if a test fails.

To avoid compatibility issues when building analyzer Docker images, use the OCI media types instead of the default proprietary Docker media types.

In addition to the periodic test, we ensure compatibility for users of the ci-templates repo:

  1. Analyzers using the ci-templates docker-test.yml template include tests to ensure our Docker images function correctly with supported Docker tools.

    These tests are executed in Merge Request pipelines and scheduled pipelines, and prevent images from being released if they break the supported Docker tools.

  2. The ci-templates docker.yml template specifies oci-mediatypes=true for the docker buildx command when building analyzer images. This builds images using OCI media types rather than Docker proprietary media types.

When creating a new analyzer, or changing the location of existing analyzer images, add it to the periodic test, or consider using the shared ci-templates which includes an automated test.

Analyzer scripts

The analyzer-scripts repository contains scripts that can be used to interact with most analyzers. They enable you to build, run, and debug analyzers in a GitLab CI-like environment, and are particularly useful for locally validating changes to an analyzer.

For more information, refer to the project README.

Versioning and release process

GitLab Security Products use an independent versioning system from GitLab MAJOR.MINOR. All products use a variation of Semantic Versioning and are available as Docker images.

Major is bumped with every new major release of GitLab, when breaking changes are allowed. Minor is bumped for new functionality, and Patch is reserved for bugfixes.

The analyzers are released as Docker images following this scheme:

  • each push to the default branch will override the edge image tag
  • each push to any awesome-feature branch will generate a matching awesome-feature image tag
  • each Git tag will generate the corresponding Major.Minor.Patch image tag. A manual job allows to override the corresponding Major and the latest image tags to point to this Major.Minor.Patch.

In most circumstances it is preferred to rely on the MAJOR image, which is automatically kept up to date with the latest advisories or patches to our tools. Our included CI templates pin to major version but if preferred, users can override their version directly.

To release a new analyzer Docker image, there are two different options:

The following diagram describes the Docker tags that are created when a new analyzer version is released:

mermaid
graph LR

A1[git tag v1.1.0]--> B1(run CI pipeline)
B1 -->|build and tag patch| D1[1.1.0]
B1 -->|tag minor| E1[1.1]
B1 -->|retag major| F1[1]
B1 -->|retag latest| G1[latest]

A2[git tag v1.1.1]--> B2(run CI pipeline)
B2 -->|build and tag patch| D2[1.1.1]
B2 -->|retag minor| E2[1.1]
B2 -->|retag major| F2[1]
B2 -->|retag latest| G2[latest]

A3[push to default branch]--> B3(run CI pipeline)
B3 -->|build and tag edge| D3[edge]

Per our Continuous Deployment flow, for new components that do not have a counterpart in the GitLab Rails application, the component can be released at any time. Until the components are integrated with the existing application, iteration should not be blocked by our standard release cycle and process.

Manual release process

  1. Ensure that the CHANGELOG.md entry for the new analyzer is correct.
  2. Ensure that the release source (typically the master or main branch) has a passing pipeline.
  3. Create a new release for the analyzer project by selecting the Deployments menu on the left-hand side of the project window, then selecting the Releases sub-menu.
  4. Select New release to open the New Release page.
    1. In the Tag name drop down, enter the same version used in the CHANGELOG.md, for example v2.4.2, and select the option to create the tag (Create tag v2.4.2 here).
    2. In the Release title text box enter the same version used above, for example v2.4.2.
    3. In the Release notes text box, copy and paste the notes from the corresponding version in the CHANGELOG.md.
    4. Leave all other settings as the default values.
    5. Select Create release.

After following the above process and creating a new release, a new Git tag is created with the Tag name provided above. This triggers a new pipeline with the given tag version and a new analyzer Docker image is built.

If the analyzer uses the analyzer.yml template, then the pipeline triggered as part of the New release process above automatically tags and deploys a new version of the analyzer Docker image.

If the analyzer does not use the analyzer.yml template, you'll need to manually tag and deploy a new version of the analyzer Docker image:

  1. Select the CI/CD menu on the left-hand side of the project window, then select the Pipelines sub-menu.
  2. A new pipeline should currently be running with the same tag used previously, for example v2.4.2.
  3. After the pipeline has completed, it will be in a blocked state.
  4. Select the Manual job play button on the right hand side of the window and select tag version to tag and deploy a new version of the analyzer Docker image.

Use your best judgment to decide when to create a Git tag, which will then trigger the release job. If you can't decide, then ask for other's input.

Automatic release process

The following must be performed before the automatic release process can be used:

  1. Configure CREATE_GIT_TAG: true as a CI/CD environment variable.

  2. Check the Variables in the CI/CD project settings:

After the above steps have been completed, the automatic release process executes as follows:

  1. A project maintainer merges an MR into the default branch.
  2. The default pipeline is triggered, and the upsert git tag job is executed.
    • If the most recent version in the CHANGELOG.md matches one of the Git tags, the job is a no-op.
    • Else, this job automatically creates a new release and Git tag using the releases API. The version and message is obtained from the most recent entry in the CHANGELOG.md file for the project.
  3. A pipeline is automatically triggered for the new Git tag. This pipeline releases the latest, major, minor and patch Docker images of the analyzer.

Service account used in the automatic release process

KeyValue
Account name@gl-service-dev-secure-analyzers-automation
PurposeUsed for creating releases/tags
Member ofgitlab-org/security-products
Maximum roleDeveloper
Scope of the associated GITLAB_TOKENapi
Expiry date of GITLAB_TOKENDecember 3, 2025

[!warning] Any changes to the service account's access token scopes or the GITLAB_TOKEN variable permissions should be announced in the section's Slack channel.

Token rotation for service account

The GITLAB_TOKEN for the @gl-service-dev-secure-analyzers-automation service account must be rotated before the Expiry Date listed above by doing the following:

  1. Log in as the gl-service-dev-secure-analyzers-automation user.

    The list of administrators who have credentials for this account can be found in the service account access request.

    Administrators can find the login credentials in the shared GitLab 1password vault.

  2. Create a new Personal Access Token with api scope for the gl-service-dev-secure-analyzers-automation service account.

  3. Update the password field of the GitLab API Token - gl-service-dev-secure-analyzers-automation account in the shared GitLab 1password vault to the new Personal Access Token created in step 2 (above), and set the Expires at field to indicate when the token expires.

  4. Update the expiry date of the GITLAB_TOKEN field in the Service account used in the automatic release process table.

  5. Set the following variables to the new Personal Access Token created in step 2 above:

    [!note] It's crucial to mask and hide the following variables.

    1. GITLAB_TOKEN CI/CD variable for the gitlab-org/security-products/analyzers group.

      This allows all projects under the gitlab-org/security-products/analyzers namespace to inherit this GITLAB_TOKEN value.

    2. GITLAB_TOKEN CI/CD variable for the gitlab-org/security-products/ci-templates project.

      This must be explicitly configured because the ci-templates project is not nested under the gitlab-org/security-products/analyzers namespace, and therefore does not inherit the GITLAB_TOKEN value.

      The ci-templates project requires the GITLAB_TOKEN to allow certain scripts to execute API calls. This step can be removed after allow JOB-TOKEN access to CI/lint endpoint has been completed.

    3. GITLAB_TOKEN CI/CD variable for gitlab-org/security-products/license-db group.

      This must be explicitly configured because the license-db project is not nested under the gitlab-org/security-products/analyzers namespace, and therefore does not inherit the GITLAB_TOKEN value.

    4. SEC_REGISTRY_PASSWORD CI/CD variable for gitlab-advanced-sast.

      This allows our tagging script to pull from the private container registry in the development project registry.gitlab.com/gitlab-org/security-products/analyzers/<analyzer-name>/tmp, and push to the publicly accessible container registry registry.gitlab.com/security-products/<analyzer-name>.

Steps to perform after releasing an analyzer

  1. After a new version of the analyzer Docker image has been tagged and deployed, test it with the corresponding test project.

  2. Announce the release on the relevant group Slack channel. Example message:

    FYI I've just released ANALYZER_NAME ANALYZER_VERSION. LINK_TO_RELEASE

Never delete a Git tag that has been pushed as there is a good chance that the tag will be used and/or cached by the Go package registry.

Backporting a critical fix or patch

To backport a critical fix or patch to an earlier version, follow the steps below.

  1. Create a new branch from the tag you are backporting the fix to, if it doesn't exist.
    • For example, if the latest stable tag is v4 and you are backporting a fix to v3, create a new branch called v3.
  2. Submit a merge request targeting the branch you just created.
  3. After its approved, merge the merge request into the branch.
  4. Create a new tag for the branch.
  5. If the analyzer has the automatic release process enabled, a new version will be released.
  6. If not, you have to follow the manual release process to release a new version.
  7. NOTE: the release pipeline will override the latest edge tag so the most recent release pipeline's tag edge job may need to be re-ran to avoid a regression for that tag.

Preparing analyzers for a major version release

This process applies to the following groups:

Other groups are responsible for documenting their own major version release process.

Choose one of the following scenarios based on whether the major version release contains breaking changes:

  1. Major version release without breaking changes
  2. Major version release with breaking changes

Major version release without breaking changes

Assuming the current analyzer release is v{N}:

  1. Configure protected tags and branches.
  2. During the milestone of the major release, when there are no more changes to be merged into the default branch:

    1. Create a v{N} branch from the default branch.

    2. Create and merge a new Merge Request in the default branch containing only the following change to the CHANGELOG.md file:

      markdown
      ## v{N+1}.0.0
- Major version release (!<MR-ID>)

    3. Configure scheduled pipelines.

    4. Bump major analyzer versions in the CI/CD templates and components

Major version release with breaking changes

Assuming the current analyzer release is v{N}:

  1. Configure protected tags and branches.

  2. Create a new branch v{N+1} to "stage" breaking changes.

  3. In the milestones leading up to the major release milestone:

    • Merge non-breaking changes to the default branch (aka master or main)

    • Merge breaking changes to the v{N+1} branch, and create a separate release candidate entry in the CHANGELOG.md file for each change:

      markdown
      ## v{N+1}.0.0-rc.0
- some breaking change (!123)

      Using release candidates allows us to release all breaking changes in a single major version bump, which follows the semver guidance of only making breaking changes in a major version update.

  4. During the milestone of the major release, when there are no more changes to be merged into the default or v{N+1} branches:

    1. Create a v{N} branch from the default branch.

    2. Create a Merge Request in the v{N+1} branch to squash all the release candidate changelog entries into a single entry for v{N+1}.

      For example, if the CHANGELOG.md contains the following 3 release candidate entries for version v{N+1}:

      markdown
      ## v{N+1}.0.0-rc.2
- yet another breaking change (!125)

## v{N+1}.0.0-rc.1
- another breaking change (!124)

## v{N+1}.0.0-rc.0
- some breaking change (!123)

      Then the new Merge Request should update the CHANGELOG.md to have a single major release for v{N+1}, by combining all the release candidate entries into a single entry:

      markdown
      ## v{N+1}.0.0
- yet another breaking change (!125)
- another breaking change (!124)
- some breaking change (!123)

    3. Create a Merge Request to merge all the breaking changes from the v{N+1} branch into the default branch.

    4. Delete the v{N+1} branch, since it's no longer needed, as the default branch now contains all the changes from the v{N+1} branch.

    5. Configure scheduled pipelines.

    6. Bump major analyzer versions in the CI/CD templates and components.

Configure protected tags and branches

  1. Ensure the wildcard v* is set as both a Protected Tag and Protected Branch for the project.

  2. Verify the gl-service-dev-secure-analyzers-automation service account is Allowed to create protected tags.

    See step 3.1 of the Officially supported images section for more details.

Configure scheduled pipelines
  1. Ensure three scheduled pipelines exist, creating them if necessary, and set PUBLISH_IMAGES: true for all of them:

    • Republish images v{N} (against the v{N} branch)

      This scheduled pipeline needs to be created

    • Daily build (against the default branch)

      This scheduled pipeline should already exist

    • Republish images v{N-1} (against the v{N-1} branch)

      This scheduled pipeline should already exist

  2. Delete the scheduled pipeline for the v{N-2} branch (if it exists), since we only support two previous major versions.
Bump major analyzer versions in the CI/CD templates and components

When images for all the v{N+1} analyzers are available under registry.gitlab.com/security-products/<ANALYZER-NAME>:<TAG>, create a new merge request to bump the major version for each analyzer in the Secure stage CI/CD templates and components belonging to your group.

Development of new analyzers

We occasionally need to build out new analyzer projects to support new frameworks and tools. In doing so we should follow our engineering Open Source guidelines, including licensing and code standards.

In addition, to write a custom analyzer that will integrate into the GitLab application a minimal feature set is required:

Checklist

Verify whether the underlying tool has:

Dockerfile

The Dockerfile should use an unprivileged user with the name GitLab. This is necessary to provide compatibility with Red Hat OpenShift instances, which don't allow containers to run as an admin (root) user. There are certain limitations to keep in mind when running a container as an unprivileged user, such as the fact that any files that need to be written on the Docker filesystem will require the appropriate permissions for the GitLab user. See the following merge request for more details: Use GitLab user instead of root in Docker image.

Minimal vulnerability data

See our security-report-schemas for a full list of required fields.

The security-report-schema repository contains JSON schemas that list the required fields for each report type:

Compatibility with report schema

Security reports uploaded as artifacts to GitLab are validated before being ingested.

Security report schemas are versioned using SchemaVer: MODEL-REVISION-ADDITION. The Sec Section is responsible for the security-report-schemas project, including the compatibility of GitLab and the schema versions. Schema changes must follow the product-wide deprecation guidelines.

When a new MODEL version is introduced, analyzers that adopt the new schema are responsible for ensuring that GitLab deployments that do not vendor this new schema version continue to ingest security reports without errors or warnings.

This can be accomplished in different ways:

  1. Implement support for multiple schema versions in the analyzer. Based on the GitLab version, the analyzer emits a security report using the latest schema version supported by GitLab.
    • Pro: analyzer can decide at runtime what the best version to utilize is.
    • Con: implementation effort and increased complexity.
  2. Release a new analyzer major version. Instances that don't vendor the latest MODEL schema version continue to use an analyzer version that emits reports using version MODEL-1.
    • Pro: keeps analyzer code simple.
    • Con: extra analyzer version to maintain.
  3. Delay use of new schema. This relies on additionalProperties=true, which allows a report to include properties that are not present in the schema. A new analyzer major version would be released at the usual cadence.
    • Pro: no extra analyzer to maintain, keep analyzer code simple.
    • Con: increased risk and/or effort to mitigate the risk of not having the schema validated.

If you are unsure which path to follow, reach-out to the security-report-schemas maintainers.

Location of Container Images

Container images for secure analyzers are published in two places:

  • Officially supported images in the registry.gitlab.com/security-products namespace, for example:

    shell
    registry.gitlab.com/security-products/semgrep:5

  • Temporary development images in the project namespace, for example:

    shell
    registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep/tmp:d27d44a9b33cacff0c54870a40515ec5f2698475

Officially supported images

The location of officially supported images, as referenced by our secure templates is:

shell
registry.gitlab.com/security-products/<ANALYZER-NAME>:<TAG>

For example, the semgrep-sast job in the SAST.gitlab-ci.yml template references the container image registry.gitlab.com/security-products/semgrep:5.

In order to push images to this location:

  1. Create a new project in https://gitlab.com/security-products/<ANALYZER-NAME>.

    For example: https://gitlab.com/security-products/semgrep

    Images for this project will be published to registry.gitlab.com/security-products/<ANALYZER-NAME>:<TAG>.

    For example: registry.gitlab.com/security-products/semgrep:5

  2. Configure the project https://gitlab.com/security-products/<ANALYZER-NAME> as follows:

    1. Add the following permissions:

    2. Configure the following project settings:

      • Settings -> General -> Visibility, project features, permissions
        • Project visibility
          • Public
        • Additional options
          • Users can request access
            • Disabled
        • Issues
          • Disabled
        • Repository
          • Only Project Members
          • Merge Requests
            • Disabled
          • Forks
            • Disabled
          • Git Large File Storage (LFS)
            • Disabled
          • CI/CD
            • Disabled
        • Container Registry
          • Everyone with access
        • Analytics, Requirements, Security and compliance, Wiki, Snippets, Package registry, Model experiments, Model registry, Pages, Monitor, Environments, Feature flags, Infrastructure, Releases, GitLab Duo
          • Disabled

  3. Configure the following options for the analyzer project, located at https://gitlab.com/gitlab-org/security-products/analyzers/<ANALYZER_NAME>:

    1. Add the wildcard v* as a Protected Tag.

      Ensure the gl-service-dev-secure-analyzers-automation service account has been explicitly added to the list of accounts Allowed to create protected tags. This is required to allow the upsert git tag job to create new releases for the analyzer project.

    2. Add the wildcard v* as a Protected Branch.

    3. CI/CD environment variables

      [!note] It's crucial to mask and hide the SEC_REGISTRY_PASSWORD variable.

      KeyValue
      SEC_REGISTRY_IMAGEregistry.gitlab.com/security-products/$CI_PROJECT_NAME
      SEC_REGISTRY_USERgl-service-dev-secure-analyzers-automation
      SEC_REGISTRY_PASSWORDPersonal Access Token for gl-service-dev-secure-analyzers-automation user. Request an administrator to configure this token value.

      The above variables are used by the tag_image.sh script in the ci-templates project to push the container image to registry.gitlab.com/security-products/<ANALYZER-NAME>:<TAG>.

      See the semgrep CI/CD Variables for an example.

Temporary development images

The location of temporary development images is:

shell
registry.gitlab.com/gitlab-org/security-products/analyzers/<ANALYZER-NAME>/tmp:<TAG>

For example, one of the development images for the semgrep analyzer is:

shell
registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep/tmp:7580d6b037d93646774de601be5f39c46707bf04

In order to restrict the number of people who have write access to the container registry, the container registry in the development project must be made private by configuring the following project features and permissions settings for the project located at https://gitlab.com/gitlab-org/security-products/analyzers/<ANALYZER-NAME>:

  • Settings -> General -> Visibility, project features, permissions
    • Container Registry
      • Only Project Members

Each group in the Sec Section is responsible for:

  1. Managing the deprecation and removal schedule for their artifacts, and creating issues for this purpose.
  2. Creating and configuring projects under the new location.
  3. Configuring builds to push release artifacts to the new location.
  4. Removing or keeping images in old locations according to their own support agreements.

Daily rebuild of Container Images

The analyzer images are rebuilt on a daily basis to ensure that we frequently and automatically pull patches provided by vendors of the base images we rely on.

This process only applies to the images used in versions of GitLab matching the current MAJOR release. The intent is not to release a newer version each day but rather rebuild each active variant of an image and overwrite the corresponding tags:

  • the MAJOR.MINOR.PATCH image tag (for example: 4.1.7)
  • the MAJOR.MINOR image tag(for example: 4.1)
  • the MAJOR image tag (for example: 4)
  • the latest image tag

The implementation of the rebuild process may vary depending on the project, though a shared CI configuration is available in our development ci-templates project to help achieving this.

Adding new language support to GitLab Advanced SAST (GLAS)

This guide helps engineers evaluate and add new language support to GLAS. These guidelines ensure consistent quality when expanding language coverage, rather than serving as strict requirements.

Language support readiness criteria

Adapt these guidelines to your specific language while maintaining our analyzer quality standards.

These guidelines come from our experience adding PHP support to GLAS (see issue #514210) and help determine when new language support is ready for production.

Quality readiness

Cross-file analysis capability
  • Support the most common dependency management patterns in the target language
  • Support common inclusion mechanisms specific to the language
Detection quality
  • Precision Rate ≥ 80% across supported CWEs
  • Comprehensive test corpus for each supported CWE
  • Testing against popular frameworks in the language ecosystem

Coverage readiness

Priority-based coverage
  • Must cover critical injection vulnerabilities relevant to the language
  • Must cover common security misconfigurations
  • Must align with industry standards (OWASP Top 10, SANS CWE Top 25)
  • Focus on high-impact vulnerabilities commonly found in the language

Support readiness

Documentation requirements
  • Language listed and described in supported languages documentation
  • CWE coverage table updated with new language column
  • All supported CWEs properly marked
  • Known limitations clearly documented

Performance readiness

Standard performance criteria
  • Medium-sized applications: < 10 minutes
  • Very large applications: < 30 minutes with multi-core options
Benchmark definition
  • Define representative codebases for benchmarking
  • Include common frameworks and libraries

Security and Build fixes of Go

The Dockerfile of the Secure analyzers implemented in Go must reference a MAJOR release of Go, and not a MINOR revision. This ensures that the version of Go used to compile the analyzer includes all the security fixes available at a given time. For example, the multi-stage Dockerfile of an analyzer must use the golang:1.15-alpine image to build the analyzer CLI, but not golang:1.15.4-alpine.

When a MINOR revision of Go is released, and when it includes security fixes, project maintainers must check whether the Secure analyzers need to be re-built. The version of Go used for the build should appear in the log of the build job corresponding to the release, and it can also be extracted from the Go binary using the strings command.

If the latest image of the analyzer was built with the affected version of Go, then it needs to be rebuilt. To rebuild the image, maintainers can either:

  • trigger a new pipeline for the Git tag that corresponds to the stable release
  • create a new Git tag where the BUILD number is incremented
  • trigger a pipeline for the default branch, and where the PUBLISH_IMAGES variable is set to a non-empty value

Either way a new Docker image is built, and it's published with the same image tags: MAJOR.MINOR.PATCH and MAJOR.

This workflow assumes full compatibility between MINOR revisions of the same MAJOR release of Go. If there's a compatibility issue, the project pipeline will fail when running the tests. In that case, it might be necessary to reference a MINOR revision of Go in the Dockerfile and document that exception until the compatibility issue has been resolved.

Since it is NOT referenced in the Dockerfile, the MINOR revision of Go is NOT mentioned in the project changelog.

There may be times where it makes sense to use a build tag as the changes made are build related and don't require a changelog entry. For example, pushing Docker images to a new registry location.

Git tag to rebuild

When creating a new Git tag to rebuild the analyzer, the new tag has the same MAJOR.MINOR.PATCH version as before, but the BUILD number (as defined in semver) is incremented.

For instance, if the latest release of the analyzer is v1.2.3, and if the corresponding Docker image was built using an affected version of Go, then maintainers create the Git tag v1.2.3+1 to rebuild the image. If the latest release is v1.2.3+1, then they create v1.2.3+2.

The build number is automatically removed from the image tag. To illustrate, creating a Git tag v1.2.3+1 in the gemnasium project makes the pipeline rebuild the image, and push it as gemnasium:1.2.3.

The Git tag created to rebuild has a simple message that explains why the new build is needed. Example: Rebuild with Go 1.15.6. The tag has no release notes, and no release is created.

To create a new Git tag to rebuild the analyzer, follow these steps:

  1. Create a new Git tag and provide a message

    shell
    git tag -a v1.2.3+1 -m "Rebuild with Go 1.15.6"

  2. Push the tags to the repo

    shell
    git push origin --tags

  3. A new pipeline for the Git tag will be triggered and a new image will be built and tagged.

  4. Run a new pipeline for the master branch in order to run the full suite of tests and generate a new vulnerability report for the newly tagged image. This is necessary because the release pipeline triggered in step 3. above runs only a subset of tests, for example, it does not perform a container scanning analysis.

Monthly release process

This should be done on the 18th of each month. Though, this is a soft deadline and there is no harm in doing it within a few days after.

First, create a new issue for a release with a script from this repo: ./scripts/release_issue.rb MAJOR.MINOR. This issue will guide you through the whole release process. In general, you have to perform the following tasks:

Dependency updates

Dependencies and upstream scanners (if any) used in analyzer source code are updated using different approaches depending on the analyzer type:

SAST automated dependency updates with Renovate

SAST uses the Renovate GitLab Bot to automatically create merge requests and changelog entries for dependency updates.

To enable automatic dependency updates for a new analyzer with the Renovate GitLab Bot, add the analyzer by submitting a merge request following the pattern shown in Add SAST analyzers.

Automated changelog updates

Changelog entries in merge requests with dependency updates are automatically generated as follows:

  1. Before creating the merge request, the Renovate GitLab Bot executes the commands listed in the postUpgradeTasks.

    1. The postUpgradeTasks runs the changelogParserCommand, which executes the changelog-parser command line tool.

      The changelog-parser command line tool automatically inserts a new minor changelog entry that contains the {{MERGE_REQUEST_ID}} placeholder text. For example:

      markdown
      ## v1.1.0
- Update `report` module from `1.2.3` to `1.2.4` (!{{MERGE_REQUEST_ID}})

    2. The Renovate GitLab Bot creates a new merge request with the dependency updates and changelog entry.

  2. A new pipeline is triggered in the merge request, which executes the update changelog mrid job, included by the analyzer.yml template.

    The update changelog mrid job creates a commit to replace the {{MERGE_REQUEST_ID}} placeholder text with the actual merge request ID.

Secret detection automated dependency updates with SastBot

The Secret Detection team uses an internal tool (SastBot) to automate dependency management of pipeline-based secret detection analyzers. SastBot generates MRs on the 8th of each month and distributes their assignment among team members to take them forward for review. For details on the process, see dependency update automation.

SastBot requires different access tokens for each job. It uses the DEP_GITLAB_TOKEN environment variable to retrieve the token when running scheduled pipeline jobs.

Scheduled PipelineToken SourceRoleScopeDEP_GITLAB_TOKEN Token Configuration LocationToken Expiry
Merge Request Metadata Updatesecurity-products/analyzers groupdeveloperapiSettings > CI/CI Variables section (Masked, Protected, Hidden)Jul 25, 2026
Release Issue Creationsecurity-products/release projectplannerapiConfiguration section of the scheduled pipeline jobJul 28, 2026
Analyzerssast-bot groupdeveloperapiConfiguration section of the scheduled pipeline jobJul 28, 2026