Example scripts documentation

ChangeLog.md

@@ -19,7 +19,7 @@ v0.2.0.dev0 - unreleased
 - Documentation: Added references to SAP Secure Storage and SSFS research.
 - `pysap/SAPCredv2.py`: Added subject fields instead of commonName for LPS-enabled credentials ([\#35](https://github.com/OWASP/pysap/issues/35)). Thanks [@rstenet](https://github.com/rstenet)!
 - `pysap/SAPCredv2.py`: Add support for cipher format version 1 with 3DES ([\#35](https://github.com/OWASP/pysap/issues/35) and [\#37](https://github.com/OWASP/pysap/pull/37)). Thanks [@rstenet](https://github.com/rstenet)!
-- `pysap/SAPHDB.py`: Added missing `StatementContextOption` values (see [\#22](https://github.com/SecureAuthCorp/SAP-Dissection-plug-in-for-Wireshark/issues/22)).
+- `pysap/SAPHDB.py`: Added missing `StatementContextOption` values (see [\#22](https://github.com/SecureAuthCorp/SAP-Dissection-plug-in-for-Wireshark/pull/22)).
 
 
 v0.1.19 - 2021-04-29
@@ -32,7 +32,7 @@ v0.1.19 - 2021-04-29
 - `pysap/SAPHDB.py`: Implementation of GSS-based auth method with Kerberos 5.
 - `pysap/SAPHDB.py`: Handling of Session Cookie values when found in the `CONNECT` response.
 - `pysap/SAPRouter.py`: Add support to route string in `SAPRouterNativeProxy` ([\#33](https://github.com/OWASP/pysap/pull/33)). Thanks [@gloomicious](https://github.com/gloomicious)!
-- `examples/router_fingerprints.json`: New fingerprints for SAP Router version 7450.34.25.5091. Thanks [@jvis](https://twitter.com/jvis)!
+- `examples/router_fingerprints.json`: New fingerprints for SAP Router version 7450.34.25.5091. Thanks [@jvis](https://x.com/jvis)!
 - `examples/router_portfw.py`: Add support to route string. ([\#33](https://github.com/OWASP/pysap/pull/33)) Thanks [@gloomicious](https://github.com/gloomicious)!
 - `tests/sapssfs_test.py`: Basic unit tests for the SSFS file format.
 
@@ -67,8 +67,8 @@ v0.1.17 - 2019-11-05
 - `bin/pysapcar`: Add cli option to determine output directory when extracting archives with pysapcar ([\#24](https://github.com/OWASP/pysap/pull/24)) Thanks [@okuuva](https://github.com/okuuva)!
 - `pysap/SAPDiag.py`: Added support bits for SAP GUI 7.50 and SAP NW 7.52 SP01.
 - `pysap/SAPCAR.py`: Fixed crafting of archive files by defaulting length fields to zero ([\#22](https://github.com/OWASP/pysap/issues/22)) Thanks [@okuuva](https://github.com/okuuva)!
-- `pysap/SAPMS.py`: Added the `DPInfo[1-3]` packets for handling specific Message Server `ADM` packets relaying Dispatcher/WP info: `[1-3]` because of tight SAP kernel version dependency. ([\#31](https://github.com/OWASP/pysap/pull/31)) Thanks Mathieu ([@gelim](https://github.com/gelim)) and Dmitry ([@_chipik](https://twitter.com/_chipik))!
-- `pysap/SAPRFC.py`: Enhanced with mainly `SAPCPIC*` and `SAPRFXPG*` new packets. ([\#31](https://github.com/OWASP/pysap/pull/31)) Thanks Mathieu ([@gelim](https://github.com/gelim)) and Dmitry ([@_chipik](https://twitter.com/_chipik))!
+- `pysap/SAPMS.py`: Added the `DPInfo[1-3]` packets for handling specific Message Server `ADM` packets relaying Dispatcher/WP info: `[1-3]` because of tight SAP kernel version dependency. ([\#31](https://github.com/OWASP/pysap/pull/31)) Thanks Mathieu ([@gelim](https://github.com/gelim)) and Dmitry ([@_chipik](https://x.com/_chipik))!
+- `pysap/SAPRFC.py`: Enhanced with mainly `SAPCPIC*` and `SAPRFXPG*` new packets. ([\#31](https://github.com/OWASP/pysap/pull/31)) Thanks Mathieu ([@gelim](https://github.com/gelim)) and Dmitry ([@_chipik](https://x.com/_chipik))!
 - `pysap/SAPRouter.py`: Fixed padding on SAPRouter client info packets.
 - `examples/rfc_monitor.py`: Renamed the script to `gw_monitor.py`.
 - `examples/router_scanner.py`: Add capability to provide a comma separated list of targets/ports to scan.
@@ -132,8 +132,8 @@ v0.1.14 - 2017-10-04
   Thanks [@gelim](https://github.com/gelim)!.
 - `examples/ms_dump_param.py`: New example script to list Message Server parameters and check them against a list of
   expected values ([\#15](https://github.com/OWASP/pysap/pull/15)). Thanks [@iggy38](https://github.com/iggy38)!
-- `examples/ms_dos_exploit.py`: New example script to check for [CVE-2017-5997](https://erpscan.com/advisories/erpscan-16-038-sap-message-server-http-remote-dos/)
-  DoS vulnerability on Message Server and fixed at [SAP Note 2358972](https://launchpad.support.sap.com/#/notes/2358972)
+- `examples/ms_dos_exploit.py`: New example script to check for [CVE-2017-5997](https://web.archive.org/web/20180125175227/https://erpscan.com/advisories/erpscan-16-038-sap-message-server-http-remote-dos/)
+  DoS vulnerability on Message Server and fixed at [SAP Note 2358972](https://me.sap.com/notes/2358972)
   ([\#10](https://github.com/OWASP/pysap/pull/10)). Thanks [@vah13](https://github.com/vah13) and [@gelim](https://github.com/gelim)!
 
 
@@ -164,8 +164,8 @@ v0.1.12 - 2016-12-16
 - Building and testing in OSX with Travis and Windows with Appveyor.
 - `pysap/SAPDiagItems.py`: Added default support bits from SAP GUI 7.40 version.
 - `examples/diag_capturer.py`: Added option to display available capture interfaces.
-- `examples/enqueue_dos_exploit.py`: New example script to check for [CVE-2016-4015](https://erpscan.com/advisories/erpscan-16-019-sap-netweaver-enqueue-server-dos-vulnerability/)
-  DoS vulnerability on Standalone Enqueue Server and fixed at [SAP Note 2258784](https://launchpad.support.sap.com/#/notes/0002258784)
+- `examples/enqueue_dos_exploit.py`: New example script to check for [CVE-2016-4015](https://seclists.org/fulldisclosure/2016/Jul/44)
+  DoS vulnerability on Standalone Enqueue Server and fixed at [SAP Note 2258784](https://me.sap.com/notes/2258784)
   ([\#6](https://github.com/OWASP/pysap/pull/6)). Thanks [@vah13](https://github.com/vah13)!
 - `examples/router_fingerprints.json`: Added fingerprints from SAP Router releases 745.
 
@@ -180,8 +180,8 @@ v0.1.11 - 2016-10-12
 - `pysap/SAPDiag.py`: Splitted `SBA`/`SFE`/`SLC` fields.
 - `pysap/SAPDiag.py`: Renamed error flag to error number.
 - `examples/diag_capturer.py`: Fix imports for running diag capturer example script in Windows.
-- `examples/diag_login_brute_force.py`: Added SOLMAN [default](https://www.troopers.de/media/filer_public/37/34/3734ebb3-989c-4750-9d48-ea478674991a/an_easy_way_into_your_sap_systems_v30.pdf)
-  [credentials](https://launchpad.support.sap.com/#/notes/2293011) and improved reading credentials file.
+- `examples/diag_login_brute_force.py`: Added SOLMAN [default](https://troopers.de/media/filer_public/37/34/3734ebb3-989c-4750-9d48-ea478674991a/an_easy_way_into_your_sap_systems_v30.pdf)
+  [credentials](https://me.sap.com/notes/2293011) and improved reading credentials file.
 
 
 v0.1.10 - 2016-03-25
@@ -191,10 +191,10 @@ v0.1.10 - 2016-03-25
 - Added support for handling SAP SAR file formats.
 - `pysap/SAPCAR.py`: New module for handling SAP SAR file formats.
 - `extra/dlmanager_decrypt.py`: Example PoC for [decrypting](https://www.coresecurity.com/advisories/sap-download-manager-password-weak-encryption)
-  [SAP Download Manager](https://support.sap.com/software/download-manager.html) stored passwords.
+  [SAP Download Manager](https://support.sap.com/en/my-support/software-downloads.html) stored passwords.
 - `examples/dlmanager_infector.py`: Example script to open a SAP SAR archive file and infect it by adding files with
   arbitrary filenames (e.g. including absolute or relative paths). It can be also used as a
-  [mitmproxy](https://mitmproxy.org/) script for on-the-fly infecting SAR files being downloaded.
+  [mitmproxy](https://www.mitmproxy.org/) script for on-the-fly infecting SAR files being downloaded.
 
 
 v0.1.9 - 2016-02-08
@@ -214,7 +214,7 @@ v0.1.8 - 2015-10-29
 - Enabled travis containers for more quick builds.
 - Minor documentation and README improvements.
 - `pysap/SAPRouter.py`: Documented some version numbers from old releases ([\#3](https://github.com/OWASP/pysap/pull/3)). Thanks [invisiblethreat](https://github.com/invisiblethreat)!
-- `pysapcompress/vpa108csulzh.cpp`: Improved the fix for CVE-2015-2278 by properly initializing arrays ([\#4](https://github.com/OWASP/pysap/pull/4)). Thanks [ret5ret](https://github.com/ret5ret)!
+- `pysapcompress/vpa108csulzh.cpp`: Improved the fix for CVE-2015-2278 by properly initializing arrays ([\#4](https://github.com/OWASP/pysap/pull/4)). Thanks [ret5et](https://github.com/ret5et)!
 - `examples/diag_render_login_screen.py`: Fail gracefully if `wx` is not found.
 - `examples/router_password_check.py`: Updating the `fau_timer` library in use and failing gracefully if it's not found.
 - `examples/router_fingerprint.py`: New example script for performing fingerprint over SAP Router versions.
@@ -257,7 +257,7 @@ v0.1.5 - 2015-01-16
 - `pysap/SAPDiag.py`: Diag item lookup now support looking up multiple items, and string lookups.
 - `pysap/SAPDiagClient.py`: Added support for specifying support bits when connecting, support for routing via SAP Router.
 - `pysap/SAPDiagClient.py`: If no terminal is supplied, use a random looking IP by default to avoid identification
-  ([SAP Note 1497445](https://launchpad.support.sap.com/#/notes/1497445)).
+  ([SAP Note 1497445](https://me.sap.com/notes/1497445)).
 - `pysap/SAPDiagItems.py`: Fixes on some atom items for old versions.
 - `pysap/SAPEnqueue.py`: Added trace max file size field.
 - `pysap/SAPNI.py`: Added helpers for creating new connections.

docs/conf.py

@@ -87,6 +87,15 @@ def skip_scapy_iface_reload(self):
 # This pattern also affects html_static_path and html_extra_path .
 exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
 
+# Some reader-facing references are behind login pages or bot-protection
+# challenges and cannot be validated reliably by Sphinx linkcheck.
+linkcheck_ignore = [
+    r'https://me\.sap\.com/notes/.*',
+    r'https://support\.sap\.com/content/dam/.*',
+    r'https://www\.coresecurity\.com/.*',
+    r'https://www\.wxpython\.org/.*',
+]
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 

docs/dev/index.rst

@@ -48,7 +48,7 @@ Notebooks
 
 Documentation include a graphical representation of the most commonly used protocol packets and file formats. This
 graphical representations are built using `Scapy <https://scapy.net/>`_,
-`The Jupyter Notebook <https://ipython.org/notebook.html>`_ , `nbconvert <https://github.com/jupyter/nbconvert>`_ and
+`The Jupyter Notebook <https://docs.jupyter.org/en/latest/>`_ , `nbconvert <https://github.com/jupyter/nbconvert>`_ and
 `nbsphinx <https://github.com/spatialaudio/nbsphinx/>`_.
 
 Jupyter notebooks containing the protocol packets' representation can be

docs/examples/diag.rst

@@ -16,14 +16,14 @@ denote password or other sensitive fields that should be masked by the SAP GUI.
 ``diag_dos_exploit``
 --------------------
 
-This example script can be used to tests against Denial of Service vulnerabilities affecting the
+This example script can be used to test against Denial of Service vulnerabilities affecting the
 Dispatcher service. Currently 5 different vulnerabilities can be triggered:
 
-- `CVE-2012-2612 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2012-2612>`_
-- `CVE-2012-2511 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2012-2511>`_
-- `CVE-2012-2512 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2012-2512>`_
-- `CVE-2012-2513 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2012-2513>`_
-- `CVE-2012-2514 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2012-2514>`_
+- `CVE-2012-2612 <https://www.cve.org/CVERecord?id=CVE-2012-2612>`_
+- `CVE-2012-2511 <https://www.cve.org/CVERecord?id=CVE-2012-2511>`_
+- `CVE-2012-2512 <https://www.cve.org/CVERecord?id=CVE-2012-2512>`_
+- `CVE-2012-2513 <https://www.cve.org/CVERecord?id=CVE-2012-2513>`_
+- `CVE-2012-2514 <https://www.cve.org/CVERecord?id=CVE-2012-2514>`_
 
 
 ``diag_interceptor``
@@ -41,17 +41,17 @@ them.
 --------------------------
 
 This example script can be used to perform a brute force attack against a SAP Netweaver
-application server. The scripts performs a login through the Diag protocol, by submitting
+application server. The script performs a login through the Diag protocol, by submitting
 username and passwords to the login screen. It can also be used to discover available clients.
 
 Usernames, passwords and SAP clients to test can be provided as individual files (using
-``--usernames``, ``--passwords`` and ``--clients`` command line options), in which case the
+``--usernames``, ``--passwords`` and ``--client`` command line options), in which case the
 script will calculate and test the combination of those, or provided in a credentials file
 (via the ``--credentials`` parameter). The credential file is expected to have a format
 containing ``username:password:client`` and blank lines or lines starting with the ``#`` are
 ignored.
 
-Clients discovery can be also performed as a firs step of the brute-force attack, by specifying
+Client discovery can also be performed as a first step of the brute-force attack, by specifying
 the ``--discovery`` option and providing a list of clients to test using the ``--discovery-range``
 parameter.
 
@@ -70,12 +70,12 @@ with care and at your own risk.
 Finally, the ``login/show_detailed_errors`` parameter can be configured to ``FALSE`` in the SAP
 Application Server to avoid disclosing information about whether a client exists or not, and
 to avoid returning information about existent users. For more information see
-`SAP Security Note 1823687 <https://launchpad.support.sap.com/#/notes/1823687>`_.
+`SAP Security Note 1823687 <https://me.sap.com/notes/1823687>`_.
 
 If the parameter is configured to ``FALSE``, the results of the discovery will be flawed, with
 probably a large set (if not all) of clients invalidly reported as existent. The same false
 positives will be reported for user names validity. The finding of valid credentials is not
-affected thought.
+affected though.
 
 
 ``diag_login_screen_info``

docs/examples/dlmanager.rst

@@ -6,7 +6,7 @@ Download Manager scripts
 ``dlmanager_decrypt``
 ---------------------
 
-This example script extract SAP's Download Manager stored passwords. For SAP Download Manager
+This example script extracts SAP Download Manager stored passwords. For SAP Download Manager
 versions before ``2.1.140a``, stored passwords were kept unencrypted. For versions between
 ``2.1.140a`` and ``2.1.142``, the script should be able to decrypt the password given possible
 to obtain the machine serial number.
@@ -18,9 +18,17 @@ The script can attempt to retrieve the machine serial number when running on Win
 provided with the ``--retrieve-serial-number`` option. For other platforms it must need to be
 provided by the ``--serial-number`` parameter.
 
+Example usage:
+
+.. code-block:: console
+
+    $ examples/dlmanager_decrypt.py -f dlmanager.conf
+    $ examples/dlmanager_decrypt.py -f dlmanager.conf --encrypted --serial-number <serial-number>
+    $ examples/dlmanager_decrypt.py -f dlmanager.conf --encrypted --retrieve-serial-number
+
 For more details on the encryption mechanism see
-`CVE-2016-3685 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2016-3685>`_ and
-`CVE-2016-3684 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2016-3684>`_ documented in the
+`CVE-2016-3685 <https://www.cve.org/CVERecord?id=CVE-2016-3685>`_ and
+`CVE-2016-3684 <https://www.cve.org/CVERecord?id=CVE-2016-3684>`_ documented in the
 `SAP Download Manager Password Weak Encryption security advisory <https://www.coresecurity.com/advisories/sap-download-manager-password-weak-encryption>`_.
 
 
@@ -36,5 +44,11 @@ In that case, the scripts takes the files to inject as parameters, performs an `
 MitM and when identifies a ``SAR`` file that is going to be offered as a download it infects it.
 
 For more details about the exemplified attack vector see the `Deep-dive into SAP
-archive file formats <https://www.troopers.de/events/troopers16/628_deep-dive_into_sap_archive_file_formats/>`_
+archive file formats <https://troopers.de/events/troopers16/628_deep-dive_into_sap_archive_file_formats/>`_
 presentation at Troopers' 2016.
+
+Example usage for a local SAR archive:
+
+.. code-block:: console
+
+    $ examples/dlmanager_infector.py -f package.SAR payload.sh usr/sap/payload.sh

docs/examples/enqueue.rst

@@ -6,10 +6,10 @@ Enqueue Example scripts
 ``enqueue_dos_exploit``
 -----------------------
 
-This example script can be used to tests against a Denial of Service vulnerability affecting
-the Enqueue service (`CVE-2016-4015 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2016-4015>`_).
+This example script can be used to test against a Denial of Service vulnerability affecting
+the Enqueue service (`CVE-2016-4015 <https://www.cve.org/CVERecord?id=CVE-2016-4015>`_).
 For more details about the vulnerability see
-`ERPScan's Security Advisory <https://erpscan.com/advisories/erpscan-16-019-sap-netweaver-enqueue-server-dos-vulnerability/>`_.
+`ERPScan's Security Advisory mirror <https://seclists.org/fulldisclosure/2016/Jul/44>`_.
 
 This example script was contributed by `Vahagn Vardanyan <https://github.com/vah13>`_.
 
@@ -18,8 +18,18 @@ This example script was contributed by `Vahagn Vardanyan <https://github.com/vah
 -------------------
 
 This script is an example implementation of SAP's Enqueue Server Monitor program (``ens_mon``).
-It allows the monitoring of a Enqueue Server service and allows sending different admin commands
-and opcodes. Includes some commands not available on the ``ensmon`` program.
+It allows the monitoring of an Enqueue Server service and allows sending different admin commands
+and opcodes. It includes some commands not available on the ``ensmon`` program.
 
 The script implements a console-like interface that can be used to specify the operations to
-perform on the Enqueue Server. A list of implemented commands can be obtained by running ``help``.
+perform on the Enqueue Server. It connects with ``--remote-host`` and ``--remote-port`` (default
+``3200``), or through a SAP Router route string with ``--route-string``. The client name can be
+changed with ``--client``. Packet logs can be written with ``--log-file``, console output can be
+written with ``--console-log``, and commands can be loaded from a file with ``--script``. A list of
+implemented commands can be obtained by running ``help`` inside the console.
+
+Example usage:
+
+.. code-block:: console
+
+    $ examples/enqueue_monitor.py -d <enqueue-host> -p 3200 --script enqueue_commands.txt

docs/examples/gw.rst

@@ -6,4 +6,24 @@ Gateway Example scripts
 ``gw_monitor``
 --------------
 
-XXX
+This script is an example implementation of SAP's Gateway monitor program
+(``gwmon``). It allows monitoring a Gateway service and sending admin commands
+and opcodes through a console-like interface. Some commands require the Gateway
+service to allow monitor access.
+
+The monitor connects to the target Gateway with ``--remote-host`` and
+``--remote-port`` (default ``3300``), or through a SAP Router route string with
+``--route-string``. The Gateway protocol version can be selected with
+``--version`` and defaults to ``3``. The client name sent by the monitor can be
+changed with ``--client``.
+
+The script can write packet logs with ``--log-file`` and console output with
+``--console-log``. It can also execute commands from a file with ``--script``.
+After connecting, run ``help`` inside the console to list the implemented
+commands.
+
+Example usage:
+
+.. code-block:: console
+
+    $ examples/gw_monitor.py -d <gateway-host> -p 3300 --client pysap-monitor --log-file gw.log