Skip to content

Commit efa15aa

Browse files
author
Raoof128
committed
🚀 v2.0.36: Unify versions & docs for KotlinConf 2025-2026 submission
Changes: - Unified all module versions to 2.0.36 - Updated contest documentation (README, JUDGE_QUICKSTART, CONTEST_START) - Fixed percentage symbols in docs - Added demo video documentation - Reorganized webMain → jsMain/wasmJsMain source sets - Updated localized strings Verified: ✅ All judge scripts pass (verify_all.sh) ✅ All builds successful (Android, Desktop, Web JS, Web Wasm, iOS) ✅ Detekt passes with zero issues ✅ 87% F1 Score accuracy maintained
1 parent 88ccaf8 commit efa15aa

33 files changed

Lines changed: 285 additions & 84 deletions

File tree

‎CONTEST_START.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,9 @@
1111
| **Official Contest Opens** | September 15, 2025 | KotlinConf 2025-2026 Student Competition |
1212
| **Repository Created** | December 5, 2025 | [GitHub API](https://api.github.com/repos/Raoof128/Raoof128.github.io) |
1313
| **First Commit** | December 5, 2025 | `git log --oneline --reverse \| head -1` |
14-
| **Submission Ready** | December 31, 2025 | All platforms verified, v1.20.33 |
15-
| **Full Platform Parity** | December 31, 2025 | iOS matches Android/Desktop/Web |
14+
| **Submission Ready** | January 4, 2026 | All platforms verified, v2.0.36 |
15+
| **Full Platform Parity** | January 4, 2026 | iOS matches Android/Desktop/Web |
16+
| **Competition Deadline** | January 12, 2026 | 23:59:00 CET |
1617
| **Competition Period** | Within Contest Window | All development after Sep 15, 2025 ✅ |
1718

1819
---
@@ -42,7 +43,7 @@ No prior open-source project combines offline detection, explainability, and tru
4243
| Tag | Purpose | Commit |
4344
|-----|---------|--------|
4445
| `v0.1-contest-start` | First commit of contest period | [See GitHub releases](https://github.com/Raoof128/Raoof128.github.io/releases) |
45-
| `v1.20.33-submission` | Final submission version | [See GitHub releases](https://github.com/Raoof128/Raoof128.github.io/releases) |
46+
| `v2.0.36-submission` | Final submission version | [See GitHub releases](https://github.com/Raoof128/Raoof128.github.io/releases) |
4647

4748
---
4849

@@ -52,8 +53,8 @@ No prior open-source project combines offline detection, explainability, and tru
5253
Repository: https://github.com/Raoof128/Raoof128.github.io
5354
Branch: main
5455
Repository Created: December 5, 2025 (well within contest period starting Sep 15, 2025)
55-
Total Development Time: 26 days (Dec 5-31, 2025)
56-
Current Version: 1.20.33 (as of December 31, 2025)
56+
Total Development Time: 30 days (Dec 5, 2025 - Jan 4, 2026)
57+
Current Version: 2.0.36 (as of January 4, 2026)
5758
```
5859

5960
To verify:

‎JUDGE_QUICKSTART.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
| Action | Link |
1010
|--------|------|
1111
| 🌐 **Try Live Demo** | [raoof128.github.io](https://raoof128.github.io) |
12-
| 🎬 **Watch Video Demo** | [docs/VIDEO_DEMO.md](docs/VIDEO_DEMO.md) |
12+
| 🎬 **Watch Video Demo** | [YouTube](https://youtu.be/n8bheouj4jM) |
1313
| 📱 **Download Android APK** | [MehrGuard-2.0.36-debug.apk](releases/MehrGuard-2.0.36-debug.apk) |
1414
| 📖 **Read Essay** | [ESSAY.md](ESSAY.md) |
1515
| 🔨 **One-Command Build Test** | `./scripts/judge-smoke.sh` |
@@ -73,7 +73,7 @@ cd mehrguard
7373
| **Web** | Settings → Security Settings → "Enable Red Team Scenarios" toggle | Toggle ON/OFF |
7474

7575
**What You'll See:**
76-
- 11 curated attack scenarios (homographs, IP obfuscation, TLD abuse, brand impersonation, URL shorteners)
76+
- 19 curated attack scenarios (homographs, IP obfuscation, TLD abuse, brand impersonation, URL shorteners, safe controls)
7777
- One-tap testing of detection accuracy (bypasses camera, feeds URL directly to engine)
7878
- Useful for demonstrating engine capabilities to judges without needing QR codes
7979

‎README.md‎

Lines changed: 112 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,16 @@
88
>
99
> **"Mehr"** (Persian: مهر) means *trust, covenant, light* — the foundation of secure scanning.
1010
11+
<p align="center">
12+
<a href="https://youtu.be/n8bheouj4jM">
13+
<img src="https://img.shields.io/badge/🎬_Demo_Video-Watch_Now-red?style=for-the-badge&logo=youtube" alt="Demo Video">
14+
</a>
15+
</p>
16+
17+
<p align="center">
18+
<b>📺 Watch the Demo:</b> <a href="https://youtu.be/n8bheouj4jM">https://youtu.be/n8bheouj4jM</a>
19+
</p>
20+
1121
<p align="center">
1222
<img src="https://img.shields.io/badge/Kotlin-2.3.0-7F52FF?logo=kotlin&logoColor=white" alt="Kotlin">
1323
<img src="https://img.shields.io/badge/KMP_Targets-5-orange" alt="5 Platforms">
@@ -19,6 +29,18 @@
1929

2030
---
2131

32+
## 🏆 KotlinConf 2025-2026 Contest Submission
33+
34+
| Item | Link |
35+
|------|------|
36+
| **📝 Essay (300 words)** | [ESSAY.md](ESSAY.md) |
37+
| **🎬 Demo Video** | [YouTube](https://youtu.be/n8bheouj4jM) |
38+
| **📋 Submission Checklist** | [SUBMISSION_CHECKLIST.md](SUBMISSION_CHECKLIST.md) |
39+
| **🔍 Judge Quickstart** | [JUDGE_QUICKSTART.md](JUDGE_QUICKSTART.md) |
40+
| **📅 Contest Timeline** | [CONTEST_START.md](CONTEST_START.md) |
41+
42+
---
43+
2244
## ⚡ 60-Second Judge Path
2345

2446
| Step | Action | Time |
@@ -246,25 +268,100 @@ All security-critical logic lives in `common/src/commonMain/kotlin/`. Platform m
246268

247269
---
248270

249-
## Red Team Mode (For Judges)
271+
## Red Team Mode & Judge Testing
272+
273+
Red Team Mode is a **hidden developer feature** that exposes curated attack scenarios for testing the detection engine. This allows judges and developers to instantly verify detection accuracy without needing to print QR codes.
274+
275+
### How It Works (Technical Architecture)
276+
277+
```
278+
┌─────────────────────────────────────────────────────────────────────┐
279+
│ RED TEAM MODE ARCHITECTURE │
280+
├─────────────────────────────────────────────────────────────────────┤
281+
│ │
282+
│ ┌───────────────────────────────────────────────────────────────┐ │
283+
│ │ SHARED MODULE (common/redteam/) │ │
284+
│ │ │ │
285+
│ │ RedTeamScenarios.kt │ │
286+
│ │ ├── 19 curated attack scenarios (object SCENARIOS) │ │
287+
│ │ ├── Scenario data class (id, category, url, expectedScore) │ │
288+
│ │ ├── Categories: Homograph, IP Obfuscation, TLD, Brand, etc. │ │
289+
│ │ └── Utility: groupedByCategory(), getById() │ │
290+
│ │ │ │
291+
│ └───────────────────────────────────────────────────────────────┘ │
292+
│ │ │
293+
│ ┌───────────────┼───────────────┐ │
294+
│ ▼ ▼ ▼ │
295+
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
296+
│ │ Android │ │ iOS │ │ Desktop │ │
297+
│ │ RedTeamPanel │ │ RedTeamPanel │ │ RedTeamChips │ │
298+
│ │ (Compose) │ │ (SwiftUI) │ │ (Compose) │ │
299+
│ └───────────────┘ └───────────────┘ └───────────────┘ │
300+
│ │
301+
│ ┌───────────────────────────────────────────────────────────────┐ │
302+
│ │ Web (JavaScript array mirrors Kotlin RedTeamScenarios) │ │
303+
│ └───────────────────────────────────────────────────────────────┘ │
304+
│ │
305+
└─────────────────────────────────────────────────────────────────────┘
306+
```
307+
308+
### Cross-Platform Parity
309+
310+
All 5 platforms share the **exact same scenarios** with identical IDs, URLs, and expected scores:
311+
312+
| Source File | Platform | Implementation |
313+
|-------------|----------|----------------|
314+
| `common/.../redteam/RedTeamScenarios.kt` | Android, Desktop | Direct Kotlin import |
315+
| `iosApp/.../MockTypes.swift` | iOS | Swift enum mirroring Kotlin |
316+
| `webApp/.../scanner.js` | Web (JS/Wasm) | JavaScript array mirror |
317+
318+
### How to Enable Red Team Mode
319+
320+
| Platform | Activation Method | UI Location |
321+
|----------|-------------------|-------------|
322+
| **Android** | Settings → Tap version number **7 times** → Developer Mode unlocks | Red Team panel appears at top of Scanner screen |
323+
| **iOS** | Settings → Tap version number **7 times** → Developer Mode unlocks | Red Team scenarios panel in Scanner view |
324+
| **Desktop** | Click "🕵️ Judge Mode" toggle in header bar | Horizontal scrollable chip bar in Scanner |
325+
| **Web** | Settings → Security Settings → Toggle "Enable Red Team Scenarios" | Chip grid appears above scanner |
250326

251-
A hidden developer mode exposes 11 curated attack scenarios for testing.
327+
### Attack Scenario Categories
252328

253-
**How to Enable:**
329+
| Category | Count | Example | Detection Target |
330+
|----------|-------|---------|------------------|
331+
| **Homograph Attack** | 3 | `https://аpple.com` (Cyrillic 'а') | Mixed Unicode scripts |
332+
| **IP Obfuscation** | 3 | `http://3232235777/malware` | Decimal/Hex/Octal IP |
333+
| **Suspicious TLD** | 3 | `https://paypa1-secure.tk` | Free/abused TLDs |
334+
| **Nested Redirect** | 2 | `https://legit.com?url=https://phishing.tk` | URL-in-URL patterns |
335+
| **Brand Impersonation** | 3 | `https://paypa1.com` | Typosquatting |
336+
| **URL Shortener** | 2 | `https://bit.ly/xyz` | Destination hiding |
337+
| **Safe Control** | 2 | `https://google.com` | Baseline verification |
254338

255-
| Platform | Activation |
256-
|----------|------------|
257-
| Android | Settings → 7-tap version number |
258-
| iOS | Settings → 7-tap version number |
259-
| Desktop | Click "🕵️ Judge Mode" in header |
260-
| Web | Settings → Security → "Enable Red Team Scenarios" |
339+
### Code Flow (One-Click Testing)
261340

262-
**Scenarios Include:**
263-
- Cyrillic homographs (аpple.com, раypal.com)
264-
- IP obfuscation (decimal, hex encoding)
265-
- Suspicious TLDs (.tk, .ml with brand keywords)
266-
- Brand impersonation (paypa1.com, netflix.secure-verify.com)
267-
- URL shortener chains
341+
```kotlin
342+
// 1. User taps a Red Team scenario chip
343+
val scenario = RedTeamScenarios.getById("HG-001") // Cyrillic Apple
344+
345+
// 2. URL is fed directly to PhishingEngine (bypasses camera)
346+
val result = phishingEngine.analyze(scenario.maliciousUrl)
347+
348+
// 3. Result displayed with full breakdown
349+
// - Expected: score 70-100, verdict MALICIOUS
350+
// - Signals: MIXED_SCRIPTS, BRAND_IMPERSONATION, HOMOGRAPH_DETECTED
351+
```
352+
353+
### Verification Commands
354+
355+
```bash
356+
# Run all judge verification tests
357+
./judge/verify_all.sh
358+
359+
# Individual verifications:
360+
./judge/verify_offline.sh # Proves zero network calls
361+
./judge/verify_performance.sh # Proves <5ms latency
362+
./judge/verify_accuracy.sh # Proves 87% F1 score on red team corpus
363+
./judge/verify_parity.sh # Proves identical verdicts across platforms
364+
```
268365

269366
---
270367

‎SUBMISSION_CHECKLIST.md‎

Lines changed: 65 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,67 @@
11
# 📋 Submission Checklist (Judge-Facing)
22

3-
> **For Judges:** This checklist maps every competition requirement to its evidence.
3+
> **For Judges:** This checklist maps every KotlinConf 2025-2026 competition requirement to its evidence.
4+
>
5+
> **Submission Deadline:** January 12, 2026 (23:59:00 CET)
46
57
---
68

7-
## ✅ Rule Compliance (PASS/FAIL)
9+
## ✅ Mandatory Requirements (PASS/FAIL)
810

911
| Requirement | Status | Evidence |
1012
|-------------|--------|----------|
11-
| Project started after contest open | ✅ PASS | [CONTEST_START.md](CONTEST_START.md) |
12-
| All code is original work | ✅ PASS | Git history, no forks |
13-
| Open-source license | ✅ PASS | [LICENSE](LICENSE) (Apache 2.0) |
14-
| Public GitHub repository | ✅ PASS | [github.com/Raoof128/Raoof128.github.io](https://github.com/Raoof128/Raoof128.github.io) |
15-
| README.md present | ✅ PASS | [README.md](README.md) |
16-
| Essay included (300+ words) | ✅ PASS | [ESSAY.md](ESSAY.md) (322 words) |
13+
| Uses Kotlin Multiplatform | ✅ PASS | `common/` module, 5 targets |
14+
| Runs on at least 2 platforms | ✅ PASS | 5 platforms: Android, iOS, Desktop, Web (JS), Web (Wasm) |
15+
| Created specifically for this contest | ✅ PASS | [CONTEST_START.md](CONTEST_START.md) - Started Dec 5, 2025 |
16+
| NOT a template or "Hello World" | ✅ PASS | 26,000+ LOC, substantial security app |
17+
| NOT a library | ✅ PASS | Standalone application with full UI |
18+
| GitHub repository | ✅ PASS | [github.com/Raoof128/Raoof128.github.io](https://github.com/Raoof128/Raoof128.github.io) |
19+
| Open-source license (Apache 2.0/MIT/BSD) | ✅ PASS | [LICENSE](LICENSE) (Apache 2.0) |
20+
| README with installation instructions | ✅ PASS | [README.md](README.md) - All 5 platforms |
21+
| README with feature descriptions | ✅ PASS | [README.md](README.md) - Detection engine, ML, Red Team |
22+
| Short screencast (3-5 min) | ✅ PASS | [Demo Video](https://youtu.be/n8bheouj4jM) |
23+
| All content in English | ✅ PASS | Docs, code, comments all English |
24+
| 300-word Essay | ✅ PASS | [ESSAY.md](ESSAY.md) (327 words) |
25+
| Original work (100% owned) | ✅ PASS | Git history shows original development |
1726

1827
---
1928

20-
## 🎯 Creativity & Novelty (40 points)
29+
## 🎯 Judging Criteria Breakdown
30+
31+
### Creativity & Novelty (40%)
2132

2233
| Criterion | Evidence | Score Target |
2334
|-----------|----------|--------------|
24-
| **Unique Problem** | QR phishing detection—587 attack increase since 2023 | +10 |
35+
| **Unique Problem** | QR phishing detection—587% attack increase since 2023 | +10 |
2536
| **Offline-First Architecture** | Zero network calls, [verify_offline.sh](judge/verify_offline.sh) | +10 |
26-
| **Ensemble ML** | 3 models combined ([EnsembleModel.kt](common/src/commonMain/kotlin/com/mehrguard/ml/EnsembleModel.kt)) | +8 |
27-
| **Dynamic Brand Discovery** | Detects unknown brands via patterns ([DynamicBrandDiscovery.kt](common/src/commonMain/kotlin/com/mehrguard/engine/DynamicBrandDiscovery.kt)) | +5 |
28-
| **Adversarial Robustness** | Homographs, punycode, RTL override ([HomographDetector.kt](common/src/commonMain/kotlin/com/mehrguard/engine/HomographDetector.kt)) | +5 |
29-
| **Explainability** | Every verdict has human-readable reasons | +2 |
37+
| **Ensemble ML** | 3 models combined ([EnsembleModel.kt](common/src/commonMain/kotlin/com/raouf/mehrguard/ml/EnsembleModel.kt)) | +8 |
38+
| **Dynamic Brand Discovery** | Detects unknown brands via patterns | +5 |
39+
| **Adversarial Robustness** | Homographs, punycode, RTL override detection | +5 |
40+
| **Beat the Bot Gamification** | Security training game mode | +2 |
3041
| **TOTAL** | | **40/40** |
3142

32-
---
33-
34-
## 🧩 Kotlin Multiplatform Usage (40 points)
43+
### Kotlin Multiplatform Usage (40%)
3544

3645
| Criterion | Evidence | Score Target |
3746
|-----------|----------|--------------|
38-
| **5 Platform Targets** | Android, iOS, Desktop, Web (JS + Wasm) | +10 |
39-
| **~80% Shared Code** | [SHARED_CODE_REPORT.md](docs/SHARED_CODE_REPORT.md) | +10 |
40-
| **Strategic expect/actual** | [PlatformAbstractions.kt](common/src/commonMain/kotlin/com/mehrguard/platform/PlatformAbstractions.kt) | +8 |
41-
| **Compose Multiplatform** | Shared UI components on iOS ([ComposeInterop.swift](iosApp/MehrGuard/ComposeInterop.swift)) | +5 |
42-
| **Native Integration** | SwiftUI host, Compose UI, proper interop | +5 |
43-
| **Platform Parity Tests** | [verify_parity.sh](judge/verify_parity.sh) runs JVM+JS+Native | +2 |
47+
| **5 Platform Targets** | Android, iOS, Desktop, Web (JS), Web (Wasm) | +10 |
48+
| **~52% Shared Code** | [SHARED_CODE_REPORT.md](docs/SHARED_CODE_REPORT.md) - 13,500 LOC shared | +10 |
49+
| **Strategic expect/actual** | 7 platform abstractions (Clipboard, Haptics, Logger, etc.) | +8 |
50+
| **Shared Business Logic** | 100% of detection engine in commonMain | +5 |
51+
| **Native Integration** | SwiftUI + Kotlin bridge, Compose MP | +5 |
52+
| **Platform Parity Tests** | [verify_parity.sh](judge/verify_parity.sh) | +2 |
4453
| **TOTAL** | | **40/40** |
4554

46-
---
47-
48-
## 📐 Kotlin Coding Conventions (20 points)
55+
### Kotlin Coding Conventions (20%)
4956

5057
| Criterion | Evidence | Score Target |
5158
|-----------|----------|--------------|
52-
| **Idiomatic Kotlin** | sealed classes, data classes, coroutines | +5 |
53-
| **Detekt Zero-Tolerance** | CI fails on any violation | +5 |
59+
| **Idiomatic Kotlin** | sealed classes, data classes, coroutines, Flow | +5 |
60+
| **Detekt Static Analysis** | [detekt.yml](detekt.yml), CI enforced | +5 |
5461
| **KDoc Documentation** | All public APIs documented | +3 |
5562
| **Test Coverage** | 89% coverage, 1,248+ tests | +3 |
56-
| **Property-Based Tests** | [PropertyBasedTest.kt](common/src/commonTest/kotlin/com/mehrguard/core/PropertyBasedTest.kt) | +2 |
57-
| **Architecture Tests** | [KonsistTest.kt](common/src/desktopTest/kotlin/com/mehrguard/architecture/KonsistTest.kt) | +2 |
63+
| **Property-Based Tests** | Randomized input testing | +2 |
64+
| **Architecture Tests** | Konsist rules enforced | +2 |
5865
| **TOTAL** | | **20/20** |
5966

6067
---
@@ -110,7 +117,7 @@ cd mehrguard
110117
| Document | Purpose |
111118
|----------|---------|
112119
| [README.md](README.md) | Quick start, architecture overview |
113-
| [ESSAY.md](ESSAY.md) | Competition essay (322 words) |
120+
| [ESSAY.md](ESSAY.md) | Competition essay (327 words) |
114121
| [CONTEST_START.md](CONTEST_START.md) | Contest timeline, original work proof |
115122
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Technical architecture deep-dive |
116123
| [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | Who attacks, what we detect |
@@ -119,7 +126,34 @@ cd mehrguard
119126
| [docs/SHARED_CODE_REPORT.md](docs/SHARED_CODE_REPORT.md) | Module-by-module shared code % |
120127
| [SECURITY.md](SECURITY.md) | Security policy, disclosure |
121128
| [PRIVACY.md](PRIVACY.md) | What data we store/don't store |
129+
| [docs/VIDEO_DEMO.md](docs/VIDEO_DEMO.md) | Demo video and script |
130+
131+
---
132+
133+
## 🎬 Demo Video
134+
135+
**YouTube Link:** [https://youtu.be/n8bheouj4jM](https://youtu.be/n8bheouj4jM)
136+
137+
The screencast demonstrates:
138+
- Real-time QR scanning on all platforms
139+
- Phishing detection with explainable verdicts
140+
- Red Team developer mode with 19 attack scenarios
141+
- Beat the Bot gamification feature
142+
- Cross-platform UI consistency
143+
144+
---
145+
146+
## ⏰ Submission Timeline
147+
148+
| Date | Event |
149+
|------|-------|
150+
| September 15, 2025 | Contest opens |
151+
| December 5, 2025 | Repository created |
152+
| January 4, 2026 | Current version: v2.0.36 |
153+
| **January 12, 2026** | **Submission deadline (23:59 CET)** |
154+
| January 22, 2026 | Winners announced |
122155

123156
---
124157

125158
*This checklist is designed for judges to verify every claim in under 10 minutes.*
159+
*Version: 2.0.36 | Last Updated: January 4, 2026*

‎androidApp/build.gradle.kts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ android {
1616
applicationId = "com.raouf.mehrguard.android"
1717
minSdk = 26
1818
targetSdk = 35 // Android 16
19-
versionCode = 33
20-
versionName = "1.20.33"
19+
versionCode = 36
20+
versionName = "2.0.36"
2121

2222
testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
2323
}

‎androidApp/src/main/res/values-ar/strings.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,7 @@
235235
<string name="cd_delete_item">حذف هذا المسح من السجل</string>
236236
<string name="cd_clear_history">مسح كل سجل المسح</string>
237237
<string name="cd_search_history">البحث في سجل المسح</string>
238+
<string name="filter_all">الكل</string>
238239
<string name="cd_filter_safe">إظهار عمليات المسح الآمنة فقط</string>
239240
<string name="cd_filter_suspicious">إظهار عمليات المسح المشبوهة فقط</string>
240241
<string name="cd_filter_malicious">إظهار عمليات المسح الخبيثة فقط</string>

‎androidApp/src/main/res/values-de/strings.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,7 @@
235235
<string name="cd_delete_item">Diesen Scan aus dem Verlauf löschen</string>
236236
<string name="cd_clear_history">Gesamten Scan-Verlauf löschen</string>
237237
<string name="cd_search_history">Scan-Verlauf durchsuchen</string>
238+
<string name="filter_all">Alle</string>
238239
<string name="cd_filter_safe">Nur sichere Scans anzeigen</string>
239240
<string name="cd_filter_suspicious">Nur verdächtige Scans anzeigen</string>
240241
<string name="cd_filter_malicious">Nur bösartige Scans anzeigen</string>

0 commit comments

Comments
 (0)