HTTP DNS

The HTTP DNS method authenticates an agent by verifying it controls a given hostname. The agent advertises a hostname and port to the Trust Domain Server; the server issues a nonce challenge and then makes an outbound HTTP request to confirm the agent's endpoint is serving that nonce.

This method proves network-level control of a hostname without requiring cloud provider credentials or hardware.

Attestation Flow

Attributes available for SVID issuance

Attribute	Description
http_dns.hostname	The hostname the agent advertised
http_dns.port	The port the agent advertised

All attributes have the origin http_dns.

Example SPIFFE ID template:

/agents/{{http_dns.hostname}}

How to Deploy

Step 1 — Update cluster configuration (Server)

Configure the allowed hostnames and, optionally, allowed ports in the AgentAttestation policy:

section: AgentAttestation
schema: v1
spec:
  policies:
    - name: my_policy
      requiredAttestors:
        - type: http_dns
          config:
            allowedHostnames:
              - "*.example.com"
            allowedPorts:
              - 7777
              - 8888

Apply it using spirlctl:

spirlctl config set cluster --id <cluster-id> attestation-policy.yaml

Or using Terraform:

resource "spirl_cluster_config" "agent_attestation" {
  cluster_id = spirl_cluster.my_cluster.id
  sections = {
    AgentAttestation = <<-YAML
      section: AgentAttestation
      schema: v1
      spec:
        policies:
          - name: my_policy
            requiredAttestors:
              - type: http_dns
                config:
                  allowedHostnames:
                    - "*.example.com"
                  allowedPorts:
                    - 7777
                    - 8888
    YAML
  }
}

Once a configuration document passes validation and is stored, the Defakto control plane syncs it to your Trust Domain Servers automatically. No server or agent restart is required.

Server Configuration Reference

Field	Required	Description
allowedHostnames	Yes	List of hostnames the agent is allowed to advertise. Wildcards are supported in the leftmost segment (e.g., *.example.com). IP addresses are not allowed.
allowedPorts	No	List of ports the agent is allowed to advertise. When omitted, any port is accepted.

Step 2 — Configure the Agent

Configure the hostname and listening port in the agent's attestation methods.

Helm Installation

agent:
  auth:
    clusterId: c-xxxxxx
    attestors:
      - type: http_dns
        config:
          hostname: p2.example.com   # defaults to system hostname if omitted
          port: 80                   # required; must be a privileged port (≤1024)
          advertisedPort: 8080       # optional; advertised port if behind a proxy or NAT

Linux Installation

cluster-id: c-xxxxxx
agent-attestors:
  - type: http_dns
    config:
      hostname: p2.example.com
      port: 80
      advertisedPort: 8080

Agent Configuration Reference

Field	Required	Default	Description
hostname	No	System hostname	The hostname the agent advertises to the server.
port	Yes	—	The port the agent listens on. Must be a privileged port (≤1024).
advertisedPort	No	port	The port the agent advertises. Useful when behind an HTTP proxy or NAT.

Step 3 — Verify

Server logs — look for these in order:

1. "Login started with multi-attestation support" — confirms the agent offered providedMethods: ["http_dns"]
2. "Authorization received and verified" — includes agentAttestationAttributes with the confirmed hostname:

   {
     "msg": "Authorization received and verified",
     "agentAttestationAttributes": [
       "http_dns:http_dns.hostname=\"p2.example.com\"",
       "http_dns:http_dns.port=\"80\""
     ]
   }

3. "Connected to agent" — session is fully established

Agent logs — enable debug logging to see "Sending Login" with attestors: ["http_dns"]. At the default log level, "Connected to server" confirms the session is live.

Metrics — confirm proofs are succeeding:

spirl_attestation_signer.proof{attestor_type="http_dns",outcome="success"}
spirl_attestation_agent.proof{attestor_type="http_dns",outcome="success"}

Alert on outcome="failed" to detect hostname verification failures.

Common errors:

Error	Likely cause
no cluster policy authorizes the provided attestors	Agent's http_dns method doesn't match any policy in the cluster's AgentAttestation config
hostname H is not in the allowed list	Advertised hostname doesn't match allowedHostnames — check system hostname or configured hostname field
Attestor rejected proof, policy failed	Trust Domain Server couldn't reach the agent's HTTP endpoint to verify the nonce — check network connectivity and port

Security Considerations

HTTP DNS proves the agent controls a specific hostname on the network at attestation time. It does not prove the hardware or cloud identity of the host.

• The Trust Domain Server makes an outbound HTTP request to the agent's hostname and port. Ensure the server has network access to the agent's advertised endpoint.
• Use wildcard hostnames (*.example.com) only when you can verify that your DNS zone is under exclusive organizational control.
• Privileged port requirement (port ≤1024) ensures the agent process has root or CAP_NET_BIND_SERVICE privileges — arbitrary unprivileged processes cannot bind these ports.
• This method should be combined with a second attestation method in environments requiring stronger identity guarantees.

Troubleshooting

hostname H is not in the allowed list — The agent advertised a hostname not in allowedHostnames. If using the system hostname (no hostname configured in the agent), verify the hostname output of the host matches an allowed pattern. If using a custom hostname, confirm it matches a pattern in the policy.

port P is not allowed — The agent advertised a port not in allowedPorts. If using advertisedPort, verify it's in the allowed list. Otherwise, verify the agent's listening port is allowed.