coreminer

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 14 Open GitHub ↗

A debugger which can be used to debug programs that do not want to be debugged

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
    <img alt="icon" src="./docs/img/logo.svg" width="60%"/>
    <h3>🔩 coreminer 👁️</h3>
    <p>
        Debug those programs that don't want to be
    </p>
    <br/>
    <a href="https://github.com/TalpaLabs/coreminer/actions/workflows/release.yaml">
        <img src="https://img.shields.io/github/actions/workflow/status/TalpaLabs/coreminer/release.yaml?label=Release" alt="Release Status"/>
    </a>
    <a href="https://github.com/TalpaLabs/coreminer/actions/workflows/cargo.yaml">
        <img src="https://img.shields.io/github/actions/workflow/status/TalpaLabs/coreminer/cargo.yaml?label=Rust%20CI" alt="Rust CI"/>
    </a>
    <a href="https://github.com/TalpaLabs/coreminer/blob/master/LICENSE">
        <img src="https://img.shields.io/github/license/TalpaLabs/coreminer" alt="License"/>
    </a>
    <a href="https://github.com/TalpaLabs/coreminer/releases">
        <img src="https://img.shields.io/github/v/release/TalpaLabs/coreminer" alt="Release"/>
    </a>
    <br/>
    <a href="https://rust-lang.org">
        <img src="https://img.shields.io/badge/language-Rust-blue.svg" alt="Rust"/>
    </a>
    <a href="https://crates.io/crates/coreminer">
        <img alt="Crates.io MSRV" src="https://img.shields.io/crates/msrv/coreminer">
        <img alt="Crates.io Total Downloads" src="https://img.shields.io/crates/d/coreminer">
    </a>
    <a href="https://docs.rs/coreminer/latest/coreminer">
    <img alt="docs.rs" src="https://img.shields.io/docsrs/coreminer">
    </a>
</div>

# coreminer

- [GitHub](https://github.com/TalpaLabs/coreminer)
- [crates.io](https://crates.io/crates/coreminer)
- [Documentation on docs.rs](https://docs.rs/coreminer/latest/coreminer/)

A powerful debugger written in Rust that provides low-level debugging capabilities for programs that may not want to be debugged. Coreminer gives you deep control over program execution with robust DWARF debug information parsing.

## Features

- **Execution Control**: Set breakpoints, step through code, continue execution
- **Memory & Register Access**: Read from and write to process memory and CPU registers
- **Variable Inspection**: Read and write application variables using DWARF debug symbols
- **Stack Unwinding**: Generate and analyze stack backtraces
- **Disassembly**: View disassembled code at specific addresses
- **Process Inspection**: View process maps and executable layouts
- **Plugin System**: Extend debugger capabilities with custom plugins (v0.3.0+)
- **Plugin Management**: Enable/disable plugins at runtime (v0.4.0+)
- **Sigtrap Guard Plugin**: Protrect from detection through self registering a handler on SIGTRAP

## Installation

### Additional system dependencies

To compile, coreminer depends on `libunwind-dev`. On Debian, it can be installed like
this. Other distributions provide similar packages.

```bash
apt install libunwind-dev pkg-config
```

### From crates.io

```bash
cargo install coreminer
```

### From source

```bash
git clone https://github.com/TalpaLabs/coreminer.git
cd coreminer
cargo build --release
```

The binary will be available at `./target/release/cm`.

## Quick Start

### Launch Coreminer

You can launch Coreminer with an optional executable path as a default target:

```bash
# Launch Coreminer without a target
cm

# Launch Coreminer with a default executable
cm ./target/debug/dummy
```

## Command-Line Interface

Coreminer provides a simple CLI that allows you to interact with the debugger. The interface supports command history for ease of use.

Once in the Coreminer CLI, you can use:

```
# Run a program with arguments
run ./target/debug/dummy arg1 arg2

# If launched with a default executable, you can run it with:
run

# Set a breakpoint at a specific address (hex)
bp 0x0000563087528176

# Continue execution
c

# Step over instructions
s
step

# View disassembly at some address, 20 bytes
d 0x0000563087528176 20

# View disassembly at some address, 20 bytes, showing the code exactly how it is
# in memory - including the int3 instructions set by breakpoints
d 0x0000563087528176 20 --literal

# Read registers
regs get

# View process memory
rmem 0x7fffffffe000

# Backtrace the call stack
bt

# Read a variable by name (requires debug information)
var my_variable_name

# Inspect a debug symbol (requires debug information)
sym main
sym i
```

A list of all commands can be gotten with `help`:

```
Coreminer Debugger Help:

run PATH:str [ARGS:str ...]             - Run program at PATH with optional arguments
  c, cont                                 - Continue execution
  s, step                                 - Step one instruction
  si                                      - Step into function call
  su, sov                                 - Step over function call
  so                                      - Step out of current function
  bp, break ADDR:num                      - Set breakpoint at address (hex)
  dbp, delbreak ADDR:num                  - Delete breakpoint at address (hex)
  d, dis ADDR:num LEN:num [--literal]     - Disassemble LEN bytes at ADDR
  bt                                      - Show backtrace
  stack                                   - Show stack
  info                                    - Show debugger info
  pm                                      - Show process memory map
  regs get                                - Show register values
  regs set REG:str VAL:num                - Set register REG to value VAL (hex)
  rmem ADDR:num                           - Read memory at address (hex)
  wmem ADDR:num VAL:num                   - Write value to memory at address (hex)
  sym, gsym NAME:str                      - Look up symbol by name
  var NAME:str                            - Read variable value
  vars NAME:str VAL:num                   - Write value to variable
  set stepper N                           - Set stepper to auto-step N times
  q, quit, exit                           - Exit the debugger
  plugin ID:str [STATUS:bool]             - Show the status of a plugin or enable/disable it
  plugins                                 - Get a list of all loaded plugins
  help, h, ?                              - Show this help

Addresses and values should be in hexadecimal (with or without 0x prefix)

Input Types:
  FOO:num is a positive whole number in hexadecimal (optional 0x prefix)
  FOO:str is a string
  FOO:bool either of 'true', 'false', '1', or '0'
```

## JSON Interface

From `v0.2.0`, Coreminer includes a second binary: `cmserve`. `cmserve` provides
all internal functionalities of the Coreminer debugger, but can be
scripted. This enables projects such as [hardhat](https://github.com/TalpaLabs/hardhat)
to build a better user interface for Coreminer.

To see some example inputs (statuses) and outputs (feedbacks), you can use
`cmserve --example-statuses --example-feedbacks`.

## Use Cases

- **Reverse Engineering**: Analyze and understand program behavior
- **Debugging Stripped Binaries**: Debug programs with limited debugging information
- **Security Research**: Analyze potentially malicious code in a controlled environment
- **Low-level Debugging**: Step through compiled code precisely

## Architecture

Coreminer is built around several key components:

- **Debuggee Control**: Via Linux ptrace API
- **DWARF Debug Info**: For symbol resolution and variable information
- **Stack Unwinding**: Using libunwind
- **Disassembly**: Powered by iced-x86
- **Plugin System**: Extensibility via [steckrs](https://github.com/PlexSheep/steckrs)

## Examples

The [examples](./examples/) directory contains a few small programs that serve
as debuggees. You can try coreminer on them and see what happens.

They can be compiled in debug or release mode with [`build-dummy.sh`](./build-dummy.sh) and
[`build-release.sh`](./build-release.sh).

The [examples](./examples/) directory also contains an example plugin.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: Add some amazing feature'`)
4. Push to the branch (`git push origin feat/amazing-feature`)
5. Open a Pull Request

Note: this project makes use of [conventional git commits](https://www.conventionalcommits.org/en/v1.0.0/).

## License

Distributed under the MIT License. See `LICENSE` for more information.

## Acknowledgements

- Thanks to the [BugStalker](https://github.com/godzie44/BugStalker) project for inspiration and reference on DWARF and unwinding implementation.
- Thanks to the [Sy Brand – Writing a Linux Debugger](https://blog.tartanllama.xyz/writing-a-linux-debugger-setup/) for his blog on writing a debugger.

coreminer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README