Skip to main content

Teardown Tool

Passive web-app architecture reconnaissance with subdomain fan-out. It collects public frontend signals and writes a versioned JSON record for agents plus a vault-compatible Markdown report for people. Collection is deterministic; interpretation belongs to the agent reading the JSON.

Passive recon only. No authenticated access, no exploitation. Active DNS brute-force is opt-in (--active-dns) and off by default.

Run with uvx (no install)

# Once published to PyPI:
uvx tech-teardown example.com --single

# Straight from the repo (works today):
uvx --from git+https://github.com/ReyemTech/teardown teardown example.com --single

The PyPI distribution is tech-teardown; it provides both tech-teardown and teardown as CLI commands. uvx builds an ephemeral environment and runs it — nothing to install. For the active-DNS extra: uvx --with dnspython --from git+https://github.com/ReyemTech/teardown teardown example.com --active-dns.

Releases are automatic on main: Conventional Commits determine the next version, and GitHub Actions publishes through PyPI trusted publishing. See PUBLISHING.md.

Local dev install

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[active-dns,mcp]'
.venv/bin/teardown example.com --single

dnspython handles bounded DNS lookups for network attribution. The wordlist enumeration path remains opt-in with --active-dns.

Usage

# Single host, no subdomain enumeration
teardown example.com --single

# Full: enumerate via crt.sh, CertSpotter and Wayback; check up to 100 hosts
teardown example.com

# Show each host, or each module and liveness probe
teardown example.com -v
teardown example.com -vv

# Limit liveness checks and host teardowns separately
teardown example.com --max-probes 40 --max-hosts 10

# Add installed subfinder's passive sources
teardown example.com --subfinder

# Opt in to active DNS brute-force
teardown example.com --active-dns --wordlist words.txt

# Machine output on stdout (no report files; scan still saved to history)
teardown example.com --single --json-only

# See earlier scans and compare the newest scan with one from at least 7 days ago
teardown history example.com
teardown compare example.com --days 7

# Compare two saved JSON scans
teardown diff last-month.json this-month.json

# Fetch and convert the optional community fingerprint database
teardown fingerprints update

Flags

Flag Default Meaning
--single off Scan only the given host; skip enumeration.
--active-dns off Add DNS brute-force (needs dnspython).
--subfinder off Merge installed subfinder's passive results.
--wordlist PATH built-in Wordlist for --active-dns.
--max-hosts N 25 Cap live hosts torn down (0 = no cap).
--max-probes N 100 Cap enumerated hosts checked for liveness (0 = no cap).
--concurrency N 10 Max concurrent requests.
--rate R 8.0 Global requests/sec cap.
--out-dir DIR ~/.teardown/reports/DOMAIN/ Where JSON + markdown land.
--name NAME domain + timestamp + ID Output basename.
--json-only off Print JSON to stdout; skip report files.
--data-dir DIR ~/.teardown/ Home for reports, cache, and SQLite history. TEARDOWN_HOME also works.
--cache-dir DIR ~/.teardown/cache/ Daily response cache location.
--no-cache off Fetch fresh responses.
--no-history off Do not save the scan to SQLite history.
--no-artifacts off Do not retain sanitized first-party bundle and source-map copies.
-q, --quiet off Suppress terminal status.
-v, -vv off Show per-host or per-module progress.
--no-color off Disable terminal colors.

Output

Two files per scan under ~/.teardown/reports/DOMAIN/: a timestamped <name>-teardown.json (machine, versioned schema) and <name>-teardown.md (vault-ready, matches the existing teardown frontmatter). Each run gets a unique basename, so earlier reports remain available. Set --out-dir to place them elsewhere. Scan status and progress go to stderr; --json-only keeps stdout parseable JSON.

Completed scans and per-host checkpoints are saved in ~/.teardown/history.sqlite3. teardown history DOMAIN lists runs, including interrupted scans and their checkpoint counts. teardown compare DOMAIN diffs the newest completed run against the preceding completed run; --days 7 selects the newest completed baseline at least seven days older. Add --json to either command for machine output. --json-only scans are saved too; use --no-history to opt out. The data home is private to the local user on Unix.

When a first-party JavaScript bundle exposes a valid source map, teardown saves sanitized copies of the generated JavaScript and map under ~/.teardown/artifacts/ (or --data-dir DIR/artifacts/). Files are content addressed, limited to 4 MB each, and private to the local user on Unix. The JSON bundle record and Markdown report include local paths, SHA-256 hashes, and the map's source count. Embedded sourcesContent stays in the saved map for inspection, with recognizable credentials redacted. If a copy is too large or cannot pass the secret check, the public evidence URL remains in the report. Use --no-artifacts to disable saved copies. Treat saved files as potentially sensitive code and inspect them locally.

The Markdown report begins with a deterministic TL;DR of observed hosts, hosting/routing providers, frameworks and finding counts. Its final To Do list groups actionable findings across hosts and cites their evidence URLs. A source map task asks for review; exposure alone does not establish a vulnerability.

The JSON is the contract an agent reads — one HostTeardown record per host inside a ScanResult rollup. Shapes are defined in teardown/models.py (SCHEMA_VERSION). An agent should consume the JSON and narrate; the markdown is for humans.

Schema 1.2 added detections per host, aggregate.detections_union, and namespaced extensions for additional scan modules. Each detection record has a technology name, categories, deterministic confidence (0–100), and signal labels in evidence. Confidence reflects matched signal strength and corroboration; it is not a statistically calibrated probability. The legacy frameworks and cms views remain. http now includes page title, redirect status chain, observed TLS version/cipher/certificate expiry and CDN header fingerprint when available. teardown diff reports added and removed hosts plus field changes; scan times and volatile response headers are excluded.

Schema 1.3 adds network per host: the observed A/AAAA addresses and CNAME chain, the routed prefix and originating ASN(s) reported by RIPE RIS, and public network registration names from RIR WHOIS. network.observation is cdn_edge, observed_endpoint, or unknown; it never claims to find the application origin. DNS answers can vary by resolver and may differ from the address used by the HTTP connection. A registered network holder may be an infrastructure provider rather than the app operator. The scan limits DNS collection to eight addresses and eight CNAME hops per host. These fields are saved in SQLite history and appear in teardown compare automatically. (RIPE network info, RIPE WHOIS)

Schema 1.4 adds optional network.addresses[].geo: a Geo-IP country code, city when known, coordinates when meaningful, source, and data timestamp. This is an approximate database estimate for the observed IP. For a CDN it describes a possible edge location, not the site origin; coordinates are not a precise server location. Unknown results remain empty. The lookup uses the same bounded client and daily cache as other network evidence.

Schema 1.5 adds network.providers with evidence from known provider-owned CNAME targets and adds saved artifact references to first-party bundles with exposed maps. For example, *.onporter.run identifies Porter, *.elb.us-east-1.amazonaws.com identifies AWS Elastic Load Balancing, and *.onrender.com identifies Render. An ELB address alone does not establish Elastic Beanstalk. A Cloudflare CDN hop is shown separately from a platform hop; neither proves an origin IP. Provider rules are in teardown/data/cname_providers.json.

Schema 1.6 adds bundles[].source_map_intel for exposed first-party maps. It inventories original source paths, distinguishes embedded source content from path-only maps, and identifies dependency versus application paths. When an embedded source contains a JSON-formatted OpenAPI object, the JSON and Markdown report list its path templates, HTTP methods, and component schemas. The Markdown appendix includes up to 200 source paths and 200 API paths per map, with an omission count above either cap. Raw source text and credential values are not copied into the report. The local sanitized map artifact remains available for deeper inspection.

These API paths are references in shipped frontend code, not verified live endpoints. Teardown does not send requests to all referenced paths or execute the described POST/PUT/PATCH/DELETE operations. Even a GET can have side effects in a poorly designed application. The passive inventory does not prove missing authorization, an exploitable vulnerability, or a package CVE. The appendix links to OWASP WSTG-INFO-05 and WSTG-APIT-03 as review guidance.

This product includes GeoLite Data created by MaxMind, available from https://www.maxmind.com. GeoLite2 data is accessed through the RIPEstat MaxMind GeoLite endpoint.

The wheel bundles 589 MIT-licensed fingerprints (588 from OpenTechAlyzer plus the Livewire definition). teardown fingerprints update downloads and converts the larger WebAppAnalyzer database automatically into the user's local cache. That optional dataset is GPL-3.0 and is not distributed with this repository or wheel. Set TEARDOWN_FINGERPRINT_DB to choose its local path. Imported definitions update bundled names; the local curated definitions take final precedence. Attribution is in teardown/data/LICENSE.md.

MCP server

Install the optional extra, then use stdio or local Streamable HTTP:

.venv/bin/python -m pip install -e '.[mcp]'
teardown-mcp
teardown-mcp --transport http --host 127.0.0.1 --port 8000
teardown-mcp --no-history
teardown-mcp --no-artifacts

The HTTP endpoint is http://127.0.0.1:8000/mcp. The tools are teardown_host, teardown_domain, enumerate_subdomains, scan_domain (compatibility alias), and diff_scans (two JSON objects). They reuse the CLI collection path. The default bind address is loopback. See .mcp.json.example for a stdio registration example. MCP scan tools save to the same SQLite history by default. Start the server with --no-history to disable this or --data-dir DIR to use another data home. Artifact saving follows the CLI default and can be disabled at MCP startup with --no-artifacts.

How collection behaves

  • The registrable root domain comes from a bundled public suffix list, so a target such as app.example.co.uk enumerates example.co.uk. This does not fetch the suffix list during a scan. Private suffixes are respected, so app.foo.github.io stays within the foo.github.io tenant.
  • The scan fetches only hosts under that root, plus crt.sh, CertSpotter and Wayback for passive enumeration. It stops at redirects outside that scope. Third-party asset URLs may appear in the result, but their bodies are not fetched.
  • Liveness checks stop after --max-probes candidates. The 25-host teardown cap applies after liveness checks. The liveness response is reused for collection. Each HTTP response body is limited to 8 MB.
  • GET responses are cached by URL and UTC day under ~/.teardown/cache/ so a rerun resumes without repeating successful requests. Bodies mentioning sensitive concepts, containing long opaque values, or matching recognized secret patterns are not persisted. The cache keeps only cookie names, never cookie values.
  • API paths count as observed only when their responses support the claim: REST requires JSON or an access-denied status; GraphQL requires a GraphQL-shaped response; OpenAPI requires a version marker and paths object. A generic HTML fallback does not count. A source map must parse as a v3 source map.
  • Extracted keys are stored as prefixes, credential-bearing headers are redacted, and sensitive URL query values are masked in output. Inspect the JSON before sharing it: public pages can contain identifiers outside these recognized patterns. Assets with credential-bearing query parameters are listed with masked URLs and may not be fetchable for bundle enrichment.

Architecture

teardown/
  models.py       # versioned dataclasses — the contract
  http_client.py  # polite async httpx client + Fetcher protocol
  safety.py       # output redaction + request scope checks
  fingerprints.py # database matcher + optional WebAppAnalyzer importer
  scan_modules.py # ordered, injectable host scan modules
  cache.py        # sanitized daily response cache
  network.py      # DNS, routed-prefix and registration attribution
  history.py      # SQLite scan history and host checkpoints
  terminal.py     # styled stderr progress and history tables
  collectors/
    headers.py    # headers + CSP
    html_js.py    # CMS details, bundles, third-parties, secret leaks
    api_discovery.py  # REST / GraphQL / OpenAPI / WordPress probes
  enumerate.py    # passive source adapters + optional DNS/subfinder + liveness
  diff.py         # normalized cross-run comparison
  mcp_server.py   # optional stdio / Streamable HTTP server
  analyze.py      # signals -> OPSEC findings + cross-host aggregate
  render.py       # JSON writer + vault markdown
  cli.py          # argparse + asyncio orchestration

Collectors take an injected Fetcher so they unit-test with a fake, no network. Design notes: docs/design.md.

Adding a scan module

Built-in host scans run as named modules over the same fetched response and injected Fetcher. To add a collector in Python, register it before calling run_scan in the same process:

from teardown.scan_modules import ScanModule, register_module

async def collect(context):
    # Use context.fetcher for any bounded, in-scope request.
    return {"public_marker": "observed"}

register_module(ScanModule("example", collect))

The returned mapping appears at hosts[].extensions.example in the JSON. Modules run independently, so one collector's error does not stop later ones. For a built-in addition, add the module to scan_modules.py; use run_scan(..., modules=[...]) to select modules for one scan. Keep module payloads deterministic and redact secret values before returning them.

Tests

.venv/bin/python -m pytest -q    # offline

Notes & gotchas

  • crt.sh is flaky — it intermittently returns a 404/HTML error page. The enumerator retries (with backoff) and falls back to the bare-domain query form.
  • Source-map findings are first-party only. A third-party CDN (Sentry, jsdelivr) publishing maps for its own SDK is not the target's exposure, so those are skipped; first-party maps are flagged MEDIUM (info disclosure, not a credential leak).
  • Secrets are redacted at collection and output boundaries. Third-party keys keep only a prefix, and sensitive headers and URL query values are masked.
  • Astro is matched from /_astro/ JS and stylesheet URLs as well as its page markers. Hosting labels follow current response evidence; a prior Cloudflare result does not carry forward when a host now identifies Fastly or GitHub Pages.

Metadata

Release files for tech-teardown 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tech-teardown 0.6.0
File Size Uploaded Provenance Actions
tech_teardown-0.6.0.tar.gz 129.8 kB Without provenance Details for tech_teardown-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tech-teardown 0.6.0
File Interpreter ABI Platform Actions
tech_teardown-0.6.0-py3-none-any.whl Python 3 none any Details for tech_teardown-0.6.0-py3-none-any.whl

Total release size: 225.6 kB

Release files / tech_teardown-0.6.0.tar.gz

Download URL tech_teardown-0.6.0.tar.gz
Size 129.8 kB
Tags Source
SHA-256 checksum
How to use checksums
7be8dd5a7cbd152d46e67c0091db5e742dc256a678118d66868d8c8ea0dc8cbb
BLAKE2b-256 checksum
How to use checksums
fd4867d122ddc91cc01296398b60ecf88853a89308278c68cf8d6e3841c94472
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / tech_teardown-0.6.0-py3-none-any.whl

Download URL tech_teardown-0.6.0-py3-none-any.whl
Size 95.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9a2bd960d584807e982156d1dfaa19256a8132c7e45c8faa0d6a23f69ac3aaec
BLAKE2b-256 checksum
How to use checksums
d35726d1e026ebc73f5ca76702521d578756898f21fdea5b3461732542125be1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for tech-teardown 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page