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 thetypes
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 specifycache=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