Skip to content

Add clear error messaging when DAST template is used without required configuration variables

Problem

DAST already validates that required configuration variables are provided, but the current error message is generic, technical, and doesn't guide users on how to fix the issue.

Current error output

$ if [[ -f "environment_url.txt" ]]; then DAST_WEBSITE="${DAST_WEBSITE:-$(cat environment_url.txt)}"; export DAST_WEBSITE; fi
$ /analyze
2025-10-16T10:06:24.432 ERR MAIN  configuration validation failed error="the required field URL was not set"
2025-10-16T10:06:24.432 FTL MAIN  failed to initialize configuration: failed to create configuration: configuration validation failed

Issues with current output:

  • Generic log format doesn't match the improved DAST console styling
  • Doesn't specify which variable name to set (DAST_TARGET_URL vs "URL")
  • No guidance on how to fix the issue
  • No link to documentation
  • Doesn't explain what the variable is used for
  • Not beginner-friendly

User Story

As a DAST user
I want clear, actionable error messages when required configuration is missing
So that I immediately understand which variable to set and how to configure it

Proposed Solution

Replace the generic configuration validation error with a formatted, user-friendly message that matches the style of the new connectivity error messages.

Proposed error output

┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                               GitLab DAST                                              │
│                                        Dynamic Security Testing                                        │
└────────────────────────────────────────────────────────────────────────────────────────────────────────┘

🔍 DAST Scanner v6.21.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ Missing Required Configuration

DAST requires a target URL to scan. The DAST_TARGET_URL variable was not set.

Required configuration:
  • DAST_TARGET_URL - The URL of the application to scan

Example:

  variables:
    DAST_TARGET_URL: "https://example.com"

You can also provide the target URL via an environment_url.txt file in your artifacts.

📚 Getting started guide: https://docs.gitlab.com/user/application_security/dast/browser/#getting-started
🔗 Configuration options: https://docs.gitlab.com/user/application_security/dast/browser/configuration/

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For other missing fields

If other configuration fields are required in the future, the message should be adaptable:

❌ Missing Required Configuration

DAST is missing required configuration variables:

Missing variables:
  • DAST_TARGET_URL - The URL of the application to scan
  • DAST_AUTH_URL - The URL used for authentication (required when DAST_AUTH_USERNAME is set)

I will try to get the customised messages through incrementally.

Template to test against

Ensure this works with the official GitLab CI template: https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml

Technical Implementation

Changes needed

  • 1. Update configuration validation error handling:

    • Catch the existing "required field URL was not set" error
    • Transform into formatted, user-friendly output
    • Match styling of other DAST console messages (box borders, emojis, etc.)

  • 1. Map internal field names to user-facing variable names:

    • Internal: "URL" → User-facing: "DAST_TARGET_URL"
    • Add mapping for any other fields that might be validated
    • Include description of what each variable does

  • 1. Provide contextual help:

    • Link to getting started documentation
    • Show example configuration
    • Mention alternative configuration methods (environment_url.txt)

  • 1. Maintain consistency:

    • Use same formatting as connectivity error messages
    • Use same emoji/icon style
    • Use same documentation links

Error detection location

The validation already happens in the configuration initialization. The fix is to:

  • Detect the configuration validation failure
  • Instead of logging generic ERR/FTL messages
  • Output the formatted, styled error message
  • Exit with appropriate error code

Tasks

  • Identify where configuration validation errors are caught
  • Create formatted error message for missing DAST_TARGET_URL
  • Map internal field name "URL" to user variable name "DAST_TARGET_URL"
  • Add getting started documentation link
  • Add example configuration snippet
  • Mention alternative configuration via environment_url.txt
  • Style message to match other DAST console output (boxes, emojis)
  • Test with no variables set
  • Test with partial configuration (if applicable to other fields)
  • Ensure error doesn't show generic ERR/FTL log lines

Benefits

  • Improved first-time user experience: Clear guidance instead of cryptic error logs
  • Reduced support burden: Self-service information reduces support requests
  • Consistency: Matches styling and tone of other improved error messages
  • Faster problem resolution: Users immediately know which variable to set
  • Professional appearance: Polished error output reflects quality of product

Related

  • Part of DAST error messaging improvements initiative
  • Complements connectivity troubleshooting error messages
  • Related to overall DAST UX enhancement

CC: @gitlab-org/secure/dynamic-analysis

Edited by Hannah Baker