development-guide.md

MalwareMinimizer Development Guide

This guide provides everything you need to know to start developing and contributing to the MalwareMinimizer project.

Table of Contents

• Project Architecture
• Development Environment Setup
• Project Structure
• Coding Standards
• Testing Approach
• Submitting Changes

Project Architecture

MalwareMinimizer follows a modular architecture designed to separate concerns and allow for easy testing and extension:

┌────────────┐      ┌────────────┐      ┌────────────┐
│    CLI     │─────▶│  Scanner   │─────▶│  Database  │
└────────────┘      └────────────┘      └────────────┘
       │                   │                   │
       │                   │                   │
       ▼                   ▼                   ▼
┌────────────┐      ┌────────────┐      ┌────────────┐
│ Quarantine │◀─────│ Detection  │◀─────│ Signatures │
└────────────┘      └────────────┘      └────────────┘

Core Components

1. CLI (src/cli/): Handles user interaction, parses commands and options.
2. Scanner (src/scanner/): Manages file traversal and detection logic for both fast and deep scans.
3. Database (src/database/): Manages local storage of malware signatures and updates.
4. Quarantine (src/quarantine/): Handles isolation and management of detected threats.
5. Utils (src/utils/): Common utilities used across components.

Core Workflows

1. Scanning Workflow:

   • CLI parses the scan command and options
   • Scanner recursively traverses the target path
   • For each file, compute hash and check against signature database
   • If deep scan is enabled, perform additional heuristic analysis
   • Return results to user

2. Quarantine Workflow:

   • Identified threats are moved to a secure location
   • Original metadata is preserved for potential restoration
   • File permissions are modified to prevent execution

3. Database Update Workflow:

   • Fetches latest signatures from trusted sources
   • Validates and merges new signatures with local database
   • Updates local database version information

Development Environment Setup

Prerequisites

• Rust (stable toolchain; see project setup script or rust-toolchain if present)
• Python 3.11
• Git

Quick Setup

We provide a setup script for Linux and macOS:

# Clone the repository
git clone https://github.com/Jordan231111/MalwareMinimizer.git
cd MalwareMinimizer

# Run the setup script
./scripts/setup.sh

Note: scripts/setup.sh installs the stable toolchain by default.

For Windows, please see the manual setup instructions below.

Manual Setup

1. Install Rust:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   rustup default stable

2. Install Python 3.11:

   • macOS: brew install python@3.11
   • Linux: Use your distribution's package manager
   • Windows: Download from python.org

3. Install Python dependencies (for helper scripts/tests):

   python3.11 -m pip install requests pytest rich

4. Install system dependencies (only if required):

   • If reqwest uses native TLS, you may need OpenSSL:
     • macOS: brew install openssl pkg-config
     • Linux: sudo apt install pkg-config libssl-dev build-essential

5. Build the project:

   cargo build

Project Structure

MalwareMinimizer/
├── .github/             # GitHub-specific configs (workflows, etc.)
├── benches/             # Performance benchmarks
├── docs/                # Documentation
├── python_scripts/      # Python helper scripts
├── scripts/             # Development and installation scripts
├── src/                 # Rust source code
│   ├── cli/             # Command-line interface
│   ├── database/        # Signature database
│   ├── quarantine/      # Threat isolation
│   ├── scanner/         # File scanning engine
│   └── utils/           # Common utilities
├── tests/               # Test suite
│   ├── integration/     # Integration tests
│   ├── security/        # Security-specific tests
│   └── README.md        # Testing guide
├── Cargo.toml           # Rust dependencies and config
├── Cargo.lock           # Lock file for dependencies
├── deny.toml            # Dependency vulnerability checking
└── README.md            # Project overview

Coding Standards

Rust Style Guidelines

1. Formatting:

   • We follow the Rust standard formatting guidelines
   • Run cargo fmt before committing code
   • CI will enforce formatting through GitHub Actions

2. Code Quality:

   • Use cargo clippy to catch common mistakes
   • Address all warnings or document why they're being suppressed
   • Comment functions with rustdoc-style documentation

3. Error Handling:

   • Use the anyhow crate for error context and propagation
   • Define custom errors with thiserror when appropriate
   • Avoid .unwrap() or .expect() in production code paths (allowed in tests)

4. Logging:

   • Use the log crate for all logging
   • Appropriate log levels:
     • error!: For user-facing errors
     • warn!: For concerning but non-fatal issues
     • info!: For normal operation information
     • debug!: For developer debugging information
     • trace!: For detailed tracing

Commit Messages

We follow the Conventional Commits specification:

• feat:: New features
• fix:: Bug fixes
• docs:: Documentation changes
• style:: Formatting changes
• refactor:: Code refactoring without functionality changes
• perf:: Performance improvements
• test:: Adding or fixing tests
• chore:: Maintenance tasks

Example: feat: implement deep scan heuristic detection

Testing Approach

MalwareMinimizer employs a comprehensive testing strategy:

1. Unit Tests:

   • Test individual components in isolation (within module files)
   • Run with cargo test --lib

2. Integration Tests:

   • Test how components work together
   • Located in tests/integration/
   • Run with cargo test --test integration

3. Security Tests:

   • Focus on security-specific aspects
   • Located in tests/security/
   • Run with cargo test --test security

4. Performance Benchmarks:

   • Located in benches/
   • Run with cargo bench

5. Test Data:

   • Never use real malware, even in tests
   • Use the EICAR test string for simulating detections

Running Tests

# Run all tests
cargo test

# Run with detailed output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Run benchmarks
cargo bench

Submitting Changes

1. Fork the repository:

   • Create your own fork of the repository

2. Create a feature branch:

   • Name it according to the feature or fix you're implementing
   • Example: feature/deep-scan-implementation

3. Make your changes:

   • Follow coding standards
   • Add tests for new functionality
   • Update documentation as needed

4. Run tests locally:

   • Ensure all tests pass with cargo test
   • Run clippy with cargo clippy
   • Format code with cargo fmt

5. Submit a pull request:

   • Provide a clear description of the changes
   • Link to any related issues
   • Include screenshots or examples if applicable

6. Code review:

   • Address any feedback from maintainers
   • Make necessary adjustments
   • Once approved, your changes will be merged

Troubleshooting

Common Issues

1. Build Failures:

   • Check that you're using the stable Rust toolchain
   • Ensure all dependencies are installed

2. Test Failures:

   • Check if tests are platform-specific
   • Ensure your environment is properly configured

3. Permission Issues:

   • Some tests may require elevated permissions on certain platforms

4. Antivirus False Positives on Windows:

   • The test suite uses the EICAR test string, which Windows Defender and other antivirus software may flag as malware.
   • If tests fail or compiled binaries are deleted, add an exclusion for the project folder:
     • Windows Security > Virus & threat protection > Manage settings > Exclusions
     • Add an exclusion for the project root directory.

For any other issues, please check the GitHub issues page or create a new issue.

Contributor Onboarding: Rust Learning Path (1 Week)

This project expects contributors to be comfortable with Rust basics, error handling, and testing. The path below is designed to get a new contributor productive within a week.

Recommended Resources (Beginner-Friendly, Time-Boxed)

Minimum (required for the week, ~60–90 minutes/day):

1. The Rust Programming Language (The Book)
   Read Chapters 1–4, then skim Chapters 6, 9, and 11 (enums, error handling, tests).
2. Rust by Example
   Use it only as a quick reference when a concept is unclear.

Optional (if you have extra time): 3. Rustlings (hands-on exercises) 4. Exercism (Rust Track) (practice problems + feedback) 5. Rust API Guidelines (for idiomatic APIs) 6. Cargo Book + Rust Reference (tooling + language reference) 7. Rustonomicon (only if working with unsafe or FFI)

One-Week Mini Project (Required Documentation)

Goal: Ship a small, production-quality feature + tests + documentation in one week. This builds confidence in the codebase and establishes habits.

Suggested mini project (recommended): Add a hash subcommand

What it does:

• Computes file hashes (sha256/sha1/md5) for a path or list of paths
• Outputs a JSON summary and a human-readable summary
• Respects size limits and error handling conventions

Deliverables:

• Rust implementation + tests
• CLI documentation update (CLI_USER_DOC.md)
• Architecture note update (where the new command lives)
• Short write-up in the PR describing design decisions

Week plan (not overwhelming):

• Day 1 (60–90 min): Read The Book Chapters 1–4, run cargo test, skim CLI commands.
• Day 2 (60–90 min): Implement command skeleton + argument parsing.
• Day 3 (60–90 min): Add hashing logic + unit tests.
• Day 4 (60–90 min): Add integration tests + update CLI docs.
• Day 5 (30–60 min): Polish error handling, write a short design note, open PR.

What you can skip this week:

• Async Rust
• Unsafe Rust
• Macro-heavy patterns
• Performance tuning and benchmarks