Configuration

This guide covers all configuration options available in DomainMate.

Configuration File Structure

DomainMate uses a YAML configuration file (default: config.yaml) with the following structure:

yaml

domains:
  - example.com
  - monitor.io

monitors:
  domain:
    enabled: true
    expiry_warning_days: 30
    expiry_critical_days: 7
  ssl:
    enabled: true
    expiry_warning_days: 30
    expiry_critical_days: 7
  dns:
    enabled: true
    required_records:
      - spf
      - dmarc
  security:
    enabled: true
  blacklist:
    enabled: true

reports:
  output_dir: "reports"
  retention_days: 30

notifications:
  telegram:
    bot_token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    chat_id: "-1001234567890"

heartbeat_url: "https://uptime.example.com/api/push/..."
api_url: "https://dashboard.example.com/api/upload"

Domain Configuration

Basic Domain List

yaml

domains:
  - example.com
  - mysite.io
  - www.another-site.com

DomainMate intelligently handles:

Root domains: example.com
Subdomains: www.example.com, api.example.com
URLs: Automatically extracts domain from https://example.com/path

Domain Resolution

For connection-based checks (SSL, Security), DomainMate:

Tries to resolve the exact domain
Falls back to www.{domain} if the root doesn't resolve
Uses parent domain for WHOIS checks to avoid subdomain errors

Monitor Configuration

Domain Monitor

Tracks domain expiration using WHOIS:

yaml

monitors:
  domain:
    enabled: true              # Enable/disable monitor
    expiry_warning_days: 30    # Days before expiry to warn
    expiry_critical_days: 7    # Days before expiry marked critical

Features:

Automatic parent domain detection for subdomains
Handles multiple registrar date formats
Timezone-aware date calculations

SSL Monitor

Validates SSL/TLS certificates:

yaml

monitors:
  ssl:
    enabled: true
    expiry_warning_days: 30
    expiry_critical_days: 7

Checks:

Certificate validity period
Certificate chain validation
Expiration date tracking
Deprecated protocol detection (SSLv3, TLS 1.0/1.1)
Certificate issuer information

DNS Monitor

Audits DNS security records:

yaml

monitors:
  dns:
    enabled: true
    required_records:
      - spf      # Sender Policy Framework
      - dmarc    # Domain-based Message Authentication
      - dkim     # DomainKeys Identified Mail (optional)

Checks:

SPF record presence and syntax
DMARC record presence and policy
DKIM record availability
DNS resolution health

Security Monitor

Analyzes HTTP security headers:

yaml

monitors:
  security:
    enabled: true

Checks:

HSTS (HTTP Strict Transport Security)
CSP (Content Security Policy)
X-Frame-Options
X-Content-Type-Options
X-XSS-Protection
Referrer-Policy
Server header information disclosure
X-Powered-By header leakage

Blacklist Monitor

Monitors IP reputation against RBLs:

yaml

monitors:
  blacklist:
    enabled: true

Features:

Checks against major RBLs (Spamhaus, SORBS, etc.)
Hybrid resolution strategy
Differentiates between blocking and listing
IPv4 and IPv6 support

Reports Configuration

yaml

reports:
  output_dir: "reports"      # Directory for generated reports
  retention_days: 30         # Days to keep old reports (cleanup)

Each run writes index.html and report.json describing the latest scan, plus a timestamped report-YYYYMMDD-HHMMSS.json snapshot. retention_days deletes snapshots older than that many days; leave it unset to keep every one.

Only the JSON is kept per run, not the HTML: it is the machine-readable record a trend would be built from, it is an order of magnitude smaller, and index.html can be rendered from it. The snapshot from the run in progress is never pruned, whatever the retention is set to.

Ports

A domains entry may carry a port:

yaml

domains:
  - example.com
  - mail.example.com:993     # IMAP over TLS
  - internal.example.com:8443

Only the SSL check uses it. WHOIS, the DNS records and the RBL lookups all want the hostname, and get it. Without a port the SSL check uses 443.

A port that is not a number, or is outside 1-65535, is reported and ignored rather than failing the run.

Unknown Keys

Every key is checked against the settings the code actually reads. A key that is not recognised is reported on startup:

WARNING | Unknown config key ignored: monitors.domain.expiry_warnings_days

A typo that looks applied but is not is worse than one that errors, so the warning names exactly where the key sits.

Reports are generated as self-contained HTML files with:

Embedded CSS and JavaScript — no external requests, so a report opens with no network and does not disclose who is reading it, or when
Sorting, search, grouping by domain and a status filter, all inline
Mobile-responsive design
No external dependencies

Notifications Configuration

In-File Configuration

yaml

notifications:
  telegram:
    bot_token: "your-bot-token"
    chat_id: "your-chat-id"
  
  teams:
    webhook_url: "https://outlook.office.com/webhook/..."
  
  email:
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    user: "your-email@gmail.com"
    password: "your-password"
    to: "recipient@example.com"

Security Note

Avoid committing secrets to your repository. Use environment variables instead!

Environment Variables (Recommended)

Override or supplement file configuration with environment variables:

Variable	Description
`DOMAINMATE_CONFIG_FILE`	Path to configuration file (default: config.yaml). Can be absolute (`/etc/domainmate/config.yaml`) or relative (`./config.yaml`).
`GITHUB_TOKEN`	GitHub Personal Access Token for issue creation
`GITHUB_REPO`	Target GitHub repository (format: `user/repo`)
`GITLAB_TOKEN`	GitLab Private Token
`GITLAB_PROJECT_ID`	GitLab Project ID
`TELEGRAM_BOT_TOKEN`	Telegram Bot API Token
`TELEGRAM_CHAT_ID`	Telegram Chat ID
`TEAMS_WEBHOOK_URL`	Microsoft Teams Connector URL
`GENERIC_WEBHOOK_URL`	Generic webhook endpoint for JSON payloads
`EMAIL_SMTP_SERVER`	SMTP Server hostname
`EMAIL_SMTP_PORT`	SMTP Port (default: 587)
`EMAIL_USER`	SMTP username
`EMAIL_PASSWORD`	SMTP password
`EMAIL_TO`	Recipient email address

Example:

bash

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export GITHUB_REPO="user/repo"
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234"
export TELEGRAM_CHAT_ID="-1001234567890"

python src/cli.py --notify

Integration Endpoints

Heartbeat URL (Dead Man's Switch)

Send a GET request on successful completion:

yaml

heartbeat_url: "https://uptime.example.com/api/push/abc123"

Use this with services like:

UptimeRobot
Healthchecks.io
Better Uptime
Custom monitoring endpoints

API Upload

POST complete audit results as JSON:

yaml

api_url: "https://dashboard.example.com/api/upload"

Payload format:

json

[
  {
    "domain": "example.com",
    "monitor": "ssl",
    "status": "ok",
    "message": "Certificate valid",
    "expiration_date": "2025-12-31",
    "days_until_expiry": 365
  }
]

Privacy & Security

Option A: Private Repository (Recommended)

Keep your repository private on GitHub/GitLab. Your configuration and reports remain secure.

Option B: Secret Injection (Public Repository)

For public repositories:

Store your entire config.yaml as a secret
Go to Settings → Secrets and variables → Actions
Create secret named DOMAINMATE_CONFIG_CONTENT
Paste your full config there

Modify your workflow to inject it:

yaml

- name: Inject Secret Config
  if: "${{ secrets.DOMAINMATE_CONFIG_CONTENT != '' }}"
  run: echo "${{ secrets.DOMAINMATE_CONFIG_CONTENT }}" > config.yaml

Option C: Environment Variables Only

Don't use a config file at all:

bash

# Minimal config.yaml with just domains
domains:
  - example.com

# All other settings via environment
export GITHUB_TOKEN="..."
export TELEGRAM_BOT_TOKEN="..."

python src/cli.py --notify

Configuration Validation

DomainMate validates your configuration on startup:

Valid YAML syntax (malformed YAML causes an early exit with an error)
domains list must be present and non-empty

Examples

Minimal Configuration

yaml

domains:
  - example.com

monitors:
  domain:
    enabled: true
  ssl:
    enabled: true

Production Configuration

yaml

domains:
  - api.prod.example.com
  - www.example.com
  - staging.example.com
  - admin.example.com

monitors:
  domain:
    enabled: true
    expiry_warning_days: 60
    expiry_critical_days: 30
  ssl:
    enabled: true
    expiry_warning_days: 45
    expiry_critical_days: 14
  dns:
    enabled: true
    required_records:
      - spf
      - dmarc
  security:
    enabled: true
  blacklist:
    enabled: true

reports:
  output_dir: "reports"
  retention_days: 90

heartbeat_url: "https://healthchecks.io/ping/abc123"

All sensitive data in environment variables.

Next Steps

Learn about each monitor in the Monitors Guide
Set up notifications in the Notifications Guide
Integrate with CI/CD in the CI/CD Guide

Configuration ​

Configuration File Structure ​

Domain Configuration ​

Basic Domain List ​

Domain Resolution ​

Monitor Configuration ​

Domain Monitor ​

SSL Monitor ​

DNS Monitor ​

Security Monitor ​

Blacklist Monitor ​

Reports Configuration ​

Ports ​

Unknown Keys ​

Notifications Configuration ​

In-File Configuration ​

Environment Variables (Recommended) ​

Integration Endpoints ​

Heartbeat URL (Dead Man's Switch) ​

API Upload ​

Privacy & Security ​

Option A: Private Repository (Recommended) ​

Option B: Secret Injection (Public Repository) ​

Option C: Environment Variables Only ​

Configuration Validation ​

Examples ​

Minimal Configuration ​

Production Configuration ​

Next Steps ​

Configuration

Configuration File Structure

Domain Configuration

Basic Domain List

Domain Resolution

Monitor Configuration

Domain Monitor

SSL Monitor

DNS Monitor

Security Monitor

Blacklist Monitor

Reports Configuration

Ports

Unknown Keys

Notifications Configuration

In-File Configuration

Environment Variables (Recommended)

Integration Endpoints

Heartbeat URL (Dead Man's Switch)

API Upload

Privacy & Security

Option A: Private Repository (Recommended)

Option B: Secret Injection (Public Repository)

Option C: Environment Variables Only

Configuration Validation

Examples

Minimal Configuration

Production Configuration

Next Steps