firebase-impact-tool 1.0.0

Read-only impact assessment tool for leaked/exposed Firebase credentials (defensive security).

firebase-cred-impact

A read-only, safe-by-default tool for determining the blast radius of an exposed / leaked Firebase credential during an authorized security assessment. Ships as a Python CLI and a zero-build, browser-only web UI.

Purpose: identify what the credential can access so the product team can remediate immediately. It is not an exploitation tool. It never enumerates, downloads, or dumps data, and every operation that could create, modify, or delete a resource is disabled unless you pass an explicit flag.

Key context: a Firebase Web API key is a client identifier, not a secret. Its real impact is governed by the project's Security Rules and enabled sign-in providers — which is exactly what this tool measures.

---

What it does

Runs a 10-phase, non-destructive assessment against a Firebase project using the exposed config and reports precisely which surfaces are reachable without authentication:

1. Credential Identification — validate the API key, record all metadata.
2. Project Fingerprinting — which services are reachable (headers/metadata).
3. Authentication Assessment — provider discovery, anon/email sign-up config, password-reset & email-verification endpoint availability.
4. Firestore Assessment — unauthenticated read/write posture (single-doc probes).
5. Realtime Database Assessment — availability, public read/write (shallow).
6. Cloud Storage Assessment — bucket reachability, listing, read, upload, delete.
7. Cloud Functions Assessment — characterize supplied/known HTTPS endpoints.
8. Security Rule Validation — infer whether rules are restrictive.
9. Privilege Matrix — condensed per-service permissions table.
10. Evidence Collection — write the deliverables (below).

Safety model

Operation	Default	Flag required
Read/reachability probes (all services)	✅ enabled	—
Auth account creation (anonymous / email sign-up)	❌ disabled	--active
Firestore / Realtime Database write probe	❌ disabled	--active
Cloud Storage upload / delete probe	❌ disabled	--storage-write
Cloud Functions brute-force	🚫 never	—

Mutating probes create a single, clearly-labeled, disposable resource and delete it immediately. The API key is masked in every artifact and response bodies are truncated so bulk data can never be captured.

---

Install (CLI)

Requires Python 3.12+.

cd tools/firebase-cred-impact
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .

CLI usage

Read-only assessment from individual values:

firebase-impact assess \
  --project-id your-project \
  --api-key AIzaSy... \
  --output ./assessment-out

From a firebaseConfig JSON object (inline or @file):

firebase-impact assess --config-json @firebaseConfig.json -o ./assessment-out

Assess specific, known HTTPS Cloud Functions (never brute-forced):

firebase-impact assess -p your-project -k AIzaSy... \
  --function api --function webhook --region us-central1

Enable mutating probes (only within an authorized engagement):

firebase-impact assess -p your-project -k AIzaSy... --active          # auth + firestore/rtdb writes
firebase-impact assess -p your-project -k AIzaSy... --storage-write   # storage upload/delete

Output artifacts

Written to the --output directory: report.md, report.html, summary.json, raw_results.json, and logs/assessment.log. Each report includes an Executive Summary, Risk Rating, Affected Services, Evidence, the Privilege Matrix, Recommended Mitigations, and non-sensitive Attribution Identifiers (project id, app id, auth domain, storage bucket, database URL, discovered function endpoints, console URL) to help locate the affected project.

---

Web UI (no build, no backend)

Open web/index.html directly in a browser (or serve it statically) to run the browser-feasible read-only checks entirely client-side — nothing is sent to any server other than the target Firebase project's public endpoints.

# open directly…
xdg-open tools/firebase-cred-impact/web/index.html
# …or serve the folder
python3 -m http.server -d tools/firebase-cred-impact/web 8080   # then visit http://localhost:8080

Because browsers enforce CORS, some Google endpoints (Identity Toolkit, Realtime Database, Cloud Storage, Remote Config) can be checked directly from the page, while others (Firestore REST, cross-origin Cloud Functions) may be blocked. When a check can't run in the browser, the UI degrades gracefully and shows the equivalent CLI command to run instead.

Read-only by default. With no options ticked the page never creates, modifies, or deletes anything. Two opt-in checkboxes mirror the CLI's mutating flags:

• Active (--active) — creates then immediately deletes a disposable auth account (email + anonymous sign-up), a Realtime Database node, and a Firestore document to measure write access.
• Storage upload/delete (--storage-write) — uploads then deletes a single disposable object.

Ticking either one and pressing Run opens an authorization disclaimer that must be explicitly accepted before any write is attempted; cancelling performs no probes. Every mutating probe cleans up the resource it created. Browser CORS still blocks some write endpoints (Firestore/Storage), and those degrade to the equivalent CLI command. The key entered on the page is never stored or transmitted anywhere except the target project's own public endpoints during the live checks.

---

Development

cd tools/firebase-cred-impact
python3.12 -m pip install -e ".[dev]"
pytest                       # offline smoke tests (import + CLI --help)
ruff check firebase_impact   # lint
black --check firebase_impact  # formatting
mypy firebase_impact         # type check (advisory)

Build a release artifact

The CLI is a standard PEP 517 Python package. Build the sdist + wheel with:

cd tools/firebase-cred-impact
python3.12 -m pip install --upgrade build
python3.12 -m build            # writes dist/*.tar.gz and dist/*.whl

Attach the files in dist/ (e.g. firebase_impact_tool-1.0.0-py3-none-any.whl and firebase_impact_tool-1.0.0.tar.gz) to a GitHub Release. Install a released wheel with pip install firebase_impact_tool-1.0.0-py3-none-any.whl.

Releasing

Releases are automated by GitHub Actions (.github/workflows/release.yml). Because this repository ships two independent packages, each is released with its own tag prefix — this package uses firebase-impact-tool-vX.Y.Z.

1. Update the version in firebase_impact/__init__.py (__version__) and add a CHANGELOG.md entry.
2. Commit the changes.
3. Push a version tag:

   git tag firebase-impact-tool-v1.2.3
   git push origin firebase-impact-tool-v1.2.3
   

4. GitHub Actions builds the sdist + wheel, runs twine check, generates SHA256SUMS, and creates a GitHub Release with auto-generated notes and the assets attached.
5. A final version (X.Y.Z) is published to PyPI; a pre-release such as 1.2.3rc1 is published to TestPyPI. Both use OIDC Trusted Publishing (no API tokens).

Alternatively, run the Manual Release workflow from the Actions tab (workflow_dispatch) to bump the version, test, build, and release — with prerelease / draft / publish-to-index toggles.

One-time setup: on PyPI (and TestPyPI) add a Trusted Publisher for this package pointing at repo ajtazer/ajtazer, workflow release.yml, and environment pypi-firebase-impact-tool (respectively testpypi-firebase-impact-tool). Each package uses its own environment so the two configs stay distinct — PyPI rejects duplicate pending-publisher configs.

---

How impact is assessed

The tool reasons from observed HTTP behavior, not assumptions:

• API-key liveness is confirmed via Identity Toolkit getProjectConfig: a dead key returns API_KEY_INVALID; a live key is accepted or returns a different, non-key error.
• Read posture is probed with the smallest possible request — a single non-existent document (Firestore), a ?shallow=true keys-only root read (RTDB), or a maxResults=1 listing / single-object metadata GET (Storage). A 200 implies unauthenticated read; 403 implies rules deny it; 401 implies auth is required; 404 distinguishes "reachable but empty".
• Write posture is only tested with --active, by creating one clearly-named disposable resource and deleting it immediately.
• Auth configuration is inferred from error codes on dry Identity Toolkit calls (e.g. OPERATION_NOT_ALLOWED ⇒ sign-up disabled) so no accounts are created unless --active is set.
• Security-rule posture (Phase 8) is derived from the read/write verdicts above — the tool never attempts to bypass rules.
• Results are condensed into a privilege matrix and mapped to an overall risk rating (accessible-write ⇒ Critical, accessible-read/self-service-auth ⇒ High, reachable-but-restricted ⇒ Low/Medium).

Responsible use

Use only against projects you are authorized to assess. Keep it read-only unless your rules of engagement explicitly permit mutating probes. Never commit real credentials or sample outputs — the included .gitignore blocks common secret/output filenames.