IoTHackBot Documentation

The jtagprobe tool uses a SEGGER J-Link to probe IoT/embedded targets for exposed SWD or JTAG debug interfaces. It classifies the target's debug state into one of three levels:

• OPEN: The Debug Port (DP) responds, the CPU halts, and memory reads return plausible data. This indicates full debugger control.
• LOCKED: The DP/IDCODE is accessible, but memory reads fail or return readout-protection sentinels (e.g., 0xFFFFFFFF). This indicates active protection like STM32 RDP, NXP CRP, or Nordic APPROTECT.
• DEAD: No response on any tested interface or speed. The debug port is likely fused off, pins are not wired, or the target is incorrect.

Use the picocom skill to interact with IoT device UART consoles. This is used for security testing operations such as bootloader manipulation, gaining root shells, device enumeration, and vulnerability discovery on embedded hardware.

Prerequisites:

• picocom installed on the system.
• Python 3 with the pyserial library.
• A physical UART connection to the target (e.g., USB-to-serial adapter, FTDI cable).
• Permissions to access serial device nodes (typically /dev/ttyUSB* or /dev/ttyACM*).

IoTHackBot tools are designed with a layered architecture to support easy automation, tool composition, and consistent behavior across the toolkit. Every tool follows this three-tier structure:

1. CLI Layer (tools/iothackbot/*.py): Handles the command-line interface using argparse.
2. Core Layer (tools/iothackbot/core/*_core.py): Implements the actual logic by adhering to the ToolInterface.
3. Binary (bin/*): Provides executable wrapper scripts for easy access via the command line.

This separation ensures that all tools provide standardized error handling and consistent output formats (text, JSON, quiet).

IoTHackBot tools rely on three primary abstractions to ensure compatibility and support tool chaining:

1. ToolInterface: The contract for all tools. It requires a name, a description, and a run(config: ToolConfig) -> ToolResult method. This abstraction allows the system to treat different tools uniformly.
2. ToolConfig: The input object passed to a tool. It contains standard fields like input_path, output_format (text, json, or quiet), verbose (boolean), and a custom_args dictionary for tool-specific parameters.
3. ToolResult: The standardized output object returned by a tool. It includes success (boolean), data (the actual result), errors (a list of strings), metadata, and execution_time.

By using these shared interfaces, tools can be chained together in pipelines, where the ToolResult of one tool serves as the input for the next.

When using --format json, the tool returns a structured object containing:

• dns_mappings: Dictionary of IP to hostname mappings.
• tcp_flows: List of TCP flow objects (includes hostname, ip, port).
• udp_flows: List of UDP flow objects (includes hostname, ip, port).
• flow_summary: List of "hostname:port" or "ip:port" strings.
• dns_queries: List of DNS domains queried.
• total_packets: Number of packets analyzed.

# Example: Parsing JSON output with jq
netflows capture.pcap --format json | jq '.data[].flow_summary'

To use the filesystem extraction capabilities of ffind, the following conditions must be met:

• Privileges: You must run the command with sudo.
• System Dependencies:
  • e2fsprogs (for ext2/3/4 support)
  • f2fs-tools (for F2FS support)
  • util-linux

Most IoT devices use BusyBox, a minimal Unix utility suite. It has limited command functionality and may lack standard Linux features like tab completion or advanced flags.

Identification commands:

# Check if busybox is present
busybox

# List available applets
busybox --list

# Check symlinks for /bin/sh
ls -la /bin/sh

Common BusyBox utilities for enumeration:

• nc (Netcat): For listeners or connections.
• wget / ftpget: For downloading files.
• httpd: To start a quick web server (busybox httpd -p 8080 -h /tmp).
• ps, top, ifconfig, netstat, vi (basic).

# Check what shell you're using
busybox
busybox --help

# Or check symlinks
ls -la /bin/sh

# List available BusyBox applets
busybox --list

The telnet_helper.py script is the recommended way to interact with IoT devices. It provides a reliable interface by:

• Removing command echoes, prompts, and ANSI codes for clean output.
• Automatically detecting and waiting for device prompts.
• Managing timeouts without arbitrary sleeps.
• Providing session logging to /tmp/telnet_session.log by default.
• Supporting JSON output for programmatic parsing.

To monitor a session in real-time, run this in a separate terminal:

tail -f /tmp/telnet_session.log

python3 .claude/skills/telnetshell/telnet_helper.py --host 192.168.1.100 --command "uname -a"

To maintain a professional and parseable interface, all tools must adhere to these output standards:

Format Support

Every tool must support three output modes via the --format flag:

• text: Human-readable, colored output (the default).
• json: Structured JSON data.
• quiet: Minimal or no output.

Color Scheme

Use colorama for text coloring:

• Green: Success messages and found items.
• Yellow: Warnings and directory paths.
• Cyan: Detailed information and file listings.
• Red: Errors and failures.

Emoji Policy

DO NOT use emojis in tool output. Use descriptive text labels instead (e.g., [HIGH RISK], FAILED, SUCCESS) to ensure compatibility across all terminal environments and to keep output easily parseable.

Monitor mode is used for passive UART monitoring where the device outputs logs without requiring interaction. This is ideal for capturing boot logs or observing how a device reacts to external triggers (like network requests or hardware events).

Use Cases:

• Monitoring boot logs from devices without interactive consoles.
• Capturing triggered output when external actions are performed.
• Comparing baseline UART output against triggered output.

Example: Monitor with an external trigger This command monitors the device for 60 seconds, runs a curl command after 5 seconds, and logs everything to /tmp/triggered_uart.log.

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 5 \
  --logfile /tmp/triggered_uart.log

Most IoT devices use BusyBox, a minimal Unix utility suite. It has limited command functionality and may lack standard Linux features like tab completion or certain command flags.

To identify BusyBox:

• Run busybox or busybox --help.
• Check symlinks: ls -la /bin/sh (often points to /bin/busybox).
• List available applets: busybox --list.

Commonly available BusyBox commands:

• Core: cat, ls, cd, pwd, echo, cp, mv, rm, mkdir, chmod, chown
• System: ps, kill, top, free, df, mount, umount
• Network: ifconfig, route, ping, netstat, telnet, nc (netcat), wget
• Others: grep, find, sed, awk, vi (basic)