Implement starttls

[vikerup]

Implementation of LDAP STARTTLS. Useful if LDAPS in unavailable while DC still requires signing/TLS

Get kerberos ticket:

getTGT.py test.local/administrator:$DAPW

export KRB5CCNAME=~/administrator.ccache

pywhisker  -t demomachine\$ -a list -u administrator -k --dc-ip 100.64.5.200 -d test.local
[!] automatic bind not successful - strongerAuthRequired

pywhisker  -t demomachine\$ -a list -u administrator -k --dc-ip 100.64.5.200 -d test.local --use-starttls
[*] Searching for the target account
[*] Target user found: CN=DEMOMACHINE,CN=Computers,DC=test,DC=local
[*] Listing devices for demomachine$
[*] DeviceID: fbf8fb45-7e50-c9a8-dd82-c65676d9c082 | Creation Time (UTC): 2025-10-03 12:32:57.648661

[vikerup]

pywhisker is using ldap3 which does not seem to support username+password or NTLM hash when LDAP signing is enforced:

cannatag/ldap3#889
cannatag/ldap3#1049

[Copilot]

Pull request overview

Adds LDAP STARTTLS support to pyWhisker so it can upgrade a plaintext LDAP connection (389) to TLS when LDAPS (636) isn’t available but the DC enforces signing/TLS.

Changes:

• Introduces --use-starttls and a new STARTTLS-based LDAP connection initializer.
• Improves bind failure error handling for NTLM binds and Kerberos SASL bind failures with actionable guidance.
• Updates README usage options to mention the new STARTTLS flag.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
pywhisker/pywhisker.py	Adds STARTTLS connection path, wiring via --use-starttls, and improves bind error messaging.
README.md	Documents the new --use-starttls CLI option.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

start_tls() is called but its return value isn’t checked. In ldap3, STARTTLS negotiation can fail and return False without raising, which would cause the subsequent bind() to send credentials over an unencrypted connection. Check the result of start_tls() (and/or ldap_session.tls_started) and raise an error before binding if TLS was not successfully established.

[Copilot]

The STARTTLS TLS-version fallback only catches LDAPSocketOpenError, but STARTTLS negotiation/handshake failures typically surface as start_tls() returning False or raising a STARTTLS/TLS-related exception instead. This can prevent fallback and/or lead to confusing errors. Consider checking the start_tls() result and broadening the exception handling to include STARTTLS/TLS handshake failures (and surface a clear error) before retrying with the older TLS version.

Suggested change

	return init_ldap_starttls_connection(target, ssl.PROTOCOL_TLSv1_2, args, domain, username, password, lmhash, nthash, logger)
	except ldap3.core.exceptions.LDAPSocketOpenError:
	return init_ldap_starttls_connection(target, ssl.PROTOCOL_TLSv1, args, domain, username, password, lmhash, nthash, logger)
	return init_ldap_starttls_connection(
	target,
	ssl.PROTOCOL_TLSv1_2,
	args,
	domain,
	username,
	password,
	lmhash,
	nthash,
	logger,
	)
	except (
	ldap3.core.exceptions.LDAPSocketOpenError,
	ldap3.core.exceptions.LDAPStartTLSError,
	ssl.SSLError,
	) as e:
	if logger is not None:
	logger.warning(
	f"[!] STARTTLS failed with TLSv1_2 for {target}: {e}. Retrying with TLSv1."
	)
	try:
	return init_ldap_starttls_connection(
	target,
	ssl.PROTOCOL_TLSv1,
	args,
	domain,
	username,
	password,
	lmhash,
	nthash,
	logger,
	)
	except (
	ldap3.core.exceptions.LDAPSocketOpenError,
	ldap3.core.exceptions.LDAPStartTLSError,
	ssl.SSLError,
	) as e2:
	raise Exception(
	f"[ERROR] Failed to establish STARTTLS LDAP connection to {target} "
	f"using both TLSv1_2 and TLSv1: {e2}"
	)

[Copilot]

--use-starttls, --use-ldaps, and --use-schannel can currently be provided together; the code will silently prioritize one path (e.g., STARTTLS wins over LDAPS). This is ambiguous for users and can mask misconfiguration. Consider making these options mutually exclusive in argparse (or validating after parsing) and erroring out when more than one transport mode is selected.

[Copilot]

The README’s detailed options list was updated with --use-starttls, but the usage synopsis earlier in the same code block still omits this flag. Please update the synopsis line as well so the README output matches the current CLI.