BLACKSHIELD

Public Guide

Deploy the VM and Host Scanner

Install a managed Linux VM scanner that reuses an existing Wazuh or OSSEC alert source by default, then forwards host alerts from one native systemd service. Audience: Security operations teams, infrastructure engineers, and platform teams. Typical setup time: 10 minutes on Ubuntu/Debian systemd hosts.

quickstart

Use this if

Install a managed Linux VM scanner that reuses an existing Wazuh or OSSEC alert source by default, then forwards host alerts from one native systemd service.

Audience
Security operations teams, infrastructure engineers, and platform teams
Typical time
10 minutes on Ubuntu/Debian systemd hosts

Before You Begin

  • Use the managed Ubuntu/Debian bundle first when an existing Wazuh manager, OSSEC server, or OSSEC local install already writes JSON alerts.
  • For existing deployments, confirm a Wazuh manager, OSSEC server, or OSSEC local install is writing JSON alerts to `/var/ossec/logs/alerts/alerts.json`.
  • Set `BLACKSHIELD_OSSEC_MODE=managed-local` only after your organization approves the OSSEC GPLv2 local install path.
  • Do not point the local file collector at a Wazuh agent-only endpoint unless that endpoint is also where manager-side `alerts.json` is produced.
  • Use the advanced S3 or GCS path only when the alert-producing host cannot run the native managed service.
  • Create an ingestion API key in Settings -> API Keys with Ingestion scope before editing any generated env or secret values.
  • Rotate any `sp_...` key that was pasted into terminal transcripts, support tickets, or chat before retesting.

Fast path

Copy a working starter, run it in your environment, then come back here for the deeper rollout details.

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

Get the source bundle

Download the exact source files referenced on this page, or run the one-command installer to write them locally before following the deployment steps.

Managed Linux VM scanner

Creates `deploy/vm-scanner/managed/` with an Ubuntu/Debian installer that defaults to existing Wazuh/OSSEC alerts and supports explicit managed-local OSSEC installs.

deploy/vm-scanner/managed/
bash
BLACKSHIELD_SITE_URL=https://blackshield.chaplau.com \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/vm-scanner-managed-linux.sh)
cd deploy/vm-scanner/managed
Download source

VM scanner Docker Compose bundle

Creates `deploy/vm-scanner/` with a Compose file, a ready-to-edit `.env.vm-scanner`, and a README so local host ingestion is runnable without rewriting the guide commands.

deploy/vm-scanner/
bash
BLACKSHIELD_VMS_IMAGE=public.ecr.aws/blackshield-security/vms-scanner:1.0.6 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/vm-scanner-compose.sh)
cd deploy/vm-scanner
Download source

VM scanner systemd bundle

Creates `deploy/vm-scanner/systemd/` with a Docker-backed unit file, env template, install helper, and README for long-running host services.

deploy/vm-scanner/systemd/
bash
BLACKSHIELD_VMS_IMAGE=public.ecr.aws/blackshield-security/vms-scanner:1.0.6 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/vm-scanner-systemd.sh)
cd deploy/vm-scanner/systemd
Download source

VM scanner cron bundle

Creates `deploy/vm-scanner/cron/` with a one-shot wrapper, cron example, env template, and README for periodic host-side forwarding.

deploy/vm-scanner/cron/
bash
BLACKSHIELD_VMS_IMAGE=public.ecr.aws/blackshield-security/vms-scanner:1.0.6 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/vm-scanner-cron.sh)
cd deploy/vm-scanner/cron
Download source

AWS VM scanner source

Creates `deploy/aws-vm-scanner/` with an ECS Fargate service, S3-backed source settings, and a host upload helper so AWS rollout can start without writing infrastructure boilerplate first.

deploy/aws-vm-scanner/
bash
BLACKSHIELD_VMS_IMAGE=public.ecr.aws/blackshield-security/vms-scanner:1.0.6 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/aws-vm-scanner.sh)
cd deploy/aws-vm-scanner
Download source

GCP VM scanner source

Creates `deploy/gcp-vm-scanner/` with a Cloud Run service, GCS-backed source settings, and a host upload helper so GCP rollout can start without rewriting the guide commands.

deploy/gcp-vm-scanner/
bash
BLACKSHIELD_VMS_IMAGE=public.ecr.aws/blackshield-security/vms-scanner:1.0.6 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/gcp-vm-scanner.sh)
cd deploy/gcp-vm-scanner
Download source

Run This

Managed Linux install

bash
BLACKSHIELD_SITE_URL=https://blackshield.chaplau.com \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/vm-scanner-managed-linux.sh)
cd deploy/vm-scanner/managed
# Edit .env.vm-scanner, replace BLACKSHIELD_API_KEY, and choose managed-local only if approved.
sudo ./install-managed-vm-scanner.sh

Advanced one-shot local validation

bash
sudo install -d -m 750 /var/lib/blackshield/vm-scanner
docker run --rm \
  -e BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
  -e BLACKSHIELD_API_KEY=sp_xxxx \
  -e VMS_COLLECTOR_MODE=file \
  -e OSSEC_ALERTS_FILE=/var/ossec/logs/alerts/alerts.json \
  -e SCAN_INTERVAL_SECONDS=0 \
  -v /var/ossec/logs/alerts:/var/ossec/logs/alerts:ro \
  -v /var/lib/blackshield/vm-scanner:/tmp/vms-state \
  public.ecr.aws/blackshield-security/vms-scanner:1.0.6

Health, logs, and alert-file verification

bash
sudo systemctl status blackshield-vms-scanner --no-pager
sudo -u blackshield-vms-scanner test -r /etc/blackshield/vm-scanner.env
sudo -u blackshield-vms-scanner test -r /var/ossec/logs/alerts/alerts.json
sudo journalctl -u blackshield-vms-scanner -n 100 --no-pager
curl http://localhost:8080/health
curl http://localhost:8080/metrics

Cloud collector environment example

bash
VMS_COLLECTOR_MODE=s3
VMS_SOURCE_URI=s3://blackshield-vm-alerts/prod/web-01/alerts.json
OSSEC_STATE_FILE=/tmp/vms-state/ossec-state.json
SCAN_INTERVAL_SECONDS=60

Understand and customize

Use the guided steps below when you want to tailor the rollout, validate ownership, or expand the deployment safely.

Step 1

Use the managed Linux path first

The managed installer makes VM scanner mean a working host scanner: it defaults to existing Wazuh or OSSEC alerts, while OSSEC local installation is an explicit customer-approved option.

  • Existing Wazuh manager, OSSEC server, or OSSEC local install: generate `deploy/vm-scanner/managed/`, set the ingestion key, and run the installer.
  • Fresh Ubuntu/Debian VM: set `BLACKSHIELD_OSSEC_MODE=managed-local` only after approving the OSSEC GPLv2 install path.
  • AWS CDK path: create a Python 3.11 venv, export BLACKSHIELD_API_URL and SCANNER_IMAGE_URI, then run `cdk bootstrap && cdk deploy`.
  • The existing-source path reuses `/var/ossec/logs/alerts/alerts.json` and makes sure JSON output is enabled.
  • Wazuh agent-only endpoints normally do not own the manager-side `alerts.json`; install BlackShield on the manager/server/local host, or use the S3/GCS sync path.
  • Fleet-noisy package and update activity is grouped with host/IP evidence; intrusion-like alerts stay per-host with actor and provenance fields.
  • Rotate any `sp_...` key pasted into terminals, tickets, or chat before retesting.

What success looks like

Rotate any `sp_...` key pasted into terminals, tickets, or chat before retesting.

All Deployment Guides

Helpful context

Wazuh Linux agent installWazuh alert filesOSSEC JSON outputOSSEC unattended install

Step 2

Generate the managed bundle

Download the recommended managed bundle first. It installs `/usr/local/bin/blackshield-vms-scanner-run`, the native package under `/opt/blackshield/vm-scanner/venv`, and a restartable systemd unit.

  • Managed Linux: generate `deploy/vm-scanner/managed/` for the default Ubuntu/Debian native service.
  • The generated env defaults to `BLACKSHIELD_OSSEC_MODE=existing`; compatibility `auto` and explicit `managed-local` remain supported.
  • `managed-local` downloads and installs OSSEC GPLv2 local mode, so use it only after customer approval.
  • Scanner state persists in `/var/lib/blackshield/vm-scanner/ossec-state.json` so restarts do not duplicate ingestion.
  • Advanced existing-source modes remain available below for Docker Compose, Docker-backed systemd, cron, AWS Fargate, and GCP Cloud Run.

What success looks like

Advanced existing-source modes remain available below for Docker Compose, Docker-backed systemd, cron, AWS Fargate, and GCP Cloud Run.

Open source bundles

Step 3

Set the ingestion key and alert source

Create a dedicated ingestion key, then update the generated env file before running the installer.

  • Create an Ingestion API key in Settings -> API Keys and paste the raw `sp_...` value into `deploy/vm-scanner/managed/.env.vm-scanner`.
  • If an ingestion key was pasted into terminal output, tickets, or chat, revoke it and create a new key before retesting.
  • Leave `BLACKSHIELD_OSSEC_MODE=existing` for existing Wazuh/OSSEC alert sources.
  • Set `BLACKSHIELD_OSSEC_MODE=managed-local` only for customer-approved OSSEC local installation.
  • Leave `VMS_COLLECTOR_MODE=file` and `OSSEC_ALERTS_FILE=/var/ossec/logs/alerts/alerts.json` for the managed Linux path.
  • Only override `BLACKSHIELD_VMS_NATIVE_PACKAGE_URL` when you also provide the matching `BLACKSHIELD_VMS_NATIVE_PACKAGE_SHA256`.

What success looks like

Only override `BLACKSHIELD_VMS_NATIVE_PACKAGE_URL` when you also provide the matching `BLACKSHIELD_VMS_NATIVE_PACKAGE_SHA256`.

Open API Keys · Sign-in required

Step 4

Install and verify ingestion

Run the generated installer with sudo, then confirm OSSEC/Wazuh alerts are readable and the native BlackShield service is healthy.

  • Run `sudo ./install-managed-vm-scanner.sh` from `deploy/vm-scanner/managed/`.
  • Check `sudo systemctl status blackshield-vms-scanner --no-pager` and `curl http://localhost:8080/health`; healthy responses report `status: ok` and `total_findings_ingested`.
  • Check `curl http://localhost:8080/metrics` when you want the raw counters without the health wrapper.
  • For failures, run `sudo journalctl -u blackshield-vms-scanner -n 100 --no-pager`, `sudo -u blackshield-vms-scanner test -r /etc/blackshield/vm-scanner.env`, `sudo -u blackshield-vms-scanner test -r /var/ossec/logs/alerts/alerts.json`, and confirm OSSEC/Wazuh service status.
  • Trigger a test OSSEC or Wazuh alert and confirm a new finding appears in the platform Findings view within the next scan interval.
  • Open the finding detail and confirm Host Identity, Network / Actor, Detection Provenance, and Raw Evidence are populated from the alert where available.

What success looks like

Open the finding detail and confirm Host Identity, Network / Actor, Detection Provenance, and Raw Evidence are populated from the alert where available.

View Findings · Sign-in required

Step 5

Use advanced existing-source bundles when needed

Keep the original sidecar and cloud patterns for environments where OSSEC/Wazuh is already managed elsewhere or alerts are synced through object storage.

  • Docker Compose: generate `deploy/vm-scanner/` for an existing local alert file with a containerized scanner.
  • Docker-backed systemd: generate `deploy/vm-scanner/systemd/` when Docker is already your host runtime standard.
  • cron / one-shot: generate `deploy/vm-scanner/cron/` for periodic forwarding without a continuously running scanner.
  • AWS and GCP: generate the S3/GCS bundles when the manager/server host syncs `alerts.json` into object storage.

What success looks like

Existing OSSEC/Wazuh deployments can still use Docker, cron, and object-storage collectors without changing the managed Linux default.

Open source bundles

What success looks like

  • Local runtime health checks return `status: ok` and managed runtimes log successful scans without read failures.
  • `total_findings_ingested` increases after OSSEC or Wazuh generates a new alert.
  • Findings appear in the platform Findings view with host/IP/provenance context and scanner=vms.
Deploy the VM and Host Scanner | BlackShield Docs