Integrate with GitLab

Software Composition Analysis (SCA) scanning enables you to scan code on pushes to the main branch and merge requests on any source or target branch. If you have GitLab Security enabled, the scan artifacts populate the GitLab Security Dashboard, vulnerability report, and dependency list.

Collect Lacework Secrets

Before you can run SCA in GitLab CI, you must add LW_ACCOUNT, LW_API_KEY and LW_API_SECRET to your GitLab repository or group CI/CD variables and assign a service user. To obtain these values:

1. Log in to the Lacework Console.
2. Click Settings > API keys.
3. Select or create an API key.
4. Ensure that a service user is assigned for your new or existing API key.
   1. To assign a service user:
      1. Select an API Key - Select an API key, click the edit icon, and then use the toggle and dropdown to select a service user and click Save.
      2. Create an API Key - Go to Create API key, then use the toggle and dropdown to select a service user and click Save.
5. Click the download icon.
6. Open the downloaded .json file to view your API Key, API Secret, and account name.

note

The service user who's assigned the API secret must have Read and Write permissions on Container Registries and Code Security. For more information, go to the Access Control Overview.

Use the values from the downloaded file to set the CI/CD variables at the project or group level.

Create a GitLab Token

In order for Lacework to add comments to your merge requests, you must add a GitLab API token as a CI/CD variable. In GitLab, you can either create a Project Access Token that is scoped to a single project, or you can create a Group Access Token that is scoped to all projects in that group. If you only need to scan code in a single project, we recommend only creating a Project Access Token. If you need to scan code from multiple projects, create a Group Access Token.

To add a GitLab API token as a CI/CD variable for a project or group:

1. Go to the project or group and choose Settings > Access Tokens.
2. Give the token an appropriate name, expiration date and select Guest from the Select a role dropdown.
3. Grant the api scope to the access token.
4. Click Create Project Access Token.
5. For the project or group, go to Settings > CI/CD.
6. In the Variables section, click Add variable.
7. Create a CI/CD variable named LW_GITLAB_TOKEN at the project (integrating a single project) or group level (integrating multiple projects).
8. Create CI/CD variables called LW_ACCOUNT, LW_API_KEY LW_API_SECRET. The values for these variables come from the Lacework secrets .json file you downloaded in a previous step.

Run on Pushes or merge Requests

1. In your project root, create a file called .gitlab-ci.yml.
2. Add the following to your .gitlab-ci.yml file:

include:
  - remote: 'https://gitlab.com/lacework-security/code-security/code-security-gitlab/-/raw/main/lacework-code-security.yaml'

stages:
  - security-scan

This includes the Lacework code security CI jobs in your CI pipeline file and scans code on pushes to the main branch.

note

Branches included in merge requests are also scanned.

For merge requests, SCA scans the commit(s) in the source branch and the base commit of the merge request diff and compares the results. Any new vulnerabilities introduced are added as a comment on the merge request, enabling you to resolve or fix these vulnerabilities before merging into the target branch.

tip

If SCA does not find any new vulnerabilities, it will not comment on the MR.

note

If you add the Lacework include CI template to your .gitlab-ci.yml file on the main development branch, you must merge or rebase changes to any existing development branches in order for scans to run on merge requests.

Variables

The following variables enable you to customize your SCA scan:

Variable	Description	Default Value
LW_SAST_CLASSES	Classes directory or JAR file to analyze - required if LW_SAST_SCAN=true	.
LW_SAST_SOURCES	Sources directory to analyze - required if LW_SAST_SCAN=true	.
LW_SCA_SCAN*	Whether to run a Lacework SCA scan	true
LW_SAST_SCAN*	Whether to run a Lacework SAST scan	false
LW_SCA_EVAL_INDIRECT_DEPENDENCIES^	Show vulnerabilities found in transitive dependencies - required if LW_SCA_SCAN=true	false
LW_DEBUG	Whether to run the Lacework code security tools in Debug mode	false

* = always required
^ = required in some circumstances

Override Variables and Log Debugging

The following example turns debug logging on:

include:
  - remote: 'https://gitlab.com/lacework-security/code-security/code-security-gitlab/-/raw/main/lacework-code-security.yaml'

stages:
  - security-scan


variables:
  LW_DEBUG: "true"

Troubleshooting

If your GitLab pipeline job returns errors indicating that the environment variables configured for CI/CD weren't found, check the Protect variable flag setting under Update Variable and determine whether it should be enabled/disabled for your environment.