desec-dns

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.9+
• requests
• cryptography (optional, for high-level management of TLSA records)
• dnspython (optional, for parsing zone files)

Usage

CLI

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
  --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 module and initialize an instance of APIClient:

import desec

api_client = desec.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 annotation 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.

Finally, you may skip package installation altogether and just get the Python script and place it in a convenient location. Be warned that this method is deprecated and may cease to work without further notice.

Related Work

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