xboarder56/velociraptor repository overview

GitHub Repository: github.com/Xboarder56/velociraptor-docker⁠

⁠Velociraptor (Server) in Docker

Run the Velocidex Velociraptor⁠ server in a container with sensible defaults, HTTPS, and prebuilt client repacks.

• Architectures: linux/amd64, linux/arm64
• Ports: 8000 (client/ingest), 8889 (GUI), 8001 (gRPC API), 8003 (Prometheus)
• Data dir: mount /velociraptor to persist config, keys, artifacts, and repacked clients
• TLS: self-signed cert generated on first run (you can rotate later)

On start, the container prints a small build banner (version, arch, base image, git commit, build date) so you can confirm what you pulled.

⁠Quick Start

docker run -it --rm \
  -p 8000:8000 -p 8889:8889 -p 8001:8001 -p 8003:8003 \
  -v $PWD/velodata:/velociraptor \
  xboarder56/velociraptor:latest

Open https://localhost:8889⁠ (accept the self-signed cert) and log in with the bootstrap credentials below (you should change them right away).

⁠Runtime Configuration (Environment Variables)

These variables are read at container start—no image rebuilds needed.

Persistent paths (mount a volume):

• /velociraptor/server.config.yaml — server config (auto-generated)
• /velociraptor/client.config.yaml — client config
• /velociraptor/client_bundles/ — repacked client binaries (.deb/.rpm/.exe/.msi)

⁠Common Run Examples

⁠1) Run quietly (INFO mode)

This overrides the default, which is to run with verbose (DEBUG) logs.

docker run -it --rm \
  -p 8000:8000 -p 8889:8889 -p 8001:8001 -p 8003:8003 \
  -v $PWD/velodata:/velociraptor \
  -e VELOX_DEFAULT_USER=admin -e VELOX_DEFAULT_PASSWORD='S3cure!' \
  -e VELOX_START_SERVER_VERBOSE=false \
  xboarder56/velociraptor:latest

⁠2) Set the public URL clients should use

docker run -it --rm \
  -e VELOX_FRONTEND_HOSTNAME=velociraptor.example.com \
  -e VELOX_FRONTEND_PORT=443 \
  -e VELOX_FRONTEND_SERVER_SCHEME=https \
  -p 443:8000 -p 8889:8889 \
  -v $PWD/velodata:/velociraptor \
  xboarder56/velociraptor:latest

⁠3) Use different public URLs for Client and GUI

docker run -it --rm \
  -e VELOX_FRONTEND_SERVER_URL=https://ingest.example.com:8000/ \
  -e VELOX_GUI_URL=https://admin.example.com:8889/ \
  -p 8000:8000 -p 8889:8889 \
  -v $PWD/velodata:/velociraptor \
  xboarder56/velociraptor:latest

⁠Docker Compose

services:
  velociraptor:
    image: xboarder56/velociraptor:latest
    restart: unless-stopped
    environment:
      VELOX_DEFAULT_USER: admin
      VELOX_DEFAULT_PASSWORD: "S3cure!"
      VELOX_FRONTEND_HOSTNAME: velociraptor.example.com
      VELOX_START_SERVER_VERBOSE: "false"
    ports:
      - "8000:8000"   # client/ingest
      - "8889:8889"   # GUI
      - "8001:8001"   # gRPC API
      - "8003:8003"   # Metrics
    volumes:
      - ./velodata:/velociraptor

⁠What to Expect on First Run

• The entrypoint generates a secure server.config.yaml and a client.config.yaml.
• Clients for Linux (amd64 + arm64), macOS (amd64 + arm64), and Windows (exe + msi) are repacked into /velociraptor/client_bundles/ with your server URL.
• You’ll see logs like:
  • GUI is ready to handle TLS requests on https://localhost:8889/
  • Frontend is ready to handle client TLS requests at https://localhost:8000/

⁠Client Binaries

After startup, check ./velodata/client_bundles/ for repacked binaries:

• Linux: .deb and .rpm packages for amd64 and arm64
• macOS: repacked executables for amd64 and arm64
• Windows: .exe and .msi

If a specific upstream client binary isn’t available, the repack step is skipped (you’ll see a log message).

⁠Security Notes

• Change the default credentials via VELOX_USER / VELOX_PASSWORD on first run.
• TLS is self-signed by default; rotate keys/certificates as needed from the server.
• Expose GUI/API only where appropriate; consider a reverse proxy or firewall rules.

⁠Troubleshooting

• Seeing [DEBUG] FlowStorageManager housekeeping run?
  You likely set VELOX_START_SERVER_VERBOSE=true (adds -v). Remove it to suppress DEBUG.
• Ports already in use? Map them as needed: -p 443:8000 and set VELOX_FRONTEND_PORT=443.

⁠Tags

• :latest — most recent successful build
• :<velociraptor-version> — e.g. :0.76.5. Floats to the latest re-release for that upstream patch.
• :<minor> — e.g. :0.76. Floats across patch releases within that minor.
• :sha-<short> — e.g. :sha-abc1234. Commit-pinned reproducible reference.
• Multi-arch manifests are published for amd64 and arm64

⁠Build & Release Flow

This repo uses two GitHub Actions workflows:

• upstream-check.yml runs daily. It polls the Velocidex release feed and, if it sees a newer release or if upstream re-published binaries for the current version (with new sha256s), opens a PR bumping versions.env + binaries.lock. For platforms upstream hasn't published yet for the latest release, the workflow walks back through prior releases and pins those assets to the most recent release that does include them.
• build-publish.yml runs on tag pushes matching v* and on manual dispatch. It:
  1. Builds an amd64 image and runs scripts/ci-image-validation.sh against it (server starts, GUI responds, a repacked Linux client makes contact).
  2. Only if validation passes, does a multi-arch (linux/amd64, linux/arm64) buildx build and pushes to Docker Hub with provenance + SBOM attestations.

To cut a release:

1. Review and merge the PR from upstream-check.

2. Tag the merge commit with the value of VELOX_VERSION from versions.env (optionally suffixed with -<IMAGE_REVISION> when IMAGE_REVISION > 1):

   git tag v0.76.8        # first revision
   # or
   git tag v0.76.8-2      # subsequent re-release of the same upstream version
   git push --tags
   

   Copy

3. Required Docker Hub secrets on the repo: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN.

⁠About This Fork

This repository is a fork of weslambert/velociraptor-docker⁠, originally created by Wes Lambert.
It aims to maintain compatibility with the latest Velocidex Velociraptor⁠ releases while providing additional configuration options and deployment improvements for Docker environments.

All credit for the foundational work goes to Wes Lambert — this fork primarily adds quality-of-life enhancements, updated configurations, and maintenance updates.

Maintained by: Xboarder56⁠
Upstream project: Velocidex Velociraptor⁠