DICOM Endpoint Analyzer

A comprehensive bash script for macOS that tests DICOM endpoints for connectivity, security, and protocol compliance.

Features

• Network Connectivity Testing

  • ICMP ping tests
  • TCP port connectivity verification
  • Connection timeout handling

• Security Analysis

  • TLS/SSL connection testing
  • Certificate validation and inspection
  • Certificate details extraction (subject, issuer, validity dates)
  • Auto-detection of TLS support

• DICOM Protocol Compliance

  • C-ECHO (verification/ping) - mandatory for all DICOM devices
  • C-FIND (query) - patient/study/series queries
  • C-STORE (storage) - safe mode without actual transfers
  • C-MOVE (retrieve) - safe mode without actual transfers
  • Association acceptance testing
  • AE Title validation

• Comprehensive Logging

  • Timestamped log files in logs/ directory
  • Color-coded console output
  • Detailed error messages and debugging information
  • Automatic log file organization

• Report Generation

  • Summary reports in reports/ directory
  • Test results and compliance scores
  • Timestamped for audit trails

Requirements

Dependencies

The script requires the DICOM Toolkit (dcmtk) which includes essential DICOM utilities:

brew install dcmtk

This installs:

• echoscu - C-ECHO client
• findscu - C-FIND client
• storescu - C-STORE client
• movescu - C-MOVE client
• dcmdump - DICOM file inspector

Built-in Tools (pre-installed on macOS)

• bash - Shell interpreter
• openssl - TLS/SSL testing
• nc (netcat) - Network connectivity
• Standard Unix utilities (ping, timeout, etc.)

Installation

1. Clone or download the script:

git clone <repository-url>
cd dicom_query

2. Make the script executable:

chmod +x dicom_endpoint_analyzer.sh

3. Install dependencies:

brew install dcmtk

Usage

Basic Usage

./dicom_endpoint_analyzer.sh <host> <port>

Example:

./dicom_endpoint_analyzer.sh 192.168.1.100 104

Advanced Options

./dicom_endpoint_analyzer.sh [OPTIONS] <host> <port>

Options:
  -c, --calling-ae <AE>    Calling AE Title (default: DICOM_ANALYZER)
  -e, --called-ae <AE>     Called AE Title (default: ANY-SCP)
  -t, --tls <mode>         TLS mode: auto|true|false (default: auto)
  -h, --help               Show help message

Examples

Test a PACS server with specific AE titles:

./dicom_endpoint_analyzer.sh -c MY_CLIENT -e PACS_SERVER pacs.hospital.com 11112

Force TLS connection:

./dicom_endpoint_analyzer.sh --tls true secure.pacs.com 11112

Test with custom AE titles:

./dicom_endpoint_analyzer.sh \
  --calling-ae WORKSTATION1 \
  --called-ae ORTHANC \
  192.168.1.50 4242

Output

The script generates two types of output:

1. Console Output

Real-time color-coded output showing:

• INFO (blue) - general information
• SUCCESS (green) - successful tests
• WARNING (yellow) - non-critical issues
• ERROR (red) - failures

2. Log Files

Located in logs/dicom_analysis_YYYYMMDD_HHMMSS.log:

• Detailed timestamped logs
• Complete command outputs
• Debug information
• Error traces

3. Reports

Located in reports/dicom_report_YYYYMMDD_HHMMSS.txt:

• Executive summary
• Test results overview
• Compliance scores
• Recommendations

Test Phases

Phase 1: Network Connectivity

• ICMP ping test (may be blocked by firewalls)
• TCP port connectivity
• Basic reachability verification

Phase 2: TLS/SSL Security

• TLS handshake testing
• Certificate validation
• Certificate details extraction
• Protocol version detection

Phase 3: DICOM Protocol Compliance

• C-ECHO: Tests basic DICOM association
• C-FIND: Tests query capabilities (Patient Root SOP Class)
• C-STORE: Checks storage capability (safe mode, no actual transfer)
• C-MOVE: Checks retrieve capability (safe mode, no actual transfer)

Phase 4: Report Generation

• Compile results
• Generate summary report
• Calculate compliance scores

Safety Features

The script implements several safety measures:

1. Read-Only Operations: C-ECHO and C-FIND are safe, read-only operations
2. No Data Transfer: C-STORE and C-MOVE tests are skipped by default (safe mode)
3. Timeout Protection: All network operations have configurable timeouts
4. Input Validation: Validates hosts, ports, and AE titles
5. Error Handling: Graceful failure with detailed error messages
6. Non-Destructive: Never modifies remote data or configurations

Common DICOM Ports

• 104: Standard DICOM port (requires root/sudo)
• 11112: Common alternative DICOM port
• 4242: Orthanc default port
• 8042: Orthanc web interface (HTTP, not DICOM)

Troubleshooting

"Port 104 requires elevated privileges"

sudo ./dicom_endpoint_analyzer.sh <host> 104

"Missing required dependencies"

Install dcmtk:

brew install dcmtk

"Association Rejected"

• Verify the Called AE Title matches the remote server configuration
• Check if your IP is whitelisted on the DICOM server
• Confirm the server is accepting connections

"Connection timeout"

• Verify network connectivity
• Check firewall rules
• Ensure the DICOM service is running

"No TLS detected"

Most DICOM servers use plain TCP without TLS. This is normal for:

• Internal hospital networks
• Legacy PACS systems
• Standard DICOM port 104

DICOM Standards Reference

The script tests compliance with:

• DICOM PS3.7: Message Exchange (DIMSE)
• DICOM PS3.8: Network Communication Support
• C-ECHO: Verification Service Class (required for all devices)
• C-FIND: Query/Retrieve Service Class
• C-STORE: Storage Service Class
• C-MOVE: Query/Retrieve Service Class

Security Considerations

1. Authorization: Ensure you have permission to test the target endpoint
2. Network Policy: Verify compliance with organizational security policies
3. Logging: Logs may contain sensitive information (host names, AE titles)
4. Safe Mode: C-STORE and C-MOVE tests are disabled by default
5. TLS: Modern DICOM servers should use TLS for security

License

This script is provided as-is for testing and diagnostic purposes.

Contributing

Contributions are welcome! Please ensure:

• macOS compatibility
• Proper error handling
• Safe, non-destructive operations
• Clear documentation

Support

For issues or questions:

1. Check the troubleshooting section
2. Review log files for detailed error information
3. Verify DICOM server configuration
4. Consult DICOM standard documentation

Version History

• 1.0.0: Initial release with full connectivity and compliance testing