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
- Python 3.9+
- requests
- cryptography (optional, for high-level management of TLSA records)
- dnspython (optional, for parsing zone files)
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.
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 desecThe documentation is also conveniently available online
and automatically updated for the main branch of this repository.
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 filestlsa- 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.