Metadata-Version: 2.4
Name: firebase-impact-tool
Version: 1.0.0
Summary: Read-only impact assessment tool for leaked/exposed Firebase credentials (defensive security).
Author-email: "Anuj Rawat (Tazer)" <ajcoolx619@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ajtazer/ajtazer/tree/main/tools/firebase-cred-impact
Project-URL: Repository, https://github.com/ajtazer/ajtazer
Project-URL: Issues, https://github.com/ajtazer/ajtazer/issues
Project-URL: Changelog, https://github.com/ajtazer/ajtazer/blob/main/tools/firebase-cred-impact/CHANGELOG.md
Keywords: firebase,security,credential-exposure,assessment,defensive
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff==0.8.6; extra == "dev"
Requires-Dist: black==24.10.0; extra == "dev"
Requires-Dist: build==1.2.2.post1; extra == "dev"
Requires-Dist: twine==6.0.1; extra == "dev"
Dynamic: license-file

# 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+**.

```bash
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:

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

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

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

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

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

Enable mutating probes (only within an authorized engagement):

```bash
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.

```bash
# 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

```bash
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:

```bash
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`](../../.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:
   ```bash
   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.
