picocom

IoT UART Console (picocom)

This skill enables interaction with IoT device UART consoles using picocom for security testing and penetration testing operations. It supports bootloader interaction, shell access (with or without authentication), device enumeration, and vulnerability discovery.

Prerequisites

• picocom must be installed on the system
• Python 3 with pyserial library (sudo pacman -S python-pyserial on Arch, or pip install pyserial)
• UART connection to the target device (USB-to-serial adapter, FTDI cable, etc.)
• Appropriate permissions to access serial devices (typically /dev/ttyUSB* or /dev/ttyACM*)

Recommended Approach: Serial Helper Script

IMPORTANT: This skill includes a Python helper script (serial_helper.py) that provides a clean, reliable interface for serial communication. This is the RECOMMENDED method for interacting with IoT devices.

Default Session Logging

ALL commands run by Claude will be logged to /tmp/serial_session.log by default.

To observe what Claude is doing in real-time:

# In a separate terminal, run:
tail -f /tmp/serial_session.log

This allows you to watch all serial I/O as it happens without interfering with the connection.

Why Use the Serial Helper?

The helper script solves many problems with direct picocom usage:

• Clean output: Automatically removes command echoes, prompts, and ANSI codes
• Prompt detection: Automatically detects and waits for device prompts
• Timeout handling: Proper timeout management with no arbitrary sleeps
• Easy scripting: Simple command-line interface for single commands or batch operations
• Session logging: All I/O logged to /tmp/serial_session.log for observation
• Reliable: No issues with TTY requirements or background processes

Quick Start with Serial Helper

Single Command:

python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --command "help"

With Custom Prompt (recommended for known devices):

python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --prompt "User@[^>]+>" --command "ifconfig"

Interactive Mode:

python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --interactive

Batch Commands from File:

# Create a file with commands (one per line)
echo -e "help\ndate\nifconfig\nps" > commands.txt
python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --script commands.txt

JSON Output (for parsing):

python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --command "help" --json

Debug Mode:

python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --command "help" --debug

Session Logging (for observation):

# Terminal 1 - Run with logging
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --prompt "User@[^>]+>" \
  --logfile /tmp/session.log \
  --interactive

# Terminal 2 - Watch the session in real-time
tail -f /tmp/session.log

Note: See OBSERVING_SESSIONS.md for comprehensive guide on monitoring serial sessions.

Monitor Mode (Passive Listening)

NEW FEATURE: Monitor mode is designed for passive UART monitoring where the device outputs logs without prompts or interaction.

Use cases:

• Monitoring boot logs from devices without interactive consoles
• Capturing triggered output when external actions are performed
• Testing if network requests or hardware events generate UART logs
• Baseline vs triggered output comparison

Basic passive monitoring:

python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --monitor \
  --duration 30 \
  --logfile /tmp/uart.log

Monitor with external trigger script:

# Run external script after 5 seconds and capture triggered UART output
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --monitor \
  --duration 60 \
  --trigger-script "python3 /path/to/test_script.py" \
  --trigger-delay 5 \
  --logfile /tmp/triggered_uart.log

Monitor with baseline capture:

# Capture 10s baseline, run trigger at 15s, continue for total 60s
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --monitor \
  --duration 60 \
  --trigger-script "curl http://192.168.1.100/api/reboot" \
  --trigger-delay 15 \
  --baseline-duration 10 \
  --logfile /tmp/reboot_monitor.log

Monitor mode options:

• --duration SECONDS - Total monitoring time (default: 30)
• --trigger-script CMD - External command/script to run during monitoring
• --trigger-delay SECONDS - When to run trigger (default: 5)
• --baseline-duration SECONDS - Capture baseline before trigger (default: 0)
• --logfile FILE - Log all I/O to file
• --json - Output results in JSON format

Output includes:

• Real-time timestamped console output
• Baseline vs trigger vs post-trigger categorization
• Trigger script exit code and output
• Summary statistics (bytes captured in each phase)
• Timeline with all captured data

Serial Helper Options

Required (one of):
  --command, -c CMD         Execute single command
  --interactive, -i         Enter interactive mode
  --script, -s FILE         Execute commands from file
  --monitor, -m             Passive monitoring mode (just listen, no commands)

Connection Options:
  --device, -d DEV          Serial device (default: /dev/ttyUSB0)
  --baud, -b RATE           Baud rate (default: 115200)
  --timeout, -t SECONDS     Command timeout (default: 3.0)
  --prompt, -p PATTERN      Custom prompt regex pattern
  --at-mode, -a             AT command mode for cellular/satellite modems

Monitor Mode Options:
  --duration SECONDS        Monitoring duration (default: 30.0)
  --trigger-script CMD      External script/command to run during monitoring
  --trigger-delay SECONDS   Seconds before running trigger (default: 5.0)
  --baseline-duration SEC   Baseline capture duration (default: 0.0)

Output Options:
  --raw, -r                 Don't clean output (show echoes, prompts)
  --json, -j                Output in JSON format
  --logfile, -l FILE        Log all I/O to file (can tail -f in another terminal)
  --debug                   Show debug information

Common Prompt Patterns

The helper script includes common prompt patterns, but you can specify custom ones:

# Uniview camera
--prompt "User@[^>]+>"

# Standard root/user prompts
--prompt "[#\$]\s*$"

# U-Boot bootloader
--prompt "=>\s*$"

# Custom device
--prompt "MyDevice>"

AT Command Mode (Cellular/Satellite Modems)

IMPORTANT: When interacting with AT command interfaces (cellular modems, satellite modems, GPS modules), use the --at-mode flag. AT interfaces do NOT use shell prompts - they respond with OK, ERROR, or specific result codes.

When to use AT mode:

• Cellular modems (Quectel, Sierra Wireless, u-blox, SIMCom, Telit)
• Satellite modems (Iridium, Globalstar)
• GPS modules with AT interface
• Any device that responds to AT commands with OK/ERROR

Basic AT command usage:

# Single AT command
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --at-mode \
  --command "AT" \
  --logfile /tmp/serial_session.log

# Get modem info
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --at-mode \
  --command "ATI" \
  --logfile /tmp/serial_session.log

# Get IMEI
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --at-mode \
  --command "AT+CGSN" \
  --logfile /tmp/serial_session.log

AT mode enumeration example:

HELPER="python3 .claude/skills/picocom/serial_helper.py"
DEVICE="/dev/ttyUSB0"
LOGFILE="/tmp/serial_session.log"

# Basic connectivity test
$HELPER --device $DEVICE --at-mode --logfile "$LOGFILE" --command "AT"

# Device identification
$HELPER --device $DEVICE --at-mode --logfile "$LOGFILE" --command "ATI"
$HELPER -