Skip to content

gglessner/MQulator

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
lib
lib
 
 
.gitattributes
.gitattributes
 
 
MQbridge.py
MQbridge.py
 
 
MQbrowse.py
MQbrowse.py
 
 
MQrest.py
MQrest.py
 
 
MQulator.py
MQulator.py
 
 
MQwrite.py
MQwrite.py
 
 
README.md
README.md
 
 
requirements.txt
requirements.txt
 
 

Repository files navigation

MQulator

MQulator is a Python tool for browsing messages from IBM MQ queues using the IBM MQ Java client via JPype. It iterates through all combinations of servers, queue managers, channels, queues, and TLS certificates, connecting to each and displaying any messages found.

In the spirit of Joe Grand's JTAGulator, which tries all wiring combinations to identify JTAG, TTL serial, I2C, or SPI ports on hardware, MQulator is designed for security testers who may not be completely sure which IBM MQ settings belong together. It automates the process of trying all possible combinations to help identify valid connection parameters.

Features

  • Connects to IBM MQ using Java client libraries
  • Supports TLS with JKS certificates
  • Iterates all combinations of connection parameters
  • Prints detailed status and browsed messages

Requirements

For Java-based tools (MQulator.py, MQbrowse.py, MQwrite.py):

  • Python 3.7+
  • Java (JRE/JDK) installed and accessible in your PATH
  • IBM MQ Java client JAR: mq.allclient-9.4.1.0.jar
  • JSON JAR: json-20240303.jar
  • JMS API JAR: javax.jms-api-2.0.1.jar
  • Python packages: see requirements.txt

For REST API tools (MQrest.py, MQbridge.py):

  • Python 3.6+
  • Python packages: requests, urllib3
  • No Java required!
  • For JKS/PKCS#12 certificate support:
    • OpenSSL (for PKCS#12 conversion)
    • Java keytool (for JKS conversion)

Where to get the .jar files

Certificate Support

All tools support JKS, PFX (PKCS12), and PEM certificate formats:

  • MQulator: Automatically detects keystore type based on file extension (.jks, .pfx, .p12, .pem)
  • MQbrowse/MQwrite: Use --keystoretype argument to specify JKS, PKCS12, or PEM (defaults to JKS)
  • PEM files: No password required (password prompts are skipped for PEM keystores)

Place all three JARs in the ./lib/ directory as follows:

./lib/com.ibm.mq.allclient-9.4.1.0.jar   # (rename as needed to match your version, must be .jar)
./lib/json-20240303.jar
./lib/javax.jms-api-2.0.1.jar

Installation

  1. Install Python dependencies: 
    pip install -r requirements.txt
  2. Ensure Java is installed and available in your PATH.
  3. Download the required JAR files and place them in the lib directory as described above.

Usage

Prepare the following input files (one entry per line):

  • server.txt: hostname:port
  • qm.txt: Queue Manager names
  • channel.txt: Channel names
  • queue.txt: Queue names
  • certs.txt: password|filename (JKS file path)

Example command:

python MQulator.py --servers server.txt --qms qm.txt --channels channel.txt --queues queue.txt --certs certs.txt

Optional:

  • --cipher <CIPHER_SUITE>: Override the default TLS cipher suite.
  • --debug-tls: Enable TLS handshake debugging (verbose output for troubleshooting SSL/TLS issues).
  • --disable-cert-verification: Disable server certificate verification (use with caution for testing).

Example Input File Formats

  • server.txt 
    mqhost1.example.com:1414
mqhost2.example.com:1414
  • qm.txt 
    QM1
QM2
  • channel.txt 
    CHANNEL1
CHANNEL2
  • queue.txt 
    QUEUE1
QUEUE2
  • certs.txt 
    mypassword|./mycert.jks
anotherpass|./anothercert.jks
pfxpassword|./mycert.pfx
p12password|./mycert.p12
|./mycert.pem
    Note: For PEM files, leave the password field empty (just use |./file.pem)

Error Handling and Reason Code Lookup

When an IBM MQ error occurs, all tools will attempt to extract the MQ reason code from the exception and print a human-readable explanation. The tools include 74 common IBM MQ reason codes organized by category:

  • Connection and communication errors (e.g., 2009 = MQRC_CONNECTION_BROKEN, 2538 = MQRC_HOST_NOT_AVAILABLE)
  • Authentication and authorization errors (e.g., 2035 = MQRC_NOT_AUTHORIZED, 2089 = MQRC_SECURITY_ERROR)
  • Queue manager errors (e.g., 2058 = MQRC_Q_MGR_NAME_ERROR, 2071 = MQRC_Q_MGR_STOPPING)
  • Queue and object errors (e.g., 2085 = MQRC_UNKNOWN_OBJECT_NAME, 2041 = MQRC_OBJECT_IN_USE)
  • Message operations (e.g., 2033 = MQRC_NO_MSG_AVAILABLE, 2016 = MQRC_GET_INHIBITED)
  • SSL/TLS errors (e.g., 2548 = MQRC_SSL_INITIALIZATION_ERROR, 2552 = MQRC_SSL_PEER_NAME_MISMATCH)
  • System and resource errors (e.g., 2069 = MQRC_STORAGE_NOT_AVAILABLE, 2195 = MQRC_UNEXPECTED_ERROR)

Comprehensive Error Explanations:

  • All tools (MQulator.py, MQbrowse.py, and MQwrite.py): Provide comprehensive explanations with detailed troubleshooting guidance for each reason code

The reason code lookup table (MQ_REASON_CODES dictionary) is easily extensible. If you encounter a code not listed, you can add it to the table for more descriptive error messages.

Object Type Verification

Both MQbrowse.py and MQwrite.py include automatic object type verification to help prevent errors caused by object type mismatches. Before attempting to access any queue or topic, the tools will:

  1. Connect to the queue manager
  2. Check the actual object type using IBM MQ inquire operations
  3. Display the verification results with clear success or mismatch messages
  4. Provide guidance when mismatches are detected

Example Output

When object type matches expectations:

Connected to QMGR1
Checking object type for 'TEST.QUEUE' (expected: queue)...
✓ Object type confirmed: LOCAL QUEUE

Mode: Queue browsing

When there's a type mismatch:

Connected to QMGR1
Checking object type for 'TEST.QUEUE' (expected: topic)...
⚠ Object type mismatch!
  Expected: TOPIC
  Actual:   LOCAL QUEUE
  → Try using --queue instead of --topic

Mode: Topic subscription

For topics that don't exist yet (valid for pub/sub):

Connected to QMGR1
Checking object type for '/test/topic' (expected: topic)...
✓ Object type confirmed: TOPIC (will be created) - Topic will be created if it doesn't exist

Mode: Topic subscription

Supported Object Types

The verification can detect and report:

  • LOCAL QUEUE: Standard local queues
  • REMOTE QUEUE: Queues on remote queue managers
  • ALIAS QUEUE: Queue aliases
  • MODEL QUEUE: Template queues for dynamic queue creation
  • TOPIC: Publish/subscribe topics (existing or to be created)

This feature helps prevent common errors such as:

  • Using --queue when the object is actually a topic
  • Using --topic when the object is actually a queue
  • IBM MQ reason code 2397 (object type error) caused by incorrect object type assumptions

Tool Collection

MQulator now includes 5 different tools for various IBM MQ interaction scenarios:

  1. MQulator.py - Automated combination testing (original tool)
  2. MQbrowse.py - Java-based queue browser and topic subscriber
  3. MQwrite.py - Java-based message writer and topic publisher
  4. MQrest.py - REST API client (simpler, no Java required)
  5. MQbridge.py - HTTP Bridge client (lightweight protocol)

Tool Selection Guide

Use Case Recommended Tool Why
Security Testing MQulator.py Tests all parameter combinations
Production Browsing MQbrowse.py Full-featured, non-destructive
Simple Messaging MQrest.py No Java setup required
Legacy/Firewall MQbridge.py Simple HTTP protocol
Message Replay MQwrite.py Exact message reproduction

Additional Tools

MQbrowse.py

A versatile tool that can both browse messages from IBM MQ queues and subscribe to IBM MQ topics for publish/subscribe messaging. It connects to the specified queue or topic and writes each raw message to its own timestamped file in the logs directory. Each file contains the raw, unaltered message bytes (suitable for re-injection).

Queue Browsing Mode:

# JKS keystore (default)
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1

# PFX keystore
python MQbrowse.py --keystore mycert.pfx --keystoretype PKCS12 --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1

# PEM keystore
python MQbrowse.py --keystore mycert.pem --keystoretype PEM --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1

# TLS without client certificate
python MQbrowse.py --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1

Topic Subscription Mode:

# Subscribe to a specific topic
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --topic /Sports/Football/Scores

# Subscribe with wildcards (+ for single level, # for multiple levels)
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --topic /Sports/+/Scores
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --topic /Sports/#

# Topic subscription without client certificate
python MQbrowse.py --server host:port --qm QM1 --channel CHANNEL1 --topic /News/Technology

Additional Options:

# Disable certificate verification (for testing with self-signed certs)
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --disable-cert-verification

Key Features:

  • Queue Mode: Browses existing messages in a queue, then continues monitoring for new messages
  • Topic Mode: Creates a subscription and waits for new messages published to the topic
  • Object Type Verification: Automatically checks and displays the actual object type before attempting access to help prevent type mismatch errors
  • Use --truststore if you want a different truststore; otherwise, the keystore is used for both.
  • Use --keystoretype PKCS12 for PFX/P12 files, PEM for PEM files, or JKS for JKS files (default).
  • Use --ciphersuite to override the default TLS cipher suite.
  • Use --debug-tls to enable verbose TLS handshake debugging for troubleshooting connection issues.
  • Use --disable-cert-verification to bypass server certificate validation (useful for testing with self-signed certs).
  • The tool will prompt for the keystore password (except for PEM files, which don't require passwords).
  • The --keystore argument is optional - omit it for TLS without client certificate authentication.
  • Each message is logged to its own file: logs/TARGET_NAME_YYYYMMDD_HHMMSS_NNNN.log (queue names or topic strings with special characters converted to underscores).

MQwrite.py

A companion tool that can write raw messages (as logged by MQbrowse.py) to IBM MQ queues or publish them to topics. It reads a log file from the logs directory and writes its contents as a message to the specified queue or publishes it to a topic. You can use it to replay individual message files captured by MQbrowse.py.

Queue Writing Mode:

# JKS keystore (default)
python MQwrite.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --file logs/QUEUE1_YYYYMMDD_HHMMSS_NNNN.log

# PFX keystore
python MQwrite.py --keystore mycert.pfx --keystoretype PKCS12 --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --file logs/QUEUE1_YYYYMMDD_HHMMSS_NNNN.log

# PEM keystore
python MQwrite.py --keystore mycert.pem --keystoretype PEM --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --file logs/QUEUE1_YYYYMMDD_HHMMSS_NNNN.log

Topic Publishing Mode:

# Publish to a specific topic
python MQwrite.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --topic /Sports/Football/Scores --file logs/message.log

# Publish to different topic hierarchies
python MQwrite.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --topic /News/Technology --file logs/tech_news.log
python MQwrite.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --topic /Finance/StockPrices --file logs/stock_data.log

Additional Options:

# Disable certificate verification (for testing with self-signed certs)
python MQwrite.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --file logs/message.log --disable-cert-verification

Key Features:

  • Queue Mode: Writes messages directly to a specific queue
  • Topic Mode: Publishes messages to a topic for distribution to subscribers
  • Object Type Verification: Automatically checks and displays the actual object type before attempting access to help prevent type mismatch errors
  • Use the same connection arguments as MQbrowse.py.
  • Use --keystoretype PKCS12 for PFX/P12 files, PEM for PEM files, or JKS for JKS files (default).
  • Use --debug-tls to enable verbose TLS handshake debugging for troubleshooting connection issues.
  • Use --disable-cert-verification to bypass server certificate validation (useful for testing with self-signed certs).
  • The tool will prompt for the keystore password (except for PEM files, which don't require passwords).
  • The --file argument specifies the log file to replay (one message per file, as produced by MQbrowse.py).

Log File Format:

  • Each log file contains the raw, unaltered bytes of a single message, as produced by MQbrowse.py.
  • MQwrite.py writes the contents of the file as a single message to the queue.

Troubleshooting TLS/SSL Issues

All tools include comprehensive TLS debugging and certificate bypass options:

  • --debug-tls: Enables verbose SSL/TLS handshake debugging output to diagnose connection issues
  • --disable-cert-verification: Bypasses all server certificate validation (useful for testing with self-signed certificates or untrusted CAs)

Common TLS troubleshooting scenarios:

# Debug TLS handshake issues
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --debug-tls

# Test with self-signed certificates
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --disable-cert-verification

# Combine debugging with certificate bypass
python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --debug-tls --disable-cert-verification

MQrest.py

A modern REST API client that provides a much simpler alternative to the Java-based tools. Uses standard HTTP requests instead of complex Java libraries, making it easier to deploy and debug.

Key Advantages:

  • No Java required - Just pip install requests
  • No JAR files to manage
  • Better error handling - HTTP status codes + JSON responses
  • Easier debugging - Standard HTTP tools work
  • Cross-platform - Works anywhere Python works

Certificate Support:

  • Auto-detection - Supports JKS, PKCS#12, and PEM formats
  • Auto-conversion - Converts JKS/PKCS#12 to temporary PEM files
  • Secure cleanup - Temporary files are automatically deleted

Operations Supported:

  • ✅ browse - Browse queue messages (non-destructive)
  • ✅ get - Get/consume messages from queues
  • ✅ put - Put messages to queues
  • ✅ publish - Publish messages to topics
  • ✅ subscribe - Subscribe to topics
  • ✅ qinfo - Get queue information
  • ✅ qminfo - Get queue manager information

Usage Examples:

# Browse queue with JKS certificate
python MQrest.py --cert keystore.jks --cert-password mypass --server https://mqweb:9443 --qmgr QM1 --operation browse --queue TESTQ

# Put message with PKCS#12 certificate
python MQrest.py --cert client.pfx --cert-password secret --server https://mqweb:9443 --qmgr QM1 --operation put --queue TESTQ --message "Hello World"

# Subscribe to topic with basic authentication
python MQrest.py --username admin --password secret --server https://mqweb:9443 --qmgr QM1 --operation subscribe --topic /news/alerts

# Get queue information with PEM certificates
python MQrest.py --cert client.crt --key client.key --server https://mqweb:9443 --qmgr QM1 --operation qinfo --queue SYSTEM.DEAD.LETTER.QUEUE

Requirements:

  • IBM MQ 9.0.5+ with mqweb server enabled
  • REST API enabled on the queue manager
  • Python 3.6+ with requests library

MQbridge.py

A lightweight HTTP Bridge client designed for simple messaging scenarios and environments where the full REST API isn't available or needed.

Key Features:

  • Simple HTTP protocol - Just GET/POST requests
  • Firewall friendly - Standard HTTP traffic
  • Legacy compatible - Works with older MQ versions
  • Same certificate support - JKS, PKCS#12, and PEM formats

Operations Supported:

  • ✅ get - Get/consume messages from queues
  • ✅ put - Put messages to queues
  • ✅ publish - Publish messages to topics
  • ✅ subscribe - Subscribe to topics
  • ❌ browse - Not supported (HTTP Bridge limitation)

Usage Examples:

# Get message with JKS certificate
python MQbridge.py --cert keystore.jks --cert-password mypass --server http://bridge:8080 --qmgr QM1 --operation get --queue REQUEST.QUEUE

# Put message with basic authentication
python MQbridge.py --username bridgeuser --password secret --server http://bridge:8080 --qmgr QM1 --operation put --queue RESPONSE.QUEUE --message "Processing complete"

# Subscribe to topic with PKCS#12 certificate
python MQbridge.py --cert client.pfx --cert-password secret --server https://bridge:8443 --qmgr QM1 --operation subscribe --topic /system/alerts

# Custom bridge path
python MQbridge.py --bridge-path /mq/bridge --username admin --password secret --server http://custom:8080 --qmgr QM1 --operation get --queue TESTQ

HTTP Bridge vs REST API:

Feature MQrest.py (REST API) MQbridge.py (HTTP Bridge)
Protocol IBM MQ REST API v3 Simple HTTP Bridge
Browse Support ✅ Non-destructive ❌ Not available
Queue Info ✅ Admin operations ❌ Message ops only
Complexity Medium Low
Requirements mqweb server HTTP Bridge server

Enhanced Error Analysis

All tools now support enhanced error analysis with the --enhanced-errors flag, which categorizes errors as either:

  • 🏢 Remote End Errors (Queue Manager/Server issues)
  • 💻 Client Side Errors (Local application/configuration issues)

This helps immediately identify whether an error requires server-side investigation or client-side fixes.

Example with enhanced errors:

python MQbrowse.py --keystore mycert.jks --server host:port --qm QM1 --channel CHANNEL1 --queue QUEUE1 --enhanced-errors

Sample output:

Error: MQJE001: Completion Code 2, Reason 2059
IBM MQ Reason Code 2059: MQRC_Q_MGR_NOT_AVAILABLE - The queue manager is not available or not running.

============================================================
ERROR LOCATION ANALYSIS
============================================================
🏢 REMOTE END ERROR (Queue Manager/Server-side issue)
Location: IBM MQ Queue Manager or Server
Action:   Contact MQ administrator or check server status
Details:  Queue manager availability issue
============================================================

These tools are useful for capturing and replaying MQ traffic for testing, troubleshooting, or security research.

License

GNU General Public License v3.0 or later

Author

Garland Glessner gglessner@gmail.com

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages