Documentation

Setup, configuration, and administration guide for AlertWatch.

First Launch

AlertWatch is a single binary. No installer, no runtime dependencies.

Linux / macOS

chmod +x alertwatch ./alertwatch

AlertWatch listens on port 8081 by default. Open http://localhost:8081 in your browser.

Windows

alertwatch.exe

Open http://localhost:8081. To run as a Windows service see the service installation guide.

Setup wizard

On first run, AlertWatch detects there are no users and shows the setup wizard. Create your admin account — this becomes the master admin that can manage all other users and configuration.

Keep your admin credentials safe. There is no password recovery mechanism — if you lose the admin password you will need to manually edit alertwatch.yaml to reset it.

Connecting to OpenSearch / Wazuh

After login, go to Settings → Connection and enter your OpenSearch host, port, credentials, and index prefix. AlertWatch connects read-only — it never writes to your OpenSearch indices.

Configuration File

AlertWatch stores all configuration in alertwatch.yaml in the same directory as the binary. Most settings are managed through the UI — edit the file directly only for advanced options.

Minimal example

server: port: 8081 secret_key: change-this-to-a-long-random-string tenants: - name: My Organisation opensearch: host: 192.168.1.10 port: 9200 username: admin password: yourpassword tls: true verify_certs: false index_prefix: wazuh-alerts wazuh_version: 4

Key settings

  • server.port — port AlertWatch listens on (default: 8081)
  • server.secret_key — used to sign session tokens; must be changed before production use
  • server.session_timeout_hours — idle session timeout for desktop users (default: 8)
  • server.session_timeout_mobile_hours — idle timeout for mobile sessions (default: 2)
  • acks.retention_days — how long alert acknowledgements are kept (default: 90, set to 0 for forever)

Security Hardening

Before exposing AlertWatch to a network, complete these steps.

1. Set a strong secret key

The secret_key in alertwatch.yaml signs all session tokens. AlertWatch will refuse to start if it is left as the default value. Generate a random key:

# Linux / macOS openssl rand -hex 32 # Windows PowerShell [System.Convert]::ToBase64String((1..32 | ForEach-Object { [byte](Get-Random -Max 256) }))

Paste the output as the value of server.secret_key in alertwatch.yaml.

2. Restrict config file permissions

The config file contains credentials. On Linux / macOS:

chmod 600 alertwatch.yaml chown alertwatch:alertwatch alertwatch.yaml

3. Run as a dedicated user

Never run AlertWatch as root. Create a dedicated system user:

sudo useradd -r -s /sbin/nologin alertwatch sudo chown -R alertwatch:alertwatch /opt/alertwatch

4. Use a reverse proxy for HTTPS

AlertWatch does not terminate TLS itself. Place it behind nginx or Caddy for HTTPS in production:

# Caddy — automatic HTTPS (Caddyfile) alertwatch.yourdomain.com { reverse_proxy localhost:8081 }

5. Firewall

AlertWatch only needs inbound access on its port from analyst workstations. It makes outbound connections to OpenSearch (port 9200) and the Wazuh API (port 55000) — both read-only.

Local Users

AlertWatch maintains its own user database in alertwatch.yaml. Users are managed through Settings → Users (admin only).

Roles

  • Admin — full access including user management, settings, and configuration
  • User — read access to all dashboards and reports; cannot manage users or change settings

Adding users

Go to Settings → Users → Add User. Set a username, temporary password, and role. The user can change their password after first login via Settings → Change Password.

Password policy

AlertWatch does not enforce a minimum password complexity policy — enforce this through your onboarding process. Passwords are stored as PBKDF2-SHA256 hashes and are never stored in plaintext.

No password recovery. If a user forgets their password, an admin resets it via Settings → Users. If the admin account password is lost, contact support@alertwatch.tech.

LDAP / Active Directory

AlertWatch supports LDAP authentication against Active Directory, OpenLDAP, or any compatible directory. Local users and LDAP users can coexist — LDAP is tried first, then local.

Configuration

Add the following section to alertwatch.yaml:

ldap: enabled: true host: "192.168.1.5" # your DC / LDAP server IP port: 389 # 389 for LDAP, 636 for LDAPS use_tls: false # set true for LDAPS (port 636) bind_dn: "cn=svc-alertwatch,dc=example,dc=com" bind_password: "service-account-password" base_dn: "dc=example,dc=com" user_filter: "(sAMAccountName={username})" # AD # user_filter: "(cn={username})" # OpenLDAP admin_group: "cn=AlertWatch-Admins,ou=Groups,dc=example,dc=com" default_tenant: 0

How it works

  1. AlertWatch binds using the service account (bind_dn) to search for the user
  2. It then attempts to bind as that user with the supplied password to verify credentials
  3. If the user is a member of admin_group, they get the admin role; otherwise viewer
  4. If LDAP fails for any reason, AlertWatch falls back to local user authentication

Active Directory notes

  • Use sAMAccountName as the user filter attribute (shown above)
  • The service account needs read permission on the Users and Groups OUs — no write access required
  • For LDAPS (port 636), set use_tls: true — ensure the DC certificate is trusted by the AlertWatch host

Restart required

AlertWatch reads alertwatch.yaml on startup. After editing the LDAP section, restart the service for changes to take effect.

Mobile Access

AlertWatch includes a mobile-optimised triage view for iOS and Android. Access is controlled at two independent levels — your license, and per-user.

Two gates, not one

  • License entitlement. Mobile access is a licensed feature — included in Professional and Enterprise, not available on Free. This is enforced by your signed license file, cryptographically — a license that doesn't include mobile cannot be made to grant it by editing any file. Any tampering with the license invalidates its signature and the install falls back to Free-tier limits.
  • Per-user permission. Within a license that includes mobile, which specific accounts are allowed to use it is a plain setting in alertwatch.yaml (or set via Settings → Users, admin only) — the same as any other per-user permission stored there.

Enabling mobile access

Go to Settings → Users and enable the Mobile toggle for users who should have mobile access. Users without mobile access will see a restricted view on small screens.

Protect your config file. Because the per-user mobile flag lives in alertwatch.yaml, anyone with write access to that file could edit it directly instead of going through Settings — the same is true of every other permission in that file, including admin role assignment. This isn't a mobile-specific gap; it's why Security Hardening step 2 (restrict the config file to chmod 600, owned by a dedicated non-root account) matters. If an attacker already has write access to your config file, they have effective admin control of AlertWatch regardless of any individual toggle.

Mobile session timeout

Mobile sessions have a shorter idle timeout than desktop sessions (default: 2 hours) to reduce exposure if a phone is left unattended. Configure in alertwatch.yaml:

server: session_timeout_mobile_hours: 2

Browser requirements

iOS 15+ (Safari) and Android 10+ (Chrome) are supported. The full dashboard is accessible on tablet; phone shows a simplified alert triage view.

Tenants

A tenant is a connection to one OpenSearch/Wazuh deployment. AlertWatch supports multiple tenants — useful for organisations managing multiple environments (e.g. production, staging, or separate customer sites).

Adding a tenant

Go to Settings → Connection and add a new tenant entry. Each tenant has its own OpenSearch credentials and index prefix.

Switching tenants

The left panel shows a tenant selector at the top. Selecting a tenant switches all dashboard views to that data source. The selection is per-session and not shared between users.

Multi-source tenants

A single tenant can aggregate data from multiple sources — for example Wazuh alerts and Suricata events in the same timeline. Configure using the sources key in alertwatch.yaml:

tenants: - name: "Combined" opensearch: host: 192.168.1.10 port: 9200 username: admin password: yourpassword tls: true verify_certs: false sources: - display_name: Wazuh index_prefix: wazuh-alerts wazuh_version: 4 - display_name: Suricata index_prefix: filebeat

FIM Configuration

AlertWatch displays File Integrity Monitoring events from Wazuh. The paths that are monitored are configured in the Wazuh agent — AlertWatch reads and displays those events but does not control which paths are watched.

Configuring watch paths in Wazuh

Edit /var/ossec/etc/ossec.conf on each Wazuh agent and add directories to the <syscheck> section:

<syscheck> <directories check_all="yes">/etc</directories> <directories check_all="yes">/usr/bin</directories> <directories check_all="yes" report_changes="yes">/var/www</directories> </syscheck>

Recent change highlighting

The FIM tab can highlight file changes that occurred within a configurable recent window. Set the default window in alertwatch.yaml:

fim: highlight_window_hours: 24 # highlight changes in the last 24 hours

Analysts can also change this interactively in the FIM tab using the Highlight buttons (1h / 6h / 24h / 7d / Off).

Notifications & Scheduled Reports

AlertWatch can send scheduled security reports by email using your SMTP server.

SMTP configuration

smtp: host: smtp.gmail.com port: 587 use_tls: true username: you@yourdomain.com password: your-app-password from_name: AlertWatch
Gmail users: use an App Password, not your account password. Generate one at Google Account → Security → 2-Step Verification → App Passwords.

Scheduled report delivery

Configure scheduled reports in Settings → Notifications. Reports are delivered as PDF attachments and include the sections you select (alerts, compliance, vulnerability summary, FIM activity).

Diagnostics & Support

When something isn't working, AlertWatch captures error information automatically to help support diagnose the problem quickly.

Generating a diagnostic report

  1. Click report issue in the bottom-left corner of the dashboard
  2. The diagnostic modal opens showing any recent client and server errors
  3. Click Copy to clipboard or Email Support to send the report

The report includes the AlertWatch version, browser information, and recent error logs. It does not include alert data or credentials.

Login problems

If you cannot log in, a Contact support link is available at the bottom of the login screen. Email support@alertwatch.tech and include:

  • The exact error message shown
  • Whether you are using local or LDAP authentication
  • Your AlertWatch version (shown in the login screen footer)

Server logs

On Linux, AlertWatch logs are available via systemd:

sudo journalctl -u alertwatch -f

On Windows, logs are written to alertwatch.log in the installation folder.

Updates

AlertWatch is distributed as a single binary. Updating is a drop-in replacement.

Linux / macOS

  1. Stop the service: sudo systemctl stop alertwatch
  2. Replace the binary with the new version
  3. Start the service: sudo systemctl start alertwatch

Your alertwatch.yaml, acknowledgements, and user accounts are preserved — they are stored separately from the binary.

Windows

  1. Stop the service: sc stop AlertWatch
  2. Replace alertwatch.exe with the new version
  3. Start the service: sc start AlertWatch

Release notifications

Professional and Enterprise customers receive email notification when new versions are available. Community edition users can watch the GitHub repository for releases.