Malware & Monsters

"Gotta Catch 'Em All... Before They Catch You!"

Collaborative cybersecurity learning through incident response

🌐 Visit the Live Site for the complete experience

Overview

Malware & Monsters is an innovative cybersecurity education framework that combines collaborative storytelling with creature-collection mechanics to create engaging, practical incident response training. Teams work together to identify, analyze, and respond to digital threats represented as "Malmons" - creatures with distinct behaviors, capabilities, and weaknesses.

Legacy & Contemporary Threats: The framework spans cybersecurity history from foundational attacks like Code Red (2001) and Stuxnet (2010) to modern threats like LockBit and FakeBat, helping teams understand threat evolution and apply lessons across decades of cybersecurity incidents.

What Makes This Different

• Your expertise drives the content - participant knowledge creates the learning experience
• Collaborative discovery over passive presentations
• Real-world scenarios with safe learning environment
• Role-based teamwork reflecting actual incident response dynamics
• Community knowledge building through shared experiences

Documentation & Presentations

This repository contains comprehensive learning materials in multiple formats:

📋 Technical Documentation

Detailed technical rationale and design decisions:

• Malware Classification System Rationale - Educational vs. industry taxonomy balance

📖 Players Handbook

Your complete guide to participating in Malware & Monsters sessions:

• Understanding Malmons and the type system
• Incident response roles and team dynamics
• Game mechanics and progression systems
• Community collection and competitive elements

🎯 Incident Master Handbook

Complete facilitation guide for running sessions:

• Facilitation philosophy and techniques
• Technical foundation and MITRE ATT&CK integration
• Session management and troubleshooting
• Advanced scenarios and community building

🎬 Presentation Slides

RevealJS presentations with consistent theming:

• Player introduction slides
• IM training presentations
• Executive overviews
• Technical deep dives

📑 PDF Downloads

Both handbooks are available as PDFs for offline reference and printing:

• Players Handbook PDF
• IM Handbook PDF

Quick Start

For Players

1. Read the Welcome chapter to understand the philosophy
2. Review Understanding Malmons for core concepts
3. Choose your Incident Response Role
4. Jump into your first session - no additional prep required!

For Incident Masters

1. Review the Facilitation Philosophy
2. Complete the Technical Foundation crash course
3. Practice with Session Management techniques
4. Start with beginner-friendly Malmons like GaboonGrabber

For Presenters

1. Create slides using make slide-template
2. Customize content for your audience
3. Present with make present

Repository Structure

malware-and-monsters/
├── docs/                    # Developer documentation and guides
├── players-handbook/        # Player documentation (13 chapters)
│   ├── chapters/           # Game rules, roles, and participation
│   └── resources/          # Quick references and practical guides
├── im-handbook/            # Facilitator documentation (15 chapters)
│   ├── chapters/           # Facilitation techniques and session management
│   └── resources/          # Malmon profiles, scenario cards, and tools
├── slides/                 # RevealJS presentation materials
├── shared/                 # Common resources and assets
│   ├── filters/           # Custom Quarto filters for game components
│   ├── malmon-cards/      # Creature definitions (12 malmons)
│   ├── badge-images/      # Progression system graphics
│   └── (styling, JavaScript, shared content)
├── _scss/                  # Unified theming and styling system
├── scripts/                # Development automation tools
├── .github/workflows/      # CI/CD automation
├── Makefile               # Unified build system
└── (configuration files)

Building the Documentation

This project uses a unified build system with Quarto that renders all 162 files in a single optimized pass. You can use either direct Quarto commands or the Makefile build system.

Prerequisites

• Quarto (version 1.4+)
• Python 3 (for local server)
• Optional: XeLaTeX (for PDF generation)
• Optional but recommended: entr for make watch

Install entr with a single command on most systems:

# macOS
brew install entr

# Debian/Ubuntu
sudo apt install entr

# FreeBSD
pkg install entr

When entr isn't available, run quarto preview directly for watch-mode behavior.

For PDF Generation: If you want to build PDFs, you'll need a complete LaTeX installation including:

# Ubuntu/Debian users:
sudo apt install texlive-latex-extra texlive-fonts-recommended

# macOS users:
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr install needspace collection-fontsrecommended

# Alternatively, use the automated installer:
make install-latex-packages

Note: PDF builds require additional LaTeX packages like needspace. If PDF builds fail with "Undefined control sequence" errors, install the full texlive-latex-extra package or use HTML-only builds with make quick.

Check your setup:

make check-deps

Quick Build Commands

Recommended approach (direct Quarto):

# Build everything (HTML + PDF + Slides) - 162 files in single pass
quarto render

# Serve locally for development
quarto preview

# Clean and rebuild everything
rm -rf _output && quarto render

Alternative approach (Makefile - equivalent functionality):

# Build everything (HTML + PDF + Slides) - uses unified build
make all

# Build and serve locally
make serve

# Build and present slides
make present

# Quick build (HTML + slides, no PDFs)
make quick

# Generate two AI-ready text bundles (Players + IM)
make text-handbooks

# Clean and rebuild everything
make clean all

make text-handbooks writes _output/text/players-handbook.txt and _output/text/im-handbook.txt, aggregating every chapter, resource, walkthrough, and reference into two AI-ready plain text bundles.

Development Workflow

Direct Quarto approach:

# Watch for changes and auto-rebuild
quarto preview

# No individual component builds - unified system renders everything

Makefile approach (with additional tooling):

# Watch for changes and auto-rebuild
make watch          # Requires entr (see prerequisites)

# Individual components (note: most use unified build)
make players          # Players Handbook (via unified build)
make im              # IM Handbook (via unified build)
make slides          # All slide decks only

# Clean cache files
make clean-cache     # Remove Quarto cache files

Advanced Build Options

# Create new slide template
make slide-template

# Validate build output
make validate

# Debug build information
make debug

Troubleshooting Common Issues

PDF Build Failures:

# Error: "Undefined control sequence \needspace"
sudo apt install texlive-latex-extra  # Ubuntu/Debian
# OR use HTML-only builds:
make quick

# Error: Missing fonts or packages
make install-latex-packages
# OR install complete LaTeX:
sudo apt install texlive-full

Quarto Issues:

# Cache-related problems
make clean-cache

# Missing directories
make clean all

# Build dependency issues
make check-deps

Performance Issues:

# Fast development builds (no PDFs)
make quick

# Parallel builds for speed
make -j$(nproc) all

# Build specific components only
make players  # or make im, make slides

Output Structure

_output/
├── index.html                 # Main landing page
├── community.html            # Community information
├── players-handbook/         # Players handbook
│   ├── index.html           # HTML version
│   ├── chapters/            # Individual chapters
│   └── resources/           # Quick references
├── im-handbook/             # IM handbook
│   ├── index.html          # HTML version
│   ├── chapters/           # IM chapters
│   └── resources/          # Malmon details
├── slides/                 # RevealJS presentations
│   └── *.html             # Generated slide presentations
├── shared/                # Shared resources
│   └── glossary.html     # Shared glossary
├── players-handbook.pdf  # PDF download
├── im-handbook.pdf       # PDF download
└── site_libs/            # Quarto assets

Creating Presentations

The framework includes full RevealJS presentation support with consistent theming:

Creating Slides

# Generate starter template
make slide-template

# Edit your slides
vim slides/my-presentation.qmd

# Build and present
make present

Slide Features

• Consistent branding with main documentation
• Interactive Malmon cards and role explanations
• Session flow visualizations
• Speaker notes support
• Fragment animations and transitions
• Multi-column layouts
• Statistics dashboards

Example Slide Content

---
title: "Malware & Monsters Introduction"
format:
  revealjs:
    theme: ../shared/revealjs-theme.scss
---

# Welcome {background-color="#2c3e50"}

## Collaborative Cybersecurity Learning

::: {.fragment}
Transform incident response training through teamwork
:::

The Malmon Collection

The framework includes detailed profiles of real malware families represented as Malmons, spanning legacy and contemporary threats:

Contemporary Malmons (2010s-2020s):

• GaboonGrabber (Trojan/Stealth) - Perfect for beginners
• WannaCry (Worm/Ransomware) - Network propagation scenarios
• LockBit (Ransomware/Criminal) - Modern cybercrime operations
• FakeBat (Trojan/Loader) - Current threat landscape

Legacy Malmons (Historical Impact):

• Code Red (Worm/2001) - Foundation of internet security
• Stuxnet (APT/Rootkit/2010) - Nation-state cyber warfare
• Ghost RAT (Remote Access/2008) - Early APT campaigns
• Poison Ivy (Backdoor/2005) - Classic persistent threats

Each Malmon includes:

• Type effectiveness relationships
• Evolution mechanics and triggers
• Real-world technical details
• MITRE ATT&CK technique mappings
• Facilitation guidance for IMs

Discord Bot

The Malware & Monsters Discord Bot provides automated community engagement for the HackBack Discord server. It highlights contribution opportunities, celebrates merged PRs, showcases project features, and guides new contributors.

Features:

• Issue Opportunity Bot - Weekly highlights of contribution opportunities
• Victory Lap Bot - Celebrates merged PRs and thanks contributors
• Getting Started Spotlight - Showcases contribution paths
• Momentum Tracker - Weekly development activity summaries
• Did You Know Bot - Feature spotlights
• Behind the Malmon Bot - Malware family deep dives
• Vibecode Challenge Bot - AI-powered gamified contribution prompts

Quick Start:

cd discord-bot
cp .env.example .env
# Configure .env and config/settings.yml
docker compose up -d

Documentation: All Discord Bot documentation is located in discord-bot/docs/:

• 📖 DISCORD_BOT_DEPLOYMENT.md - Complete deployment guide
• 🧪 DISCORD_BOT_TESTING.md - Testing guide (35+ tests)
• ⚙️ ENV_CONFIGURATION.md - Environment variables
• 🤖 AI_PROVIDER_CONFIGURATION.md - AI setup

See: discord-bot/README.md for complete bot documentation

Community & Contributions

Getting Involved

• Run sessions with your team or organization
• Share scenarios and adaptations
• Contribute Malmon profiles for new threats
• Improve documentation and training materials
• Build tools for session management
• Create presentations for conferences and training

Contributing Guidelines

1. Fork the repository
2. Create feature branch: git checkout -b feature/new-malmon
3. Make changes following existing patterns
4. Test documentation builds: make validate
5. Submit pull request with clear description

Development Setup

# Clone repository
git clone https://github.com/klausagnoletti/malware-and-monsters.git
cd malware-and-monsters

# Check dependencies
make check-deps

# Test build system
make all validate

# Quick build and serve
make quick && make serve

Developer Guides

• 🏗️ Build System - Makefile documentation and build commands
• 🔧 Development Workflow - Automated development tools and visual testing
• 🎬 Slides Integration - RevealJS presentations and theming
• 🛠️ Filters Usage - Custom Quarto filters and components
• 🤝 Contributing Guide - How to contribute content and code

Community Resources

• Discussions: Use GitHub Discussions for questions and ideas
• Issues: Report bugs or request features
• Contributing: See our Contributing Guide for how to get involved
• Wiki: Community-contributed scenarios and adaptations
• Releases: Stable versions for workshops and training

Deployment Options

Local Development

# Build and serve locally
make serve
# Available at http://localhost:8000

# Development with auto-rebuild
make watch          # Requires entr (run quarto preview if entr isn't installed)

GitHub Pages

# Prepare for GitHub Pages deployment
make github-pages

# Commit and push to gh-pages branch
# Documentation automatically deploys

Production Deployment

# Build everything for production
make deploy-prep

# Upload _output/ directory to your web server
# Contains complete site with PDFs and slides

Educational Philosophy

Malware & Monsters is built on evidence-based learning principles:

• Collaborative learning is more effective than individual study
• Active practice beats passive information consumption
• Diverse perspectives improve problem-solving quality
• Safe failure accelerates skill development
• Community knowledge benefits everyone

Technical Features

Unified Build System

• 162 files in single pass - all handbooks, PDFs, slides, and pages rendered together
• Dual approach supported - use quarto render directly or make commands (equivalent)
• Intelligent dependency tracking via Makefile for specialized builds
• Consistent theming across all formats
• PDF integration with download links
• RevealJS presentations with matching styles
• GitHub Actions compatibility - uses unified build automatically

Custom Quarto Components

• Malmon card filter for interactive creature displays
• ATT&CK mapping filter for technique visualization
• Unified themes across books and presentations
• Responsive design for all screen sizes

Development Tools

• Watch mode for automatic rebuilds
• Validation to check build integrity
• Debug information for troubleshooting
• Modular structure for easy customization

License

This project is released under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 to encourage community contribution while maintaining educational focus.

Usage Terms

You are free to:

• Use, share, and adapt this material for non-commercial educational purposes
• Remix and build upon the material as long as you share under the same license

Commercial use (including paid workshops, training sessions, or monetized events) requires a separate commercial license. Please contact Lena Yu for commercial licensing arrangements.

What constitutes commercial use:

• Paid cybersecurity training workshops using Malware & Monsters
• Commercial training companies offering M&M-based sessions
• Consulting services built around M&M methodology
• Any situation where participants pay specifically for M&M content

Non-commercial use includes:

• University courses, internal corporate training, research use
• Personal and hobbyist activities, non-profit educational events

Acknowledgments

• Lena Yu for the original Malmon concept and research
• HackBack for the foundational incident response game framework
• Klaus Agnoletti and Glen Sorenson for the initial version of Malware & Monsters and the workshop at Malware Village 2025 that started it all
• MITRE ATT&CK for the threat behavior taxonomy
• The cybersecurity community for collaborative learning inspiration
• Quarto team for the excellent documentation framework

Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Build Problems: Run make debug and include output in issue reports
• Community: GitHub Discussions

---

Ready to start your cybersecurity learning adventure?

• 📖 New to the system? Check out the Players Handbook
• 🎯 Want to facilitate? Start with the IM Handbook
• 🎬 Need to present? Run make slide-template to get started
• 🚀 Ready to build? Run make all and join the community!

Transform cybersecurity education through collaborative learning.