π΅οΈββοΈ (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.
Python cybersecuritycybersecurity-toolsemail-osintethical-hackingethical-hacking-toolsidentificationinfosecosintosint-emailosint-toolosint-toolsosint-usernamepentestingpythonredteam-toolsredteamingthreat-intelligence
chore: add AI/contributor config and organize gitignore
Bruno Leonardo Michelsed1833721c41
diff --git a/.gitignore b/.gitignoreindex 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*.csvvalidated_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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.