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
32 changes: 31 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ can read in full, the daily quiz question and the incident of the day.
| `checklist [name]` | Tick off a checklist; progress is saved |
| `incident [--fix]` | Today's real-world incident, then the fix |
| `play [simulator]` | Open a simulator, a game or Opsville in your browser |
| `check tls\|dns\|headers\|email <target>` | Check a certificate, DNS records, security headers or email records |
| `subscribe` | Open the newsletter sign-up page |
| `sync` | Download the latest content now |
| `update` | Show how to upgrade the way you installed it |
Expand All @@ -65,6 +66,33 @@ Names are forgiving: `devops-daily quiz docker`, `devops-daily play dns` and
`devops-daily read terraform-state` find the closest match or list the
candidates.

## Check a host

Four everyday checks, run from your machine. Each line says what was found
and what it means, and the last line links to a DevOps Daily page on the
topic.

```sh
ddy check tls github.com # certificate, days left, chain, trust
ddy check dns www.github.com --server 1.1.1.1 # records with TTLs, CNAME chain
ddy check headers devops-daily.com # redirects, security and cache headers
ddy check email gmail.com # MX, SPF, DMARC, DKIM, MTA-STS, TLS-RPT
```

```text
$ ddy check tls expired.badssl.com
...
fail Expires in expired 4234 days ago (2015-04-12 23:59 UTC)
Browsers block the site with a warning page. Renew the certificate now.
fail Trusted no, a certificate in the chain has expired or is not valid yet
...
Result: 2 problems.
```

Add `--json` for scripts and `--timeout 10s` for slow hosts. Exit codes: 0
all good, 1 warnings, 2 a problem or an error. The checks are not part of
the SSH app. See [docs/check.md](docs/check.md) for what each one looks at.

## Offline use and files

After content has been synced, the CLI works offline. On Linux, the cache is
Expand All @@ -80,7 +108,9 @@ to disable color.

No telemetry. The CLI downloads the public content files from
`devops-daily.com/cli/v1/` and, only when you run `update`, asks GitHub for
the latest version. Nothing about you is sent.
the latest version. The `check` commands talk only to the host you name and
to your DNS resolver (or the one you pick with `--server`). Nothing about
you is sent.

## SSH app

Expand Down
85 changes: 85 additions & 0 deletions cmd/ssh-site/imports_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
package main

import (
"bufio"
"go/parser"
"go/token"
"os"
"path/filepath"
"strconv"
"strings"
"testing"
)

// The check commands connect to any host they are given. In the SSH app
// that would let a visitor make our server connect anywhere, so the server
// must not be able to reach them, not even through another package.
func TestSSHAppCannotReachCheckCommands(t *testing.T) {
root, module := moduleRoot(t)
deps := map[string]bool{}
walkImports(t, root, module, module+"/cmd/ssh-site", deps)
if !deps[module+"/internal/tui"] {
t.Fatalf("import walk found no internal/tui, so it is broken: %v", deps)
}
for _, banned := range []string{module + "/internal/check", module + "/internal/cli"} {
if deps[banned] {
t.Errorf("cmd/ssh-site imports %s; the network checks must stay out of the SSH app", banned)
}
}
}

func moduleRoot(t *testing.T) (string, string) {
t.Helper()
dir, err := os.Getwd()
if err != nil {
t.Fatal(err)
}
for {
if file, err := os.Open(filepath.Join(dir, "go.mod")); err == nil {
defer file.Close()
scanner := bufio.NewScanner(file)
for scanner.Scan() {
if module, ok := strings.CutPrefix(strings.TrimSpace(scanner.Text()), "module "); ok {
return dir, strings.TrimSpace(module)
}
}
t.Fatal("go.mod has no module line")
}
parent := filepath.Dir(dir)
if parent == dir {
t.Fatal("go.mod not found")
}
dir = parent
}
}

// walkImports records every package of this module that pkg imports,
// directly or not. Test files do not count; files for every OS do.
func walkImports(t *testing.T, root, module, pkg string, seen map[string]bool) {
t.Helper()
dir := filepath.Join(root, filepath.FromSlash(strings.TrimPrefix(pkg, module)))
entries, err := os.ReadDir(dir)
if err != nil {
t.Fatal(err)
}
for _, entry := range entries {
name := entry.Name()
if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
continue
}
file, err := parser.ParseFile(token.NewFileSet(), filepath.Join(dir, name), nil, parser.ImportsOnly)
if err != nil {
t.Fatal(err)
}
for _, spec := range file.Imports {
path, err := strconv.Unquote(spec.Path.Value)
if err != nil {
t.Fatal(err)
}
if (path == module || strings.HasPrefix(path, module+"/")) && !seen[path] {
seen[path] = true
walkImports(t, root, module, path, seen)
}
}
}
}
175 changes: 175 additions & 0 deletions docs/check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
# Check commands

`devops-daily check` (or `ddy check`) looks at a host from your own machine
and says, in plain words, what it found:

| Command | What it checks |
| --- | --- |
| `check tls <host[:port]>` | TLS version, cipher, the certificate (names, issuer, dates, days left), the chain, trust, host name match, OCSP stapling |
| `check dns <name>` | A, AAAA, MX, NS, TXT and CAA records with TTLs, and the CNAME chain |
| `check headers <url>` | Each redirect, then the security headers and cache headers of the final response |
| `check email <domain>` | MX, SPF, DMARC, DKIM, MTA-STS and TLS-RPT records |

Every line has a status:

| Status | Meaning |
| --- | --- |
| `pass` | Looks right |
| `info` | Just information |
| `warn` | Works, but worth fixing |
| `missing` | Not set, and it should be |
| `fail` | Broken, or the check could not run |

## Flags and exit codes

All four commands take:

- `--json`: print the report as JSON for scripts. `details` has the raw
data (for example `details.daysLeft` for TLS) and `sections` has every
finding with a stable `id`.
- `--timeout 5s`: how long to wait for each network reply. For `check
headers` it covers each request, including its connect and TLS handshake.

Exit codes: `0` all good, `1` warnings (`warn` or `missing`), `2` a
problem (`fail`) or an error, such as a host that does not resolve or a bad
argument.

```sh
ddy check tls example.com --json | jq .details.daysLeft
ddy check tls example.com >/dev/null || echo "fix the certificate"
```

## What leaves your machine

Only what the check needs: a connection to the host you name, and DNS
questions to your system resolver (the first `nameserver` in
`/etc/resolv.conf`) or the server you pick with `--server`. No telemetry and
no request to devops-daily.com. Where `/etc/resolv.conf` cannot be read (on
Windows, for example), DNS questions go to `1.1.1.1` and the report says so.
`check headers` sends `User-Agent: devops-daily-cli/<version> (check
headers)`.

On macOS and Windows, Go asks the operating system to verify certificate
chains, and the operating system may fetch a missing intermediate
certificate itself.

International names work in any check: `bücher.de` is looked up, sent as
the TLS server name and matched against the certificate as
`xn--bcher-kva.de`, and the report shows both forms.

## check tls

```sh
ddy check tls github.com
ddy check tls smtp.gmail.com:465
```

The port defaults to 443, and a pasted URL works too. The check connects
without trusting the certificate first, so that a bad one is reported
instead of stopping the check; then it verifies the chain against your
system's trusted roots and the host name separately. It warns when the
certificate expires in 21 days or less: lifetimes are getting shorter (Let's
Encrypt moves to 64 days in February 2027, later 45), so renewal must be
automatic. TLS 1.0 and 1.1 are a `fail`. A missing OCSP staple is only
`info`, since Let's Encrypt ended OCSP in 2025.

## check dns

```sh
ddy check dns devops-daily.com
ddy check dns www.github.com --type CNAME,A --server 1.1.1.1
```

`--type` takes `A`, `AAAA`, `CNAME`, `MX`, `NS`, `TXT`, `CAA` or `SOA`
(repeat it or separate with commas). Without it you get A, AAAA, MX, NS,
TXT and CAA. `--server` takes an IP address, with an optional port. TTLs
from a caching resolver count down; ask the zone's own name server (see the
NS records) for the full value.

A name that does not exist is a `fail`, and so is an alias whose target is
gone (a dangling CNAME, which someone may be able to take over), a CNAME
loop, or a chain of 16 or more aliases. The chain is followed to its end even
when the resolver stops early, as it does for `--type CNAME`. With the
default types, a name with no A or AAAA records is a `warn`; with `--type`,
a type with no records is a `warn`.

## check headers

```sh
ddy check headers devops-daily.com
ddy check headers http://example.com/login
```

`https://` is added when there is no scheme. Redirects (301, 302, 303, 307
and 308; not 300 or 304) are followed one at a time, at most 10, and each
hop is shown with its status and target. A
loop, too many redirects or an untrusted certificate is a `fail`; a
redirect from HTTPS to plain HTTP is a `warn`.

The final response's headers:

| Header | `pass` when |
| --- | --- |
| `Strict-Transport-Security` | `max-age` is 180 days or more and no directive appears twice |
| `Content-Security-Policy` | `script-src`, `script-src-elem` and `script-src-attr` (each falling back to `script-src`, then `default-src`) allow no `'unsafe-inline'` without a nonce or hash, and no `'unsafe-eval'`, `*`, `http:`, `https:`, `https://*` or `data:` |
| `X-Content-Type-Options` | `nosniff` |
| `X-Frame-Options` or CSP `frame-ancestors` | `DENY`/`SAMEORIGIN`, or a `frame-ancestors` with no wildcard source in at least one policy |
| `Referrer-Policy` | the last valid value, over all the headers, is not `unsafe-url` or `no-referrer-when-downgrade` |
| `Permissions-Policy` | present |

A missing HSTS (on HTTPS), CSP, `X-Content-Type-Options` or frame protection
is `missing`. A missing `Referrer-Policy` or `Permissions-Policy` is only
`info`: browsers default to `strict-origin-when-cross-origin`, and
`Permissions-Policy` is optional. With several CSP headers the browser
enforces all of them, so the strictest one counts.

`Cache-Control`, `Age`, `ETag` and `Server` are shown as `info`, with what
they mean for caches. There are no grades.

## check email

```sh
ddy check email gmail.com
ddy check email example.com --selector mailjet --server 8.8.8.8
```

An email address or a URL works too; only the domain is used.

- **SPF**: there must be one `v=spf1` record. Like a receiver, the check
stops at the first `all` and uses `redirect=` only when there is no `all`.
It counts the DNS lookups that needs (`include`, `a`, `mx`, `ptr`,
`exists` and an evaluated `redirect`, nested includes too) against the
limit of 10. These are a `fail` (receivers return permerror): over 10
lookups, an `mx` with more than 10 MX hosts, a bad `ip4`/`ip6` address or
prefix length, an unknown mechanism, and an include with no SPF record.
`+all` is a `fail`, `?all` or no `all` a `warn`, `ptr` a `warn`
(deprecated). An `include` or `redirect` with macros (`%{d}`) is a `warn`:
it is filled in per message, so the count cannot be checked.
- **DMARC**: one record at `_dmarc.<domain>` whose first tag is
`v=DMARC1`, exactly in that case (spaces around `=` are fine). `p=none` is
a `warn` (monitoring only), and so is a missing `rua` (no reports). A
`pct` under 100 is a `warn`: the updated standard (DMARCbis) drops `pct`,
and `t=y` is the new testing switch. With `t=y`, receivers apply one step
less: `reject` becomes `quarantine`, `quarantine` becomes `none`.
- **DKIM**: keys cannot be listed, so the check tries common selectors:
`default`, `google`, `selector1`, `selector2`, `k1`, `s1`, `mail` and
`dkim`. Finding none is only `info`: many providers (Amazon SES, for
example) use their own selector names. Add yours with `--selector` (find
it as `s=` in the `DKIM-Signature` header of a mail you received). RSA keys
under 2048 bits are a `warn`, under 1024 a `fail`. A malformed record is a
`fail`: `v=` that is not first or not `DKIM1`, no `p=`, a key that does not
decode, an unknown `k=` or a tag given twice. An empty `p=` means the key
was revoked on purpose (`info`).
- **MTA-STS** (`_mta-sts.<domain>`) and **TLS-RPT** (`_smtp._tls.<domain>`)
are optional. When present there must be one record each, MTA-STS with an
`id=` (1 to 32 letters and digits) and TLS-RPT with a `rua=`; otherwise
senders ignore them, which is a `fail`. The MTA-STS policy file itself is
not downloaded.

## Not in the SSH app

The check commands exist only in the local CLI. In the SSH app
(`ssh ssh.devops-daily.com`) they would make our server connect to any host
a visitor typed. `cmd/ssh-site/imports_test.go` fails if the server ever
imports `internal/check` or `internal/cli`, directly or through another
package.
7 changes: 6 additions & 1 deletion docs/ssh-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,11 @@ Built with [Wish](https://github.com/charmbracelet/wish) and
- The app never queries the client terminal (no OSC or DA requests); colors
come from `TERM` alone. All feed, quiz and config text is stripped of
control codes before it is drawn.
- The app never makes a network request on a visitor's behalf. The CLI's `check`
commands (TLS, DNS, headers, email) are left out on purpose: here they
would make the server connect to any host a visitor typed.
`cmd/ssh-site/imports_test.go` fails if the server imports `internal/check`
or `internal/cli`, directly or through another package.

Limits (flags on the binary, defaults shown):

Expand Down Expand Up @@ -85,7 +90,7 @@ because a wildcard bind would clash with sshd on the tailnet address.
Needs Go 1.26 or newer.

```sh
make test # unit tests: date picks, feed cache, limits, server hardening, UI layout
make test # unit tests: date picks, feed cache, limits, server hardening, UI layout, no check imports
make build # static linux/amd64 binary in bin/ssh-site
make run # local copy on 127.0.0.1:2222; then: ssh -p 2222 localhost
```
Expand Down
3 changes: 2 additions & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,12 @@ require (
github.com/charmbracelet/wish v1.4.7
github.com/charmbracelet/x/ansi v0.11.6
github.com/charmbracelet/x/term v0.2.2
github.com/miekg/dns v1.1.73
github.com/muesli/termenv v0.16.0
github.com/spf13/cobra v1.10.2
github.com/yuin/goldmark v1.7.13
golang.org/x/crypto v0.58.0
golang.org/x/net v0.60.0
)

require (
Expand Down Expand Up @@ -54,7 +56,6 @@ require (
github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
github.com/yuin/goldmark-emoji v1.0.6 // indirect
golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect
golang.org/x/net v0.60.0 // indirect
golang.org/x/sys v0.49.0 // indirect
golang.org/x/term v0.47.0 // indirect
golang.org/x/text v0.43.0 // indirect
Expand Down
4 changes: 4 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byF
github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
github.com/miekg/dns v1.1.73 h1:uhT8nJxmTrPJYClxVxTCX+CVn6qnzSiybRk72Z6DgrE=
github.com/miekg/dns v1.1.73/go.mod h1:RW2Obtfd5NZHvOFe3zYG0W8koWOQtAzyHaLo8vASBuQ=
github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
Expand Down Expand Up @@ -118,6 +120,8 @@ golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0
golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY=
golang.org/x/net v0.60.0 h1:79p50tfZlm0J9YfoDsSi639qSXNGVwEzOPLCxM2FsYU=
golang.org/x/net v0.60.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg=
golang.org/x/sync v0.24.0 h1:iqiDrGoDgyuvAKrhLQthUEzU/R378N78gXbBjxed7oA=
golang.org/x/sync v0.24.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA=
Expand Down
Loading
Loading