Ironclad Agent Usage
Overview
The Ironclad Agent is a lightweight security and management agent that runs in the background on your Windows, Linux, or macOS endpoints. Once installed, it connects your device to your organization's private network, ships security events to your SIEM, and keeps everything running without any day-to-day interaction needed from you.
This guide walks through how to install, configure, upgrade, and delete the agent on an endpoint.
Before you start: You'll need administrator (or root/sudo) privileges on the endpoint.
The Ironclad Agent is modular — you only install what your organization needs. The core components are:
- Ironclad Agent Service — the background daemon that ties everything together. Always installed.
- Ironclad SIEM Agent — forwards security events to your Ironclad SIEM dashboard.
- YARA — a file-scanning engine that lets the SIEM trigger on-demand malware scans on the endpoint.
- Stunnel — encrypts the connection between the endpoint and your SIEM over TLS.
- Logstash (optional) — collects syslog traffic and forwards it for analysis.
- Sysmon (optional) — captures detailed process, network, and file system events for deeper visibility.
Windows Installation
The Windows installer is a standard .exe built with Inno Setup. It must be run with administrator privileges. All configuration is passed as command-line flags — there is no configuration wizard to fill out.
The recommended approach is to run it silently via PowerShell:
.\setup.exe /VERYSILENT /WAZUH_MANAGER="127.0.0.1" /WAZUH_PASSWORD="your-password" /STUNNEL_AGT="agt.your-tenant.mgr.ironclad.decianx.com:443" /STUNNEL_ENR="enr.your-tenant.mgr.ironclad.decianx.com:443" /STUNNEL_INSTALL="true" /WAZUH_INSTALL="true" /LOGSTASH_INSTALL="false" /SYSMON_INSTALL="true"
Important: The “wazuh password” and the “tenant name” are both available and can be viewed in the Ironclad SIEM dashboard in the Agent Deployment section.
Flag Reference
The flags are grouped by the component they control. Components whose flags are omitted are simply skipped — nothing is installed for them.
| Flag | Required? | Description |
|---|---|---|
/WAZUH_MANAGER |
Yes | Hostname of your SIEM manager. Omit to skip installation entirely. |
/WAZUH_PASSWORD |
Yes | Agent Enrollment Token |
/WAZUH_INSTALL=true |
Yes | Explicitly enables SIEM installation. If /WAZUH_MANAGER is provided, this is implied. |
/STUNNEL_INSTALL=true |
Yes | Installs Stunnel to encrypt SIEM traffic over TLS. Requires /STUNNEL_AGT and /STUNNEL_ENR. |
/STUNNEL_AGT |
Yes | Hostname and port for the Stunnel agent connection (e.g. agt.yourorg.decianx.com:1514). |
/STUNNEL_ENR |
Yes | Hostname and port for the Stunnel enrollment connection (e.g. enr.yourorg.decianx.com:1515). |
/LOGSTASH_INSTALL=true |
No | Installs Logstash to collect and forward syslog traffic from this endpoint. |
/SYSMON_INSTALL=true |
No | Installs Sysmon for detailed endpoint event collection. Recommended for high-visibility environments. |
/VERYSILENT |
Yes | Suppresses all UI prompts. Use this for unattended or scripted deployments. |
Linux and macOS Installation
On Linux and macOS, installation is handled by a shell script included in the agent bundle. It auto-detects the operating system, CPU architecture (x64 or ARM64), and package manager, then installs the right binaries and registers the appropriate services.
sudo ./install.sh \
--wazuh-manager wazuh.yourorganization \
--wazuh-password <provided-by-decian> \
--install-wazuh true \
--install-stunnel true \
--stunnel-agt agt.yourorg.decianx.com:1514 \
--stunnel-enr enr.yourorg.decianx.com:1515
Flag Reference
| Flag | Default | Description |
|---|---|---|
--wazuh-manager |
127.0.0.1 |
Hostname of your Wazuh SIEM manager. |
--wazuh-password |
— | Enrollment password for the Wazuh manager. Provided by Decian. |
--install-wazuh |
false |
Set to true to install and configure the Wazuh agent. |
--install-stunnel |
false |
Set to true to install Stunnel and encrypt Wazuh traffic. |
--stunnel-agt |
agt.default.decianx.com |
Stunnel agent endpoint hostname. |
--stunnel-enr |
enr.default.decianx.com |
Stunnel enrollment endpoint hostname. |
--install-logstash |
false |
Set to true to install Logstash for syslog collection. |
--install-ui |
false |
Set to true to install the Ironclad Agent UI tray application. |
What Happens During Installation
Here's a summary of what the installer does, step by step, so there are no surprises:
- Copies agent files to
C:\Program Files\decianx-agent\(Windows) or/opt/decianx-agent/(Linux) or/usr/local/decianx-agent/(macOS). - Writes
config.yamlwith the agent's runtime configuration, including Logstash settings if that component was selected. - Starts the Ironclad Agent Service as a background process (Windows) or a systemd/launchd service (Linux/macOS).
- Installs Stunnel (if selected) and registers it as a named service so it starts automatically on reboot.
- Installs Logstash (if selected), configures it to collect syslog on port 514, and registers it as a service.
- Installs the Ironclad agent (if selected), rewrites
ossec.confto a clean minimal configuration, enables remote command execution for active response, sets the enrollment password, and starts the Wazuh service. - Deploys YARA (if Wazuh is selected) — copies
yara64.exeand a seed ruleset to the agent directory, and installs theyara.batactive-response script so your SIEM manager can trigger on-demand file scans remotely. - Installs Sysmon (if selected) — downloads the latest Sysmon binary and applies Decian's recommended configuration automatically.
- Configures Windows audit policies and logging (if Wazuh is selected) to ensure the event IDs your SIEM rules rely on are actually being generated.
The Wazuh ossec.conf rewrite in step 6 is intentional. Wazuh ships a verbose default configuration that can conflict with the policy your SIEM manager pushes down. The installer strips it to just the connection and enrollment block, so the manager stays fully in control of agent policy.
Deleting the Agent
Windows
Run the uninstaller from an elevated PowerShell prompt. Change out of the agent install directory first so Windows is not holding the folder open while the uninstaller removes files.
Set-Location C:\
Start-Process -FilePath "C:\Program Files\decianx-agent\unins000.exe" `
-ArgumentList "/VERYSILENT","/SUPPRESSMSGBOXES","/NORESTART","/LOG=C:\Temp\decianx-agent-uninstall.log"
The uninstall normally takes about 45 seconds. The command runs silently, so no progress window is shown.
The Windows uninstaller stops and removes the Ironclad-related services, removes Ironclad if it was installed by the agent installer, removes Stunnel and Logstash service registrations, deletes C:\ProgramData\decianx-agent, and removes the agent files under C:\Program Files\decianx-agent. The tools folder may be preserved because it is intentionally excluded from uninstall cleanup for upgrade/reinstall workflows.
To confirm the agent was removed, run:
Get-Service decianx-agent-service,Decianx-Agent,Decianx-tls-tunnel,Decianx-syslog-receiver,wazuh-agent -ErrorAction SilentlyContinue
Test-Path "C:\Program Files\decianx-agent"
Get-Content "C:\Temp\decianx-agent-uninstall.log" -Tail 80
Linux
The current Linux bundle installs files and registers services, but does not ship a dedicated uninstall script. To remove the agent service and installed files, run:
sudo systemctl disable --now decianx-agent 2>/dev/null || true
sudo systemctl disable --now decianx-stunnel 2>/dev/null || true
sudo rm -f /etc/systemd/system/decianx-agent.service
sudo rm -f /etc/systemd/system/decianx-stunnel.service
sudo systemctl daemon-reload
sudo rm -rf /opt/decianx-agent /etc/decianx-agent /var/log/decianx-agent
sudo rm -f /etc/xdg/autostart/decianx-ui.desktop
If Ironclad or Logstash were installed for this endpoint, remove them using the operating system's package manager and your organization's standard endpoint cleanup process.
macOS
The current macOS bundle installs files and registers launchd services, but does not ship a dedicated uninstall script. To unload the Ironclad services and remove installed files, run:
sudo launchctl bootout system /Library/LaunchDaemons/com.decianx.agent.plist 2>/dev/null || true
sudo launchctl bootout system /Library/LaunchDaemons/com.decianx.stunnel.plist 2>/dev/null || true
launchctl bootout gui/$(id -u) /Library/LaunchAgents/com.decianx.ui.plist 2>/dev/null || true
sudo rm -f /Library/LaunchDaemons/com.decianx.agent.plist
sudo rm -f /Library/LaunchDaemons/com.decianx.stunnel.plist
sudo rm -f /Library/LaunchDaemons/com.decianx.logstash.plist
sudo rm -f /Library/LaunchAgents/com.decianx.ui.plist
sudo rm -rf /usr/local/decianx-agent /usr/local/etc/decianx-agent /usr/local/var/log/decianx-agent
If Ironclad, Logstash, or other optional components were installed, remove them using the normal macOS package or service removal process approved for the customer environment.
Upgrading the Agent
The installer includes an upgrade script that persists on the endpoint across uninstall/reinstall cycles. Use the upgrade script when you want to move an existing installation to a specific published build or to the latest available build.
Windows
Run the upgrade script from an elevated PowerShell prompt:
*You must be in the the “C:\Program Files\decianx-agent\tools” directory to run the upgrade script
.\agent_upgrade.ps1 1.0.0.371
To target a specific build, replace 1.0.0.371 with the build number:
.\agent_upgrade.ps1 1.0.0.370
If the repository requires credentials, pass them with the request:
Linux and macOS
Run the upgrade script with root privileges:
sudo /etc/decianx-agent/tools/agent_upgrade.sh --version latest
On macOS, the script is stored under /usr/local/etc:
sudo /usr/local/etc/decianx-agent/tools/agent_upgrade.sh --version latest
To target a specific build, replace latest with the build number:
sudo /etc/decianx-agent/tools/agent_upgrade.sh --version 1.0.5.001
If the repository requires credentials, pass them with the request:
sudo /etc/decianx-agent/tools/agent_upgrade.sh \
--version latest \
--repo-user <username> \
--repo-pass <password>
The upgrade script stops the agent services, downloads the requested build from Artifactory, installs it, and restarts the services. Linux and macOS upgrade logs are written under the platform log directory shown below.
Installation Paths Reference
| Platform | Agent binaries | Config & tools | Logs |
|---|---|---|---|
| Windows | C:\Program Files\decianx-agent\ |
C:\Program Files\decianx-agent\tools\ |
C:\Program Files\decianx-agent\log.txt |
| Linux | /opt/decianx-agent/ |
/etc/decianx-agent/tools/ |
/var/log/decianx-agent/ |
| macOS | /usr/local/decianx-agent/ |
/usr/local/etc/decianx-agent/tools/ |
/usr/local/var/log/decianx-agent/ |