
testssl-inspector
GRC connector wrapping testssl.sh: TLS/SSL protocol, cipher, certificate, and known-CVE checks on HTTPS endpoints → v1 finding contract
- version
- 0.1.0
- GitHub stars
- 436
Install
/plugin install testssl-inspector@grc-engineering-suiteRun it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.
Contents
Discovered from sourceSkills 1
testssl Inspector Expert
Use this skill when reviewing findings produced by /testssl-inspector:scan. The connector wraps testssl.sh and emits v1 Findings against tls_endpoint resources; this skill translates those into remediation advice an engineer can act on and audit evidence a reviewer can sign off.
Reading the output
Findings live at ~/.cache/claude-grc/findings/testssl-inspector/<run_id>.json. Each document covers one TLS endpoint:
resource.type = "tls_endpoint",resource.id = "<host>:<port>",resource.uri = "https://<host>:<port>/"for HTTPS orresource.uri = "starttls+<proto>://<host>:<port>/"for STARTTLS scansevaluations[]— one entry per (control_framework, control_id, testssl finding) tuplefindings[]— narrative roll-up for CVEs and critical results (cap 50 per doc)metadata.target,metadata.effective_target,metadata.host,metadata.port,metadata.starttls— the original input, the port-expanded target actually scanned, the parsed host/port, and the STARTTLS protocol when applicable
What testssl IDs mean
Most fails fall into one of five families. The remediation pattern is the same within each family.
Family 1 — Weak protocol offered
IDs: SSLv2, SSLv3, TLS1, TLS1_1. SCF anchors: CRY-01 (Use of Cryptographic Controls), CRY-03 (Transmission of Sensitive Data), NET-09 (Session Authenticity). SCF crosswalk fans these out at scan time — typical resolved targets include NIST SC-08, SC-08(01), SC-08(02), SC-13, SC-23, SI-07(06); SOC 2 CC6.1, CC6.7; PCI 4.2, 4.2.1, 4.2.1.2, 8.3.2; ISO 27002 5.14, 8.24, 8.26.
Remediation:
- Terminate TLS at a load balancer or web server that supports a TLS 1.2+ minimum. AWS ALB: set the security policy to
ELBSecurityPolicy-TLS-1-2-2017-01or newer. NGINX:ssl_protocols TLSv1.2 TLSv1.3;. Apache:SSLProtocol -all +TLSv1.2 +TLSv1.3. - PCI DSS 4.0.1 specifically prohibits SSL and "early TLS" (1.0/1.1) — these are audit-fail conditions, not advisories.
Family 2 — Weak ciphers in the offered list
IDs: cipher_negotiated, cipherlist_* (NULL, aNULL, EXPORT, LOW, 3DES_IDEA, OBSOLETED), RC4, std_* variants. SCF anchors: CRY-01.2 (Algorithm Selection), CRY-05 (Cryptographic Protection). Resolved targets typically include NIST SC-13, SC-28, SC-28(01); SOC 2 CC6.1, CC6.7; PCI 3.5, 3.5.1.2, 3.5.1.3, 8.3.2; ISO 27002 8.24.
Remediation:
- Pin an explicit cipher list. Modern baseline:
TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384. - Prefer forward-secrecy ciphers (ECDHE/DHE families). Anything without
(EC)DHEshould be disabled in 2026.
Family 3 — Certificate posture
IDs: cert_expirationStatus, cert_notAfter, cert_signatureAlgorithm, cert_keySize, cert_chain_of_trust, OCSP_*, CT, DNS_CAArecord. SCF anchor: CRY-08 (Public Key Infrastructure). Resolved targets include NIST SC-12 (Key Establishment & Management) and SC-17 (PKI Certificates); SOC 2 CC6.1.
Remediation depends on the specific failure:
- Expired / near-expiry: rotate via ACM (AWS), Let's Encrypt, or your CA portal. Set up rotation alerts at T-30, T-14, T-7 days.
- Weak signature (SHA-1, MD5): reissue with SHA-256+ signature.
- Weak key size (RSA <2048): reissue with RSA 2048+ or ECDSA P-256+.
- Broken chain: server is missing an intermediate. Re-deploy the cert bundle with the full chain (your CA's portal shows the bundle order).
- No CAA record: add a
CAADNS record naming your authorized issuer(s) — defense against unauthorized certificate issuance.
Family 4 — Known TLS CVEs
IDs: heartbleed, CCS, ticketbleed, ROBOT, secure_renego, secure_client_renego, CRIME_TLS, BREACH, POODLE_SSL, fallback_SCSV, SWEET32, FREAK, DROWN, LOGJAM, BEAST, LUCKY13, RC4, winshock. SCF anchors: VPM-01 (Vulnerability & Patch Management), VPM-06 (Vulnerability Scanning). Resolved targets include NIST SI-02, SI-03, RA-05; SOC 2 CC7.1 and CC3.x POFs; PCI 6.3, 6.3.1, 6.3.3, 11.3, 11.3.1; ISO 27002 8.8.
These are not configuration tuning — they're vulnerability remediation. Treat any non-OK finding here as an audit-tracked vuln with a remediation deadline. Most are addressed by:
- Patching OpenSSL / the TLS implementation on the server.
- Disabling vulnerable protocols/ciphers (e.g., POODLE → drop SSLv3; SWEET32 → drop 3DES/Blowfish; BEAST → use TLS 1.2+).
- For BREACH (HTTP-layer): disable HTTP compression for responses containing sensitive data, or add a per-request masking token.
Family 5 — HTTP transport headers
IDs: HSTS, HSTS_preload, HSTS_time, HPKP, cookie_secure, cookie_httponly, banner_*, security_headers. SCF anchors: CRY-03 (Transmission of Sensitive Data), WEB-03 (Web App Hardening), NET-09 (Session Authenticity). Resolved targets include NIST SC-08, SC-08(01), SC-07(17), SC-23; PCI 4.2, 6.4, 6.4.1.
Remediation:
- HSTS missing or short max-age:
Strict-Transport-Security: max-age=31536000; includeSubDomains; preloadand submit to the HSTS preload list (hstspreload.org) for the strongest posture. - Cookies without
SecureorHttpOnly: fix the application — set both flags on every session cookie. - HPKP: deprecated; if testssl flags HPKP usage, plan to remove it (browsers no longer enforce).
Evidence packaging
For an audit, the auditor wants three things per finding:
- The raw testssl JSON or its normalized v1 doc (already in
~/.cache/claude-grc/findings/testssl-inspector/<run_id>.json). - The scan timestamp (
collected_atfield). - A remediation narrative tying each failed evaluation to a specific control and a future check.
Workflow:
/testssl-inspector:scan --target=auth.example.com --target=api.example.com
# Inspect the resulting findings file. Attach it to the audit evidence packet
# alongside the remediation tickets opened for each fail.
/grc-engineer:gap-assessment SOC2,PCI-DSS --sources=testssl-inspector
# Aggregates testssl evaluations with your other connector outputs into a
# control-by-control posture view.
What you will not do
- Don't run testssl against endpoints you don't own or are not authorized to test. testssl makes hundreds of connections per target and looks like a scanner to defenders.
- Don't recommend ignoring a fail because "the application is internal." TLS 1.0/1.1 and weak ciphers are no less broken on intranets.
- Don't recommend disabling individual checks just because they're noisy. If a check produces too many false positives, raise an issue against this connector with the testssl
idand reasoning so we can refine the mapping table. - Don't claim a finding maps to a framework beyond the five listed in
scan.md. If a user asks about SP 800-52 Rev. 2 specifically, point them at the relevant framework plugin instead.
Commands 3
/testssl-inspector:scan
Wraps testssl.sh, normalizes its JSON output into the toolkit's v1 finding contract, and writes one document per target.
How to run
node plugins/connectors/testssl-inspector/scripts/scan.js [options]
Options
--target=host[:port]— repeatable; or pass targets positionally. Port defaults to 443 for HTTPS, or the protocol's default port when--starttls=<proto>is used.--starttls=<proto>— enable STARTTLS for the specified protocol. Supported protocols:smtp(25),imap(143),pop3(110),ftp(21),ldap(389),postgres(5432),mysql(3306). When--starttls=<proto>is specified without an explicit port in the target, the target is automatically appended with the protocol's default port. For example,--target=mail.example.com --starttls=smtpbecomesmail.example.com:25. If the target already includes an explicit port (e.g.,--target=mail.example.com:587 --starttls=smtp), the explicit port is preserved. Implicit TLS services such as SMTPS on 465 should be scanned as normal TLS endpoints without--starttls.--fast—testssl.sh --fast(~3× faster, drops vulnerability checks).--full— full check set (default). Slower; includes CVE checks (Heartbleed, ROBOT, POODLE, BEAST, BREACH, SWEET32, FREAK, LOGJAM, DROWN, …).--docker/--no-docker— override the runner choice from the config.--scf-only— emit only SCF evaluations; skip fan-out to NIST/SOC2/PCI/ISO. Smaller output, no network. Useful for CI or air-gapped environments.--offline— never make network calls. Uses cached SCF crosswalks if present (under~/.cache/claude-grc/scf/<version>/); otherwise falls back to the hardcoded framework table. testssl itself still has to reach the target.--output=summary|silent|json— defaultsummaryprints counts to stdout;jsonemits machine-readable run info;silentwrites the cache file and nothing else.--quiet— suppress stderr progress lines.
What it evaluates
Each testssl.sh finding is mapped first to one or more SCF (Secure Controls Framework) control IDs, then fanned out to downstream frameworks via the SCF crosswalk at https://grcengclub.github.io/scf-api/. Crosswalks are cached at ~/.cache/claude-grc/scf/<version>/ (shared with the grc-engineer plugin's SCF client) and refreshed every 7 days.
| testssl finding family | SCF anchors |
|---|---|
| Weak protocols (SSLv2/3, TLS 1.0/1.1) | CRY-01, CRY-03, NET-09 |
| Weak ciphers (NULL, EXPORT, 3DES, RC4, anon) | CRY-01.2, CRY-05 |
| Certificate posture (expiry, signature, chain, key size, OCSP, CT) | CRY-08 |
| Known CVEs (Heartbleed, ROBOT, POODLE, SWEET32, FREAK, LOGJAM, DROWN, BEAST, LUCKY13, …) | VPM-01, VPM-06 |
| HTTP transport headers (HSTS, HPKP, cookie flags) | CRY-03, WEB-03, NET-09 |
The SCF crosswalk fan-out resolves each anchor to its equivalent controls in:
- NIST 800-53 r5 (e.g.
CRY-01→SC-08(01),SC-08(02),SC-13,SI-07(06)) - SOC 2 TSC 2017 (CC-family controls and POFs)
- PCI DSS 4.0.1 (§4 cryptography, §6 vulnerability management, §11 testing)
- ISO 27002:2022 (technical Annex A catalog — same numbering as ISO 27001:2022 Annex A, but the 27002 crosswalk has the technical depth; SCF's 27001:2022 crosswalk is sparse)
If the SCF mirror is unreachable (network error, --offline with no cache), the script falls back to a curated hardcoded table that covers the same five frameworks at one canonical control per family. This is the v0 behavior; you'll see a (scf expansion unavailable; framework fallback used) note in the summary line when it kicks in.
Severity translation: testssl FATAL/CRITICAL → critical; HIGH → high; WARN/MEDIUM → medium; LOW → low; OK/INFO → info (and pass for status). Anything else → inconclusive.
Output
-
~/.cache/claude-grc/findings/testssl-inspector/<run_id>.json -
One Finding doc per target with
resource.type = "tls_endpoint",resource.id = "<host>:<port>", andresource.uri = "https://<host>:<port>/"for HTTPS orresource.uri = "starttls+<proto>://<host>:<port>/"for STARTTLS scans. -
Critical findings and any with a CVE are also lifted into a
findings[]narrative array for quick triage. -
Summary printed to stdout unless
--output=silent:testssl-inspector: 2 targets, 2 resources, 47 evaluations, 9 failing (1 critical, 3 high, 4 medium, 1 low). → /home/.../<run_id>.json
Exit codes
0— clean run, no scan errors2— usage error (missing target)3— testssl.sh / docker unavailable (or every target failed)4— partial run (some targets failed but at least one succeeded)5— not configured (no config file and no--targetprovided)
Examples
# Fast scan of one HTTPS endpoint
/testssl-inspector:scan --target=example.com --fast
# Full vulnerability scan against two HTTPS endpoints, Docker runner
/testssl-inspector:scan --target=example.com --target=api.example.com:8443 --docker
# STARTTLS scan of SMTP service with default port
/testssl-inspector:scan --target=mail.example.com --starttls=smtp --output=json
# STARTTLS scan of SMTP service with explicit port
/testssl-inspector:scan --target=mail.example.com:587 --starttls=smtp --output=json
# STARTTLS scan of IMAP service
/testssl-inspector:scan --target=mail.example.com --starttls=imap --output=json
# Implicit TLS SMTPS service (no STARTTLS flag)
/testssl-inspector:scan --target=mail.example.com:465 --output=json
# Pipe summary into another step
/testssl-inspector:scan --target=example.com --output=json | jq '.counters'
Targets and scope
- HTTPS endpoints by default. STARTTLS services are supported through the
--starttls=<proto>flag for protocols including SMTP, IMAP, POP3, FTP, LDAP, PostgreSQL, and MySQL. Implicit TLS endpoints such as SMTPS are regular TLS scans on their implicit-TLS port. - Scanning runs on the local machine and requires outbound network reach to the target. Not suitable for endpoints behind a private network unless the runner has access.
- Be courteous: testssl makes a couple hundred connections per target. Don't point it at infrastructure you don't own without authorization.
/testssl-inspector:setup
One-time configuration step. Verifies testssl.sh is reachable, captures its version, and seeds a config file with any targets you pass.
How to run
bash plugins/connectors/testssl-inspector/scripts/setup.sh [options]
Options
--docker— use thedrwetter/testssl.shDocker image instead of a native binary. Pulls the image if not already present.--target=host[:port]— repeatable; pre-populate the targets list. Port defaults to 443.
What it does
- Locates
testssl.sh— checks$PATH, then~/.local/share/testssl.sh/testssl.sh,/opt/testssl.sh/testssl.sh,/usr/local/bin/testssl.sh. - If not found and
--dockernot passed, prints install instructions and exits with code 3. - Captures the testssl version.
- Writes
~/.config/claude-grc/connectors/testssl-inspector.yamlwith:use_dockerandtestssl_pathtestssl_versiontargets:list (empty if not provided)
- Creates the cache dir
~/.cache/claude-grc/findings/testssl-inspector/.
Install paths
| OS / approach | Command |
|---|---|
| macOS (Homebrew) | brew install testssl |
| Debian / Ubuntu | sudo apt-get install -y testssl.sh |
| From source | git clone https://github.com/testssl/testssl.sh ~/.local/share/testssl.sh && export PATH="$HOME/.local/share/testssl.sh:$PATH" |
| Docker (no install) | run /testssl-inspector:setup --docker and the plugin will use the image |
Exit codes
0success2unknown flag3testssl.sh and Docker both unavailable
Examples
# Native testssl on PATH, no targets yet
/testssl-inspector:setup
# Docker-based, pre-load two targets
/testssl-inspector:setup --docker --target=example.com --target=api.example.com:8443
Next
/testssl-inspector:scan --target=example.com
/testssl-inspector:status
/testssl-inspector:status
Quick health check.
How to run
bash plugins/connectors/testssl-inspector/scripts/status.sh
What it shows
- Runner (
nativevsdocker) and the binary path if native - testssl.sh version captured at setup
- Config file path
- Configured target count
- Cache directory + number of scans on disk
- Filename of the latest scan, if any
Exit codes
0configured and reachable5not configured — run/testssl-inspector:setupfirst
Sponsors
Details
- Marketplace
- GRCEngClub/claude-grc-engineering
- Source
- plugins/connectors/testssl-inspector
- Category
- Community
More from GRCEngClub/claude-grc-engineering
All 70- trust-centerv0.1.0
- us-ccpav0.1.0
- us-exportv0.1.0
- us-finrav0.1.0
- us-hipaa-securityv0.1.0
- us-nerc-cipv0.1.0
- us-soxv0.1.0
- vault-kvv0.1.0
- wiz-inspectorv0.1.0
- academic-research-companionv0.1.0
- au-apra-cps-234v0.1.0
- aws-inspectorv0.1.0
- aws-secrets-inspectorv0.1.0
- azure-inspectorv0.1.0
- ch-fadpv0.1.0
- cis-controlsv0.1.0
- cmmcv0.1.0
- compliance-posture-dashboardv0.1.0
- crowdstrike-inspectorv0.1.0
- csa-ccmv0.1.0
- cyber-essentials-plusv0.1.0
- datadog-inspectorv0.1.0
- dorav0.1.0
- drata-inspectorv0.1.0