Clarified docs and error messages
Change-Id: Ic30f6ade79461770a5283b4783aaa6d547049cff
This commit is contained in:
parent
92978b3783
commit
cb458c03db
|
@ -2,29 +2,6 @@
|
||||||
Syntribos, An Automated API Security Testing Tool
|
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 is
|
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>`_.
|
maintained by members of the `OpenStack Security Project <https://wiki.openstack.org/wiki/Security>`_.
|
||||||
|
|
||||||
|
|
|
@ -49,6 +49,9 @@ environment, you can specify the ``--force`` flag to overwrite existing files.
|
||||||
The ``--custom_install_root`` and ``--force`` flags can be combined to
|
The ``--custom_install_root`` and ``--force`` flags can be combined to
|
||||||
overwrite files in a custom install root.
|
overwrite files in a custom install root.
|
||||||
|
|
||||||
|
Note: if you install syntribos to a custom install root, you must supply the
|
||||||
|
``--custom_install_root`` flag when running syntribos.
|
||||||
|
|
||||||
**Example:**
|
**Example:**
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
|
@ -14,6 +14,9 @@ There are two types of logs generated by syntribos:
|
||||||
Results Log
|
Results Log
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
The results log is displayed at the end of every syntribos run, it can be
|
||||||
|
written to a file by using the ``-o`` flag on the command line.
|
||||||
|
|
||||||
The results log includes failures and errors. The ``"failures"`` key represents
|
The results log includes failures and errors. The ``"failures"`` key represents
|
||||||
tests that have failed, indicating a possible security vulnerability. The
|
tests that have failed, indicating a possible security vulnerability. The
|
||||||
``"errors"`` key gives us information on any unhandled exceptions, such as
|
``"errors"`` key gives us information on any unhandled exceptions, such as
|
||||||
|
|
|
@ -2,8 +2,14 @@
|
||||||
Running syntribos
|
Running syntribos
|
||||||
=================
|
=================
|
||||||
|
|
||||||
|
By default, syntribos looks in the syntribos home directory (the directory
|
||||||
|
specified when running the ``syntribos init`` command on install) for config
|
||||||
|
files, payloads, and templates. This can all be overridden through command
|
||||||
|
line options. For a full list of command line options available, run
|
||||||
|
``syntribos --help`` from the command line.
|
||||||
|
|
||||||
To run syntribos against all the available tests, specify the
|
To run syntribos against all the available tests, specify the
|
||||||
command ``syntribos`` with the configuration file without
|
command ``syntribos``, with the configuration file (if needed), without
|
||||||
specifying any test type.
|
specifying any test type.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
|
@ -6,6 +6,25 @@ This section describes how to write templates and how to run specific tests.
|
||||||
Templates are input files which have raw HTTP requests and may be
|
Templates are input files which have raw HTTP requests and may be
|
||||||
supplemented with variable data using extensions.
|
supplemented with variable data using extensions.
|
||||||
|
|
||||||
|
In general, a request template is a marked-up raw HTTP request. It's possible
|
||||||
|
for you to test your application by using raw HTTP requests as your request
|
||||||
|
templates, but syntribos allows you to mark-up your request templates for
|
||||||
|
further functionality.
|
||||||
|
|
||||||
|
A request template looks something like this:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
POST /users/{user1} HTTP/1.1
|
||||||
|
Content-Type: application/json
|
||||||
|
X-Auth-Token: CALL_EXTERNAL|syntribos.extensions.vAPI.client:get_token:[]|
|
||||||
|
|
||||||
|
{"newpassword": "qwerty123"}
|
||||||
|
|
||||||
|
For fuzz tests, syntribos will automatically detect URL parameters, headers,
|
||||||
|
and body content as fields to fuzz. It will not automatically detect URL path
|
||||||
|
elements as fuzz fields, but they can be specified with curly braces ``{}``.
|
||||||
|
|
||||||
Note: The name of a template file must end with the extension ``.template``
|
Note: The name of a template file must end with the extension ``.template``
|
||||||
Otherwise, syntribos will skip the file and will not attempt to parse any files
|
Otherwise, syntribos will skip the file and will not attempt to parse any files
|
||||||
that do not adhere to this naming scheme.
|
that do not adhere to this naming scheme.
|
||||||
|
|
|
@ -51,8 +51,7 @@ class RequestCreator(object):
|
||||||
:returns: RequestObject with method, url, params, etc. for use by
|
:returns: RequestObject with method, url, params, etc. for use by
|
||||||
runner
|
runner
|
||||||
"""
|
"""
|
||||||
if meta_vars:
|
cls.meta_vars = meta_vars
|
||||||
cls.meta_vars = meta_vars
|
|
||||||
string = cls.call_external_functions(string)
|
string = cls.call_external_functions(string)
|
||||||
action_field = str(uuid.uuid4()).replace("-", "")
|
action_field = str(uuid.uuid4()).replace("-", "")
|
||||||
string = string.replace(cls.ACTION_FIELD, action_field)
|
string = string.replace(cls.ACTION_FIELD, action_field)
|
||||||
|
@ -78,6 +77,13 @@ class RequestCreator(object):
|
||||||
:returns: VariableObject holding the attributes defined in the JSON
|
:returns: VariableObject holding the attributes defined in the JSON
|
||||||
object read in from meta.json
|
object read in from meta.json
|
||||||
"""
|
"""
|
||||||
|
if not cls.meta_vars:
|
||||||
|
msg = ("Template contains reference to meta variable of the form "
|
||||||
|
"\'|variable|\', but no meta.json file is found in the"
|
||||||
|
"templates directory. Check your templates and the "
|
||||||
|
"documentation on how to resolve this")
|
||||||
|
raise TemplateParseException(msg)
|
||||||
|
|
||||||
if var not in cls.meta_vars:
|
if var not in cls.meta_vars:
|
||||||
msg = _("Expected to find %s in meta.json, but didn't. "
|
msg = _("Expected to find %s in meta.json, but didn't. "
|
||||||
"Check your templates") % var
|
"Check your templates") % var
|
||||||
|
@ -266,7 +272,8 @@ class RequestCreator(object):
|
||||||
data = ElementTree.fromstring(data)
|
data = ElementTree.fromstring(data)
|
||||||
except Exception:
|
except Exception:
|
||||||
if not re.match(postdat_regex, data):
|
if not re.match(postdat_regex, data):
|
||||||
raise TypeError(_("Unknown data format"))
|
raise TypeError(_("Template request data does not contain "
|
||||||
|
"valid JSON or XML data"))
|
||||||
except Exception:
|
except Exception:
|
||||||
raise
|
raise
|
||||||
return data
|
return data
|
||||||
|
|
Loading…
Reference in New Issue