{"id":45369492,"url":"https://github.com/nerdlem/czdstool","last_synced_at":"2026-02-21T15:22:55.355Z","repository":{"id":57553953,"uuid":"187316338","full_name":"nerdlem/czdstool","owner":"nerdlem","description":"Command line tool to interact with ICANN CZDS REST API","archived":false,"fork":false,"pushed_at":"2025-06-30T15:53:26.000Z","size":45,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-30T16:48:52.868Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nerdlem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-05-18T05:01:10.000Z","updated_at":"2025-06-30T15:53:29.000Z","dependencies_parsed_at":"2025-07-01T16:33:47.260Z","dependency_job_id":null,"html_url":"https://github.com/nerdlem/czdstool","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nerdlem/czdstool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdlem%2Fczdstool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdlem%2Fczdstool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdlem%2Fczdstool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdlem%2Fczdstool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nerdlem","download_url":"https://codeload.github.com/nerdlem/czdstool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdlem%2Fczdstool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29684420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T14:31:22.911Z","status":"ssl_error","status_checked_at":"2026-02-21T14:31:22.570Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-21T15:22:52.999Z","updated_at":"2026-02-21T15:22:55.347Z","avatar_url":"https://github.com/nerdlem.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GoDoc](https://godoc.org/github.com/nerdlem/czdstool?status.svg)](https://godoc.org/github.com/nerdlem/czdstool)\n[![Go Report Card](https://goreportcard.com/badge/github.com/nerdlem/czdstool)](https://goreportcard.com/report/github.com/nerdlem/czdstool)\n[![Build Status](https://travis-ci.org/nerdlem/czdstool.svg?branch=master)](https://travis-ci.org/nerdlem/czdstool)\n\n# czdstool, command line interface to the ICANN CZDS REST API\n\n[ICANN](https://icann.org) provides public access to thousands of TLD zone files through the [Centralized Zone Data System — CZDS](https://czds.icann.org) using an [HTTP REST API](https://github.com/icann/czds-api-client-java/blob/master/docs/ICANN_CZDS_api.pdf).\n\nIn order to use this tool, you'll need to access the CZDS system and complete your registration to get your access credentials.\n\n## Installation\n\nThis should be a matter of\n\n```\ngo install github.com/nerdlem/czdstool@latest\n```\n\n## Configuration\n\nThe shipped [sample configuration](https://github.com/nerdlem/czdstool/blob/master/czds.toml-example) only needs you to put your username and password. Keep that file safe — mind your file permissions — to prevent misuse.\n\n## Logging in\n\nThe REST API uses JWT for authentication. JWTs are cryptographically signed _blobs_ that include authorization information. To prevent brute forcing attacks, the authentication API that provides the JWT tokens is subjected to aggressive rte limiting.\n\n`czdstool` can store the JWTs in a local file, so you can authenticate once and keep issuing commands for up to 24 hours. To have `czdstool` authenticate itself and save the JWT to a file, issue the following command:\n\n```\nczdstool --config my-config.toml save ./my-token.jwt\n```\n\nIf all went well, the file `my-token.jwt` should now contain a JWT token that allows you to access the CZDS via the REST API.\n\nTo use the saved JWT for authentication, remember to add the `--auth-file` command line option.\n\n## Help\n\nTo get help about the tool, use either the `help` or `--help` commands as follows:\n\n```\n$ czdstool --help\n\nUtility program to use the ICANN CZDS REST API to download authorized\nTLD zone files.\n\nUsage:\n  czdstool [flags]\n  czdstool [command]\n\nAvailable Commands:\n  fetch       Download TLD zone files using the ICANN CZDS REST API\n  help        Help about any command\n  ls          List available TLD zone URLs in the ICANN CZDS\n  save        Persist authorization ICANN CZDS authorization token for later reuse\n\nFlags:\n  -A, --auth-file string   auth file previously created with save\n      --config string      config file (default is /etc/czds.toml)\n  -h, --help               help for czdstool\n  -T, --tlds string        comma-separated list of TLDs to download\n  -v, --verbose            verbose output format\n\nUse \"czdstool [command] --help\" for more information about a command.\n```\n\n## Listing TLDs you have access to\n\nUse the `ls` sub-command, as below. I'm also using the `-l` option to get some additional information about the TLD file:\n\n```\n$ czdstool ls --auth-file ./czds.ticket -l link\n{\"name\":\"link\",\"last_modified\":\"2019-05-18T00:57:45Z\",\"content_length\":11766449,\"content_type\":\"application/x-gzip\"}\n```\n\nIssuing the `ls` commands with no additional arguments will simply list _all_ the TLDs you have available. This can be useful to keep track on access authorizations as they are revoked or expire automatically.\n\n## Retrieving TLD zone files\n\nThis is done via the `fetch` command. The following example downloads a TLD file to the `./samples/` directory:\n\n```\n$ czdstool fetch --destination-dir ./samples/ --verbose sexy\nRequesting auth token using credentials\nRequest is authorized\nprocessing list of TLDs provided\nlooking up data for https://czds-api.icann.org/czds/downloads/sexy.zone\nstat() ./samples//sexy.gz: stat ./samples//sexy.gz: no such file or directory\nwill fetch ./samples//sexy.gz via https://czds-api.icann.org/czds/downloads/sexy.zone\n```\n\nSince the `--auth-file` was not used, this command actually authenticated to the API and used a brand new JWT — which was discarded after use — for this transaction. The `--verbose` option causes additional output detailing what's happening.\n\nIf no TLDs are given to the `fetch` command, then all available TLD zones will be downloaded.\n\nBy default, only zone files that are older than the last-modified time provided by the REST API will be downloaded. The `--force` cancels this behavior and forces downloading the zone file regardless of local state.\n\nAs zone files are downloaded, their final size is compared with the length reported by the REST API, with an error being reported otherwise and the in-progress download being deleted. This behavior can be overridden with the `--keep-anyway` option.\n\nDownloads happen atomically _ala_ `rsync`. Files are downloaded to a temporary location and, if the size check passes, are then renamed to the final intended name.\n\n## Parallel access to the CZDS REST API\n\nThe option `--info-workers` and `--fetch-workers` control the number of concurrent `HEAD` and `GET` requests used to access the zone file data.\n\n## Requesting access to tlds\n\nThe `request` command automatically requests access to the TLDs provided in the command line.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdlem%2Fczdstool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnerdlem%2Fczdstool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdlem%2Fczdstool/lists"}