Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions .actor/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Apify Actor image for knock-knock
# (built with the repository root as context, see dockerContextDir in actor.json)

FROM rust:1-slim-bookworm AS builder

# perl and make are needed for building vendored OpenSSL, cmake for aws-lc
RUN apt-get update \
&& apt-get install -y --no-install-recommends cmake make perl \
&& rm -rf /var/lib/apt/lists/*

WORKDIR /src
COPY . .
RUN cargo build --release --locked


FROM node:22-bookworm-slim

RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates jq \
&& rm -rf /var/lib/apt/lists/* \
&& npm install --global apify-cli \
&& npm cache clean --force

COPY --from=builder /src/target/release/knock-knock /usr/local/bin/knock-knock
COPY .actor/main.sh /usr/local/bin/knock-knock-actor

USER node

CMD ["/usr/local/bin/knock-knock-actor"]
102 changes: 102 additions & 0 deletions .actor/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
## What does knock-knock do?

**knock-knock** checks when domain names expire, using the official, standardized registration
data service of domain registries ([RDAP](https://about.rdap.org)), and optionally when their
**TLS certificates** expire too. It also supports **ENS (`.eth`) names**, reading their expiration
straight from Ethereum.

Give it a list of domain names (or URLs) and get back, for each of them:

- 📅 **Expiration date** and days left (negative if already expired)
- 🏢 **Registrar**, its IANA ID and abuse contact
- 🌐 **Name servers** and **DNSSEC** status
- 🔒 **EPP status codes** (e.g. `client transfer prohibited`)
- 🔐 **TLS certificate** expiration, and whether it's trusted (optional)
- ⚠️ A **`needs_attention`** flag for anything expiring soon, untrusted, or failing

## Why use it?

Expired domain names and certificates take websites, email and APIs down, and lapsed domain names
can get picked up by someone else. Run this Actor on a **schedule** (e.g. daily) with your list of
domain names, and connect a **webhook or integration** (Slack, email, Make, Zapier…) to get notified
when something has `needs_attention` set.

## How to use it

1. Enter domain names, one per line: plain names (`example.com`), URLs
(`https://www.example.co.uk/page`), Gemini URLs (`gemini://example.org`) or ENS names (`vitalik.eth`).
Subdomains are checked via their registrable domain name (`www.example.co.uk` → `example.co.uk`).
2. Optionally enable **Check TLS certificates**, and adjust **Needs attention within (days)**.
3. Start the Actor and download results as JSON, CSV, Excel, or access them via the API.

## Input example

```json
{
"domains": ["github.com", "https://www.example.co.uk/", "vitalik.eth"],
"checkCertificates": true,
"warnDays": 30
}
```

## Output example

Each checked name produces one item. Besides the summary fields shown in the table, the full details
are included under `registration` and `certificate`:

```json
{
"input": "github.com",
"domain": "github.com",
"naming_system": "dns",
"registration_status": "registered",
"expires": "2027-10-09T18:20:50Z",
"days_left": 347,
"registrar": "MarkMonitor Inc.",
"nameservers": ["dns1.p08.nsone.net", "ns-1283.awsdns-32.org"],
"certificate_expires": "2027-02-05T23:59:59Z",
"certificate_days_left": 101,
"certificate_trusted": true,
"needs_attention": false,
"error": null,
"registration": {
"status": "registered",
"expires": "2027-10-09T18:20:50Z",
"seconds_left": 29981430,
"registered": "2007-10-09T18:20:50Z",
"statuses": ["client delete prohibited", "client transfer prohibited", "client update prohibited"],
"dnssec": false,
"registrar": { "name": "MarkMonitor Inc.", "iana_id": "292", "abuse_email": "abusecomplaints@markmonitor.com" }
},
"certificate": {
"status": "checked",
"host": "github.com",
"port": 443,
"expires": "2027-02-05T23:59:59Z",
"self_signed": false,
"trusted": true,
"verification_error": null
}
}
```

For ENS names, `registration` also contains `grace_period_ends` (expired ENS names can be renewed
by their owner for 90 more days), and the `owner` and `resolver` addresses.

## FAQ

**Which domain names are supported?**
All top-level domains that offer RDAP, which includes all generic ones (`.com`, `.org`, `.app`…) and
many country-code ones. For the rest, the result contains an error saying no RDAP server is known.

**Is the data reliable?**
It comes straight from registries' official RDAP servers (or from Ethereum for ENS names), not from a
third-party database. Still, keep an eye on important domain names using more than one method.

**Why are some fields empty?**
Registries differ in what they publish, and personal data is usually redacted. Fields that a registry
doesn't provide are `null` (or empty).

**Is it open source?**
Yes, this Actor runs [knock-knock](https://github.com/snshn/knock-knock), an open-source command-line tool,
which you can also use on your own machine.
17 changes: 17 additions & 0 deletions .actor/actor.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"actorSpecification": 1,
"name": "knock-knock",
"title": "Domain Expiration Checker (RDAP, TLS certificates, ENS)",
"description": "Checks when domain names, TLS certificates and ENS (.eth) names expire, and returns registrar, name servers, EPP statuses and DNSSEC info from official RDAP registration records.",
"version": "0.4",
"buildTag": "latest",
"dockerfile": "./Dockerfile",
"dockerContextDir": "../",
"readme": "./README.md",
"input": "./input_schema.json",
"storages": {
"dataset": "./dataset_schema.json"
},
"minMemoryMbytes": 128,
"defaultMemoryMbytes": 256
}
63 changes: 63 additions & 0 deletions .actor/dataset_schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
{
"actorSpecification": 1,
"fields": {
"type": "object",
"properties": {
"input": { "type": "string", "description": "Name as given in the input" },
"host": { "type": ["string", "null"], "description": "Normalized (lowercase, Punycode) host name" },
"domain": { "type": ["string", "null"], "description": "Registrable domain name that was checked" },
"scheme": { "type": ["string", "null"], "description": "Scheme of the given URL, if any" },
"naming_system": { "type": ["string", "null"], "enum": ["dns", "ens", null] },
"registration": { "type": "object", "description": "Registration info, as output by knock-knock --json" },
"certificate": { "type": "object", "description": "TLS certificate info, present when certificates are checked" },
"registration_status": { "type": ["string", "null"], "enum": ["registered", "not_registered", "error", null] },
"expires": { "type": ["string", "null"], "description": "Registration expiration timestamp (RFC 3339)" },
"days_left": { "type": ["integer", "null"], "description": "Days until registration expires (negative if already expired)" },
"registrar": { "type": ["string", "null"] },
"nameservers": { "type": "array", "items": { "type": "string" } },
"certificate_expires": { "type": ["string", "null"], "description": "TLS certificate expiration timestamp (RFC 3339)" },
"certificate_days_left": { "type": ["integer", "null"] },
"certificate_trusted": { "type": ["boolean", "null"] },
"needs_attention": { "type": "boolean", "description": "Expires within the configured number of days, or a check failed" },
"error": { "type": ["string", "null"] }
},
"required": ["input", "registration", "needs_attention"]
},
"views": {
"overview": {
"title": "Overview",
"description": "Expiration at a glance",
"transformation": {
"fields": [
"input",
"registration_status",
"expires",
"days_left",
"registrar",
"nameservers",
"certificate_expires",
"certificate_days_left",
"certificate_trusted",
"needs_attention",
"error"
]
},
"display": {
"component": "table",
"properties": {
"input": { "label": "Name", "format": "text" },
"registration_status": { "label": "Status", "format": "text" },
"expires": { "label": "Expires", "format": "date" },
"days_left": { "label": "Days left", "format": "number" },
"registrar": { "label": "Registrar", "format": "text" },
"nameservers": { "label": "Name servers", "format": "array" },
"certificate_expires": { "label": "Certificate expires", "format": "date" },
"certificate_days_left": { "label": "Certificate days left", "format": "number" },
"certificate_trusted": { "label": "Certificate trusted", "format": "boolean" },
"needs_attention": { "label": "Needs attention", "format": "boolean" },
"error": { "label": "Error", "format": "text" }
}
}
}
}
}
38 changes: 38 additions & 0 deletions .actor/input_schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
{
"title": "knock-knock input",
"description": "Domain names (or URLs) to check. Expiration info comes from official registration records (RDAP), or straight from Ethereum for ENS (.eth) names.",
"type": "object",
"schemaVersion": 1,
"properties": {
"domains": {
"title": "Domain names",
"type": "array",
"description": "Domain names, URLs or ENS names to check, e.g. example.com, https://www.example.co.uk/page, gemini://example.org or vitalik.eth. Subdomains are checked via their registrable domain name.",
"editor": "stringList",
"prefill": ["github.com", "example.co.uk", "vitalik.eth"],
"minItems": 1
},
"checkCertificates": {
"title": "Check TLS certificates",
"type": "boolean",
"description": "Also connect to each host and check when its TLS certificate expires, and whether it's trusted (port 443, the port from the given URL, or 1965 for gemini:// URLs).",
"default": false
},
"warnDays": {
"title": "Needs attention within (days)",
"type": "integer",
"description": "Results are marked with needs_attention = true when the domain name or certificate expires within this many days (or a check fails). Handy for filtering results in integrations and webhooks.",
"minimum": 0,
"maximum": 3650,
"default": 30
},
"ethRpcUrl": {
"sectionCaption": "Advanced",
"title": "Ethereum JSON-RPC endpoint",
"type": "string",
"description": "Used for looking up ENS (.eth) names. Defaults to https://ethereum-rpc.publicnode.com. Note that this is stored as part of the run's input, so avoid URLs containing private API keys.",
"editor": "textfield"
}
},
"required": ["domains"]
}
95 changes: 95 additions & 0 deletions .actor/main.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
#!/usr/bin/env bash
#
# Apify Actor entry point: reads Actor input, runs knock-knock --json,
# adds a few flat summary fields for the Output table, and pushes
# one dataset item per checked name.

set -euo pipefail

log() {
echo "$@" >&2
}

INPUT="$(apify actor get-input)"
if [ -z "${INPUT}" ] || [ "${INPUT}" = "null" ]; then
log "ERROR: No input provided"
exit 1
fi

# Domain names: trimmed, without empty lines
mapfile -t DOMAINS < <(
jq -r '.domains // [] | .[] | strings | gsub("^\\s+|\\s+$"; "") | select(length > 0)' <<< "${INPUT}"
)
if [ "${#DOMAINS[@]}" -eq 0 ]; then
log "ERROR: No domain names provided"
exit 1
fi

ARGS=(--json)
if [ "$(jq -r '.checkCertificates // false' <<< "${INPUT}")" = "true" ]; then
ARGS+=(--check-certificates)
fi
ETH_RPC_URL_INPUT="$(jq -r '.ethRpcUrl // "" | strings' <<< "${INPUT}")"
if [ -n "${ETH_RPC_URL_INPUT}" ]; then
ARGS+=(--eth-rpc-url "${ETH_RPC_URL_INPUT}")
fi
WARN_DAYS="$(jq -r '.warnDays // 30 | if type == "number" and . >= 0 then floor else 30 end' <<< "${INPUT}")"

log "Checking ${#DOMAINS[@]} name(s)..."

# knock-knock exits with 1 when some of the checks failed, but still outputs results for all names
STATUS=0
OUTPUT="$(knock-knock "${ARGS[@]}" -- "${DOMAINS[@]}")" || STATUS=$?

if ! jq -e 'type == "array"' > /dev/null 2>&1 <<< "${OUTPUT}"; then
log "ERROR: knock-knock failed (exit status ${STATUS}) without producing results"
exit 1
fi

# Flat summary fields make the Output table (and CSV/Excel exports) readable,
# the full knock-knock output is kept under "registration" and "certificate"
RESULTS="$(jq --argjson warn_days "${WARN_DAYS}" '
# Whole days, rounded towards zero (expired 3 days and 5 seconds ago means -3)
def days_left:
if . == null then null
elif . < 0 then -(-. / 86400 | floor)
else . / 86400 | floor
end;

# Self-signed certificates are the norm for Gemini capsules
def untrusted_certificate:
.certificate.trusted == false
and ((.scheme == "gemini" or .scheme == "titan")
and .certificate.verification_error == "issued by an unknown certificate authority"
| not);

map(
(.registration.seconds_left // null) as $seconds_left
| (.certificate.seconds_left // null) as $certificate_seconds_left
| . + {
registration_status: (.registration.status // null),
expires: (.registration.expires // null),
days_left: ($seconds_left | days_left),
registrar: (.registration.registrar.name? // null),
nameservers: (.registration.nameservers // []),
certificate_expires: (.certificate.expires // null),
certificate_days_left: ($certificate_seconds_left | days_left),
certificate_trusted: .certificate.trusted,
needs_attention: (
(.registration.status == "error")
or (.registration.error? != null)
or (.certificate.status? == "error")
or ($seconds_left != null and $seconds_left <= $warn_days * 86400)
or ($certificate_seconds_left != null and $certificate_seconds_left <= $warn_days * 86400)
or untrusted_certificate
),
error: (.registration.error // .certificate.error // null)
}
)
' <<< "${OUTPUT}")"

apify actor push-data <<< "${RESULTS}"

log "Done: $(jq 'length' <<< "${RESULTS}") result(s)," \
"$(jq '[.[] | select(.needs_attention)] | length' <<< "${RESULTS}") needing attention" \
"(expiring within ${WARN_DAYS} days, untrusted certificate, or failed check)"
3 changes: 3 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.git
target
storage
Loading