diff --git a/doc/source/about.rst b/doc/source/about.rst index 78278e89..8474f615 100644 --- a/doc/source/about.rst +++ b/doc/source/about.rst @@ -2,29 +2,6 @@ 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 maintained by members of the `OpenStack Security Project `_. diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 928131eb..23deb172 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -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 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:** :: diff --git a/doc/source/logging.rst b/doc/source/logging.rst index 285b0592..6eb32b9e 100644 --- a/doc/source/logging.rst +++ b/doc/source/logging.rst @@ -14,6 +14,9 @@ There are two types of logs generated by syntribos: 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 tests that have failed, indicating a possible security vulnerability. The ``"errors"`` key gives us information on any unhandled exceptions, such as diff --git a/doc/source/running.rst b/doc/source/running.rst index f3076414..b7b15186 100644 --- a/doc/source/running.rst +++ b/doc/source/running.rst @@ -2,8 +2,14 @@ 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 -command ``syntribos`` with the configuration file without +command ``syntribos``, with the configuration file (if needed), without specifying any test type. :: diff --git a/doc/source/test-anatomy.rst b/doc/source/test-anatomy.rst index 31ff7ab0..2a63c12d 100644 --- a/doc/source/test-anatomy.rst +++ b/doc/source/test-anatomy.rst @@ -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 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`` Otherwise, syntribos will skip the file and will not attempt to parse any files that do not adhere to this naming scheme. diff --git a/syntribos/clients/http/parser.py b/syntribos/clients/http/parser.py index 69df55d5..e403f2a0 100644 --- a/syntribos/clients/http/parser.py +++ b/syntribos/clients/http/parser.py @@ -51,8 +51,7 @@ class RequestCreator(object): :returns: RequestObject with method, url, params, etc. for use by runner """ - if meta_vars: - cls.meta_vars = meta_vars + cls.meta_vars = meta_vars string = cls.call_external_functions(string) action_field = str(uuid.uuid4()).replace("-", "") string = string.replace(cls.ACTION_FIELD, action_field) @@ -78,6 +77,13 @@ class RequestCreator(object): :returns: VariableObject holding the attributes defined in the 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: msg = _("Expected to find %s in meta.json, but didn't. " "Check your templates") % var @@ -266,7 +272,8 @@ class RequestCreator(object): data = ElementTree.fromstring(data) except Exception: 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: raise return data