# Contributing to Malware & Monsters

Thank you for your interest in contributing to Malware & Monsters! This guide will help you get started with contributing to our collaborative cybersecurity education framework.

## 🎯 Ways to Contribute

### 📝 **Content Contributions**
- **New Malmon profiles** - Add real malware families as learning scenarios
- **Session scenarios** - Create new training situations and adaptations
- **Role descriptions** - Enhance or add new incident response roles
- **Quick references** - Improve guides and cheat sheets
- **Real-world examples** - Share actual incident response experiences

### 🎨 **Technical Contributions**
- **Documentation improvements** - Fix errors, add clarity, improve organization
- **Build system enhancements** - Improve Makefile, add new targets
- **Theme and styling** - Enhance visual design and user experience
- **Quarto filters** - Develop new custom components
- **Presentation templates** - Create slide decks for different audiences

### 🎬 **Presentation Materials**
- **Training slides** - Create presentations for different contexts
- **Workshop materials** - Develop facilitation resources
- **Demo scenarios** - Build interactive examples
- **Conference talks** - Share speaking materials and experiences

### 🐛 **Quality Improvements**
- **Bug reports** - Identify and report issues
- **Testing** - Validate builds across different platforms
- **Accessibility** - Improve usability for diverse learners
- **Performance** - Optimize build times and output quality

## 🤝 Community Contributions

We welcome community contributions of malmons and scenarios! If you're creating new content for the community, please follow these guidelines:

### 📋 Community Content Guidelines

For detailed contribution guidelines, see [COMMUNITY_CONTENT.md](docs/COMMUNITY_CONTENT.md).

### 🏷️ Categorization System

**Malmon Categories:**
- `real-world`: Based on actual malware (contemporary or legacy)
- `community`: Fictional/educational scenarios from contributors
- `experimental`: Research-based or predictive threats

**Scenario Categories:**
- `core`: Official scenarios by maintainers
- `community`: Contributed by community members
- `experimental`: Research or predictive scenarios

### 📁 Where to Place Community Content

```
shared/malmon-cards/community/          # Community malmon cards
im-handbook/resources/malmon-details/community/  # Community malmon details

slides/scenarios/community/              # Community scenarios
├── tier1-beginner/
├── tier2-intermediate/
└── tier3-advanced/

im-handbook/resources/scenario-cards/community/  # Community scenario cards
im-handbook/resources/scenario-planning-docs/community/  # Community planning docs
```

### 📊 Required Metadata

**For Malmon Cards:**
```yaml
---
name: "Malmon Name"
type: "Type/Subtype"
origin: "community"  # REQUIRED
contributor: "Your Name"
contribution-date: "YYYY-MM-DD"
---
```

**For Scenarios:**
```yaml
metadata:
  mm-scenario-id: "unique-identifier"
  mm-origin: "community"  # REQUIRED
  mm-malmon: "Malmon Name"
  mm-malmon-origin: "community"  # must match malmon
  mm-difficulty: "⭐⭐"
  mm-tier: "Tier X"
  mm-contributor: "Your Name"
  mm-contribution-date: "YYYY-MM-DD"
  mm-license: "CC-BY-SA-4.0"
```

### 🎨 Visual Differentiation

Community content should be clearly marked:

```markdown
::: {.scenario-header}
## Scenario Title
**Origin:** 🤝 Community  **Tier:** ⭐⭐  **Contributor:** Name
:::
```

## 🚀 Getting Started

### Prerequisites
Before contributing, ensure you have:

- **Git** for version control
- **Quarto** (version 1.4+) for documentation building
- **Text editor** of your choice
- **GitHub account** for collaboration
- **Optional but recommended:** [`entr`](https://eradman.com/entrproject/) for `make watch` (install via `brew install entr` on macOS or `sudo apt install entr` on Debian/Ubuntu)

Check your setup:
```bash
git --version
quarto --version
make check-deps
```

### Development Setup

1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
   ```bash
   git clone https://github.com/YOUR-USERNAME/malware-and-monsters.git
   cd malware-and-monsters
   ```

3. **Set up the upstream remote**:
   ```bash
   git remote add upstream https://github.com/ORIGINAL-OWNER/malware-and-monsters.git
   ```

4. **Test the build system**:
   ```bash
   make all validate
   ```

5. **Start local development**:
   ```bash
   make watch    # Requires entr; use `quarto preview` if entr isn't installed
   ```

### Development Workflow

1. **Pick an issue** from the [project board](https://github.com/users/klausagnoletti/projects/1). Issues in **🎯 Ready** status are scoped and waiting for someone to pick up. Check that no one else has already assigned it or opened a PR for it.

2. **Claim the issue** before you write anything:
   - **Assign it to yourself** on GitHub — this is the primary signal the issue is taken
   - **Set its status to 🚧 In Progress** on the project board — this moves it out of Ready so no one else picks it up

3. **Create a feature branch**:
   ```bash
   git checkout -b feature/your-contribution-name
   ```

4. **Make your changes** following our guidelines below

5. **Test your changes**:
   ```bash
   make clean all validate
   ```

6. **Commit with clear messages**:
   ```bash
   git add .
   git commit -m "Add new Malmon: ExampleThreat

   - Adds ExampleThreat Malmon with Trojan/Stealth typing
   - Includes ATT&CK mappings for T1055, T1027
   - Provides beginner-friendly facilitation notes"
   ```

7. **Push to your fork**:
   ```bash
   git push origin feature/your-contribution-name
   ```

8. **Create a Pull Request** on GitHub and set the issue status to **👀 Review/Testing** on the project board. This tells the team your code is done and waiting for review.

### Keeping the project board up to date

The project board is only useful if it reflects reality. Update your issue as you go:

| Situation | What to do |
|-----------|------------|
| You're actively working | Status: 🚧 In Progress |
| You're stuck and need help | Status: 🔒 Blocked — leave a comment on the issue explaining what's in the way |
| Your PR is open and waiting | Status: 👀 Review/Testing |
| You're abandoning the issue | Unassign yourself, set status back to 🎯 Ready, leave a comment with any useful context for the next person |

## 📋 Contribution Guidelines

### Content Standards

#### **Malmon Profiles**
When creating new Malmon profiles:

- **Base on real malware** families with documented behavior
- **Include accurate technical details** while maintaining accessibility
- **Map to MITRE ATT&CK** techniques when applicable
- **Provide facilitation guidance** for different experience levels
- **Follow the established template** structure

Example structure:
```markdown
# MalmonName

## Overview
Brief description linking to real malware family.

## Technical Details
- **Type:** Primary/Secondary
- **Threat Level:** ⭐⭐⭐
- **Evolution Trigger:** Specific conditions

## Abilities
### Primary Ability: Name
Description of main capability

### Special Attack: Name  
Description of escalation behavior

## ATT&CK Mapping
::: {.attck-mapping}
INITIAL ACCESS:
T1566.001 Spearphishing Attachment

EXECUTION:
T1059.003 Windows Command Shell
:::

## Facilitation Notes
Guidance for Incident Masters on running scenarios.
```

#### **Documentation**
- **Write clearly** for diverse technical backgrounds
- **Use inclusive language** and avoid jargon without explanation
- **Include examples** to illustrate concepts
- **Cross-reference** related content appropriately
- **Test all links** and references

#### **Presentations**
- **Follow the RevealJS theme** for consistency
- **Include speaker notes** for facilitation guidance
- **Use fragments** appropriately for progressive disclosure
- **Test on different screen sizes**
- **Provide clear learning objectives**

### Technical Standards

#### **File Organization**
- Place files in appropriate directories following existing structure
- Use descriptive, lowercase filenames with hyphens: `my-new-content.qmd`
- Include proper YAML front matter in all `.qmd` files
- Reference shared resources using relative paths

#### **Code Quality**
- **Test builds** before submitting: `make all validate`
- **Follow existing patterns** for consistency
- **Document any new dependencies** or requirements
- **Use semantic commit messages**

#### **Styling**
- **Follow existing CSS/SCSS** patterns
- **Test responsive design** on mobile devices
- **Maintain accessibility** standards
- **Use consistent color schemes** from theme variables

### Content Guidelines

#### **Educational Approach**
- **Collaborative learning first** - content should enable team discovery
- **Question-driven** rather than answer-providing
- **Inclusive of different experience levels**
- **Safe learning environment** - mistakes are learning opportunities
- **Real-world relevance** with practical application

#### **Technical Accuracy**
- **Verify information** with authoritative sources
- **Update outdated references** to current best practices
- **Balance accuracy with accessibility**
- **Cite sources** when referencing external research

#### **Community Focus**
- **Support diverse participation** across backgrounds and experience
- **Encourage knowledge sharing** and peer learning
- **Build on existing community wisdom**
- **Foster collaborative problem-solving**

## 🔍 Review Process

### Pull Request Requirements
- **Clear description** of changes and motivation
- **Working build** with `make all validate` passing
- **Appropriate scope** - focused changes are easier to review
- **Documentation updates** if adding new features
- **Tests** if applicable

### Review Criteria
Reviewers will evaluate:

- **Content quality** and educational value
- **Technical accuracy** and implementation
- **Consistency** with existing patterns and style
- **Accessibility** and inclusive design
- **Community alignment** with collaborative learning principles

### Feedback Process
- Reviews aim to be **constructive and educational**
- **Multiple rounds** may be needed for substantial contributions
- **Collaboration** to improve contributions is encouraged
- **Learning opportunity** for both contributors and reviewers

## 📚 Content Types

### New Malmon Profiles

**What we need:**
- Real malware families not yet covered
- Diverse threat types (APT, ransomware, banking trojans, etc.)
- Varying difficulty levels for different learning stages
- Current and historically significant threats

**How to contribute:**
1. Research the malware family thoroughly
2. Create profile using `im-handbook/resources/malmon-details/template.qmd`
3. Include ATT&CK mappings and facilitation notes
4. Test with actual learning sessions if possible

### Session Scenarios

**What we need:**
- Adaptations for different organizational contexts
- Industry-specific scenarios (healthcare, finance, education)
- Current event tie-ins and trending attack methods
- Cross-cultural and international perspectives

**How to contribute:**
1. Document successful adaptations you've run
2. Include context, modifications, and lessons learned
3. Provide facilitator guidance for replication
4. Share participant feedback and outcomes

### Training Materials

**What we need:**
- Onboarding materials for new facilitators
- Advanced facilitation techniques
- Assessment and evaluation frameworks
- Integration guides for existing training programs

**How to contribute:**
1. Share successful training approaches
2. Document lessons learned from real implementations
3. Create templates and frameworks others can adapt
4. Provide metrics and evaluation methods

### Presentation Content

**What we need:**
- Executive overview presentations
- Technical deep-dive presentations
- Conference talk materials
- Workshop facilitation slides

**How to contribute:**
1. Use `make slide-template` to start
2. Follow the established theme and patterns
3. Include speaker notes and facilitation guidance
4. Test with real audiences when possible

## 🌟 Recognition

### Contributor Recognition
- **Discoverer Status** for first contributors of new Malmon types
- **Community Champion** recognition for outstanding community building
- **Technical Innovation** awards for significant enhancements
- **Attribution** in relevant materials and documentation

### Hall of Fame
Outstanding contributors will be recognized in:
- Project documentation and website
- Conference presentations and publications
- Community newsletters and updates
- Annual contributor highlights

## 💬 Communication

### GitHub Channels
- **Issues** - Bug reports, feature requests, specific problems
- **Discussions** - General questions, ideas, community conversation
- **Pull Requests** - Code and content review and collaboration

### Community Guidelines
- **Be respectful** and inclusive in all interactions
- **Assume positive intent** when reviewing or receiving feedback
- **Ask questions** when something is unclear
- **Share knowledge** generously with the community
- **Celebrate successes** and learn from challenges together

### Getting Help
- **Check existing issues** before creating new ones
- **Use descriptive titles** for issues and discussions
- **Provide context** including build output and error messages
- **Tag appropriately** to help others find relevant discussions

## 🔧 Advanced Contributions

### Custom Quarto Filters
If you want to create new Quarto filters:

1. Study existing filters in `shared/`
2. Follow Lua filter best practices
3. Include comprehensive documentation
4. Provide examples and test cases
5. Consider backward compatibility

### Build System Enhancements
For Makefile improvements:

1. Test across different platforms (Linux, macOS, Windows)
2. Maintain existing functionality
3. Add appropriate help documentation
4. Consider performance implications
5. Include error handling and validation

### Theme and Styling
For visual improvements:

1. Maintain brand consistency across all formats
2. Test on multiple devices and screen sizes
3. Consider accessibility requirements
4. Preserve existing functionality
5. Document any new CSS classes or components

## 📖 Resources

### Documentation
- [Build System Guide](docs/BUILD_SYSTEM.md) - Comprehensive Makefile documentation
- [Slides Integration](docs/SLIDES_INTEGRATION.md) - RevealJS presentation system
- [Deployment Guide](docs/DEPLOYMENT_GUIDE.md) - Publishing and hosting options

### External Resources
- [Quarto Documentation](https://quarto.org/docs/) - Official Quarto guides
- [MITRE ATT&CK](https://attack.mitre.org/) - Threat behavior framework
- [RevealJS Documentation](https://revealjs.com/) - Presentation framework
- [Collaborative Learning Research](https://www.researchgate.net/topic/Collaborative-Learning) - Educational background

### Learning Materials
- [Players Handbook](players-handbook/) - Understanding the participant experience
- [IM Handbook](im-handbook/) - Facilitation techniques and approaches
- [Quick References](players-handbook/resources/) - At-a-glance guides

## 🎉 Thank You!

Your contributions help make cybersecurity education more collaborative, engaging, and effective. Whether you're fixing a typo, adding a new Malmon, or building presentation materials, every contribution matters.

The Malware & Monsters community grows stronger with each person who shares their knowledge and experience. Thank you for being part of this collaborative learning adventure!

---

**Questions?** Open a [GitHub Discussion](https://github.com/[username]/malware-and-monsters/discussions) or check our [existing issues](https://github.com/[username]/malware-and-monsters/issues).

**Ready to contribute?** Fork the repository and dive in! The community is here to support you.