diff options
Diffstat (limited to 'src/DebuggerKit')
| -rw-r--r-- | src/DebuggerKit/CommonCLI.inl | 23 | ||||
| -rw-r--r-- | src/DebuggerKit/DebuggerContract.h | 52 | ||||
| -rw-r--r-- | src/DebuggerKit/NeKernelContract.h | 60 | ||||
| -rw-r--r-- | src/DebuggerKit/POSIXMachContract.h | 147 | ||||
| -rw-r--r-- | src/DebuggerKit/Platform.h | 37 | ||||
| -rw-r--r-- | src/DebuggerKit/Version.h | 15 | ||||
| -rw-r--r-- | src/DebuggerKit/dk-nekernel.json | 17 | ||||
| -rw-r--r-- | src/DebuggerKit/dk-osx.json | 18 | ||||
| -rw-r--r-- | src/DebuggerKit/src/NeKernelContract.cc | 90 | ||||
| -rw-r--r-- | src/DebuggerKit/src/NeKernelContractCLI.cc | 100 | ||||
| -rw-r--r-- | src/DebuggerKit/src/POSIXMachContractCLI.cc | 94 |
11 files changed, 653 insertions, 0 deletions
diff --git a/src/DebuggerKit/CommonCLI.inl b/src/DebuggerKit/CommonCLI.inl new file mode 100644 index 0000000..e06a9b9 --- /dev/null +++ b/src/DebuggerKit/CommonCLI.inl @@ -0,0 +1,23 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#define kBlank "\e[0;30m" +#define kRed "\e[0;31m" +#define kWhite "\e[0;97m" + +#define kStdOut (std::cout << kRed << "dbg: " << kWhite) + +static Bool kKeepRunning = false; + +#ifdef DK_NEKERNEL_DEBUGGER +static DebuggerKit::NeKernel::NeKernelContract kKernelDebugger; +#else +static DebuggerKit::POSIX::POSIXMachContract kUserDebugger; +#endif + +static DebuggerKit::ProcessID kPID = 0L; +static DebuggerKit::CAddress kActiveAddress = nullptr; +static CompilerKit::STLString kPath = ""; diff --git a/src/DebuggerKit/DebuggerContract.h b/src/DebuggerKit/DebuggerContract.h new file mode 100644 index 0000000..2114041 --- /dev/null +++ b/src/DebuggerKit/DebuggerContract.h @@ -0,0 +1,52 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#pragma once + +#include <DebuggerKit/Platform.h> + +#define DK_DEBUGGER_CONTRACT : public ::DebuggerKit::DebuggerContract + +namespace DebuggerKit { +class DebuggerContract; + +/// =========================================================== /// +/// \brief Process ID +/// =========================================================== /// +typedef uint64_t ProcessID; + +/// =========================================================== /// +/// \brief Address type, a la BSD. +/// =========================================================== /// +typedef char* CAddress; + +/// =========================================================== /// +/// \brief Debugger contract class in C++, as per the design states. +/// \author Amlal El Mahrouss +/// =========================================================== /// +class DebuggerContract { + public: + explicit DebuggerContract() = default; + virtual ~DebuggerContract() = default; + + public: + DebuggerContract& operator=(const DebuggerContract&) = default; + DebuggerContract(const DebuggerContract&) = default; + + public: + virtual bool Attach(std::string path, std::string argv, ProcessID& pid) noexcept = 0; + virtual bool BreakAt(std::string symbol) noexcept = 0; + virtual bool Break() noexcept = 0; + virtual bool Continue() noexcept = 0; + virtual bool Detach() noexcept = 0; + + virtual std::unordered_map<uintptr_t, uintptr_t>& Get() { return m_breakpoints; } + + protected: + ProcessID m_pid{(ProcessID)~0}; + std::unordered_map<uintptr_t, uintptr_t> m_breakpoints; +}; +} // namespace DebuggerKit diff --git a/src/DebuggerKit/NeKernelContract.h b/src/DebuggerKit/NeKernelContract.h new file mode 100644 index 0000000..d048303 --- /dev/null +++ b/src/DebuggerKit/NeKernelContract.h @@ -0,0 +1,60 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#ifndef DK_NEKERNEL_CONTRACT_H +#define DK_NEKERNEL_CONTRACT_H + +/// @brief NeKernel Debugging Protocol +/// @author Amlal El Mahrouss + +#ifdef DK_NEKERNEL_DEBUGGER + +#include <CompilerKit/Defines.h> +#include <DebuggerKit/DebuggerContract.h> + +namespace DebuggerKit::NeKernel { +class NeKernelContract; + +namespace Detail { + inline constexpr auto kDebugCmdLen = 256U; + inline constexpr auto kDebugPort = 51820; + inline constexpr auto kDebugMagic = "NE1.0.0;"; + inline constexpr uint16_t kDebugVersion = 0x0100; + inline constexpr auto kDebugDelim = ';'; + inline constexpr auto kDebugEnd = '\r'; + typedef int64_t dk_socket_type; +} // namespace Detail + +/// =========================================================== /// +/// \brief NeKernel Debugger Contract +/// \author Amlal El Mahrouss +/// =========================================================== /// +class NeKernelContract final DK_DEBUGGER_CONTRACT { + public: + NeKernelContract(); + virtual ~NeKernelContract() override; + + public: + NeKernelContract& operator=(const NeKernelContract&) = default; + NeKernelContract(const NeKernelContract&) = default; + + public: + bool Attach(CompilerKit::STLString path, CompilerKit::STLString arg_v, + ProcessID& pid) noexcept override; + bool BreakAt(CompilerKit::STLString symbol) noexcept override; + bool Break() noexcept override; + bool Continue() noexcept override; + bool Detach() noexcept override; + + private: + CompilerKit::STLString m_kernel_path{}; + Detail::dk_socket_type m_socket{0}; +}; +} // namespace DebuggerKit::NeKernel + +#endif // ifdef DK_NEKERNEL_DEBUGGER + +#endif // DK_NEKERNEL_CONTRACT_H diff --git a/src/DebuggerKit/POSIXMachContract.h b/src/DebuggerKit/POSIXMachContract.h new file mode 100644 index 0000000..5bd4ba8 --- /dev/null +++ b/src/DebuggerKit/POSIXMachContract.h @@ -0,0 +1,147 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#pragma once + +#ifdef DK_MACH_DEBUGGER + +/// @file POSIXMachContract.h +/// @brief POSIX Mach debugger. + +#include <DebuggerKit/DebuggerContract.h> + +CK_IMPORT_C kern_return_t mach_vm_write(vm_map_t target_task, mach_vm_address_t address, + vm_offset_t data, mach_msg_type_number_t dataCnt); + +CK_IMPORT_C kern_return_t mach_vm_protect(vm_map_t target_task, mach_vm_address_t address, + mach_vm_size_t size, boolean_t set_maximum, + vm_prot_t new_protection); + +#define PTRACE_ATTACH PT_ATTACHEXC +#define PTRACE_DETACH PT_DETACH +#define PTRACE_POKETEXT PT_WRITE_I +#define PTRACE_CONT PT_CONTINUE +#define PTRACE_PEEKTEXT PT_READ_I + +namespace DebuggerKit::POSIX { +/// =========================================================== /// +/// \brief POSIXMachContract engine class in C++ +/// \author Amlal El Mahrouss +/// =========================================================== /// +class POSIXMachContract final DK_DEBUGGER_CONTRACT { + public: + explicit POSIXMachContract() = default; + ~POSIXMachContract() override = default; + + public: + POSIXMachContract& operator=(const POSIXMachContract&) = default; + POSIXMachContract(const POSIXMachContract&) = default; + + public: + Bool Attach(CompilerKit::STLString path, CompilerKit::STLString argv, + ProcessID& pid) noexcept override { + pid = fork(); + + if (pid == 0) { + if (argv.empty()) { + ptrace(PT_TRACE_ME, 0, nullptr, 0); + kill(getpid(), SIGSTOP); + } + + std::vector<char*> argv_arr; + + argv_arr.push_back(const_cast<char*>(path.c_str())); + argv_arr.push_back(const_cast<char*>(argv.c_str())); + argv_arr.push_back(nullptr); + + execv(path.c_str(), argv_arr.data()); + + _exit(1); + } + + m_path = path; + m_pid = pid; + + pid = this->m_pid; + + return true; + } + + void SetPath(CompilerKit::STLString path) noexcept { + if (path.empty()) { + return; + } + + m_path = path; + } + + Bool BreakAt(CompilerKit::STLString symbol) noexcept override { + if (!m_path.empty() && std::filesystem::exists(m_path) && + std::filesystem::is_regular_file(m_path)) { + auto handle = dlopen(m_path.c_str(), RTLD_LAZY); + + if (handle == nullptr) { + return false; + } + + auto addr = dlsym(handle, symbol.c_str()); + + if (addr == nullptr) { + return false; + } + + task_read_t task; + task_for_pid(mach_task_self(), m_pid, &task); + + uint32_t brk_inst = 0xD43E0000; + + mach_vm_protect(task, (mach_vm_address_t) addr, sizeof(uint32_t), false, + VM_PROT_READ | VM_PROT_WRITE | VM_PROT_EXECUTE); + + mach_vm_write(task, (mach_vm_address_t) addr, (vm_offset_t) &brk_inst, sizeof(addr)); + + return true; + } + + return false; + } + + Bool Break() noexcept override { + task_read_t task; + task_for_pid(mach_task_self(), m_pid, &task); + + kern_return_t ret = task_suspend(task); + + return ret == KERN_SUCCESS; + } + + Bool Continue() noexcept override { + task_read_t task; + task_for_pid(mach_task_self(), m_pid, &task); + + kern_return_t ret = task_resume(task); + + return ret == KERN_SUCCESS; + } + + Bool Detach() noexcept override { + this->Continue(); + + task_read_t task; + task_for_pid(mach_task_self(), m_pid, &task); + + kern_return_t kr = mach_port_deallocate(mach_task_self(), task); + + return kr = KERN_SUCCESS; + } + + private: + ProcessID m_pid{0}; + CompilerKit::STLString m_path; +}; +} // namespace DebuggerKit::POSIX + +#endif diff --git a/src/DebuggerKit/Platform.h b/src/DebuggerKit/Platform.h new file mode 100644 index 0000000..f878845 --- /dev/null +++ b/src/DebuggerKit/Platform.h @@ -0,0 +1,37 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#pragma once + +/// =========================================================== /// +/// @author Amlal El Mahrouss +/// =========================================================== /// + +#include <CompilerKit/Defines.h> + +#include <arpa/inet.h> +#include <sys/socket.h> +#include <sys/types.h> +#include <sys/un.h> + +#include <sys/ptrace.h> +#include <sys/types.h> +#include <sys/user.h> +#include <sys/wait.h> +#include <unistd.h> + +#include <filesystem> +#include <iostream> + +#include <dlfcn.h> +#include <mach-o/dyld.h> +#include <mach/mach.h> +#include <mach/mach_error.h> +#include <signal.h> + +#include <cstdint> +#include <string> +#include <unordered_map>
\ No newline at end of file diff --git a/src/DebuggerKit/Version.h b/src/DebuggerKit/Version.h new file mode 100644 index 0000000..8f3168a --- /dev/null +++ b/src/DebuggerKit/Version.h @@ -0,0 +1,15 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#pragma once + +#define kDistVersion "v0.0.7-debuggerkit" +#define kDistVersionBCD 0x0001 + +#define ToString(X) Stringify(X) +#define Stringify(X) #X + +#define kDistRelease ToString(kDistReleaseBranch) diff --git a/src/DebuggerKit/dk-nekernel.json b/src/DebuggerKit/dk-nekernel.json new file mode 100644 index 0000000..9c3d311 --- /dev/null +++ b/src/DebuggerKit/dk-nekernel.json @@ -0,0 +1,17 @@ +{ + "compiler_path": "clang++", + "compiler_std": "c++20", + "headers_path": [ + "../DebuggerKit", + "../" + ], + "sources_path": ["src/*.cc"], + "output_name": "/usr/local/lib/libDebuggerKit.dylib", + "compiler_flags": ["-fPIC", "-shared"], + "cpp_macros": [ + "__NECTI__=202505", + "DK_USE_STRUCTS=1", + "DK_NEKERNEL_DEBUGGER", + "kDistReleaseBranch=$(git rev-parse --abbrev-ref HEAD)-$(uuidgen)" + ] +} diff --git a/src/DebuggerKit/dk-osx.json b/src/DebuggerKit/dk-osx.json new file mode 100644 index 0000000..c220756 --- /dev/null +++ b/src/DebuggerKit/dk-osx.json @@ -0,0 +1,18 @@ +{ + "compiler_path": "clang++", + "compiler_std": "c++20", + "headers_path": [ + "../DebuggerKit", + "../" + ], + "sources_path": ["src/*.cc"], + "output_name": "/usr/local/lib/libDebuggerKit.dylib", + "compiler_flags": ["-fPIC", "-shared"], + "cpp_macros": [ + "__NECTI__=202505", + "CK_USE_STRUCTS=1", + "DEBUGGERKIT_POSIX", + "DK_MACH_DEBUGGER", + "kDistReleaseBranch=$(git rev-parse --abbrev-ref HEAD)-$(uuidgen)" + ] +} diff --git a/src/DebuggerKit/src/NeKernelContract.cc b/src/DebuggerKit/src/NeKernelContract.cc new file mode 100644 index 0000000..38f327d --- /dev/null +++ b/src/DebuggerKit/src/NeKernelContract.cc @@ -0,0 +1,90 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#ifdef DK_NEKERNEL_DEBUGGER + +/// @author Amlal El Mahrouss +/// @brief Kernel Debugger Protocol + +#include <CompilerKit/Defines.h> +#include <DebuggerKit/NeKernelContract.h> +#include <DebuggerKit/Platform.h> +#include <ThirdParty/Dialogs.h> + +using namespace DebuggerKit::NeKernel; +using namespace DebuggerKit::NeKernel::Detail; + +NeKernelContract::NeKernelContract() = default; + +NeKernelContract::~NeKernelContract() = default; + +Bool NeKernelContract::Attach(CompilerKit::STLString path, CompilerKit::STLString argv, + ProcessID& pid) noexcept { + if (path.empty() || argv.empty()) return NO; + + m_socket = ::socket(AF_INET, SOCK_STREAM, 0); + + if (m_socket == -1) return NO; + + struct sockaddr_in server_addr; + + server_addr.sin_family = AF_INET; + server_addr.sin_port = htons(kDebugPort); + + if (::inet_pton(AF_INET, argv.c_str(), &server_addr.sin_addr) <= 0) return NO; + + auto ret = (::connect(m_socket, (struct sockaddr*) &server_addr, sizeof(server_addr)) == -1); + + if (ret) return NO; + + CompilerKit::STLString pkt = Detail::kDebugMagic; + pkt += ";\r"; + + ret = ::send(m_socket, pkt.data(), pkt.size(), 0) > 0; + return ret; +} + +Bool NeKernelContract::BreakAt(CompilerKit::STLString symbol) noexcept { + CompilerKit::STLString pkt = Detail::kDebugMagic; + pkt += ";SYM="; + pkt += symbol; + pkt += ";\r"; + + if (pkt.size() > kDebugCmdLen) return NO; + + auto ret = ::send(m_socket, pkt.data(), pkt.size(), 0) > 0; + return ret; +} + +Bool NeKernelContract::Break() noexcept { + CompilerKit::STLString pkt = Detail::kDebugMagic; + pkt += ";BRK=1;\r"; + + auto ret = ::send(m_socket, pkt.data(), pkt.size(), 0) > 0; + return ret; +} + +Bool NeKernelContract::Continue() noexcept { + CompilerKit::STLString pkt = Detail::kDebugMagic; + pkt += ";CONT=1;\r"; + + auto ret = ::send(m_socket, pkt.data(), pkt.size(), 0) > 0; + return ret; + return NO; +} + +Bool NeKernelContract::Detach() noexcept { + CompilerKit::STLString pkt = Detail::kDebugMagic; + pkt += ";DTCH=1;\r"; + + auto ret = ::send(m_socket, pkt.data(), pkt.size(), 0) > 0; + + if (ret) ::close(m_socket); + + return ret; +} + +#endif // DK_NEKERNEL_DEBUGGER diff --git a/src/DebuggerKit/src/NeKernelContractCLI.cc b/src/DebuggerKit/src/NeKernelContractCLI.cc new file mode 100644 index 0000000..fc13a53 --- /dev/null +++ b/src/DebuggerKit/src/NeKernelContractCLI.cc @@ -0,0 +1,100 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#ifdef DK_NEKERNEL_DEBUGGER + +#include <CompilerKit/Defines.h> +#include <DebuggerKit/NeKernelContract.h> +#include <ThirdParty/Dialogs.h> +#include <string> + +#include <DebuggerKit/CommonCLI.inl> + +using namespace DebuggerKit::NeKernel; + +static void dbgi_ctrlc_handler(std::int32_t _) { + if (!kPID || kPath.empty()) { + return; + } + + kKernelDebugger.Break(); + + pfd::notify("Debugger Event", "Breakpoint hit!"); + + kKeepRunning = false; +} + +NECTI_MODULE(DebuggerNeKernel) { + pfd::notify("Debugger Event", + "NeCTI Debugger\n(C) 2025 Amlal El Mahrouss and NeKernel.org contributors, all " + "rights reserved."); + + if (argc >= 5 && std::string(argv[1]) == "-k" && argv[2] != nullptr && + std::string(argv[3]) == "-ip" && argv[4] != nullptr) { + kPath = argv[2]; + kPath += ":"; + kPath += argv[4]; + + kStdOut << "[+] KIP (Kernel:IP) set to: " << kPath << "\n"; + + CompilerKit::install_signal(SIGINT, dbgi_ctrlc_handler); + + kKernelDebugger.Attach(kPath, argv[4], kPID); + + while (YES) { + if (kKeepRunning) { + continue; + } + + std::string cmd; + if (!std::getline(std::cin, cmd)) break; + + if (cmd == "c" || cmd == "cont" || cmd == "continue") { + if (kKernelDebugger.Continue()) { + kKeepRunning = true; + + kStdOut << "[+] Continuing...\n"; + + pfd::notify("Debugger Event", "Continuing..."); + } + } + + if (cmd == "d" || cmd == "detach") kKernelDebugger.Detach(); + + if (cmd == "start") { + kStdOut << "[?] Enter a argument to use: "; + std::getline(std::cin, cmd); + + kKernelDebugger.Attach(kPath, cmd, kPID); + } + + if (cmd == "exit") { + if (kPID > 0) kKernelDebugger.Detach(); + + break; + } + + if (cmd == "break" || cmd == "b") { + kStdOut << "[?] Enter a symbol to break on: "; + + std::getline(std::cin, cmd); + + if (kKernelDebugger.BreakAt(cmd)) { + pfd::notify("Debugger Event", "Add BreakAt at: " + cmd); + } + } + } + + return EXIT_SUCCESS; + } + + kStdOut << "usage: " << argv[0] << " -k <kernel_path> -ip <ip4>\n"; + kStdOut << "example: " << argv[0] << " -k /path/to/ne_kernel -ip 127.0.0.1\n"; + + return EXIT_FAILURE; +} + +#endif // DK_NEKERNEL_DEBUGGER diff --git a/src/DebuggerKit/src/POSIXMachContractCLI.cc b/src/DebuggerKit/src/POSIXMachContractCLI.cc new file mode 100644 index 0000000..77fe844 --- /dev/null +++ b/src/DebuggerKit/src/POSIXMachContractCLI.cc @@ -0,0 +1,94 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#ifdef DK_MACH_DEBUGGER + +#include <CompilerKit/Defines.h> +#include <DebuggerKit/POSIXMachContract.h> +#include <ThirdParty/Dialogs.h> +#include <DebuggerKit/CommonCLI.inl> + +/// @internal +/// @brief Handles CTRL-C signal on debugger. +static void dbgi_ctrlc_handler(std::int32_t _) { + if (!kPID) { + return; + } + + kUserDebugger.Break(); + + pfd::notify("Debugger Event", "Breakpoint hit!"); + + kKeepRunning = false; +} + +NECTI_MODULE(DebuggerMachPOSIX) { + pfd::notify( + "Debugger Event", + "Userland Debugger\n(C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license."); + + if (argc >= 3 && std::string(argv[1]) == "-p" && argv[2] != nullptr) { + kPath = argv[2]; + kUserDebugger.SetPath(kPath); + + kStdOut << "[+] Image set to: " << kPath << "\n"; + } else { + kStdOut << "usage: " << argv[0] << " -p <path>\n"; + kStdOut << "example: " << argv[0] << " -p /path/to/program\n"; + + return EXIT_FAILURE; + } + + CompilerKit::install_signal(SIGINT, dbgi_ctrlc_handler); + + while (YES) { + if (kKeepRunning) { + continue; + } + + std::string cmd; + if (!std::getline(std::cin, cmd)) break; + + if (cmd == "c" || cmd == "cont" || cmd == "continue") { + if (kUserDebugger.Continue()) { + kKeepRunning = true; + + kStdOut << "[+] Continuing...\n"; + + pfd::notify("Debugger Event", "Continuing..."); + } + } + + if (cmd == "d" || cmd == "detach") kUserDebugger.Detach(); + + if (cmd == "start") { + kStdOut << "[?] Enter a argument to use: "; + std::getline(std::cin, cmd); + + kUserDebugger.Attach(kPath, cmd, kPID); + } + + if (cmd == "exit") { + if (kPID > 0) kUserDebugger.Detach(); + + break; + } + + if (cmd == "break" || cmd == "b") { + kStdOut << "[?] Enter a symbol to break on: "; + + std::getline(std::cin, cmd); + + if (kUserDebugger.BreakAt(cmd)) { + pfd::notify("Debugger Event", "Add BreakAt at: " + cmd); + } + } + } + + return EXIT_SUCCESS; +} + +#endif
\ No newline at end of file |
