Metadata-Version: 2.4
Name: mailaccess
Version: 0.16.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: alembic>=1.13
Requires-Dist: asyncpg>=0.29
Requires-Dist: curl-cffi>=0.7
Requires-Dist: dnspython>=2.6
Requires-Dist: fastapi>=0.111
Requires-Dist: httpx>=0.27
Requires-Dist: imagehash>=4.3
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic[email]>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: python-whois>=0.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: rich>=13
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: stix2>=3.0
Requires-Dist: typer[all]>=0.25.1
Requires-Dist: unidecode>=1.3
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: websockets>=12
Provides-Extra: build
Requires-Dist: duckdb==1.5.5; extra == 'build'
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-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: ml
Requires-Dist: spacy<4.0,>=3.7; extra == 'ml'
Provides-Extra: pdf
Requires-Dist: weasyprint>=60.0; extra == 'pdf'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mailaccess-logo-reversed.svg">
    <img src="assets/brand/mailaccess-logo.svg" alt="MailAccess" width="440">
  </picture>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-0D0D0D.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11%2B-0D0D0D.svg" alt="Python 3.11+"></a>
  <a href="docker-compose.yml"><img src="https://img.shields.io/badge/Docker-Compose-0D0D0D.svg" alt="Docker Compose"></a>
  <a href="https://pypi.org/project/mailaccess/"><img src="https://img.shields.io/static/v1?label=PyPI&message=0.16.0&color=8A1C2B&logo=pypi&logoColor=white" alt="PyPI version"></a>
  <a href="https://pepy.tech/projects/mailaccess"><img src="https://img.shields.io/pepy/dt/mailaccess?color=8A1C2B&amp;label=downloads" alt="PyPI downloads"></a>
</p>

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.

## Terminal Output

![MailAccess terminal output](assets/terminal-hero.png)

## Install

```bash
pip install mailaccess
mailaccess investigate you@example.com
```

The CLI auto-starts and stops the backend for each investigation. Use
`mailaccess serve` when you want a persistent server, or install
`mailaccess[ml]` for optional spaCy-based name classification.

Full install options (Docker, persistent server, self-hosting) -> [docs/self-hosting.md](docs/self-hosting.md).

## Quick Start

```bash
mailaccess investigate you@example.com
mailaccess investigate you@example.com -o report.pdf
mailaccess harvest-emails --domain company.com
mailaccess harvest-emails --domain company.com --export harvest.csv
mailaccess find-email --name "Jane Doe" --domain company.com
mailaccess keys set HIBP_API_KEY your-key
mailaccess keys list
mailaccess serve
mailaccess modules
```

Pipeline, stdin, JSONL, and CI examples -> [docs/integrations.md](docs/integrations.md#pipeline-integration).

![Investigation demo](assets/investigate.gif)

![Harvest emails demo](assets/harvest-emails.gif)

## What It Does

- **Identity graph** - cross-platform correlation of accounts, usernames, names, avatars, breach data, and profile links.
- **Name Consensus Engine** - synthesizes independent name signals into confirmed, probable, possible, or unknown identity bands.
- **Defender's Brief** - security-manager-ready risk summary with prioritized findings and a concrete next action.
- **Domain email harvesting** - `harvest-emails` discovers organization addresses across Common Crawl, GitHub, CT logs, registries, keyservers, dorks, employee pages, and patterns.
- **Company email patterns** - `find-email` turns a name plus an employer domain into one honestly-graded likely address, offline from a bundled 384K-domain pattern index; unverified guesses are labelled as such, and Microsoft 365 mailboxes are verified where the provider allows.
- **5,000+ platform corpus** - a native username-platform engine over a MailAccess-verified corpus of 5,000+ platform definitions (`data/mailaccess_sites.json`), with two-marker detection and zero runtime dependencies; each investigation probes a bounded, rank- and health-prioritized subset of the highest-signal platforms. Plus a native account-existence engine covering 250+ email-checkable services, and native Google-account intelligence (unauthenticated, on by default).
- **Deep breach mode** - probes the highest-severity breach corpus for account-existence risk.
- **Credential Risk Score** - separate 0-100 credential exposure band with top drivers and recommended next steps.
- **6 export formats** - JSON, CSV, PDF, Markdown, STIX 2.1, and Maltego XML.

## Identity Graph

Every investigation builds an identity graph linking accounts by shared usernames, photos, display names, and breach data. View it at `/investigation/:id/graph`, export it with `GET /api/report/{id}/graph`, or read the full model in [docs/modules.md](docs/modules.md).

## Name Consensus Engine

MailAccess collects name signals from profile modules and returns a defensible identity summary:

```text
CONFIRMED IDENTITY
  Name:     Katriel Moses  [CONFIRMED]
  Sources:  GitHub . Gravatar . Keybase . PGP
  Reasoning: 4 independent sources agree.
```

Full confidence rules and source behavior -> [docs/modules.md](docs/modules.md).

## Defender's Brief

Every investigation includes a 30-second risk summary designed for security managers:

```text
DEFENDER'S BRIEF
  Risk:    CRITICAL
  Summary: Active infostealer infection detected.
  1. Active credential theft   [CRITICAL]
     -> Rotate credentials immediately.
  Next action: Immediately rotate credentials and enforce hardware MFA.
```

Suppress it with `--no-brief`; full details live in [docs/modules.md](docs/modules.md).

## Find Email (Company Patterns)

Give MailAccess a person's name and their employer domain and it returns **one** most-likely email address — not a spray of guesses:

```bash
mailaccess find-email --name "Jane Doe" --domain company.com
```

```text
Company email pattern - company.com
  email          jane.doe@company.com
  verification   unverified
  confidence     likely (0.78)
  support        142 verified samples
  provenance     company email pattern (P04, 142 verified samples, conf 0.91)
```

The pattern comes from a bundled index of ~384,000 domains learned from real verified addresses — it loads offline, no network access. The result is **honest by construction**: an inferred address is always labelled `unverified` and graded *likely*, never presented as confirmed. Where the domain runs on Microsoft 365, the candidate is checked against the mailbox-existence oracle — a confirmed one is upgraded to `provider_verified`, and one proven not to exist is dropped. Add `--title` to apply per-role pattern overrides. Domains the index doesn't cover fall back cleanly to live inference. Full details -> [docs/modules.md](docs/modules.md#find-email-company-email-pattern-index).

## Modules

75 modules over a 5,000+ platform corpus. Investigations probe a bounded, evidence-first wave of the highest-signal platforms (~700 vetted by default) rather than the whole corpus. Full module reference -> [docs/modules.md](docs/modules.md).

## API Keys

Most modules work with zero keys. Optional keys unlock more coverage. Full list -> [docs/api-keys.md](docs/api-keys.md).

## Export Formats

Save reports as JSON, CSV, PDF, Markdown, STIX 2.1, or Maltego XML with `-o`. Full export reference -> [docs/exports.md](docs/exports.md).

## Integrations

Use Maltego, Slack, Discord, generic webhooks, JSONL pipelines, and CI workflows. Full integration guide -> [docs/integrations.md](docs/integrations.md).

## Self-Hosting

Run the CLI locally or launch the full web stack with Docker Compose. Full guide -> [docs/self-hosting.md](docs/self-hosting.md).

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## Troubleshooting

![Troubleshooting demo](assets/troubleshoot.gif)

## Links

| | |
|-|-|
| [Self-hosting guide](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 |
| [False-positive controls](docs/fp-control.md) | Common-name, disposable-domain, clustering, health, and scoring controls |
| [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 |
| [Brand assets](docs/brand.md) | Logo lockups, palette, typography, clearspace, downloadable SVGs |
| [Sponsors](docs/sponsors.md) | Current partners and categories accepting sponsors |
| [Contributing](CONTRIBUTING.md) | Adding modules, adding exporters, code style, PR checklist |
| [PyPI](https://pypi.org/project/mailaccess/) | `pip install mailaccess` |
| [GitHub](https://github.com/KatrielMoses/MailAccess) | Source code, issues, releases |

## License

MIT. All data queried by MailAccess comes from public sources. See [DISCLAIMER.md](DISCLAIMER.md) for authorized use cases and legal responsibility.
