Configuration

Basic Setup

The Email DNS collector queries public DNS records and does not require authentication.

collectors:
  email-dns:
    source: locktivity/epack-collector-email-dns@^0.1
    config:
      domains:
        - example.com
        - company.org

Configuration Options

DKIM Selectors

The collector automatically checks these common DKIM selectors for each domain:

If your organization uses custom DKIM selectors not in this list, the DKIM check may not find them. The collector reports what it finds, but absence of a DKIM record doesn't necessarily mean DKIM isn't configured.

DNS Resolution

The collector uses the system's default DNS resolver. For consistent results across environments, ensure your DNS resolver can reach authoritative nameservers for all configured domains.

Troubleshooting

"domains is required"

The domains field must be set in your config:

config:
  domains:
    - example.com  # Required - at least one domain

DNS lookup failures

If DNS lookups fail for specific domains:
- Verify the domain exists and is reachable
- Check your network's DNS resolution
- Ensure the domain's DNS servers are responding

Missing DKIM records

DKIM records may not be found if:
- The domain uses a custom selector not in the default list
- DKIM is not configured for the domain
- The DKIM record has been removed or is misconfigured

DMARC policy shows "unknown"

The DMARC policy is extracted from the p= tag. If parsing fails or the policy value is non-standard, it will show as "unknown".

Examples

Basic Usage

Single Domain

stream: myorg/email-dns-posture

collectors:
  email-dns:
    source: locktivity/epack-collector-email-dns@^0.1
    config:
      domains:
        - example.com

Then run:

epack collect

Multiple Domains

stream: myorg/email-dns-posture

collectors:
  email-dns:
    source: locktivity/epack-collector-email-dns@^0.1
    config:
      domains:
        - example.com
        - company.org
        - brand.io
        - marketing.example.com

Including Parked Domains

Best practice is to include all domains you own, including parked domains. Parked domains should still have DMARC set to p=reject to prevent spoofing.

collectors:
  email-dns:
    source: locktivity/epack-collector-email-dns@^0.1
    config:
      domains:
        - example.com           # Primary domain
        - corp.example.com      # Corporate subdomain
        - parked-domain.com     # Parked domain
        - old-brand.com         # Legacy domain

Sample Output

{
  "protocol_version": 1,
  "data": {
    "schema_version": "1.0.0",
    "collected_at": "2026-04-20T10:30:00Z",
    "domains": [
      {
        "domain": "example.com",
        "mx": [
          {"host": "smtp.google.com", "priority": 10}
        ],
        "spf": {
          "record": "v=spf1 include:_spf.google.com ~all",
          "valid": true
        },
        "dmarc": {
          "record": "v=DMARC1; p=reject; sp=reject; pct=100; rua=mailto:dmarc@example.com",
          "policy": "reject",
          "subdomain_policy": "reject",
          "pct": 100,
          "rua": "mailto:dmarc@example.com",
          "valid": true
        },
        "dkim": [
          {"selector": "google", "record": "v=DKIM1; k=rsa; p=...", "valid": true}
        ],
        "assessment": {
          "enforced": true,
          "has_reporting": true
        }
      },
      {
        "domain": "parked-domain.com",
        "mx": [],
        "spf": {
          "record": "v=spf1 -all",
          "valid": true
        },
        "dmarc": {
          "record": "v=DMARC1; p=reject; sp=reject",
          "policy": "reject",
          "subdomain_policy": "reject",
          "pct": 100,
          "valid": true
        },
        "assessment": {
          "enforced": true,
          "has_reporting": false,
          "issues": [
            "No DMARC aggregate reporting (rua) configured",
            "No DKIM records found for common selectors (custom selectors not checked)"
          ]
        }
      }
    ],
    "summary": {
      "total_domains": 2,
      "with_mx_pct": 50,
      "with_spf_pct": 100,
      "with_dmarc_pct": 100,
      "with_dkim_pct": 50,
      "with_all_three_pct": 50,
      "enforced_pct": 100,
      "with_reporting_pct": 50,
      "all_enforced": true
    }
  }
}

Understanding the Output

Assessment

Each domain includes an assessment object:

Summary Metrics

Pass Criteria

For full compliance with email authentication requirements:
- all_enforced should be true
- with_reporting_pct should be 100
- All sending domains should have SPF and DKIM

CI/CD Integration

GitHub Actions

name: Collect Evidence

on:
  schedule:
    - cron: "0 0 * * 1"  # Weekly on Monday
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install epack
        run: |
          curl -sSL https://github.com/locktivity/epack/releases/latest/download/epack-linux-amd64 -o epack
          chmod +x epack
          sudo mv epack /usr/local/bin/

      - name: Collect evidence
        run: epack collect --frozen

      - name: Upload pack
        uses: actions/upload-artifact@v4
        with:
          name: evidence-pack
          path: "*.pack"