Guia público

Deploy the VM and Host Scanner

Install a managed Linux VM scanner that reuses an existing Wazuh or OSSEC alert source, runs Lynis hardening audits, and forwards host findings from one native systemd service. Público: Security operations teams, infrastructure engineers, and platform teams. Tempo típico de configuração: 10 minutes on Ubuntu/Debian systemd hosts.

quickstart

Use isto se

Install a managed Linux VM scanner that reuses an existing Wazuh or OSSEC alert source, runs Lynis hardening audits, and forwards host findings from one native systemd service.

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

Antes de começar

  • 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.
  • Managed Linux installs enable Lynis hardening findings by default through a root-owned audit timer and unprivileged report ingestion.
  • 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.

Caminho rápido

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

Apenas para demonstração

Esta configuração foi concebida para facilitar a utilização. Para implementar clientes de scanner em escala, planeie a sua arquitetura de implementação adequadamente ou contacte-nos para obter as melhores práticas empresariais.

Obtém o bundle de código fonte

Descarrega os ficheiros exatos usados neste guia ou executa o instalador de um só comando para os escrever localmente antes do deploy.

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
Descarregar fonte

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.8 \
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
Descarregar fonte

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.8 \
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
Descarregar fonte

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.8 \
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
Descarregar fonte

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.8 \
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
Descarregar fonte

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.8 \
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
Descarregar fonte

Executar isto

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 LYNIS_ENABLED=true \
  -e LYNIS_REPORT_FILE=/host/lynis/lynis-report.dat \
  -e SCAN_INTERVAL_SECONDS=0 \
  -v /var/ossec/logs/alerts:/var/ossec/logs/alerts:ro \
  -v /var/lib/blackshield/vm-scanner/lynis:/host/lynis:ro \
  -v /var/lib/blackshield/vm-scanner:/tmp/vms-state \
  public.ecr.aws/blackshield-security/vms-scanner:1.0.8

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

Entender e personalizar

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

1

Passo 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.
  • Managed Linux installs enable Lynis by default with a root-owned audit timer; the BlackShield scanner stays unprivileged and ingests the generated report.
  • 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.

Como é o sucesso

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
2

Passo 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`, a restartable scanner unit, and a Lynis audit timer.

  • 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.
  • Lynis reports are written to `/var/lib/blackshield/vm-scanner/lynis/lynis-report.dat` and ingested as host misconfiguration findings.
  • Advanced existing-source modes remain available below for Docker Compose, Docker-backed systemd, cron, AWS Fargate, and GCP Cloud Run.

Como é o sucesso

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

Open source bundles
3

Passo 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.
  • Leave `LYNIS_ENABLED=true` for managed Linux unless your organization does not want host hardening findings from Lynis.
  • Only override `BLACKSHIELD_VMS_NATIVE_PACKAGE_URL` when you also provide the matching `BLACKSHIELD_VMS_NATIVE_PACKAGE_SHA256`.

Como é o sucesso

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

Open API Keys · Requer login
4

Passo 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.
  • For Lynis, check `sudo systemctl status blackshield-lynis-audit.timer --no-pager` and `sudo -u blackshield-vms-scanner test -r /var/lib/blackshield/vm-scanner/lynis/lynis-report.dat`.
  • 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.

Como é o sucesso

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

View Findings · Requer login
5

Passo 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.
  • For Docker-backed Lynis, mount a host-generated Lynis report directory and set `LYNIS_ENABLED=true`; do not use container-local Lynis output as VM evidence.
  • AWS and GCP: generate the S3/GCS bundles when the manager/server host syncs `alerts.json` into object storage.

Como é o sucesso

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

Open source bundles

Como é o sucesso

  • 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.
  • Lynis warnings and suggestions appear as host misconfiguration findings with `source.scanner=lynis` after the audit timer writes its first report.
  • Findings appear in the platform Findings view with host/IP/provenance context and scanner metadata.

Continuar

Keep your rollout moving with the next recommended step.

Revise e priorize achados
Deploy the VM and Host Scanner | Documentação BlackShield