Add Kerberos service authentication tracing

[eve0805]

Summary

Depends on #21717.

This PR extends KerberosTicketTrace to cover the Kerberos service-authentication exchange after a service ticket has been selected.

It builds on Rex::Proto::Gss::KerberosToken, introduced by #21717, and adds structured tracing for AP-REQ construction, GSS-Kerberos and SPNEGO encapsulation, and service-authentication responses.

Protocol-specific HTTP, SMB, LDAP, and MSSQL carrier hooks are intentionally excluded and will be submitted separately.

Functionality

The service authenticator now emits structured trace events for:

• AP-REQ construction and the selected service ticket
• GSS-Kerberos AP-REQ encapsulation
• SPNEGO NegTokenInit encapsulation
• GSS-Kerberos AP-REP responses
• Kerberos error responses
• SPNEGO NegTokenResp responses
• Mutual-authentication trace results, when mutual authentication is requested:
  • success after an AP-REP is parsed and decrypted
  • failed when the Kerberos response fails parsing/decryption or negotiation is rejected
  • incomplete when SPNEGO negotiation succeeds but no AP-REP has been validated in that trace event

The trace context includes, when available:

• Client and service principals
• SPN and realm
• Selected service-ticket metadata
• Ticket encryption type and flags
• Ticket validity times
• AP options
• Authenticator checksum
• Authenticator subkey and sequence number
• Replay-detection state
• Channel-binding presence and length
• Delegated-credential state

Malformed or unsupported tokens are rendered as structured parse failures without changing the existing authentication error behavior.

Trace presentation

The presentation and parsing responsibilities are separated into dedicated components:

• Rex::Proto::Kerberos::GssTokenParser

  • Adapts the shared token handling introduced by Add shared Kerberos GSS and SPNEGO token handling #21717 for trace presentation.
  • Parses GSS-Kerberos, SPNEGO NegTokenInit, and SPNEGO NegTokenResp metadata.

• Rex::Proto::Kerberos::ServiceAuthenticationTracePresenter

  • Presents AP-REQ, GSS/SPNEGO, AP-REP, and KRB-ERROR trace events.
  • Handles mutual-authentication and service-ticket context.

• Rex::Proto::Kerberos::KerberosTraceSerializer

  • Serializes Kerberos model objects, flags, enums, timestamps, and binary values into trace-friendly output.

KerberosLoggerSubscriber is reduced to trace-mode handling, event routing, headers, colors, and output dispatch.

Trace modes

The existing KerberosTicketTrace modes are preserved:

Mode	Service-authentication output
off	No trace output
metadata	Structured metadata with binary contents redacted
ticket	The selected service-ticket credential
full	Full AP-REQ/authenticator details and hexadecimal binary contents

Binary token payloads are summarized in metadata mode. Kerberos model fields, including checksums, keys, and encrypted fields, are serialized normally; printable string values may be shown, and non-printable binary strings are summarized.

Subscriber events

The Kerberos subscriber interface now supports:

• on_ap_req
• on_gss_token
• on_spnego_token
• on_response_token

These events keep service-authentication trace presentation separate from the authentication implementation.

Additional changes

• Corrects the AP-REP success message that previously referred to an AP-REQ.
• Updates the KerberosTicketTrace option description from ticket tracing to protocol tracing.
• Ensures temporary AP-REQ/authenticator trace context is removed before returning the authentication result.

Scope

This PR is limited to Kerberos service-authentication trace collection and presentation.

It does not add application-protocol carrier callbacks. HTTP, SMB, LDAP, and MSSQL integration will follow in a separate dependent PR.

Testing

The following affected test suites were run:

bundle exec rspec \
  spec/lib/rex/proto/kerberos \
  spec/lib/msf/core/exploit/remote/kerberos \
  spec/lib/msf/base/serializer/readable_text_spec.rb

[github-actions]

Thanks for your pull request! As part of our landing process, we manually verify that all modules work as expected.

We've added the additional-testing-required label to indicate that additional testing is required before this pull request can be merged.
For maintainers, this means visiting here.

[Copilot]

Pull request overview

Extends Kerberos tracing through service authentication while separating token parsing, serialization, and presentation.

Changes:

• Adds AP-REQ, GSS/SPNEGO, response-token, and mutual-authentication trace events.
• Adds dedicated parsers, serializers, presenters, and comprehensive RSpec coverage.
• Updates trace option wording and removes temporary trace context from authentication results.

Impact Analysis:

• Blast radius: Medium—shared Kerberos authentication and tracing used by multiple protocol clients.
• Data and contract effects: Adds subscriber events and trace output; no storage changes. Redaction and mutual-authentication accuracy require fixes.
• Rollback and test focus: No irreversible effects; prioritize metadata redaction and verified AP-REP result handling.

Reviewed changes

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

Show a summary per file

File	Description
lib/msf/core/exploit/remote/kerberos/client.rb	Updates trace option wording.
lib/msf/core/exploit/remote/kerberos/service_authenticator/base.rb	Emits service-authentication events and manages trace context.
lib/msf/core/exploit/remote/kerberos/service_authenticator/options.rb	Updates trace option description.
lib/rex/proto/kerberos/gss_token_parser.rb	Parses GSS and SPNEGO trace metadata.
lib/rex/proto/kerberos/kerberos_logger_subscriber.rb	Routes and formats new trace events.
lib/rex/proto/kerberos/kerberos_readable_text_presenter.rb	Adds labels for trace fields.
lib/rex/proto/kerberos/kerberos_subscriber.rb	Adds subscriber callback APIs.
lib/rex/proto/kerberos/kerberos_trace_serializer.rb	Serializes Kerberos objects for tracing.
lib/rex/proto/kerberos/service_authentication_trace_presenter.rb	Presents AP-REQ and response traces.
spec/lib/msf/base/serializer/readable_text_spec.rb	Updates option-output expectations.
spec/lib/msf/core/exploit/remote/kerberos/service_authenticator/base_spec.rb	Tests authentication trace emission and cleanup.
spec/lib/rex/proto/kerberos/gss_token_parser_spec.rb	Tests token parsing behavior.
spec/lib/rex/proto/kerberos/kerberos_logger_subscriber_spec.rb	Tests trace-mode output.
spec/lib/rex/proto/kerberos/kerberos_trace_serializer_spec.rb	Tests serialization and redaction.
spec/lib/rex/proto/kerberos/service_authentication_trace_presenter_spec.rb	Tests trace presentation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jenkins-eks-metasploit]

Additional test pipeline started ⌛
Note: build results only accessible to maintainers.

[jenkins-eks-metasploit]

Pipeline results available

Slice summary:

• Test slice 1 - 🟢
• Test slice 2 - 🟢
• Test slice 3 - 🟢
• Test slice 4 - 🟢

Note: build results only accessible to maintainers.