pwncat.modules.enumerate module¶

Enumeration modules are the core information gathering mechanism within pwncat. Enumeration modules are a subclass of pwncat.modules.BaseModule. However, they extend the functionality of a module to cache results within the database and provide a structured way of specifying how often to execute a given enumeration.

An enumeration module returns a list of facts. Each fact must inherit from pwncat.db.Fact. Each fact that is generated is stored in the database, and deduplicated. A fact can have one or more types. A type is simply a string which identifies the kind of data the fact represents. When you define an enumeration module, you must specify a list of fact types which your module is capable of generating. This is so that pwncat can automatically locate facts of any type. Further, you must specify the “schedule” for your enumeration. Schedules identify whether a module should run only once, once per user or should run every time the given type is requested. Unlike base modules, enumeration modules do not accept any custom arguments. However, they do still require a list of compatible platforms.

Aside from schedules, you can also specify an enumeration scope. The default scope is Scope.HOST. This scope saves facts to the database which is shared between sessions and between instances of pwncat. Scope.SESSION defines facts which live only as long as the specific session is alive and are not shared with other sessions with the same target. The Scope.NONE scope specifies that facts are never saved. This is normally used with Schedule.ALWAYS to have enumeration modules run every time without saving the facts.

When defining an enumeration module, you must define the EnumerateModule.enumerate() method. This method is a generator which can yield either facts or status updates, just like the pwncat.modules.BaseModule.run() method.

Example Enumerate Module¶

class CustomFact(Fact):
    """ Custom fact data regarding the target """

    def __init__(self, source):
        super().__init__(source=source, types=["custom.fact.type"])

    def title(self, session: "pwncat.manager.Session"):
        return "[red]Custom Fact![/red]"

class Module(EnumerateModule):
    """ Module documentation """

    PLATFORM = [Windows]
    SCHEDULE = Schedule.PER_USER
    PROVIDES = ["custom.fact.type"]
    SCOPE = Scope.HOST

    def enumerate(self, session: "pwncat.manager.Session"):
        yield CustomFactObject(self.name)

class pwncat.modules.enumerate.EnumerateModule¶

Bases: pwncat.modules.BaseModule

Base class for all enumeration modules.

As discussed above, an enumeration module must define the enumerate() method, provide a list of supported platforms, a list of provided fact types and a schedule.

The base enumeration module’s run() method will provide a few routines and options. You can filter the results of this module with the types argument. This causes the module to only return the types specified. You can also tell the module to clear any cached data from the database generated by this module. Lastly, if you specify cache=False, the module will only return new facts that were not cached in the database already.

ARGUMENTS: Dict[str, Argument] = {'cache': Argument(type=<class 'bool'>, default=True, help='return cached facts along with new facts (default: True)'), 'clear': Argument(type=<class 'bool'>, default=False, help='If specified, do not perform enumeration. Cleared cached results.'), 'types': Argument(type=<function List.<locals>._ListType>, default=[], help='A list of enumeration types to retrieve (default: all)')}¶: Arguments accepted by all enumeration modules. This should not be overridden.

PLATFORM: List[Type[pwncat.platform.Platform]] = []¶: List of supported platforms for this module

PROVIDES: List[str] = []¶: List of fact types which this module is capable of providing

SCHEDULE: pwncat.modules.enumerate.Schedule = 3¶: Determine the run schedule for this enumeration module

SCOPE: pwncat.modules.enumerate.Scope = 1¶: Defines the scope for this fact (either host or session)

enumerate(session: pwncat.manager.Session) → Generator[pwncat.db.Fact, None, None]¶

Enumerate facts according to the types listed in PROVIDES.

Parameters: session (pwncat.manager.Session) – the session on which to enumerate

run(session: pwncat.manager.Session, types: List[str], clear: bool, cache: bool)¶

Locate all facts this module provides.

Sub-classes should not override this method. Instead, use the enumerate method. run will cross-reference with database and ensure enumeration modules aren’t re-run.

Parameters

session (pwncat.manager.Session) – the session on which to run the module
types (List[str]) – list of requested fact types
clear (bool) – whether to clear all cached enumeration data
cache (bool) – whether to return facts from the database or only new facts

enum pwncat.modules.enumerate.Schedule(value)¶

Bases: enum.Enum

Defines how often an enumeration module will run

Valid values are as follows:

ALWAYS = <Schedule.ALWAYS: 1>¶

PER_USER = <Schedule.PER_USER: 2>¶

ONCE = <Schedule.ONCE: 3>¶

enum pwncat.modules.enumerate.Scope(value)¶

Bases: enum.Enum

Defines whether the fact is scoped to the target host or to the active session. Session-scoped facts are lost when a session ends.

Valid values are as follows:

HOST = <Scope.HOST: 1>¶

SESSION = <Scope.SESSION: 2>¶

NONE = <Scope.NONE: 3>¶