Termineter

Overview

Termineter is a specialized security testing framework designed for advanced metering infrastructure (AMI) smart meter security research. It provides tools for analyzing, testing, and validating smart meter protocols and communications. This framework is essential for utility companies, security researchers, and critical infrastructure professionals conducting authorized security assessments on smart meter systems and AMI networks.

Installation

Prerequisites

# Required packages
sudo apt-get update
sudo apt-get install python3-dev python3-pip

# Git for cloning
sudo apt-get install git

From GitHub

git clone https://github.com/matthewchatham/termineter.git
cd termineter

# Install dependencies
pip3 install -r requirements.txt

# Install termineter
sudo python3 setup.py install

Verify Installation

termineter --version
termineter --help

Architecture Overview

Component	Function
Core Protocol Modules	G3-PLC, DLMS/COSEM protocol support
Meter Interface	Direct meter communication interface
Session Management	Meter connection state handling
Exploit Library	Known vulnerability implementations
Packet Crafting	Custom protocol message generation

Basic Usage

Interactive Shell

# Start termineter interactive shell
termineter

# Display help
help

# List available commands
help

Command-Line Mode

# Get help for specific function
termineter --help function

# Set configuration
termineter --set option value

Configuration and Setup

Serial Port Configuration

# List available serial ports
ls /dev/tty*

# Set serial port in termineter
set device /dev/ttyUSB0

# Verify connection
ping

Meter Connection Settings

# Set meter baud rate
set baudrate 9600

# Set timeout
set timeout 5

# Configure address
set meter_address 1

Device Detection

# Scan for meters
scan

# List detected devices
devices

# Select specific meter
select device_id

Command	Purpose
`set device`	Serial port device
`set baudrate`	Communication speed
`set timeout`	Response timeout
`scan`	Auto-detect meters

Protocol Commands

Basic Meter Interaction

# Establish connection
connect

# Identify meter
ident

# Read meter info
info

# Disconnect
disconnect

DLMS/COSEM Operations

# Get DLMS attributes
get_attribute class_id instance_id attribute_id

# Set DLMS attributes
set_attribute class_id instance_id attribute_id value

# Invoke DLMS methods
invoke class_id instance_id method_id

G3-PLC Protocol

# Read G3-PLC data
g3_read address

# Write G3-PLC data
g3_write address value

# G3 network status
g3_status

Vulnerability Assessment

Known Meter Vulnerabilities

# Check for default credentials
check_defaults

# Test weak authentication
test_auth_bypass

# Verify encryption implementation
test_encryption

Meter Access Control Testing

# Test read access
test_read_access

# Test write access
test_write_access

# Test function access
test_function_access

Data Extraction

Meter Reading Capture

# Read current consumption
read consumption

# Read cumulative data
read cumulative_energy

# Read time-of-use data
read tou_registers

Historical Data Retrieval

# Read event log
read event_log

# Read load profile
read load_profile

# Read power quality data
read power_quality

Bulk Data Extraction

# Export meter data
export meter_data.csv

# Capture meter stream
capture output.bin

# Analyze captured data
analyze output.bin

Command	Purpose
`read`	Extract meter data
`export`	Export to file
`capture`	Record communication
`analyze`	Process captured data

Exploit Modules

Available Exploits

# List available exploits
show exploits

# Load specific exploit
use exploit_name

# Show exploit options
options

# Run exploit
run

Credential Testing

# Test default passwords
exploit test_default_creds

# Brute force credentials
exploit brute_force_auth

# Bypass authentication
exploit auth_bypass

Data Manipulation

# Test meter tamper
exploit meter_tamper

# Reverse consumption
exploit reverse_energy

# Time manipulation
exploit time_skew

Packet Crafting

Manual Message Generation

# Create DLMS/COSEM packet
craft_packet class=7 instance=0 attribute=2

# Send crafted packet
send_packet packet_data

# Receive response
recv_packet timeout=5

Protocol-Specific Crafting

# Create G3-PLC frame
create_g3_frame destination source data

# Build DLMS APDU
build_apdu tag data

# Construct frame
build_frame apdu

Session Management

Session Control

# Create new session
new_session

# Save session
save_session session_name

# Load session
load_session session_name

# Resume session
resume_session

Multi-Meter Testing

# Connect to multiple meters
connect_multi addresses.txt

# Batch operations
batch_read meters.txt attributes.txt

# Parallel testing
parallel_test device_list.txt

Practical Workflow Examples

Meter Security Assessment

# Connect to meter
connect

# Identify meter type and firmware
ident

# Check default credentials
check_defaults

# Test authentication bypass
test_auth_bypass

# Verify access controls
test_read_access
test_write_access

# Disconnect
disconnect

Vulnerability Scanning

# Enable logging
set log_level debug

# Connect to meter
connect

# Run all vulnerability checks
run_vulnerability_scan

# Export report
export vulnerability_report.txt

# Analyze results
analyze vulnerability_report.txt

Tamper Detection Testing

# Establish baseline
baseline_meter

# Test reverse consumption
test_reverse_flow

# Test clock manipulation
test_time_jump

# Check anti-tamper responses
verify_tamper_detection

Load Profile Analysis

# Connect to meter
connect

# Extract load profile
read load_profile

# Export data
export load_profile.csv

# Analyze patterns
analyze_pattern load_profile.csv

# Generate report
report load_profile_analysis.txt

Data Analysis

Consumption Pattern Analysis

# Import consumption data
import consumption_data.csv

# Analyze patterns
analyze_consumption

# Identify anomalies
detect_anomalies

# Generate visualization
plot consumption.png

Security Event Review

# Extract event log
read event_log

# Filter by type
filter_events event_type

# Timeline analysis
create_timeline events.csv

# Report generation
generate_report events_analysis.txt

Logging and Reporting

Enable Debug Logging

# Set verbose output
set log_level verbose

# Enable protocol tracing
set trace on

# Log to file
set logfile assessment.log

Report Generation

# Create assessment report
report_create

# Export findings
export findings.txt

# Generate executive summary
summary summary.txt

# Archive session data
archive session.tar.gz

Integration with Other Tools

With Scapy

from scapy.all import *
import termineter

# Load termineter module
meter = termineter.MeterInterface('/dev/ttyUSB0')

# Use with scapy
packet = meter.read_raw()

With tcpdump

# Capture meter communications
tcpdump -i any -w meter_traffic.pcap

# Analyze with termineter
termineter
read_pcap meter_traffic.pcap

Automation Scripts

Batch Meter Assessment

#!/bin/bash
METER_LIST="meters.txt"

while IFS= read -r meter; do
  echo "[*] Testing meter: $meter"
  termineter << EOF
set device $meter
connect
ident
check_defaults
test_auth_bypass
disconnect
quit
EOF
done < "$METER_LIST"

Continuous Monitoring

#!/bin/bash
INTERVAL=300  # 5 minutes

while true; do
  echo "[*] Monitoring meter at $(date)"
  termineter << EOF
connect
read consumption
read power_quality
disconnect
quit
EOF
  sleep $INTERVAL
done

Vulnerability Database Update

#!/bin/bash
# Update vulnerability definitions
git clone https://github.com/matthewchatham/termineter.git
cd termineter
python3 setup.py install

Security Best Practices

Authorized Testing Only

Ensure written authorization from utility company before testing
Document all testing activities and findings
Follow responsible disclosure procedures
Maintain confidentiality of sensitive infrastructure data

Data Protection

# Encrypt assessment data
tar -czf assessment.tar.gz assessment_data/
gpg -c assessment.tar.gz

# Secure deletion
shred -vfz -n 3 sensitive_data.txt

Documentation

# Log all activities
enable logging

# Record meter identifiers
save_session meter_assessment_$(date +%Y%m%d)

# Archive findings
archive assessment_data_$(date +%Y%m%d).tar.gz

Troubleshooting

Connection Issues

# Verify serial port
ls -la /dev/ttyUSB*

# Check port permissions
sudo usermod -a -G dialout $USER

# Test communication
termineter set device /dev/ttyUSB0 && ping

Meter Not Responding

# Adjust timeout
set timeout 10

# Change baud rate
set baudrate 19200

# Try different protocol
set protocol dlms

Permission Errors

# Grant serial port access
sudo usermod -a -G dialout $USER

# Log out and back in for changes to take effect
newgrp dialout

Module Import Errors

# Reinstall dependencies
pip3 install --upgrade -r requirements.txt

# Verify Python version
python3 --version  # Must be 3.6+

# Check package installation
pip3 list | grep termineter

Advanced Topics

Custom Exploit Development

# Create custom exploit module
class CustomExploit:
    def __init__(self, meter):
        self.meter = meter
    
    def exploit(self):
        # Custom vulnerability test
        pass

Protocol Extension

# Extend protocol support
from termineter.protocols import DLMS

class CustomProtocol(DLMS):
    def custom_method(self):
        pass

Wireshark — Protocol analysis for captured meter traffic
scapy — Packet manipulation and crafting
OpenForms — DLMS/COSEM reference implementation
GridLAB-D — Smart grid simulation
OpenAMI — Open Advanced Metering Infrastructure

Important Legal Notice

Termineter is intended for authorized security research and testing only. Unauthorized access to critical infrastructure is illegal. Always obtain proper authorization and follow responsible disclosure practices when testing smart meter systems.