Metadata-Version: 2.4
Name: recon-tool
Version: 2.17.13
Summary: Public-metadata domain intelligence CLI and MCP server using DNS, certificate transparency, and unauthenticated identity discovery.
Project-URL: Homepage, https://github.com/blisspixel/recon
Project-URL: Repository, https://github.com/blisspixel/recon
Project-URL: Changelog, https://github.com/blisspixel/recon/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/blisspixel/recon/issues
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: dns,domain-intelligence,mcp,osint,recon,saas-fingerprinting,security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: deal>=4.24.0
Requires-Dist: defusedxml>=0.7
Requires-Dist: dnspython>=2.6
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: publicsuffixlist>=1.0
Requires-Dist: python-multipart>=0.0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.24.1
Description-Content-Type: text/markdown

# recon

[![CI](https://github.com/blisspixel/recon/actions/workflows/ci.yml/badge.svg)](https://github.com/blisspixel/recon/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/recon-tool.svg?cacheSeconds=300)](https://pypi.org/project/recon-tool/)
[![Python](https://img.shields.io/pypi/pyversions/recon-tool.svg?cacheSeconds=300)](https://pypi.org/project/recon-tool/)
[![License](https://img.shields.io/pypi/l/recon-tool.svg?cacheSeconds=300)](https://github.com/blisspixel/recon/blob/main/LICENSE)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/blisspixel/recon/badge)](https://scorecard.dev/viewer/?uri=github.com/blisspixel/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. Lookup time depends on public-provider latency and whether certificate
transparency enrichment is enabled.

> **Defensive use only.** Posture review, vendor diligence, architecture
> review. See
> [docs/legal.md](https://github.com/blisspixel/recon/blob/main/docs/legal.md).

## Quick Start

Install and check the version offline:

```bash
uv tool install recon-tool    # or: pipx install recon-tool
recon --version               # offline check
```

Python 3.11 through 3.14, on Windows, macOS, or Linux. `recon doctor` tests
online connectivity to recon's public data sources.

Optional install helpers at `scripts/install.ps1` and `scripts/install.sh` drive
an existing `uv` or `pipx` installation. Download a
[release-tag source archive](https://github.com/blisspixel/recon/releases/latest),
review the helper locally, then run it: each installs the exact version
represented by that tag, preserves a sole existing owner, and refuses ambiguous
or unmanaged installations. Do not pipe mutable branch content into a shell. To
verify published artifacts first, follow the
[consumer verification recipe](https://github.com/blisspixel/recon/blob/main/docs/supply-chain.md#consumer-verification-quick-path).

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. See
[ADR-0011](https://github.com/blisspixel/recon/blob/main/docs/adr/0011-public-metadata-collection-boundary.md).

Run a real review by replacing the placeholder with the domain you want to
review:

```bash
recon "<domain-you-want-to-review>"
```

For a harmless syntax-only example, you can use `recon example.com`. Every
lookup is live. recon ships no offline demo mode, so reserved names such as
`example.com` return a panel of stray public residue from unrelated test
configurations, including a meaningless display name, at High confidence. It
shows the shape of the output, not a result about any organization.

A domain is a query coordinate, not proof of one organization or product: recon
reports observations, not verdicts. That is the caution to keep beside every row
the panel shows.

### Illustrated output (synthetic, not a captured run)

![Synthetic recon output in a modern Linux terminal](https://raw.githubusercontent.com/blisspixel/recon/main/docs/assets/terminal-demo.svg)

The panel above is **generated, not captured**:
[`scripts/generate_terminal_demo.py`](https://github.com/blisspixel/recon/blob/main/scripts/generate_terminal_demo.py)
drives recon's real formatter over a deterministic, no-network fixture for the
fictional Example Industries Ltd. It shows the *shape* of a full-signal
result, every row a rich target can fill, and no live lookup of reserved
`example.com` reproduces it. No real organization is depicted. Other project
fixtures use IETF reserved `.invalid` namespaces.

<!-- terminal-demo-transcript:start -->
<details>
<summary>Accessible text transcript</summary>

```text
demo@recon:~$ recon example.com    # synthetic fixture, not a captured run
Example Industries Ltd
example.com
──────────────────────────────────────────────────────────────────────────────
  Provider     Microsoft 365 + Proofpoint gateway
  Tenant       a1b2c3d4-e5f6-7890-abcd-ef1234567890 • NA
  Tenant domain example-industries.onmicrosoft.example.com
  Auth         Federated
  Confidence   ●●● High (4 sources)


Services
  Email            Microsoft 365, Proofpoint, DMARC reject, DKIM,
                   SPF strict, MTA-STS enforce
  Identity         Okta
  Cloud            Cloudflare (CDN/edge), AWS Route 53 (DNS)
  Security         Wiz Security
  Data & Analytics Snowflake, Datadog
  Collaboration    Slack, Atlassian (Jira/Confluence), GitHub, Zoom
                   Evidence roles: --explain


High-signal related domains
  login.example.com, support.example.com, status.example.com

Insights
  Federated identity observed; identity-vendor indicators: Okta
  Email security: observed controls: DMARC reject, DKIM, SPF strict, MTA-STS

```

</details>
<!-- terminal-demo-transcript:end -->

Install, update, uninstall, and first-run detail:
[docs/getting-started.md](https://github.com/blisspixel/recon/blob/main/docs/getting-started.md).

## Start with Your Workflow

| You are trying to | Start here | What you get |
|---|---|---|
| Review one namespace | `recon "<domain>"` | A compact, hedged panel of observed mail, identity, service, and confidence signals |
| Explain or hand off a finding | `recon "<domain>" --explain` | Per-source status plus the evidence retained for each material observation |
| Review an operator-supplied set | `recon batch domains.txt --json --include-ecosystem --summary --summary-schema 2.2` | One portfolio evidence bundle with ordered typed results and errors, observable ecosystem overlaps, and an aggregate cohort summary |
| Work through an agent | `recon mcp install --client=<name>` | Local typed tools, resources, and prompts without a hosted recon service |

Defenders can follow the
[evidence-first review workflow](https://github.com/blisspixel/recon/blob/main/docs/defender-workflow.md).
Consultants and analysts should treat every multi-domain set as operator
supplied: recon describes observable similarities and differences but does not
infer ownership, control, or a corporate relationship.

## 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](https://github.com/blisspixel/recon/blob/main/docs/limitations.md).
How to report a result without overstating it:
[docs/reporting-observations.md](https://github.com/blisspixel/recon/blob/main/docs/reporting-observations.md).

### Correlation without overclaiming

recon is designed around a harder question than record collection: when may
several incomplete public observations support one claim, and when must the
result stay unresolved? The
[correlation model](https://github.com/blisspixel/recon/blob/main/docs/correlation.md)
is the deeper design contract for that question. It separates observed facts,
deterministic deductions, and model-relative diagnostics; treats provenance and
abstention as first-class; and keeps ownership, causation, complete-inventory,
and unvalidated robustness claims outside the result.

v2.15 and v2.16 closed a five-round presentation-drift class. Independent
testers installed the published package, never read the source, and kept finding
the same issue: a decision applied to one renderer and not the others. The
current engine surface and core contracts are stable. Those findings and their
fixes are in
[CHANGELOG.md](https://github.com/blisspixel/recon/blob/main/CHANGELOG.md) and in
[ADR-0015](https://github.com/blisspixel/recon/blob/main/docs/adr/0015-role-split-vendor-claims-in-the-default-view.md)
through
[ADR-0017](https://github.com/blisspixel/recon/blob/main/docs/adr/0017-one-briefing-in-every-shape.md).

The living work is the fingerprint catalog. Vendors add, rename, and retire the
public patterns recon detects, so a rule with no re-check is a slow source of
false positives and negatives. Most useful contributions are one YAML file, not
code: a current vendor-documentation page (or a disclosure-safe aggregate
basis), a `verified` date, a fictional positive, and a lookalike negative.
[CONTRIBUTING.md](https://github.com/blisspixel/recon/blob/main/CONTRIBUTING.md)
has the schema, the validation command, and what is deliberately out of scope.
The freshness loop and its coverage floor live in
[docs/catalog-strategy.md](https://github.com/blisspixel/recon/blob/main/docs/catalog-strategy.md).

## Common Commands

```bash
recon example.com                              # default panel
recon example.com --explain                    # evidence trail
recon example.com --gaps                       # neutral hardening prompts
recon example.com --plain                      # panel as linear text (screen readers, grep)
recon example.com --plain --full               # every field, linear
recon example.com --json                       # structured record
recon example.com --explain-dag --explain-dag-format mermaid   # evidence DAG
recon batch domains.txt --json                 # batch JSON array
recon batch domains.txt --json --include-ecosystem --summary --summary-schema 2.2
                                                # portfolio evidence bundle
recon delta example.com                        # diff vs local cache
recon capsule capture example.com -o run.json  # caller-owned replay artifact
recon mcp install --client=cursor              # wire MCP into a client
```

More flags:
[docs/cli-surface.md](https://github.com/blisspixel/recon/blob/main/docs/cli-surface.md).
JSON contracts:
[schema](https://github.com/blisspixel/recon/blob/main/docs/schema.md) ·
[stability](https://github.com/blisspixel/recon/blob/main/docs/stability.md) ·
[operational contract](https://github.com/blisspixel/recon/blob/main/docs/operational-contract.md).

Versioned JSON remains recon's structured runtime contract. The
[Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
projection is deferred until a named consumer justifies the mapping. recon does
not emit OKF, and any future OKF view would be additive rather than a replacement
for JSON. Caller-owned JSON observation capsules are documented in
[docs/observation-capsules.md](https://github.com/blisspixel/recon/blob/main/docs/observation-capsules.md),
with the decision boundary in
[ADR-0014](https://github.com/blisspixel/recon/blob/main/docs/adr/0014-caller-owned-capsules-and-okf-deferral.md).

`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 (plugin / MCP / skill)

Wire recon into Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Kiro,
or any MCP-compatible client:

```bash
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](https://github.com/blisspixel/recon/blob/main/docs/mcp.md).
Per-client scaffolds and skills:
[agents/](https://github.com/blisspixel/recon/tree/main/agents).
The PyPI package installs the CLI and MCP runtime. Repository agent scaffolds
and plugin files are not included in the wheel or release assets.

The current scaffolds use each client's native configuration. In particular,
the source-checkout-only Claude Code plugin uses Claude Code's client-specific
layout; it does not claim conformance with the portable
[Agent Plugins v1.0.0 specification](https://agent-plugins.org/specification).
A complete-surface portable candidate now lives under
[`agents/agent-plugin/`](https://github.com/blisspixel/recon/tree/main/agents/agent-plugin)
and passes network-free validation against the exact pinned v1.0.0 schemas,
whose bytes still match the Published specification. That is not a client
compatibility or conformance claim. Representative-client evaluation remains
incomplete, so use `recon mcp install --client=<name>` as the released setup
path. The aggregate evaluation status and stop conditions are
[recorded here](https://github.com/blisspixel/recon/blob/main/validation/2026-08-20-agent-portability-cost-gate.md).

| You say | What the agent should do |
|---|---|
| "Recon example.com" | Call `lookup_tenant` (or `recon example.com`) and return the panel-style summary |
| "What does example.com 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 example.com and example.net" | `compare_postures` or two lookups side by side |
| "Any public hardening gaps?" | `find_hardening_gaps` after a lookup - hedged "Consider" notes only |

**Example chat.** This transcript uses the same synthetic Example Industries
fixture as the illustration above, so it shows the shape of a full-signal
answer rather than what a live `example.com` lookup returns:

> **You:** Recon example.com and tell me what you observe.
>
> **Agent:** Public evidence for `example.com` (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 and Route 53 infrastructure, Wiz, Snowflake,
>   Datadog, Slack, Atlassian, GitHub, and Zoom 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/](https://github.com/blisspixel/recon/tree/main/agents/claude-code/skills/recon/),
[AGENTS.md](https://github.com/blisspixel/recon/blob/main/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.

- [Optional cloud plan](https://github.com/blisspixel/recon/blob/main/docs/optional-cloud-deployment-plan.md)
- [Draft deployment framework](https://github.com/blisspixel/recon/tree/main/deploy)

## Docs

| Topic | Link |
|---|---|
| Glossary of recon's terms | [docs/glossary.md](https://github.com/blisspixel/recon/blob/main/docs/glossary.md) |
| Install and first commands | [docs/getting-started.md](https://github.com/blisspixel/recon/blob/main/docs/getting-started.md) |
| Reporting a result without overstating it | [docs/reporting-observations.md](https://github.com/blisspixel/recon/blob/main/docs/reporting-observations.md) |
| How it works | [docs/how-it-works.md](https://github.com/blisspixel/recon/blob/main/docs/how-it-works.md) |
| Known weak areas and conservative wording | [docs/weak-areas.md](https://github.com/blisspixel/recon/blob/main/docs/weak-areas.md) |
| Catalog growth and freshness loop | [docs/catalog-strategy.md](https://github.com/blisspixel/recon/blob/main/docs/catalog-strategy.md) |
| Observation capsules | [docs/observation-capsules.md](https://github.com/blisspixel/recon/blob/main/docs/observation-capsules.md) |
| Correlation model | [docs/correlation.md](https://github.com/blisspixel/recon/blob/main/docs/correlation.md) |
| MCP and agents | [docs/mcp.md](https://github.com/blisspixel/recon/blob/main/docs/mcp.md), [agents/](https://github.com/blisspixel/recon/tree/main/agents) |
| Full docs index | [docs/README.md](https://github.com/blisspixel/recon/blob/main/docs/README.md) |
| Roadmap | [ROADMAP.md](https://github.com/blisspixel/recon/blob/main/ROADMAP.md) · [docs/roadmap.md](https://github.com/blisspixel/recon/blob/main/docs/roadmap.md) · [docs/strategic-gap-audit.md](https://github.com/blisspixel/recon/blob/main/docs/strategic-gap-audit.md) |
| Changelog | [CHANGELOG.md](https://github.com/blisspixel/recon/blob/main/CHANGELOG.md) |
| Security | [SECURITY.md](https://github.com/blisspixel/recon/blob/main/SECURITY.md) · [docs/security.md](https://github.com/blisspixel/recon/blob/main/docs/security.md) |

Research and publication pointers (maintainer track, not the product core):
[docs/submission-freeze-checklist.md](https://github.com/blisspixel/recon/blob/main/docs/submission-freeze-checklist.md),
[validation/2026-06-30-submission-freeze-local-proof.md](https://github.com/blisspixel/recon/blob/main/validation/2026-06-30-submission-freeze-local-proof.md),
[docs/public-label-snapshot-decision.md](https://github.com/blisspixel/recon/blob/main/docs/public-label-snapshot-decision.md)
(public lists as robustness checks rather than population rates), and
[docs/m365-tenancy-decision.md](https://github.com/blisspixel/recon/blob/main/docs/m365-tenancy-decision.md).

## Development

Repository and release tasks use uv `0.11.17`. The broader
`>=0.11.8,<0.12` project constraint exists for dependency-update tooling, not
as the reproducible maintainer toolchain.

```bash
uv self update 0.11.17
uv --version                # must report uv 0.11.17
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.
It mirrors the blocking core CI gate; hosted scheduled and supply-chain
workflows remain separate checks.

Project hygiene: keep examples reserved and synthetic, keep validation artifacts
aggregate-only, and avoid dead code or placeholders. See
[CONTRIBUTING.md](https://github.com/blisspixel/recon/blob/main/CONTRIBUTING.md).

## License

Apache 2.0. Free to use, build on, fork, and share. See
[LICENSE](https://github.com/blisspixel/recon/blob/main/LICENSE) for
the full terms.
