Skip to content

πŸ•΅οΈβ€β™‚οΈ (2-in-1) Email & Username OSINT suite featuring native MCP support for deep data extraction just from a single Email/Username. Analyzes 2720+ actively maintained scan vectors (210+ email / 2510+ username) for security research, investigations, and digital footprinting.

chore: add AI/contributor config and organize gitignore

Bruno Leonardo Michelsed1833721c41
diff --git a/.gitignore b/.gitignore
index 1f9bb11..4213541 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,21 @@
-.env
+# Python
.venv
__pycache__/
-rm_cache.py
+uv.lock
+
+# Secrets & environment
+.env
+
+# Scan outputs & artifacts
+output/
result.json
*.csv
validated_proxies.txt
+
+# Local-only files (scratch, private notes, AI working files)
+docs/local/
+*.local.*
+
+# Tooling
+rm_cache.py
+.playwright-mcp/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..bcaa7f5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,75 @@
+# AI contributor guide
+
+This file orients an AI assistant (or any new contributor) working in this
+repository. `AGENTS.md` is kept in sync with this file β€” edit both together.
+
+## What this project is
+
+A 2-in-1 OSINT suite for **email** and **username** intelligence. It checks
+whether an account exists on a given platform and, when found, extracts rich
+profile metadata. See `README.md` for the full feature list and install steps.
+
+## Start here (read before writing code)
+
+- `README.md` β€” overview, features, installation, usage examples.
+- `CONTRIBUTING.md` β€” the authoritative guide for adding scan modules
+ (naming, validator signatures, orchestrator helpers, return values, style).
+- `docs/USAGE.md` β€” library-mode usage (calling the engine from Python).
+- `docs/FLAGS.md` β€” every CLI flag.
+- `docs/PATTERNS.md` β€” the username/email permutation pattern syntax.
+
+## Repository layout
+
+- `user_scanner/user_scan/<category>/<site>.py` β€” **username** availability
+ modules. Synchronous. Export `def validate_<site>(user: str) -> Result`.
+- `user_scanner/email_scan/<category>/<service>.py` β€” **email** OSINT modules.
+ Asynchronous. Export `async def validate_<service>(email: str) -> Result`.
+- `user_scanner/core/` β€” engine, orchestrator, helpers, `Result`, formatters,
+ exporters (JSON/CSV/PDF). Changes here affect every module; review carefully.
+- `tests/` β€” pytest suite. Add tests for new core behavior.
+
+## Adding a new module (the short version)
+
+Read `CONTRIBUTING.md` first β€” it has full examples. The essentials:
+
+1. **File name** = platform name, lowercase, no spaces/special chars
+ (`github.py`, `reddit.py`).
+2. **One validator** per module: `validate_<name>` returning a `Result`
+ (`Result.available()`, `Result.taken(extra=..., media=...)`,
+ `Result.error("...")`). Image URLs go in `media`, other metadata in `extra`.
+3. **No false positives.** Never infer availability from a bare HTTP 200 or a
+ bare `else`. Verify a unique string/JSON key for **both** the found and
+ not-found states. Confirm *not found* with an explicit marker too, not just
+ a 404 β€” transient/blocked responses must return `Result.error`, never a
+ verdict.
+4. **Map every account namespace** a site exposes before trusting one path;
+ many sites split accounts across several public paths and a clean 404 on one
+ must not launder a blocked response on another.
+5. **Pick the transport by how the site defends itself.** Reach for the
+ impersonating transport (`impersonate_validate` / `impersonate_request`,
+ curl_cffi) first for sites behind bot walls; drop to `generic_validate`
+ (httpx) only when a plain request already returns clean 200/404.
+6. **Never use `raise`.** Return `Result.error(...)` so the scan continues.
+7. **Respect the global CLI flags** in any request-making code (timeout `-t`,
+ concurrency `-C`, `--allow-loud`) β€” mirror the existing helpers.
+
+## Before opening a PR
+
+Local CI gates must pass:
+
+```
+ruff check .
+mypy user_scanner
+pytest
+```
+
+Test live against a **real** handle/email and a **nonexistent** one, across
+every namespace and account type the module checks β€” this is what catches
+mislabeled types, missed namespaces, and false positives/negatives.
+
+## Local files and privacy
+
+- `*.local.*` and `docs/local/` are git-ignored β€” use them for scratch notes,
+ private scan output, and AI working files that must not be committed.
+- `output/` is git-ignored β€” write scan outputs there (e.g. `-o output/result.json`).
+- Never commit real scan results, targets, credentials, or personal data.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..bcaa7f5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,75 @@
+# AI contributor guide
+
+This file orients an AI assistant (or any new contributor) working in this
+repository. `AGENTS.md` is kept in sync with this file β€” edit both together.
+
+## What this project is
+
+A 2-in-1 OSINT suite for **email** and **username** intelligence. It checks
+whether an account exists on a given platform and, when found, extracts rich
+profile metadata. See `README.md` for the full feature list and install steps.
+
+## Start here (read before writing code)
+
+- `README.md` β€” overview, features, installation, usage examples.
+- `CONTRIBUTING.md` β€” the authoritative guide for adding scan modules
+ (naming, validator signatures, orchestrator helpers, return values, style).
+- `docs/USAGE.md` β€” library-mode usage (calling the engine from Python).
+- `docs/FLAGS.md` β€” every CLI flag.
+- `docs/PATTERNS.md` β€” the username/email permutation pattern syntax.
+
+## Repository layout
+
+- `user_scanner/user_scan/<category>/<site>.py` β€” **username** availability
+ modules. Synchronous. Export `def validate_<site>(user: str) -> Result`.
+- `user_scanner/email_scan/<category>/<service>.py` β€” **email** OSINT modules.
+ Asynchronous. Export `async def validate_<service>(email: str) -> Result`.
+- `user_scanner/core/` β€” engine, orchestrator, helpers, `Result`, formatters,
+ exporters (JSON/CSV/PDF). Changes here affect every module; review carefully.
+- `tests/` β€” pytest suite. Add tests for new core behavior.
+
+## Adding a new module (the short version)
+
+Read `CONTRIBUTING.md` first β€” it has full examples. The essentials:
+
+1. **File name** = platform name, lowercase, no spaces/special chars
+ (`github.py`, `reddit.py`).
+2. **One validator** per module: `validate_<name>` returning a `Result`
+ (`Result.available()`, `Result.taken(extra=..., media=...)`,
+ `Result.error("...")`). Image URLs go in `media`, other metadata in `extra`.
+3. **No false positives.** Never infer availability from a bare HTTP 200 or a
+ bare `else`. Verify a unique string/JSON key for **both** the found and
+ not-found states. Confirm *not found* with an explicit marker too, not just
+ a 404 β€” transient/blocked responses must return `Result.error`, never a
+ verdict.
+4. **Map every account namespace** a site exposes before trusting one path;
+ many sites split accounts across several public paths and a clean 404 on one
+ must not launder a blocked response on another.
+5. **Pick the transport by how the site defends itself.** Reach for the
+ impersonating transport (`impersonate_validate` / `impersonate_request`,
+ curl_cffi) first for sites behind bot walls; drop to `generic_validate`
+ (httpx) only when a plain request already returns clean 200/404.
+6. **Never use `raise`.** Return `Result.error(...)` so the scan continues.
+7. **Respect the global CLI flags** in any request-making code (timeout `-t`,
+ concurrency `-C`, `--allow-loud`) β€” mirror the existing helpers.
+
+## Before opening a PR
+
+Local CI gates must pass:
+
+```
+ruff check .
+mypy user_scanner
+pytest
+```
+
+Test live against a **real** handle/email and a **nonexistent** one, across
+every namespace and account type the module checks β€” this is what catches
+mislabeled types, missed namespaces, and false positives/negatives.
+
+## Local files and privacy
+
+- `*.local.*` and `docs/local/` are git-ignored β€” use them for scratch notes,
+ private scan output, and AI working files that must not be committed.
+- `output/` is git-ignored β€” write scan outputs there (e.g. `-o output/result.json`).
+- Never commit real scan results, targets, credentials, or personal data.