Monitor your domains for unauthorized changes

Overview

Appwarden uses your domain configuration to continuously monitor your infrastructure and web traffic. When a mismatch is detected, an incident is communicated to your Discord server for diagnosis. This guide will walk you through the process of creating and managing your domain configuration files.

Create your domain configuration repository

Appwarden manages your domain configuration in a source-controlled GitHub repository of your choice.

An Appwarden domain configuration repository in a code editor

You can use our template repository or bring your own repository. This makes your Appwarden domain configuration files:

Version controlled and auditable
Easily accessible by your developers and security personnel
Conveniently co-located with your infrastructure and source code
Inherit GitHub’s outstanding security and access control features

Create your Appwarden configuration repository from our template repository to manage your domain configuration. Simply choose a name for your repository and click “Create repository” to get started.

Once the repository is created, or if you want to use your own repository, you can move on to the next step. We will return to the repository later to set up your domain configuration.

In GitHub, create your domain configuration repository from the template repository

Appwarden in pull requests

When a GitHub pull request is opened in your domain configuration repository, Appwarden will comment on configuration validation issues and deployment status changes in the pull request thread.

Appwarden uses a GitHub app to synchronize your domain configuration repository changes with Appwarden.

Although you can push changes directly to main, you should always use pull requests to make domain configuration changes. This ensures that your domain configuration is valid, peer reviewed, and approved before being merged.

Use pull requests to ensure your domain configuration correctly deploys. If faulty configuration files are pushed directly to main, they will not be deployed and you will not be notified of the problem.

Appwarden reported a valid domain configuration change in the pull request below and will deploy the changes when the pull request is merged.

Appwarden signals any domain configuration validation issues and deployment status changes in pull requests

Create a domain configuration file

The Appwarden CLI generates preconfigured domain configuration files from your existing domain state. To generate domain configuration files, run the following command from the root of your domain configuration repository:

1
npx appwarden init -d your.app -d app.your.app

This command will scaffold an .appwarden directory in your project and generate a domain configuration file at .appwarden/domains/your-domain.yml containing DNS records on your.app and websites on your.app and app.your.app.

Please review the results of the appwarden init command and check that the generated domain configuration reflects your deployed domain state. Modify any values as needed.

Updating existing domain configurations

When you run appwarden init on a domain configuration file that already exists, the command will intelligently merge your changes:

Preserves middleware configuration: Any middleware settings (such as CSP directives and lock page configuration) remain intact
Preserves DNS and website options: Existing dns.options and websites.options (such as links) are maintained
Selective monitor updates: Only DNS and website monitors for domains specified with -d flags are updated

For example, if your configuration file monitors example.com, api.example.com, and cdn.example.com, running:

1
npx appwarden init -d example.com

Will fetch and update the DNS and website monitors for example.com only, while preserving all monitors for api.example.com and cdn.example.com, as well as any middleware configuration and options you’ve set up.

Domain configuration file structure

A domain configuration file is scoped to a specific hostname and tagged with a version. For the purpose of DNS and website monitoring, it contains two primary top level sections, dns and websites. Each section contains lists of monitors. The middleware section is used to configure the Appwarden middleware with Content Security Policy (CSP) and lock page settings.

1
hostname: your.app
2
version: 1
3
dns:
4
  options:
5
    links:
6
      - label: DNS Dashboard
7
        url: your-dns-dashboard.com
8
  monitors:
9
    - name: your.app
10
      type: A
11
      content:
12
        # This is the first nested record
13
        - content: 104.21.73.192
14
        # This is the second nested record
15
        - content: 172.67.165.113
16
    - name: your.app
17
      type: SOA
18
      content: anastasia.ns.cloudflare.com. dns.cloudflare.com.
19
      validator: starts-with
20
websites:
21
  options:
22
    links:
23
      - label: Website metrics
24
        url: your-metrics-dashboard.com
25
  monitors:
26
    - url: your.app
27
      status: 200
28
      headers:
29
        - name: content-type
30
          value: text/html
31
          validator: starts-with
32
    - url: app.your.app
33
      status: 200
34
      headers:
35
        - name: server
36
          value: cloudflare
37
        - name: referrer-policy
38
          value: strict-origin-when-cross-origin
39
  middleware:
40
    - url: app.your.app
41
      options:
42
        lock-page-slug: /maintenance
43
        csp-mode: report-only
44
        csp-directives:
45
          script-src:
46
            - "self"
47
            - "{{nonce}}"
48
            - https://cdn.jsdelivr.net

This domain configuration file contains two dns monitors, two website monitors, and a middleware configuration. The dns monitors define two A records and an SOA record starting with the content field that should exist on your deployed infrastructure. The website monitors defines that the response status code is 200 and that the enumerated headers are present in the response.

Version

The version field indicates the file schema version. The current version is 1.

Hostname

The hostname field indicates the domain that this configuration file is scoped to. All enumerated websites must be subdomains of the root hostname field.

DNS

Monitors

DNS records can be listed individually as seen in the SOA record or conveniently grouped by type fields as shown in the example above for A records.

Websites

All enumerated websites must be subdomains of the root hostname field.

Monitors

Each website monitor contains a url, status, and headers field. The headers field contains a list of headers to monitor for each website.

Middleware

The middleware field is used to configure the Appwarden middleware for Cloudflare-powered websites. The url field specifies the subdomain to apply the middleware configuration on. The options field contains the lock-page-slug, csp-mode, and csp-directives fields. For more information on middleware options, please refer to the Middleware reference.

If your website is on Vercel, Appwarden is configured directly in your middleware.ts file.

Links

You may add links to the options field to provide quick access to critical dashboards during an incident. When an incident is created, the incident message will contain links corresponding to the values in dns.options.links and websites.options.links.

Comments

You may add YAML comments (lines starting with #) to describe the contents or purpose of any entry.

1
dns:
2
  monitors:
3
    - name: your.app
4
      type: A
5
      content:
6
        # This is the first nested record
7
        - content: 104.21.73.192
8
        # This is the second nested record
9
        - content: 172.67.165.113

Validators

Validators are used to validate the value of a DNS record or web response header.

Supported validators

starts-with - The detected value must start with this expected value. Useful for DNS records with dynamic values such as SOA records that start with static values and end with dynamic values (e.g. ns1.cloudflare.com. dns.cloudflare.com. 2026021701 10000 2400 604800 3600)

If you have need for other validators, please reach out in our community.

1
websites:
2
  monitors:
3
    - url: your.app
4
      status: 200
5
      headers:
6
        - name: content-type
7
          value: text/html
8
          validator: starts-with

Limits

You can monitor up to three domains with Appwarden.
The maximum file size for a domain configuration file is 60kb.

These global limits are in place for abuse prevention. If you need higher limits, we’re happy to work with you — please reach out in our community.