diff --git a/docs/source/api/configuration.rst b/docs/source/api/configuration.rst new file mode 100644 index 0000000..4259e44 --- /dev/null +++ b/docs/source/api/configuration.rst @@ -0,0 +1,65 @@ +Configuration +============= + +Configuration in ``pwncat`` is tracked in the ``pwncat.config`` object. This object +acts similar to a dictionary with some extra features. Specifically, this object +implements type checking, and understands/tracks module context. + +There is a module named ``pwncat.config`` which contains some helper-types, but +generally should not be needed. It is masked behind an object defined in ``pwncat/__init__.py`` +named ``config``. The ``pwncat.config`` object is of the type ``pwncat.config.Config``. + +When used as a dictionary, only setting local values (specific to a module context) is +supported. Therefore, the following is valid within a module context: + +.. code-block:: python + + import pwncat + pwncat.config["lhost"] = "10.10.10.10" + +If you would like to set global configuration items, you must use the ``set`` method: + + +.. code-block:: python + + import pwncat + pwncat.config.set("lhost", "10.10.10.10", glob=True) + +When retreiving values, the preference is always for local module-context values. If +no module-specific values are set, then the global value is returned. You can use the +dictionary syntax for this: + +.. code-block:: python + + import pwncat + username = pwncat.config["backdoor_user"] + +To add available global configuration items, you can add items to the ``pwncat.config.values`` +dictionary. This dictionary maps configuration names to another dictionary. The structure +looks like this: + +.. code-block:: python + + pwncat.config.values["config_name"] = { + "value": "default or current value", + "type": callable_converting_string_to_correct_type + } + +The ``type`` property should be a callable which converts the input (normally a string`` +to the required type. If the required type is passed in, it should be returned unchanged. +If the provided value is invalid, a ``ValueError`` should be raised. + +If the value is a script (such as ``on_load``), the type will be a regular string. In this +case, the string is literally a script which will be evaluated upon some condition. + +Key Bindings +------------ + +Key bindings are handled separately from standard configuration items. They are managed +with the same configuration object, but are retrieved using the ``binding`` method. This method +takes either a string representing the name of the key or a bytes object representing the +raw key-codes. The keybindings are stored in the ``pwncat.config.bindings`` dictionary which +maps ``KeyType`` objects to the script which executes upon their press. + +This is mainly a UI/end-user function, and therefore the only clean method of modifying this +dictionary at the moment is through the ``set`` command. This may change in the future.