flintbase 0.3.1

# flintBase

A fast, single-binary security toolkit for Google / Firebase API key analysis and Android APK secret scanning, built in Rust.

## What it does

flintBase has three core capabilities:

1. **API Key Analysis** (`flintbase key`) — tests a Google/Firebase API key against **20+ endpoints** to determine which services are enabled, what auth providers are configured, and whether there are security misconfigurations.

2. **APK Secret Scanner** (`flintbase apk`) — downloads an Android app from the Play Store, decompiles it to Java source, and scans every file for hardcoded secrets using NoseyParker.

3. **Full Scan** (`flintbase scan`) — combines both: downloads and decompiles an APK, extracts all Firebase/Google credentials from the results, and automatically runs the full key analysis against every discovered API key.

## Features

### `flintbase key` — API Key Analysis

- **Firebase Authentication** — anonymous signup, email/password auth, provider enumeration, token refresh, password reset
- **Firebase Cloud Messaging (FCM)** — legacy send API, token registration, topic management, v1 API probing
- **Firebase Installations** — device registration emulation (FID generation, install token retrieval)
- **Firebase Storage & Realtime Database** — public read/list detection for storage buckets and RTDB
- **Google Cloud APIs** — Static Maps, Geocoding, Places, YouTube Data, Gemini, Translate, Directions
- **Saved configurations** — re-test previously discovered configs with `--config <name>`, edit `~/.config/flintbase/configs.json` to tweak values
- **Rich terminal output** — colored tables, progress bars, tree-view project analysis, and security finding summaries

### `flintbase apk` — APK Analysis Pipeline

- **Flexible input** — accepts Play Store app URLs, developer page URLs, or direct package names
- **Multi-source APK downloading** — tries APKPure, F-Droid, Huawei AppGallery, and direct APKPure web scrape as fallbacks via [apkeep](https://github.com/EFForg/apkeep)
- **Resilient decompilation** via [jadx](https://github.com/skylot/jadx) — tolerates partial decompilation errors (common in large apps), only fails when zero files are produced
- **Secret scanning** via [NoseyParker](https://github.com/praetorian-inc/noseyparker) — 188 high-signal regex patterns for API keys, tokens, passwords, and more
- **Verbose mode** (`-v`) — shows full stdout/stderr from apkeep, jadx, and NoseyParker for debugging download or decompilation issues
- **Structured reports** — human-readable, JSON, JSONL, or SARIF output
- **Organized workspace** — each package gets its own directory with APK, decompiled sources, and reports
- **Self-healing** — clear error messages, automatic fallback chains, and manual workaround tips when all sources are exhausted

### `flintbase scan` — Full Automated Pipeline

- **End-to-end** — single command goes from Play Store URL to complete security assessment
- **Credential extraction** — parses NoseyParker JSON findings for Google API keys, OAuth secrets, and more
- **Config file scanning** — directly parses `google-services.json`, `strings.xml`, and other Firebase config artifacts from the decompiled APK
- **Smart assembly** — co-locates API keys with their associated project IDs, app IDs, and sender IDs from the same source files
- **Auto key testing** — every discovered API key is automatically run through the full 20+ endpoint key analysis
- **Credential summary table** — shows all extracted credentials with types and source files before testing
- **Config saving** (`--save`) — persist discovered configs to `~/.config/flintbase/configs.json` for later re-testing or manual tweaking

### `flintbase setup` — Dependency Management

- **Platform discovery** — detects OS (Linux/macOS/Windows), CPU architecture (x86_64/aarch64), Linux distro and family, and all available package managers
- **Pre-flight checks** — verifies all external tools are installed and shows versions in a status table
- **Auto-install** (`--install`) — downloads and installs missing tools using the best method for your platform (apt/dnf/pacman/brew/cargo/binary download)
- **Install guidance** — when not using `--install`, shows per-tool installation instructions
- **Pipeline guard** — `flintbase apk` and `flintbase scan` automatically block with a helpful message if any tools are missing

## Installation

### From crates.io

```bash
cargo install flintbase
```

### From source

```bash
git clone https://github.com/sbern/flintbase && cd flintbase
cargo build --release
# Binary at target/release/flintbase
```

### With cargo install (local)

```bash
cargo install --path .
```

## External Dependencies

The `flintbase key` subcommand has no external dependencies. The `flintbase apk` and `flintbase scan` pipelines require these tools:

| Tool | Purpose | Install |
|---|---|---|
| [apkeep](https://github.com/EFForg/apkeep) | APK downloading from Play Store / APKPure | `cargo install apkeep` |
| [jadx](https://github.com/skylot/jadx) | APK decompilation to Java source | Download from GitHub releases |
| Java | Required by jadx | `sudo apt install default-jre` |
| [noseyparker](https://github.com/praetorian-inc/noseyparker) | Secret scanning | `cargo install noseyparker` or `brew install noseyparker` |

The easiest way to get everything set up is to run `flintbase setup --install`, which auto-detects your platform and installs everything for you.

## Usage

### API Key Testing

```bash
# Test a single API key
flintbase key AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Test with full Firebase context
flintbase key AIzaSyXXXX -p my-project -a 1:123:android:abc -s 849958900587

# Re-test a previously saved config (from `flintbase scan --save`)
flintbase key --config com.example.app

# List all saved configs
flintbase key --list-configs
```

### APK Secret Scanning

```bash
# Scan an app for secrets (NoseyParker report only)
flintbase apk "https://play.google.com/store/apps/details?id=com.example.app"

# Scan by package name with JSON report
flintbase apk com.example.app --format json

# Scan all apps from a developer page
flintbase apk "https://play.google.com/store/apps/developer?id=Developer+Name"

# Verbose mode: show apkeep/jadx/noseyparker output for debugging
flintbase apk com.example.app -v
```

### Full Scan (APK + Auto Key Testing)

```bash
# Download, decompile, extract credentials, and test every found key
flintbase scan "https://play.google.com/store/apps/details?id=com.example.app"

# Same with a direct package name
flintbase scan com.example.app

# Custom output directory
flintbase scan com.example.app --output-dir ./analysis

# Save discovered configs for later re-testing or manual editing
flintbase scan com.example.app --save
```

Saved configs are written to `~/.config/flintbase/configs.json` — a human-readable JSON file you can edit to tweak API keys, project IDs, or any other field before re-running with `flintbase key --config <name>`.

The `scan` command runs through six phases:

1. **Resolve packages** — parse Play Store URL or package name
2. **Download APK** — tries multiple download sources with automatic fallback (APKPure → F-Droid → Huawei AppGallery → direct web scrape)
3. **Decompile** — convert to Java source with jadx (tolerant of partial decompilation errors)
4. **Secret scan** — NoseyParker scans all decompiled files
5. **Extract credentials** — parses NoseyParker JSON + `google-services.json` + `strings.xml` + regex patterns across all source files
6. **Key analysis** — each discovered API key is tested against 20+ Firebase and Google Cloud endpoints

### Dependency Setup

```bash
# Check status of all required tools
flintbase setup

# Auto-detect platform and install everything that's missing
flintbase setup --install
```

The `--install` flag performs platform discovery (OS, architecture, distro, available package managers) and uses the best installation method for each tool:

- **Java** — `apt`, `dnf`, `pacman`, `zypper`, or `brew` depending on your system
- **jadx** — downloads the latest release ZIP from GitHub, extracts to `~/.local/share/flintbase/jadx`, and symlinks into `~/.local/bin`
- **apkeep** — `cargo install` if Rust is available, otherwise downloads the pre-built binary for your arch
- **noseyparker** — `brew`, `cargo install`, or pre-built binary download

### Output Structure

When running `flintbase apk` or `flintbase scan`, a workspace is created:

```
flintbase_output/
  com.example.app/
    apk/                    # Downloaded APK file
    decompiled/             # Java source + resources (from jadx)
    reports/
      datastore.np/         # NoseyParker datastore
      secrets.txt           # Human-readable findings
```

## How it works

### Key Analysis

Firebase API keys **identify** a project but do not by themselves **authorize** access. flintBase probes each endpoint with the provided key and interprets the responses:

- **200** or service-specific success → API is enabled and key is accepted
- **400 with validation error** (e.g. `INVALID_ID_TOKEN`) → endpoint is reachable, would work with valid credentials
- **401** → key is invalid or deleted
- **403** → API is restricted, not enabled, or requires billing

### Credential Extraction

The parser combines two data sources to maximize coverage:

1. **NoseyParker findings** — the JSON report is parsed to extract Google API keys, OAuth client secrets, and any other matched patterns. Values are decoded from base64 groups and cleaned.

2. **Firebase config files** — the decompiled APK is scanned for:
   - `google-services.json` — project ID, app ID, sender ID, API keys, OAuth client IDs, storage bucket, database URL
   - `res/values/strings.xml` — Firebase string resources (`google_api_key`, `google_app_id`, `gcm_defaultSenderId`, etc.)
   - Regex patterns across all `.xml`, `.json`, `.java`, `.kt`, `.properties` files — catches stray `AIzaSy*` keys, Firebase app IDs, database URLs, and storage buckets

Credentials from the same source file are co-located, so each API key is paired with the project ID, app ID, and sender ID found alongside it.

## Project Structure

```
src/
  main.rs                  -- CLI entry point (clap subcommands), orchestration
  config.rs                -- FirebaseConfig, TestResult, saved config store (~/.config/flintbase/)
  parser.rs                -- NoseyParker JSON parser + decompiled file config scanner
  preflight.rs             -- Platform discovery, dependency checks, and auto-installer
  scanner.rs               -- NoseyParker wrapper (scan + report + JSON export)
  google.rs                -- 7 Google Cloud API checks
  report.rs                -- Colored tables, tree view, config panel, summary
  apk/
    mod.rs                 -- APK pipeline orchestrator (download → decompile → scan)
    download.rs            -- Play Store URL parsing + multi-source apkeep wrapper with fallbacks
    decompile.rs           -- jadx wrapper with partial-error tolerance
  firebase/
    mod.rs                 -- Firebase test orchestrator with progress bars
    auth.rs                -- 6 Identity Toolkit / SecureToken tests
    fcm.rs                 -- 4 FCM tests (legacy send, token, topics, v1)
    installations.rs       -- FID generation + Firebase Installations API
    storage.rs             -- Realtime Database + Firebase Storage checks
```

## License

MIT