uddr_client

A Python SDK for UltraDDR

Installation

The package can be installed using pip

pip install uddr_client

Setup

For ease of use, you can store your API key in an environment file using the client's "setup" method.

import uddr_client
uddr_client.connect.setup()

Alternatively, you can pass the key directly to the connection using keyword arguments.

c = uddr_client.connect('api_key=<your API key>')

If your API key is associated with more than one organization, you can specify which one to use by passing the organization name as a keyword argument or by setting it in your environment.

import uddr_client
client = uddr_client.connect()
doh_client = client.doh()
doh_client.setup()

API Usage

import uddr_client

c = uddr_client.connect() # Instantiates a new instance of the client which, by default, uses the API key stored in your .env
api_client = c.api()      # Creates an API client instance
resp = api_client.reports()        # Call an endpoint
print(resp)

Available methods

The API client currently supports the following endpoints:

aggregates()
bar()
histogram()
summary()
report()
reports()
histogram_artifact()
logs()
passthrough()
category()
account()
- organization()
  - settings()
  - products()
  - packages()
- user()
  - organizations()
decision()
- baseline()
  - countries()

Use Python's help function for more in-depth documentation on each method.

help(c.api().logs)

Response parsing

Aside from the report() (application/pdf) and category() (list) endpoints, all methods produce a Response object which handles different outputs.

Response.xml(): Outputs the response in XML
Response.csv(): Outputs the response in CSV

The default is JSON.

DoH Usage

The DNS over HTTPS (DoH) client provides an interface for directly querying the UDDR resolvers.

import uddr_client

client = uddr_client.connect()
doh = client.doh() # Creates a DoH client instance
lookup = doh.lookup('google.com') # Perform a lookup on google.com
print(lookup)  # This will return the full json response for the lookup

Record Types

The client stores the response for various DNS record types as properties. The following are supported.

lookup.A      # For A records
lookup.AAAA   # For AAAA records
lookup.CNAME  # For CNAME records
lookup.NS     # For NS records
lookup.MX     # For MX records
lookup.TXT    # For TXT records
lookup.SOA    # For SOA records
lookup.SRV    # For SRV records
lookup.CAA    # For CAA records
lookup.DS     # For DS records
lookup.DNSKEY # For DNSKEY records

Reverse Lookups

If you pass an IP to the client, it will automatically perform a reverse lookup (PTR).

IoC Parsing

This concept is borrowed from Michael Smith's DDR-IOC-Checker.

Indicators of compromise passed to the DOHClient as a positional argument will be run through a parser. The parser accepts the following:

Domain names
URLs by means of stripping the protocol and path
"Defanged" URLs which are intentionally obfuscated for security reasons
Emails - the parser will remove the prefix and @
IP addresses

Additional Methods

The following methods return information about the DoH query or specific parts of the response.

status() - Returns an object with information about the status of the response. DoH provides a numerical code, this expands with a message and description.
block_info() - Returns a string stating whether the domain is blocked (by checking if the A record resolves to the UDDR block page).
answer() - Returns the answer section of the response, if one exists.
authority() - Returns the authority section of the response, if one exists.

Dependencies

pandas
xmltodict
python-decouple
requests

License

This project is licensed under the terms of the MIT license. See LICENSE.md for more details.

sbarbett/uddr_client