Skip to content
/ codekhoda Public

Next-gen Android security: On-device AI malware scanning, real-time threat protection, network traffic analysis, and cloud-powered threat intelligence.

License

GPL-2.0 license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

abbasiandev/codekhoda

BranchesTags

Repository files navigation

🛡️ Hybrid Cloud Sentinel

Version Platform Backend License

Live API

"The smartphone is too weak to fight alone. We brought the brain to the cloud."

A next-generation mobile security solution that offloads complex threat analysis to a centralized "Cloud Brain"

📖 Documentation • 🏗️ Architecture • 🚀 Setup Guide • 🧪 Testing

🎯 Overview

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.

Key Value Proposition

Feature Description
⚡ Lightweight Endpoint Minimal battery drain through cloud-offloaded processing
🧠 Deep Analysis Cloud-based heuristics & ML for advanced threat detection
🔴 Real-time Protection Instantaneous feedback and blocking capabilities
🌐 Hybrid Ensemble On-device TFLite + Heuristic Matrix + Cloud Brain Intelligence
🛡️ Trust-First UX Educational onboarding and security score gamification
🔄 OTA Model Updates Automated ML model retraining and over-the-air updates
📊 Admin Dashboard Comprehensive analytics and threat management interface
💳 Flexible Plans Freemium and Featured subscription models with integrated billing

🏗️ Architecture

We prioritize Clean Architecture with MVVM to ensure scalability and testability.

┌──────────────────────────────────────────────────────────────┐
│                     HYBRID CLOUD SENTINEL                    │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────┐                    ┌─────────────────┐  │
│  │  Android Agent  │◄──── HTTPS ───────►│   Cloud Brain   │  │
│  │                 │                    │                 │  │
│  │  ┌───────────┐  │                    │  ┌───────────┐  │  │
│  │  │:app       │  │                    │  │ FastAPI   │  │  │
│  │  │:domain    │  │    Threat Data     │  │ Engine    │  │  │
│  │  │:data      │  │◄──────────────────►│  │ ML Models │  │  │
│  │  │:present   │  │                    │  │ Heuristics│  │  │
│  │  │:agent     │  │                    │  └───────────┘  │  │
│  │  └───────────┘  │                    │                 │  │
│  └─────────────────┘                    └─────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Android Client (Kotlin)

Module Purpose
:app Dependency Injection (Hilt), Application class, Navigation host
:domain Pure Kotlin entities, Use Cases, Repository interfaces (NO Android deps)
:data Repository implementations, Room Database, Retrofit API, Mappers
:presentation Jetpack Compose UI, ViewModels, State holders
:agent Foreground Services, Permission Analysis, Package Scanning

Cloud Brain (Python)

Component Purpose
FastAPI High-performance async API with automatic OpenAPI docs
Pydantic Type safety and shared contracts with Android
Heuristic Engine Rule-based detection of semantic threat patterns
ML Classifier Extensible interface for TensorFlow/PyTorch models

🌐 Live Deployment

The Cloud Brain is deployed and accessible at:

Endpoint URL
Landing Page https://codekhoda-sentinel.liara.run/
Admin Dashboard https://codekhoda-sentinel.liara.run/dashboard/
Login Page https://codekhoda-sentinel.liara.run/dashboard/login
Health Check https://codekhoda-sentinel.liara.run/health
API Documentation https://codekhoda-sentinel.liara.run/docs
Scan Endpoint https://codekhoda-sentinel.liara.run/api/v1/scan/analyze
Threat Intel (Web) Package Lists JSON

Infrastructure

Component Platform Details
Backend Liara Docker container on free tier
Database SQLite Lightweight embedded database
Intel Source GitHub Dynamic threat signatures (OTA)

🛡️ Hybrid Security Matrix

We utilize a multi-layered approach to threat detection:

  1. L1: Local Whitelist (System): Fast bypass for verified system/OS apps.
  2. L2: Local TFLite Model: On-device AI for instant heuristic flagging.
  3. L3: Cloud Allow/Blocklist: Real-time verification against global threat databases.
  4. L4: External Intelligence: Dynamic fetching of signatures from GitHub and VirusTotal.
  5. L5: Contextual Analysis: Correlating app categories with requested permissions.

🚀 Quick Start

Prerequisites

  • Android Development: Android Studio Arctic Fox+, JDK 17
  • Backend Development: Python 3.10+, pip

Option A: Use Live Backend (Recommended)

The Android app is pre-configured to use the live Liara backend at https://codekhoda-sentinel.liara.run. Simply:

  1. Clone the repository
  2. Open android/ in Android Studio
  3. Build & Run on your device

Option B: Local Development

1. Clone the Repository

git clone https://github.com/your-org/hybrid-cloud-sentinel.git
cd hybrid-cloud-sentinel

2. Start the Backend (Cloud Brain)

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Local Server runs at http://127.0.0.1:8000
Production API available at https://codekhoda-sentinel.liara.run
API Documentation: Local | Production

3. Configure Android for Local Backend

  1. Open the android/ folder in Android Studio
  2. Sync Gradle dependencies
  3. Configure the Cloud Brain URL in your local.properties: 
    # android/local.properties
# For local development (Emulator):
cloud.brain.url=http://10.0.2.2:8000

# For production (Liara):
# cloud.brain.url=https://codekhoda-sentinel.liara.run

☁️ Deployment Guide

Deploying to Liara

  1. Install Liara CLI:

    npm install -g @liara/cli

  2. Deploy Backend:

    cd backend
liara deploy --app codekhoda-sentinel --platform docker --port 8000

    The deployment uses the Docker platform and will automatically build the image from the Dockerfile.

  3. Configure Environment Variables (Optional):

    liara env set --app codekhoda-sentinel JWT_SECRET=your-secure-secret-key-here
liara env set --app codekhoda-sentinel DEBUG=false

  4. Using GitHub Actions for CI/CD:

    • Add LIARA_API_TOKEN to your GitHub repository secrets
    • Generate the token from Liara Console -> Account -> API Tokens
    • The workflow will automatically deploy on push to main branch

Database Information

The backend uses SQLite as an embedded database, which:

  • Requires no external database service
  • Stores data in a single file (sentinel_brain.db)
  • Is perfect for MVP and small-scale deployments
  • Automatically initializes on first startup

For production with high traffic, consider migrating to PostgreSQL by:

  1. Adding psycopg2-binary to requirements.txt
  2. Setting DATABASE_URL environment variable to PostgreSQL connection string
  3. The code will automatically detect and use PostgreSQL

Environment Variables

Variable Description Example
DATABASE_URL Database connection string sqlite:///./sentinel_brain.db (default)
JWT_SECRET Secret key for JWT tokens your-secret-key-change-in-production
DEBUG Enable debug mode false
SKIP_INIT_DB Skip database seeding on startup 0

📁 Project Structure

hybrid-cloud-sentinel/
├── 📂 android/                    # Android Application
│   ├── 📂 app/                    # Main application module
│   ├── 📂 domain/                 # Business logic (Pure Kotlin)
│   │   ├── model/                 # Entities (AppPackage, RiskAssessment)
│   │   ├── repository/            # Repository interfaces
│   │   └── usecase/               # Use cases (ScanAppUseCase)
│   ├── 📂 data/                   # Data layer
│   │   ├── local/                 # Room database, DAOs
│   │   ├── remote/                # Retrofit API, DTOs
│   │   ├── ml/                    # TFLite model, FeatureExtractor
│   │   └── repository/            # Repository implementations
│   ├── 📂 presentation/           # UI Layer (Jetpack Compose)
│   │   ├── theme/                 # Cyberpunk design system
│   │   ├── components/            # Reusable UI components
│   │   ├── scan/                  # Scanning screens
│   │   └── about/                 # About screen
│   └── 📂 agent/                  # System services
│       ├── service/               # Foreground service (SentinelService)
│       └── scanner/               # Package analyzer
├── 📂 backend/                    # Python Backend (Cloud Brain)
│   ├── 📂 app/
│   │   ├── api/v1/endpoints/      # REST endpoints (scan, auth, dashboard)
│   │   ├── core/                  # Config, database, security
│   │   ├── engine/                # Heuristics & ML
│   │   ├── models/                # SQLAlchemy models (User, ScanLog)
│   │   ├── schemas/               # Pydantic schemas
│   │   ├── services/              # Business logic (auth)
│   │   ├── static/                # CSS, JavaScript
│   │   └── templates/             # Jinja2 HTML templates (dashboard)
│   └── 📂 tests/                  # pytest test suite
├── 📂 docs/                       # Documentation
├── 📂 references/                 # Reference ML models & datasets
└── 📂 samples/                    # Test APK samples

🧪 Testing

Android Tests

# Unit Tests (Domain logic, ViewModels)
cd android
./gradlew testDebugUnitTest

# Instrumented Tests (Room DB, UI flows)
./gradlew connectedDebugAndroidTest

Backend Tests

cd backend
pytest --cov=app tests/

Manual Verification

  1. Threat Detection Test: Install a test app with suspicious permissions
  2. Connectivity Test: Verify offline mode shows cached results
  3. UI Fluidity: Test radar animations on real device

🏆 Features Checklist

  • Core Scanning Loop - Real-time app analysis
  • Cloud Integration - Offloaded threat analysis
  • Offline Support - Local caching with Room
  • ML Classification - Ensemble TFLite model integration
  • Trust-First Onboarding - Educational permission dashboard
  • OTA Model Updates - Background model synchronization
  • Admin Dashboard - Real-time analytics and management
  • Premium Features - Subscription model and sandbox payments
  • Network Monitoring - Packet analysis (implemented)

📚 Documentation

Document Description
Architecture Guide Detailed system architecture and design decisions
Setup Guide Complete installation and configuration instructions
API Reference Cloud Brain REST API documentation
Development Guide Contributing guidelines and coding standards
Testing Guide Testing strategy and test writing guide

🤝 Contributing

We welcome contributions! Please see our Development Guide for:

  • Coding standards and conventions
  • Branch naming and commit messages
  • Pull request process
  • Code review guidelines

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by AI + Human Collaboration

Protecting your digital life, one scan at a time.

About

Next-gen Android security: On-device AI malware scanning, real-time threat protection, network traffic analysis, and cloud-powered threat intelligence.

Topics

kotlin python machine-learning clean-architecture cybersecurity intrusion-detection network-monitoring android-security mobile-security security-scanner hybrid-cloud vpn-service threat-intelligence android-malware malware-detection packet-analysis tensorflow-lite fastapi jetpack-compose

Resources

Readme

License

GPL-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

Hybrid Cloud Sentinel Latest
Dec 21, 2025

Packages

No packages published

Contributors 2

  •  
  •  

Languages