BLACKSHIELD

Guía pública

Deploy the VM and Host Scanner

Ingest OSSEC and Wazuh host intrusion detection alerts into the platform for correlation with cloud and container findings. Works with Docker Compose, systemd, or ECS Fargate. Audiencia: Security operations teams, infrastructure engineers. Tiempo típico de configuración: 3 minutes.

quickstart

Úsalo si

Ingest OSSEC and Wazuh host intrusion detection alerts into the platform for correlation with cloud and container findings. Works with Docker Compose, systemd, or ECS Fargate.

Audience
Security operations teams, infrastructure engineers
Typical time
3 minutes

Antes de comenzar

  • Confirm OSSEC or Wazuh is running and writing alerts to a JSON file (alerts.json).
  • Default alert path: /var/ossec/logs/alerts/alerts.json
  • Create an ingestion API key in Settings → API Keys with Ingestion scope.

Camino rápido

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

Ejecuta esto

Docker Compose quick start

yaml
services:
  blackshield-vms-scanner:
    image: public.ecr.aws/blackshield-security/vms-scanner:1.0.0
    restart: unless-stopped
    environment:
      BLACKSHIELD_API_URL: "https://api.blackshield.chaplau.com"
      BLACKSHIELD_API_KEY: "sp_xxxx"
      OSSEC_ALERTS_FILE: /alerts/alerts.json
      SCAN_INTERVAL_SECONDS: "60"
      LOG_LEVEL: INFO
    volumes:
      - /var/ossec/logs/alerts:/alerts:ro
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3

systemd sidecar install

bash
# Create secure env file (root-only)
install -d -m 750 /etc/blackshield
install -m 600 /dev/null /etc/blackshield/env
cat > /etc/blackshield/env << 'EOF'
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
BLACKSHIELD_API_KEY=sp_xxxx
OSSEC_ALERTS_FILE=/var/ossec/logs/alerts/alerts.json
SCAN_INTERVAL_SECONDS=60
EOF

# Create and enable service
cat > /etc/systemd/system/blackshield-vms-scanner.service << 'EOF'
[Unit]
Description=BlackShield VM Scanner
After=docker.service
Requires=docker.service

[Service]
Restart=always
EnvironmentFile=/etc/blackshield/env
ExecStartPre=-/usr/bin/docker rm -f blackshield-vms-scanner
ExecStart=/usr/bin/docker run --rm --name blackshield-vms-scanner \
  --env-file /etc/blackshield/env \
  -v /var/ossec/logs/alerts:/var/ossec/logs/alerts:ro \
  -p 8080:8080 \
  public.ecr.aws/blackshield-security/vms-scanner:1.0.0

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now blackshield-vms-scanner

Entender y personalizar

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

Paso 1

Quick start with Docker Compose

Mount the OSSEC alerts file and start the scanner container in under a minute.

  • Add the docker-compose.yml snippet from the Developer Guide next to your Wazuh or OSSEC installation.
  • Set BLACKSHIELD_API_URL, BLACKSHIELD_API_KEY, and OSSEC_ALERTS_FILE in the environment section.
  • Mount /var/ossec/logs/alerts as read-only into the container.
  • Run: docker compose up -d && curl http://localhost:8080/health

Cómo se ve el éxito

Run: docker compose up -d && curl http://localhost:8080/health

All Deployment Guides

Paso 2

Production: systemd sidecar or ECS

For production fleets, run as a systemd service with a secure env file, or as an ECS Fargate task.

  • systemd: create /etc/blackshield/env (mode 600), copy the unit file from the Developer Guide, run: systemctl enable --now blackshield-vms-scanner
  • ECS Fargate: register the task definition from the Developer Guide, pass BLACKSHIELD_API_KEY from Secrets Manager via the secrets array.
  • GCP: deploy as a Cloud Run service with --min-instances 1 to keep it always running.
  • The scanner tracks its file offset across restarts — no duplicate alerts on container restart.

Cómo se ve el éxito

The scanner tracks its file offset across restarts — no duplicate alerts on container restart.

Open API Keys · Requiere inicio de sesión

Paso 3

Verify alert ingestion

Confirm alerts are flowing into the platform and correlating with cloud findings.

  • Check health: curl http://localhost:8080/health — look for findings_ingested_total > 0
  • Open the platform Findings view and filter by scanner=vms.
  • Trigger a test OSSEC alert and confirm it appears within the SCAN_INTERVAL_SECONDS window.
  • Review correlated findings — the platform links host alerts to related cloud and container findings.

Cómo se ve el éxito

Review correlated findings — the platform links host alerts to related cloud and container findings.

View Findings · Requiere inicio de sesión

Cómo se ve el éxito

  • curl http://localhost:8080/health returns status: healthy.
  • findings_ingested_total increases after OSSEC/Wazuh generates an alert.
  • Findings appear in the platform Findings view with scanner=vms.
Deploy the VM and Host Scanner | Docs de BlackShield