GitLab CI Component

The Qualys GitLab CI Component provides native container vulnerability scanning with direct integration into the GitLab Security Dashboard. Results appear alongside other GitLab security features.

Component Path: gitlab.com/qualys/qualys-container-scan@1.0.0

Component Inputs

Authentication

Input	Required	Default	Description
access_token	Yes	$QUALYS_ACCESS_TOKEN	Qualys API access token. Store as CI/CD variable.
pod	Yes	-	Qualys platform POD (US1, US2, US3, EU1, EU2, etc.)

Scan Target

Input	Required	Default	Description
image	Yes	-	Container image to scan (name:tag or digest)
image_tar	No	-	Path to tar archive of the image
platform	No	linux/amd64	Target platform for multi-arch images

Scan Mode

Input	Required	Default	Description
scan_mode	No	get-report	Scan operation mode (see below)

Available Scan Modes

Mode	Description	Use Case
get-report	Scan image and generate vulnerability report	Default mode for CI/CD pipelines
evaluate-policy	Evaluate image against Qualys cloud policies	Policy-based pipeline gating
scan-only	Scan without generating reports	Quick validation scans
inventory-only	Collect inventory without vulnerability matching	Asset discovery and SBOM

Scan Types

Input	Required	Default	Description
scan_types	No	pkg	Comma-separated scan types to perform

Available Scan Types

Type	Description	Dashboard Integration
pkg	Package vulnerability scanning	Container Scanning report
secret	Secrets detection in container layers	Secret Detection report
malware	Malware detection	Container Scanning report
fileinsight	File analysis and insight	Container Scanning report
compliance	Compliance checking	Container Scanning report

Threshold Configuration

Input	Required	Default	Description
fail_on_severity	No	-	Fail pipeline if vulnerabilities at or above this severity (1-5)
max_critical	No	-1	Maximum critical vulnerabilities allowed
max_high	No	-1	Maximum high vulnerabilities allowed
max_medium	No	-1	Maximum medium vulnerabilities allowed
max_low	No	-1	Maximum low vulnerabilities allowed

Policy Configuration

Input	Required	Default	Description
use_policy	No	false	Enable Qualys cloud policy evaluation
fail_on_audit	No	false	Fail pipeline on AUDIT policy result

Complete Example

include:
  - component: gitlab.com/qualys/qualys-container-scan@1.0.0
    inputs:
      pod: "US3"
      image: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
      scan_mode: "get-report"
      scan_types: "pkg,secret,malware"
      fail_on_severity: "4"
      max_critical: 0
      max_high: 5

stages:
  - build
  - test
  - security

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

# The qualys-container-scan job is automatically added to the security stage

Using CI/CD Variables

Store sensitive values as CI/CD variables:

1. Go to Settings > CI/CD > Variables
2. Add QUALYS_ACCESS_TOKEN with your API token
3. Mark as Masked and optionally Protected

include:
  - component: gitlab.com/qualys/qualys-container-scan@1.0.0
    inputs:
      access_token: $QUALYS_ACCESS_TOKEN
      pod: $QUALYS_POD
      image: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"

Policy Evaluation Mode

Use Qualys cloud policies for pipeline gating:

include:
  - component: gitlab.com/qualys/qualys-container-scan@1.0.0
    inputs:
      pod: "US3"
      image: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
      scan_mode: "evaluate-policy"
      use_policy: true
      fail_on_audit: true

Scanning Multiple Images

Scan multiple images using parallel jobs:

.qualys-scan-template:
  include:
    - component: gitlab.com/qualys/qualys-container-scan@1.0.0

scan-frontend:
  extends: .qualys-scan-template
  variables:
    QUALYS_IMAGE: "$CI_REGISTRY_IMAGE/frontend:$CI_COMMIT_SHA"

scan-backend:
  extends: .qualys-scan-template
  variables:
    QUALYS_IMAGE: "$CI_REGISTRY_IMAGE/backend:$CI_COMMIT_SHA"

scan-api:
  extends: .qualys-scan-template
  variables:
    QUALYS_IMAGE: "$CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHA"

Security Dashboard Integration

The component automatically generates GitLab Security Dashboard reports:

Scan Type	Report File	Dashboard Section
pkg, malware, compliance	gl-container-scanning-report.json	Container Scanning
secret	gl-secret-detection-report.json	Secret Detection

View results in Security & Compliance > Vulnerability Report.

Exit Codes

Code	Meaning	Pipeline Result
0	Scan passed all thresholds/policy	Success
1	Scan error or failed to complete	Failed
42	Policy DENY - failed policy evaluation	Failed
43	Policy AUDIT - requires review	Failed (if fail_on_audit) or Success

Artifacts

The component produces the following artifacts:

Artifact	Description
gl-container-scanning-report.json	GitLab Container Scanning format report
gl-secret-detection-report.json	GitLab Secret Detection format report
qualys-scan-results.json	Full Qualys scan results in JSON format