Merge pull request #64 from CarterPerez-dev/phase/3.4

add and create all learn/ folders for beginner projects

Author: CarterPerez-dev

CONTRIBUTING.md

@@ -217,7 +217,7 @@ mypy your_module/
 
 **Code Formatting:**
 
-Format your code using the repository's custom YAPF configuration. Copy the [.style.yapf](https://github.com/CarterPerez-dev/Cybersecurity-Projects/blob/main/.style.yapf) file and place it in the root of your project directory.
+Format your code using the repository's custom YAPF configuration. Copy the [.style.yapf](https://github.com/CarterPerez-dev/Cybersecurity-Projects/blob/main/TEMPLATES/.style.yapf) file and place it in the root of your project directory.
 ```bash
 yapf -i -r -vv your_project/
 ```

PROJECTS/beginner/caesar-cipher/learn/00-OVERVIEW.md

@@ -0,0 +1,104 @@
+# Caesar Cipher CLI Tool
+
+## What This Is
+
+A command line tool that implements the Caesar cipher, one of the oldest known encryption techniques. It shifts each letter in your text by a fixed number of positions in the alphabet. The tool can encrypt messages, decrypt them if you know the key, or crack encrypted text by trying all possible shifts and ranking them using frequency analysis.
+
+## Why This Matters
+
+The Caesar cipher is weak by modern standards, but understanding how to break it teaches fundamental cryptanalysis skills that apply to stronger systems. Every security professional should know why simple substitution ciphers fail.
+
+**Real world scenarios where this applies:**
+- ROT13 is still used for spoiler text on forums and in email (it's Caesar with key=13)
+- Understanding frequency analysis helps you break other substitution ciphers found in CTF challenges
+- The concept of brute forcing a small key space applies to weak passwords, short PINs, and poorly designed crypto
+
+## What You'll Learn
+
+This project teaches you how classical cryptography breaks down under statistical analysis. By building it yourself, you'll understand:
+
+**Security Concepts:**
+- Substitution ciphers: how they work and why character frequency gives them away
+- Brute force attacks: when the key space is small enough (26 possibilities here), trying everything is trivial
+- Frequency analysis: real English text has predictable letter patterns that survive encryption
+
+**Technical Skills:**
+- Chi-squared statistical testing to score how "English-like" text appears
+- Building CLI tools with proper argument parsing (using Typer)
+- Implementing both encryption and cryptanalysis in the same codebase
+
+**Tools and Techniques:**
+- Typer for command line interfaces with automatic help text
+- Rich library for colored terminal output and formatted tables
+- Python's Counter for frequency counting and statistical analysis
+
+## Prerequisites
+
+Before starting, you should understand:
+
+**Required knowledge:**
+- Python basics: functions, classes, list comprehensions
+- String manipulation: iterating characters, checking if they're letters
+- Modular arithmetic: why `(25 + 3) % 26 = 2` wraps around the alphabet
+
+**Tools you'll need:**
+- Python 3.12 or higher
+- pip for installing dependencies
+- A terminal where you can run commands
+
+**Helpful but not required:**
+- Basic statistics (what chi-squared means)
+- Some exposure to encryption concepts
+
+## Quick Start
+
+Get the project running locally:
+```bash
+# Clone and navigate
+cd PROJECTS/beginner/caesar-cipher
+
+# Install with dependencies
+pip install -e .
+
+# Encrypt some text
+caesar-cipher encrypt "HELLO WORLD" --key 3
+
+# Decrypt it back
+caesar-cipher decrypt "KHOOR ZRUOG" --key 3
+
+# Crack it without knowing the key
+caesar-cipher crack "KHOOR ZRUOG"
+```
+
+Expected output: You should see `KHOOR ZRUOG` when encrypting, `HELLO WORLD` when decrypting, and a ranked table of all 26 possible decryptions when cracking (with the correct one at the top).
+
+## Project Structure
+```
+caesar-cipher/
+├── src/caesar_cipher/
+│   ├── cipher.py         # Core encryption/decryption logic
+│   ├── analyzer.py       # Frequency analysis for cracking
+│   ├── constants.py      # English letter frequencies, alphabet
+│   ├── main.py          # CLI commands (encrypt/decrypt/crack)
+│   └── utils.py         # File I/O and input validation
+├── tests/               # Pytest test suite
+└── pyproject.toml      # Project dependencies and config
+```
+
+## Next Steps
+
+1. **Understand the concepts** - Read [01-CONCEPTS.md](./01-CONCEPTS.md) to learn why Caesar ciphers are broken
+2. **Study the architecture** - Read [02-ARCHITECTURE.md](./02-ARCHITECTURE.md) to see how the pieces fit together
+3. **Walk through the code** - Read [03-IMPLEMENTATION.md](./03-IMPLEMENTATION.md) for line by line explanation
+4. **Extend the project** - Read [04-CHALLENGES.md](./04-CHALLENGES.md) to build variants like Vigenère cipher
+
+## Common Issues
+
+**"Key must be between -25 and 26" error**
+```
+ValueError: Key must be between -25 and 26
+```
+Solution: Caesar cipher only makes sense with shifts from -25 to 26. Use a key in that range. The code validates this in `cipher.py:20-22`.
+
+**No output when piping from stdin**
+Solution: Make sure you're actually sending text. Try `echo "TEST" | caesar-cipher encrypt --key 5` instead of just `caesar-cipher encrypt --key 5`.

PROJECTS/beginner/caesar-cipher/learn/01-CONCEPTS.md

@@ -0,0 +1,221 @@
+# Core Security Concepts
+
+This document explains the security concepts you'll encounter while building this project. These are not just definitions, we'll dig into why they matter and how they actually work.
+
+## Substitution Ciphers
+
+### What It Is
+
+A substitution cipher replaces each letter in your message with a different letter according to a fixed rule. Caesar cipher is the simplest version: shift every letter by the same amount. If your key is 3, A becomes D, B becomes E, and so on until Z wraps back to C.
+
+### Why It Matters
+
+Substitution ciphers were state of the art cryptography for centuries. Julius Caesar actually used this method to protect military messages around 58 BC. Understanding why they fail teaches you that security through obscurity doesn't work when the underlying pattern is too simple.
+
+### How It Works
+
+The transformation is just modular arithmetic on alphabet positions:
+```
+Encryption: ciphertext_position = (plaintext_position + key) % 26
+Decryption: plaintext_position = (ciphertext_position - key) % 26
+```
+
+For example, encrypting "HELLO" with key=3:
+```
+H (position 7)  → (7+3) % 26 = 10 → K
+E (position 4)  → (4+3) % 26 = 7  → H
+L (position 11) → (11+3) % 26 = 14 → O
+L (position 11) → (11+3) % 26 = 14 → O
+O (position 14) → (14+3) % 26 = 17 → R
+
+Result: KHOOR
+```
+
+### Common Attacks
+
+1. **Brute Force** - Try all 26 possible keys. With modern computers this takes milliseconds. The key space is too small.
+2. **Frequency Analysis** - English text has known letter frequencies. E appears 12.7% of the time, T about 9%, Z only 0.07%. These patterns survive Caesar encryption.
+3. **Known Plaintext** - If you know even part of the message, you can calculate the key immediately. One plaintext/ciphertext pair reveals everything.
+
+### Defense Strategies
+
+You can't defend Caesar cipher. It's fundamentally broken. But the lessons apply to stronger ciphers:
+- Larger key spaces make brute force impractical (this is why AES uses 128+ bit keys)
+- Randomization breaks frequency patterns (modern ciphers use different transformations for each block)
+- Authenticated encryption prevents known plaintext attacks from being useful
+
+## Frequency Analysis
+
+### What It Is
+
+A statistical attack that exploits the non-uniform distribution of letters in natural language. In English, E is the most common letter. In Caesar-encrypted English, some other letter will be most common, but it's still E underneath. By comparing the frequency distribution of the ciphertext to known English frequencies, you can score how likely a given shift is correct.
+
+### Why It Matters
+
+Al-Kindi described this technique in the 9th century, over a thousand years ago. It broke all simple substitution ciphers and stayed relevant until polyalphabetic ciphers like Vigenère were developed. Modern cryptanalysis still uses statistical attacks, just against more complex patterns.
+
+### How It Works
+
+The chi-squared test measures how far an observed distribution differs from an expected one:
+```
+χ² = Σ ((observed - expected)² / expected)
+```
+
+Lower scores mean better matches. In `analyzer.py:27-42`, the code calculates this:
+```python
+def calculate_chi_squared(self, text: str) -> float:
+    text_upper = text.upper()
+    letter_counts = Counter(char for char in text_upper if char.isalpha())
+    
+    total_letters = sum(letter_counts.values())
+    chi_squared = 0.0
+    
+    for letter, expected_freq in self.reference_frequencies.items():
+        observed_count = letter_counts.get(letter, 0)
+        expected_count = (expected_freq / 100) * total_letters
+        
+        if expected_count > 0:
+            chi_squared += ((observed_count - expected_count)**2) / expected_count
+    
+    return chi_squared
+```
+
+### Common Pitfalls
+
+**Mistake 1: Not handling case properly**
+```python
+# Bad - misses lowercase letters
+def count_letters(text):
+    return Counter(c for c in text if c.isupper())
+
+# Good - normalize to uppercase first
+def count_letters(text):
+    return Counter(c for c in text.upper() if c.isalpha())
+```
+
+Frequency analysis needs all letters. The code in `analyzer.py:29` converts to uppercase before counting.
+
+**Mistake 2: Including non-letters in frequency counts**
+
+Spaces, punctuation, and numbers will skew your statistics. Only count actual letters. The code uses `if char.isalpha()` to filter properly.
+
+**Mistake 3: Short text gives unreliable results**
+
+You need at least 50-100 letters for frequency analysis to work. With "HI" encrypted, there's not enough data. The chi-squared test returns `float("inf")` for empty strings in `analyzer.py:33`.
+
+## Brute Force Attacks
+
+### What It Is
+
+Simply trying every possible key until you find one that works. For Caesar cipher, that's only 26 attempts. Your computer can do millions of attempts per second, so this is instant.
+
+### Why It Matters
+
+Brute force sets the absolute maximum security of any cipher. Even with perfect implementation, if the key space is too small, the cipher is broken. This is why password complexity matters: each additional character multiplies the search space exponentially.
+
+### How It Works
+
+The `crack()` method in `cipher.py:53-60` implements this:
+```python
+@staticmethod
+def crack(ciphertext: str) -> list[tuple[int, str]]:
+    results = []
+    for shift in range(ALPHABET_SIZE):
+        cipher = CaesarCipher(key=shift)
+        decrypted = cipher.decrypt(ciphertext)
+        results.append((shift, decrypted))
+    return results
+```
+
+Try shift 0, shift 1, shift 2, all the way to shift 25. Return all results and let frequency analysis pick the best one.
+
+### Key Space Analysis
+```
+Caesar cipher:     26 possible keys (2^4.7 bits)
+4-digit PIN:       10,000 possibilities (2^13 bits)
+8-char password:   ~200 trillion (2^47 bits if using a-z, A-Z, 0-9)
+AES-128:           2^128 ≈ 10^38 possibilities
+```
+
+Anything under 2^40 is considered brute forceable today. Caesar is laughably weak.
+
+## How These Concepts Relate
+```
+Substitution Cipher (weak pattern)
+    ↓
+preserves letter frequencies
+    ↓
+Frequency Analysis (detects pattern)
+    ↓
+scores all possible keys
+    ↓
+Brute Force (tries all keys)
+    ↓
+Cipher is broken
+```
+
+The vulnerability chain: simple substitution creates a detectable pattern, frequency analysis exploits that pattern, brute force makes trying all keys practical.
+
+## Industry Standards and Frameworks
+
+### OWASP Top 10
+
+This project addresses:
+- **A02:2021 - Cryptographic Failures** - Demonstrates why weak cryptographic algorithms fail. Shows proper key validation (though the algorithm itself is pedagogical, not production-ready).
+
+### MITRE ATT&CK
+
+Relevant techniques:
+- **T1552.001** - Credentials from Password Stores - Weak encryption of stored credentials can be broken like this
+- **T1140** - Deobfuscate/Decode Files or Information - Attackers use frequency analysis on ROT13 and similar "obfuscation"
+
+### CWE
+
+Common weakness enumerations covered:
+- **CWE-327** - Use of a Broken or Risky Cryptographic Algorithm - Caesar cipher is the textbook example
+- **CWE-326** - Inadequate Encryption Strength - 4.7 bits of key strength is inadequate for anything
+
+## Real World Examples
+
+### Case Study 1: Zodiac Killer Cipher (1969)
+
+The Zodiac Killer sent encrypted messages to newspapers. His Z408 cipher was a homophonic substitution (multiple symbols per letter) but still fell to frequency analysis. Solved in 1969 by a schoolteacher and his wife using pencil and paper.
+
+What happened: The killer used 54 different symbols but they still mapped to 26 letters. Frequency analysis revealed the patterns. The Z340 cipher took 51 years to crack (finally solved in 2020) because it used polyalphabetic techniques.
+
+How this could have been prevented: Modern encryption with proper key length and randomization. Using ROT13 or Caesar on sensitive data is security theater.
+
+### Case Study 2: CVE-2015-2187 (ROT13 for passwords)
+
+In 2015, researchers found that some router firmware was storing admin passwords using ROT13 encoding. This is Caesar cipher with shift=13. Anyone with file access could instantly decrypt all passwords.
+
+What happened: Developers confused encoding with encryption. ROT13 is meant for spoiler text, not security.
+
+What defenses failed: No security review caught the use of a broken cipher for credential storage.
+
+Lesson: Never use Caesar cipher (or ROT13) for anything security-sensitive. Use bcrypt, scrypt, or argon2 for password hashing.
+
+## Testing Your Understanding
+
+Before moving to the architecture, make sure you can answer:
+
+1. If you encrypt "ATTACK AT DAWN" with key=7, will the letter A always encrypt to the same letter? Why does this matter for security?
+
+2. You intercept "WKLV LV D WHVW" and know it's encrypted with Caesar. Describe two different ways to decrypt it without brute forcing all 26 keys.
+
+3. Why does frequency analysis work on Caesar cipher but not on modern ciphers like AES?
+
+If these questions feel unclear, re-read the relevant sections. The implementation will make more sense once these fundamentals click.
+
+## Further Reading
+
+**Essential:**
+- "The Code Book" by Simon Singh - Chapter on historical ciphers explains Caesar and frequency analysis with great examples
+- Wikipedia: Chi-squared test - Mathematical foundation for the statistical scoring
+
+**Deep dives:**
+- "Applied Cryptography" by Bruce Schneier - Chapter 1 covers why classical ciphers fail
+- Al-Kindi's original manuscript on frequency analysis (translated versions available)
+
+**Historical context:**
+- David Kahn's "The Codebreakers" - History of cryptanalysis from ancient times to WWII