From 21e259fa7341a6c0f9de53cf2059b226c8972d76 Mon Sep 17 00:00:00 2001 From: hakril Date: Fri, 21 Dec 2018 16:18:19 +0100 Subject: [PATCH] Update some doc/samples for new module/features --- docs/source/conf.py | 28 +++++++++++++++++++++++ docs/source/index.rst | 3 ++- docs/source/process.rst | 6 ----- docs/source/sample.rst | 48 +++++++++++++++++++++++++++++++++++++++ docs/source/security.rst | 18 ++++++++++----- docs/source/windows.rst | 1 + docs/source/winobject.rst | 1 + windows/security.py | 2 +- 8 files changed, 93 insertions(+), 14 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index f622bc2..5b9cf0a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,6 +14,8 @@ import sys import os +import sphinx +import docutils # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -45,6 +47,7 @@ extensions = [ ] autodoc_default_flags = ['inherited-members'] +# autodoc_member_order = "groupwise" todo_include_todos = True # Add any paths that contain templates here, relative to this directory. @@ -375,5 +378,30 @@ def get_rst(app, what, name, obj, options, lines): def get_rst2(app, what, name, obj, options, signature, return_annotation): pass + +# Test code to handle :class:`gdef.STRUCTURE_NAME` +# demo of custom xref for not-found structures +# Test was for ref to 'SECURITY_DESCRIPTOR_CONTROL' in SecurityDescriptor.control +def miss_ref(app, env, node, contnode): + # import pdb;pdb.set_trace() + if not node["reftype"] == "class": + return + print(node, node["reftype"], node["reftarget"], contnode) + # import pdb;pdb.set_trace() + + if "SECURITY_DESCRIPTOR_CONTROL" not in node["reftarget"]: + return + + res = docutils.nodes.reference("", "") + py_domain = env.domains["py"] + full_name = "windows.generated_def.winstructs.{0}".format(node["reftarget"].rsplit(".", 1)[-1]) + t = [x for x in py_domain.get_objects() if full_name == x[0]][0] + res["refdocname"] = node["refdoc"] + res.append(contnode) + uri = app.builder.get_relative_uri(node["refdoc"], t[3]) + res['refuri'] = "{0}#{1}".format(uri, t[0]) + return res + def setup(app): app.add_stylesheet('css/mbasic.css') # may also be an URL + # app.connect('missing-reference', miss_ref) diff --git a/docs/source/index.rst b/docs/source/index.rst index fbae528..7a2170d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -35,7 +35,7 @@ You can install PythonForWindows using the ``setup.py`` at the root of the proje python setup.py install In its current state the project only support Python2 and -``setup.py`` will raise an :class:`NotImplementedError` is launched from python3. +``setup.py`` will raise an :class:`NotImplementedError` if launched from python3. .. warning:: @@ -54,6 +54,7 @@ Documentation winobject.rst native_exec.rst winproxy.rst + security.rst pipe.rst utils.rst wintrust.rst diff --git a/docs/source/process.rst b/docs/source/process.rst index 575a64e..4321dca 100644 --- a/docs/source/process.rst +++ b/docs/source/process.rst @@ -50,12 +50,6 @@ WinThread :show-inheritance: :inherited-members: -Token -''''' - -.. autoclass:: Token - :members: - :inherited-members: PEB Exploration diff --git a/docs/source/sample.rst b/docs/source/sample.rst index 645ffe8..683b1e1 100644 --- a/docs/source/sample.rst +++ b/docs/source/sample.rst @@ -67,6 +67,18 @@ Output .. literalinclude:: samples_output\process_iat_hook.txt +.. _token_sample: + +Token +""""" + +.. literalinclude:: ..\..\samples\token\token_demo.py + +Output + +.. literalinclude:: samples_output\token_token_demo.txt + + .. _sample_system: @@ -226,6 +238,17 @@ Output .. literalinclude:: samples_output\debug_debugger_print_LdrLoaddll.txt +.. _sample_debugger_on_setup: + +on_setup +~~~~~~~~ + +.. literalinclude:: ..\..\samples\debug\debugger_on_setup.py + + +Output + +.. literalinclude:: samples_output\debug_debugger_on_setup.txt Single stepping @@ -523,3 +546,28 @@ Output .. literalinclude:: samples_output\pipe_child_send_object.txt + +.. _sample_security: + +:mod:`windows.security` +""""""""""""""""""""""" + +Security Descriptor +''''''''''''''''''' + +.. literalinclude:: ..\..\samples\security\security_descriptor.py + +Output + +.. literalinclude:: samples_output\security_security_descriptor.txt + +.. _sample_security_sacl: + +Query SACL +'''''''''' + +.. literalinclude:: ..\..\samples\security\query_sacl.py + +Output + +.. literalinclude:: samples_output\security_query_sacl.txt diff --git a/docs/source/security.rst b/docs/source/security.rst index 7321d5d..8ddc124 100644 --- a/docs/source/security.rst +++ b/docs/source/security.rst @@ -12,6 +12,12 @@ .. module:: windows.security +This module give access to :class:`SecurityDescriptor` and related structures (``Acl`` & ``Ace``). + +.. note:: + + See sample :ref:`sample_security` + SecurityDescriptor """""""""""""""""" @@ -218,36 +224,36 @@ SystemProcessTrustLabelACE Ace common base -""""""""""""""" +''''''''''''''' These classes are internals and here for completness sake. You should not need to instanciate/use them directly. AceHeader -''''''''' +~~~~~~~~~ .. autoclass:: AceHeader AceBase -''''''' +~~~~~~~ .. autoclass:: AceBase MaskAndSidACE -''''''''''''' +~~~~~~~~~~~~~ .. autoclass:: MaskAndSidACE CallbackACE -''''''''''' +~~~~~~~~~~~ .. autoclass:: CallbackACE ObjectRelatedACE -'''''''''''''''' +~~~~~~~~~~~~~~~~ .. autoclass:: ObjectRelatedACE diff --git a/docs/source/windows.rst b/docs/source/windows.rst index 8da568f..057bc6f 100644 --- a/docs/source/windows.rst +++ b/docs/source/windows.rst @@ -16,6 +16,7 @@ The submodules that you might use by themself are: * :mod:`windows.native_exec` * :mod:`windows.winproxy` * :mod:`windows.wintrust` + * :mod:`windows.security` * :mod:`windows.crypto` * :mod:`windows.utils` * :mod:`windows.debug` diff --git a/docs/source/winobject.rst b/docs/source/winobject.rst index 11f3e5b..e0737b5 100644 --- a/docs/source/winobject.rst +++ b/docs/source/winobject.rst @@ -10,6 +10,7 @@ This sections describes them by group of relation. :maxdepth: 3 process.rst + token.rst exception.rst registry.rst network.rst diff --git a/windows/security.py b/windows/security.py index 0c52686..4605a52 100644 --- a/windows/security.py +++ b/windows/security.py @@ -597,7 +597,7 @@ class SecurityDescriptor(gdef.PSECURITY_DESCRIPTOR): To query the SACL enable the ``SeSecurityPrivilege`` and use the parameter ``query_sacl=True`` on the functions expecting a ``flags`` - see SACL sample + see :ref:`Query SACL sample ` """ _close_function = winproxy.LocalFree