Skip to content

Add STARTTLS protocol support to testssl-inspector #165

Description

@ethanolivertroy

Context

The testssl-inspector connector currently only scans plain HTTPS endpoints (port 443 by default). testssl.sh itself can scan TLS-on-mail-and-other-protocols via its --starttls=<proto> flag, covering SMTP (25, 587), IMAP (143), POP3 (110), FTP (21), LDAP (389), Postgres (5432), MySQL (3306), and a few others. Wiring this through unlocks the plugin for email and database compliance reviews — a real audit need that we currently force users to drop out to the CLI for.

The plugin's README explicitly calls this out as a future addition. Acceptance is well-defined and the surface area is small (touches Node arg parsing + the testssl invocation, no schema changes).

What to do

  1. Add a --starttls=<proto> flag to plugins/connectors/testssl-inspector/scripts/scan.js:
    • Parse it in parseArgs() alongside the other flags.
    • When present, pass --starttls <proto> through to testssl (via the testsslArgs() builder). It should slot in before the target argument.
    • When the user passes --starttls=smtp, default the port to 25 if no explicit port is in the target string. Same for imap143, pop3110, ftp21, ldap389, postgres5432, mysql3306, smtps465. Use a small lookup table.
    • Reject unknown protocol values with an exit code 2 (EXIT.USAGE) and a helpful error.
  2. Update plugins/connectors/testssl-inspector/commands/scan.md to document the new flag with examples (e.g., --target=mail.example.com --starttls=smtp).
  3. Update the "Targets and scope" section of plugins/connectors/testssl-inspector/README.md — it currently says STARTTLS is "not currently wired into this wrapper".
  4. Add an --output=json smoke test you can run locally to confirm the flag is plumbed end-to-end (no need to add a CI test; the existing fixture-based contract test still passes since we're not changing the schema).

Acceptance criteria

  • --starttls=smtp (and the other supported protocols) is accepted and passed to testssl.
  • Unknown protocols fail with exit code 2 and a clear message.
  • Default port defaults to the protocol's standard port when not given (25 for smtp, 143 for imap, etc.).
  • scan.md and README.md are updated.
  • node --check plugins/connectors/testssl-inspector/scripts/scan.js and bash tests/validate-contract-fixtures.sh both pass.

Verification

# These should all parse cleanly even without testssl.sh installed — they'll
# fail at the runner-resolution step, which proves arg parsing got that far.
node plugins/connectors/testssl-inspector/scripts/scan.js --target=mail.example.com --starttls=smtp --no-docker 2>&1 | grep -E 'testssl|starttls'
node plugins/connectors/testssl-inspector/scripts/scan.js --target=mail.example.com --starttls=bogus 2>&1   # should exit 2

Effort

~2–3 hours. Higher per-line ceremony than the other good-first-issues on the board because it touches Node arg parsing, but well-bounded.

Metadata

Metadata

Assignees

No one assigned

    Labels

    connectorNew or improved connector plugin (Tier-1 or Tier-2)difficulty: easy~2-4 hours, self-contained, no deep codebase knowledge requiredgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions