# Domain Security API

> Compare caller-supplied DNS, certificate, address, ASN, and RPKI snapshots, and review custom-domain onboarding evidence. No network lookups are made.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/domain-security
- Docs: https://www.brainiac.software/api/domain-security/docs
- OpenAPI: https://www.brainiac.software/api/domain-security/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/domain-security/domain-infrastructure-consistency-audit

$0.05 USDC. Compare caller-supplied DNS answers, certificate names, addresses, prefixes, and RPKI results for one domain. audit_status is consistent, inconsistencies_detected, warnings, or incomplete. risk_level is low, medium, high, or critical. No DNS, TLS, WHOIS, or BGP lookup is performed.

Inputs: domain, checkedAt?, snapshot, previous?, expected?, edge?

Docs: https://www.brainiac.software/api/domain-security/docs#domain-security-domain-infrastructure-consistency-audit

Example request:

```json
{
  "domain": "app.example.com",
  "checkedAt": "2026-11-05T00:00:00.000Z",
  "snapshot": {
    "records": [
      {
        "type": "A",
        "name": "app.example.com",
        "value": "198.51.100.8"
      },
      {
        "type": "A",
        "name": "app.example.com",
        "value": "203.0.113.10"
      },
      {
        "type": "CNAME",
        "name": "www.app.example.com",
        "value": "gone.example.net"
      },
      {
        "type": "TXT",
        "name": "gone.example.net",
        "value": "left"
      },
      {
        "type": "NS",
        "name": "example.com",
        "value": "ns1.expected.net"
      },
      {
        "type": "MX",
        "name": "example.com",
        "value": "mail.expected.net",
        "preference": 10
      }
    ],
    "certificates": [
      {
        "sans": [
          "other.example.com"
        ],
        "issuer": "Other CA",
        "notBefore": "2026-01-01T00:00:00.000Z",
        "notAfter": "2026-02-01T00:00:00.000Z",
        "fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ],
    "addresses": [
      {
        "ip": "198.51.100.8",
        "source": "dns"
      },
      {
        "ip": "203.0.113.10",
        "source": "dns"
      },
      {
        "ip": "192.0.2.50",
        "source": "observed"
      }
    ],
    "prefixes": [
      {
        "prefix": "198.51.100.0/24",
        "asn": 64501,
        "rpki": "invalid"
      },
      {
        "prefix": "203.0.113.0/24",
        "asn": 64500,
        "rpki": "valid"
      }
    ],
    "owners": [
      {
        "ip": "198.51.100.8",
        "asn": 64501,
        "provider": "Other Net"
      },
      {
        "ip": "203.0.113.10",
        "asn": 64500,
        "provider": "Example Host"
      }
    ]
  },
  "previous": {
    "records": [
      {
        "type": "A",
        "name": "app.example.com",
        "value": "203.0.113.10"
      },
      {
        "type": "NS",
        "name": "example.com",
        "value": "ns1.expected.net"
      },
      {
        "type": "MX",
        "name": "example.com",
        "value": "mail.expected.net",
        "preference": 10
      }
    ],
    "certificates": [],
    "addresses": [
      {
        "ip": "203.0.113.10",
        "source": "dns"
      }
    ],
    "prefixes": [
      {
        "prefix": "203.0.113.0/24",
        "asn": 64500,
        "rpki": "valid"
      }
    ],
    "owners": [
      {
        "ip": "203.0.113.10",
        "asn": 64500,
        "provider": "Example Host"
      }
    ]
  },
  "expected": {
    "providers": [
      "Example Host"
    ],
    "asns": [
      64500
    ],
    "ranges": [
      "203.0.113.0/24"
    ],
    "names": [
      "app.example.com"
    ],
    "issuers": [
      "Example CA"
    ],
    "nameservers": [
      "ns1.expected.net"
    ],
    "mailHosts": [
      "mail.expected.net"
    ]
  },
  "edge": {
    "providers": [
      "Example Host"
    ],
    "asns": [
      64500
    ],
    "ranges": [
      "203.0.113.0/24"
    ],
    "hosts": [
      "cdn.example.net"
    ]
  }
}
```

Example response:

```json
{
  "audit_status": "inconsistencies_detected",
  "risk_level": "critical",
  "dns_consistency": {
    "status": "inconsistent",
    "names": [
      "app.example.com"
    ],
    "addresses": [
      "198.51.100.8",
      "203.0.113.10"
    ],
    "detail": "app.example.com has 2 supplied address answers. More than one address is not an inconsistency by itself."
  },
  "certificate_consistency": {
    "status": "inconsistent",
    "matched": false,
    "names": [
      "other.example.com"
    ],
    "detail": "No supplied certificate name matches the domain. This compares the supplied names only."
  },
  "ip_asn_consistency": {
    "status": "inconsistent",
    "rows": [
      {
        "ip": "198.51.100.8",
        "prefix": "198.51.100.0/24",
        "asn": 64501,
        "rpki": "invalid",
        "provider": "Other Net",
        "detail": "198.51.100.8 uses supplied prefix 198.51.100.0/24. The result was not looked up."
      },
      {
        "ip": "203.0.113.10",
        "prefix": "203.0.113.0/24",
        "asn": 64500,
        "rpki": "valid",
        "provider": "Example Host",
        "detail": "203.0.113.10 uses supplied prefix 203.0.113.0/24. The result was not looked up."
      },
      {
        "ip": "192.0.2.50",
        "prefix": "",
        "detail": "192.0.2.50 is not inside a supplied prefix."
      }
    ]
  },
  "routing_consistency": {
    "status": "consistent",
    "nameservers": [
      "ns1.expected.net"
    ],
    "mailHosts": [
      "mail.expected.net"
    ],
    "detail": "Nameserver and mail-host comparisons use the supplied records. They are not a live delegation lookup."
  },
  "infrastructure_changes": [
    {
      "kind": "address",
      "name": "app.example.com",
      "previous": "203.0.113.10",
      "current": "198.51.100.8",
      "impact": "unexplained",
      "detail": "198.51.100.8 is in the current supplied answers and not in the previous answers. An address change is not by itself malicious."
    }
  ],
  "unexpected_assets": [
    {
      "kind": "address",
      "value": "192.0.2.50",
      "detail": "192.0.2.50 is an unexplained address in the supplied snapshot. This is not a claim about who operates it."
    }
  ],
  "findings": [
    {
      "code": "cname_dangling",
      "severity": "high",
      "name": "www.app.example.com",
      "detail": "www.app.example.com aliases to gone.example.net, and the supplied records for that name do not provide an address. This is not a live lookup."
    },
    {
      "code": "address_outside_expected",
      "severity": "high",
      "name": "198.51.100.8",
      "detail": "198.51.100.8 is outside the supplied expected ranges and edge ranges. This is not by itself malicious."
    },
    {
      "code": "address_not_in_dns",
      "severity": "high",
      "name": "192.0.2.50",
      "detail": "192.0.2.50 is in the supplied address list and is not a supplied DNS answer for app.example.com. It is not covered by the supplied edge configuration."
    },
    {
      "code": "certificate_name_mismatch",
      "severity": "high",
      "name": "app.example.com",
      "detail": "No supplied certificate name matches app.example.com. This is not a live TLS check."
    },
    {
      "code": "certificate_name_unexpected",
      "severity": "high",
      "name": "app.example.com",
      "detail": "app.example.com is an expected certificate name and is not in the supplied names."
    },
    {
      "code": "issuer_unexpected",
      "severity": "high",
      "name": "Other CA",
      "detail": "Other CA is not one of the supplied expected issuers. This is not a trust-anchor lookup."
    },
    {
      "code": "certificate_expired",
      "severity": "critical",
      "name": "app.example.com",
      "detail": "The supplied certificate end 2026-02-01T00:00:00.000Z is before 2026-11-05T00:00:00.000Z. This uses the supplied timestamps only."
    },
    {
      "code": "asn_unexpected",
      "severity": "high",
      "name": "198.51.100.8",
      "detail": "ASN 64501 for 198.51.100.8 is outside the supplied expected and edge ASNs. This is not a live ownership check."
    },
    {
      "code": "provider_unexpected",
      "severity": "high",
      "name": "198.51.100.8",
      "detail": "Other Net is not one of the supplied expected or edge providers for 198.51.100.8."
    },
    {
      "code": "rpki_invalid",
      "severity": "critical",
      "name": "198.51.100.8",
      "detail": "The supplied RPKI result for 198.51.100.0/24 is invalid. This is not a live BGP check."
    },
    {
      "code": "prefix_unmatched",
      "severity": "high",
      "name": "192.0.2.50",
      "detail": "192.0.2.50 is not inside a supplied prefix. This is not a live routing lookup."
    },
    {
      "code": "snapshot_only",
      "severity": "low",
      "detail": "These records were supplied in the request. No DNS lookup, TLS connection, WHOIS query, or BGP lookup was performed. An address change is not by itself malicious."
    }
  ],
  "limitations": [
    "The audit compares the DNS, certificate, address, prefix, and RPKI values in the request. It does not query DNS, TLS, WHOIS, or BGP.",
    "Missing evidence is incomplete. It is not a confirmed inconsistency.",
    "An address or ASN change is not by itself malicious.",
    "A CDN, proxy, load balancer, or multi-region address is expected only when the request supplies its host, range, ASN, or provider.",
    "A supplied RPKI result is not a live routing validation, and a matching name is not current ownership.",
    "Several addresses for one name are not an inconsistency by themselves."
  ]
}
```

### POST /api/v1/domain-security/infrastructure-health

$0.04 USDC. Look through the supplied DNS records, certificate names, expiry date, and cipher names. A CNAME whose target has no A or AAAA in the snapshot, a certificate that omits the domain, an expiry before the supplied date, a weak cipher name, or a missing NS record raises the exposure. The grade follows that percentage. No DNS or TLS lookup is performed.

Inputs: domain, as_of, records, certificate

Docs: https://www.brainiac.software/api/domain-security/docs#domain-security-infrastructure-health

Example request:

```json
{
  "domain": "app.example.com",
  "as_of": "2026-11-05",
  "records": [
    {
      "type": "A",
      "name": "app.example.com",
      "value": "203.0.113.10"
    },
    {
      "type": "CNAME",
      "name": "www.app.example.com",
      "value": "gone.example.net"
    },
    {
      "type": "NS",
      "name": "example.com",
      "value": "ns1.expected.net"
    }
  ],
  "certificate": {
    "names": [
      "other.example.com"
    ],
    "not_after": "2026-02-01",
    "ciphers": [
      "TLS_RSA_WITH_AES_128_CBC_SHA"
    ]
  }
}
```

Example response:

```json
{
  "infrastructure_health_grade": "F",
  "security_exposure_percentage": 85
}
```

### POST /api/v1/domain-security/custom-domain-onboarding-audit

$0.05 USDC. Compare a custom domain, tenant, ownership TXT records, DNS targets, and platform assignment status. A dangling name is a potential condition only when the supplied assignment is unassigned or deleted. The audit does not query DNS or claim the domain.

Inputs: domain, tenant, verification, records, token, targets, assignments?, previous?, certificates?, checkedAt?, status?

Docs: https://www.brainiac.software/api/domain-security/docs#domain-security-custom-domain-onboarding-audit

Example request:

```json
{
  "domain": "shop.example.com",
  "tenant": "tenant-a",
  "token": "platform-verify-token-shop",
  "status": "removed",
  "checkedAt": "2026-11-05T00:00:00.000Z",
  "verification": [
    {
      "type": "TXT",
      "name": "_verify.shop.example.com",
      "value": "platform-verify-token-shop"
    }
  ],
  "records": [
    {
      "type": "TXT",
      "name": "shop.example.com",
      "value": "platform-verify-token-shop"
    },
    {
      "type": "CNAME",
      "name": "shop.example.com",
      "value": "sites.platform.test"
    }
  ],
  "targets": [
    {
      "kind": "CNAME",
      "value": "sites.platform.test"
    }
  ],
  "assignments": [
    {
      "hostname": "sites.platform.test",
      "tenant": "tenant-a",
      "status": "deleted"
    }
  ],
  "previous": {
    "tenant": "tenant-b",
    "domain": "shop.example.com",
    "status": "active"
  },
  "certificates": [
    {
      "sans": [
        "other.example.com"
      ],
      "issuer": "Example CA",
      "notBefore": "2026-01-01T00:00:00.000Z",
      "notAfter": "2026-02-01T00:00:00.000Z",
      "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}
```

Example response:

```json
{
  "audit_status": "takeover_risk",
  "risk_level": "high",
  "ownership_verification": {
    "status": "matched",
    "records": 2,
    "detail": "A supplied TXT value matches the expected verification token. The token is not repeated here."
  },
  "tenant_binding_status": {
    "status": "conflict",
    "tenant": "tenant-a",
    "previous_tenant": "tenant-b",
    "detail": "A removed domain is still associated with a different active tenant in the supplied records."
  },
  "dns_target_status": {
    "status": "dangling",
    "targets": [
      "sites.platform.test"
    ],
    "detail": "A supplied CNAME points at a platform hostname the caller marked unassigned or deleted. This is not proof of a takeover."
  },
  "dangling_target_findings": [
    {
      "hostname": "sites.platform.test",
      "status": "deleted",
      "detail": "The supplied assignment says this platform hostname is not in use. A dangling name is not proof that the domain can be taken over."
    }
  ],
  "certificate_findings": [
    {
      "code": "certificate_name_mismatch",
      "name": "shop.example.com",
      "detail": "The supplied certificate names do not include this domain. This is an identity mismatch, not a takeover condition."
    },
    {
      "code": "certificate_expired",
      "name": "shop.example.com",
      "detail": "The supplied certificate was expired at checkedAt. This is not a takeover condition."
    }
  ],
  "potential_takeover_conditions": [
    {
      "code": "reusable_binding",
      "hostname": "sites.platform.test",
      "detail": "DNS still points at a platform hostname the caller marked unassigned or deleted. Live platform verification was not performed, so this is a potential condition, not a confirmed takeover."
    }
  ],
  "recommended_actions": [
    {
      "code": "verify_assignment",
      "detail": "Confirm the platform assignment before reusing or repointing the hostname. A dangling DNS target is not proof of a takeover, and this audit did not claim the domain."
    },
    {
      "code": "review_certificate",
      "detail": "Review the supplied certificate name and validity. This comparison does not connect to the domain."
    },
    {
      "code": "review_tenants",
      "detail": "Review the supplied tenant associations before treating the domain as bound to one customer."
    }
  ],
  "limitations": [
    "The audit compares caller-supplied records only. It does not query DNS, HTTP, or TLS, and it does not claim or change a domain.",
    "A dangling DNS target is a potential condition only when the supplied assignment status is unassigned or deleted. It is not proof of a takeover.",
    "A missing TXT record is missing evidence. A TXT record that does not match is a verification failure. Neither one is a takeover condition by itself.",
    "The verification token is not repeated in this result.",
    "Certificate names are compared only when certificate metadata is supplied."
  ]
}
```

### POST /api/v1/domain-security/onboarding-readiness

$0.04 USDC. Compare the supplied TXT name and token, the CNAME target, and a certificate flag. Readiness drops when the token is missing from the expected name, the CNAME does not match the target, or the certificate flag is false. The hijacking index rises when a CNAME points elsewhere, the token sits on another name, or the certificate does not cover the domain. No DNS lookup is performed.

Inputs: domain, token, txt_name, cname_target, certificate_covers_domain, records

Docs: https://www.brainiac.software/api/domain-security/docs#domain-security-onboarding-readiness

Example request:

```json
{
  "domain": "shop.example.com",
  "token": "platform-verify-token-shop",
  "txt_name": "_verify.shop.example.com",
  "cname_target": "sites.platform.test",
  "certificate_covers_domain": false,
  "records": [
    {
      "type": "TXT",
      "name": "shop.example.com",
      "value": "platform-verify-token-shop"
    },
    {
      "type": "CNAME",
      "name": "shop.example.com",
      "value": "other.platform.test"
    }
  ]
}
```

Example response:

```json
{
  "onboarding_readiness_score": 10,
  "hijacking_risk_index": 90
}
```