feat: add reusable DAST security scanning workflow

[gandalf-at-lerian]

Request Type

New workflow

Affected Workflow

N/A — new workflow

Problem / Motivation

The organization currently has reusable SAST, dependency, secret, and container scanning capabilities, but github-actions-shared-workflows does not provide a reusable Dynamic Application Security Testing (DAST) workflow.

As a result, repositories that expose HTTP applications or APIs have no standard organization-wide mechanism to test a deployed application from the outside, gate releases on dynamic security findings, and retain consistent evidence for security and audit purposes.

DAST must complement—not replace—SAST and periodic penetration testing. It should apply only to repositories with a deployed HTTP surface; libraries, CLIs, and workers without such a surface should be documented as not applicable.

Proposed Solution

Create a reusable workflow such as .github/workflows/dast-security-scan.yml, initially using OWASP ZAP or an equivalent open-source DAST engine pinned to an immutable digest/SHA.

The workflow should run after deployment and a successful health check against an authorized staging, release-candidate, or ephemeral environment. It must not actively scan production by default.

Proposed capabilities:

• Support baseline, api, and full scan modes.
• Accept a target URL and an optional OpenAPI specification URL/path.
• Support authenticated scans without exposing credentials in logs or artifacts.
• Restrict targets through an explicit host allowlist to prevent scanning unintended systems.
• Configure finding thresholds and advisory versus blocking behavior.
• Fail closed when the scanner or evidence generation fails.
• Produce human-readable and machine-readable evidence.
• Add concurrency controls and timeouts.
• Keep existing callers unchanged; adoption should occur through explicit caller workflows.

Proposed inputs:

• target_url
• scan_type (baseline, api, or full; default baseline)
• openapi_url or openapi_path
• allowed_hosts
• fail_on_severity
• blocking (default false during initial rollout)
• timeout_minutes
• artifact_retention_days

Proposed optional secrets:

• authentication header name/value or an equivalent safe authentication mechanism

Evidence Requirements

Each run should generate and retain:

• HTML report for human review.
• JSON/XML/SARIF or equivalent machine-readable report.
• GitHub Actions job summary and PR/release comment.
• Artifact containing the reports and a manifest with repository, commit SHA, sanitized target, scan type, scanner version/digest, execution time, result, and finding counts by severity.
• A documented path for longer-term evidence storage, such as the existing S3 evidence pattern, when GitHub artifact retention is insufficient.

No credentials, tokens, authorization headers, customer data, or sensitive response bodies may be persisted as evidence.

Example Usage

name: DAST Security Scan

on:
  workflow_dispatch:
  workflow_call:

jobs:
  dast:
    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/dast-security-scan.yml@<immutable-ref>
    with:
      target_url: https://application.stg.example.net
      scan_type: api
      openapi_url: https://application.stg.example.net/openapi.json
      allowed_hosts: application.stg.example.net
      fail_on_severity: high
      blocking: false
    secrets: inherit

Expected execution order in caller repositories:

build -> deploy to authorized environment -> health check -> DAST -> evidence/gate

Rollout

1. Implement and validate the reusable workflow in github-actions-shared-workflows.
2. Pilot it in one Go API and one JS/TS web application with stable staging environments.
3. Run initially in advisory mode and classify false positives.
4. Define a versioned, justified, and expiring suppression mechanism.
5. Make HIGH/CRITICAL findings blocking after the pilot.
6. Inventory organization repositories as applicable, not applicable, or pending configuration before claiming organization-wide DAST coverage.

Acceptance Criteria

• Reusable DAST workflow exists and passes repository lint/validation checks.
• Scanner dependency is pinned immutably.
• Baseline and OpenAPI/API scan modes are supported.
• Active scans cannot target production by default.
• Target host allowlisting is enforced.
• Authentication values are masked and absent from evidence.
• Missing/unparseable scan evidence fails closed.
• Advisory and blocking modes are supported.
• HTML plus machine-readable evidence is uploaded with configurable retention.
• Evidence manifest identifies the exact repository commit and scanner version.
• Self-tests cover clean, findings, scanner failure, invalid target, and secret-masking scenarios.
• Documentation explains applicability, configuration, limitations, and the distinction between DAST and penetration testing.
• Pilot executions are completed successfully in one API and one web repository before broad rollout.

Alternatives Considered

• Treating existing Apidog E2E tests as DAST: rejected because functional API scenarios do not provide automated dynamic vulnerability scanning.
• Running DAST inside every PR validation workflow: rejected because DAST requires an authorized deployed target and should run after deployment.
• Relying only on periodic penetration testing: rejected because it does not provide continuous regression detection between assessments.

Breaking Change

No — fully backward compatible. Repositories opt in through an explicit caller workflow.

Checklist

• I searched existing issues and this is not a duplicate.
• This feature aligns with the repository's goal of providing reusable, organization-wide workflows.