GitLab CI/CD Integration

This guide provides specific instructions for integrating the Wisec agent into your GitLab CI/CD pipelines.

1. Prerequisites

Before proceeding, ensure you have:

• A Wisec account and project created.

• Your Project ID from the Wisec dashboard.

• Your Agent Signing Key (Private Key) generated from the Wisec dashboard.

Refer to the Installation Guide for details on obtaining these.

2. Configure GitLab CI/CD Variables

Go to your GitLab project's Settings > CI/CD > Variables. Add the following variables, making sure to mark sensitive values as "Masked" to prevent their exposure in job logs.

• WISEC_PROJECT_ID:

  • Value: Your project's unique ID from the Wisec dashboard.

  • Type: Variable

  • Masked: No

• AGENT_PRIVATE_KEY_HEX:

  • Value: The private part of your Ed25519 signing key pair, obtained from the Wisec dashboard Settings page.

  • Type: Variable

  • Masked: Yes (highly recommended)

• WISEC_API_ENDPOINT:

  • Value: https://app.wisec.io/api/v1/events

  • Type: Variable

  • Masked: No

3. Modify your .gitlab-ci.yml

Add a new job or a step within an existing job in your .gitlab-ci.yml file to download and execute the Wisec agent.

# Example .gitlab-ci.yml job for Wisec integration

stages:
  - build
  - test
  - security # Example stage

scan_with_wisec:
  stage: security
  image: alpine:latest # Use an image with git installed, or install it
  before_script:
    - apk add --no-cache git curl tar # Ensure all tools are available
    - echo "Downloading gitleaks..."
    - wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz
    - tar -xzf gitleaks_8.18.2_linux_x64.tar.gz
    - chmod +x gitleaks
    - mv gitleaks /usr/local/bin/
    - echo "Downloading wisec-agent..."
    - curl -L -o wisec-agent https://storage.googleapis.com/wisec-downloads/agent
    - chmod +x wisec-agent
  script:
    # Execute the Wisec agent (it automatically uses environment variables)
    - ./wisec-agent
  allow_failure: true # Configure based on your pipeline's criticality for security checks
  only:
    - master
    - merge_requests # Run on main branches and merge requests

Important Notes:

• git Installation: The agent relies on git for collecting repository metadata. Ensure your CI/CD runner image has git installed, or add a step to install it (apk add git for Alpine, apt-get install git for Debian/Ubuntu).

• --public-key parameter: The agent does NOT require a --public-key parameter. The public key is already registered with your Wisec instance when you generate the signing key pair from the dashboard. The API Gateway uses this registered public key to verify the agent's signature.

• allow_failure: true: It's recommended to start with allow_failure: true for the security job so that any issues with the Wisec integration do not block your main development workflow. Once confident, you can set it to false.

Gitleaks and Secret Scanning

The CI/CD job example above includes steps to download and install gitleaks. The wisec-agent automatically detects gitleaks and uses it to scan your code for hardcoded secrets, which will appear as CRITICAL alerts in your dashboard.

To manage false positives, you can add a .gitleaksignore file to the root of your repository. For a detailed guide and an example file, please see the Secret Scanning section in our Quick Start guide.