recon
Point recon at a domain and get its public technology and identity footprint: email security, mail and identity providers, SaaS indicators, and certificate-transparency findings. No credentials, no API keys, no active scanning. Ships as a CLI, versioned JSON, and a local MCP server for agent tools.
A domain is a query coordinate, not proof of one organization or product. Observations, not verdicts.
Defensive use only. Posture review, vendor diligence, architecture review. See docs/legal.md.
Quick Start
Install with uv or pipx:
uv tool install recon-tool
# or
pipx install recon-tool
Python 3.11 through 3.14, on Windows, macOS, or Linux.
Optional helpers at scripts/install.ps1 and scripts/install.sh drive an
existing uv or pipx installation. Download a
release-tag source archive,
review the helper locally, then run it. Each helper installs the exact version
represented by that tag, preserves a sole existing uv or pipx owner, and
refuses ambiguous or unmanaged installations. Do not pipe mutable branch
content into a shell. To verify published artifacts before installing, follow the
consumer verification recipe.
Verify the installed command offline:
recon --version
Then optionally test online connectivity to recon's public data sources:
recon doctor
Before the first lookup, know what leaves your machine. recon makes DNS queries
that recursive and authoritative DNS infrastructure may observe. Its only
default request to a target-owned endpoint is the standards-defined MTA-STS
policy fetch. Google CSE and BIMI certificate probes run only when
--direct-probes is explicitly enabled. Full boundary:
docs/how-it-works.md.
recon example.com
Example output
This is a deterministic, no-network fixture for Globex Ltd using IETF reserved .invalid namespaces (globex.invalid). No real organization is depicted.
Accessible text transcript
$ recon globex.invalid
Globex Ltd
globex.invalid
──────────────────────────────────────────────────────────────────────────────
Provider Microsoft 365 (MX delivery path) + Proofpoint gateway (MX
delivery path)
Tenant a1b2c3d4-e5f6-7890-abcd-ef1234567890 • NA
Tenant domain globex.onmicrosoft.invalid
Auth Federated
Confidence ●●● High (4 sources)
Services
Email Microsoft 365 (MX delivery path),
Proofpoint (MX delivery path), DMARC reject, DKIM,
SPF strict, MTA-STS enforce
Identity Okta (CNAME endpoint binding)
Cloud Cloudflare (CDN/edge), AWS Route 53 (DNS)
Security Wiz Security (public TXT account indicator)
Collaboration Slack (public TXT account indicator),
Atlassian (Jira/Confluence) (CNAME endpoint binding)
High-signal related domains
login.globex.invalid, status.globex.invalid, support.globex.invalid
Insights
Federated identity observed; identity-vendor indicators: Okta
Email security: observed controls: DMARC reject, DKIM, SPF strict, MTA-STS
Install, update, uninstall, and first-run detail: docs/getting-started.md.
What recon Is Good For
| Need | Use recon for | Use something else when |
|---|---|---|
| Fast external stack context | Passive DNS, identity-endpoint, CT, SaaS, and posture indicators | You need authenticated tenant inventory or asset-management truth |
| Defensive review or vendor diligence | Hedged observations and evidence traces you can verify | You need vulnerability scanning, exploit checks, or host-level facts |
| Automation-friendly output | Stable JSON, batch mode, delta mode, and local MCP tools | You need dashboards, scheduling, or report generation built in |
recon reports observations, not verdicts. Public channel ceiling: docs/limitations.md.
Common Commands
recon example.com # default panel
recon example.com --explain # evidence trail
recon example.com --plain # linear text for screen readers and grep
recon example.com --json # structured record
recon batch domains.txt --json # batch JSON array
recon delta example.com # diff vs local cache
recon mcp install --client=cursor # wire MCP into a client
More flags: docs/cli-surface.md. JSON contracts: schema · stability · operational contract.
docs/surface-inventory.json, docs/cli-surface.md, and
recon://surface-inventory are generated discovery context and drift guards,
not stable runtime API contracts. ADR-0007 records the promotion gate.
Use with an AI agent (MCP / skill)
Wire recon into Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Kiro, or any MCP-compatible client:
recon mcp install --client=claude-desktop
# also: claude-code, cursor, vscode, windsurf, kiro
recon mcp doctor
Start with manual tool approvals. Treat agents as untrusted input. Full setup: docs/mcp.md. Per-client scaffolds and skills: agents/.
| You say | What the agent should do |
|---|---|
| "Recon globex.invalid" | Call lookup_tenant (or recon globex.invalid) and return the panel-style summary |
| "What does globex.invalid run for email and identity?" | Same lookup; lead with MX/IdP/tenant facts and confidence |
| "Why do you think that?" | Re-run with explain / provenance (--explain or explain=true) |
| "Compare globex.invalid and beta.invalid" | compare_postures or two lookups side by side |
| "Any public hardening gaps?" | find_hardening_gaps after a lookup - hedged "Consider" notes only |
Example chat (Globex demo shape):
You: Recon globex.invalid and tell me what you observe.
Agent: Public evidence for
globex.invalid(fictional demo):
- Mail: Microsoft 365 delivery path plus Proofpoint gateway; DMARC
p=reject, SPF strict, MTA-STS enforce.- Identity: Federated; Okta indicator via CNAME.
- Tenant: GUID present, region NA; confidence high from four sources.
- Also seen: Cloudflare edge, AWS Route 53 DNS, Slack/Atlassian/Wiz public indicators.
These are public-record observations, not a security grade or proof of active product use. Say if you want evidence detail or a gap review.
Guidance: agents/claude-code/skills/recon/, AGENTS.md.
Optional Cloud Access
Local execution is the default, and the project does not operate a hosted service. For teams that want shared remote access, the repository includes a draft authenticated container and Cloud Run Terraform starting point. It is intended to be directionally useful, not a validated production deployment. Operators own deployment, identity, data handling, cost, and operations.
Docs
| Topic | Link |
|---|---|
| Install and first commands | docs/getting-started.md |
| How it works | docs/how-it-works.md |
| MCP and agents | docs/mcp.md, agents/ |
| Full docs index | docs/README.md |
| Roadmap | ROADMAP.md · docs/roadmap.md · docs/strategic-gap-audit.md |
| Changelog | CHANGELOG.md |
| Security | SECURITY.md · docs/security.md |
Research and publication pointers (maintainer track, not the product core): docs/submission-freeze-checklist.md, validation/2026-06-30-submission-freeze-local-proof.md, docs/public-label-snapshot-decision.md (public lists as robustness checks rather than population rates), and docs/m365-tenancy-decision.md.
Development
uv sync
uv run pre-commit install
uv run python scripts/release_readiness.py --allow-dirty
uv run python scripts/check.py
uv run python scripts/check.py is the canonical local gate: lint, type
checks, coverage-gated tests, generated-artifact and catalog checks, text and
link hygiene, interface and claim checks, and size and complexity ratchets.
Green locally means green in CI.
Project hygiene: keep examples reserved and synthetic, keep validation artifacts aggregate-only, and avoid dead code or placeholders. See CONTRIBUTING.md.
License
Apache 2.0. Free to use, build on, fork, and share. See LICENSE for the full terms.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file recon_tool-2.10.2.tar.gz.
File metadata
- Download URL: recon_tool-2.10.2.tar.gz
- Upload date:
- Size: 2.9 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
453af77370d0ab71f7582a61f5ca5980415c2847d02b4c798de1ec338d7c2a7a
|
|
| MD5 |
38378871248737aabf23410fa7eca510
|
|
| BLAKE2b-256 |
92a07febbb31d8a4b86275eb0002efe2bf5d085a62365287e1a26caa0d83cbdc
|
Provenance
The following attestation bundles were made for recon_tool-2.10.2.tar.gz:
Publisher:
release.yml on blisspixel/recon
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
recon_tool-2.10.2.tar.gz -
Subject digest:
453af77370d0ab71f7582a61f5ca5980415c2847d02b4c798de1ec338d7c2a7a - Sigstore transparency entry: 2341148826
- Sigstore integration time:
-
Permalink:
blisspixel/recon@4f1f9c0685c32c8dff0b9b6a2e1dca8a27ea9dc7 -
Branch / Tag:
refs/tags/v2.10.2 - Owner: https://github.com/blisspixel
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4f1f9c0685c32c8dff0b9b6a2e1dca8a27ea9dc7 -
Trigger Event:
push
-
Statement type:
File details
Details for the file recon_tool-2.10.2-py3-none-any.whl.
File metadata
- Download URL: recon_tool-2.10.2-py3-none-any.whl
- Upload date:
- Size: 738.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e35d453cb19bb3b123fb951fd507e44a4caa71c48b98a3d2a3cf228b899095de
|
|
| MD5 |
dd9d90f65fe86732ffb38d5da7de8758
|
|
| BLAKE2b-256 |
8524c8c54b5b0b8daffa42125e93ad77da2beda3abb8c0df98bc85512d89d5c4
|
Provenance
The following attestation bundles were made for recon_tool-2.10.2-py3-none-any.whl:
Publisher:
release.yml on blisspixel/recon
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
recon_tool-2.10.2-py3-none-any.whl -
Subject digest:
e35d453cb19bb3b123fb951fd507e44a4caa71c48b98a3d2a3cf228b899095de - Sigstore transparency entry: 2341148829
- Sigstore integration time:
-
Permalink:
blisspixel/recon@4f1f9c0685c32c8dff0b9b6a2e1dca8a27ea9dc7 -
Branch / Tag:
refs/tags/v2.10.2 - Owner: https://github.com/blisspixel
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4f1f9c0685c32c8dff0b9b6a2e1dca8a27ea9dc7 -
Trigger Event:
push
-
Statement type:
