Skip to content
Open
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
34 changes: 26 additions & 8 deletions docs/checks/tls.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,34 +5,52 @@ description: Protocol version, cipher strength/forward secrecy, certificate chai

| Check ID | Title | CVSS 4.0 | CWE | OWASP |
| --- | --- | --- | --- | --- |
| `tls.protocol_version` | Weak TLS Protocol Version Accepted | 5.3 | [CWE-326](https://cwe.mitre.org/data/definitions/326.html) | API8:2023 |
| `tls.cipher_strength` | Weak Cipher Suite or Missing Forward Secrecy | 4.8 | [CWE-327](https://cwe.mitre.org/data/definitions/327.html) | API8:2023 |
| `tls.certificate` | Certificate Chain, Expiry, Hostname, or OCSP Stapling Issue | 5.3 | [CWE-295](https://cwe.mitre.org/data/definitions/295.html) | API8:2023 |
| `tls.https_redirect` | Missing HTTP to HTTPS Redirect | 5.3 | [CWE-319](https://cwe.mitre.org/data/definitions/319.html) | API8:2023 |
| `tls.protocol_version` | Weak TLS Protocol Version Accepted | 6.9 | [CWE-326](https://cwe.mitre.org/data/definitions/326.html) | API8:2023 |
| `tls.cipher_strength` | Weak Cipher Suite or Missing Forward Secrecy | 6.9 | [CWE-327](https://cwe.mitre.org/data/definitions/327.html) | API8:2023 |
| `tls.certificate` | Certificate Chain, Expiry, Hostname, or OCSP Stapling Issue | 6.9 | [CWE-295](https://cwe.mitre.org/data/definitions/295.html) | API8:2023 |
| `tls.https_redirect` | Missing HTTP to HTTPS Redirect | 6.9 | [CWE-319](https://cwe.mitre.org/data/definitions/319.html) | API8:2023 |
| `tls.hsts` | Missing or Weak Strict-Transport-Security Header | 0 (informational) | [CWE-16](https://cwe.mitre.org/data/definitions/16.html) | API8:2023 |

## `tls.protocol_version`

Tests whether the proxy still accepts deprecated TLS versions (TLS 1.0/1.1) alongside modern ones, by forcing a handshake at each deprecated version. Go's `crypto/tls` no longer implements SSLv3, so that version can't be probed directly — but a server still offering it would also offer TLS 1.0/1.1 in virtually every real deployment.
Tests whether the proxy still accepts deprecated protocol versions alongside modern ones, by forcing a handshake at each deprecated version: TLS 1.0 and 1.1 through `crypto/tls`, and SSL 3.0 through a raw ClientHello since `crypto/tls` no longer implements it. Accepted versions are reported together as one observation, code `protocol.legacy_enabled`.

Per-CVE findings (Heartbleed, DROWN, ROBOT) are not probed: they need exploit-specific handshakes, and every affected deployment also enables a legacy protocol or suite reported here.

**Remediate:** disable TLS 1.0/1.1 (and SSLv3) in the proxy's TLS configuration; require TLS 1.2 or later.

## `tls.cipher_strength`

Inspects the negotiated cipher suite for missing forward secrecy (non-ECDHE/DHE key exchange on TLS ≤ 1.2), and separately forces a handshake offering only known-weak cipher suites (RC4, 3DES, CBC-mode) to test whether the server still accepts them.
Inspects the negotiated cipher suite for missing forward secrecy (non-ECDHE/DHE key exchange on TLS ≤ 1.2), and separately forces handshakes offering only weak cipher suites to test whether the server still accepts them: RC4, 3DES and NULL through a raw ClientHello, the other suites Go marks insecure (CBC mode with SHA-256) through `crypto/tls`. A raw handshake offering only DHE suites reads the Diffie-Hellman group size and flags a group below 2048 bits.

**Remediate:** restrict the cipher suite list to modern AEAD suites with ECDHE key exchange (or rely on TLS 1.3, which is always forward-secret).

## `tls.certificate`

Inspects the leaf certificate presented during the TLS handshake:

- **Chain trust** — independently verifies the presented chain against the system trust store and the request hostname.
- **Expiry** — flags an expired certificate, and separately flags one expiring within 30 days.
- **Chain trust** — independently verifies the presented chain against the system trust store, and tells a self-signed certificate apart from an untrusted chain.
- **Hostname** — flags a certificate not valid for the hostname of the target URL.
- **Expiry** — flags an expired or not yet valid certificate, and separately one expiring within 30 days.
- **OCSP stapling** — flags a handshake with no stapled OCSP response.

**Remediate:** use a certificate from a trusted CA matching the hostname, automate renewal well before expiry, and enable OCSP stapling.

## Observation codes

Each kind of finding carries a stable code in `Metadata["code"]`, so an embedder maps it to its own check ID without matching titles:

| Check | Codes |
| --- | --- |
| `tls.protocol_version` | `protocol.legacy_enabled` |
| `tls.cipher_strength` | `cipher.no_forward_secrecy`, `cipher.rc4`, `cipher.3des`, `cipher.null`, `cipher.weak_suite`, `cipher.weak_dh` |
| `tls.certificate` | `certificate.untrusted_chain`, `certificate.self_signed`, `certificate.hostname_mismatch`, `certificate.expired`, `certificate.not_yet_valid`, `certificate.expires_soon`, `certificate.ocsp_not_stapled` |
| `tls.https_redirect` | `https_redirect.not_redirected`, `https_redirect.not_https` |

## Skipped targets

The TLS checks share one handshake, `probe.tls_info`, whose result (`probebase.TLSInfo`) is exported for other scanners. When it fails, they are skipped with the reason given by `TLSInfo.SkipReason`: a plain-HTTP target URL, a port that does not speak TLS, or a closed or unreachable port.

## `tls.https_redirect`

Sends a plain-HTTP request to the target and checks whether it's redirected to HTTPS.
Expand Down
116 changes: 88 additions & 28 deletions proxy/checks/tls/certificate/check.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,18 @@
package certificate

import (
"bytes"
"context"
"crypto/x509"
_ "embed"
"errors"
"net/url"
"time"

"github.com/cerberauth/harnessx"
"github.com/cerberauth/harnessx/checkdef"
"github.com/cerberauth/proxyaudit/proxy/probebase"
"github.com/cerberauth/proxyaudit/proxy/scanctx"
)

var errNoCertificate = errors.New("no certificate available from probe.tls_info")
Expand All @@ -25,55 +29,111 @@ var Def = checkdef.MustParseCheckDefYAML("certificate", checkYAML)
// soon enough to be an operational risk.
const ExpiryWarningWindow = 30 * 24 * time.Hour

var Check = checkdef.NewCheck(Def, func(_ context.Context, _ harnessx.Target, store harnessx.ResultStore) (harnessx.Result, error) {
const (
CodeUntrustedChain = "certificate.untrusted_chain"
CodeSelfSigned = "certificate.self_signed"
CodeHostnameMismatch = "certificate.hostname_mismatch"
CodeExpired = "certificate.expired"
CodeNotYetValid = "certificate.not_yet_valid"
CodeExpiresSoon = "certificate.expires_soon"
CodeOCSPNotStapled = "certificate.ocsp_not_stapled"
)

func isSelfSigned(cert *x509.Certificate) bool {
return bytes.Equal(cert.RawIssuer, cert.RawSubject) && cert.CheckSignature(cert.SignatureAlgorithm, cert.RawTBSCertificate, cert.Signature) == nil
}

func chainError(leaf *x509.Certificate, intermediates []*x509.Certificate, roots *x509.CertPool) error {
pool := x509.NewCertPool()
for _, c := range intermediates {
pool.AddCert(c)
}
_, err := leaf.Verify(x509.VerifyOptions{
Roots: roots,
Intermediates: pool,
CurrentTime: leaf.NotBefore.Add(time.Second),
})
return err
}

func observation(code, title, description, evidence string, metadata map[string]string) harnessx.Observation {
if metadata == nil {
metadata = map[string]string{}
}
metadata[probebase.MetadataCode] = code
return harnessx.Observation{Title: title, Description: description, Evidence: evidence, Metadata: metadata}
}

var Check = checkdef.NewCheck(Def, func(_ context.Context, target harnessx.Target, store harnessx.ResultStore) (harnessx.Result, error) {
info, ok := probebase.Info(store)
if !ok || info.Err != nil || info.ConnState == nil || len(info.ConnState.PeerCertificates) == 0 {
return harnessx.Result{Err: errNoCertificate}, nil
}
sctx := scanctx.TargetContext(target)
leaf := info.ConnState.PeerCertificates[0]
subject := map[string]string{"subject": leaf.Subject.String()}

var observations []harnessx.Observation

if info.VerifyErr != nil {
observations = append(observations, harnessx.Observation{
Title: "Certificate chain does not verify",
Description: "The certificate presented by the target does not chain to a trusted root, or the hostname does not match.",
Evidence: info.VerifyErr.Error(),
Metadata: map[string]string{"subject": leaf.Subject.String()},
})
if err := chainError(leaf, info.ConnState.PeerCertificates[1:], sctx.RootCAs); err != nil {
var unknownAuthority x509.UnknownAuthorityError
if errors.As(err, &unknownAuthority) && isSelfSigned(leaf) {
observations = append(observations, observation(CodeSelfSigned,
"Certificate is self-signed",
"The certificate presented by the target is signed by its own key instead of a trusted certificate authority, so clients cannot authenticate the server.",
err.Error(), subject))
} else {
observations = append(observations, observation(CodeUntrustedChain,
"Certificate chain does not verify",
"The certificate presented by the target does not chain to a trusted root.",
err.Error(), subject))
}
}

if u, err := url.Parse(target.URL); err == nil {
if err := leaf.VerifyHostname(u.Hostname()); err != nil {
observations = append(observations, observation(CodeHostnameMismatch,
"Certificate hostname does not match",
"The certificate presented by the target is not valid for the hostname of the target URL.",
err.Error(), map[string]string{"subject": leaf.Subject.String(), "hostname": u.Hostname()}))
}
}

now := time.Now()
notAfter := map[string]string{"not_after": leaf.NotAfter.Format(time.RFC3339)}
switch {
case now.After(leaf.NotAfter):
observations = append(observations, harnessx.Observation{
Title: "Certificate has expired",
Description: "The certificate presented by the target expired and is no longer valid.",
Evidence: "not_after: " + leaf.NotAfter.Format(time.RFC3339),
Metadata: map[string]string{"not_after": leaf.NotAfter.Format(time.RFC3339)},
})
observations = append(observations, observation(CodeExpired,
"Certificate has expired",
"The certificate presented by the target expired and is no longer valid.",
"not_after: "+leaf.NotAfter.Format(time.RFC3339), notAfter))
case now.Before(leaf.NotBefore):
observations = append(observations, observation(CodeNotYetValid,
"Certificate is not valid yet",
"The certificate presented by the target is not valid before a future date.",
"not_before: "+leaf.NotBefore.Format(time.RFC3339), map[string]string{"not_before": leaf.NotBefore.Format(time.RFC3339)}))
case leaf.NotAfter.Before(now.Add(ExpiryWarningWindow)):
observations = append(observations, harnessx.Observation{
Title: "Certificate expires soon",
Description: "The certificate presented by the target expires within 30 days.",
Evidence: "not_after: " + leaf.NotAfter.Format(time.RFC3339),
Metadata: map[string]string{"not_after": leaf.NotAfter.Format(time.RFC3339)},
})
observations = append(observations, observation(CodeExpiresSoon,
"Certificate expires soon",
"The certificate presented by the target expires within 30 days.",
"not_after: "+leaf.NotAfter.Format(time.RFC3339), notAfter))
}

if info.ConnState.OCSPResponse == nil {
observations = append(observations, harnessx.Observation{
Title: "OCSP stapling not enabled",
Description: "The target did not staple an OCSP response during the TLS handshake, so clients must query the CA's OCSP responder separately (or skip revocation checking entirely).",
Evidence: "no OCSP response in TLS handshake",
})
observations = append(observations, observation(CodeOCSPNotStapled,
"OCSP stapling not enabled",
"The target did not staple an OCSP response during the TLS handshake, so clients must query the CA's OCSP responder separately (or skip revocation checking entirely).",
"no OCSP response in TLS handshake", nil))
}

return harnessx.Result{Observations: observations}, nil
}, checkdef.WithSkip(harnessx.SkipWhen(func(_ context.Context, _ harnessx.Target, store harnessx.ResultStore) string {
info, ok := probebase.Info(store)
if !ok || info.Err != nil || info.ConnState == nil || len(info.ConnState.PeerCertificates) == 0 {
return "target TLS handshake produced no certificate — see probe.tls_info"
info, _ := probebase.Info(store)
if reason := info.SkipReason(); reason != "" {
return reason
}
if len(info.ConnState.PeerCertificates) == 0 {
return "target TLS handshake produced no certificate"
}
return ""
})))
2 changes: 1 addition & 1 deletion proxy/checks/tls/certificate/check.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,6 @@ tags:
depends_on:
- "probe.tls_info"
cvss_vector: "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:L/VI:L/VA:N/SC:N/SI:N/SA:N"
cvss_score: 5.3
cvss_score: 6.9
cwe_id: "CWE-295"
owasp: "API8:2023"
101 changes: 77 additions & 24 deletions proxy/checks/tls/cipher_strength/check.go
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
// Package cipherstrength checks the negotiated TLS cipher suite for
// forward secrecy and probes whether the target still accepts any
// known-weak cipher suite (RC4, 3DES, CBC-mode) that Go's crypto/tls
// implements but excludes from its default client offer.
// forward secrecy and probes whether the target still accepts RC4, 3DES,
// NULL or other insecure cipher suites, or a weak Diffie-Hellman group.
package cipherstrength

import (
"context"
"crypto/tls"
_ "embed"
"fmt"
"strconv"
"strings"

"github.com/cerberauth/harnessx"
Expand All @@ -21,6 +22,44 @@ var checkYAML []byte

var Def = checkdef.MustParseCheckDefYAML("cipher_strength", checkYAML)

const (
CodeNoForwardSecrecy = "cipher.no_forward_secrecy"
CodeRC4 = "cipher.rc4"
CodeTripleDES = "cipher.3des"
CodeNULL = "cipher.null"
CodeWeakSuite = "cipher.weak_suite"
CodeWeakDH = "cipher.weak_dh"
)

const MinDHPrimeBits = 2048

const metadataCipherSuite = "cipher_suite"

var probeLegacyHello = probebase.ProbeLegacyHello

var legacyFamilies = []struct {
code string
name string
suites []uint16
}{
{CodeRC4, "RC4", probebase.RC4Suites},
{CodeTripleDES, "3DES", probebase.TDESSuites},
{CodeNULL, "NULL (no encryption)", probebase.NULLSuites},
}

func offered(suites []uint16, suite uint16) bool {
for _, s := range suites {
if s == suite {
return true
}
}
return false
}

func suiteName(id uint16) string {
return fmt.Sprintf("%s (0x%04x)", tls.CipherSuiteName(id), id)
}

var Check = checkdef.NewCheck(Def, func(ctx context.Context, target harnessx.Target, store harnessx.ResultStore) (harnessx.Result, error) {
sctx := scanctx.TargetContext(target)

Expand All @@ -33,7 +72,7 @@ var Check = checkdef.NewCheck(Def, func(ctx context.Context, target harnessx.Tar
Title: "Negotiated cipher suite lacks forward secrecy",
Description: "The default TLS handshake negotiated a cipher suite that does not provide forward secrecy, so a compromised private key could decrypt captured past traffic.",
Evidence: "negotiated cipher suite: " + name,
Metadata: map[string]string{"cipher_suite": name},
Metadata: map[string]string{probebase.MetadataCode: CodeNoForwardSecrecy, metadataCipherSuite: name},
})
}
}
Expand All @@ -43,27 +82,43 @@ var Check = checkdef.NewCheck(Def, func(ctx context.Context, target harnessx.Tar
return harnessx.Result{Observations: observations, Err: err}, nil
}

weak := insecureSuiteIDs()
if len(weak) > 0 {
for _, family := range legacyFamilies {
hello, err := probeLegacyHello(ctx, host, probebase.VersionTLS12, family.suites)
if err != nil || !offered(family.suites, hello.CipherSuite) {
continue
}
observations = append(observations, harnessx.Observation{
Title: "Weak cipher suite accepted: " + family.name,
Description: "The target completed a TLS handshake using a " + family.name + " cipher suite, which does not protect the confidentiality of the traffic.",
Evidence: "negotiated cipher suite: " + suiteName(hello.CipherSuite),
Metadata: map[string]string{probebase.MetadataCode: family.code, metadataCipherSuite: suiteName(hello.CipherSuite)},
})
}

if weak := otherInsecureSuiteIDs(); len(weak) > 0 {
state, err := probebase.DialTLS(ctx, host, sctx, tls.VersionTLS10, tls.VersionTLS12, weak...)
if err == nil && state != nil {
observations = append(observations, harnessx.Observation{
Title: "Weak cipher suite accepted",
Description: "The target completed a TLS handshake using a known-weak cipher suite (RC4, 3DES, or a CBC-mode suite).",
Description: "The target completed a TLS handshake using a cipher suite Go marks as insecure (CBC mode with SHA-256).",
Evidence: "negotiated cipher suite: " + tls.CipherSuiteName(state.CipherSuite),
Metadata: map[string]string{"cipher_suite": tls.CipherSuiteName(state.CipherSuite)},
Metadata: map[string]string{probebase.MetadataCode: CodeWeakSuite, metadataCipherSuite: tls.CipherSuiteName(state.CipherSuite)},
})
}
}

return harnessx.Result{Observations: observations}, nil
}, checkdef.WithSkip(harnessx.SkipWhen(func(_ context.Context, target harnessx.Target, store harnessx.ResultStore) string {
info, ok := probebase.Info(store)
if !ok || info.Err != nil {
return "target TLS handshake failed — see probe.tls_info"
if hello, err := probeLegacyHello(ctx, host, probebase.VersionTLS12, probebase.DHESuites); err == nil && probebase.IsDHESuite(hello.CipherSuite) && hello.DHPrimeBits > 0 && hello.DHPrimeBits < MinDHPrimeBits {
bits := strconv.Itoa(hello.DHPrimeBits)
observations = append(observations, harnessx.Observation{
Title: "Weak Diffie-Hellman group accepted",
Description: "The target negotiated a DHE cipher suite with a Diffie-Hellman group below 2048 bits, which can be broken by a well-resourced attacker (Logjam).",
Evidence: "DH prime: " + bits + " bits, cipher suite: " + suiteName(hello.CipherSuite),
Metadata: map[string]string{probebase.MetadataCode: CodeWeakDH, "dh_bits": bits, metadataCipherSuite: suiteName(hello.CipherSuite)},
})
}
return ""
})))

return harnessx.Result{Observations: observations}, nil
}, checkdef.WithSkip(probebase.SkipUnlessHandshake()))

// hasForwardSecrecy reports whether the negotiated cipher suite provides
// forward secrecy. TLS 1.3 suites are always forward-secret (fixed ECDHE
Expand All @@ -76,15 +131,13 @@ func hasForwardSecrecy(cipherSuiteName string, version uint16) bool {
return strings.Contains(cipherSuiteName, "ECDHE") || strings.Contains(cipherSuiteName, "DHE")
}

// insecureSuiteIDs returns the IDs of cipher suites Go's crypto/tls
// implements but marks insecure (RC4, 3DES, CBC-mode, ...) — excluded from
// the client's default offer, so they must be requested explicitly to test
// whether the server still accepts them.
func insecureSuiteIDs() []uint16 {
suites := tls.InsecureCipherSuites()
ids := make([]uint16, len(suites))
for i, s := range suites {
ids[i] = s.ID
func otherInsecureSuiteIDs() []uint16 {
var ids []uint16
for _, s := range tls.InsecureCipherSuites() {
if strings.Contains(s.Name, "RC4") || strings.Contains(s.Name, "3DES") {
continue
}
ids = append(ids, s.ID)
}
return ids
}
4 changes: 2 additions & 2 deletions proxy/checks/tls/cipher_strength/check.yaml
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
id: "tls.cipher_strength"
name: "Weak Cipher Suite or Missing Forward Secrecy"
description: "Inspects the negotiated cipher suite for known-weak ciphers (RC4, 3DES, CBC-mode) and for support of forward secrecy (ECDHE/DHE key exchange)."
description: "Inspects the negotiated cipher suite for forward secrecy and probes for weak cipher suites (RC4, 3DES, NULL, CBC-mode) and Diffie-Hellman groups below 2048 bits."
link: "https://ciphersuite.info/"
tags:
- tls
- transport
depends_on:
- "probe.tls_info"
cvss_vector: "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:L/VI:L/VA:N/SC:N/SI:N/SA:N"
cvss_score: 4.8
cvss_score: 6.9
cwe_id: "CWE-327"
owasp: "API8:2023"
Loading
Loading