Home

🦅 Welcome to the FalconScan Wiki

FalconScan is an enterprise-grade Android APK security analysis platform that combines advanced static analysis, AI-powered intelligence, and professional reporting — helping developers and security researchers identify vulnerabilities before deployment.

---

🚀 Quick Navigation

Section	Description
📦 Installation & Setup	Get FalconScan running locally
📖 User Guide	How to use the platform
🏗️ Architecture	System design and structure
✨ Features	Full feature breakdown
🔒 Security Analysis	What FalconScan checks
🤖 AI Intelligence	Gemini-powered analysis
🔌 API Reference	REST API endpoints
🛠️ Tech Stack	Technologies used
🐛 Troubleshooting	Common issues & fixes

---

📦 Installation & Setup

Prerequisites

• Python 3.8+
• Node.js 18+
• pnpm or npm
• Git

1. Clone the Repository

git clone https://github.com/AbdullahMaqbool22/FalconScan.git
cd FalconScan

2. Backend Setup (Django)

cd backend

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run database migrations
python manage.py migrate

# (Optional) Create admin superuser
python manage.py createsuperuser

# Start the backend server
python manage.py runserver

Backend runs at → http://localhost:8000

3. Frontend Setup (Next.js)

# From the project root
pnpm install

# Configure environment
cp .env.example .env.local
# Set: NEXT_PUBLIC_API_URL=http://localhost:8000/api

# Start the frontend
pnpm dev

Frontend runs at → http://localhost:3000

---

📖 User Guide

Uploading an APK for Analysis

1. Navigate to http://localhost:3000 and log in (or register).
2. Go to the Upload page from the sidebar.
3. Drag & drop an .apk file, or click to browse.
4. Optionally enter an app name (filename is used if left blank).
5. Click Start Analysis — results appear in ~1.5–2 seconds.

Viewing Results

Page	What You'll Find
Dashboard	Overview stats: total scans, threat levels, recent activity
Reports	Full vulnerability breakdown per scan, filterable by severity
History	Timeline of all previous scans
Report Detail	10+ analysis sections, charts, remediation guidance

Exporting Reports

Click Download PDF on any report page to get a professionally formatted security assessment document.

---

🏗️ Architecture

Backend (Django REST Framework)

backend/
├── falconscan_backend/        # Project config (settings, urls, asgi/wsgi)
└── apps/
    ├── accounts/              # JWT auth, user models, profile management
    └── scans/
        ├── analyzer.py        # APK analyzer wrapper (Androguard)
        ├── static_analyzer.py # String & artifact extraction
        ├── vulnerability_scanner.py  # 15+ security checks
        ├── pdf_generator.py   # ReportLab PDF reports
        ├── tasks.py           # Background analysis tasks
        ├── views.py           # REST API endpoints
        └── models.py          # Scan, Vulnerability, Report models

Frontend (Next.js + TypeScript)

app/
├── page.tsx                   # Landing page
├── login/ & register/         # Authentication pages
└── dashboard/
    ├── upload/                # APK upload interface
    ├── reports/[id]/          # Detailed report view
    ├── history/               # Scan timeline
    ├── profile/               # User settings
    └── documentation/         # In-app docs viewer

---

✨ Features

Core Analysis

• Manifest Analysis — Permissions, components, debug flags, backup settings
• Certificate Validation — Debug cert detection, expiry checks
• Code Analysis — Hardcoded secrets, weak crypto, SQL injection patterns
• String Extraction — URLs, IPs, emails, phone numbers, API keys
• Component Discovery — Activities, services, receivers, providers

Reporting & UI

• PDF Export — Professional reports with executive summary
• Interactive Charts — Severity distribution, threat breakdown (Recharts)
• Real-time Notifications — Scan completion alerts
• Responsive Design — Desktop, tablet, and mobile support
• Dark Cybersecurity Theme — Glassmorphism UI with Tailwind CSS

Advanced

• Duplicate Detection — Skips re-analysis of identical APKs
• Auto-Recovery — Retries failed scans automatically
• Multi-tab Support — Persistent state across browser tabs
• Real-time Progress — Live status tracker during analysis

---

🔒 Security Analysis

FalconScan runs 15+ checks covering the OWASP Mobile Top 10:

Category	Checks
Manifest	Debuggable flag, backup allowed, min SDK version, network security config
Permissions	Dangerous permissions (CAMERA, SMS, LOCATION, CONTACTS), unused permissions
Certificates	Debug cert in production, expiry, signature verification
Components	Exported components without permission, unsafe intent filters
Code	Hardcoded API keys (AWS, Firebase, GitHub, Stripe, Google), weak crypto (DES, MD5, ECB, SHA-1), SQL injection, path traversal, cleartext HTTP, sensitive data logging

Risk Scoring

Severity	Points	Color
Critical	25 pts each	🔴
High	15 pts each	🟠
Medium	8 pts each	🟡
Low	3 pts each	🟢

Score multipliers are applied for: dangerous permissions (5+), debuggable flag, cleartext traffic, hardcoded secrets, and backup enabled.

Threat Level	Score Range
🔴 Critical	≥ 80
🟠 High	≥ 60
🟡 Medium	≥ 35
🟢 Low	≥ 15
✅ Safe	< 15

---

🤖 AI Intelligence

FalconScan integrates Google Gemini (google-genai) for in-depth AI-powered analysis:

1. Open any completed scan report.
2. Click the AI tab.
3. Click Generate AI Report.
4. Receive in 10–20 seconds:
   • Attack chain mapping
   • Severity re-scoring with justification
   • Code-level fix recommendations
   • Compliance notes (OWASP, GDPR, etc.)

---

🔌 API Reference

All endpoints are prefixed with /api/.

Authentication

Method	Endpoint	Description
POST	/api/auth/register/	Register a new user
POST	/api/auth/login/	Obtain JWT tokens
POST	/api/auth/refresh/	Refresh access token
GET	/api/auth/profile/	Get current user profile

Scans

Method	Endpoint	Description
POST	/api/scans/upload/	Upload APK and start analysis
GET	/api/scans/	List all scans
GET	/api/scans/{id}/	Get scan details
DELETE	/api/scans/{id}/	Delete a scan
GET	/api/scans/{id}/report/	Get full vulnerability report
GET	/api/scans/{id}/download-pdf/	Download PDF report
POST	/api/scans/{id}/ai-analysis/	Generate AI security analysis

All protected endpoints require Authorization: Bearer <access_token> header.

---

🛠️ Tech Stack

Layer	Technology
Backend Framework	Django 4.2 + Django REST Framework
APK Analysis	Androguard 4.x
AI Engine	Google Gemini (google-genai 1.0+)
Authentication	JWT (djangorestframework-simplejwt)
Database	SQLite (dev) / PostgreSQL (prod)
PDF Generation	ReportLab
Server	Daphne (ASGI)
Frontend Framework	Next.js 16 + TypeScript 5
UI Components	shadcn/ui + Radix UI
Styling	Tailwind CSS
Charts	Recharts
HTTP Client	Axios

---

🐛 Troubleshooting

Backend won't start

• Ensure virtual environment is activated.
• Run pip install -r requirements.txt again.
• Check that migrations are applied: python manage.py migrate.

Frontend can't reach backend

• Verify NEXT_PUBLIC_API_URL in .env.local points to http://localhost:8000/api.
• Confirm the Django server is running.
• Check CORS settings in backend/falconscan_backend/settings.py.

APK upload fails

• Only .apk files are accepted.
• Make sure the media/apks/ directory exists and is writable.
• Confirm Androguard is installed: pip show androguard.

---

📄 License

FalconScan is released under the MIT License. See LICENSE for details.

---

This wiki is maintained by Abdullah Maqbool.