feat: add probe_raw() public function

Adds tls_utils.probe_raw(host, port, *, starttls, sni_hostname, timeout)
— a public function that runs openssl s_client without -brief, with
-ign_eof and a QUIT\r\n probe, returning raw combined stdout+stderr for
callers to parse (Max Early Data:, Negotiated TLS1.3 group:).
Exported from the package root as quantumvalidator.probe_raw.

Adds 15 new unit tests (245 total). Bumps version to 0.6.0.

Author: t0kubetsu

CHANGELOG.md

@@ -11,6 +11,32 @@ Version numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html
 
 ---
 
+## [0.6.0] — 2026-06-19
+
+### Added
+- `tls_utils.probe_raw(host, port, *, starttls, sni_hostname, timeout)` — public
+  function that runs `openssl s_client` and returns the raw combined
+  stdout+stderr as a string (or `None` on failure).  Unlike `probe_tls`, it
+  omits `-brief`, adds `-ign_eof`, and sends `QUIT\r\n` so callers can parse
+  protocol-specific fields such as `Max Early Data:` (TLS 1.3 0-RTT) and
+  `Negotiated TLS1.3 group:`.  Exported from the package root as
+  `quantumvalidator.probe_raw`.
+- 15 new unit tests for `probe_raw` in `tests/test_tls_utils.py` (245 total).
+
+### Fixed
+- `tls_utils.probe_raw`: docstring now explicitly documents the ``timeout + 2``
+  buffer passed to the subprocess, which gives the TLS handshake time to
+  complete before Python terminates the process.
+- `tests/test_tls_utils.py`: `TestProbeRaw.test_returns_none_for_invalid_port`
+  now monkeypatches `check_openssl` to return `(True, ...)` so the test
+  exercises `_validate_target` deterministically regardless of whether
+  `openssl` is installed on the test machine.
+- `__init__.py`: added `# noqa: E402` to the `probe_raw` re-export to
+  suppress the false-positive E402 lint warning (the import intentionally
+  follows the logging teardown block).
+
+---
+
 ## [0.5.2] — 2026-05-15
 
 ### Added
@@ -173,7 +199,8 @@ Version numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html
 
 ---
 
-[Unreleased]: https://github.com/NC3-TestingPlatform/quantumvalidator/compare/v0.5.2...HEAD
+[Unreleased]: https://github.com/NC3-TestingPlatform/quantumvalidator/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/NC3-TestingPlatform/quantumvalidator/compare/v0.5.2...v0.6.0
 [0.5.2]: https://github.com/NC3-TestingPlatform/quantumvalidator/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/NC3-TestingPlatform/quantumvalidator/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/NC3-TestingPlatform/quantumvalidator/compare/v0.4.0...v0.5.0

README.md

@@ -12,7 +12,7 @@ $ quantumvalidator check cloudflare.com
 ```
 
 ![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue)
-![Tests](https://img.shields.io/badge/tests-230%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-245%20passing-brightgreen)
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 ![License](https://img.shields.io/badge/license-GPLv3-lightgrey)
 
@@ -297,7 +297,7 @@ pytest tests/test_tls_utils.py
 pytest tests/test_assessor.py::TestAssessHttps -v
 ```
 
-The test suite has **230 tests** and maintains **100% statement coverage**.
+The test suite has **245 tests** and maintains **100% statement coverage**.
 
 All network I/O (`openssl s_client` subprocess) is mocked at the `probe_tls` boundary —
 no test touches a real server or the internet.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantumvalidator"
-version = "0.5.2"
+version = "0.6.0"
 description = "Quantum-safe cryptography validator — TLS, STARTTLS, and SSH post-quantum readiness assessment"
 readme = "README.md"
 requires-python = ">=3.11"

quantumvalidator/__init__.py

@@ -5,11 +5,13 @@
 try:
     __version__ = version("quantumvalidator")
 except PackageNotFoundError:  # pragma: no cover
-    __version__ = "0.5.2"
+    __version__ = "0.6.0"
 
 import logging as _logging
 
 _logging.getLogger("quantumvalidator").addHandler(_logging.NullHandler())
 del _logging
 
-__all__ = ["__version__"]
+from quantumvalidator.tls_utils import probe_raw as probe_raw  # noqa: F401, E402
+
+__all__ = ["__version__", "probe_raw"]

quantumvalidator/tls_utils.py

@@ -73,6 +73,76 @@ def ok(self) -> bool:
         return self.error is None
 
 
+def probe_raw(
+    host: str,
+    port: int,
+    *,
+    starttls: str | None = None,
+    sni_hostname: str | None = None,
+    timeout: float = 10.0,
+) -> str | None:
+    """Run ``openssl s_client`` and return the combined stdout+stderr output.
+
+    Unlike :func:`probe_tls`, this function does not parse the output — it
+    returns the raw text so callers can extract protocol-specific fields such
+    as ``Max Early Data:`` (TLS 1.3 0-RTT, RFC 8446 §8).
+
+    Returns ``None`` when ``openssl`` is not on PATH, the host/port are
+    invalid, or the subprocess fails (timeout, OSError).
+
+    :param host: Hostname or IP to connect to.
+    :param port: TCP port.
+    :param starttls: openssl ``-starttls`` mode (e.g. ``'smtp'``), or ``None`` for raw TLS.
+    :param sni_hostname: Hostname to send as TLS SNI via ``-servername``, or ``None``.
+    :param timeout: Connection timeout in seconds; the subprocess is given
+        ``timeout + 2`` seconds to allow TLS handshake completion.
+    :returns: Combined stdout+stderr from ``openssl s_client``, or ``None`` on failure.
+    :rtype: str | None
+    """
+    ok, _ = check_openssl()
+    if not ok:
+        return None
+
+    try:
+        _validate_target(host, port)
+    except ValueError:
+        return None
+
+    try:
+        addr = ipaddress.ip_address(host)
+        connect_str = f"[{host}]:{port}" if addr.version == 6 else f"{host}:{port}"
+    except ValueError:
+        connect_str = f"{host}:{port}"
+
+    groups_str = ":".join(PROBE_GROUPS)
+    cmd = [
+        OPENSSL_BINARY,
+        "s_client",
+        "-connect", connect_str,
+        "-groups", groups_str,
+        "-ign_eof",
+    ]
+    if starttls:
+        cmd.extend(["-starttls", starttls])
+    if sni_hostname:
+        cmd.extend(["-servername", sni_hostname])
+
+    logger.debug(
+        "probe_raw %s:%d starttls=%s sni=%s — cmd: %s",
+        host, port, starttls, sni_hostname, " ".join(cmd),
+    )
+    try:
+        proc = subprocess.run(
+            cmd,
+            input=b"QUIT\r\n",
+            capture_output=True,
+            timeout=timeout + 2,
+        )
+        return (proc.stdout + proc.stderr).decode("utf-8", errors="replace")
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+
+
 def probe_tls(
     host: str,
     port: int,

tests/test_tls_utils.py

@@ -18,6 +18,7 @@
     _probe_ssh,
     _read_server_banner,
     _read_ssh_packet,
+    probe_raw,
     probe_tls,
 )
 
@@ -1128,3 +1129,175 @@ def fake_recv(n: int) -> bytes:
         assert "Could not parse SSH KEXINIT" in result.error
         assert result.tls_version == "SSHv2"
 
+
+# ---------------------------------------------------------------------------
+# probe_raw
+# ---------------------------------------------------------------------------
+
+
+def _make_raw_proc(stdout: bytes = b"", stderr: bytes = b"", returncode: int = 0):
+    proc = MagicMock()
+    proc.stdout = stdout
+    proc.stderr = stderr
+    proc.returncode = returncode
+    return proc
+
+
+class TestProbeRaw:
+    def test_returns_combined_output_on_success(self, monkeypatch):
+        stdout = b"Connecting to 1.2.3.4\nCONNECTION ESTABLISHED\n"
+        stderr = b"depth=0 CN=example.com\n"
+        monkeypatch.setattr(
+            "quantumvalidator.tls_utils.subprocess.run",
+            lambda *a, **kw: _make_raw_proc(stdout, stderr),
+        )
+        result = probe_raw("example.com", 25)
+        assert result == (stdout + stderr).decode("utf-8", errors="replace")
+
+    def test_returns_none_when_openssl_missing(self, monkeypatch):
+        monkeypatch.setattr(
+            "quantumvalidator.tls_utils.check_openssl",
+            lambda: (False, "openssl not found"),
+        )
+        assert probe_raw("example.com", 25) is None
+
+    def test_returns_none_on_timeout(self, monkeypatch):
+        def _raise(*a, **kw):
+            raise subprocess.TimeoutExpired(cmd="openssl", timeout=12)
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", _raise)
+        assert probe_raw("example.com", 25) is None
+
+    def test_returns_none_on_oserror(self, monkeypatch):
+        def _raise(*a, **kw):
+            raise OSError("connection refused")
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", _raise)
+        assert probe_raw("example.com", 25) is None
+
+    def test_returns_none_for_invalid_port(self, monkeypatch):
+        # _validate_target raises ValueError for port 0; probe_raw catches it.
+        # Mock check_openssl so the test exercises _validate_target regardless
+        # of whether openssl is installed on the CI machine.
+        monkeypatch.setattr(
+            "quantumvalidator.tls_utils.check_openssl",
+            lambda: (True, "openssl 3.0.0"),
+        )
+        assert probe_raw("example.com", 0) is None
+
+    def test_starttls_smtp_in_cmd(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("example.com", 25, starttls="smtp")
+        assert "-starttls" in captured["cmd"]
+        assert "smtp" in captured["cmd"]
+
+    def test_sni_hostname_adds_servername(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("1.2.3.4", 25, sni_hostname="mail.example.com")
+        assert "-servername" in captured["cmd"]
+        assert "mail.example.com" in captured["cmd"]
+
+    def test_no_servername_when_sni_none(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("example.com", 25)
+        assert "-servername" not in captured["cmd"]
+
+    def test_brief_not_in_cmd(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("example.com", 25)
+        assert "-brief" not in captured["cmd"]
+
+    def test_ign_eof_in_cmd(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("example.com", 25)
+        assert "-ign_eof" in captured["cmd"]
+
+    def test_groups_in_cmd(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("example.com", 25)
+        assert "-groups" in captured["cmd"]
+        groups_idx = captured["cmd"].index("-groups")
+        groups_val = captured["cmd"][groups_idx + 1]
+        assert all(g in groups_val for g in PROBE_GROUPS)
+
+    def test_ipv6_bracket_notation(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("::1", 25)
+        connect_idx = captured["cmd"].index("-connect")
+        connect_val = captured["cmd"][connect_idx + 1]
+        assert connect_val.startswith("[::1]:")
+
+    def test_input_is_quit_crlf(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["kwargs"] = kw
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("example.com", 25)
+        assert captured["kwargs"].get("input") == b"QUIT\r\n"
+
+    def test_no_starttls_flag_when_none(self, monkeypatch):
+        captured = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _make_raw_proc()
+
+        monkeypatch.setattr("quantumvalidator.tls_utils.subprocess.run", fake_run)
+        probe_raw("example.com", 443)
+        assert "-starttls" not in captured["cmd"]
+
+    def test_non_utf8_output_decoded_with_replace(self, monkeypatch):
+        raw_bytes = b"ok \xff\xfe output"
+        monkeypatch.setattr(
+            "quantumvalidator.tls_utils.subprocess.run",
+            lambda *a, **kw: _make_raw_proc(stdout=raw_bytes),
+        )
+        result = probe_raw("example.com", 443)
+        assert result is not None
+        assert "ok" in result
+