czds

package module
v1.2.7 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2022 License: GPL-3.0 Imports: 12 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:
  -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)
  -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
  -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-REPORT

Download the CSV report for current zone status.

Usage
Usage of czds-report:
  -file string
        filename to save report to, '-' for stdout (default "report.csv")
  -password string
        password to authenticate with
  -username string
        username to authenticate with
  -verbose
        enable verbose logging
Example
$ ./czds-report -username "$USERNAME" -password "$PASSWORD" -verbose -file report.csv
2019/02/02 17:43:37 Authenticating to https://account-api.icann.org/api/authenticate
2019/02/02 17:43:38 Saving to report.csv

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
  -extend string
        comma separated list of zones to request extensions
  -extend-all
        extend all possible zones
  -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
Example

View zones able to be requested

./czds-request -username "$USERNAME" -password "$PASSWORD" -status  | grep -v pending | grep -v approved

Request access to new zones

./czds-request -username "$USERNAME" -password "$PASSWORD" -request "red,blue,xyz" -reason "$REASON"

Request access to all zones

./czds-request -username "$USERNAME" -password "$PASSWORD" -request-all -reason "$REASON"

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.

Usage of czds-status:
  -id string
        ID of specific zone request to lookup, defaults to printing all
  -password string
        password to authenticate with
  -username string
        username to authenticate with
  -verbose
        enable verbose logging
  -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"
)

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

This section is empty.

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) 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) 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) 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 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"`
}

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-report
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.