jt-wazuh-mgr v1.32.3
English | 繁體中文 | 日本語
A powerful web-based management tool for Wazuh agents in cluster environments.
Purpose: This tool is designed to supplement the Wazuh Dashboard by providing missing or inconvenient management features. It is NOT intended to replace the Wazuh Dashboard, but to complement it.
Recommended: Use the Web UI as the primary interface — it's the main feature of this tool with full functionality.
🌐 Project site: https://jasoncheng7115.github.io/jt-wazuh-mgr/
⚡ One-line Install / Upgrade / Uninstall
Run as root on your Wazuh Manager (Master node in cluster mode):
# Install
curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-wazuh-mgr/main/install.sh | sudo bash
# Upgrade (re-run the installer; your config.yaml is preserved)
curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-wazuh-mgr/main/install.sh | sudo bash
# Uninstall
curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-wazuh-mgr/main/uninstall.sh | sudo bash
The installer downloads the app to /opt/jt-wazuh-mgr, installs Python dependencies, and registers + starts a systemd service (jt-wazuh-mgr). After installation, open https://YOUR_WAZUH_MANAGER_IP:5000 and log in with your Wazuh API credentials.
Already installed? You can also upgrade/uninstall locally:
curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-wazuh-mgr/main/install.sh | sudo bash # upgrade
sudo bash /opt/jt-wazuh-mgr/uninstall.sh # uninstall
📦 Offline install / upgrade (no internet on the manager)
On a machine with internet access, download the release and the Python wheels for the manager's Python version (/usr/bin/python3 -V on the manager; 3.9 below):
VER=X.Y.Z # a release tag from https://github.com/jasoncheng7115/jt-wazuh-mgr/releases, without the "v"
curl -fsSLO https://github.com/jasoncheng7115/jt-wazuh-mgr/archive/refs/tags/v$VER.tar.gz
tar xzf v$VER.tar.gz
docker run --rm -v "$PWD":/w -w /w python:3.9-slim \
pip download --only-binary=:all: -r jt-wazuh-mgr-$VER/requirements.txt -d jt-wazuh-mgr-$VER/wheels
tar czf jt-wazuh-mgr-$VER-offline.tar.gz jt-wazuh-mgr-$VER
Copy the archive to the manager, then as root (the same two commands install and upgrade; config.yaml is kept):
tar xzf /root/jt-wazuh-mgr-X.Y.Z-offline.tar.gz -C /root
bash /root/jt-wazuh-mgr-X.Y.Z/install.sh --offline
grep __version__ /opt/jt-wazuh-mgr/lib/__init__.py && systemctl is-active jt-wazuh-mgr
--offline never touches the network and does not need pip on the manager. The full procedure (without Docker, backup and rollback, manual steps for v1.19.0 and earlier, wheels that do not match): Offline install & upgrade.
Features
Language
- English / Traditional Chinese (繁體中文) / Japanese (日本語), chosen from the language menu in the header, where each language is listed under its own name; the preference is saved per browser.
Agent Management
- View all agents with real-time status
- Advanced filtering (status, group, node, OS, version, IP, name, sync)
- Convenient multi-select for batch operations
- Distribution bar: visual statistics bar showing agent distribution by status, OS, version, group, node, or sync status
- Click on segments to filter agents
- Animated transitions when switching views
- Auto-refresh stats: top statistics refresh every 10 seconds with slide animation
- Group operations: add to / remove from group, merge into another group, keep in a specific group only, rename group, import from CSV (with preview), export to CSV
- Batch operations: restart, reconnect, delete, upgrade
- Move to Node (planned): migrate agents to a specific node via HAProxy integration (under development)
- Health check and duplicate detection
- Queue DB size check: monitor agent queue database usage with batch clean support
- Agent upgrade with real-time progress tracking
Cluster Support
- Full master/worker cluster support
- Node service status monitoring
- Edit ossec.conf for master and worker nodes
- Restart services on any node
- Download cluster.key from the master node
- WPK file management: upload and delete WPK upgrade files
- Sync status checking between master and workers (Rules, Decoders, Groups, Keys, Lists, SCA), including a view of files that differ between nodes
- SSH remote management for worker nodes
- Email Alerts management: form-based management of
<email_alerts> rules in ossec.conf — add/edit/delete without manual XML editing, one-click sync to all worker nodes, auto-backup before every change
Statistics & Reports
- Statistics by status, group, node, OS, version, network segment
- Sortable columns in all statistics tables
- Export to JSON/CSV
Rules Viewer
- Browse all rules in a sortable, searchable, paginated table; filter by level range, file, and type (Custom/Built-in)
- Rule hierarchy visualization as a collapsible tree (parent/child via
if_sid, if_matched_sid)
- Click any Rule ID to jump to its hierarchy view; expand to view full rule XML with syntax highlighting
Rule Packs
- Catalogue of detection rule series maintained by Jason Tools, installable from the UI
- Each pack bundles rules, decoders and CDB lists behind a manifest; open one to see the files it installs, where they go, and which rule IDs it claims
- Install is guarded: rule-ID conflict detection, backup of anything overwritten,
wazuh-analysisd -t validation, and full rollback if any step fails
- The list shows the version installed on this Wazuh manager next to the version this jt-wazuh-mgr ships, marks the packs that can be updated, and counts them; a manager that already has a newer version is not offered a downgrade
- Update an installed pack when a new release brings a newer version. A plan comes first: what happens to every file (added, updated, removed, or left because you changed it), then the update runs with the same backup, validation and rollback. Lists the site maintains (approved tools, internal networks, lists an updater fills) are never replaced, new files reach agent groups that already exist, and the agent-side steps added since your version are listed
- Removal restores replaced files, refuses to discard rule files you edited, and keeps the lists the site maintains
- Setup guide for packs that depend on configuration the manager cannot apply (Sysmon filters, auditd, agent groups, syslog forwarding): numbered steps, copyable commands, a way to check each one, and the agent-side files to view or download
- A pack whose files were copied in by hand is recognised as installed but untracked, instead of being reported as conflicting with itself
- Active response, opt-in: a pack can offer responses (for example, block the source of a brute force). None is enabled by installing; each states what it blocks, where, and the risk. Enabling writes a marked block into
ossec.conf on every cluster node, validates each node and rolls every node back if one rejects it; disabling restores the file exactly. The page shows each node's white_list and which managers still need a restart
- Quiet on a fresh install: no pack needs a site list to stop flooding. A successful login alerts only when it matters (built-in administrator, public address, right after failures, or an account seen from an address for the first time); allowlists are optional tuning
- Account security across services: packs tag every login attempt the same way, so one address spraying the SSO, the mail server and Nextcloud at once, or logging in right after it, is one alert rather than three unrelated ones; mail accounts get takeover chains (a new-address login followed by forwarding, password or 2FA changes), SMTP/ActiveSync spraying and mailbox harvesting
Security
- Input validation for all parameters; command-injection and path-traversal protection
- Secure file-upload handling
- Complete logging & audit of operations
- API user management: create, modify, and manage Wazuh API users and roles
- Brute-force protection (IP lockout: 3 failed logins = 30-minute lockout)
- See SECURITY.md for the security policy and hardening notes
- See TEST-PLAN.md for what is verified before a release, and what is not
Screenshots
| |
|---|
| Login | |
| Agent List | |
| Agent Actions & Queue DB | |
| Groups | |
| Nodes | |
| WPK Files Management | |
| Rules Viewer | |
| API Users | |
| Logs Viewer | |
| Edit ossec.conf | |
| Agent Upgrade | |
| Agent Detail | |
| Inventory (search across every agent) | |
| Rule Packs | |
| Rule Pack Detail | |
| Rules by File Name | |
| Statistics | |
Quick Start
Requirements
- Python 3.8+
- Wazuh Manager 4.x (tested with 4.14.7 and 4.14.8)
- The installer puts the Python dependencies in
/opt/jt-wazuh-mgr/vendor, not in the system Python. That works where pip into the system is refused (Ubuntu 24.04, Debian 12) and survives an OS upgrade that changes the Python version
- Must be installed on the Wazuh Manager (for cluster mode, install on the Master node)
Install
Use the one-line installer above, or run manually after cloning:
python3 -m pip install --target vendor -r requirements.txt
./wazuh_agent_mgr.py --web --ssl-auto
Open https://YOUR_WAZUH_MANAGER_IP:5000 and log in with your Wazuh API credentials.
Note: Log in with an API user of the tool's own (log in once as wazuh and create one on the API Users tab, or use create_api_user.py), or with wazuh. Avoid wazuh-wui: it is the dashboard's account, and when its tokens are revoked on the dashboard's side this tool is logged out too. The passwords of the default accounts are in wazuh-install-files.tar (created during installation) or in your installation records.
--ssl-auto serves the Wazuh dashboard's certificate when the dashboard runs on the same host, and otherwise generates a self-signed one.
Other Options
# Custom port
./wazuh_agent_mgr.py --web --port 8443 --ssl-auto
# Custom SSL certificate
./wazuh_agent_mgr.py --web --ssl-cert /path/to/cert.pem --ssl-key /path/to/key.pem
systemd Service
The installer registers and starts a systemd service automatically. Management commands:
systemctl status jt-wazuh-mgr # Check status
systemctl restart jt-wazuh-mgr # Restart service
journalctl -u jt-wazuh-mgr -f # View logs
CLI Usage
# List all agents
./wazuh_agent_mgr.py agent list
# Filter agents
./wazuh_agent_mgr.py agent list --status=Active --group=production
# Quick status queries
./wazuh_agent_mgr.py agent disconnected
./wazuh_agent_mgr.py agent pending
# Group management
./wazuh_agent_mgr.py group list
./wazuh_agent_mgr.py group add-agent webservers 001 002 003
# Node management
./wazuh_agent_mgr.py node list
./wazuh_agent_mgr.py node reconnect 001 002
# Statistics
./wazuh_agent_mgr.py stats report
Output Formats
Supports three output formats: table (default), json, csv.
./wazuh_agent_mgr.py agent list --format=json
./wazuh_agent_mgr.py agent list --format=csv > agents.csv
./wazuh_agent_mgr.py stats report --format=json > report.json
Dry-Run Mode
All write operations support --dry-run to preview actions without executing:
./wazuh_agent_mgr.py agent delete 001 --dry-run
# Output: [DRY-RUN] Would execute: /var/ossec/bin/manage_agents -r 001
Configuration
config.yaml (a template is included; no credentials are required for Web UI mode):
wazuh_path: /var/ossec
# API settings
# Web UI mode: username/password NOT required (users log in via the browser)
# CLI mode: username/password REQUIRED for commands like ./wazuh_agent_mgr.py agent list
api:
enabled: false # set to true for CLI mode
host: localhost
port: 55000
username: wazuh # only for CLI mode
password: "" # only for CLI mode, see wazuh-install-files.tar
verify_ssl: false
# Web UI settings
web:
session_timeout: 120 # minutes
# Optional: SSH for remote worker node management
# ssh:
# enabled: true
# key_file: /root/.ssh/wazuh_cluster_key
# nodes:
# worker01:
# host: 192.168.1.100
# port: 22
# user: root
Web UI vs CLI Configuration
| Setting | Web UI | CLI |
|---|
api.enabled | Not required | true |
api.username | Not required (login via browser) | Required |
api.password | Not required (login via browser) | Required |
ssh.* | Optional (for remote node management) | Optional |
Internationalization (i18n)
The UI ships in English and translates to Traditional Chinese and Japanese
entirely on the client side. UI strings live in lib/i18n_engine.js, which is
embedded into lib/web_ui.py by tools/build_i18n.py. To extend or edit
translations:
# edit lib/i18n_engine.js, then re-embed into web_ui.py
python3 tools/build_i18n.py
Adding a language means adding its key to I18N and I18N_PATTERNS and a code
to SUPPORTED; nothing else in the engine is language-specific.
Tech Stack
- Backend: Python, Flask
- Frontend: Vanilla JavaScript, CSS (no framework)
- Wazuh Integration: CLI commands + REST API
Disclaimer
This software is provided "as is" without warranty of any kind, express or implied. The author is not responsible for any damages or losses arising from the use of this software. Use at your own risk.
Before performing any operations (especially delete, restart, or upgrade), it is strongly recommended to:
- Use
--dry-run mode to preview actions
- Back up important configurations
- Test in a non-production environment first
License
Licensed under the GNU Affero General Public License v3.0.
Author
Jason Cheng (Jason Tools)
