CI/CD Integration
CI/CD Integration
Relevant source files
Purpose and Scope
This document provides practical examples and guidance for integrating WSHawk into Continuous Integration/Continuous Deployment (CI/CD) pipelines for automated WebSocket security scanning. It covers workflow configurations for GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and generic shell-based CI systems. The focus is on production-ready configurations that handle report artifacts, authentication, and failure conditions.
For Docker-specific deployment details, see Docker Deployment. For programmatic integration using Python scripts, see Python API Usage.
Installation Strategies in CI/CD
WSHawk supports two primary installation methods in CI/CD environments, each with distinct trade-offs:
pip Installation Strategy
The pip-based approach installs WSHawk directly into the CI runner's Python environment. This method provides faster startup times after initial caching and direct access to the Python API.
Advantages:
- Faster execution after dependency caching
- Native access to Python API for custom workflows
- Smaller storage footprint (no Docker image layers)
Disadvantages:
- Requires Python 3.8+ on the CI runner
- Dependency conflicts possible in shared environments
- Playwright browser installation adds complexity
Docker Installation Strategy
The Docker-based approach uses pre-built images from Docker Hub or GitHub Container Registry. This method ensures consistent environments and eliminates dependency management.
Advantages:
- Consistent execution environment (no dependency conflicts)
- No Python installation required on runner
- Pre-configured with all dependencies
- Supports multi-architecture (amd64/arm64)
Disadvantages:
- Larger image pull size (~150MB)
- Slower cold-start times without image caching
- Requires Docker daemon access
Sources: README.md L36-L62
Integration Workflow Architecture
The following diagram shows how WSHawk integrates into a typical CI/CD pipeline:
Sources: README.md L69-L72
GitHub Actions Integration
GitHub Actions is the native CI/CD platform for GitHub repositories. WSHawk integrates seamlessly with Actions workflows.
Basic Security Scan Workflow
This minimal workflow runs WSHawk on every push and pull request:
This configuration uses the Docker-based approach to eliminate dependency management. The --rm flag ensures container cleanup after execution.
Sources: docs/DOCKER.md L146-L163
.github/workflows/docker-build.yml L1-L68
Advanced Workflow with Artifact Upload
This workflow saves HTML reports as GitHub Actions artifacts for later review:
The schedule trigger enables automated daily scans. The if: always() condition ensures report upload even if the scan fails.
Sources: .github/workflows/docker-build.yml L25-L68
pip-Based Installation Workflow
For teams preferring pip installation:
The cache: 'pip' option speeds up subsequent runs by caching dependencies. The playwright install chromium command enables browser-based XSS verification.
Sources: README.md L39-L44
Matrix Build for Multiple Targets
This workflow scans multiple WebSocket endpoints in parallel:
The fail-fast: false setting ensures all targets are scanned even if one fails.
Sources: .github/workflows/docker-build.yml L18-L68
Defensive Validation in CI/CD
This workflow runs defensive validation tests for blue team security control validation:
This workflow runs weekly to validate security controls remain effective. The wshawk-defensive command runs DNS exfiltration, bot detection, CSWSH, and WSS protocol tests.
Sources: README.md L143-L184
GitLab CI Integration
GitLab CI uses .gitlab-ci.yml for pipeline configuration. WSHawk integrates using either Docker-in-Docker or shell runners.
Basic GitLab CI Pipeline
The docker:dind service enables Docker-in-Docker execution for runners that don't have native Docker access.
Sources: docs/DOCKER.md L146-L163
GitLab CI with Artifacts
The allow_failure: true setting prevents pipeline failure while still reporting vulnerabilities. GitLab displays artifacts in the pipeline UI.
Sources: docs/DOCKER.md L56-L63
Multi-Stage GitLab Pipeline
This configuration separates offensive and defensive testing:
The offensive scan runs on merge requests, while defensive validation runs on scheduled pipelines with stricter failure conditions.
Sources: README.md L143-L184
Jenkins Integration
Jenkins supports both Declarative and Scripted pipelines. WSHawk integrates using shell commands.
Declarative Pipeline
The publishHTML plugin renders reports directly in Jenkins UI. The emailext plugin sends notifications on failure.
Sources: docs/DOCKER.md L14-L25
Scripted Pipeline with Credentials
The withCredentials block securely injects authentication tokens as environment variables without exposing them in logs.
Sources: docs/DOCKER.md L110-L118
Azure DevOps Integration
Azure DevOps uses YAML pipelines for build automation.
Azure Pipelines YAML
The $(Build.ArtifactStagingDirectory) variable points to Azure's artifact directory. The condition: always() ensures artifact publication even on failure.
Sources: docs/DOCKER.md L56-L63
Azure Pipelines with Schedule
The always: true setting ensures scheduled runs even without code changes.
Sources: README.md L143-L150
Configuration and Authentication
Environment Variables
WSHawk supports configuration through environment variables for authentication and customization:
The -e flag passes environment variables into the Docker container. The ${{ secrets.* }} syntax accesses encrypted GitHub secrets.
Sources: docs/DOCKER.md L110-L118
Configuration Files
For complex authentication sequences, use YAML configuration files:
The volume mount (-v) makes the configuration file accessible inside the container.
Sources: docs/DOCKER.md L56-L63
Secrets Management Best Practices
The following diagram shows secure credential flow in CI/CD:
Key practices:
- Store credentials in CI platform secrets (encrypted at rest)
- Use environment variable injection (not hardcoded in YAML)
- Never commit secrets to version control
- Redact sensitive data in logs and reports
Sources: docs/DOCKER.md L110-L118
Report Handling and Artifact Management
Report File Naming Convention
WSHawk generates reports with timestamp-based filenames: wshawk_report_YYYYMMDD_HHMMSS.html. CI/CD pipelines must handle these dynamic filenames.
The wildcard pattern wshawk_report_*.html matches all generated reports.
Sources: README.md L129
Volume Mounting for Report Persistence
Docker-based workflows require volume mounting to extract reports from containers:
The -v $(pwd)/reports:/app/reports flag mounts the host's reports directory into the container at /app/reports.
Sources: docs/DOCKER.md L56-L63
Multi-Target Report Organization
For matrix builds scanning multiple targets:
This approach creates separate directories per target, preventing filename collisions.
Sources: README.md L129
Exit Codes and Failure Handling
WSHawk Exit Code Behavior
WSHawk uses standard Unix exit codes:
| Exit Code | Condition | Description |
| --- | --- | --- |
| 0 | Success | Scan completed, no critical vulnerabilities |
| 1 | Failure | Critical vulnerabilities found or scan error |
| 2 | Invalid Arguments | Command-line syntax error |
| >2 | System Error | Network failure, timeout, or system issue |
Sources: README.md L1-L245
Fail-on-Critical Pattern
This pattern fails the build only when critical vulnerabilities are detected:
The continue-on-error: true setting allows the workflow to proceed to the check step. The grep command searches HTML reports for severity levels.
Sources: README.md L143-L184
Informational Mode
For informational scanning without build failure:
The if: always() condition ensures report upload regardless of scan outcome. This approach is useful for tracking vulnerability trends without blocking deployments.
Sources: docs/DOCKER.md L146-L163
Advanced CI/CD Patterns
Scheduled Security Audits
This pattern runs comprehensive weekly audits with defensive validation:
The retention-days: 365 setting preserves audit reports for compliance requirements.
Sources: README.md L82-L93
Progressive Security Testing
This pattern runs lightweight tests on every commit, comprehensive tests on PRs, and full audits on main:
This tiered approach balances security coverage with CI/CD performance.
Sources: README.md L69-L105
Rate-Limited Production Scanning
For scanning production systems without impacting performance:
The --rate 2 flag limits to 2 requests per second, minimizing production impact. The timeout option prevents hung scans from blocking the pipeline.
Sources: README.md L88-L89
Integration Code Flow
The following diagram maps CI/CD integration components to their code implementations:
Sources: .github/workflows/docker-build.yml L1-L68
Security Considerations for CI/CD
Credential Isolation
Never expose credentials in CI logs or reports:
WSHawk automatically redacts authentication tokens from logs and HTML reports.
Sources: docs/DOCKER.md L110-L118
Network Segmentation
For scanning internal systems, use appropriate network configurations:
The --network host flag allows container access to host network interfaces. Use this only in trusted CI environments.
Sources: docs/DOCKER.md L66-L70
Rate Limiting for Production Scans
Always apply rate limiting when scanning production systems:
The --rate 2 flag limits requests to 2 per second, preventing service disruption.
Sources: README.md L88-L89
Resource Limits
Prevent CI resource exhaustion:
The --memory and --cpus flags prevent runaway resource consumption.
Sources: docs/DOCKER.md L222-L225
Troubleshooting CI/CD Integration
Common Issues and Solutions
| Issue | Symptom | Solution |
| --- | --- | --- |
| Image pull timeout | docker pull fails in CI | Use docker pull --max-concurrent-downloads 3 or pre-cache images |
| Report not found | Artifact upload fails | Verify volume mount path matches report output directory |
| Permission denied | Container cannot write reports | Use --user $(id -u):$(id -g) or ensure volume permissions |
| Network unreachable | Cannot connect to WebSocket target | Check network mode, DNS resolution, and firewall rules |
| Playwright not found | Browser verification fails | Add playwright install chromium before scan |
| Exit code 137 | Container killed by OOM | Increase memory limit or reduce --rate value |
Sources: docs/DOCKER.md L167-L192
Debug Mode
Enable verbose logging for troubleshooting:
The tee command captures both stdout and stderr for analysis.
Sources: docs/DOCKER.md L110-L118
Summary
This document covered CI/CD integration patterns for WSHawk across multiple platforms:
- GitHub Actions: Most common platform with native artifact support
- GitLab CI: Docker-in-Docker configuration with artifact management
- Jenkins: Both Declarative and Scripted pipeline approaches
- Azure DevOps: YAML pipeline configuration with scheduled scans
Key integration points:
- docker-build.yml L1-L68 demonstrates automated Docker image building
- DOCKER.md L146-L163 provides CI/CD example templates
- README.md L69-L72 specifies the quick scan command optimized for automation
- README.md L129 documents the report filename convention
The Docker-based approach (docker pull rothackers/wshawk:latest) provides the most reliable integration due to consistent dependencies and zero configuration. For teams requiring pip installation, the Python API approach offers more flexibility at the cost of increased setup complexity.
Sources: README.md L1-L245