deSEC.io API client

This is a simple client to manage domains hosted by deSEC.io using the deSEC.io API. It can be used from the command line or as a Python module.

It serves as an API client for most of the functionality of the deSEC.io API, but also includes some additional convenience functionality that goes beyond what is offered by the API. The features include:

• Domain management
• DNS record management
• Authentication token management
• Token policy management
• Import and export of records in zone file format
• Import and export of records in custom JSON format
• Generation of TLSA records from certificate files
• Sensible handling of rate limits and pagination

Requirements

• Python 3.10+
• requests
• cryptography (optional, for high-level management of TLSA records)
• dnspython (optional, for parsing zone files)

Usage

CLI

The deSEC API requires an token for authentication, which you can create on the deSEC.io website or through the API if you already have another token. You can provide this token to the CLI:

1. Via the --token argument
2. In the DESEC_TOKEN environment variable
3. In a file by passing a path to the --token-file argument
4. In a file at $XDG_CONFIG_HOME/desec/token

In case multiple methods are used simultaneously, priority will be given according to the list above in order.

Note: If the token is obtained from a file, the file may be a scripts that prints to token to stdout. Scripts are distinguished from plain files by the executable permission bit on the file system.

The functionality is split into subcommands, as shown below. Most subcommand require further parameters to work. They are described by the usage information of each individual subcommand.

usage: desec [-h] [-V] [--token TOKEN | --token-file TOKEN_FILE] [--non-blocking] [--blocking] [--debug-http] action ...

A simple deSEC.io API client

positional arguments:
  action
    list-tokens         list all authentication tokens
    create-token        create and return a new authentication token
    modify-token        modify an existing authentication token
    delete-token        delete an authentication token
    list-token-policies
                        list all policies of an authentication token
    add-token-policy    add a policy for an authentication token
    modify-token-policy
                        modify an existing policy for an authentication token
    delete-token-policy
                        delete an existing policy for an authentication token
    list-domains        list all registered domains
    domain-info         get information about a domain
    new-domain          create a new domain
    delete-domain       delete a domain
    get-records         list all records of a domain
    add-record          add a record set to the domain
    change-record       change an existing record set
    delete-record       delete a record set
    update-record       add entries, possibly to an existing record set
    add-tlsa            add a TLSA record for a X.509 certificate (aka DANE),
                        keeping any existing records
    set-tlsa            set the TLSA record for a X.509 certificate (aka
                        DANE), removing any existing records for the same
                        port, protocol and subname
    export              export all records into a file
    export-zone         export all records into a zone file
    import              import records from a file
    import-zone         import records from a zone file

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --token TOKEN         API authentication token (default: $DESEC_TOKEN environment variable)
  --token-file TOKEN_FILE
                        file containing the API authentication token (default:
                        $XDG_CONFIG_HOME/desec/token)
  --non-blocking        When the API's rate limit is reached, return an
                        appropriate error.
  --blocking            When the API's rate limit is reached, wait and retry
                        the request. This is the default behaviour.
  --debug-http          Print details about http requests / responses.

Python Module

This project can also be used as a Python module. To get started, import the desec.api module and initialize an instance of APIClient:

import desec.api

api_client = desec.api.APIClient("my-secret-token-value")

Refer to the documentation for anything beyond that. The module's API is documented in standard Python docstrings and type annotations and can be viewed using any tool that can handle them. For example, to browse the documentation using pdoc, run:

pdoc -d google desec

The documentation is also conveniently available online and automatically updated for the main branch of this repository.

Installation

This software is available on PyPI and can therefore be installed in the usual way, e.g. using pipx:

pipx install desec-dns[all]

Note that this command installs the dependencies required for all optional features, namely:

• zonefiles - Support for importing zone files
• tlsa - Support generating TLSA records from certificates
  Select only desired features or omit them altogether for a smaller installation.

To install the latest development version, run

pipx install git+https://github.com/s-hamann/desec-dns.git#egg=desec-dns[all]

or clone the repository and run

pipx install -e ./path/to/desc-dns[all]

You can use poetry to manage a virtual environment with desec installed. That is especially recommended if you want to contribute. Run poetry install --with=dev to get all dependencies and necessary tools for formatting, linting, and type-checking. If you want to work on features that require optional dependencies, install the corresponding extras, e.g.: poetry install --extras=tlsa or just go for poetry install --all-extras.

Shell completion

Completion scripts for bash and zsh are available at completions/desec.bash and completions/_desec, respectively. Distribution packages typically install them automatically. When installing manually, copy them to your completions directories, for example:

install -Dm644 completions/desec.bash /usr/share/bash-completion/completions/desec
install -Dm644 completions/_desec /usr/share/zsh/site-functions/_desec

Alternatively, you can source the bash-completion from your ~/.bashrc:

source /path/to/completions/desec.bash

Manual page

A manual page for the desec command is available at man/desec.1. Distribution packages typically install it automatically. When installing manually, copy it to a directory in your MANPATH, for example:

install -Dm644 man/desec.1 /usr/share/man/man1/desec.1

It can then be viewed with man desec.

Gentoo Linux

Gentoo users can enable the GURU overlay and install it using portage:

emerge app-misc/desec-dns

Related Work

• deSEC.io - official website
• deSEC.io DNS API documentation
• deSEC.io stack
• list of tools that use the deSEC.io API