czds

- ICANN Centralized Zone Data Service Tool
git clone git://git.acid.vegas/czds.git
PKG-INFO (7034B)
      1 Metadata-Version: 2.2
      2 Name: czds-api
      3 Version: 1.2.1
      4 Summary: ICANN API for the Centralized Zones Data Service
      5 Home-page: https://github.com/acidvegas/czds
      6 Author: acidvegas
      7 Author-email: acid.vegas@acid.vegas
      8 Project-URL: Bug Tracker, https://github.com/acidvegas/czds/issues
      9 Project-URL: Documentation, https://github.com/acidvegas/czds#readme
     10 Project-URL: Source Code, https://github.com/acidvegas/czds
     11 Classifier: Development Status :: 5 - Production/Stable
     12 Classifier: Intended Audience :: Developers
     13 Classifier: License :: OSI Approved :: ISC License (ISCL)
     14 Classifier: Operating System :: OS Independent
     15 Classifier: Programming Language :: Python :: 3
     16 Classifier: Programming Language :: Python :: 3.6
     17 Classifier: Programming Language :: Python :: 3.7
     18 Classifier: Programming Language :: Python :: 3.8
     19 Classifier: Programming Language :: Python :: 3.9
     20 Classifier: Programming Language :: Python :: 3.10
     21 Classifier: Programming Language :: Python :: 3.11
     22 Classifier: Topic :: Internet
     23 Classifier: Topic :: Security
     24 Classifier: Topic :: Software Development :: Libraries :: Python Modules
     25 Requires-Python: >=3.6
     26 Description-Content-Type: text/markdown
     27 License-File: LICENSE
     28 Requires-Dist: aiohttp>=3.8.0
     29 Requires-Dist: aiofiles>=23.2.1
     30 Dynamic: author
     31 Dynamic: author-email
     32 Dynamic: classifier
     33 Dynamic: description
     34 Dynamic: description-content-type
     35 Dynamic: home-page
     36 Dynamic: project-url
     37 Dynamic: requires-dist
     38 Dynamic: requires-python
     39 Dynamic: summary
     40 
     41 # ICANN Centralized Zone Data Service API
     42 
     43 The [ICANN Centralized Zone Data Service](https://czds.icann.org) *(CZDS)* allows *approved* users to request and download DNS zone files in bulk, provided they represent a legitimate company or academic institution and their intended use is legal and ethical. Once ICANN approves the request, this tool streamlines the retrieval of extensive domain name system data, facilitating research and security analysis in the realm of internet infrastructure.
     44 
     45 ## Features
     46 * Asynchronous downloads with configurable concurrency
     47 * Support for both CSV and JSON report formats
     48 * Optional gzip decompression of zone files
     49 * Environment variable support for credentials
     50 * Comprehensive error handling and logging
     51 
     52 ## Zone Information
     53 Zone files are updated once every 24 hours, specifically from 00:00 UTC to 06:00 UTC. Access to these zones is granted in increments, and the total time for approval across all zones may extend to a month or longer. It is typical for more than 90% of requested zones to receive approval. Access to certain zone files may require additional application forms with the TLD organization. Please be aware that access to certain zones is time-bound, expiring at the beginning of the following year, or up to a decade after the initial approval has been confirmed.
     54 
     55 At the time of writing this repository, the CZDS offers access to 1,151 zones in total.
     56 
     57 1,079 have been approved, 55 are still pending *(after 3 months)*, 10 have been revoked because the TLDs are longer active, and 6 have been denied. Zones that have expired automatically had the expiration extended for me without doing anything, aside from 13 zones that remained expired. I have included a recent [stats file](./extras/stats.csv) directly from my ICANN account.
     58 
     59 ## Installation
     60 ```bash
     61 pip install czds-api
     62 ```
     63 
     64 ## Usage
     65 ### Command Line Interface
     66 ```bash
     67 czds [-h] [-u USERNAME] [-p PASSWORD] [-z] [-c CONCURRENCY] [-d] [-k] [-r] [-s] [-f {csv,json}] [-o OUTPUT]
     68 ```
     69 
     70 #### Arguments
     71 | Argument              | Description                                  | Default           |
     72 |-----------------------|----------------------------------------------|-------------------|
     73 | `-h`, `--help`        | Show help message and exit                   |                   |
     74 | `-u`, `--username`    | ICANN Username                               | `$CZDS_USER`      |
     75 | `-p`, `--password`    | ICANN Password                               | `$CZDS_PASS`      |
     76 | `-z`, `--zones`       | Download zone files                          |                   |
     77 | `-c`, `--concurrency` | Number of concurrent downloads               | `3`               |
     78 | `-d`, `--decompress`  | Decompress zone files after download         |                   |
     79 | `-k`, `--keep`        | Keep original gzip files after decompression |                   |
     80 | `-r`, `--report`      | Download the zone stats report               |                   |
     81 | `-s`, `--scrub`       | Scrub username from the report               |                   |
     82 | `-f`, `--format`      | Report output format (csv/json)              | `csv`             |
     83 | `-o`, `--output`      | Output directory                             | Current directory |
     84 
     85 ### Environment Variables
     86 ```bash
     87 export CZDS_USER='your_username'
     88 export CZDS_PASS='your_password'
     89 ```
     90 
     91 ### Python Module
     92 ```python
     93 import os
     94 from czds import CZDS
     95 
     96 async with CZDS(username, password) as client:
     97     # Download zone stats report
     98     await client.get_report('report.csv', scrub=True, format='json')
     99     
    100     # Download zone files
    101     zone_links = await client.fetch_zone_links()
    102     await client.download_zones(zone_links, 'zones', concurrency=3, decompress=True)
    103 ```
    104 
    105 ## Zone Information
    106 Zone files are updated once every 24 hours, specifically from 00:00 UTC to 06:00 UTC. Access to these zones is granted in increments, and the total time for approval across all zones may extend to a month or longer. It is typical for more than 90% of requested zones to receive approval. Access to certain zone files may require additional application forms with the TLD organization. Please be aware that access to certain zones is time-bound, expiring at the beginning of the following year, or up to a decade after the initial approval has been confirmed.
    107 
    108 At the time of writing this repository, the CZDS offers access to 1,151 zones in total.
    109 
    110 1,079 have been approved, 55 are still pending *(after 3 months)*, 10 have been revoked because the TLDs are longer active, and 6 have been denied. Zones that have expired automatically had the expiration extended for me without doing anything, aside from 13 zones that remained expired. I have included a recent [stats file](./extras/stats.csv) directly from my ICANN account.
    111 
    112 ## Respects & extras
    113 While ICANN does have an official [czds-api-client-python](https://github.com/icann/czds-api-client-python) repository, I rewrote it from scratch to be more streamline & included a [POSIX version](./extras/czds) for portability. There is some [official documentation](https://raw.githubusercontent.com/icann/czds-api-client-java/master/docs/ICANN_CZDS_api.pdf) that was referenced in the creation of the POSIX version. Either way, big props to ICANN for allowing me to use the CZDS for research purposes!
    114 
    115 ___
    116 
    117 ###### Mirrors for this repository: [acid.vegas](https://git.acid.vegas/czds) • [SuperNETs](https://git.supernets.org/acidvegas/czds) • [GitHub](https://github.com/acidvegas/czds) • [GitLab](https://gitlab.com/acidvegas/czds) • [Codeberg](https://codeberg.org/acidvegas/czds)