{"id":35205306,"url":"https://github.com/abbasiandev/codekhoda","last_synced_at":"2026-04-04T16:34:47.602Z","repository":{"id":329750139,"uuid":"1120688023","full_name":"abbasiandev/codekhoda","owner":"abbasiandev","description":"Next-gen Android security: On-device AI malware scanning, real-time threat protection, network traffic analysis, and cloud-powered threat intelligence.","archived":false,"fork":false,"pushed_at":"2025-12-21T22:47:47.000Z","size":5690,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-23T04:56:44.586Z","etag":null,"topics":["android-malware","android-security","clean-architecture","cybersecurity","fastapi","hybrid-cloud","intrusion-detection","jetpack-compose","kotlin","machine-learning","malware-detection","mobile-security","network-monitoring","packet-analysis","python","security-scanner","tensorflow-lite","threat-intelligence","vpn-service"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abbasiandev.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-21T18:31:05.000Z","updated_at":"2025-12-21T23:17:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abbasiandev/codekhoda","commit_stats":null,"previous_names":["abbasiandev/codekhoda"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/abbasiandev/codekhoda","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abbasiandev%2Fcodekhoda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abbasiandev%2Fcodekhoda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abbasiandev%2Fcodekhoda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abbasiandev%2Fcodekhoda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abbasiandev","download_url":"https://codeload.github.com/abbasiandev/codekhoda/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abbasiandev%2Fcodekhoda/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-malware","android-security","clean-architecture","cybersecurity","fastapi","hybrid-cloud","intrusion-detection","jetpack-compose","kotlin","machine-learning","malware-detection","mobile-security","network-monitoring","packet-analysis","python","security-scanner","tensorflow-lite","threat-intelligence","vpn-service"],"created_at":"2025-12-29T13:39:57.266Z","updated_at":"2026-04-04T16:34:47.594Z","avatar_url":"https://github.com/abbasiandev.png","language":"Kotlin","readme":"# 🛡️ Hybrid Cloud Sentinel\n\n\u003cdiv align=\"center\"\u003e\n\n![Version](https://img.shields.io/badge/version-1.0.0--alpha-blue.svg)\n![Platform](https://img.shields.io/badge/platform-Android-green.svg)\n![Backend](https://img.shields.io/badge/backend-Python%20FastAPI-orange.svg)\n![License](https://img.shields.io/badge/license-MIT-purple.svg)\n\n![Live API](https://img.shields.io/badge/API-Live-success)\n\n**\"The smartphone is too weak to fight alone. We brought the brain to the cloud.\"**\n\n*A next-generation mobile security solution that offloads complex threat analysis to a centralized \"Cloud Brain\"*\n\n[📖 Documentation](./docs/) • [🏗️ Architecture](./docs/ARCHITECTURE.md) • [🚀 Setup Guide](./docs/SETUP.md) • [🧪 Testing](./docs/TESTING.md)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Overview\n\n**Hybrid Cloud Sentinel (HCS)** is a mobile security MVP that combines a lightweight on-device Android agent with a powerful Python-based backend analysis engine. The solution provides comprehensive threat detection while maintaining minimal battery impact on the user's device.\n\n### Key Value Proposition\n\n| Feature | Description |\n|---------|-------------|\n| **⚡ Lightweight Endpoint** | Minimal battery drain through cloud-offloaded processing |\n| **🧠 Deep Analysis** | Cloud-based heuristics \u0026 ML for advanced threat detection |\n| **🔴 Real-time Protection** | Instantaneous feedback and blocking capabilities |\n| **🌐 Hybrid Ensemble** | On-device TFLite + Heuristic Matrix + Cloud Brain Intelligence |\n| **🛡️ Trust-First UX** | Educational onboarding and security score gamification |\n| **🔄 OTA Model Updates** | Automated ML model retraining and over-the-air updates |\n| **📊 Admin Dashboard** | Comprehensive analytics and threat management interface |\n| **💳 Flexible Plans** | Freemium and Featured subscription models with integrated billing |\n\n---\n\n## 🏗️ Architecture\n\nWe prioritize **Clean Architecture** with **MVVM** to ensure scalability and testability.\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                     HYBRID CLOUD SENTINEL                    │\n├──────────────────────────────────────────────────────────────┤\n│                                                              │\n│  ┌─────────────────┐                    ┌─────────────────┐  │\n│  │  Android Agent  │◄──── HTTPS ───────►│   Cloud Brain   │  │\n│  │                 │                    │                 │  │\n│  │  ┌───────────┐  │                    │  ┌───────────┐  │  │\n│  │  │:app       │  │                    │  │ FastAPI   │  │  │\n│  │  │:domain    │  │    Threat Data     │  │ Engine    │  │  │\n│  │  │:data      │  │◄──────────────────►│  │ ML Models │  │  │\n│  │  │:present   │  │                    │  │ Heuristics│  │  │\n│  │  │:agent     │  │                    │  └───────────┘  │  │\n│  │  └───────────┘  │                    │                 │  │\n│  └─────────────────┘                    └─────────────────┘  │\n│                                                              │\n└──────────────────────────────────────────────────────────────┘\n```\n\n### Android Client (Kotlin)\n\n| Module | Purpose |\n|--------|---------|\n| **`:app`** | Dependency Injection (Hilt), Application class, Navigation host |\n| **`:domain`** | Pure Kotlin entities, Use Cases, Repository interfaces (NO Android deps) |\n| **`:data`** | Repository implementations, Room Database, Retrofit API, Mappers |\n| **`:presentation`** | Jetpack Compose UI, ViewModels, State holders |\n| **`:agent`** | Foreground Services, Permission Analysis, Package Scanning |\n\n### Cloud Brain (Python)\n\n| Component | Purpose |\n|-----------|---------|\n| **FastAPI** | High-performance async API with automatic OpenAPI docs |\n| **Pydantic** | Type safety and shared contracts with Android |\n| **Heuristic Engine** | Rule-based detection of semantic threat patterns |\n| **ML Classifier** | Extensible interface for TensorFlow/PyTorch models |\n\n---\n\n## 🌐 Live Deployment\n\nThe Cloud Brain is deployed and accessible at:\n\n| Endpoint | URL |\n|----------|-----|\n| **Landing Page** | https://codekhoda-sentinel.liara.run/ |\n| **Admin Dashboard** | https://codekhoda-sentinel.liara.run/dashboard/ |\n| **Login Page** | https://codekhoda-sentinel.liara.run/dashboard/login |\n| **Health Check** | https://codekhoda-sentinel.liara.run/health |\n| **API Documentation** | https://codekhoda-sentinel.liara.run/docs |\n| **Scan Endpoint** | https://codekhoda-sentinel.liara.run/api/v1/scan/analyze |\n| **Threat Intel (Web)**| [Package Lists JSON](https://raw.githubusercontent.com/codekhoda/threat-intel/main/package_lists.json) |\n\n### Infrastructure\n\n| Component | Platform | Details |\n|-----------|----------|---------|\n| **Backend** | [Liara](https://liara.ir) | Docker container on free tier |\n| **Database** | SQLite | Lightweight embedded database |\n| **Intel Source** | GitHub | Dynamic threat signatures (OTA) |\n\n---\n\n## 🛡️ Hybrid Security Matrix\n\nWe utilize a multi-layered approach to threat detection:\n\n1.  **L1: Local Whitelist (System)**: Fast bypass for verified system/OS apps.\n2.  **L2: Local TFLite Model**: On-device AI for instant heuristic flagging.\n3.  **L3: Cloud Allow/Blocklist**: Real-time verification against global threat databases.\n4.  **L4: External Intelligence**: Dynamic fetching of signatures from GitHub and VirusTotal.\n5.  **L5: Contextual Analysis**: Correlating app categories with requested permissions.\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Android Development**: Android Studio Arctic Fox+, JDK 17\n- **Backend Development**: Python 3.10+, pip\n\n### Option A: Use Live Backend (Recommended)\n\nThe Android app is pre-configured to use the live Liara backend at `https://codekhoda-sentinel.liara.run`. Simply:\n\n1. Clone the repository\n2. Open `android/` in Android Studio\n3. Build \u0026 Run on your device\n\n### Option B: Local Development\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/your-org/hybrid-cloud-sentinel.git\ncd hybrid-cloud-sentinel\n```\n\n#### 2. Start the Backend (Cloud Brain)\n\n```bash\ncd backend\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n*Local Server runs at `http://127.0.0.1:8000`*  \n*Production API available at `https://codekhoda-sentinel.liara.run`*  \n*API Documentation: [Local](http://127.0.0.1:8000/docs) | [Production](https://codekhoda-sentinel.liara.run/docs)*\n\n#### 3. Configure Android for Local Backend\n\n1. Open the `android/` folder in **Android Studio**\n2. Sync Gradle dependencies\n3. Configure the Cloud Brain URL in your `local.properties`:\n   ```properties\n   # android/local.properties\n   # For local development (Emulator):\n   cloud.brain.url=http://10.0.2.2:8000\n   \n   # For production (Liara):\n   # cloud.brain.url=https://codekhoda-sentinel.liara.run\n   ```\n\n---\n\n## ☁️ Deployment Guide\n\n### Deploying to Liara\n\n1. **Install Liara CLI**:\n   ```bash\n   npm install -g @liara/cli\n   ```\n\n2. **Deploy Backend**:\n   ```bash\n   cd backend\n   liara deploy --app codekhoda-sentinel --platform docker --port 8000\n   ```\n\n   The deployment uses the Docker platform and will automatically build the image from the Dockerfile.\n\n3. **Configure Environment Variables** (Optional):\n   ```bash\n   liara env set --app codekhoda-sentinel JWT_SECRET=your-secure-secret-key-here\n   liara env set --app codekhoda-sentinel DEBUG=false\n   ```\n\n4. **Using GitHub Actions for CI/CD**:\n   - Add `LIARA_API_TOKEN` to your GitHub repository secrets\n   - Generate the token from Liara Console -\u003e Account -\u003e API Tokens\n   - The workflow will automatically deploy on push to `main` branch\n\n### Database Information\n\nThe backend uses **SQLite** as an embedded database, which:\n- Requires no external database service\n- Stores data in a single file (`sentinel_brain.db`)\n- Is perfect for MVP and small-scale deployments\n- Automatically initializes on first startup\n\nFor production with high traffic, consider migrating to PostgreSQL by:\n1. Adding `psycopg2-binary` to `requirements.txt`\n2. Setting `DATABASE_URL` environment variable to PostgreSQL connection string\n3. The code will automatically detect and use PostgreSQL\n\n### Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `DATABASE_URL` | Database connection string | `sqlite:///./sentinel_brain.db` (default) |\n| `JWT_SECRET` | Secret key for JWT tokens | `your-secret-key-change-in-production` |\n| `DEBUG` | Enable debug mode | `false` |\n| `SKIP_INIT_DB` | Skip database seeding on startup | `0` |\n\n---\n\n## 📁 Project Structure\n\n```\nhybrid-cloud-sentinel/\n├── 📂 android/                    # Android Application\n│   ├── 📂 app/                    # Main application module\n│   ├── 📂 domain/                 # Business logic (Pure Kotlin)\n│   │   ├── model/                 # Entities (AppPackage, RiskAssessment)\n│   │   ├── repository/            # Repository interfaces\n│   │   └── usecase/               # Use cases (ScanAppUseCase)\n│   ├── 📂 data/                   # Data layer\n│   │   ├── local/                 # Room database, DAOs\n│   │   ├── remote/                # Retrofit API, DTOs\n│   │   ├── ml/                    # TFLite model, FeatureExtractor\n│   │   └── repository/            # Repository implementations\n│   ├── 📂 presentation/           # UI Layer (Jetpack Compose)\n│   │   ├── theme/                 # Cyberpunk design system\n│   │   ├── components/            # Reusable UI components\n│   │   ├── scan/                  # Scanning screens\n│   │   └── about/                 # About screen\n│   └── 📂 agent/                  # System services\n│       ├── service/               # Foreground service (SentinelService)\n│       └── scanner/               # Package analyzer\n├── 📂 backend/                    # Python Backend (Cloud Brain)\n│   ├── 📂 app/\n│   │   ├── api/v1/endpoints/      # REST endpoints (scan, auth, dashboard)\n│   │   ├── core/                  # Config, database, security\n│   │   ├── engine/                # Heuristics \u0026 ML\n│   │   ├── models/                # SQLAlchemy models (User, ScanLog)\n│   │   ├── schemas/               # Pydantic schemas\n│   │   ├── services/              # Business logic (auth)\n│   │   ├── static/                # CSS, JavaScript\n│   │   └── templates/             # Jinja2 HTML templates (dashboard)\n│   └── 📂 tests/                  # pytest test suite\n├── 📂 docs/                       # Documentation\n├── 📂 references/                 # Reference ML models \u0026 datasets\n└── 📂 samples/                    # Test APK samples\n```\n\n---\n\n## 🧪 Testing\n\n### Android Tests\n\n```bash\n# Unit Tests (Domain logic, ViewModels)\ncd android\n./gradlew testDebugUnitTest\n\n# Instrumented Tests (Room DB, UI flows)\n./gradlew connectedDebugAndroidTest\n```\n\n### Backend Tests\n\n```bash\ncd backend\npytest --cov=app tests/\n```\n\n### Manual Verification\n\n1. **Threat Detection Test**: Install a test app with suspicious permissions\n2. **Connectivity Test**: Verify offline mode shows cached results\n3. **UI Fluidity**: Test radar animations on real device\n\n---\n\n## 🏆 Features Checklist\n\n- [x] **Core Scanning Loop** - Real-time app analysis\n- [x] **Cloud Integration** - Offloaded threat analysis\n- [x] **Offline Support** - Local caching with Room\n- [x] **ML Classification** - Ensemble TFLite model integration\n- [x] **Trust-First Onboarding** - Educational permission dashboard\n- [x] **OTA Model Updates** - Background model synchronization\n- [x] **Admin Dashboard** - Real-time analytics and management\n- [x] **Premium Features** - Subscription model and sandbox payments\n- [x] **Network Monitoring** - Packet analysis (implemented)\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Architecture Guide](./docs/ARCHITECTURE.md) | Detailed system architecture and design decisions |\n| [Setup Guide](./docs/SETUP.md) | Complete installation and configuration instructions |\n| [API Reference](./docs/API.md) | Cloud Brain REST API documentation |\n| [Development Guide](./docs/DEVELOPMENT.md) | Contributing guidelines and coding standards |\n| [Testing Guide](./docs/TESTING.md) | Testing strategy and test writing guide |\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Development Guide](./docs/DEVELOPMENT.md) for:\n\n- Coding standards and conventions\n- Branch naming and commit messages\n- Pull request process\n- Code review guidelines\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ by AI + Human Collaboration**\n\n*Protecting your digital life, one scan at a time.*\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabbasiandev%2Fcodekhoda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabbasiandev%2Fcodekhoda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabbasiandev%2Fcodekhoda/lists"}