czds

package module
v1.2.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2023 License: GPL-3.0 Imports: 20 Imported by: 0

README

CZDS

Go Report Card PkgGoDev CodeQL docker

A utility and golang library implementing a client to the CZDS REST API using both the documented and undocumented API endpoints

Should allow you to perform almost any action you can in the web interface via this API

CZDS-DL

Implements a client for the officially documented CZDS REST API

Download zone files from czds.icann.org in parallel
Features
  • Can be used as a standalone client or as an API for another client
  • Automatically refreshes authorization token if expired during download
  • Can save downloaded zones as named by Content-Disposition or URL name
  • Can compare local and remote files size and modification time to skip redownloading unchanged zones
  • Can download multiple zones in parallel
  • Docker image available
Usage
Usage of czds-dl:
  -exclude string
        don't fetch these zones
  -force
        force redownloading the zone even if it already exists on local disk with same size and modification date
  -out string
        path to save downloaded zones to (default ".")
  -parallel uint
        number of zones to download in parallel (default 5)
  -passin
        password source (default: prompt on tty; other options: cmd:command, env:var, file:path, keychain:name, lpass:name, op:name)
  -password string
        password to authenticate with
  -quiet
        suppress progress printing
  -redownload
        redownload zones that are newer on the remote server than local copy
  -retries uint
        max retry attempts per zone file download (default 3)
  -urlname
        use the filename from the url link as the saved filename instead of the file header
  -username string
        username to authenticate with
  -verbose
        enable verbose logging
  -version
        print version and exit
  -zone string
        comma separated list of zones to download, defaults to all
Example
$ ./czds-dl -out /zones -username "$USERNAME" -password "$PASSWORD" -verbose
2019/01/12 16:23:51 Authenticating to https://account-api.icann.org/api/authenticate
2019/01/12 16:23:52 'zones' does not exist, creating
2019/01/12 16:23:52 requesting download links
2019/01/12 16:23:54 received 5 zone links
2019/01/12 16:23:54 starting 5 parallel downloads
2019/01/12 16:23:54 downloading 'https://czds-api.icann.org/czds/downloads/example2.zone'
2019/01/12 16:23:54 downloading 'https://czds-api.icann.org/czds/downloads/example4.zone'
2019/01/12 16:23:54 downloading 'https://czds-api.icann.org/czds/downloads/example1.zone'
2019/01/12 16:23:54 downloading 'https://czds-api.icann.org/czds/downloads/example3.zone'
2019/01/12 16:23:54 downloading 'https://czds-api.icann.org/czds/downloads/example5.zone'

CZDS-REQUEST

Submit a new zone request or modify an existing CZDS request. Be sure to view and accept the terms and conditions with the -terms flag.

Usage
Usage of czds-request:
  -cancel string
        comma separated list of zones to cancel outstanding requests for
  -exclude string
        comma separated list of zones to exclude from request-all or extend-all
  -extend string
        comma separated list of zones to request extensions
  -extend-all
        extend all possible zones
  -passin
        password source (default: prompt on tty; other options: cmd:command, env:var, file:path, keychain:name, lpass:name, op:name)
  -password string
        password to authenticate with
  -reason string
        reason to request zone access
  -request string
        comma separated list of zones to request
  -request-all
        request all available zones
  -status
        print status of zones
  -terms
        print CZDS Terms & Conditions
  -username string
        username to authenticate with
  -verbose
        enable verbose logging
  -version
        print version and exit
Example

View zones able to be requested, prompting the user interactively for their password:

./czds-request -username "$USERNAME" -passin "tty" -status  | grep -v pending | grep -v approved
Password:

Request access to new zones, reading the user's password from the file ~/.czds.pass:

./czds-request -username "$USERNAME" -passin "file:~/.czds.pass" -request "red,blue,xyz" -reason "$REASON"

Request access to all zones:

./czds-request -username "$USERNAME" -passin "tty" -request-all -reason "$REASON"
Password:

CZDS-STATUS

View information about current zone file requests

Usage

By default czds-requests prints high-level information about all czds requests, like the reports page on czds. Detailed information about a particular zone can be displayed with the -zone or -id flag.

  -id string
        ID of specific zone request to lookup, defaults to printing all
  -passin
        password source (default: prompt on tty; other options: cmd:command, env:var, file:path, keychain:name, lpass:name, op:name)
  -password string
        password to authenticate with
  -report string
        filename to save report CSV to, '-' for stdout
  -username string
        username to authenticate with
  -verbose
        enable verbose logging
  -version
        print version and exit
  -zone string
        same as -id, but prints the request by zone name
Example

Show all requests:

$ ./czds-status -username "$USERNAME" -password "$PASSWORD"
TLD     ID      UnicodeTLD      Status  Created Updated Expires SFTP
xn--mxtq1m	e59839f1-d69d-4970-9a15-7b49f3592065	政府	Approved	Wed Jan 30 08:00:42 2019	Wed Jan 30 08:53:41 2019	Sat Jan 12 08:53:41 2030	false
aigo	c6886423-b67d-43b6-828f-9d5a6cb3e6a3	aigo	Pending	Wed Jan 30 08:00:41 2019	Wed Jan 30 08:01:38 2019		false
barclaycard	fa6d9c14-17ac-4b15-baf6-2d10g8e806fe	barclaycard	Pending	Wed Jan 30 08:00:41 2019	Wed Jan 30 08:01:38 2019		false
fans	977d8589-9cec-41ef-b62e-0d3f0cf863e0	fans	Pending	Wed Jan 30 08:00:41 2019	Wed Jan 30 08:01:38 2019		false
live	8c95ccae-ae4d-4028-8997-655b132f542d	live	Approved	Wed Jan 30 08:00:41 2019	Wed Jan 30 16:40:15 2019	Sat Jan 12 16:40:13 2030	false
onyourside	259aa66b-ac77-43db-a09a-9d3f57cf0e6b	onyourside	Pending	Wed Jan 30 08:00:41 2019	Wed Jan 30 08:02:16 2019		false
wtc	67f5b31d-19f0-4071-a176-25ff71f509f7	wtc	Pending	Wed Jan 30 08:00:41 2019	Wed Jan 30 08:02:55 2019		false
xn--d1acj3b	69929632-ed92-437a-b140-fff4b0d771a7	дети	Approved	Wed Jan 30 08:00:41 2019	Wed Jan 30 10:55:03 2019	Tue Apr 30 10:55:03 2019	false

Lookup specific request details:

$ ./czds-status -username "$USERNAME" -password "$PASSWORD" -zone red
ID:     a056b38d-0080-4097-95cb-014b35ed4cb7
TLD:    red (red)
Status: approved
Created:        Wed Jan 30 08:00:41 2019
Updated:        Thu Jan 31 20:51:22 2019
Expires:        Sun Jan 13 20:51:20 2030
Request IP:     123.456.789.123
FTP IPs:         []
Reason: ...
History:
        Wed Jan 30 08:00:41 2019        Request submitted
        Wed Jan 30 08:02:16 2019        Request status change to Pending
        Thu Jan 31 20:51:22 2019        Request status change to Approved

Building

Just run make! Building from source requires go >= 1.11 for module support

make

Docker

docker run --rm -v /path/to/zones/:/zones lanrat/czds czds-dl -out /zones -username "$USERNAME" -password "$PASSWORD"

Documentation

Overview

Package czds implementing a client to the CZDS REST API using both the documented and undocumented API endpoints

Index

Constants

View Source 
const (
	// AuthURL production url endpoint
	AuthURL = "https://account-api.icann.org/api/authenticate"
	// BaseURL production url endpoint
	BaseURL = "https://czds-api.icann.org"

	// TestAuthURL testing url endpoint
	TestAuthURL = "https://account-api-test.icann.org/api/authenticate"
	// TestBaseURL testing url endpoint
	TestBaseURL = "https://czds-api-test.icann.org"
)
View Source 
const (
	RequestAll       = ""
	RequestSubmitted = "Submitted"
	RequestPending   = "Pending"
	RequestApproved  = "Approved"
	RequestDenied    = "Denied"
	RequestRevoked   = "Revoked"
	RequestExpired   = "Expired"
	RequestCanceled  = "Canceled"
)

Filters for RequestsFilter.Status Statuses for RequestStatus.Status

View Source 
const (
	SortAsc  = "asc"
	SortDesc = "desc"
)

Filters for RequestsSort.Direction

View Source 
const (
	SortByTLD         = "tld"
	SortByStatus      = "status"
	SortByLastUpdated = "last_updated"
	SortByExpiration  = "expired"
	SortByCreated     = "created"
	SortByAutoRenew   = "auto_renew"
)

Filters for RequestsSort.Field

View Source 
const (
	StatusAvailable = "available"
	StatusSubmitted = "submitted"
	StatusPending   = "pending"
	StatusApproved  = "approved"
	StatusDenied    = "denied"
	StatusExpired   = "expired"
	StatusCanceled  = "canceled"
	StatusRevoked   = "revoked" // unverified
)

Status from TLDStatus.CurrentStatus and RequestsInfo.Status

Variables

This section is empty.

Functions

func Getpass added in v1.2.13 

func Getpass(passfrom ...string) (pass string, err error)

Getpass retrieves a password from the user using a method defined by the 'passfrom' string. The following methods are supported: 

cmd:command    Obtain the password by running the given command.
               The command will be passed to the shell for execution
               via "/bin/sh -c 'command'".

env:var        Obtain the password from the environment variable var.
               Since the environment of other processes may be visible
               via e.g. ps(1), this option should be used with caution.

file:pathname  The first line of pathname is the password.  pathname need
               not refer to a regular file: it could for example refer to
               a device or named pipe.  Note that standard Unix file
               access controls should be used to protect this file.

keychain:name  Use the security(1) utility to retrieve the
               password from the macOS keychain.

lpass:name     Use the LastPass command-line client lpass(1) to
               retrieve the named password.  You should previously have
               run 'lpass login' for this to work.

op:name        Use the 1Password command-line client op(1) to
               retrieve the named password.

pass:password  The actual password is password.  Since the password is
               visible to utilities such as ps(1) and possibly leaked
               into the shell history file, this form should only be
               used where security is not important.

tty:prompt     This is the default: `Getpass` will prompt the user on
               the controlling tty using  the provided `prompt`.  If no
               `prompt` is provided, then `Getpass` will use "Password: ".

This function is variadic purely so that you can invoke it without any arguments, thereby defaulting to interactively providing the password as if 'passfrom' was set to "tty:Password: ".

Types

type CancelRequestSubmission added in v1.0.6 

type CancelRequestSubmission struct {
	RequestID string `json:"integrationId"` // This is effectively 'requestId'
	TLDName   string `json:"tldName"`
}

CancelRequestSubmission Request cancellation arguments passed to CancelRequest()

type Client 

type Client struct {
	HTTPClient *http.Client
	AuthURL    string
	BaseURL    string

	Creds Credentials
	// contains filtered or unexported fields
}

Client stores all session information for czds authentication and manages token renewal

func NewClient 

func NewClient(username, password string) *Client

NewClient returns a new instance of the CZDS Client with the default production URLs

func (*Client) Authenticate 

func (c *Client) Authenticate() error

Authenticate tests the client's credentials and gets an authentication token from the server calling this is optional. All other functions will check the auth state on their own first and authenticate if necessary.

func (*Client) CancelRequest added in v1.0.6 

func (c *Client) CancelRequest(cancel *CancelRequestSubmission) (*RequestsInfo, error)

CancelRequest cancels a pre-existing request. Can only cancel pending requests.

func (*Client) DownloadAllRequests 

func (c *Client) DownloadAllRequests(output io.Writer) error

DownloadAllRequests outputs the contents of the csv file downloaded by the "Download All Requests" button on the CZDS portal to the provided output

func (*Client) DownloadZone 

func (c *Client) DownloadZone(url, destinationPath string) error

DownloadZone provided the zone download URL retrieved from GetLinks() downloads the zone file and saves it to local disk at destinationPath

func (*Client) DownloadZoneToWriter 

func (c *Client) DownloadZoneToWriter(url string, dest io.Writer) (int64, error)

DownloadZoneToWriter is analogous to DownloadZone but instead of writing it to a file, it will write it to a provided io.Writer. It returns the number of bytes written to dest and any error that was encountered.

func (*Client) ExtendAllTLDs added in v1.2.0 

func (c *Client) ExtendAllTLDs() ([]string, error)

ExtendAllTLDs is a helper function to request extensions to all TLDs that are extendable

func (*Client) ExtendAllTLDsExcept added in v1.2.12 

func (c *Client) ExtendAllTLDsExcept(except []string) ([]string, error)

ExtendAllTLDsExcept is a helper function to request extensions to all TLDs that are extendable excluding any in except

func (*Client) ExtendTLD added in v1.2.0 

func (c *Client) ExtendTLD(tld string) error

ExtendTLD is a helper function that requests extensions to the provided tld TLDs provided should be marked as Extensible from GetRequestInfo()

func (*Client) GetAllRequests added in v1.2.0 

func (c *Client) GetAllRequests(status string) ([]Request, error)

GetAllRequests returns the request information for all requests with the given status status should be one of the constant czds.Status* strings warning: for large number of results, may be slow

func (*Client) GetDownloadInfo 

func (c *Client) GetDownloadInfo(url string) (*DownloadInfo, error)

GetDownloadInfo Performs a HEAD request to the zone at url and populates a DownloadInfo struct with the information returned by the headers 

func (c *Client) GetLinks() ([]string, error)

GetLinks returns the DownloadLinks available to the authenticated user

func (*Client) GetRequestInfo 

func (c *Client) GetRequestInfo(requestID string) (*RequestsInfo, error)

GetRequestInfo gets detailed information about a particular request and its timeline as seen on the CZDS dashboard page "https://czds.icann.org/zone-requests/{ID}"

func (*Client) GetRequests 

func (c *Client) GetRequests(filter *RequestsFilter) (*RequestsResponse, error)

GetRequests searches for the status of zones requests as seen on the CZDS dashboard page "https://czds.icann.org/zone-requests/all"

func (*Client) GetTLDStatus 

func (c *Client) GetTLDStatus() ([]TLDStatus, error)

GetTLDStatus gets the current status of all TLDs and their ability to be requested

func (*Client) GetTerms 

func (c *Client) GetTerms() (*Terms, error)

GetTerms gets the current terms and conditions from the CZDS portal page "https://czds.icann.org/terms-and-conditions" this is required to accept the terms and conditions when submitting a new request

func (*Client) GetZoneRequestID added in v1.2.0 

func (c *Client) GetZoneRequestID(zone string) (string, error)

GetZoneRequestID returns the most request RequestID for the given zone

func (*Client) RequestAllTLDs 

func (c *Client) RequestAllTLDs(reason string) ([]string, error)

RequestAllTLDs is a helper function to request access to all available TLDs with the provided reason

func (*Client) RequestAllTLDsExcept added in v1.2.12 

func (c *Client) RequestAllTLDsExcept(reason string, except []string) ([]string, error)

RequestAllTLDsExcept is a helper function to request access to all available TLDs with the provided reason skipping over the TLDs in except

func (*Client) RequestExtension added in v1.2.0 

func (c *Client) RequestExtension(requestID string) (*RequestsInfo, error)

RequestExtension submits a request to have the access extended. Can only request extensions for requests expiring within 30 days.

func (*Client) RequestTLDs 

func (c *Client) RequestTLDs(tlds []string, reason string) error

RequestTLDs is a helper function that requests access to the provided tlds with the provided reason TLDs provided should be marked as able to request from GetTLDStatus()

func (*Client) SetLogger added in v1.2.9 

func (c *Client) SetLogger(l Logger)

SetLogger enables verbose printing for most API calls with the provided logger defaults to nil/off.

func (*Client) SubmitRequest 

func (c *Client) SubmitRequest(request *RequestSubmission) error

SubmitRequest submits a new request for access to new zones

type Credentials 

type Credentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

Credentials used by the czds.Client

type DownloadInfo 

type DownloadInfo struct {
	ContentLength int64
	LastModified  time.Time
	Filename      string
}

DownloadInfo information from the HEAD request from a DownloadLink

type FtpDetails 

type FtpDetails struct {
	PrivateDataError bool `json:"privateDataError"`
}

FtpDetails contains FTP information for RequestsInfo

type HistoryEntry 

type HistoryEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Action    string    `json:"action"`
	Comment   string    `json:"comment"`
}

HistoryEntry contains a timestamp and description of action that happened for a RequestsInfo For example: requested, expired, approved, etc..

type Logger added in v1.2.9 

type Logger interface {
	Printf(format string, v ...interface{})
}

Logger specifies the methods required for the verbose logger for the API

type Request 

type Request struct {
	RequestID   string    `json:"requestId"`
	TLD         string    `json:"tld"`
	ULabel      string    `json:"ulable"` // UTF-8 decoded punycode, looks like API has a typo
	Status      string    `json:"status"` // should be set to one of the Request* constants
	Created     time.Time `json:"created"`
	LastUpdated time.Time `json:"last_updated"`
	Expired     time.Time `json:"expired"` // Note: epoch 0 means no expiration set
	SFTP        bool      `json:"sftp"`
	AutoRenew   bool      `json:"auto_renew"`
}

Request holds information about a request in RequestsResponse from GetRequests()

type RequestSubmission 

type RequestSubmission struct {
	AllTLDs          bool     `json:"allTlds"`
	TLDNames         []string `json:"tldNames"`
	Reason           string   `json:"reason"`
	TcVersion        string   `json:"tcVersion"` // terms and conditions revision version
	AdditionalFTPIps []string `json:"additionalFtfIps,omitempty"`
}

RequestSubmission contains the information required to submit a new request with SubmitRequest()

type RequestsFilter 

type RequestsFilter struct {
	Status     string             `json:"status"` // should be set to one of the Request* constants
	Filter     string             `json:"filter"` // zone name search
	Pagination RequestsPagination `json:"pagination"`
	Sort       RequestsSort       `json:"sort"`
}

RequestsFilter is used to set what results should be returned by GetRequests

type RequestsInfo 

type RequestsInfo struct {
	RequestID          string         `json:"requestId"`
	TLD                *TLDStatus     `json:"tld"`
	FtpIps             []string       `json:"ftpips"`
	Status             string         `json:"status"` // should be set to one of the Status* constants
	TcVersion          string         `json:"tcVersion"`
	Created            time.Time      `json:"created"`
	RequestIP          string         `json:"requestIp"`
	Reason             string         `json:"reason"`
	LastUpdated        time.Time      `json:"last_updated"`
	Cancellable        bool           `json:"cancellable"`
	Extensible         bool           `json:"extensible"`
	ExtensionInProcess bool           `json:"extensionInProcess"`
	AutoRenew          bool           `json:"auto_renew"`
	Expired            time.Time      `json:"expired"` // Note: epoch 0 means no expiration set
	History            []HistoryEntry `json:"history"`
	FtpDetails         *FtpDetails    `json:"ftpDetails"`
	PrivateDataError   bool           `json:"privateDataError"`
}

RequestsInfo contains the detailed information about a particular zone request returned by GetRequestInfo()

type RequestsPagination 

type RequestsPagination struct {
	Size int `json:"size"`
	Page int `json:"page"`
}

RequestsPagination sets the page size and offset for paginated results for RequestsFilter

type RequestsResponse 

type RequestsResponse struct {
	Requests      []Request `json:"requests"`
	TotalRequests int64     `json:"totalRequests"`
}

RequestsResponse holds Requests from from GetRequests() and total number of requests that match the query but may not be returned due to pagination

type RequestsSort 

type RequestsSort struct {
	Field     string `json:"field"`
	Direction string `json:"direction"`
}

RequestsSort sets which field and direction the results for the RequestsFilter request should be returned with

type TLDStatus 

type TLDStatus struct {
	TLD           string `json:"tld"`
	ULabel        string `json:"ulable"`        // UTF-8 decoded punycode, looks like API has a typo
	CurrentStatus string `json:"currentStatus"` // should be set to one of the Status* constants
	SFTP          bool   `json:"sftp"`
}

TLDStatus is information about a particular TLD returned from GetTLDStatus() or included in RequestsInfo

type Terms 

type Terms struct {
	Version    string    `json:"version"`
	Content    string    `json:"content"`
	ContentURL string    `json:"contentUrl"`
	Created    time.Time `json:"created"`
}

Terms holds the terms and conditions details from GetTerms()

Source Files

View all Source files

Directories

Path Synopsis
cmd
czds-dl
czds-request
czds-status
Package jwt defines the JWT types used by the czds authentication API
 Package jwt defines the JWT types used by the czds authentication API

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.