diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d56ecd8f..b37a2e26 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -17,7 +17,7 @@ Anyone wanting to contribute to OpenStack must follow All changes should be submitted through the code review process in Gerrit described above. All pull requests on Github will be closed/ignored. -Bugs should be filed on the `Syntribos launchpad site `__, +Bugs should be filed on the `syntribos launchpad site `__, and not on Github. All Github issues will be closed/ignored. Breaking changes, feature requests, and other unprioritized work should first be diff --git a/README.rst b/README.rst index 0bdfd44b..a54eea08 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,10 @@ +================================================= Syntribos, An Automated API Security Testing Tool ================================================= :: - Syntribos + syntribos xxxxxxx x xxxxxxxxxxxxx x x xxxxxxxxxxx x @@ -34,37 +35,151 @@ Syntribos, An Automated API Security Testing Tool Syntribos is an automated API security testing tool that is maintained by members of the `OpenStack Security Project `__. -Given a simple configuration file and an example HTTP request, Syntribos +Given a simple configuration file and an example HTTP request, syntribos can replace any API URL, URL parameter, HTTP header and request body -field with a given set of strings. This is similar to Burp Proxy's -Intruder sniper attack, but Syntribos iterates through each position -automatically. Syntribos aims to automatically detect common security -defects such as SQL injection, LDAP injection, buffer overflow, etc. In -addition, Syntribos can be used to help identifying new security defects -by fuzzing. +field with a given set of strings. Syntribos iterates through each position +in the request automatically. Syntribos aims to automatically detect common +security defects such as SQL injection, LDAP injection, buffer overflow, etc. In +addition, syntribos can be used to help identify new security defects +by automated fuzzing. Syntribos has the capability to test any API, but is designed with `OpenStack `__ applications in mind. +List of Tests +~~~~~~~~~~~~~ + +Syntribos is shipped with batteries included, which means, with minimal +configuration effort you can initiate automated testing of any API of +your choice. If testing OpenStack API is in your mind, then syntribos +by default will help you in automatically downloading a set of templates +of some of the bigger OpenStack projects like nova, neutron, keystone etc. + +A short list of tests that can be run using syntribos is given below: + +* Buffer Overflow +* Command Injection +* CORS Wildcard +* Integer Overflow +* LDAP Injection +* SQL Injection +* String Validation +* XML External Entity +* Cross Site Scripting ( XSS ) + +Buffer Overflow +--------------- + +The idea of `buffer overflow`_ in the context of a web application is to force +an application to handle more data than it can hold in a buffer. +In syntribos a buffer overflow test is attempted by injecting a large +string into the body of an HTTP request. + +Command Injection +----------------- + +`Command injection`_ attacks are done by injecting arbitrary commands in an +attempt to execute these commands on a remote system. In syntribos this is +achieved by injecting a set of strings that have been proven to be successful +in executing a command injection attacks. + +CORS Wildcard +------------- + +`CORS wildcard`_ test is used to verify if a web server allows cross-domain +resource sharing from any external URL ( wild carding of +`Access-Control-Allow-Origin` header) rather than a white list of URLs. + +Integer Overflow +---------------- + +`Integer overflow`_ test in syntribos attempts to inject numeric values that +the remote application may fail to represent within in its storage, for example +a 32 bit integer type trying to store a 64 bit number + +LDAP Injection +-------------- + +`LDAP injection`_ is attempted in syntribos by injection of LDAP statements +on to HTTP requests; if an application fails to properly sanitize the +request content, it may be possible to execute arbitrary commands. + +SQL Injection +------------- + +`SQL injection`_ attacks are one of the most common web application attacks. +If the user input is not properly sanitized, it is fairly easy to +execute SQL queries that may result in an attacker reading sensitive +information or gaining control of the SQL server. In syntribos +an application is tested for SQL injection vulnerabilities by injecting +SQL strings into the HTTP request. + +String Validation +----------------- + +String validation attacks in syntribos try to exploit the fact that +some string patterns are not sanitized effectively by the input +validator and may cause the application to crash. Examples of characters +that may cause string validation vulnerabilities are special unicode +characters, emojis etc. + +XML External Entity +------------------- + +An `XML external entity`_ attack is an attack that targets the web +application's XML parser. If an XML parser allows processing of +external entities referenced in an XML document then an attacker +might be able to cause denial of service, leakage of information etc. +Syntribos tries to inject a few malicious strings into an XML body +while sending requests to an application in an attempt to obtain an +appropriate response. + +Cross Site Scripting ( XSS ) +---------------------------- +An XSS_ attack is one where malicious JavaScript is injected into a web +application. Syntribos tries to find potential XSS issues by injecting +string containing "script" and other HTML tags into request fields. + +Other than these built-in tests, you can extend syntribos by writing +your own custom tests. To do this, download the source code and look at +the tests in ``syntribos/tests`` directory. The CORS test may be an easy +one to emulate. In the same way, users can add different extensions also +to the tests. To see how extensions can be written please see +``syntribos/extensions`` directory. + +.. _buffer overflow: https://en.wikipedia.org/wiki/Buffer_overflow +.. _Command injection: https://www.owasp.org/index.php/Command_Injection +.. _CORS wildcard: https://www.owasp.org/index.php/Test_Cross_Origin_Resource_Sharing_(OTG-CLIENT-007) +.. _Integer overflow: https://en.wikipedia.org/wiki/Integer_overflow +.. _LDAP injection: https://www.owasp.org/index.php/LDAP_injection +.. _SQL injection: https://www.owasp.org/index.php/SQL_Injection +.. _XML external entity: https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Processing +.. _XSS: https://www.owasp.org/index.php/Cross-site_Scripting_(XSS) + **Details** +* `Documentation`_ * Free software: `Apache license`_ * `Launchpad project`_ * `Blueprints`_ * `Bugs`_ +* `Source code`_ Supported Operating Systems ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Syntribos has been developed primarily in Linux and Mac environments, -however it supports installation and execution on Windows. But it has -not been tested yet. +Syntribos has been developed primarily in Linux and Mac environments and would +work on most Unix and Linux based Operating Systems. At this point, we are not +supporting Windows, but this may change in the future. +.. _Documentation: http://docs.openstack.org/developer/syntribos/ .. _Apache license: https://github.com/openstack/syntribos/blob/master/LICENSE .. _Launchpad project: https://launchpad.net/syntribos .. _Blueprints: https://blueprints.launchpad.net/syntribos .. _Bugs: https://bugs.launchpad.net/syntribos +.. _Source code: https://github.com/openstack/syntribos +============ Installation ============ @@ -79,12 +194,17 @@ pip `__ from the git repository. $ cd syntribos $ pip install . --upgrade +============= Configuration ============= -This is the basic structure of a Syntribos configuration file. -All config files should have the section ``[syntribos]`` and a -``[user]`` section, the ``[logging]`` section is optional. +This is the basic structure of a syntribos configuration file. +All configuration files should have at least the section +``[syntribos]``. Depending upon what extensions you are using +and what you are testing, you can add other sections as well, +for example, if you are using the built-in identity extension +you would also need the ``[user]`` section. The sections +``[logging]`` and ``[remote]`` are optional. :: @@ -100,6 +220,7 @@ All config files should have the section ``[syntribos]`` and a [user] # # User credentials and endpoint URI to get an AUTH_TOKEN + # This section is only needed if you are using the identity extension. # endpoint= username= @@ -112,16 +233,16 @@ All config files should have the section ``[syntribos]`` and a To test any project, just update the endpoint URI under ``[syntribos]`` to point to the API and also modify the user credentials if needed. The endpoint URI in the ``[syntribos]`` -section is the one being tested by Syntribos and the endpoint URI in +section is the one being tested by syntribos and the endpoint URI in ``[user]`` section is just used to get an AUTH_TOKEN. -Testing Keystone API --------------------- +Testing keystone API +~~~~~~~~~~~~~~~~~~~~ -A sample config file is given in ``examples/configs/keystone.conf``. +A sample config file is given in :file:`examples/configs/keystone.conf`. Copy this file to a location of your choice (default file path for -configuration file is: ``~/.syntribos/syntribos.conf``) and update the +configuration file is: :file:`~/.syntribos/syntribos.conf`) and update the necessary fields like user credentials, log, template directory etc. :: @@ -185,35 +306,38 @@ necessary fields like user credentials, log, template directory etc. # if you don't want this, set this option to False. http_request_compression=True +================== Syntribos Commands ================== Below are the set of commands that should be specified while -using Syntribos. +using syntribos. -- **run** +- :command:`syntribos run` - This command runs Syntribos with the given config options + This command runs syntribos with the given config options :: $ syntribos --config-file keystone.conf -t SQL run -- **dry_run** +- :command:`syntribos dry-run` - This command prepares all the test cases that would be executed by - the ```run``` command based on the configuration options passed to - Syntribos, but simply prints their details to the screen instead - of actually running them. + This command ensures that the template files given for this run parse + successfully without errors. It then runs a debug test which sends no + requests of its own. + + Note: if any external calls referenced inside the template file do make + requests, the parser will still make those requests even for a dry run. :: - $ syntribos --config-file keystone.conf -t SQL dry_run + $ syntribos --config-file keystone.conf dry_run -- **list_tests** +- :command:`syntribos list_tests` This command will list the names and description of all the tests @@ -227,11 +351,12 @@ using Syntribos. All these commands will only work if a configuration file is specified. -Running Syntribos +================= +Running syntribos ================= -To run Syntribos against all the available tests, just specify the -command ``syntribos`` with the configuration file without specifying +To run syntribos against all the available tests, just specify the +command :command:`syntribos run` with the configuration file without specifying any test type. :: @@ -239,9 +364,9 @@ any test type. $ syntribos --config-file keystone.conf run Fuzzy-matching test names -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ -It is possible to limit Syntribos to run a specific test type using +It is possible to limit syntribos to run a specific test type using the ``-t`` flag. :: @@ -346,93 +471,7 @@ above: 2016-05-19 16:11:52,083: INFO: root: Total Errored..: 0 2016-05-19 16:11:52,083: INFO: root: ======================================================== -Basic Syntribos Test Anatomy -============================ - -Test Types ----------- - -The tests included at release time include LDAP injection, SQL -injection, integer overflow, command injection, XML external entity, -reflected cross-site scripting, Cross Origin Resource Sharing (CORS) -wildcard and SSL. - -In order to run a specific test, simply use the ``-t, --test-types`` -option and provide `syntribos` with a keyword or keywords to match from -the test files located in ``syntribos/tests/``. - -For SQL injection tests, use: - -:: - - $ syntribos --config-file keystone.conf -t SQL - -Another example, to run SQL injection tests against the template body only, use: - -:: - - $ syntribos --config-file keystone.conf -t SQL_INJECTION_BODY - -For all tests against HTTP headers only, use: - -:: - - $ syntribos --config-file keystone.conf -t HEADERS - - -Call External -------------- - -Syntribos template files can be supplemented with variable data, or data -retrieved from external sources. This is handled using 'extensions.' - -Extensions are found in ``syntribos/extensions/`` . - -Calls to extensions are made in this form: - -:: - - CALL_EXTERNAL|{extension dot path}:{function}:{arguments} - -One example packaged with Syntribos enables the tester to obtain an auth -token from keystone/identity. The code is located in -``identity/client.py`` - -To use this extension, you can add the following to your template file: - -:: - - X-Auth-Token: CALL_EXTERNAL|syntribos.extensions.identity.client:get_token_v3:["user"]| - -The "user" string indicates the data from the configuration file we -added in ``examples/configs/keystone.conf`` - -Another example is found in ``random_data/client.py`` . This returns a -UUID when random but unique data is needed. This can be used in place of -usernames when fuzzing a create user call. - -:: - - "username": "CALL_EXTERNAL|syntribos.extensions.random_data.client:get_uuid:[]|" - -The extension function can return one value or be used as a generator if -you want it to change for each test. - - -Action Field ------------- - -While Syntribos is designed to test all fields in a request, it can also -ignore specific fields through the use of Action Fields. If you want to -fuzz against a static object ID, use the Action Field indicator as -follows: - -:: - - "ACTION_FIELD:id": "1a16f348-c8d5-42ec-a474-b1cdf78cf40f" - -The ID provided will remain static for every test. - +=================== Executing unittests =================== @@ -449,15 +488,17 @@ Now, run $ python -m unittest discover tests/unit -p "test_*.py" -Also, if you have configured tox you could also do +If you have configured tox you could also do :: $ tox -e py27 + $ tox -e py35 This will run all the unittests and give you a result output containing the status and coverage details of each test. +======================= Contributing Guidelines ======================= @@ -466,7 +507,7 @@ Contributing Guidelines 2. All new classes/functions should have appropriate docstrings in `RST format `__ 3. All new code should have appropriate unittests (place them in the - ``tests/unit`` folder) + :file:`tests/unit` folder) Anyone wanting to contribute to OpenStack must follow `the OpenStack development workflow `__ @@ -474,15 +515,15 @@ Anyone wanting to contribute to OpenStack must follow All changes should be submitted through the code review process in Gerrit described above. All pull requests on Github will be closed/ignored. -Bugs should be filed on the `Syntribos launchpad site `__, +Bugs should be filed on the `syntribos launchpad site `__, and not on Github. All Github issues will be closed/ignored. Breaking changes, feature requests, and other non prioritized work should first be submitted as a blueprint `here `__ for review. -Readme.rst is auto generated from docs by running ``python readme.py`` in the -``syntribos/scripts`` directory. So when the README.rst needs to be updated; -modify the corresponding rst file in ``syntribos/doc/source`` and auto generate +README.rst is auto generated from docs by running :command:`python readme.py` in the +:file:`syntribos/scripts` directory. So when the README.rst needs to be updated; +modify the corresponding rst file in :file:`syntribos/doc/source` and auto generate the README. diff --git a/doc/source/about.rst b/doc/source/about.rst index 6fcbe4f9..78a0bf97 100644 --- a/doc/source/about.rst +++ b/doc/source/about.rst @@ -1,9 +1,10 @@ +================================================= Syntribos, An Automated API Security Testing Tool ================================================= :: - Syntribos + syntribos xxxxxxx x xxxxxxxxxxxxx x x xxxxxxxxxxx x @@ -34,33 +35,146 @@ Syntribos, An Automated API Security Testing Tool Syntribos is an automated API security testing tool that is maintained by members of the `OpenStack Security Project `__. -Given a simple configuration file and an example HTTP request, Syntribos +Given a simple configuration file and an example HTTP request, syntribos can replace any API URL, URL parameter, HTTP header and request body -field with a given set of strings. This is similar to Burp Proxy's -Intruder sniper attack, but Syntribos iterates through each position -automatically. Syntribos aims to automatically detect common security -defects such as SQL injection, LDAP injection, buffer overflow, etc. In -addition, Syntribos can be used to help identifying new security defects -by fuzzing. +field with a given set of strings. Syntribos iterates through each position +in the request automatically. Syntribos aims to automatically detect common +security defects such as SQL injection, LDAP injection, buffer overflow, etc. In +addition, syntribos can be used to help identify new security defects +by automated fuzzing. Syntribos has the capability to test any API, but is designed with `OpenStack `__ applications in mind. +List of Tests +~~~~~~~~~~~~~ + +Syntribos is shipped with batteries included, which means, with minimal +configuration effort you can initiate automated testing of any API of +your choice. If testing OpenStack API is in your mind, then syntribos +by default will help you in automatically downloading a set of templates +of some of the bigger OpenStack projects like nova, neutron, keystone etc. + +A short list of tests that can be run using syntribos is given below: + +* Buffer Overflow +* Command Injection +* CORS Wildcard +* Integer Overflow +* LDAP Injection +* SQL Injection +* String Validation +* XML External Entity +* Cross Site Scripting ( XSS ) + +Buffer Overflow +--------------- + +The idea of `buffer overflow`_ in the context of a web application is to force +an application to handle more data than it can hold in a buffer. +In syntribos a buffer overflow test is attempted by injecting a large +string into the body of an HTTP request. + +Command Injection +----------------- + +`Command injection`_ attacks are done by injecting arbitrary commands in an +attempt to execute these commands on a remote system. In syntribos this is +achieved by injecting a set of strings that have been proven to be successful +in executing a command injection attacks. + +CORS Wildcard +------------- + +`CORS wildcard`_ test is used to verify if a web server allows cross-domain +resource sharing from any external URL ( wild carding of +`Access-Control-Allow-Origin` header) rather than a white list of URLs. + +Integer Overflow +---------------- + +`Integer overflow`_ test in syntribos attempts to inject numeric values that +the remote application may fail to represent within in its storage, for example +a 32 bit integer type trying to store a 64 bit number + +LDAP Injection +-------------- + +`LDAP injection`_ is attempted in syntribos by injection of LDAP statements +on to HTTP requests; if an application fails to properly sanitize the +request content, it may be possible to execute arbitrary commands. + +SQL Injection +------------- + +`SQL injection`_ attacks are one of the most common web application attacks. +If the user input is not properly sanitized, it is fairly easy to +execute SQL queries that may result in an attacker reading sensitive +information or gaining control of the SQL server. In syntribos +an application is tested for SQL injection vulnerabilities by injecting +SQL strings into the HTTP request. + +String Validation +----------------- + +String validation attacks in syntribos try to exploit the fact that +some string patterns are not sanitized effectively by the input +validator and may cause the application to crash. Examples of characters +that may cause string validation vulnerabilities are special unicode +characters, emojis etc. + +XML External Entity +------------------- + +An `XML external entity`_ attack is an attack that targets the web +application's XML parser. If an XML parser allows processing of +external entities referenced in an XML document then an attacker +might be able to cause denial of service, leakage of information etc. +Syntribos tries to inject a few malicious strings into an XML body +while sending requests to an application in an attempt to obtain an +appropriate response. + +Cross Site Scripting ( XSS ) +---------------------------- +An XSS_ attack is one where malicious JavaScript is injected into a web +application. Syntribos tries to find potential XSS issues by injecting +string containing "script" and other HTML tags into request fields. + +Other than these built-in tests, you can extend syntribos by writing +your own custom tests. To do this, download the source code and look at +the tests in ``syntribos/tests`` directory. The CORS test may be an easy +one to emulate. In the same way, users can add different extensions also +to the tests. To see how extensions can be written please see +``syntribos/extensions`` directory. + +.. _buffer overflow: https://en.wikipedia.org/wiki/Buffer_overflow +.. _Command injection: https://www.owasp.org/index.php/Command_Injection +.. _CORS wildcard: https://www.owasp.org/index.php/Test_Cross_Origin_Resource_Sharing_(OTG-CLIENT-007) +.. _Integer overflow: https://en.wikipedia.org/wiki/Integer_overflow +.. _LDAP injection: https://www.owasp.org/index.php/LDAP_injection +.. _SQL injection: https://www.owasp.org/index.php/SQL_Injection +.. _XML external entity: https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Processing +.. _XSS: https://www.owasp.org/index.php/Cross-site_Scripting_(XSS) + **Details** +* `Documentation`_ * Free software: `Apache license`_ * `Launchpad project`_ * `Blueprints`_ * `Bugs`_ +* `Source code`_ Supported Operating Systems ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Syntribos has been developed primarily in Linux and Mac environments, -however it supports installation and execution on Windows. But it has -not been tested yet. +Syntribos has been developed primarily in Linux and Mac environments and would +work on most Unix and Linux based Operating Systems. At this point, we are not +supporting Windows, but this may change in the future. +.. _Documentation: http://docs.openstack.org/developer/syntribos/ .. _Apache license: https://github.com/openstack/syntribos/blob/master/LICENSE .. _Launchpad project: https://launchpad.net/syntribos .. _Blueprints: https://blueprints.launchpad.net/syntribos .. _Bugs: https://bugs.launchpad.net/syntribos +.. _Source code: https://github.com/openstack/syntribos diff --git a/doc/source/code-docs.rst b/doc/source/code-docs.rst index 7fa02259..bb55d8ec 100644 --- a/doc/source/code-docs.rst +++ b/doc/source/code-docs.rst @@ -1,8 +1,9 @@ +============================ Syntribos Code Documentation ============================ Configuration -------------- +~~~~~~~~~~~~~ This section describes the configuration specified in your configuration file (second argument to the runner). @@ -23,7 +24,7 @@ This section describes the configuration specified in your configuration file :show-inheritance: Signals -------- +~~~~~~~ This section describes Signals (:class:`syntribos.signal.SynSignal`) and SignalHolders (:class:`syntribos.signal.SignalHolder`) @@ -36,19 +37,19 @@ SignalHolders (:class:`syntribos.signal.SignalHolder`) :special-members: __init__, __contains__ Checks ------- +~~~~~~ .. autofunction:: syntribos.checks.http.check_http_fail .. autofunction:: syntribos.checks.http.check_http_status_code Tests ------ +~~~~~ This section describes the components involved with writing your own tests with -Syntribos. +syntribos. -All Syntribos tests inherit from :class:`syntribos.tests.base.BaseTestCase`, +All syntribos tests inherit from :class:`syntribos.tests.base.BaseTestCase`, either directly, or through a subclass like :class:`syntribos.tests.fuzz.base_fuzz.BaseFuzzTestCase`. @@ -76,10 +77,10 @@ All tests are aggregated in the `syntribos.tests.base.test_table` variable :show-inheritance: Issues ------- +~~~~~~ This section describes the representation of issues that are uncovered by -Syntribos. +syntribos. .. automodule:: syntribos.issue :members: @@ -87,10 +88,10 @@ Syntribos. :show-inheritance: Results -------- +~~~~~~~ This section describes the representation of results (collections of issues) -from a given Syntribos run. +from a given syntribos run. .. automodule:: syntribos.result :members: @@ -98,7 +99,7 @@ from a given Syntribos run. :show-inheritance: HTTP Requests -------------- +~~~~~~~~~~~~~ This section describes the components related to generating, fuzzing, and making HTTP requests. @@ -119,9 +120,9 @@ HTTP requests. :show-inheritance: Extension ----------- +~~~~~~~~~ -This section describes Syntribos' extensions, which are called by the +This section describes syntribos' extensions, which are called by the CALL_EXTERNAL field in the request template. .. automodule:: syntribos.extensions.identity.models.base diff --git a/doc/source/commands.rst b/doc/source/commands.rst index 70a34c26..437d118f 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -1,19 +1,20 @@ +================== Syntribos Commands ================== Below are the set of commands that should be specified while -using Syntribos. +using syntribos. -- **run** +- :command:`syntribos run` - This command runs Syntribos with the given config options + This command runs syntribos with the given config options :: $ syntribos --config-file keystone.conf -t SQL run -- **dry_run** +- :command:`syntribos dry-run` This command ensures that the template files given for this run parse @@ -22,12 +23,13 @@ using Syntribos. Note: if any external calls referenced inside the template file do make requests, the parser will still make those requests even for a dry run. + :: $ syntribos --config-file keystone.conf dry_run -- **list_tests** +- :command:`syntribos list_tests` This command will list the names and description of all the tests diff --git a/doc/source/conf.py b/doc/source/conf.py index 9bc30ec8..4db92f79 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -15,33 +15,29 @@ import os import sys -sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath("../../")) # -- General configuration ---------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'oslosphinx' -] +# extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones. +extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "oslosphinx"] # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. # execute "export SPHINX_DEBUG=1" in your terminal to disable # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ".rst" # The master toctree document. -master_doc = 'index' +master_doc = "index" # General information about the project. -project = u'Syntribos' -copyright = u'2015, OpenStack Foundation' +project = u"syntribos" +copyright = u"2015-present, OpenStack Foundation" -# If true, '()' will be appended to :func: etc. cross-reference text. +# If true, "()" will be appended to :func: etc. cross-reference text. add_function_parentheses = True # If true, the current module name will be prepended to all description @@ -49,40 +45,37 @@ add_function_parentheses = True add_module_names = True # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" -#-- Options for man page output -------------------------------------------- +# -- Options for man page output -------------------------------------------- # Grouping the document tree for man pages. -# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' +# List of tuples "sourcefile", "target", u"title", u"Authors name", "manual" -man_pages = [ - ('man/syntribos', 'syntribos', u'Automated API security testing tool', - [u'OpenStack Security Group'], 1) -] +man_pages = [("man/syntribos", "syntribos", + u"Automated API security testing tool", + [u"OpenStack Security Group"], 1)] # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. +# Sphinx are currently "default" and "sphinxdoc". # html_theme_path = ["."] -# html_theme = '_theme' -# html_static_path = ['static'] +# html_theme = "_theme" +# html_static_path = ["static"] html_theme_options = {} # Output file base name for HTML help builder. -htmlhelp_basename = '%sdoc' % project +htmlhelp_basename = "%sdoc" % project # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass # [howto/manual]). -latex_documents = [ - ('index', - '%s.tex' % project, - u'%s Documentation' % project, - u'OpenStack Foundation', 'manual'), -] +latex_documents = [("index", "%s.tex" % project, u"%s Documentation" % project, + u"OpenStack Foundation", "manual"), ] # Example configuration for intersphinx: refer to the Python standard library. -# intersphinx_mapping = {'http://docs.python.org/': None} -intersphinx_mapping = {'requests': ('http://docs.python-requests.org/en/master', None)} +# intersphinx_mapping = {"http://docs.python.org/": None} +intersphinx_mapping = { + "requests": ("http://docs.python-requests.org/en/master", None) +} diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index f1d8e5fc..12f5f581 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -1,9 +1,14 @@ +============= Configuration ============= -This is the basic structure of a Syntribos configuration file. -All config files should have the section ``[syntribos]`` and a -``[user]`` section, the ``[logging]`` section is optional. +This is the basic structure of a syntribos configuration file. +All configuration files should have at least the section +``[syntribos]``. Depending upon what extensions you are using +and what you are testing, you can add other sections as well, +for example, if you are using the built-in identity extension +you would also need the ``[user]`` section. The sections +``[logging]`` and ``[remote]`` are optional. :: @@ -19,6 +24,7 @@ All config files should have the section ``[syntribos]`` and a [user] # # User credentials and endpoint URI to get an AUTH_TOKEN + # This section is only needed if you are using the identity extension. # endpoint= username= @@ -31,16 +37,16 @@ All config files should have the section ``[syntribos]`` and a To test any project, just update the endpoint URI under ``[syntribos]`` to point to the API and also modify the user credentials if needed. The endpoint URI in the ``[syntribos]`` -section is the one being tested by Syntribos and the endpoint URI in +section is the one being tested by syntribos and the endpoint URI in ``[user]`` section is just used to get an AUTH_TOKEN. -Testing Keystone API --------------------- +Testing keystone API +~~~~~~~~~~~~~~~~~~~~ -A sample config file is given in ``examples/configs/keystone.conf``. +A sample config file is given in :file:`examples/configs/keystone.conf`. Copy this file to a location of your choice (default file path for -configuration file is: ``~/.syntribos/syntribos.conf``) and update the +configuration file is: :file:`~/.syntribos/syntribos.conf`) and update the necessary fields like user credentials, log, template directory etc. :: diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 94f988da..1aef2a8e 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,3 +1,4 @@ +======================= Contributing Guidelines ======================= @@ -6,7 +7,7 @@ Contributing Guidelines 2. All new classes/functions should have appropriate docstrings in `RST format `__ 3. All new code should have appropriate unittests (place them in the - ``tests/unit`` folder) + :file:`tests/unit` folder) Anyone wanting to contribute to OpenStack must follow `the OpenStack development workflow `__ @@ -14,14 +15,14 @@ Anyone wanting to contribute to OpenStack must follow All changes should be submitted through the code review process in Gerrit described above. All pull requests on Github will be closed/ignored. -Bugs should be filed on the `Syntribos launchpad site `__, +Bugs should be filed on the `syntribos launchpad site `__, and not on Github. All Github issues will be closed/ignored. Breaking changes, feature requests, and other non prioritized work should first be submitted as a blueprint `here `__ for review. -Readme.rst is auto generated from docs by running ``python readme.py`` in the -``syntribos/scripts`` directory. So when the README.rst needs to be updated; -modify the corresponding rst file in ``syntribos/doc/source`` and auto generate +README.rst is auto generated from docs by running :command:`python readme.py` in the +:file:`syntribos/scripts` directory. So when the README.rst needs to be updated; +modify the corresponding rst file in :file:`syntribos/doc/source` and auto generate the README. diff --git a/doc/source/index.rst b/doc/source/index.rst index 6d24d888..243002ec 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,22 +1,22 @@ +========= Syntribos ========= -Syntribos is an automated API security testing tool +Syntribos is an automated API security testing tool. -Given a simple configuration file and an example HTTP request, Syntribos +Given a simple configuration file and an example HTTP request, syntribos can replace any API URL, URL parameter, HTTP header and request body -field with a given set of strings. This is similar to Burp Proxy's -Intruder sniper attack, but Syntribos iterates through each position -automatically. Syntribos aims to automatically detect common security -defects such as SQL injection, LDAP injection, buffer overflow, etc. In -addition, Syntribos can be used to help identifying new security defects -by fuzzing. +field with a given set of strings. Syntribos iterates through each position +in the request automatically. Syntribos aims to automatically detect common +security defects such as SQL injection, LDAP injection, buffer overflow, etc. In +addition, syntribos can be used to help identify new security defects +by automated fuzzing. Syntribos has the capability to test any API, but is designed with `OpenStack `__ applications in mind. Index ------ +~~~~~ .. toctree:: :maxdepth: 1 @@ -27,10 +27,10 @@ Index commands running logging - test.anatomy + test-anatomy For Developers --------------- +~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -41,14 +41,18 @@ For Developers unittests Project information -------------------- +~~~~~~~~~~~~~~~~~~~ +* `Documentation`_ * Free software: `Apache license`_ * `Launchpad project`_ * `Blueprints`_ * `Bugs`_ +* `Source code`_ +.. _Documentation: http://docs.openstack.org/developer/syntribos/ .. _Apache license: https://github.com/openstack/syntribos/blob/master/LICENSE .. _Launchpad project: https://launchpad.net/syntribos .. _Blueprints: https://blueprints.launchpad.net/syntribos .. _Bugs: https://bugs.launchpad.net/syntribos +.. _Source code: https://github.com/openstack/syntribos diff --git a/doc/source/installation.rst b/doc/source/installation.rst index fd6f8fef..b92407be 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,3 +1,4 @@ +============ Installation ============ diff --git a/doc/source/man/syntribos.rst b/doc/source/man/syntribos.rst index d9372c0a..278e4401 100644 --- a/doc/source/man/syntribos.rst +++ b/doc/source/man/syntribos.rst @@ -3,7 +3,7 @@ syntribos ========= SYNOPSIS -======== +~~~~~~~~ syntribos [-h] [--colorize] [--config-dir DIR] [--config-file PATH] [--excluded-types EXCLUDED_TYPES] [--format OUTPUT_FORMAT] @@ -17,29 +17,27 @@ syntribos [-h] [--colorize] [--config-dir DIR] [--config-file PATH] {list_tests,run,dry_run} ... DESCRIPTION -=========== +~~~~~~~~~~~ Syntribos is an automated API security testing tool. -Given a simple configuration file and an example HTTP request, Syntribos +Given a simple configuration file and an example HTTP request, syntribos can replace any API URL, URL parameter, HTTP header and request body -field with a given set of strings. This is similar to Burp Proxy's -Intruder sniper attack, but Syntribos iterates through each position -automatically. Syntribos aims to automatically detect common security -defects such as SQL injection, LDAP injection, buffer overflow, etc. In -addition, Syntribos can be used to help identifying new security defects -by fuzzing. +field with a given set of strings. Syntribos aims to automatically detect +common security defects such as SQL injection, LDAP injection, buffer +overflow, etc. In addition, syntribos can be used to help identifying new +security defects by fuzzing. Syntribos has the capability to test any API, but is designed with OpenStack applications in mind. OPTIONS -======= +~~~~~~~ -h, --help show this help message and exit - --colorize, -cl Enable color in Syntribos terminal output - --config-dir DIR Path to a config directory to pull *.conf files from. - This file set is sorted, so as to provide a + --colorize, -cl Enable color in syntribos terminal output + --config-dir DIR Path to a config directory to pull :file:`*.conf` files + from. This file set is sorted, so as to provide a predictable parse order if individual options are over-ridden. The set is parsed after the file(s) specified via previous --config-file, arguments hence @@ -48,7 +46,7 @@ OPTIONS can be specified, with values in later files taking precedence. Defaults to None. --excluded-types EXCLUDED_TYPES, -e EXCLUDED_TYPES - Test types to be excluded from current runagainst the + Test types to be excluded from current run against the target API --format OUTPUT_FORMAT, -f OUTPUT_FORMAT The format for outputting results @@ -68,7 +66,7 @@ Main Syntribos Config: --syntribos-exclude_results SYNTRIBOS_EXCLUDE_RESULTS Defect types to exclude from the results output --syntribos-payload_dir SYNTRIBOS_PAYLOAD_DIR - The location where we can find Syntribos' payloads + The location where we can find syntribos' payloads --syntribos-templates SYNTRIBOS_TEMPLATES A directory of template files, or a single template file, to test on the target API @@ -77,27 +75,27 @@ Syntribos Commands: {list_tests,run,dry_run} Available commands list_tests List all available tests - run Run Syntribos with given config options + run Run syntribos with given config options dry_run Dry run Syntribos with given config options FILES -===== +~~~~~ ~/.syntribos/syntribos.conf syntribos configuration file EXAMPLES -======== +~~~~~~~~ -To run Syntribos against all the available tests, just specify the -command ``syntribos`` with the configuration file without specifying -any test type. +To run syntribos against all the available tests, just specify the +command :command:`syntribos run` with the configuration file without +specifying any test type. :: $ syntribos --config-file keystone.conf run SEE ALSO -======== +~~~~~~~~ bandit(1) diff --git a/doc/source/running.rst b/doc/source/running.rst index 33826ec3..9a9070ec 100644 --- a/doc/source/running.rst +++ b/doc/source/running.rst @@ -1,8 +1,9 @@ -Running Syntribos +================= +Running syntribos ================= -To run Syntribos against all the available tests, just specify the -command ``syntribos`` with the configuration file without specifying +To run syntribos against all the available tests, just specify the +command :command:`syntribos run` with the configuration file without specifying any test type. :: @@ -10,9 +11,9 @@ any test type. $ syntribos --config-file keystone.conf run Fuzzy-matching test names -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ -It is possible to limit Syntribos to run a specific test type using +It is possible to limit syntribos to run a specific test type using the ``-t`` flag. :: diff --git a/doc/source/structure.rst b/doc/source/structure.rst index 97a10fc4..c9b9c61f 100644 --- a/doc/source/structure.rst +++ b/doc/source/structure.rst @@ -1,21 +1,22 @@ +================= Project Structure ================= -- ``data/`` (textfiles containing data for use by Syntribos tests) +- ``data/`` (textfiles containing data for use by syntribos tests) - ``doc/source/`` (Sphinx documentation files) -- ``examples/`` (example Syntribos request templates, config files) - - ``configs/`` (examples of Syntribos configs; currently only Keystone) +- ``examples/`` (example syntribos request templates, config files) + - ``configs/`` (examples of syntribos configs; currently only Keystone) - ``templates/`` (examples of request templates; currently only Keystone/Solum) - ``scripts/`` (?) -- ``syntribos/`` (core Syntribos code) +- ``syntribos/`` (core syntribos code) - ``clients/`` (clients for making calls, e.g. HTTP) - ``http/`` (clients for making HTTP requests) - ``extensions/`` (extensions that can be called in request templates) - ``identity/`` (extension for interacting with Keystone/identity) - ``random_data/`` (extension for generating random test data) - ``formatters/`` (output formatters, e.g. JSON, XML/XUnit) - - ``tests/`` (location of tests that Syntribos can run against a target) + - ``tests/`` (location of tests that syntribos can run against a target) - ``auth/`` (tests related to authentication/authorization) - ``fuzz/`` (tests that "fuzz" API requests) - ``utils/`` (utility methods) -- ``tests/unit/`` (unittests for testing Syntribos itself) +- ``tests/unit/`` (unittests for testing syntribos itself) diff --git a/doc/source/test.anatomy.rst b/doc/source/test-anatomy.rst similarity index 90% rename from doc/source/test.anatomy.rst rename to doc/source/test-anatomy.rst index 8d0e061a..96986f09 100644 --- a/doc/source/test.anatomy.rst +++ b/doc/source/test-anatomy.rst @@ -1,8 +1,9 @@ -Basic Syntribos Test Anatomy +============================ +Basic syntribos Test Anatomy ============================ Test Types ----------- +~~~~~~~~~~ The tests included at release time include LDAP injection, SQL injection, integer overflow, command injection, XML external entity, @@ -33,7 +34,7 @@ For all tests against HTTP headers only, use: Call External -------------- +~~~~~~~~~~~~~ Syntribos template files can be supplemented with variable data, or data retrieved from external sources. This is handled using 'extensions.' @@ -46,7 +47,7 @@ Calls to extensions are made in this form: CALL_EXTERNAL|{extension dot path}:{function}:{arguments} -One example packaged with Syntribos enables the tester to obtain an auth +One example packaged with syntribos enables the tester to obtain an auth token from keystone/identity. The code is located in ``identity/client.py`` @@ -72,9 +73,9 @@ you want it to change for each test. Action Field ------------- +~~~~~~~~~~~~ -While Syntribos is designed to test all fields in a request, it can also +While syntribos is designed to test all fields in a request, it can also ignore specific fields through the use of Action Fields. If you want to fuzz against a static object ID, use the Action Field indicator as follows: diff --git a/doc/source/unittests.rst b/doc/source/unittests.rst index 016029f5..b6e20499 100644 --- a/doc/source/unittests.rst +++ b/doc/source/unittests.rst @@ -1,3 +1,4 @@ +=================== Executing unittests =================== @@ -14,11 +15,12 @@ Now, run $ python -m unittest discover tests/unit -p "test_*.py" -Also, if you have configured tox you could also do +If you have configured tox you could also do :: $ tox -e py27 + $ tox -e py35 This will run all the unittests and give you a result output containing the status and coverage details of each test. diff --git a/syntribos/config.py b/syntribos/config.py index f2c0a22b..44158c92 100644 --- a/syntribos/config.py +++ b/syntribos/config.py @@ -127,7 +127,7 @@ class TemplateType(ExistingPathType): return [self._fetch_from_file(string)] -syntribos_group = cfg.OptGroup(name="syntribos", title="Main Syntribos Config") +syntribos_group = cfg.OptGroup(name="syntribos", title="Main syntribos Config") user_group = cfg.OptGroup(name="user", title="Identity Config") test_group = cfg.OptGroup(name="test", title="Test Config") logger_group = cfg.OptGroup(name="logging", title="Logger config") @@ -137,9 +137,9 @@ def sub_commands(sub_parser): sub_parser.add_parser('list_tests', help="List all available tests") sub_parser.add_parser('run', - help="Run Syntribos with given config options") + help="Run syntribos with given config options") sub_parser.add_parser('dry_run', - help="Dry run Syntribos with given config options") + help="Dry run syntribos with given config options") def list_opts(): @@ -174,7 +174,7 @@ def list_cli_opts(): cfg.SubCommandOpt(name="sub_command", handler=sub_commands, help="Available commands", - title="Syntribos Commands"), + title="syntribos Commands"), cfg.MultiStrOpt("test-types", dest="test_types", short="t", default=[""], sample_default=["SQL", "XSS"], help="Test types to run against the target API"), @@ -183,7 +183,7 @@ def list_cli_opts(): help="Test types to be excluded from current run" "against the target API"), cfg.BoolOpt("colorize", dest="colorize", short="cl", default=False, - help="Enable color in Syntribos terminal output"), + help="Enable color in syntribos terminal output"), cfg.StrOpt("outfile", short="o", sample_default="out.json", help="File to print output to"), cfg.StrOpt("format", dest="output_format", short="f", default="json", @@ -209,7 +209,7 @@ def list_syntribos_opts(): "file, to test on the target API"), cfg.StrOpt("payload_dir", default="", required=True, sample_default="~/.syntribos/data", - help="The location where we can find Syntribos' payloads"), + help="The location where we can find syntribos' payloads"), cfg.MultiStrOpt("exclude_results", default=[""], sample_default=["500_errors", "length_diff"], @@ -221,21 +221,21 @@ def list_syntribos_opts(): def list_user_opts(): return [ cfg.StrOpt("version", default="v2.0", - help="Keystone version", choices=["v2.0", "v3"]), - cfg.StrOpt("username", default="", help="Keystone username"), - cfg.StrOpt("password", default="", help="Keystone user password", + help="keystone version", choices=["v2.0", "v3"]), + cfg.StrOpt("username", default="", help="keystone username"), + cfg.StrOpt("password", default="", help="keystone user password", secret=True), cfg.StrOpt("user_id", default="", help="Keystone user ID", secret=True), - cfg.StrOpt("token", default="", help="Keystone auth token", + cfg.StrOpt("token", default="", help="keystone auth token", secret=True), - cfg.StrOpt("endpoint", default="", help="Keystone endpoint URI"), - cfg.StrOpt("domain_name", default="", help="Keystone domain name"), - cfg.StrOpt("project_id", default="", help="Keystone project id"), - cfg.StrOpt("project_name", default="", help="Keystone project name"), - cfg.StrOpt("domain_id", default="", help="Keystone domain id"), - cfg.StrOpt("tenant_name", default="", help="Keystone tenant name"), - cfg.StrOpt("tenant_id", default="", help="Keystone tenant id"), + cfg.StrOpt("endpoint", default="", help="keystone endpoint URI"), + cfg.StrOpt("domain_name", default="", help="keystone domain name"), + cfg.StrOpt("project_id", default="", help="keystone project id"), + cfg.StrOpt("project_name", default="", help="keystone project name"), + cfg.StrOpt("domain_id", default="", help="keystone domain id"), + cfg.StrOpt("tenant_name", default="", help="keystone tenant name"), + cfg.StrOpt("tenant_id", default="", help="keystone tenant id"), cfg.StrOpt("serialize_format", default="json", help="Type of request body"), cfg.StrOpt("deserialize_format", default="json",