Updating syntribos documentation
Updating documentation and fixing some nits Change-Id: Ic37199d35a5cd284506d1baefbbcdf31d2e458a6
This commit is contained in:
Rahul Nair
parent
97de7a6c17
commit
0824fddcaa
|
|
@ -1,9 +1,10 @@
|
|||
=================================
|
||||
Syntribos Contributing Guidelines
|
||||
=================================
|
||||
=======================
|
||||
Contributing Guidelines
|
||||
=======================
|
||||
|
||||
Contributions to syntribos are always welcome, if you have any questions,
|
||||
we can be found in the #openstack-security channel on Freenode IRC.
|
||||
Syntribos is an open source project and contributions are always
|
||||
welcome, if you have any questions, we can be found in the
|
||||
#openstack-security channel on Freenode IRC.
|
||||
|
||||
1. Follow all the `OpenStack Style Guidelines <http://docs.openstack.org/developer/hacking/>`__
|
||||
(e.g. PEP8, Py3 compatibility)
|
||||
|
|
@ -32,3 +33,8 @@ and not on Github. All Github issues will be closed/ignored.
|
|||
Breaking changes, feature requests, and other unprioritized work should first be
|
||||
submitted as a blueprint `here <https://blueprints.launchpad.net/syntribos>`__
|
||||
for review.
|
||||
|
||||
|
||||
**Note:** README.rst is auto generated from docs by running ``python readme.py``
|
||||
from the ``syntribos/scripts`` directory. So when the README.rst needs to be updated;
|
||||
modify the corresponding rst file in syntribos/doc/source and auto generatoe the README.
|
||||
|
|
|
|||
77
README.rst
77
README.rst
|
|
@ -32,8 +32,8 @@ Syntribos, An Automated API Security Testing Tool
|
|||
:target: https://pypi.python.org/pypi/syntribos/
|
||||
:alt: Downloads
|
||||
|
||||
Syntribos is an automated API security testing tool that is maintained by
|
||||
members of the `OpenStack Security Project <https://wiki.openstack.org/wiki/Security>`__.
|
||||
Syntribos is an open source automated API security testing tool that is
|
||||
maintained by members of the `OpenStack Security Project <https://wiki.openstack.org/wiki/Security>`__.
|
||||
|
||||
Given a simple configuration file and an example HTTP request, syntribos
|
||||
can replace any API URL, URL parameter, HTTP header and request body
|
||||
|
|
@ -217,7 +217,7 @@ file.
|
|||
endpoint=http://localhost:5000
|
||||
# Set payload and templates path
|
||||
templates=<location_of_templates_dir/file>
|
||||
payload_dir=<location_of_payload_dir>
|
||||
payloads_dir=<location_of_payloads_dir>
|
||||
|
||||
[user]
|
||||
#
|
||||
|
|
@ -247,7 +247,7 @@ section is the one being tested by syntribos and the endpoint URL in
|
|||
``[user]`` section is just used to get an AUTH_TOKEN.
|
||||
|
||||
Downloading templates and payloads remotely
|
||||
-------------------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Payload and template files can be downloaded remotely in syntribos.
|
||||
In the config file under ``[syntribos]`` section, if ``templates``
|
||||
|
|
@ -266,18 +266,18 @@ and payload files.
|
|||
The advantage of using these options are that you will be able to get
|
||||
the latest payloads from the official repository and if you are
|
||||
using syntribos to test OpenStack projects, then in most cases
|
||||
you would already have well defined templates availble to work with.
|
||||
you would already have well defined templates available to work with.
|
||||
|
||||
This option also helps to easily manage different versions of
|
||||
templates remotely, without the need to maintain a set of
|
||||
different versions offline.
|
||||
|
||||
Testing keystone API
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
Testing OpenStack keystone API
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A sample config file is given in :file:`examples/configs/keystone.conf`.
|
||||
A sample config file is given in ``examples/configs/keystone.conf``.
|
||||
Copy this file to a location of your choice (default file path for
|
||||
configuration file is: :file:`~/.syntribos/syntribos.conf`) and update the
|
||||
configuration file is: ``~/.syntribos/syntribos.conf``) and update the
|
||||
necessary fields like user credentials, log, template directory etc.
|
||||
|
||||
::
|
||||
|
|
@ -294,7 +294,7 @@ necessary fields like user credentials, log, template directory etc.
|
|||
endpoint=http://localhost:5000
|
||||
# Set payload and templates path
|
||||
templates=<location_of_templates_dir/file>
|
||||
payload_dir=<location_of_payload_dir>
|
||||
payloads_dir=<location_of_payloads_dir>
|
||||
|
||||
[user]
|
||||
#
|
||||
|
|
@ -351,15 +351,15 @@ 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
|
||||
==================
|
||||
========
|
||||
Commands
|
||||
========
|
||||
|
||||
Below are the set of commands that should be specified while
|
||||
Below are the set of commands that can be specified while
|
||||
using syntribos.
|
||||
|
||||
|
||||
- :command:`syntribos run`
|
||||
- ``syntribos run``
|
||||
|
||||
This command runs syntribos with the given config options
|
||||
|
||||
|
|
@ -367,7 +367,7 @@ using syntribos.
|
|||
|
||||
$ syntribos --config-file keystone.conf -t SQL run
|
||||
|
||||
- :command:`syntribos dry-run`
|
||||
- ``syntribos dry-run``
|
||||
|
||||
|
||||
This command ensures that the template files given for this run parse
|
||||
|
|
@ -382,7 +382,7 @@ using syntribos.
|
|||
$ syntribos --config-file keystone.conf dry_run
|
||||
|
||||
|
||||
- :command:`syntribos list_tests`
|
||||
- ``syntribos list_tests``
|
||||
|
||||
|
||||
This command will list the names and description of all the tests
|
||||
|
|
@ -394,15 +394,18 @@ using syntribos.
|
|||
|
||||
|
||||
All these commands will only work if a configuration file
|
||||
is specified.
|
||||
is specified. If a configuration file is present in the default
|
||||
path ( ``.syntribos/syntribos.conf`` ), then you
|
||||
do not need to explicitly specify a config file and
|
||||
can just run syntribos like ``syntribos run``.
|
||||
|
||||
=================
|
||||
Running syntribos
|
||||
=================
|
||||
|
||||
To run syntribos against all the available tests, just specify the
|
||||
command ``syntribos`` with the configuration file without specifying
|
||||
any test type.
|
||||
command ``syntribos`` with the configuration file without
|
||||
specifying any test type.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -422,9 +425,9 @@ the ``-t`` flag.
|
|||
This will match all tests that contain ``SQL`` in their name
|
||||
like SQL_INJECTION_HEADERS, SQL_INJECTION_BODY etc.
|
||||
|
||||
=================
|
||||
Syntribos logging
|
||||
=================
|
||||
===================
|
||||
Logging and Results
|
||||
===================
|
||||
|
||||
Two types of logs are generated by syntribos, results and debug logs. While
|
||||
results log is the representation of results(collection of issues) from a
|
||||
|
|
@ -589,7 +592,7 @@ And the signals captured:
|
|||
|
||||
Debug logs are sanitized to prevent storing secrets to log files.
|
||||
Passwords and other sensitive information are masked with astericks using a
|
||||
slightly modified version of `oslo_utils.strutils.mask_password <http://docs.openstack.org/developer/oslo.utils/api/strutils.html#oslo_utils.strutils.mask_password>_`
|
||||
slightly modified version of `oslo_utils.strutils.mask_password <http://docs.openstack.org/developer/oslo.utils/api/strutils.html#oslo_utils.strutils.mask_password>`__
|
||||
|
||||
Debug logs also includes body compression, wherein long fuzz strings are
|
||||
compressed before being written to the logs. The threshold to start data
|
||||
|
|
@ -628,12 +631,24 @@ containing the status and coverage details of each test.
|
|||
Contributing Guidelines
|
||||
=======================
|
||||
|
||||
Syntribos is an open source project and contributions are always
|
||||
welcome, if you have any questions, we can be found in the
|
||||
#openstack-security channel on Freenode IRC.
|
||||
|
||||
1. Follow all the `OpenStack Style Guidelines <http://docs.openstack.org/developer/hacking/>`__
|
||||
(e.g. PEP8, Py3 compatibility)
|
||||
2. All new classes/functions should have appropriate docstrings in
|
||||
`RST format <https://pythonhosted.org/an_example_pypi_project/sphinx.html>`__
|
||||
3. All new code should have appropriate unittests (place them in the
|
||||
:file:`tests/unit` folder)
|
||||
``tests/unit`` folder)
|
||||
|
||||
4. Any change you make can be tested using tox:
|
||||
|
||||
pip install tox
|
||||
tox -e pep8
|
||||
tox -e py27
|
||||
tox -e py34
|
||||
tox -e cover
|
||||
|
||||
Anyone wanting to contribute to OpenStack must follow
|
||||
`the OpenStack development workflow <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`__
|
||||
|
|
@ -644,12 +659,12 @@ described above. All pull requests on Github will be closed/ignored.
|
|||
Bugs should be filed on the `syntribos launchpad site <https://bugs.launchpad.net/syntribos>`__,
|
||||
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 <https://blueprints.launchpad.net/syntribos>`__
|
||||
Breaking changes, feature requests, and other unprioritized work should first be
|
||||
submitted as a blueprint `here <https://blueprints.launchpad.net/syntribos>`__
|
||||
for review.
|
||||
|
||||
Note: 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.
|
||||
|
||||
**Note:** README.rst is auto generated from docs by running ``python readme.py``
|
||||
from the ``syntribos/scripts`` directory. So when the README.rst needs to be updated;
|
||||
modify the corresponding rst file in syntribos/doc/source and auto generatoe the README.
|
||||
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ Syntribos, An Automated API Security Testing Tool
|
|||
:target: https://pypi.python.org/pypi/syntribos/
|
||||
:alt: Downloads
|
||||
|
||||
Syntribos is an automated API security testing tool that is maintained by
|
||||
members of the `OpenStack Security Project <https://wiki.openstack.org/wiki/Security>`__.
|
||||
Syntribos is an open source automated API security testing tool that is
|
||||
maintained by members of the `OpenStack Security Project <https://wiki.openstack.org/wiki/Security>`__.
|
||||
|
||||
Given a simple configuration file and an example HTTP request, syntribos
|
||||
can replace any API URL, URL parameter, HTTP header and request body
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
==================
|
||||
Syntribos Commands
|
||||
==================
|
||||
========
|
||||
Commands
|
||||
========
|
||||
|
||||
Below are the set of commands that should be specified while
|
||||
Below are the set of commands that can be specified while
|
||||
using syntribos.
|
||||
|
||||
|
||||
- :command:`syntribos run`
|
||||
- ``syntribos run``
|
||||
|
||||
This command runs syntribos with the given config options
|
||||
|
||||
|
|
@ -14,7 +14,7 @@ using syntribos.
|
|||
|
||||
$ syntribos --config-file keystone.conf -t SQL run
|
||||
|
||||
- :command:`syntribos dry-run`
|
||||
- ``syntribos dry-run``
|
||||
|
||||
|
||||
This command ensures that the template files given for this run parse
|
||||
|
|
@ -29,7 +29,7 @@ using syntribos.
|
|||
$ syntribos --config-file keystone.conf dry_run
|
||||
|
||||
|
||||
- :command:`syntribos list_tests`
|
||||
- ``syntribos list_tests``
|
||||
|
||||
|
||||
This command will list the names and description of all the tests
|
||||
|
|
@ -41,4 +41,7 @@ using syntribos.
|
|||
|
||||
|
||||
All these commands will only work if a configuration file
|
||||
is specified.
|
||||
is specified. If a configuration file is present in the default
|
||||
path ( ``.syntribos/syntribos.conf`` ), then you
|
||||
do not need to explicitly specify a config file and
|
||||
can just run syntribos like ``syntribos run``.
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ file.
|
|||
endpoint=http://localhost:5000
|
||||
# Set payload and templates path
|
||||
templates=<location_of_templates_dir/file>
|
||||
payload_dir=<location_of_payload_dir>
|
||||
payloads_dir=<location_of_payloads_dir>
|
||||
|
||||
[user]
|
||||
#
|
||||
|
|
@ -51,7 +51,7 @@ section is the one being tested by syntribos and the endpoint URL in
|
|||
``[user]`` section is just used to get an AUTH_TOKEN.
|
||||
|
||||
Downloading templates and payloads remotely
|
||||
-------------------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Payload and template files can be downloaded remotely in syntribos.
|
||||
In the config file under ``[syntribos]`` section, if ``templates``
|
||||
|
|
@ -70,18 +70,18 @@ and payload files.
|
|||
The advantage of using these options are that you will be able to get
|
||||
the latest payloads from the official repository and if you are
|
||||
using syntribos to test OpenStack projects, then in most cases
|
||||
you would already have well defined templates availble to work with.
|
||||
you would already have well defined templates available to work with.
|
||||
|
||||
This option also helps to easily manage different versions of
|
||||
templates remotely, without the need to maintain a set of
|
||||
different versions offline.
|
||||
|
||||
Testing keystone API
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
Testing OpenStack keystone API
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A sample config file is given in :file:`examples/configs/keystone.conf`.
|
||||
A sample config file is given in ``examples/configs/keystone.conf``.
|
||||
Copy this file to a location of your choice (default file path for
|
||||
configuration file is: :file:`~/.syntribos/syntribos.conf`) and update the
|
||||
configuration file is: ``~/.syntribos/syntribos.conf``) and update the
|
||||
necessary fields like user credentials, log, template directory etc.
|
||||
|
||||
::
|
||||
|
|
@ -98,7 +98,7 @@ necessary fields like user credentials, log, template directory etc.
|
|||
endpoint=http://localhost:5000
|
||||
# Set payload and templates path
|
||||
templates=<location_of_templates_dir/file>
|
||||
payload_dir=<location_of_payload_dir>
|
||||
payloads_dir=<location_of_payloads_dir>
|
||||
|
||||
[user]
|
||||
#
|
||||
|
|
|
|||
|
|
@ -2,12 +2,24 @@
|
|||
Contributing Guidelines
|
||||
=======================
|
||||
|
||||
Syntribos is an open source project and contributions are always
|
||||
welcome, if you have any questions, we can be found in the
|
||||
#openstack-security channel on Freenode IRC.
|
||||
|
||||
1. Follow all the `OpenStack Style Guidelines <http://docs.openstack.org/developer/hacking/>`__
|
||||
(e.g. PEP8, Py3 compatibility)
|
||||
2. All new classes/functions should have appropriate docstrings in
|
||||
`RST format <https://pythonhosted.org/an_example_pypi_project/sphinx.html>`__
|
||||
3. All new code should have appropriate unittests (place them in the
|
||||
:file:`tests/unit` folder)
|
||||
``tests/unit`` folder)
|
||||
|
||||
4. Any change you make can be tested using tox:
|
||||
|
||||
pip install tox
|
||||
tox -e pep8
|
||||
tox -e py27
|
||||
tox -e py34
|
||||
tox -e cover
|
||||
|
||||
Anyone wanting to contribute to OpenStack must follow
|
||||
`the OpenStack development workflow <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`__
|
||||
|
|
@ -18,11 +30,11 @@ described above. All pull requests on Github will be closed/ignored.
|
|||
Bugs should be filed on the `syntribos launchpad site <https://bugs.launchpad.net/syntribos>`__,
|
||||
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 <https://blueprints.launchpad.net/syntribos>`__
|
||||
Breaking changes, feature requests, and other unprioritized work should first be
|
||||
submitted as a blueprint `here <https://blueprints.launchpad.net/syntribos>`__
|
||||
for review.
|
||||
|
||||
Note: 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.
|
||||
|
||||
**Note:** README.rst is auto generated from docs by running ``python readme.py``
|
||||
from the ``syntribos/scripts`` directory. So when the README.rst needs to be updated;
|
||||
modify the corresponding rst file in syntribos/doc/source and auto generatoe the README.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
=================
|
||||
Syntribos logging
|
||||
=================
|
||||
===================
|
||||
Logging and Results
|
||||
===================
|
||||
|
||||
Two types of logs are generated by syntribos, results and debug logs. While
|
||||
results log is the representation of results(collection of issues) from a
|
||||
|
|
@ -165,7 +165,7 @@ And the signals captured:
|
|||
|
||||
Debug logs are sanitized to prevent storing secrets to log files.
|
||||
Passwords and other sensitive information are masked with astericks using a
|
||||
slightly modified version of `oslo_utils.strutils.mask_password <http://docs.openstack.org/developer/oslo.utils/api/strutils.html#oslo_utils.strutils.mask_password>_`
|
||||
slightly modified version of `oslo_utils.strutils.mask_password <http://docs.openstack.org/developer/oslo.utils/api/strutils.html#oslo_utils.strutils.mask_password>`__
|
||||
|
||||
Debug logs also includes body compression, wherein long fuzz strings are
|
||||
compressed before being written to the logs. The threshold to start data
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ 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 :file:`*.conf` files
|
||||
--config-dir DIR Path to a config directory to pull ``*.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)
|
||||
|
|
@ -73,10 +73,10 @@ Main Syntribos Config:
|
|||
|
||||
Syntribos Commands:
|
||||
{list_tests,run,dry_run}
|
||||
Available commands
|
||||
Available commands
|
||||
list_tests List all available tests
|
||||
run Run syntribos with given config options
|
||||
dry_run Dry run Syntribos with given config options
|
||||
dry_run Dry run syntribos with given config options
|
||||
|
||||
FILES
|
||||
~~~~~
|
||||
|
|
@ -88,7 +88,7 @@ EXAMPLES
|
|||
~~~~~~~~
|
||||
|
||||
To run syntribos against all the available tests, just specify the
|
||||
command :command:`syntribos run` with the configuration file without
|
||||
command ``syntribos run`` with the configuration file without
|
||||
specifying any test type.
|
||||
|
||||
::
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@ Running syntribos
|
|||
=================
|
||||
|
||||
To run syntribos against all the available tests, just specify the
|
||||
command ``syntribos`` with the configuration file without specifying
|
||||
any test type.
|
||||
command ``syntribos`` with the configuration file without
|
||||
specifying any test type.
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
============================
|
||||
Basic syntribos Test Anatomy
|
||||
============================
|
||||
==================
|
||||
Basic Test Anatomy
|
||||
==================
|
||||
|
||||
This section describes how to test and API using syntribos.
|
||||
|
||||
Test Types
|
||||
~~~~~~~~~~
|
||||
|
||||
The tests included at release time include LDAP injection, SQL
|
||||
Some tests included with syntribos by default are LDAP injection, SQL
|
||||
injection, integer overflow, command injection, XML external entity,
|
||||
reflected cross-site scripting, Cross Origin Resource Sharing (CORS)
|
||||
wildcard and SSL.
|
||||
|
|
@ -48,8 +50,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
|
||||
token from keystone/identity. The code is located in
|
||||
``identity/client.py``
|
||||
token from keystone. The code is located in ``identity/client.py``
|
||||
|
||||
To use this extension, you can add the following to your template file:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue