Sessions

CredSLayer’s sessions is probably the most important concept, it helps you create a context between loads of packets you “receive”. It will hold credentials you find and enables parsers to keep variables across per-packet analysis.

For example in telnet, data are transmitted line by line, and sometimes character by character. So the parser gathers those pieces of information and store them in a session variable that will be available to further packets belonging to the same session :

session["data_being_built"] += data

The lines that follow are directly taken from the code’s documentation and explain more in depth how sessions work.

class Session(packet: pyshark.packet.packet.Packet)

A Session object represents an exchange of packets between two parties. TCP and UDP communication are not considered in the same way. Put simply a session is a way of grouping packets together in order to create some context. CredSLayer identifies a TCP exchange based on the IP addresses and port of each party. Here’s an example of its string representation : “192.168.1.42:42000 <-> 42.42.42.42:443” This representation is the identity of a session, it’s what makes it unique. On the other hand, UDP being a stateless protocol, its source port cannot be relied on because it is always different. That’s why CredSLayer builds UDP sessions based on the source address and the destination address and port. Here’s a example of its string representation : “192.168.1.42 <-> 42.42.42.42:53”

protocol

The identified protocol, at first it will either be TCP or UDP, but it can be updated at any time to be more specific about what the protocol being analysed really is.

Type

str

credentials_being_built

Credentials going over the wire are often split into multiple packets (e.g. the username in a first packet, then the password in a second one), this is why each Session object has an instance of the Credentials object which will hold all the information being gathered to compose the credentials over time.

Type

Credentials

credentials_list

A list of credentials found so far in the session. Most of the time it will only hold a single Credentials instance.

Type

List[Credentials]

Raises

SessionException – This exception will occur if the session relative to a packet cannot be built (mostly because the packet isn’t TCP or UDP based).

invalidate_credentials_and_clear_session()

At some point, a CredSLayer parser should be able to identify that an unsuccessful authentication has been made, to tell CredSLayer the credentials_being_built are invalid and what it contains must be discarded, this method must be called. This will create a new instance of Credentials in order to build new potential incoming credentials of the same session.

validate_credentials()

At some point, a CredSLayer parser should be able to identify that a successful authentication has been made, to tell CredSLayer the credentials_being_built are valid, this method must be called. This will create a new instance of Credentials in order to build new potential incoming credentials of the same session.

exception SessionException

Exception related to the Session class.

class SessionsManager(remove_outdated=False)

The SessionsManager object is basically a list of Session objects, it will most likely be created once and be used during the whole program’s lifespan. It ensures the uniqueness of a Session, can delete outdated sessions and enables the developer to retrieve data about all the sessions at once (e.g. all credentials found so far).

get_list_of_all_credentials() → List[credslayer.core.utils.Credentials]

Returns

A list of all valid Credentials instances built during the whole SessionManager lifespan.

Return type

List[Credentials]

get_remaining_content() → List[Tuple[credslayer.core.session.Session, credslayer.core.utils.Credentials]]

Sometimes CredSLayer parsers are not able to tell if the provided credentials were valid or not, the Session instance still conserves those, and this method is here to return what’s remaining in all sessions.

Returns

Each entry is a tuple of the Session instance and the remaining credentials_being_built.

Return type

List[Tuple[Session, Credentials]]

get_session_of(packet: pyshark.packet.packet.Packet) → credslayer.core.session.Session

Parameters

packet (Packet) – The packet from which the Session object will be created or retrieved.

Returns

This method returns the Session object associated to the given packet.

Return type

Session

stop_managed_sessions()

Will stop threads managing sessions.