picocom-claude-skill

A Claude Code skill for using picocom to interact with IoT device UART consoles for penetration testing operations. This skill enables Claude to help you perform device enumeration, vulnerability discovery, bootloader manipulation, and gain root shells on embedded devices.

---

🔍 MONITORING: Watch What Claude Is Doing

All serial activity is logged to /tmp/serial_session.log

Open a terminal and run:

tail -f /tmp/serial_session.log

This lets you observe every command and response in real-time while Claude interacts with your device!

---

Features

• Python Serial Helper Script: Clean, reliable serial communication with automatic prompt detection
• UART Console Access: Connect to IoT devices via serial console (USB-to-serial, FTDI, etc.)
• Automatic Output Cleaning: Removes command echoes, prompts, and ANSI codes automatically
• Multiple Operation Modes: Single command, interactive, and batch script execution
• Bootloader Interaction: Work with U-Boot and other bootloaders to manipulate boot parameters
• Shell Access: Handle both authenticated and unauthenticated shells
• Device Enumeration: Comprehensive system information gathering
• Vulnerability Discovery: Common IoT security testing procedures
• Privilege Escalation: Techniques for gaining root access
• Firmware Extraction: Extract and analyze device firmware
• Persistence: Establish backdoor access for further testing

What's New: Serial Helper Script

This skill now includes a custom Python helper script (serial_helper.py) that makes interacting with IoT serial consoles much easier and more reliable than using picocom directly.

Why use the helper script?

• Automatic prompt detection (no manual parsing needed)
• Clean output (removes echoes and prompts)
• Proper timeout handling (no arbitrary sleeps)
• Easy to script and automate
• Works without TTY issues

Quick Example:

# Single command with clean output (with logging)
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --logfile /tmp/serial_session.log \
  --command "ifconfig"

# Interactive mode (with logging)
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --logfile /tmp/serial_session.log \
  --interactive

# Batch commands (with logging)
echo -e "help\ndate\nifconfig" > commands.txt
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --logfile /tmp/serial_session.log \
  --script commands.txt

💡 Pro Tip: Run tail -f /tmp/serial_session.log in another terminal to watch the I/O in real-time!

See DEVICE_ENUMERATION.md for a complete example of using the helper script to enumerate a Uniview IoT camera.

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/picocom-claude-skill.git
   cd picocom-claude-skill
   

2. Install dependencies:

   # Debian/Ubuntu
   sudo apt-get install picocom python3-serial
   
   # Arch Linux
   sudo pacman -S picocom python-pyserial
   
   # macOS
   brew install picocom
   pip3 install pyserial
   
   # Or using pip
   pip3 install pyserial
   

3. Symlink or copy the skill to your Claude Code skills directory:

   # Option 1: Symlink (recommended - allows easy updates)
   ln -s "$(pwd)/.claude/skills/picocom" ~/.claude/skills/picocom
   
   # Option 2: Copy
   cp -r .claude/skills/picocom ~/.claude/skills/picocom
   

4. Grant serial port permissions (Linux):

   sudo usermod -a -G dialout $USER
   # Log out and back in for changes to take effect
   

Usage

Once installed, Claude will automatically detect when to use this skill based on your requests. Simply ask Claude to help with IoT device testing:

Example Prompts

• "Help me connect to the IoT device on /dev/ttyUSB0 and enumerate its system information"
• "The device has a U-Boot bootloader, help me modify the boot arguments to get a root shell"
• "I have access to the shell, help me check for privilege escalation vulnerabilities"
• "Extract the firmware from this device for offline analysis"
• "Check if this device has any SUID binaries that could be exploited"

Direct Skill Invocation

You can also explicitly invoke the skill in Claude Code (though it will auto-activate when appropriate):

Can you help me pentest this IoT device using picocom?

Skill Capabilities

The skill provides comprehensive guidance for:

1. Connection Setup: Proper picocom configuration with appropriate baud rates and options
2. Console State Detection: Identify bootloader, login prompt, or shell access
3. Interactive Commands: Techniques for sending commands through picocom
4. Device Enumeration: System info, network config, running services, file permissions
5. Bootloader Exploitation: U-Boot commands, boot argument modification, memory operations
6. Privilege Escalation: Common techniques for gaining root access
7. Persistence: Methods to maintain access (SSH keys, backdoor accounts, startup scripts)
8. Firmware Extraction: Dump flash partitions and MTD devices
9. Troubleshooting: Common issues and solutions (baud rate, permissions, line endings)

Common IoT Device Scenarios

Scenario 1: Direct Root Shell Access

Device drops you directly into a root shell without authentication - immediate access for enumeration and exploitation.

Scenario 2: Login Protected

Device requires credentials - try default passwords, manufacturer-specific credentials, or attempt bypass techniques.

Scenario 3: Bootloader Manipulation

Access to U-Boot or other bootloader - modify boot parameters to gain root shell or boot custom firmware.

Scenario 4: Limited Shell Escape

Restricted shell environment - use escape techniques to break out into a full shell.

Security and Legal Considerations

IMPORTANT: This skill is designed for authorized security testing only. Only use this skill on:

• Devices you own
• Devices you have explicit written permission to test
• Security research in controlled lab environments

Unauthorized access to computer systems is illegal in most jurisdictions. Always obtain proper authorization before conducting any security testing.

Hardware Requirements

• USB-to-Serial adapter (FTDI FT232, CP2102, CH340, etc.) OR
• Device with built-in serial port OR
• JTAG/SWD adapter with UART capabilities

Common IoT devices with UART access:

• IP cameras
• Routers and access points
• Smart home devices
• Embedded Linux systems
• Development boards (Raspberry Pi, BeagleBone, etc.)

Troubleshooting

No Output from Device

• Check physical connections (TX to RX, RX to TX, GND to GND)
• Verify correct baud rate (try 115200, 57600, 38400, 19200, 9600)
• Ensure device is powered on
• Press Enter several times

Permission Denied

sudo usermod -a -G dialout $USER
# Then log out and back in

Garbled Output

Wrong baud rate - try different common rates until you see readable text.

Device Busy Error

Another program is using the serial port. Close other terminal programs, ModemManager, or use:

sudo systemctl stop ModemManager

Quick Reference Card

🔍 Monitoring Serial Activity

📋 Log File Location: /tmp/serial_session.log

Watch Commands in Real-Time:

tail -f /tmp/serial_session.log

✨ All commands run by Claude automatically log to this file!

Common Command Patterns

# Single command with logging (ALWAYS USE THIS FORMAT)
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --prompt "User@[^>]+>" \
  --logfile /tmp/serial_session.log \
  --command "COMMAND_HERE"

# Interactive mode with logging
python3 .claude/skills/picocom/serial_helper.py \
  --device /dev/ttyUSB0 \
  --logfile /tmp/serial_session.log \
  --interactive

Default Settings

• Device: /dev/ttyUSB0
• Baud Rate: 115200
• Log File: /tmp/serial_session.log ⬅️ ALWAYS MONITOR THIS
• Timeout: 3.0 seconds (use --timeout 10 for slow commands)

Contributing

Contributions are welcome! Please feel free to submit pull requests with:

• Additional IoT device scenarios
• New enumeration techniques
• Privilege escalation methods
• Troubleshooting tips
• Documentation improvements

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool is provided for educational and authorized security testing purposes only. The authors are not responsible for any misuse or damage caused by this tool. Users are solely responsible for ensuring they have proper authorization before testing any systems.