tlsaudit 0.1.0__tar.gz

tlsaudit-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.3
+Name: tlsaudit
+Version: 0.1.0
+Summary: A command-line TLS/cipher auditor. Points at a host, tests which TLS/SSL protocol versions it accepts and how strong its negotiated cipher suite is, then reports findings as a simple PASS/FAIL/WARN table.
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# tlsaudit
+
+A command-line TLS/cipher auditor. Points at a host, tests which TLS/SSL protocol
+versions it accepts and how strong its negotiated cipher suite is, then reports
+findings as a simple PASS/FAIL/WARN table.
+
+Standard library only (`ssl`, `socket`, `argparse`), no dependencies to install.
+
+## What it checks
+
+**Protocol version support** — tests SSLv3, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3
+individually by pinning the handshake to each version in turn.
+
+- A deprecated version (SSLv3, TLS 1.0, TLS 1.1) that the server still **accepts**
+  is a **FAIL**.
+- A deprecated version that the server correctly **rejects** is a **PASS**, that's
+  the server behaving securely.
+- TLS 1.2 or TLS 1.3 being **supported** is a **PASS**.
+- TLS 1.2 or TLS 1.3 **not** being supported produces no result at all, that's not
+  a finding worth reporting in Phase 1, it just means the server doesn't offer that
+  particular version.
+
+**Cipher suite strength** — connects normally (letting the server negotiate freely)
+and checks the resulting cipher name against known-weak markers: `RC4`, `3DES`,
+`NULL`, `EXPORT`, `CBC`.
+
+## Usage
+
+```bash
+python3 tlsaudit.py <hostname> [--port PORT]
+```
+
+Port defaults to 443.
+
+Example:
+
+```
+$ python3 tlsaudit.py github.com
+[*] Auditing github.com on port 443
+[+] TLS Audit Report for github.com:443
+[PASS] Cipher Suite: Strong cipher suite: TLS_AES_256_GCM_SHA384
+[PASS] TLS 1.2: Supported
+[PASS] TLS 1.3: Supported
+
+[+] Verdict Summary: PASS: 3 | FAIL: 0 | WARN: 0
+```
+
+If the target isn't running TLS at all (wrong port, plain HTTP, etc.), the tool
+prints a distinct banner instead of the normal table:
+
+```
+$ python3 tlsaudit.py example.com --port 80
+[*] Auditing example.com on port 80
+[+] TLS Audit Report for example.com:80
+------------------------------------------------------------
+[!] NOT A TLS service: Provided port does not run TLS
+------------------------------------------------------------
+```
+
+## Known limitations (by design, not bugs)
+
+- **No certificate validation yet.** This is Phase 1, only protocol version and
+  cipher strength are checked. Certificate chain validation, expiry, key size,
+  and hostname/SAN matching are planned for Phase 2.
+- **SSLv3 is often untestable on modern systems.** Current OpenSSL builds
+  frequently disable SSLv3 entirely at compile time, as a hardening measure. On
+  those systems, testing SSLv3 fails locally before any packet reaches the
+  server, and shows as a WARN ("no protocols available"), not a PASS or FAIL,
+  since nothing was actually verified about the server itself.
+- **A timeout doesn't necessarily mean nothing's there.** A well-configured
+  firewall silently dropping unsolicited connections looks identical, from this
+  tool's perspective, to a genuinely unreachable host. `Connection refused` (an
+  explicit rejection) and `Connection timed out` (no response at all) are
+  reported separately and mean different things.
+- **Single host only.** No batch scanning from a file yet, and no JSON output.
+  Both are planned for Phase 3.
+
+## Roadmap
+
+This is Phase 1 of a larger plan:
+
+- **Phase 2** — certificate chain validation, expiry, key size, SAN matching
+- **Phase 3** — batch scanning from a host list, JSON output
+- **Phase 4** — HTTP security headers, A-F scoring, CAA/OCSP checks, and more
+
+## Responsible Usage
+
+**DO NOT** scan hosts you are not expressly authorized to do so. Doing so may land you in trouble with
+the owners of the host. Therefore, seek permission from the owner before scanning.
+
+## License
+
+TBD, add MIT or Apache 2.0 once decided.

tlsaudit-0.1.0/README.md

@@ -0,0 +1,93 @@
+# tlsaudit
+
+A command-line TLS/cipher auditor. Points at a host, tests which TLS/SSL protocol
+versions it accepts and how strong its negotiated cipher suite is, then reports
+findings as a simple PASS/FAIL/WARN table.
+
+Standard library only (`ssl`, `socket`, `argparse`), no dependencies to install.
+
+## What it checks
+
+**Protocol version support** — tests SSLv3, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3
+individually by pinning the handshake to each version in turn.
+
+- A deprecated version (SSLv3, TLS 1.0, TLS 1.1) that the server still **accepts**
+  is a **FAIL**.
+- A deprecated version that the server correctly **rejects** is a **PASS**, that's
+  the server behaving securely.
+- TLS 1.2 or TLS 1.3 being **supported** is a **PASS**.
+- TLS 1.2 or TLS 1.3 **not** being supported produces no result at all, that's not
+  a finding worth reporting in Phase 1, it just means the server doesn't offer that
+  particular version.
+
+**Cipher suite strength** — connects normally (letting the server negotiate freely)
+and checks the resulting cipher name against known-weak markers: `RC4`, `3DES`,
+`NULL`, `EXPORT`, `CBC`.
+
+## Usage
+
+```bash
+python3 tlsaudit.py <hostname> [--port PORT]
+```
+
+Port defaults to 443.
+
+Example:
+
+```
+$ python3 tlsaudit.py github.com
+[*] Auditing github.com on port 443
+[+] TLS Audit Report for github.com:443
+[PASS] Cipher Suite: Strong cipher suite: TLS_AES_256_GCM_SHA384
+[PASS] TLS 1.2: Supported
+[PASS] TLS 1.3: Supported
+
+[+] Verdict Summary: PASS: 3 | FAIL: 0 | WARN: 0
+```
+
+If the target isn't running TLS at all (wrong port, plain HTTP, etc.), the tool
+prints a distinct banner instead of the normal table:
+
+```
+$ python3 tlsaudit.py example.com --port 80
+[*] Auditing example.com on port 80
+[+] TLS Audit Report for example.com:80
+------------------------------------------------------------
+[!] NOT A TLS service: Provided port does not run TLS
+------------------------------------------------------------
+```
+
+## Known limitations (by design, not bugs)
+
+- **No certificate validation yet.** This is Phase 1, only protocol version and
+  cipher strength are checked. Certificate chain validation, expiry, key size,
+  and hostname/SAN matching are planned for Phase 2.
+- **SSLv3 is often untestable on modern systems.** Current OpenSSL builds
+  frequently disable SSLv3 entirely at compile time, as a hardening measure. On
+  those systems, testing SSLv3 fails locally before any packet reaches the
+  server, and shows as a WARN ("no protocols available"), not a PASS or FAIL,
+  since nothing was actually verified about the server itself.
+- **A timeout doesn't necessarily mean nothing's there.** A well-configured
+  firewall silently dropping unsolicited connections looks identical, from this
+  tool's perspective, to a genuinely unreachable host. `Connection refused` (an
+  explicit rejection) and `Connection timed out` (no response at all) are
+  reported separately and mean different things.
+- **Single host only.** No batch scanning from a file yet, and no JSON output.
+  Both are planned for Phase 3.
+
+## Roadmap
+
+This is Phase 1 of a larger plan:
+
+- **Phase 2** — certificate chain validation, expiry, key size, SAN matching
+- **Phase 3** — batch scanning from a host list, JSON output
+- **Phase 4** — HTTP security headers, A-F scoring, CAA/OCSP checks, and more
+
+## Responsible Usage
+
+**DO NOT** scan hosts you are not expressly authorized to do so. Doing so may land you in trouble with
+the owners of the host. Therefore, seek permission from the owner before scanning.
+
+## License
+
+TBD, add MIT or Apache 2.0 once decided.

tlsaudit-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "tlsaudit"
+version = "0.1.0"
+description = "A command-line TLS/cipher auditor. Points at a host, tests which TLS/SSL protocol versions it accepts and how strong its negotiated cipher suite is, then reports findings as a simple PASS/FAIL/WARN table."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = []
+
+[project.scripts]
+tlsaudit = "tlsaudit:main"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bandit>=1.9.4",
+    "mypy>=2.3.0",
+    "pip-audit>=2.10.1",
+    "pytest>=9.1.1",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.16.2",
+]

tlsaudit-0.1.0/pyproject.toml.orig

@@ -0,0 +1,24 @@
+[project]
+name = "tlsaudit"
+version = "0.1.0"
+description = "A command-line TLS/cipher auditor. Points at a host, tests which TLS/SSL protocol versions it accepts and how strong its negotiated cipher suite is, then reports findings as a simple PASS/FAIL/WARN table."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = []
+
+[project.scripts]
+tlsaudit = "tlsaudit:main"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bandit>=1.9.4",
+    "mypy>=2.3.0",
+    "pip-audit>=2.10.1",
+    "pytest>=9.1.1",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.16.2",
+]

tlsaudit-0.1.0/src/tlsaudit/__init__.py

@@ -0,0 +1,23 @@
+from .cli import main
+from .report import (
+    NOT_TLS_CHECK_NAME,
+    CheckResult,
+    ScanReport,
+    Verdict,
+    VersionSpec,
+    display_report,
+)
+from .scanner import check_cipher_suite, check_protocol_version, scan_host
+
+__all__ = [
+    "NOT_TLS_CHECK_NAME",
+    "CheckResult",
+    "ScanReport",
+    "Verdict",
+    "VersionSpec",
+    "check_cipher_suite",
+    "check_protocol_version",
+    "display_report",
+    "main",
+    "scan_host",
+]

tlsaudit-0.1.0/src/tlsaudit/cli.py

@@ -0,0 +1,20 @@
+import argparse
+
+from .report import display_report
+from .scanner import scan_host
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("hostname", type=str, help="Hostname to audit")
+    parser.add_argument("-p", "--port", type=int, default=443, help="Port to audit")
+    args = parser.parse_args()
+
+    print(f"[*] Auditing {args.hostname} on port {args.port}")
+    report = scan_host(args.hostname, args.port)
+
+    display_report(report)
+
+
+if __name__ == "__main__":
+    main()

tlsaudit-0.1.0/src/tlsaudit/report.py

@@ -0,0 +1,53 @@
+import ssl
+from collections import Counter
+from dataclasses import dataclass, field
+from enum import Enum
+
+NOT_TLS_CHECK_NAME = "Not TLS"
+WEAK_CIPHER_MARKERS = ["RC4", "3DES", "NULL", "EXPORT", "CBC"]
+
+
+class Verdict(Enum):
+    PASS = "PASS"  # nosec: B105 - num member, not a credential; Bandit's heuristic matches on the name "PASS"
+    FAIL = "FAIL"
+    WARN = "WARN"
+
+
+@dataclass
+class VersionSpec:
+    version: ssl.TLSVersion
+    label: str
+    is_deprecated: bool
+
+
+@dataclass
+class CheckResult:
+    name: str  # which check this is, e.g. "TLS 1.0" or "Cipher Suite"?
+    detail: str
+    verdict: Verdict
+
+
+@dataclass
+class ScanReport:
+    hostname: str
+    port: int
+    results: list[CheckResult] = field(default_factory=list)
+
+
+def display_report(report: ScanReport):
+    print(f"[+] TLS Audit Report for {report.hostname}:{report.port}")
+    if len(report.results) == 1 and report.results[0].name == NOT_TLS_CHECK_NAME:
+        print("-" * 40)
+        print(f"[!] NOT A TLS service: {report.results[0].detail}")
+        print("-" * 40)
+        return
+
+    for result in report.results:
+        print(f"[{result.verdict.value}] {result.name}: {result.detail}")
+
+    verdict_count = Counter({v: 0 for v in Verdict})
+    verdict_count.update(result.verdict for result in report.results)
+
+    summary_part = [f"{v.value}: {verdict_count[v]}" for v in Verdict]
+    one_liner = " | ".join(summary_part)
+    print(f"\n[+] Verdict Summary: {one_liner}")

tlsaudit-0.1.0/src/tlsaudit/scanner.py

@@ -0,0 +1,160 @@
+import socket
+import ssl
+
+from .report import (
+    NOT_TLS_CHECK_NAME,
+    WEAK_CIPHER_MARKERS,
+    CheckResult,
+    ScanReport,
+    Verdict,
+    VersionSpec,
+)
+
+
+def check_protocol_version(
+    hostname: str, port: int, version: ssl.TLSVersion, label: str, is_deprecated: bool
+) -> CheckResult | None:
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    context.minimum_version = context.maximum_version = version
+
+    try:
+        with (
+            socket.create_connection((hostname, port), timeout=20) as sock,
+            context.wrap_socket(sock, server_hostname=hostname),
+        ):
+            if is_deprecated:
+                return CheckResult(label, "Deprecated", Verdict.FAIL)
+            return CheckResult(label, "Supported", Verdict.PASS)
+
+    except ssl.SSLError as e:
+        if e.reason == "NO_SHARED_CIPHER":
+            return CheckResult(label, "No shared cipher", Verdict.WARN)
+        elif e.reason == "NO_PROTOCOLS_AVAILABLE":
+            return CheckResult(label, "No protocols available", Verdict.WARN)
+        if is_deprecated:
+            return CheckResult(label, "Not supported & Deprecated", Verdict.PASS)
+        return None
+    except TimeoutError:
+        return CheckResult(label, "Connection timed out", Verdict.WARN)
+
+
+def check_cipher_suite(hostname: str, port: int = 443) -> CheckResult:
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    try:
+        with (
+            socket.create_connection((hostname, port), timeout=20) as sock,
+            context.wrap_socket(sock, server_hostname=hostname) as ssock,
+        ):
+            cipher_info = ssock.cipher()
+            if cipher_info is None:
+                return CheckResult("Cipher Suite", "No cipher negotiated", Verdict.WARN)
+            cipher_name = cipher_info[0]
+
+        if any(marker in cipher_name for marker in WEAK_CIPHER_MARKERS):
+            return CheckResult(
+                "Cipher Suite", f"Weak cipher negotiated: {cipher_name}", Verdict.FAIL
+            )
+        else:
+            return CheckResult(
+                "Cipher Suite", f"Strong cipher suite: {cipher_name}", Verdict.PASS
+            )
+    except TimeoutError:
+        return CheckResult("Cipher Suite", "Connection timed out", Verdict.WARN)
+
+
+def scan_host(hostname: str, port: int) -> ScanReport:
+    report = ScanReport(hostname, port)
+    target_versions = [
+        VersionSpec(ssl.TLSVersion.SSLv3, "SSL 3.0", True),
+        VersionSpec(ssl.TLSVersion.TLSv1, "TLS 1.0", True),
+        VersionSpec(ssl.TLSVersion.TLSv1_1, "TLS 1.1", True),
+        VersionSpec(ssl.TLSVersion.TLSv1_2, "TLS 1.2", False),
+        VersionSpec(ssl.TLSVersion.TLSv1_3, "TLS 1.3", False),
+    ]
+    try:
+        context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_NONE
+        with (
+            socket.create_connection((hostname, port), timeout=10) as sock,
+            context.wrap_socket(sock, server_hostname=hostname),
+        ):
+            pass
+        check_cipher_suite_result = check_cipher_suite(hostname, port)
+        report.results.append(check_cipher_suite_result)
+        for version in target_versions:
+            try:
+                result = check_protocol_version(
+                    hostname,
+                    port,
+                    version.version,
+                    version.label,
+                    version.is_deprecated,
+                )
+                if result:
+                    report.results.append(result)
+            except Exception as e:  # noqa: BLE001 — deliberate safety net; check_protocol_version already handles its known exception types internally
+                report.results.append(
+                    CheckResult(
+                        version.label, f"Could not complete check: {e!s}", Verdict.WARN
+                    )
+                )
+        return report
+    except socket.gaierror:
+        return ScanReport(
+            hostname,
+            port,
+            [CheckResult("Hostname", "Could not resolve hostname", Verdict.WARN)],
+        )
+    except TimeoutError:
+        return ScanReport(
+            hostname,
+            port,
+            [CheckResult("Connection", "Connection timed out", Verdict.WARN)],
+        )
+    except ConnectionRefusedError:
+        return ScanReport(
+            hostname,
+            port,
+            [CheckResult("Connection", "Connection refused", Verdict.WARN)],
+        )
+    except ConnectionResetError:
+        return ScanReport(
+            hostname,
+            port,
+            [CheckResult("Connection", "Connection reset", Verdict.WARN)],
+        )
+    except ssl.SSLError as e:
+        if e.reason == "RECORD_LAYER_FAILURE":
+            return ScanReport(
+                hostname,
+                port,
+                [
+                    CheckResult(
+                        NOT_TLS_CHECK_NAME,
+                        "Provided port does not run TLS",
+                        Verdict.WARN,
+                    )
+                ],
+            )
+        return ScanReport(
+            hostname,
+            port,
+            [
+                CheckResult(
+                    NOT_TLS_CHECK_NAME,
+                    f"Provided port does not appear to run TLS ({e.reason})",
+                    Verdict.WARN,
+                )
+            ],
+        )
+    except OSError as e:
+        return ScanReport(
+            hostname,
+            port,
+            [CheckResult("Network Error", f"OS Error: {e}", Verdict.WARN)],
+        )