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.

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

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"]

    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, pwncat.modules.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 = 4

Determine the run schedule for this enumeration module

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>
NOSAVE = <Schedule.NOSAVE: 2>
PER_USER = <Schedule.PER_USER: 3>
ONCE = <Schedule.ONCE: 4>