README
¶
Let's Debug
Let's Debug is a diagnostic website, API, CLI and Go package for quickly and accurately finding and reporting issues for any domain that may prevent issuance of a Let's Encrypt SSL certificate for any ACME validation method.
It is motivated by this community thread.
Status
Currently deployed to letsdebug.net and regularly in use.
Problems Detected
| Name | Description | Examples |
|---|---|---|
| InvalidMethod, ValidationMethodDisabled, ValidationMethodNotSuitable | Checks the ACME validation method is valid and usable for the provided domain name. | Example |
| InvalidDomain | Checks the domain is a valid domain name on a public TLD. | Example |
| StatusNotOperational | Checks that the Let's Encrypt service is not experiencing an outage, according to status.io | - |
| DNSLookupFailed, TXTRecordError | Checks that the Unbound resolver (via libunbound) is able to resolve a variety records relevant to Let's Encrypt. Discovers problems such as DNSSEC issues, 0x20 mixed case randomization, timeouts etc, in the spirit of jsha's unboundtest.com | Example |
| CAAIssuanceNotAllowed | Checks that no CAA records are preventing the issuance of Let's Encrypt certificates. | Example |
| CAACriticalUnknown | Checks that no CAA critical flags unknown to Let's Encrypt are used | - |
| RateLimit | Checks that the domain name is not currently affected by any of the domain-based rate limits imposed by Let's Encrypt, using the public certwatch Postgres interface from Comodo's crt.sh. | Example |
| NoRecords, ReservedAddress | Checks that sufficient valid A/AAAA records are present to perform HTTP-01 validation | Example |
| BadRedirect | Checks that no bad HTTP redirects are present. Discovers redirects that aren't accessible, unacceptable ports, unacceptable schemes, accidental missing trailing slash on redirect. | Example |
| WebserverMisconfiguration | Checks whether the server is serving the wrong protocol on the wrong port as the result of an HTTP-01 validation request. | - |
| ANotWorking, AAAANotWorking | Checks whether listed IP addresses are not functioning properly for HTTP-01 validation, including timeouts and other classes of network and HTTP errors. | Example |
| MultipleIPAddressDiscrepancy | For domains with multiple A/AAAA records, checks whether there are major discrepancies between the server responses to reveal when the addresses may be pointing to different servers accidentally. | Example |
| CloudflareCDN | Checks whether the domain is being served via Cloudflare's proxy service (and therefore SSL termination is occurring at Cloudflare) | - |
| CloudflareSSLNotProvisioned | Checks whether the domain has its SSL terminated by Cloudflare and Cloudflare has not provisioned a certificate yet (leading to a TLS handshake error). | Example |
| IssueFromLetsEncrypt | Attempts to detect issues with a high degree of accuracy via the Let's Encrypt v2 staging service by attempting to perform an authorization for the domain. Discovers issues such as CA-based domain blacklists & other policies, specific networking issues. | Example |
| TXTDoubleLabel | Checks for the presence of records that are doubled up (e.g. _acme-challenge.example.org.example.org). Usually indicates that the user has been incorrectly creating records in their DNS user interface. |
Example |
| PortForwarding | Checks whether the domain is serving a modem-router administrative interface instead of an intended webserver, which is indicative of a port-forwarding misconfiguration. | Example |
| SanctionedDomain | Checks whether the Registered Domain is present on the USG OFAC SDN List. Updated daily. | Example |
| BlockedByNginxTestCookie | Checks whether the HTTP-01 validation requests are being intercepted by testcookie-nginx-module. | Example |
| HttpOnHttpsPort | Checks whether the server reported receiving an HTTP request on an HTTPS-only port | Example |
| BlockedByFirewall | Checks whether HTTP-01 validation requests are being blocked by Palo Alto firewall devices | Example |
Web API Usage
There is a JSON-based API available as part of the web frontend.
Submitting a test
$ curl --data '{"method":"http-01","domain":"example.com"}' -H 'content-type: application/json' https://letsdebug.net
{"Domain":"example.com","ID":674477}
Submitting a test with custom options
curl --data '{"method":"http-01","domain":"example.com","options":{"http_request_path":"custom-path","http_expect_response":"abc123"}}' -H 'content-type: application/json' https://letsdebug.net
Available options are as follows:
| Option | Description |
|---|---|
http_request_path |
What path within /.well-known/acme-challenge/ to use instead of letsdebug-test (default) for the HTTP check. Max length 255. |
http_expect_response |
What exact response to expect from each server during the HTTP check. By default, no particular response is expected. If present and the response does not match, the test will fail with an Error severity. It is highly recommended to always use a completely random value. Max length 255. |
Viewing tests
$ curl -H 'accept: application/json' https://letsdebug.net/example.com/674477
{"id":674477,"domain":"example.com","method":"http-01","status":"Complete","created_at":"2021-09-08T04:02:26.416259Z","started_at":"2021-09-08T04:02:26.419336Z","completed_at":"2021-09-08T04:02:30.529766Z","result":{}}
or to view all recent tests
$ curl -H 'accept: application/json' https://letsdebug.net/example.com
Performing a query against the Certwatch database
$ curl "https://letsdebug.net/certwatch-query?q=<urlencoded SQL query>"
{
"query": "select c.id as crtsh_id, x509_subjectName(c.CERTIFICATE), x509_notAfter(c.CERTIFICATE) from certificate c where x509_notAfter(c.CERTIFICATE) = '2018-06-01 16:25:44' AND x509_issuerName(c.CERTIFICATE) LIKE 'C=US, O=Let''s Encrypt%';",
"results": [
{
"crtsh_id": 346300797,
"x509_notafter": "2018-06-01T16:25:44Z",
"x509_subjectname": "CN=hivdatingzimbabwe.com"
},
/* ... */
]
}
CLI Usage
You can download binaries for tagged releases for Linux for both the CLi and the server from the releases page.
letsdebug-cli -domain example.org -method http-01 -debug
Library Usage
import "github.com/letsdebug/letsdebug"
problems, _ := letsdebug.Check("example.org", letsdebug.HTTP01)
Installation
Dependencies
This package relies on a fairly recent version of libunbound.
-
On Debian-based distributions:
apt install libunbound8 libunbound-dev -
On EL-based distributions, you may need to build from source because the packages are ancient on e.g. CentOS, but you can try:
yum install unbound-libs unbound-devel -
On OSX, Homebrew contains the latest version of unbound:
brew install unbound
You will also need Go's dep dependency manager.
Releases
You can save time by downloading tagged releases for 64-bit Linux. Keep in mind you will still need to have libunbound present on your system.
Building
go get -u github.com/letsdebug/letsdebug/...
cd $GOPATH/src/github.com/letsdebug/letsdebug
make clean letsdebug-cli letsdebug-server
Contributing
Any contributions containing JavaScript will be discarded, but other feedback, bug reports, suggestions and enhancements are welcome - please open an issue first.
LICENSE
See LICENSE
Documentation
¶
Overview ¶
Package letsdebug provides an library, web API and CLI to provide diagnostic information for why a particular (FQDN, ACME Validation Method) pair *may* fail when attempting to issue an SSL Certificate from Let's Encrypt (https://letsencrypt.org).
The usage cannot be generalized to other ACME providers, as the policies checked by this package are specific to Let's Encrypt, rather than being mandated by the ACME protocol.
This package relies on libunbound.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// HTTPRequestPath alters the /.well-known/acme-challenge/letsdebug-test to
// /acme-challenge/acme-challenge/{{ HTTPRequestPath }}
HTTPRequestPath string
// HTTPExpectResponse causes the HTTP checker to require the remote server to
// respond with specific content. If the content does not match, then the test
// will fail with severity Error.
HTTPExpectResponse string
}
Options provide additional configuration to the various checkers
type Problem ¶
type Problem struct {
Name string `json:"name"`
Explanation string `json:"explanation"`
Detail string `json:"detail"`
Severity SeverityLevel `json:"severity"`
}
Problem represents an issue found by one of the checkers in this package. Explanation is a human-readable explanation of the issue. Detail is usually the underlying machine error.
func Check ¶
func Check(domain string, method ValidationMethod) (probs []Problem, retErr error)
Check calls CheckWithOptions with default options
func CheckWithOptions ¶
func CheckWithOptions(domain string, method ValidationMethod, opts Options) (probs []Problem, retErr error)
CheckWithOptions will run each checker against the domain and validation method provided. It is expected that this method may take a long time to execute, and may not be cancelled.
func (Problem) DetailLines ¶
type SeverityLevel ¶
type SeverityLevel string
SeverityLevel represents the priority of a reported problem
const ( SeverityFatal SeverityLevel = "Fatal" // Represents a fatal error which will stop any further checks SeverityError SeverityLevel = "Error" SeverityWarning SeverityLevel = "Warning" SeverityDebug SeverityLevel = "Debug" // Not to be shown by default )
type ValidationMethod ¶
type ValidationMethod string
ValidationMethod represents an ACME validation method
const ( HTTP01 ValidationMethod = "http-01" // HTTP01 represents the ACME http-01 validation method. DNS01 ValidationMethod = "dns-01" // DNS01 represents the ACME dns-01 validation method. TLSALPN01 ValidationMethod = "tls-alpn-01" // TLSALPN01 represents the ACME tls-alpn-01 validation method. )
Source Files
Directories