# Polymorphic Malware Stage Framework (PMSF)
<p align="left">
<a href="https://crates.io/crates/pmsf"><img src="https://img.shields.io/crates/v/pmsf.svg?style=flat-square" alt="Crates.io"></a>
<a href="https://docs.rs/pmsf"><img src="https://img.shields.io/docsrs/pmsf?style=flat-square" alt="docs.rs"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License"></a>
</p>
> **⚠️ DISCLAIMER:**
> This framework is a proof‑of‑concept for educational and research use only. The author does not condone or support malicious or unauthorized activities.
PMSF is a robust, research-grade Rust framework engineered for the simulation and analysis of modular malware stages. Designed with a focus on safety, extensibility, and clarity, PMSF empowers security researchers, educators, and students to explore advanced malware staging, evasion, and polymorphism techniques in a controlled, observable environment. All real-world actions are stubbed by default, ensuring a safe and risk-free experience for experimentation and learning.
---
> ⚠️ Security Warning
> **This framework is designed solely for safe simulation of malware stages in research and educational contexts.**
>
> Because PMSF is open source, it is possible for someone to modify the code to perform real malicious actions. **Always review the code before running it, especially if you received it from an untrusted source.**
>
> To verify the code is safe:
> - Open `src/lib.rs`.
> - Search for the following function names:
> - `establish_persistence`
> - `execute_code`
> - `communicate_c2`
> - `perform_anti_analysis`
> - Inside each function, look for comments like `// Placeholder`.
> - If you see only logging and `Ok(())` or `Ok(true)` being returned, it's safe.
> - If you see real system calls, file operations, network connections, or anything that changes your system, that's a red flag.
>
> **Never run code you do not trust or understand.**
---
## Table of Contents
- [Why Choose PMSF?](#why-choose-pmsf)
- [Key Features](#key-features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Dynamic Registration](#dynamic-registration)
- [Logging & Telemetry](#logging--telemetry)
- [Chaining Techniques](#chaining-techniques)
- [Helpers](#helpers)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)
---
## Why Choose PMSF?
- **Purpose-Built for Security Research & Education:** PMSF is tailored for security professionals, educators, and students seeking a safe, hands-on environment to study and demonstrate malware staging and evasion techniques.
- **Risk-Free Simulation:** All operational stages are fully stubbed, guaranteeing a non-destructive, controlled experience ideal for experimentation and curriculum development.
- **Modular & Extensible Architecture:** Easily add, modify, or chain new techniques with a stage-based, pluggable design—enabling rapid prototyping and comparative analysis.
- **Comprehensive Observability:** Integrated logging and telemetry provide deep visibility into stage-level events, supporting detailed analysis and reporting.
- **Configurable & Reproducible:** Dynamic configuration and deterministic selection mechanisms allow for precise scenario customization and repeatable experiments.
---
## Key Features
- **Compile-Time Polymorphism:** Leverage the `rustmorphism` crate to generate multiple binaries at build time, enabling diverse technique selection.
- **Dynamic Configuration:** Select and orchestrate stages explicitly via a TOML configuration file (`config.toml`).
- **Runtime Extensibility:** Register custom techniques on the fly using a global registry and intuitive `register_*` functions.
- **Structured Error Handling:** Diagnose issues efficiently with the comprehensive `FrameworkError` enum.
- **Context Propagation:** Seamlessly transfer payloads and metadata between stages using the `StageContext` abstraction.
- **Integrated Logging:** Monitor stage-level events in real time with the `log` crate and `env_logger` integration.
- **Telemetry Hooks:** Instrument research and simulation workflows with the `TelemetryEvent` trait for custom callbacks.
- **Chaining Utilities:** Execute multiple techniques in sequence with `run_*_chain`, aggregating results and errors.
- **Advanced Selection Helpers:** Employ weighted random (`weighted_random_choice`) and conditional (environment/config) selection utilities for flexible technique orchestration.
- **Comprehensive Example:** Explore a full-featured demonstration in `examples/demo.rs` showcasing all major capabilities.
---
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
pmsf = "0.1.0"
```
Then import in Rust:
```rust
use pmsf::*;
```
---
## Quick Start
```rust
use pmsf::{
establish_persistence_poly,
execute_code_poly,
communicate_c2_poly,
perform_anti_analysis_poly,
StageContext,
};
fn main() {
// Initialize a default stage context (no payload, empty metadata)
let ctx = StageContext::default();
// Select and execute the persistence stage
let persistence = establish_persistence_poly();
persistence.establish_persistence(&ctx).expect("Persistence stage failed");
// Select and execute the anti-analysis stage
let anti_analysis = perform_anti_analysis_poly();
anti_analysis.perform_anti_analysis(&ctx).expect("Anti-analysis stage failed");
// Select and execute the code execution stage
let execution = execute_code_poly();
execution.execute_code(&ctx).expect("Execution stage failed");
// Select and execute the C2 communication stage
let c2 = communicate_c2_poly();
c2.communicate_c2(&ctx).expect("C2 stage failed");
}
```
---
## Configuration
To customize stage selection, create a `config.toml` file in your project root. This allows you to explicitly specify which technique to use for each stage, or omit entries to enable random selection.
```toml
# config.toml
# Specify one technique per stage, or omit to use random selection.
persistence = "ScheduledTasks"
execution = "MappingInjection"
c2 = "DNSTunneling"
anti_analysis = "VMDetection"
```
Load the configuration at runtime:
```rust
let config = FrameworkConfig::from_file("config.toml");
println!("Loaded config: {:?}", config);
```
---
## Dynamic Registration
You can register your own custom technique at runtime, enabling rapid prototyping and extension:
```rust
// Define and implement your stage trait
struct MyTechnique;
impl PersistenceStage for MyTechnique { /* ... */ }
// Register it under a unique name
register_persistence("MyTechnique", || Box::new(MyTechnique));
// Retrieve and use the registered technique by name
if let Some(inst) = get_persistence_by_name("MyTechnique") {
inst.establish_persistence(&ctx)?;
}
```
---
## Logging & Telemetry
PMSF supports integrated logging and custom telemetry callbacks for enhanced observability:
```rust
use log::LevelFilter;
use env_logger;
env_logger::builder().filter_level(LevelFilter::Info).init();
struct ConsoleTelemetry;
impl TelemetryEvent for ConsoleTelemetry {
fn on_event(&self, stage: &str, tech: &str, status: &str) {
println!("Telemetry: {}::{}, {}", stage, tech, status);
}
}
set_telemetry_callback(Box::new(ConsoleTelemetry));
```
All stages emit `info!` logs and trigger `on_event(...)` on success, or `error!` on failure.
---
## Chaining Techniques
You can execute multiple techniques in sequence and collect any errors for robust, multi-step simulations:
```rust
let errs = run_persistence_chain(&["RegistryRunKeys", "ScheduledTasks"]);
match errs {
Ok(_) => println!("All persistence steps succeeded."),
Err(e) => println!("Errors: {:?}", e),
}
```
---
## Helpers
PMSF provides utility functions for advanced technique selection:
- **Weighted random selection:**
```rust
weighted_random_choice(&[("A", 70), ("B", 30)])
```
- **Conditional selection based on environment/config:**
```rust
select_technique_by_condition(&choices, "ENV_VAR")
```
---
## Examples
Build and run the comprehensive demo:
```bash
cargo run --example demo
```
This example demonstrates config loading, registration, logging, telemetry, and chaining.
---
## Contributing
Issues, pull requests, and suggestions are welcome. Please follow standard Rust project conventions.
---
## License
The MIT License — see [LICENSE](LICENSE) for details.