iot-uart-console-picocom

What this skill does

# 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:
```bash
# 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:**
```bash
python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --command "help"
```

**With Custom Prompt (recommended for known devices):**
```bash
python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --prompt "User@[^>]+>" --command "ifconfig"
```

**Interactive Mode:**
```bash
python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --interactive
```

**Batch Commands from File:**
```bash
# 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):**
```bash
python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --command "help" --json
```

**Debug Mode:**
```bash
python3 .claude/skills/picocom/serial_helper.py --device /dev/ttyUSB0 --command "help" --debug
```

**Session Logging (for observation):**
```bash
# 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.

### Serial Helper Options

```
Required (one of):
  --command, -c CMD         Execute single command
  --interactive, -i         Enter interactive mode
  --script, -s FILE         Execute commands from file

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

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:

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

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

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

# Custom device
--prompt "MyDevice>"
```

### Device Enumeration Example with Serial Helper

Here's a complete example of safely enumerating a device:

```bash
# Set variables for convenience
HELPER="python3 .claude/skills/picocom/serial_helper.py"
DEVICE="/dev/ttyUSB0"
PROMPT="User@[^>]+>"  # Adjust for your device
LOGFILE="/tmp/serial_session.log"

# Get available commands
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "help"

# System information
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "date"
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "runtime"

# Network configuration
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "ifconfig"
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "route"

# Process listing (may need longer timeout)
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --timeout 5 --command "ps"

# File system exploration
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "ls"
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "ls /etc"

# Device identifiers
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "getudid"
$HELPER --device $DEVICE --prompt "$PROMPT" --logfile "$LOGFILE" --command "catmwarestate"
```

**IMPORTANT FOR CLAUDE CODE**: When using this skill, ALWAYS include `--logfile /tmp/serial_session.log` in every command so the user can monitor activity with `tail -f /tmp/serial_session.log`.

## Alternative: Direct picocom Usage (Advanced)

If you need direct picocom access (e.g., for bootloader interaction during boot), you can use picocom directly. However, this is more complex and error-prone.

## Instructions

### 1. Connection Setup

**CRITICAL**: picocom runs interactively and CANNOT be controlled via standard stdin/stdout pipes. Use the following approach:

1. **Always run picocom in a background shell** using `run_in_background: true`
2. **Monitor output** using the BashOutput tool to read responses
3. **Send commands** by using `Ctrl-A Ctrl-S` to enter send mode, or by writing to the device file directly

**Default connection command:**
```bash
picocom -b 115200 --nolock --omap crlf --echo /dev/ttyUSB0
```

**Defaults (unless specified otherwise):**
- **Baud rate**: 115200 (most common for IoT devices)
- **Device**: /dev/ttyUSB0 (most common USB-to-serial adapter)
- **Always use `--nolock`**: Prevents file locking issues unless user specifically requests otherwise

**Alternative baud rates** (if 115200 doesn't work):
- 57600
- 38400
- 19200
- 9600
- 230400 (less common, high-speed)

**Alternative device paths:**
- /dev/ttyUSB0, /dev/ttyUSB1, /dev/ttyUSB2, ... (USB-to-serial adapters)
- /dev/ttyACM0, /dev/ttyACM1, ... (USB CDC devices)
- /dev/ttyS0, /dev/ttyS1, ... (built-in serial ports)

**Essential picocom options:**
- `-b` or `--baud`: Set baud rate (use 115200 by default)
- `--nolock`: Disable file locking (ALWAYS use unless user asks not to)
- `--omap crlf`: Map output CR to CRLF (helps with formatting)
- `--echo`: Enable local echo (see what you type)
- `--logfile <file>`: Log all session output to a file (recommended)
- `-q` or `--quiet`: Suppress picocom status messages
- `--imap lfcrlf`: Map LF to CRLF on input (sometimes needed)

### 2. Detecting Console State

After connecting, you need to identify what state the device is in:

**a) Blank/Silent Console:**
- Press Enter several times to check for a prompt
- Try Ctrl-C to interrupt any running processes
- If still nothing, the device may be in bootloader waiting state - try space bar or other bootloader interrupt keys

**b) Bootloader (U-Boot, etc.):**
- Look for prompts like `U-Boot>`, `=>`, `uboot>`, `Boot>`
- Bootloaders often have a countdown that can b