Sensorctl

Sensorctl

sensorctl is a command-line tool supporting JSON-RPC method calls to alert-mqttx via MQTT, while providing SSH capability to sensors and agents.

Purpose

• Interact with any sensor.
• Support SSH to sensor (requires password entry).
• Support SSH to agent.
• Support downloading files from agent machine to local for investigation.

Flow Diagram

Installation

Create .env file to configure MQTT and sensor name:

X_API_KEY=NO
MQTT_BROKER=msg.broker.com
MQTT_PORT=8883
MQTT_USERNAME=soc
MQTT_PASSWORD=pass
SENSOR_NAME=sensor-20250526120306.852  # If not set, need to pass through argument

Run ./sensorctl. If usage instructions display, installation was successful.

User Guide

1. SSH to Sensor

Method 1: Using .env file

• Set sensor name in .env file.

• Run command:

  bash ./sensorctl ssh

Method 2: Pass sensor name via argument

• Run command:

  bash ./sensorctl ssh --sensor-name <sensor-name>

Note:

• To exit program, press Ctrl+W.
• Due to SSH via MQTT feature, file editing may not display as expected. Should copy file content instead of typing each character.

2. JSON-RPC

Syntax:

./sensorctl rpc [sensor-name] --method [RPC-method]

Examples:

• Health check sensor:

  bash ./sensorctl rpc [sensor-name] --method healthCheck

• Note when using Wazuh rule files:

  • Replace --filename with --src_file, --file with --dst_file.
  • Add --watch to monitor changes when saving file.

3. SSH to Agent

3.1. Run Always-On Onexar

Run Always-On before SSH to agent:

• Linux agent:

  bash agentctl ar run --agent 003 --command "alwayson-linux0"

• Windows agent:

  bash agentctl ar run --agent 004 --command "alwayson-windows0"

3.2. SSH to Agent

Syntax:

./sensorctl ssh-agent <sensor-name> <agent-id>

Example:

./sensorctl ssh-agent sensor-20250526120306.852 004

3.3. Download file from Agent to local

Syntax:

./sensorctl agent-download <sensor-name> <agent-id> --dst_file <file_path_download>

Example:

./sensorctl agent-download sensor-20250526120306.852 004 --dst_file /home/vagrant/Desktop/test.png

Appendix: RPC Methods List

Method	Description
getAlert	Return alert by UUID
listAlerts	List recent alerts
getAssets	List known assets
getFlows	List correlation between internal assets
getWorldFlows	List correlation of assets with external
getAssetNeighbors	List neighboring assets
getAssetGraph	Return asset correlation topology
getSensorStatus	Return status of sensor & version of binaries
healthCheck	Return overall status of sensor & binaries
shutdownSensor	Shutdown sensor in controlled manner
restartSensor	Restart sensor
triggerUpdate	Trigger config/binary update mechanism
triggerBackup	Trigger ClickHouse backup mechanism
getConfig	Return current configuration of sensor
setConfig	Update new configuration for sensor
getThresholds	Return CEL threshold configuration
setThresholds	Update CEL threshold configuration
getDBStatus	Return database parameters
setRetention	Update ClickHouse data retention time
pruneOldAlerts	Delete alerts older than retention time configuration
reloadCelRules	Reload CEL rules in database
exportPCAP	Export PCAP content by ID
getPCAP	Return PCAP file as bytes
getMetrics	Return runtime metrics
getCacheStats	Return cache metrics
getQueueDepth	Return async process queue
getRuleCoverage	Return rule coverage metrics
clearCaches	Clear cache
scanOsVulns	Start OS vulnerability scan
scanPkgVulns	Start package vulnerability scan
scanHotfixVulns	Start hotfix vulnerability scan
listScapResults	Query SCAP rule assessment results
wazuhDecoders.listFiles	List XML files in decoder directory
wazuhDecoders.getFileContent	Return content of decoder
wazuhDecoders.saveFile	Upload decoder XML file from local to sensor
wazuhRules.listFiles	List XML files in rule directory
wazuhRules.getFileContent	Return content of decoder
wazuhRules.saveFile	Upload rule XML file from local to sensor
suricataRules.listFiles	List files in suricata rule
suricataRules.getFileContent	Return content of suricata rule
suricataRules.saveFile	Upload suricata.rules file from local to sensor
getJobStatus	Return status of async scan process
cancelJob	Cancel async scan process
ackAlert	Acknowledge alert
tagAlert	Update alert tag with metadata
subscribeAlertsRPC	Subscribe to alerts via RPC
unsubscribeAlertsRPC	Unsubscribe to alerts via RPC

Reference

Google Docs

Git repo alert-mqttx/cmd