Skip to content
FQDN Serverless Service
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


FQDN Service Serverless Application

Serverless Application to turn a list of FQDN entries into a dynamic IPv4/IPv6 feed.


Cloud embracement by many companies are driving adoption of Content Delivery providers as well as Global Server Load Balancing technologies. In many occasions the DNS service is at the very bottom layer of the stack of these technology providing FQDN to A Record mapping with too many entries or with a TTL too small to be tracked in L4 security policies.

Using L7 security policies is the right solution to the problem. But, if for any reason, you need a WEB API that provides you with a feed of IPv4 and IPv6 values bound to a set of FQDN entries then this serverless application might be a good fit.


Just deploy the Serverless Application from the AWS Serverless Repo or create a CloudFormation Stack using the template sam_template.yaml


The following resources will be created into your AWS Account once the FQDN Service Application is deployed:

  • AWS API Gateway named fqndServiceGw
  • AWS Lambda named fqdnServiceLamdba
  • AWS DynamoDB table named fqdnservice-fqndServiceTable-{ID}
  • AWS IAM Role named fqdnservice-fqdnServiceLamdbaRole-{ID}

In the AWS Console navigate to Services > API GW > fqdnServiceGw > Stages > prod > Stage Variables and change the default secret value ("defaultSecret") for something meaningful to you.

FQDN Service Configuration File

The configuration must be provided as a JSON document with a free schema. Inside the JSON document you must provide fqdn templates conforming with the following schema:

{ "fqdn": "{full qualified domain name i.e}" }

At runtime, any fqdn template in the configuration file will be replaced with and object featuring IPv4 and IPv6 arrays provided by a DNS resolver.

Example Configuration File:

    "UPF": { "fqdn": "" },
    "UB": { "fqdn": "" }

Example FQDN Service Sesponse:

  "UPF": {
    "ipv4": [
    "ipv6": [
  "UB": {
    "ipv4": [

Publishing the configuration file

The FQDN Service provides a /config entry point that can be used to POST a new configuration file at any moment.

In the AWS Console navigate to Services > API GW > fqdnServiceGw > Stages > prod to take note of the Invoke URL value for your instance.

Then use curl (or any other tool you feel comfortable with) to POST your configuration file.


foo$ curl --data-binary '{ "PANW": { "fqdn": "" } }' "{Invoke URL}/config?key={secret}"

If everything goes right, the configuration file will be echoed in the response. Otherwise, the error will be returned.

Example response:


Formating the output

By default, the FQDN Service returns the list of IPv4 addresses known to have been resolved in the last 24 hours by the list of fqdn templates in the configuration file in a plain/text format.


foo$ curl {Invoke URL}

If you want the list of IPv6 records instead, then just add the v=ipv6 url parameter.


foo$ curl {Invoke URL}?v=ipv6

And, finally, if you want to get the original JSON configuration file transformed then use the v=json url parameter.


foo$ curl {Invoke URL}?v=json

Spanning your response

The FQDN Service is backed by a DynamoDB table that stores all known resolutions (both IPv4 and IPv6) for a given fqdn alongside a valid until value computed as the current time plus the ttl value returned by the DNS resolver.

You can use the span={seconds} url paramter to change the default 24 hour span.


foo$ curl "{Invoke URL}?v=json&span=60"

Using multiple stages

You can create additional stages in the AWS API GW to implement many virtual FQDN services.

If you do so then take into account that:

  1. remember to add the stage variables dbtable and secret
  2. POST a new configuration file for the new stage.

You can (in fact you're encouraged to) use the same DynamoDB table by the many stages you decide to deploy. If you choose to use a different table than the one already deployed then remember to create it using the DynameDB console and to modify the IAM rome fqdnServiceLamdbaRole-{ID} to allow the fqdn service lambda perform operation onto the new table.

You can’t perform that action at this time.