syntribos 0.5.0

Description:

syntribos 0.5.0

========================Team and repository tags========================.. image:: http://governance.openstack.org/badges/syntribos.svg :target: http://governance.openstack.org/reference/tags/index.html.. image:: http://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat :target: http://docs.openstack.org/developer/syntribos/.. image:: http://img.shields.io/pypi/v/syntribos.svg :target: http://pypi.python.org/pypi/syntribos/.. image:: http://img.shields.io/pypi/pyversions/syntribos.svg :target: http://pypi.python.org/pypi/syntribos/.. image:: http://img.shields.io/pypi/wheel/syntribos.svg :target: http://pypi.python.org/pypi/syntribos/.. image:: http://img.shields.io/irc/%23openstack-security.png :target: http://webchat.freenode.net/?channels=openstack-security=================================================Syntribos, An Automated API Security Testing Tool=================================================:: syntribos xxxxxxx x xxxxxxxxxxxxx x x xxxxxxxxxxx x xxxxxxxxx x xxxxxxx x xxxxx x xxx x x xxxxxxxxxxxxxxx xxxxxxxxxxxxxxx xxxxxxxxxxxxx xxxxxxxxxxxxx xxxxxxxxxxx xxxxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxx xxxxxx xxx xxx x x x === Automated API Scanning ===Syntribos is an open source automated API security testing tool that ismaintained by members of the `OpenStack Security Project <https://wiki.openstack.org/wiki/Security>`_.Given a simple configuration file and an example HTTP request, syntriboscan replace any API URL, URL parameter, HTTP header and request bodyfield with a given set of strings. Syntribos iterates through each positionin the request automatically. Syntribos aims to automatically detect commonsecurity defects such as SQL injection, LDAP injection, buffer overflow, etc.In addition, syntribos can be used to help identify new security defectsby automated fuzzing.Syntribos has the capability to test any API, but is designed with`OpenStack <https://www.openstack.org/>`__ applications in mind.List of Tests~~~~~~~~~~~~~With syntribos, you can initiate automated testing of any API with minimalconfiguration effort. Syntribos is ideal for testing the OpenStack API as itwill help you in automatically downloading a set of templates of some of thebigger 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)* Regex Denial of Service (ReDoS)* JSON Parser Depth Limit* User DefinedBuffer Overflow---------------`Buffer overflow`_ attacks, in the context of a web application,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 largestring into the body of an HTTP request.Command Injection-----------------`Command injection`_ attacks are done by injecting arbitrary commands in anattempt to execute these commands on a remote system. In syntribos, this isachieved by injecting a set of strings that have been proven as successfulexecutors of injection attacks.CORS Wildcard-------------`CORS wildcard`_ tests are used to verify if a web server allows cross-domainresource sharing from any external URL (wild carding of`Access-Control-Allow-Origin` header), rather than a white list of URLs.Integer Overflow----------------`Integer overflow`_ tests in syntribos attempt to inject numeric values thatthe remote application may fail to represent within its storage. For example,injecting a 64 bit number into a 32 bit integer type.LDAP Injection--------------Syntribos attempts `LDAP injection`_ attacks by injecting LDAP statementsinto HTTP requests; if an application fails to properly sanitize therequest 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 toexecute SQL queries that may result in an attacker reading sensitiveinformation or gaining control of the SQL server. In syntribos,an application is tested for SQL injection vulnerabilities by injectingSQL strings into the HTTP request.String Validation-----------------Some string patterns are not sanitized effectively by the input validator andmay cause the application to crash. String validation attacks in syntribostry to exploit this by inputting characters that may cause string validationvulnerabilities. For example, special unicode characters, emojis, etc.XML External Entity-------------------`XML external entity`_ attacks target the web application's XML parser.If an XML parser allows processing of external entities referenced in anXML document then an attacker might be able to cause a denial of service,or leakage of information, etc. Syntribos tries to inject a few maliciousstrings into an XML body while sending requests to an application in anattempt to obtain an appropriate response.Cross Site Scripting (XSS)----------------------------`XSS`_ attacks inject malicious JavaScript into a webapplication. Syntribos tries to find potential XSS issues by injectingstring containing "script" and other HTML tags into request fields.Regex Denial of Service (ReDoS)-------------------------------`ReDoS`_ attacks attempt to produce a denial of service byproviding a regular expression that takes a very long time to evaluate.This can cause the regex engine to backtrack indefinitely, which canslow down some parsers or even cause a processing halt. The attackexploits the fact that most regular expression implementations havean exponential time worst case complexity.JSON Parser Depth Limit-----------------------There is a possibility that the JSON parser will reach depth limit and crash,resulting in a successful overflow of the JSON parsers depth limit, leadingto a DoS vulnerability. Syntribos tries to check for this, and raises an issueif the parser crashes.User defined Test-----------------This test gives users the ability to fuzz using user defined fuzz data andprovides an option to look for failure strings provided by the user. The fuzzdata needs to be provided using the config option :option:`[user_defined]`.Example:: [user_defined] payload=<payload_file> failure_strings=<[list_of_failure_strings] # optionalOther than these built-in tests, you can extend syntribos by writingyour own custom tests. To do this, download the source code and look atthe tests in the ``syntribos/tests`` directory. The CORS test may be an easyone to emulate. In the same way, you can also add different extensionsto the tests. To see how extensions can be written please see the``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).. _ReDoS: https://en.wikipedia.org/wiki/ReDoS**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 and wouldwork on most Unix and Linux based Operating Systems. At this point, we are notsupporting Windows, but this may change in the future... _Documentation: https://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============Syntribos can be installed directly from `pypi with pip <https://pypi.python.org/pypi/pip>`__.:: pip install syntribosFor the latest changes, install syntribos from `source <https://www.github.com/openstack/syntribos.git>`__with `pip <https://pypi.python.org/pypi/pip>`__.Clone the repository:: gitclonehttps://github.com/openstack/syntribos.gitChangedirectoryintotherepositorycloneandinstallwithpip:: cd syntribos pipinstall.======================================InitializingthesyntribosEnvironment======================================Oncesyntribosisinstalled,youmustinitializethesyntribosenvironment.Thiscanbedonemanually,orwiththe‘‘init‘‘command.:: syntribos init.. Note:: By default, ``syntribos init`` fetches a set of default payload files from a `remote repository <https://github.com/openstack/syntribos-payloads>`_ maintained by our development team. These payload files are necessary for our fuzz tests to run. To disable this behavior, run syntribos with the ``--no_downloads`` flag. Payload files can also be fetched by running ``syntribos download --payloads`` at any time.To specify a custom root for syntribos to be installed in,specify the ``--custom_install_root`` flag after ``init``. This will skipprompts for information from the terminal, which can be handy forJenkins jobs and other situations where user input cannot be retrieved.If you've already run the ``init`` command but want to start over with a freshenvironment, you can specify the ``--force`` flag to overwrite existing files.The ``--custom_install_root`` and ``--force`` flags can be combined tooverwrite files in a custom install root.**Example:**:: You can't use 'macro parameter character #' in math modeYou can't use 'macro parameter character #' in math mode vi examples/configs/keystone.conf [syntribos] # # As keystone is being tested in the example, enter your # # keystone auth endpoint url. endpoint=http://localhost:5000 # Set payload and templates path templates=<location_of_templates_dir/file> payloads=<location_of_payloads_dir> [user] # # User credentials # endpoint=http://localhost:5000 username=<yourusername> password=<yourpassword> # Optional, only needed if Keystone V3 API is used #user_id=<youruserid> # Optional, api version if required #version=v2.0 # Optional, for getting scoped tokens #user_id=<alt_userid> # If user id is not known # For V3 API #domain_name=<name_of_the_domain> #project_name=<name_of_the_project> # For Keystone V2 API #tenant_name=<name_of_the_project> #[alt_user] # # Optional, Used for cross auth tests (-t AUTH) # #endpoint=http://localhost:5000 #username=<alt_username> #password=<alt_password> # Optional, for getting scoped tokens #user_id=<alt_userid> # If user id is not known # For V3 API #domain_name=<name_of_the_domain> #project_name=<name_of_the_project> # For Keystone V2 API #tenant_name=<name_of_the_project> [remote] # # Optional, Used to specify URLs of templates and payloads # #cache_dir=<a local path to save the downloaded files> #templates_uri=https://github.com/your_project/templates.tar #payloads_uri=https://github.com/your_project/payloads.tar # To disable caching of these remote contents, set the following variable to False #enable_caching=True [logging] # # Logger options go here # log_dir=<location_to_store_log_files> # Optional, compresses http_request_content, # if you don't want this, set this option to False. http_request_compression=True========Commands========Below are the set of commands that can be specified whileusing syntribos:- **init** This command sets up the syntribos environment after installation. Running this command creates the necessary folders for templates, payloads, and logs; as well a sample configuration file. :: syntribosinitTolearnmoreabout‘‘syntribosinit‘‘,seetheinstallationinstructions‘here<installation.html>‘.−∗∗run∗∗Thiscommandrunssyntriboswiththegivenconfigoptions.:: syntribos --config-file keystone.conf -t SQL run- **dry_run** This command ensures that the template files given for this run parse successfully and without errors. It then runs a debug test which sends no requests of its own. :: syntribos−−config−filekeystone.confdryrun..Note::Ifanyexternalcallsreferencedinsidethetemplatefiledomakerequests,theparserwillstillmakethoserequestsevenforadryrun.−∗∗listtests∗∗Thiscommandwilllistthenamesofalltheteststhatcanbeexecutedbythe‘‘run‘‘commandwiththeirdescription.:: syntribos --config-file keystone.conf list_tests- **download** This command will download templates and payload files. By default, it will download a set of OpenStack template files (with the ``--templates`` flag), or a set of payloads (with the ``--payloads`` flag) to your syntribos root directory. However, the behavior of this command can be configured in the ``[remote]`` section of your config file. :: syntribosdownload−−templates..Important::Allthesecommands,except‘‘init‘‘,willonlyworkifaconfigurationfileisspecified.Ifaconfigurationfileispresentinthedefaultpath(‘‘ /.syntribos/syntribos.conf‘‘),thenyoudonotneedtoexplicitlyspecifyaconfigfileandcanrunsyntribosusingthecommand‘‘syntribosrun‘‘.=================Runningsyntribos=================Torunsyntribosagainstalltheavailabletests,specifythecommand‘‘syntribos‘‘withtheconfigurationfilewithoutspecifyinganytesttype.:: syntribos --config-file keystone.conf runFuzzy-matching test names~~~~~~~~~~~~~~~~~~~~~~~~~It is possible to limit syntribos to run a specific test type usingthe ``-t`` flag.:: You can't use 'macro parameter character #' in math modeYou can't use 'macro parameter character #' in math mode ls .syntribos/logs/ 2016-09-15_11:06:37.198412 2016-09-16_10:11:37.834892 2016-09-16_13:31:36.362584 2016-09-15_11:34:33.271606 2016-09-16_10:38:55.820827 2016-09-16_13:36:43.151048 2016-09-15_11:41:53.859970 2016-09-16_10:39:50.501820 2016-09-16_13:40:23.203920:: You can't use 'macro parameter character #' in math modeYou can't use 'macro parameter character #' in math mode syntribos --config-file keystone.conf -t SQL runTo run SQL injection tests against the template body only, see below::: syntribos−−config−filekeystone.conf−tSQLINJECTIONBODYrunForalltestsagainstHTTPheadersonly,seebelow::: syntribos --config-file keystone.conf -t HEADERS run============Unit testing============To execute unit tests automatically, navigate to the ``syntribos`` rootdirectory and install the test requirements.:: pipinstall−rtest−requirements.txtNow,runthe‘‘unittest‘‘asbelow::: python -m unittest discover tests/unit -p "test_*.py"If you have configured tox you could also run the following::: tox−epy27 tox -e py35This will run all the unit tests and give you a result outputcontaining the status and coverage details of each test.=======================Contributing Guidelines=======================Syntribos is an open source project and contributions are alwayswelcome. If you have any questions, we can be found in the#openstack-security channel on Freenode IRC.1. Follow all the `OpenStack Style Guidelines <https://docs.openstack.org/developer/hacking/>`__ (e.g. PEP8, Py3 compatibility)2. Follow `secure coding guidelines <https://security.openstack.org/#secure-development-guidelines>`__3. Ensure all classes/functions have appropriate `docstrings <https://www.python.org/dev/peps/pep-0257/>`__ in `RST format <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__4. Include appropriate unit tests for all new code(place them in the ``tests/unit`` folder)5. Test any change you make using tox: :: pip install tox tox -e pep8 tox -e py27 tox -e py35 tox -e coverAnyone wanting to contribute to OpenStack must follow`the OpenStack development workflow <https://docs.openstack.org/infra/manual/developers.html#development-workflow>`__Submit all changes through the code review process in Gerritdescribed above. All pull requests on Github will be closed/ignored.File bugs on the `syntribos launchpad site <https://bugs.launchpad.net/syntribos>`__,and not on Github. All Github issues will be closed/ignored.Submit blueprints `here <https://blueprints.launchpad.net/syntribos>`__ for allbreaking changes, feature requests, and other unprioritized work... Note:: README.rst is a file that can be generated by running ``python readme.py`` from the ``syntribos/scripts`` directory. When the README file needs to be updated; modify the corresponding rst file in ``syntribos/doc/source`` and have it generate by running the script.