seo security

Invocation#

echo-cli seo security --origin <https origin> [--sitemap <https url>]...
echo-cli seo certificates watch --host <host or https origin> --warn-days <n> --notify-user <user-id> [--scan-mixed true|false] --by <who>
echo-cli seo certificates list
echo-cli seo certificates unwatch --host <host>
echo-cli seo certificates check

Inputs and output#

security writes origin, certificate (subject, issuer, valid_from, valid_to and days_left, the whole days until it expires, measured now), unreadable (the sitemaps that could not be read), mixed (each page loading plain-http resources, with insecure, the addresses it loads, or with error, what stopped reading it) and checked (how many pages the sitemaps listed). It exits 1 when mixed or unreadable is not empty, and 0 otherwise. certificates watch and unwatch write the watch; list and check write every watch by host: host, warn_days, notify_user, declared_by, declared_at, checked_at, valid_to, days_left, error (why the last read failed, or null), alerted_valid_to (the expiry of the certificate last alerted on), alert_id, scan_mixed, and for a scanning watch mixed (the pages the last run found loading plain http or not read, in security's shape), mixed_checked_at, mixed_error (why the last run failed, or null) and mixed_alert_id; check exits 1 when any read failed.

State effect#

security calls Echo Web's authenticated /api/seo/security and certificates /api/seo/certificates, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Site security section of the GEO screen and of Echo Desktop's GEO screen call the same operations, its Watched certificates part listing, watching (with the daily page scan or not), unwatching and checking all, and echo-mcp runs echo_seo_security and lists the watches as echo_certificate_watches. The certificate is the one the origin's host presents in a TLS handshake on the https port. The pages are those the sitemaps list, as seo deploy-check reads them; a resource counts when an element's src, or a <link>'s href, starts with http:// — an anchor's href is navigation and does not count. security stores nothing. Every day /api/cron/certificates reads each watched host's certificate and keeps when it read it, the expiry and days left, or the error that stopped the read; when the days left are at or below --warn-days, one pending action of type tls_expiry is raised for --notify-user naming the host, the expiry and the issuer. A certificate is known by its expiry: it is alerted once, and a renewed certificate is watched afresh. With --scan-mixed true the same daily run reads https://<host> as security does and keeps the pages loading plain http (or not read) with when it ran, or the error that stopped the run; when such pages appear where the run before found none, one pending action of type mixed_content is raised naming each page and what it loads, so pages that stay are not alerted every day. Watching a host again replaces its window, user and scan.

Refusals#

• A wrong invocation is refused before anything is sent: "seo security does not take <flag>; it takes --origin, --sitemap", "<flag> needs a value", "seo security needs --origin", "seo certificates takes <every verb's usage, separated by semicolons>; got <word>", "seo certificates <verb> does not take <flag>; it takes …" and "seo certificates <verb> needs <flag>".
• Echo Web answers a bad request with "origin is required: the https origin of the site to check, such as https://example.com; got <value>", "host is required: the host whose certificate to watch, or its https origin", "host must be a host name or an https origin; got <value>", "warn_days must be a positive whole number: how many days before the certificate expires the alert is raised; got <value>", "notify_user is required: the id of the user whose pending actions receive the alert; got <value>", "scan_mixed, when given, is true to read the host's sitemap pages for plain-http resources every day or false not to; got <value>" or "declared_by is required: …"; not found with "<origin>/robots.txt declares no sitemap and none was named; name one with sitemap=<https url>" or "no certificate watch names <host>; echo-cli seo certificates lists them"; and fails naming the cause with "the TLS handshake with <host> failed: <cause>" or "<host> presented no certificate in the TLS handshake" — for a watch that sentence is kept as its error instead. --scan-mixed that is not true or false is refused before anything is sent with "--scan-mixed is true or false; got <value>". The command prints Echo Web's sentence and exits 1.