mailaccess 0.1.0__tar.gz

mailaccess-0.1.0/.env.example

@@ -0,0 +1,101 @@
+# MailAccess Environment Configuration
+
+# Application Environment
+# Can be 'development' or 'production'
+MAILACCESS_ENV=development
+
+# Database Connection
+# Leave empty to use SQLite. Default: sqlite+aiosqlite:///./data/mailaccess.db
+# To use Postgres, set this to your connection string. Example:
+# DATABASE_URL=postgresql://user:password@db:5432/mailaccess
+# DATABASE_URL=
+
+# Backend Configuration
+# The URL where the backend is accessible
+BACKEND_URL=http://localhost:8000
+
+# CORS Allowed Origins
+# Comma-separated list of origins allowed to access the backend API (maps to CORS_ORIGINS in config)
+CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]
+
+# Application debug mode (true/false)
+DEBUG=false
+# Log level: DEBUG, INFO, WARNING, ERROR
+LOG_LEVEL=INFO
+
+# Investigation Settings
+# Maximum number of modules to run concurrently
+MAX_CONCURRENT_MODULES=10
+# Per-module timeout in seconds
+MODULE_TIMEOUT_SECONDS=30
+# Per-module timeout in seconds. Global default is MODULE_TIMEOUT_SECONDS.
+MODULE_TIMEOUT_OVERRIDES={"whatsmyname": 200, "account_discovery": 120}
+
+# Whether to enable investigation history persistence
+ENABLE_HISTORY=true
+
+# Account discovery module: probes registration/reset endpoints across 57 platforms.
+# Opt-in because it is noisy (many HTTP probes) and may trigger rate limits.
+# Enable via --modules account_discovery in the CLI or by setting this to true.
+ENABLE_ACCOUNT_DISCOVERY=false
+
+# WhatsMyName module: username enumeration across 700+ platforms.
+# Opt-in because it fires ~700 HTTP requests and takes 60–90 seconds.
+# Data is fetched from GitHub and cached locally for 24h (data/cache/wmn-data.json).
+ENABLE_WHATSMYNAME=false
+
+# Permutation discovery: if breach/Gravatar/other modules recover a real name,
+# auto-generates up to 60 email variations and probes each with HIBP + Hudson Rock.
+# Opt-in because it adds 30–60 seconds and up to 120 extra API calls.
+ENABLE_PERMUTATION_DISCOVERY=false
+
+# GHunt: deep Google account intelligence (GAIA ID, YouTube channel, Maps reviews, profile photo).
+# Requires ghunt>=2.3 installed (`pip install "mailaccess[ghunt]"`) and a valid session obtained
+# via `ghunt login`. Cookies expire periodically and must be refreshed manually.
+# See docs/ghunt-setup.md for the one-time setup guide.
+# Only runs against @gmail.com, @googlemail.com, or Google Workspace domains.
+ENABLE_GHUNT=false
+# Absolute path to the ghunt_creds.json file generated by `ghunt login`
+GHUNT_CREDS_PATH=
+
+# Optional proxy for all requests (e.g. Tor or HTTP proxy)
+# Example: socks5://127.0.0.1:9050  (Tor) or http://user:pass@proxy:port
+PROXY_URL=
+# Set to true to activate the proxy. Proxy is ignored when false.
+PROXY_ENABLED=false
+
+# Per-domain rate limiting
+# Set to false to disable all rate limiting (not recommended in production)
+RATE_LIMIT_ENABLED=true
+# Default minimum delay between requests to the same domain (milliseconds)
+REQUEST_DELAY_MS=1000
+# Per-domain overrides as a JSON object (values in milliseconds)
+# Example: RATE_LIMIT_OVERRIDES={"api.github.com": 500, "haveibeenpwned.com": 1500}
+RATE_LIMIT_OVERRIDES={}
+# Legacy per-domain delays in seconds (JSON object): RATE_LIMIT_DELAYS={"haveibeenpwned.com": 1.5}
+RATE_LIMIT_DELAYS={}
+
+# Integrations (Webhooks)
+SLACK_WEBHOOK_URL=
+DISCORD_WEBHOOK_URL=
+INTEGRATION_WEBHOOK_URL=
+INTEGRATION_WEBHOOK_SECRET=
+
+# API Keys (all optional, features will be disabled if key is missing)
+# MAILACCESS_API_KEY restricts access to the REST API if set
+MAILACCESS_API_KEY=
+
+# Have I Been Pwned API Key for breach data (hibp module)
+HIBP_API_KEY=
+
+# SerpAPI Key for Google dork queries (google_dork module)
+SERPAPI_KEY=
+
+# Shodan API Key for host intelligence (shodan module and domain_intel)
+SHODAN_API_KEY=
+
+# EmailRep API Key for email reputation checking (emailrep module, optional - raises rate limits)
+EMAILREP_API_KEY=
+
+# Hunter.io API Key for email deliverability checks (hunter_io module)
+HUNTER_IO_API_KEY=

mailaccess-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug Report
+about: Something is broken or behaving incorrectly
+title: '[bug] '
+labels: bug
+assignees: ''
+---
+
+## What happened
+
+<!-- A clear description of the bug. What did you expect to happen? What actually happened? -->
+
+## Steps to reproduce
+
+1. 
+2. 
+3. 
+
+## Environment
+
+- MailAccess version / commit:
+- Deployment: [ ] Docker Compose  [ ] Manual
+- Database: [ ] SQLite  [ ] PostgreSQL
+- OS:
+
+## Relevant logs or output
+
+```
+paste logs here
+```
+
+## Which module or endpoint is affected
+
+<!-- e.g. "hibp module", "GET /api/investigations", "WebSocket stream" -->
+
+## Additional context
+
+<!-- Screenshots, curl commands, example emails (use a fake address), anything else useful -->

mailaccess-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: '[feature] '
+labels: enhancement
+assignees: ''
+---
+
+## What problem does this solve
+
+<!-- Describe the gap or pain point. What are you trying to do that you can't do today? -->
+
+## Proposed solution
+
+<!-- How would you like this to work? Be as specific as you can — API shape, UI behavior, module output, etc. -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about and why you ruled them out -->
+
+## Additional context
+
+<!-- Mockups, links to similar tools, related issues -->

mailaccess-0.1.0/.github/ISSUE_TEMPLATE/new_module.md

@@ -0,0 +1,39 @@
+---
+name: New Module Proposal
+about: Propose adding a new OSINT data source as a module
+title: '[module] '
+labels: module
+assignees: ''
+---
+
+## Data source
+
+**Name:** <!-- e.g. FullContact, Hunter.io, Shodan -->
+**URL:** <!-- link to the API or service -->
+
+## What it checks
+
+<!-- What information does this source provide for a given email address? -->
+
+## Example output
+
+<!-- Paste a sample API response or describe what findings would look like. -->
+
+## API key required?
+
+- [ ] Yes — free tier available
+- [ ] Yes — paid only
+- [ ] No
+
+## Rate limits
+
+<!-- Requests per minute / day on the free tier, if known -->
+
+## Why it belongs in MailAccess
+
+<!-- What OSINT value does this add that existing modules don't cover? -->
+
+## Will you implement it?
+
+- [ ] Yes, I plan to submit a PR
+- [ ] No, I'm requesting someone else implement it

mailaccess-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+
+# Node
+node_modules/
+dist/
+.next/
+*.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Runtime data
+*.db
+data/
+maltego/*.mtz
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Secrets (never commit)
+.env
+.env.local
+.env.*.local
+
+# Test artifacts
+test_*.py
+verify_*.py
+.pytest_cache/
+coverage/
+.coverage
+
+# Documentation
+!.env.example

mailaccess-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

mailaccess-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing
+
+## Adding a Module
+
+Each OSINT module is a single `.py` file in `backend/modules/`. The auto-discovery registry (`backend/modules/__init__.py`) scans the package at import time — no manual wiring needed.
+
+### The five things every module must implement
+
+```python
+from backend.modules.base import BaseModule, ModuleResult, ModuleStatus
+
+class MyModule(BaseModule):
+    name = "my_module"         # 1. unique slug — used in API responses and DB records
+    description = "One line."  # 2. human-readable purpose (shown in GET /api/modules/)
+    requires_key = True        # 3. True if the module should skip when its API key is absent
+
+    async def run(self, email: str) -> ModuleResult:  # 4. async, takes the email string
+        ...
+        return ModuleResult(   # 5. always return ModuleResult — never raise
+            status=ModuleStatus.SUCCESS,   # SUCCESS | PARTIAL | FAILED | SKIPPED
+            findings=[                     # list of dicts — flexible schema per module
+                {
+                    "platform": "my_service",
+                    "url": "https://...",
+                    "metadata": {...},
+                    "confidence": "high",  # high | medium | low
+                }
+            ],
+            metadata={},   # module-level supplementary info (counts, API version, etc.)
+            errors=[],     # human-readable error strings
+        )
+```
+
+### Key constraints
+
+- **Never raise from `run()`.** Catch all exceptions and return `ModuleResult(status=ModuleStatus.FAILED, errors=[str(e)])`.
+- **Check for missing keys early.** If `requires_key = True`, check `settings.your_api_key` at the top of `run()` and return `ModuleStatus.SKIPPED` if absent.
+- **Use `build_client()`** from `backend.core.http_client` for all outbound HTTP — it respects proxy settings and the rate limiter.
+- The engine enforces `MODULE_TIMEOUT_SECONDS` (default 30 s) per module via `asyncio.wait_for`. Plan accordingly.
+- Do not call blocking libraries directly on the event loop — wrap them with `asyncio.to_thread()`.
+
+### File placement
+
+Drop the file at `backend/modules/my_module.py`. The next server start auto-registers it. Module `name` values must be unique across the package.
+
+---
+
+## Adding an Exporter
+
+Exporters live in `backend/exporters/`. Each inherits `BaseExporter`:
+
+```python
+from backend.exporters.base import BaseExporter
+
+class MyExporter(BaseExporter):
+    format_name = "myformat"              # matched against ?format= query param
+    content_type = "application/x-mine"  # MIME type returned in the HTTP response
+
+    def export(self, investigation_id: str, data: dict) -> bytes:
+        ...
+        return result_bytes
+```
+
+After writing the class, register it in `backend/exporters/__init__.py` — add it to the import list and to the `EXPORTERS` dict.
+
+The `data` argument is the enriched report dict produced by `enrich_report()` in `backend/core/service.py`. It contains: `id`, `email`, `status`, `exposure_score`, `risk_level`, `summary`, `findings`, `module_runs`, `findings_by_module`, `metadata_table`.
+
+PDF exports use an async `generate()` method instead of `export()`; see `PdfExporter` for the pattern.
+
+---
+
+## Code Style
+
+- Python 3.11+, `from __future__ import annotations` at the top of every file
+- Type annotations on all function signatures
+- `async`/`await` throughout — no blocking I/O on the event loop
+- No comments that describe *what* the code does — only comments explaining *why* when the reason is non-obvious
+- Line length: 100 characters
+- Formatter: `ruff format` (black-compatible)
+
+---
+
+## PR Checklist
+
+- [ ] Module or exporter follows the contracts above
+- [ ] `requires_key = True` modules return `SKIPPED` (not `FAILED`) when the key is absent
+- [ ] No blocking I/O executed directly on the asyncio event loop
+- [ ] No hardcoded credentials, tokens, or identifying user-agent strings
+- [ ] Existing tests pass (`pytest`)
+- [ ] PR description explains what data source is queried, what the findings look like, and why they are useful for OSINT

mailaccess-0.1.0/DISCLAIMER.md

@@ -0,0 +1,29 @@
+# Disclaimer
+
+## Intended Use
+
+MailAccess is designed for:
+
+- **Security research** — investigating the exposure of your own or client-authorized addresses
+- **OSINT investigations** — open-source intelligence gathering in professional or journalistic contexts
+- **Penetration testing** — with explicit written authorization from the target organization
+- **Personal exposure audits** — checking your own email addresses against breach databases and public sources
+
+## All Data Is from Public Sources
+
+Every data point MailAccess retrieves comes from publicly accessible sources: breach notification databases, public APIs, DNS records, WHOIS registries, and the open web. MailAccess does not exploit vulnerabilities, bypass authentication, or access any non-public system or dataset.
+
+## Not a Hacking Tool
+
+MailAccess is not designed or intended for:
+
+- Unauthorized access to accounts, systems, or private data
+- Surveillance, stalking, or targeted harassment of individuals
+- Aggregating personal data about individuals without their consent or a lawful basis
+- Any activity that violates the Computer Fraud and Abuse Act (CFAA), the UK Computer Misuse Act, GDPR, or equivalent laws in your jurisdiction
+
+## User Responsibility
+
+By using MailAccess you accept sole legal and ethical responsibility for how you deploy and use it. The authors provide this software as-is, without warranty of any kind. If you are unsure whether a particular use is lawful in your jurisdiction, consult a qualified attorney before proceeding.
+
+Misuse of this tool may violate federal, state, or local laws. The project maintainers are not liable for any misuse or damage arising from use of this software.

mailaccess-0.1.0/Makefile

@@ -0,0 +1,42 @@
+.PHONY: dev prod logs shell help
+
+# MailAccess Docker Workflow Commands
+# 
+# Note for Production:
+# This setup does not include Kubernetes, CI/CD pipelines, or SSL termination.
+# For production deployments exposed to the internet, you MUST put a reverse proxy
+# such as Nginx, Caddy, or Traefik in front of the application to handle SSL/TLS
+# termination.
+
+# Load environment variables to detect POSTGRES_ENABLED
+ifneq (,$(wildcard ./.env))
+    include .env
+    export
+endif
+
+# Determine if we should activate the postgres profile
+ifeq ($(POSTGRES_ENABLED),true)
+    COMPOSE_PROFILES := --profile postgres
+else
+    COMPOSE_PROFILES :=
+endif
+
+help:
+	@echo "Available commands:"
+	@echo "  make dev    - Starts the development environment with hot-reload"
+	@echo "  make prod   - Builds and starts the production-optimized environment"
+	@echo "  make logs   - Tails logs for all running containers"
+	@echo "  make shell  - Opens an interactive shell inside the backend container"
+
+dev:
+	docker compose $(COMPOSE_PROFILES) -f docker-compose.yml up --build
+
+prod:
+	@echo "Starting production environment. Ensure you have SSL termination configured upstream!"
+	docker compose $(COMPOSE_PROFILES) -f docker-compose.prod.yml up --build -d
+
+logs:
+	docker compose logs -f
+
+shell:
+	docker compose exec backend /bin/bash || docker compose exec backend /bin/sh

mailaccess-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: mailaccess
+Version: 0.1.0
+Summary: Open-source OSINT email intelligence tool
+Project-URL: Homepage, https://github.com/YOUR_USERNAME/mailaccess
+Project-URL: Documentation, https://github.com/YOUR_USERNAME/mailaccess/docs
+Project-URL: Issues, https://github.com/YOUR_USERNAME/mailaccess/issues
+Author: Katriel Moses
+License: MIT
+Keywords: email,intelligence,osint,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: dnspython>=2.6
+Requires-Dist: fastapi>=0.111
+Requires-Dist: holehe>=1.61
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic[email]>=2.0
+Requires-Dist: python-whois>=0.9
+Requires-Dist: rich>=13
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: stix2>=3.0
+Requires-Dist: typer[all]>=0.25.1
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: weasyprint>=62
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: ghunt
+Requires-Dist: ghunt>=2.3; extra == 'ghunt'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="frontend/public/ma_logo.png" width="120" alt="MailAccess Logo" />
+</p>
+
+<h1 align="center">MailAccess</h1>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
+[![Docker](https://img.shields.io/badge/Docker-Compose-blue.svg)](docker-compose.yml)
+
+Self-hostable OSINT platform for investigating email addresses. Fan out across breach databases, social networks, DNS records, and the open web — get back a unified exposure score and structured findings you can export or pipe into Maltego.
+
+Built for security researchers, OSINT analysts, and penetration testers operating under authorization. Read [DISCLAIMER.md](DISCLAIMER.md) before use.
+
+## Install
+
+### CLI only (fastest)
+
+```bash
+pip install mailaccess
+# or (recommended)
+pipx install mailaccess
+```
+
+### Full self-hosted stack
+
+```bash
+git clone https://github.com/YOUR_USERNAME/mailaccess
+cd mailaccess
+docker compose up -d
+```
+
+### Usage
+
+```bash
+mailaccess investigate you@example.com
+mailaccess investigate you@example.com --format json
+mailaccess investigate you@example.com --modules hibp,gravatar,social
+mailaccess history
+```
+
+<!-- screenshot -->
+
+## Features
+
+- Concurrent module execution — all modules run in parallel, results stream as they arrive
+- WebSocket streaming — partial results arrive in real time without polling
+- REST API + web UI + CLI — use whatever interface fits your workflow
+- Plugin module system — drop a `.py` file in `backend/modules/` and it auto-registers; no wiring required
+- 6 export formats: JSON, CSV, PDF, Markdown, STIX 2.1, Maltego XML
+- Maltego local transform server — run investigations directly from the Maltego desktop app
+- Webhook notifications — Slack, Discord, or any HTTP endpoint
+- Exposure score (0–100) with risk label: low / medium / high / critical
+- SQLite by default; PostgreSQL optional via Docker Compose profile
+
+## Quick Start
+
+```bash
+cp .env.example .env      # all API keys are optional
+docker compose up         # backend :8000  ·  frontend :3000
+```
+
+Open **http://localhost:3000** in your browser.
+
+## Modules
+
+| Module | What it checks | Requires key |
+|--------|---------------|:------------:|
+| `hibp` | Known data breaches via the HIBP v3 API | Yes — `HIBP_API_KEY` |
+| `emailrep` | Reputation score, risk flags, linked profiles (EmailRep.io) | No (key optional) |
+| `gravatar` | Gravatar and Libravatar profile, linked accounts | No |
+| `google_dork` | Google dork queries via SerpAPI — LinkedIn, GitHub, Pastebin, open web | Yes — `SERPAPI_KEY` |
+| `domain_intel` | WHOIS, SPF / DMARC / MX, website presence, Shodan subdomains | No (Shodan optional) |
+| `social` | Account existence on 13 platforms (GitHub, Discord, Spotify, Skype, and more) | No |
+| `account_discovery` | Account probing across 120+ platforms via Holehe (opt-in) | No |
+| `whatsmyname` | Username enumeration across 800+ platforms via WhatsMyName dataset (opt-in) | No |
+| `hudson_rock` | Infostealer credential log lookup via Hudson Rock Cavalier API | No |
+| `permutation_discovery` | Generates email permutations from recovered name, probes with HIBP + Hudson Rock (opt-in) | No |
+| `ghunt` | Deep Google account intel: GAIA ID, YouTube, Maps reviews, Drive (Gmail only, opt-in) | Yes — `GHUNT_CREDS_PATH` |
+| `dns_lookup` | MX, SPF, DMARC, DKIM DNS records | No |
+| `whois_lookup` | WHOIS registration data | No |
+| `shodan` | Hosts and open services for the email's domain | Yes — `SHODAN_API_KEY` |
+| `social_links` | Social profiles inferred from the email username | No |
+| `google_search` | Google search mentions of the email | No |
+
+## Export Formats
+
+| Format | `?format=` value | Use case |
+|--------|-----------------|----------|
+| JSON | `json` | Programmatic use, archiving |
+| CSV | `csv` | Spreadsheet analysis |
+| PDF | `pdf` | Human-readable reports |
+| Markdown | `markdown` | Wikis, issue trackers |
+| STIX 2.1 | `stix` | Threat intelligence platforms |
+| Maltego XML | `maltego` | Maltego graph import |
+
+## Integrations
+
+| Integration | How |
+|-------------|-----|
+| Maltego | Local transform server at `POST /maltego/email_investigate` (no API key required) |
+| Slack | Set `SLACK_WEBHOOK_URL` in `.env` |
+| Discord | Set `DISCORD_WEBHOOK_URL` in `.env` |
+| Generic webhook | `INTEGRATION_WEBHOOK_URL` + optional `INTEGRATION_WEBHOOK_SECRET` (HMAC) |
+
+## Documentation
+
+| Page | Contents |
+|------|----------|
+| [Self-hosting](docs/self-hosting.md) | Docker Compose, `.env` reference, PostgreSQL, proxy/Tor, Maltego setup |
+| [Module reference](docs/modules.md) | All modules, findings schema, adding new modules |
+| [API reference](docs/api.md) | REST endpoints, WebSocket events, authentication |
+| [Export formats](docs/exports.md) | Supported formats, MIME types, filename conventions |
+| [Integrations](docs/integrations.md) | Maltego, Slack, Discord, generic webhooks |
+| [Contributing](CONTRIBUTING.md) | Adding modules, adding exporters, code style, PR checklist |
+
+## License
+
+MIT. All data queried by MailAccess comes from public sources. See [DISCLAIMER.md](DISCLAIMER.md) for authorized use cases and legal responsibility.