A comprehensive cybersecurity platform for analyzing Android APK files, detecting threats, vulnerabilities, and malicious behavior using advanced static analysis and AI-powered intelligence.
- 🎯 Overview
- ✨ Features
- 🏗️ Architecture
- 🛠️ Technology Stack
- 📋 Prerequisites
- 🛠️ Installation
- 📖 User Guide
- 🤖 AI Analysis
- 🔒 Security Analysis
- 🔌 API Documentation
- 📁 Directory Structure
- 📄 Pages
- 🌍 Environment Variables
- 🚀 Deployment
- 🐛 Troubleshooting
- 📄 License
FalconScan is an advanced Android APK security analysis platform for static analysis, vulnerability detection, AI-assisted triage, and professional reporting.
| ⚡ Fast Analysis | 🔒 Security Checks | 📊 Professional Reports | 🎨 Modern UI |
|---|---|---|---|
| Completes analysis in seconds | Covers secrets, crypto, permissions, network risks, and more | PDF and JSON reporting with remediation guidance | Cybersecurity-themed interface with real-time feedback |
| 🤖 AI Assistance | 📱 APK Focused | 🚀 Live Updates | 🛡️ Production-Ready |
|---|---|---|---|
| Optional Gemini-powered analysis and summaries | Built for Android package workflows | Progress tracking and notifications | JWT auth, role-aware dashboard, and deployment guidance |
- 🔍 Real-time APK Analysis - Instant threat detection and vulnerability scanning
- 🛡️ Advanced Security Checks - Detect hardcoded secrets, weak crypto, dangerous permissions
- 🤖 AI Security Intelligence - On-demand AI analysis with attack chains, severity re-scoring, and code-level fix recommendations
- 📊 Dynamic Risk Scoring - Industry-standard CVSS-inspired weighted scoring system
- 📈 Comprehensive Reporting - Detailed vulnerability reports with remediation guidance
- 🔐 Permission Analysis - Identify dangerous permissions and risky behaviors
- 📉 Threat Visualization - Interactive charts and graphs for vulnerability breakdown
- 📜 PDF Export - Professional security reports for documentation
- 🔔 Real-time Notifications - Stay informed about scan completion and threats
- 👤 User Management - Secure JWT authentication and profile management
- 🎨 Modern UI - Professional dark cybersecurity theme with glassmorphism effects
- Framework: Django 4.2 + Django REST Framework
- APK Analysis: Androguard 4.x for decompilation and static analysis
- AI Engine: google-genai 1.0+ for intelligent security reporting
- Authentication: JWT (djangorestframework-simplejwt)
- Database: SQLite (development) / PostgreSQL (production)
- Server: Daphne (ASGI)
- PDF Generation: ReportLab
- API: RESTful with comprehensive endpoints
- Framework: Next.js 16 with TypeScript 5
- UI Library: React 19
- Components: shadcn/ui + Radix UI
- Styling: Tailwind CSS with custom cybersecurity theme
- Charts: Recharts for data visualization
- HTTP Client: Axios
- Date Handling: date-fns
The application is split into a Django backend for analysis and persistence, and a Next.js frontend for the dashboard, reports, and uploads.
- Backend API and analysis engine live under
backend/ - Frontend dashboard and user flows live under
app/ - Shared UI, auth, and notification components live under
components/ - API access and helpers live under
lib/
- Python 3.8 or higher
- Node.js 18 or higher
- npm or pnpm
- Git
git clone https://github.com/yourusername/falconscan.git
cd falconscancd backend
# Create virtual environment
python -m venv venv
# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Run migrations
python manage.py migrate
# Create superuser (optional)
python manage.py createsuperuser
# Start development server
python manage.py runserverThe backend will run at http://localhost:8000
# In a new terminal, from project root
pnpm install
# or
npm install
# Copy environment file
cp .env.example .env.local
# Update .env.local with your settings:
# NEXT_PUBLIC_API_URL=http://localhost:8000/api
# Start development server
pnpm dev
# or
npm run devThe frontend will run at http://localhost:3000
- Navigate to
http://localhost:3000 - Register or login to your account
- Go to Upload page
- Drag & drop or browse for an APK file
- Enter app name (optional - will use filename if empty)
- Click Start Analysis
- Wait for analysis to complete (~1.5-2 seconds)
- View detailed security report
- Dashboard: Overview of all scans with statistics
- Reports: Detailed vulnerability findings for each scan
- History: Timeline of all previous scans
- Download PDF: Export professional security reports
- Upload: Submit APKs for static analysis and scoring
- Documentation: Read built-in API and usage help
- Profile: Manage your account settings and preferences
FalconScan can generate AI-assisted analysis for completed scans using the configured Gemini model.
- Attack-chain style summaries
- Severity re-scoring and prioritization
- Remediation recommendations
- Compliance-oriented observations
- Open a completed scan report.
- Select the AI tab.
- Click Generate AI Report.
- Review the generated findings and recommendations.
- AI analysis requires
AI_API_KEYin the backend environment. - Model selection and fallback behavior are configured in the backend.
- Hardcoded API keys and secrets (AWS, Google, Firebase, GitHub, Stripe, and more)
- Weak cryptographic implementations (DES, ECB, MD5, SHA-1)
- Insecure network configurations (HTTP, cleartext traffic)
- Dangerous permissions usage (CAMERA, LOCATION, SMS, CONTACTS, etc.)
- SQL injection vulnerabilities
- Path traversal issues
- Exported components without permission protection
- Debug certificate in production
- 15+ additional security checks
Weighted scoring system based on industry standards:
- Critical: 25 points each
- High: 15 points each
- Medium: 8 points each
- Low: 3 points each
Multipliers applied for:
- Dangerous permissions (5+): +20%
- Debuggable flag: +15%
- Cleartext traffic: +15%
- Hardcoded secrets: +15%
- Backup allowed: +10%
| Level | Score Range | Color | Action Required |
|---|---|---|---|
| Critical | ≥ 80 | 🔴 | Immediate attention required |
| High | ≥ 60 | 🟠 | Significant security concerns |
| Medium | ≥ 35 | 🟡 | Notable issues requiring review |
| Low | ≥ 15 | 🟢 | Minor issues or recommendations |
| Safe | < 15 | ✅ | No threats detected |
- Manifest and permission inspection
- Component exposure and exported surface review
- Certificate and signing checks
- Secret, token, and credential pattern detection
- Network and cleartext traffic review
- Weak crypto and insecure storage checks
POST /api/accounts/users/register/ # Create account
POST /api/token/ # Login → returns access + refresh JWT
POST /api/token/refresh/ # Refresh access token
GET /api/accounts/users/me/ # Current user profilePOST /api/scans/upload/ # Upload APK (multipart/form-data)
GET /api/scans/ # List all scans (paginated)
GET /api/scans/{id}/ # Full scan details + analysis results
GET /api/scans/{id}/report/ # Security report (JSON)
GET /api/scans/{id}/download_pdf/ # Download PDF report
POST /api/scans/{id}/rescan/ # Retry a failed scan
DELETE /api/scans/{id}/ # Delete scan + all associated data
GET /api/scans/statistics/ # Dashboard stats
POST /api/scans/ai_report/ # Generate AI security report
POST /api/scans/cleanup_failed/ # Bulk retry all failed scansAll scan endpoints require Authorization: Bearer <access_token>.
falconscan/
├── backend/
│ ├── falconscan_backend/
│ │ ├── settings.py # Django configuration
│ │ ├── urls.py
│ │ └── wsgi.py / asgi.py
│ ├── apps/
│ │ ├── accounts/ # User management (JWT auth)
│ │ │ ├── models.py
│ │ │ ├── views.py
│ │ │ └── serializers.py
│ │ └── scans/ # Core scan engine
│ │ ├── models.py # Scan, Vulnerability, Report models
│ │ ├── analyzer.py # Androguard APK wrapper
│ │ ├── static_analyzer.py # String & artifact extraction
│ │ ├── vulnerability_scanner.py # 15+ security checks
│ │ ├── ai_analyzer.py # AI security intelligence engine
│ │ ├── pdf_generator.py # ReportLab PDF builder
│ │ └── views.py # REST API endpoints
│ └── manage.py
├── app/ # Next.js app router
│ ├── dashboard/
│ │ ├── upload/ # APK upload interface
│ │ ├── reports/[id]/ # Detailed scan report viewer
│ │ ├── history/ # Scan history timeline
│ │ ├── settings/ # User settings
│ │ └── documentation/ # In-app documentation viewer
│ ├── login/
│ ├── register/
│ └── page.tsx # Landing page
├── components/ # Shared React components
├── lib/
│ └── api.ts # Centralised Axios API client
└── public/ # Static assets
/- Landing page with features and stats/login- User login with JWT authentication/register- New user registration
/dashboard- Overview with statistics and recent scans/dashboard/upload- Upload APK for scanning/dashboard/history- View all previous scans/dashboard/reports- Generate and download detailed reports/dashboard/documentation- Complete API and usage documentation/dashboard/settings- User settings and preferences/dashboard/profile- User profile management
DEBUG=True
DJANGO_SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1
CORS_ALLOWED_ORIGINS=http://localhost:3000
DATABASE_URL=sqlite:///db.sqlite3
AI_API_KEY=your-ai-api-key-hereNEXT_PUBLIC_API_URL=http://localhost:8000/api
NEXT_PUBLIC_APP_NAME=FalconScan- Set
DEBUG=Falsein Django settings - Generate a new
DJANGO_SECRET_KEY - Switch to PostgreSQL for production
- Set
ALLOWED_HOSTSto your production domain - Configure HTTPS / TLS termination
- Set
CORS_ALLOWED_ORIGINSto the production frontend URL - Set
AI_API_KEYfor AI analysis feature - Run
python manage.py collectstatic - Set up proper logging and monitoring
# Check if port 8000 is in use
lsof -i :8000 # macOS/Linux
netstat -ano | findstr :8000 # Windows# Clear cache and reinstall
rm -rf node_modules .next
pnpm install# Reset database (development only!)
python manage.py flush --no-input
python manage.py migratepip install androguard
pip install -r requirements.txtCORS errors: Verify CORS_ALLOWED_ORIGINS in backend/falconscan_backend/settings.py includes your frontend origin.
MIT — see LICENSE.