VulnScout - Android Vulnerability Scanner

An Android application built with Kotlin that downloads and manages the NVD (National Vulnerability Database), allowing users to search for vulnerabilities, track products, and receive automatic notifications when new vulnerabilities are published.

Features

• Vulnerability Search: Search CVEs by keyword, product, or severity (CRITICAL, HIGH, MEDIUM, LOW)
• Pull-to-Refresh: Intuitive swipe-down gesture to trigger on-demand synchronization
• Statistics Dashboard: Overview of the local CVE database — total entries, severity breakdown, sync status
• Automatic Updates: Reliable periodic background synchronization using WorkManager, ensuring you receive timely alerts even when the app is closed.
• Smart Notifications: Instant alerts when new high-severity vulnerabilities are found during background syncs.
• Hardware-Backed Security: Sensitive data like the NVD API Key is securely encrypted using Android Jetpack Security (EncryptedSharedPreferences) and the device's Keystore.
• Flexible Configuration:
  • Configurable sync frequency
  • Configurable database size (last N months or complete)
  • NVD API key support (optional)
  • WiFi-only downloads
• Modern UI: Jetpack Compose with Material Design 3

Screenshots

Review the application's clean Material 3 Dark Mode interface:

Technologies Used

• Kotlin - Programming language
• Jetpack Compose - Modern declarative UI
• Room - Local SQLite database
• Retrofit + Moshi - HTTP client and JSON parsing
• WorkManager - Background tasks
• Hilt - Dependency injection
• DataStore - Preferences storage
• Material 3 - Design system
• NVD API 2.0 - Vulnerability data source

Architecture

The application follows the MVVM (Model-View-ViewModel) pattern with clean architecture:

app/
├── data/
│   ├── local/          # Room database, entities, DAOs
│   ├── remote/         # NVD API service, models
│   ├── repository/     # Repositories (data logic)
│   └── preferences/    # DataStore for configuration
├── domain/             # Business logic (future)
├── ui/                 # Compose UI + ViewModels
│   ├── search/
│   ├── products/
│   └── settings/
├── workers/            # WorkManager workers
├── di/                 # Hilt modules
└── utils/              # Utilities (notifications, etc)

Requirements

• Android SDK 26+ (Android 8.0 Oreo)
• Android Studio Hedgehog or higher
• Gradle 8.2+
• Kotlin 1.9.20+
• JDK 17

Installation

1. Clone the repository:

git clone https://github.com/repson/vuln-scout.git
cd vuln-scout

2. Open the project in Android Studio

3. Sync Gradle:

./gradlew build

4. Run the app on an emulator or physical device

---

Building and Running

Debug Build

To build and install the debug version:

# Build debug APK
./gradlew assembleDebug

# Install on connected device
./gradlew installDebug

# Build and run
./gradlew installDebug
adb shell am start -n com.vulnscout/.ui.MainActivity

The debug APK will be located at:

app/build/outputs/apk/debug/app-debug.apk

Release Build

To build a signed release version:

1. Create a keystore (first time only):

keytool -genkey -v -keystore vulnscout-release-key.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias vulnscout-key

2. Create keystore.properties in the project root:

storeFile=/path/to/vulnscout-release-key.jks
storePassword=your_store_password
keyAlias=vulnscout-key
keyPassword=your_key_password

3. Update app/build.gradle.kts to add signing config:

android {
    signingConfigs {
        create("release") {
            val keystorePropertiesFile = rootProject.file("keystore.properties")
            if (keystorePropertiesFile.exists()) {
                val keystoreProperties = Properties()
                keystoreProperties.load(FileInputStream(keystorePropertiesFile))
                
                storeFile = file(keystoreProperties["storeFile"] as String)
                storePassword = keystoreProperties["storePassword"] as String
                keyAlias = keystoreProperties["keyAlias"] as String
                keyPassword = keystoreProperties["keyPassword"] as String
            }
        }
    }
    
    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

4. Build release APK:

./gradlew assembleRelease

Output: app/build/outputs/apk/release/app-release.apk

5. Build Android App Bundle (AAB) for Play Store:

./gradlew bundleRelease

Output: app/build/outputs/bundle/release/app-release.aab

---

Testing

Unit Tests

Run unit tests:

./gradlew test

Run tests with coverage:

./gradlew testDebugUnitTest

Instrumented Tests

Run on connected device or emulator:

./gradlew connectedAndroidTest

Test Structure

Create tests in the following directories:

• app/src/test/ - Unit tests (JUnit)
• app/src/androidTest/ - Instrumented tests (Espresso)

Example unit test for CveRepository:

@Test
fun `syncCves should download and save CVEs`() = runTest {
    // Arrange
    val mockApi = mockk<NvdApiService>()
    val repository = CveRepository(cveDao, mockApi, userPreferences)
    
    // Act
    val result = repository.syncCves()
    
    // Assert
    assertTrue(result.isSuccess)
    verify { cveDao.insertCves(any()) }
}

---

Configuration

NVD API Key (Optional)

For better rate limits (50 req/s vs 50 req/30s):

1. Request a free API key at NVD API
2. In the app, go to Settings → NVD API Key
3. Enter your API key

First Sync

The first time you use the app:

1. Go to Settings
2. Configure database size:
   • Last N months: Faster, less storage
   • Full database: ~250,000 CVEs, ~500MB-1GB
3. Tap Sync Now
4. Wait for initial download to complete (may take several minutes)

Usage

Search Vulnerabilities

1. Go to Search tab
2. Type in search bar (product name, CVE ID, keyword)
3. Use severity filters to refine results
4. Tap a vulnerability to view full details

Statistics

1. Go to Stats tab
2. View total CVEs in local database
3. Check severity breakdown (CRITICAL, HIGH, MEDIUM, LOW)
4. See last sync status and timestamp

Settings

• Sync Frequency: Auto-update frequency (default: 24 hours)
• Database Size: How many months to retain or full database
• WiFi Only: Sync only on WiFi

Privacy Policy

VulnScout respects your privacy:

• No user data collected
• No analytics or tracking
• No account required
• Data stays on your device
• Only communicates with NVD API (HTTPS)

For the complete privacy policy, visit: Privacy Policy

Roadmap

• Detailed CVE view screen
• Export search results
• Advanced filters (by date, CVSS score)
• Vulnerability trend charts
• Support for multiple vulnerability databases
• Home screen widget

Contributing

Contributions are welcome! Please:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License. See LICENSE for details.

Credits

• Vulnerability data provided by NVD (National Vulnerability Database)
• Material Design icons

Support

For questions or suggestions, please open an issue on GitHub.

Disclaimer

VulnScout is an independent project and is not affiliated with or endorsed by NIST or the National Vulnerability Database.