GitLab CI — Shieldome Docs

Overview

Shieldome integrates with GitLab CI via its REST API. Add a security scan stage to your .gitlab-ci.yml and get automatic vulnerability reports on every merge request or deployment.

Prerequisites

A Shieldome account with an API key (see API Keys)
The target URL added as an authorized site in Shieldome
GitLab CI/CD enabled on your project

Step 1 — Add your API key as a CI/CD variable

In your GitLab project, go to Settings → CI/CD → Variables
Click Add variable
Key: SHIELDOME_API_KEY
Value: your Shieldome API key
Check Masked so it doesn't appear in logs
Uncheck Protected if you want it available on all branches
Click Add variable

Step 2 — Add the scan job to .gitlab-ci.yml

yaml

stages:
  - build
  - test
  - deploy
  - security   # add after deploy

shieldome-scan:
  stage: security
  image: python:3.11-slim
  only:
    - main
    - merge_requests
  allow_failure: false   # set to true to warn without blocking
  variables:
    SHIELDOME_URL: https://your-shieldome-url
    TARGET_URL:   https://your-app-url.com
    FAIL_ON:      critical   # critical | high | medium
  script:
    - pip install requests -q
    - |
      python3 - <<'EOF'
      import requests, time, sys, os

      base   = os.environ['SHIELDOME_URL']
      target = os.environ['TARGET_URL']
      key    = os.environ['SHIELDOME_API_KEY']
      fail   = os.environ.get('FAIL_ON', 'critical')
      headers = {'X-Shieldome-Key': key, 'Content-Type': 'application/json'}

      # Trigger scan
      r = requests.post(f'{base}/api/scan', json={
          'target_url': target, 'scan_type': 'vuln', 'scan_authorized': True
      }, headers=headers, timeout=30)
      r.raise_for_status()
      scan_id = r.json()['scan_id']
      print(f'Scan started: {scan_id}')

      # Poll until done
      for _ in range(72):  # 12 min max
          time.sleep(10)
          s = requests.get(f'{base}/api/scan/{scan_id}', headers=headers, timeout=15).json()
          print(f'Status: {s.get("status")} | Progress: {s.get("progress", 0)}%')
          if s.get('status') in ('completed', 'failed'):
              break

      # Evaluate
      vulns = s.get('results', {}).get('vulnerabilities', [])
      counts = {'critical': 0, 'high': 0, 'medium': 0, 'low': 0}
      for v in vulns:
          sev = v.get('severity', 'low')
          if sev in counts:
              counts[sev] += 1

      print('\n=== Shieldome Scan Results ===')
      for sev, cnt in counts.items():
          print(f'  {sev.upper():10} {cnt}')
      print(f'\nFull report: {base}/app')

      threshold = {'critical': 4, 'high': 3, 'medium': 2, 'low': 1}
      t = threshold.get(fail, 4)
      failed_sevs = [s for s, c in counts.items() if c > 0 and threshold[s] >= t]
      if failed_sevs:
          print(f'\nFAILED: {", ".join(failed_sevs)} findings detected.')
          sys.exit(1)
      EOF
  artifacts:
    when: always
    reports:
      dotenv: scan.env
    expire_in: 30 days

Merge request integration

To show scan results directly in merge requests, add the only: merge_requests rule as shown above. The job output appears in the pipeline tab of the merge request.

Fail thresholds

FAIL_ON value	Fails when
`critical`	Any critical finding is detected
`high`	Any critical or high finding is detected
`medium`	Any critical, high, or medium finding

Scheduled weekly scans

GitLab has built-in pipeline scheduling. Go to CI/CD → Schedules → New schedule, set a cron expression (e.g. 0 6 * * 1 for every Monday at 06:00), and select your branch. The workflow_dispatch equivalent in GitLab is the Run pipeline button.

💡

Tip: use environments Set TARGET_URL as an environment-specific variable in GitLab so main scans production and feature branches scan staging automatically.