Deployment and Integration

Deployment and Integration

Relevant source files

Purpose and Scope

This document provides an overview of WSHawk's deployment options and integration strategies across different environments. It covers the three primary distribution channels (PyPI, Docker Hub, GitHub Container Registry), containerized deployment architecture, and methods for integrating WSHawk into automated workflows.

For detailed instructions on specific deployment methods, see:

For installation steps and initial setup, see Installation Methods.

Distribution Architecture

WSHawk employs a triple-channel distribution strategy, enabling deployment in diverse environments from local development to enterprise CI/CD pipelines.

Sources: Dockerfile L1-L66

.github/workflows/docker-build.yml L1-L68

.github/workflows/ghcr-publish.yml L1-L50

Distribution Channels

| Channel | Registry | Authentication | Use Case | Version Tags | | --- | --- | --- | --- | --- | | PyPI | pypi.org | Public | Python developers, local development | 2.0.5, 2.0.6 | | Docker Hub | docker.io | Public | DevOps teams, traditional workflows | latest, 2.0.5, 2.0, 2 | | GHCR | ghcr.io | GitHub token | GitHub-native organizations | latest, 2.0.5, 2.0 |

Sources: .github/workflows/docker-build.yml L14-L16

.github/workflows/ghcr-publish.yml L11-L13

Docker Image Architecture

WSHawk's Docker image uses a multi-stage build pattern to minimize image size (~150MB) while including all necessary dependencies. The image runs as a non-root user (wshawk:1000) for enhanced security.

Sources: Dockerfile L4-L53

Multi-Stage Build Process

The Docker image construction follows a two-stage pattern defined in Dockerfile L1-L66

:

Stage 1: Builder Dockerfile L4-L20

  • Base: python:3.11-slim
  • Installs build dependencies (gcc)
  • Copies source files and setup.py, pyproject.toml
  • Executes pip install to build Python packages
  • Produces compiled artifacts in /usr/local/lib/python3.11/site-packages

Stage 2: Final Dockerfile L22-L53

Image Metadata

The image includes OpenContainers-compliant labels Dockerfile L55-L65

:

org.opencontainers.image.source=https://github.com/noobforanonymous/wshawk
org.opencontainers.image.description=Professional WebSocket security scanner
org.opencontainers.image.licenses=MIT
org.opencontainers.image.title=WSHawk

Sources: Dockerfile L4-L66

Automated Build and Publishing

WSHawk uses GitHub Actions to automate Docker image building and publishing to both Docker Hub and GitHub Container Registry.

Sources: .github/workflows/docker-build.yml L1-L68

.github/workflows/ghcr-publish.yml L1-L50

Docker Hub Workflow

The docker-build.yml workflow .github/workflows/docker-build.yml L1-L68

handles Docker Hub publishing:

Trigger Conditions .github/workflows/docker-build.yml L3-L12

:

  • Push to main branch
  • Push of tags matching v* pattern
  • Pull requests to main
  • Manual dispatch via GitHub UI

Build Process .github/workflows/docker-build.yml L52-L61

:

Tag Strategy .github/workflows/docker-build.yml L44-L50

:

  • Semantic versioning: {{version}}, {{major}}.{{minor}}, {{major}}
  • latest tag for default branch
  • Branch name tags for development
  • PR number tags for pull requests

Verification .github/workflows/docker-build.yml L63-L67

:

GitHub Container Registry Workflow

The ghcr-publish.yml workflow .github/workflows/ghcr-publish.yml L1-L50

publishes to GHCR:

Authentication .github/workflows/ghcr-publish.yml L26-L31

:

  • Uses GITHUB_TOKEN (no external credentials required)
  • Username: ${{ github.actor }}
  • Registry: ghcr.io

Tag Strategy .github/workflows/ghcr-publish.yml L38-L41

:

  • latest for main branch
  • Semantic versioning: {{version}}, {{major}}.{{minor}}

Sources: .github/workflows/docker-build.yml L1-L68

.github/workflows/ghcr-publish.yml L1-L50

Docker Compose Configuration

WSHawk includes a docker-compose.yml file for orchestrated deployments and local testing environments.

Sources: docker-compose.yml L1-L36

Service Definitions

WSHawk Service docker-compose.yml L4-L18

:

Vulnerable Server Service docker-compose.yml L20-L31

:

Network Configuration

docker-compose.yml L33-L35

defines a custom bridge network wshawk-network enabling container-to-container communication. The WSHawk service uses host network mode docker-compose.yml L9

to access services running on the host machine without port mapping complexity.

Sources: docker-compose.yml L1-L36

Integration Entry Points

WSHawk provides multiple entry points for different integration scenarios, all accessible from the Docker container or local installation.

Sources: Dockerfile L35

Dockerfile L52

docker-compose.yml L1-L36

CLI Entry Points

All CLI commands are installed as console scripts during package installation and available in the Docker container at /usr/local/bin/ Dockerfile L35

:

| Command | Purpose | Docker Usage | | --- | --- | --- | | wshawk | Quick automated scan | docker run --rm rothackers/wshawk ws://target.com | | wshawk-interactive | Menu-driven testing | docker run --rm -it rothackers/wshawk wshawk-interactive | | wshawk-advanced | Full feature control | docker run --rm rothackers/wshawk wshawk-advanced --full | | wshawk-defensive | Blue team validation | docker run --rm rothackers/wshawk wshawk-defensive ws://target.com |

The Docker ENTRYPOINT Dockerfile L52

is set to wshawk, with default CMD of --help Dockerfile L53

enabling both direct execution and command override patterns.

Python API Entry Point

Programmatic integration uses the WSHawkV2 class from wshawk.scanner_v2 module. This approach enables:

  • Custom scanning workflows
  • Integration with existing Python security tools
  • Embedding WSHawk in automated testing frameworks
  • Fine-grained control over scan configuration

For detailed Python API usage, see Python API Usage.

Sources: Dockerfile L35

Dockerfile L52-L53

Environment Configuration

WSHawk's behavior can be customized via environment variables in containerized deployments.

Docker Environment Variables

Python Runtime Configuration Dockerfile L44-L45

:

  • PYTHONUNBUFFERED=1: Disables output buffering for real-time log streaming
  • PYTHONDONTWRITEBYTECODE=1: Prevents .pyc file generation

Docker Run Example:

Docker Compose Configuration docker-compose.yml L17-L18

:

Volume Mounting for Persistence

Reports and logs are written to the container's /app directory Dockerfile L26

To persist artifacts:

The report filename includes timestamp: wshawk_report_YYYYMMDD_HHMMSS.html, enabling historical tracking without overwrite conflicts.

Sources: Dockerfile L26

Dockerfile L44-L45

docker-compose.yml L17-L18

Build Optimization

The Docker image employs several optimization strategies to minimize size and improve security.

.dockerignore Configuration

The .dockerignore L1-L72

file excludes unnecessary files from the Docker build context:

Excluded Categories:

This reduces build context size and speeds up image builds.

Multi-Stage Build Benefits

The multi-stage approach Dockerfile L4-L23

provides:

  • Size Reduction: Build tools (gcc) excluded from final image
  • Security: Attack surface minimized by removing compilers
  • Caching: Layer caching optimizes rebuild times
  • Separation: Build artifacts cleanly isolated from runtime

Final image size: ~150MB (documented in Dockerfile L198

comments in DOCKER.md reference)

Sources: .dockerignore L1-L72

Dockerfile L4-L23

Security Considerations

The Docker image implements security best practices for production deployments.

Non-Root User

Dockerfile L38-L41

creates and switches to a non-root user:

Benefits:

  • Prevents privilege escalation attacks
  • Limits container escape impact
  • Aligns with security scanning tool requirements
  • Compatible with restricted Kubernetes PSPs

Health Check

Dockerfile L48-L49

implements a container health check:

Enables orchestration systems (Docker Swarm, Kubernetes) to detect and restart failed containers.

Read-Only Filesystem

The image supports read-only root filesystem execution:

Only /app/reports requires write access for output artifacts.

Resource Limits

Example resource-constrained execution:

Sources: Dockerfile L38-L41

Dockerfile L48-L49

Summary

WSHawk's deployment architecture supports three distinct integration patterns:

  1. Containerized Deployment: Docker images on Docker Hub and GHCR, optimized for size (~150MB), security (non-root user), and multi-platform support (amd64/arm64)
  2. Package Installation: PyPI distribution for local development and programmatic integration via Python API
  3. CI/CD Automation: GitHub Actions workflows automate building, testing, and publishing to all distribution channels on every commit and release

The combination of multiple distribution channels, comprehensive Docker configuration, and automated CI/CD ensures WSHawk can be deployed in diverse environments from developer workstations to enterprise security pipelines.

For implementation details:

Sources: Dockerfile L1-L66

.github/workflows/docker-build.yml L1-L68

.github/workflows/ghcr-publish.yml L1-L50

docker-compose.yml L1-L36

.dockerignore L1-L72

docs/DOCKER.md L1-L240