DOCSEARCHbyAlgolia
Submit Docs

Depthcharge

repository·main·Indexed 43 days ago

https://github.com/nccgroup/depthcharge

A Python-based module and collection of scripts for interacting with hardware via serial communication. It includes tools for memory reading and writing, configuration validation for U-Boot via depthcharge.checker, and specialized search implementations (Hunters) for finding command tables, environment data, and Flattened Device Trees (FDT). The project also provides Arduino-based firmware for supported target platforms.

Tokens
8.5K
Snippets
19
Records
74
Agent score
54%

What's inside Depthcharge

  1. What is Depthcharge?

    main

    Depthcharge is a toolkit designed for security research and "jailbreaking" of embedded platforms that use the U-Boot bootloader. The toolkit is composed of several interconnected parts:

    • depthcharge Python module: An extensible Python 3 module providing the core API.
    • Python scripts: Scripts built on top of the depthcharge module API for common tasks.
    • Depthcharge "Companion" firmware: Firmware used to perform attacks that require a malicious peripheral device.
    • Helper payload binaries: Example U-Boot "standalone" program-esque payloads and build scripts to assist with initial setup.

  2. Use the Depthcharge Python API

    main
    The Depthcharge API is provided via the depthcharge module. Most core functionality is accessible directly through the top-level depthcharge namespace. If you are looking for implementation patterns, the project's internal scripts are built on top of this API and serve as practical examples of how to use the library.

  3. Use the depthcharge.monitor module

    main
    The depthcharge.monitor module provides various monitoring classes designed to observe and capture data from different sources. Depending on your target, you can use specialized monitor implementations such as FileMonitor for files, NamedPipeMonitor for named pipes, or TerminalMonitor for terminal output.

  5. Use the Depthcharge Python API for U-Boot scripting

    main
    The Depthcharge Python API is designed as a tool for quickly scripting U-Boot hacks. Rather than being a fully automated exploitation framework, it provides common security testing 'building blocks' that can be used to automate boot-time tasks or create proof-of-concept exploits. This is particularly useful for handling OEM-specific modifications to U-Boot by providing reusable primitives.

  6. Implement a custom Hunter by subclassing Hunter

    main

    To create a custom search implementation, subclass the Hunter base class and implement the private _search_at(target, start_offset, end_offset, **kwargs) method.

    Implementation Logic:

    • The method searches for target within the bounds of [start_offset, end_offset] inside the Hunter's data.
    • If a result is found: Return a dictionary matching the format expected by Hunter.find().
    • If no result is found (searched entire range): Raise a HunterResultNotFound exception.
    • If no result is found (only checked start_offset): Return None. The parent class will then automatically call _search_at repeatedly to scan the rest of the range.

    Note: _search_at is a private method intended for implementation, not for direct API calls.

  7. Perform memory access via Depthcharge abstractions

    main

    Depthcharge provides an abstraction layer for memory access operations. Instead of relying on a single command, it identifies available memory access mechanisms (such as i2c, crc32, itest, or setexpr) and automatically selects the 'best' available operation based on the requested data size and available functionality.

    This abstraction is exposed through:

    • Scripts: read and write commands.
    • API calls: Depthcharge.read_memory() and Depthcharge.write_memory().

    You can also register your own custom implementations at runtime using the Operation.register() static method if you encounter a memory access command not currently in the codebase.

    # Example of registering a custom memory operation
# (Note: Actual implementation details depend on the MemoryReader/Writer classes)
from depthcharge import Operation

# Operation.register() is a static method used to add new implementations
Operation.register(my_custom_reader_instance)

  10. Understand the Companion Firmware TLV message format

    main

    The host code (depthcharge.Companion) communicates with the firmware using a binary Type-Length-Value (TLV) message format. This format is used for both commands sent to the device and responses returned by the device.

    Message Structure:

    • Command type: 1 byte
    • Length: 1 byte (unsigned, represents the size of the following payload; can be zero)
    • Data payload: Command-specific data (omitted if length is zero)

  11. Core Depthcharge abstractions

    main

    For developers building custom U-Boot attack automation or image analysis tools, the Depthcharge API provides several key abstractions:

    • depthcharge.Operation: A base abstraction for individual actions.
    • depthcharge.Stratagem: A higher-level abstraction for organizing operations.
    • depthcharge.hunter.Hunter: A component for orchestrating attacks or analysis.
    • depthcharge.Console: An interface for interacting with the U-Boot console.

    Existing implementations for cmd, env, and fdt serve as reference examples for how to use these abstractions for U-Boot image analysis.

  12. When to use Depthcharge

    main

    Depthcharge is most effective when you have access to a restricted U-Boot environment. Specifically, it is useful if you can:

    • Access a restricted U-Boot console.
    • Tamper with a stored environment.
    • Modify a loaded script.

    Even if you do not meet these criteria, the Depthcharge API (including abstractions like Operation, Stratagem, and Hunter) can serve as a foundation for building your own U-Boot attack automation or image analysis tools. It is particularly useful for automating interactions with the U-Boot Console.