Metadata-Version: 2.4
Name: cyberatlas-finder
Version: 0.1.0
Summary: Python client & CLI for the CyberAtlas Finder API — passive subdomain enumeration across 3B+ domains (certificate transparency + DNS), no brute force.
Author: CyberAtlas
License: MIT
Project-URL: Homepage, https://cyberatlas.ai/finder
Project-URL: Documentation, https://cyberatlas.ai/finder/about
Project-URL: Repository, https://github.com/CyberAtlas-ai/finder
Project-URL: Issues, https://github.com/CyberAtlas-ai/finder/issues
Keywords: subdomain enumeration,subdomain finder,subdomain discovery,attack surface,attack surface management,asm,osint,passive dns,certificate transparency,reconnaissance,recon,bug bounty,dns,cyberatlas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: license-file

# cyberatlas-finder

Python client & CLI for **[CyberAtlas Finder](https://cyberatlas.ai/finder)** — passive subdomain enumeration across **~3B domain names** (certificate transparency + DNS, no brute force). Wildcard patterns, exact counts, one API call.

![CyberAtlas Finder](docs/finder.png)

## Install

```bash
pip install cyberatlas-finder
```

## Quickstart

```python
from cyberatlas_finder import Finder

finder = Finder()                          # anonymous — no key needed
print(finder.count("*.gitlab.*"))          # total "gitlab" subdomains

for host in finder.iter_domains("*gitlab*.io", max_results=50_000):
    print(host)                            # paging handled for you

# more volume? Finder(api_key="ca_live_...") or set CYBERATLAS_API_KEY
```

## Patterns

| Pattern | Matches |
|---|---|
| `*.gitlab.*` | a label exactly `gitlab` |
| `gitlab*.io` | starts with `gitlab`, under `.io` |
| `*admin*.gov.uk` | `admin` substring, `.gov.uk` |
| `*.mit.edu` | subdomains of `mit.edu` |
| `mlflow` | bare substring (≥ 3 chars) |

## CLI

```bash
cyberatlas-finder "*.gitlab.*"                 # first page
cyberatlas-finder "*.gitlab.*" --count         # total only
cyberatlas-finder "*gitlab*.io" --all --json   # stream everything
```

## Limits

Free & anonymous: **60 req/min per IP · 2,000 lookups/day · 10B search operations/day**. An API key raises the limits — [cyberatlas.ai/finder](https://cyberatlas.ai/finder).

## Manual pagination

`iter_domains()` pages for you. To drive it yourself (e.g. checkpoint the cursor):

```python
cursor = None
while True:
    page = finder.search("*.gitlab.*", per_page=500, cursor=cursor)
    for host in page.domains:
        print(host)
    if not page.has_more:
        break
    cursor = page.next_cursor
```

## API

- `Finder(api_key=None, timeout=30, max_retries=3)`
- `.search(pattern, *, page, per_page, cursor, tld, live, full) -> SearchPage`
- `.count(pattern, **filters) -> int`
- `.iter_domains(pattern, *, per_page=500, max_results=None, **filters)`
- Errors: `AuthError`, `RateLimitError`, `QuotaExceeded`, `InvalidPattern`

MIT · a product of [cyberatlas.ai](https://cyberatlas.ai)
