Updating readme
Updating readme with details on extensions. Also, fixing a bug in readme.py file, on account of changing file name of test_anatomy.rst to test-anatomy.rst Also, fixing a few spelling mistakes. Change-Id: Ic86d9fcb0be74f9474e1b070ed19d4708d61b677
This commit is contained in:
Rahul Nair
parent
9909a0e6f6
commit
09f5a1820a
186
README.rst
186
README.rst
|
|
@ -287,7 +287,7 @@ file.
|
|||
|
||||
[remote]
|
||||
#
|
||||
# Optional, to define remote URI and cache_dir explictly
|
||||
# Optional, to define remote URI and cache_dir explicitly
|
||||
#
|
||||
templates_uri=<URI to a tar file of set of templates>
|
||||
payloads_uri=<URI to a tar file of set of payloads>
|
||||
|
|
@ -600,7 +600,7 @@ Debug logs include details about HTTP requests and responses, and other debuggin
|
|||
information like errors and warnings across the project. The default path where
|
||||
debug logs are saved is ``.syntribos/logs/``. Debug logs are arranged in
|
||||
directories based on the timestamp and in these directories, in files named
|
||||
accordring to the templates.
|
||||
according to the templates.
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -686,6 +686,187 @@ compression is set to 512 characters. While compression can be turned off
|
|||
by setting the variable "http_request_compression" under logging section
|
||||
in the config file to ``False``, it is not recommended.
|
||||
|
||||
=============================
|
||||
Anatomy of a request template
|
||||
=============================
|
||||
|
||||
This section will give you a brief idea on writing templates
|
||||
and on how to run specific tests. Templates are input files which has
|
||||
raw http requests and may also be supplemented with variable
|
||||
data using extensions.
|
||||
|
||||
Syntribos template files are ordinary text files containing raw http
|
||||
requests.
|
||||
|
||||
Using external functions in templates
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These template files can also 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. 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.
|
||||
|
||||
Built in functions
|
||||
------------------
|
||||
|
||||
Syntribos comes with a slew of utility functions/extensions, these functions can
|
||||
be used to dynamically inject data into templates.
|
||||
|
||||
.. list-table:: **Utility Functions**
|
||||
:widths: 15 35 40
|
||||
:header-rows: 1
|
||||
|
||||
* - Method
|
||||
- Parameters
|
||||
- Description
|
||||
* - hash_it
|
||||
- [data, hash_type (optional hash type, default being SHA256)]
|
||||
- Returns hashed value of data
|
||||
* - hmac_it
|
||||
- [data, key, hash_type (optional hash type, default being SHA256)]
|
||||
- Returns HMAC based on the has algorithm, data and the key provided
|
||||
* - epoch_time
|
||||
- [offset (optional integer offset value, default is zero)]
|
||||
- Returns the current time minus offset since epoch
|
||||
* - utc_datetime
|
||||
- []
|
||||
- Returns current UTC date time
|
||||
* - base64_encode
|
||||
- [data]
|
||||
- Returns base 64 encoded value of data supplied
|
||||
* - url_encode
|
||||
- [url]
|
||||
- Returns encoded URL
|
||||
|
||||
All these utility functions can be called using:
|
||||
|
||||
::
|
||||
|
||||
CALL_EXTERNAL|common_utils.client.{method_name}:{comma separated parameters in square brackets}
|
||||
|
||||
For example:
|
||||
|
||||
::
|
||||
|
||||
"encoded_url": "CALL_EXTERNAL|common_utils.client:url_encode:['http://localhost:5000']|
|
||||
|
||||
There are a few other functions that return random values as well, they are:
|
||||
|
||||
.. list-table:: **Random Functions**
|
||||
:widths: 15 35 40
|
||||
:header-rows: 1
|
||||
|
||||
* - Method
|
||||
- Parameters
|
||||
- Description
|
||||
* - get_uuid
|
||||
- []
|
||||
- Returns a random UUID
|
||||
* - random_port
|
||||
- []
|
||||
- Returns random port number between 0 and 65535
|
||||
* - random_ip
|
||||
- []
|
||||
- Returns random ipv4 address
|
||||
* - random_mac
|
||||
- []
|
||||
- Returns random mac address
|
||||
* - random_integer
|
||||
- [beg (optional beginning value, default is 0), end (optional end value)]
|
||||
- Returns an integer value between 0 and 1468029570 by default
|
||||
* - random_utc_datetime
|
||||
- []
|
||||
- Returns random UTC datetime
|
||||
|
||||
These can be called using:
|
||||
|
||||
::
|
||||
|
||||
CALL_EXTERNAL|random_data.client.{method_name}:{comma separated parameters in square brackets}
|
||||
|
||||
For example,
|
||||
|
||||
::
|
||||
|
||||
"address": "CALL_EXTERNAL|random_data.client:random_ip:[]|"
|
||||
|
||||
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.
|
||||
|
||||
Running a specific test
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As mentioned above, 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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
===================
|
||||
Executing unittests
|
||||
===================
|
||||
|
|
@ -756,4 +937,3 @@ docs directory. The file can be generated by running ``python readme.py``
|
|||
from the ``syntribos/scripts`` directory. When the README needs to be
|
||||
updated; modify the corresponding rst file in ``syntribos/doc/source``
|
||||
and generate it by running the script.
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ file.
|
|||
|
||||
[remote]
|
||||
#
|
||||
# Optional, to define remote URI and cache_dir explictly
|
||||
# Optional, to define remote URI and cache_dir explicitly
|
||||
#
|
||||
templates_uri=<URI to a tar file of set of templates>
|
||||
payloads_uri=<URI to a tar file of set of payloads>
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ Debug logs include details about HTTP requests and responses, and other debuggin
|
|||
information like errors and warnings across the project. The default path where
|
||||
debug logs are saved is ``.syntribos/logs/``. Debug logs are arranged in
|
||||
directories based on the timestamp and in these directories, in files named
|
||||
accordring to the templates.
|
||||
according to the templates.
|
||||
|
||||
For example:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,45 +1,21 @@
|
|||
==================
|
||||
Basic Test Anatomy
|
||||
==================
|
||||
=============================
|
||||
Anatomy of a request template
|
||||
=============================
|
||||
|
||||
This section describes how to test and API using syntribos.
|
||||
This section will give you a brief idea on writing templates
|
||||
and on how to run specific tests. Templates are input files which has
|
||||
raw http requests and may also be supplemented with variable
|
||||
data using extensions.
|
||||
|
||||
Test Types
|
||||
~~~~~~~~~~
|
||||
Syntribos template files are ordinary text files containing raw http
|
||||
requests.
|
||||
|
||||
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.
|
||||
Using external functions in templates
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.'
|
||||
These template files can also be supplemented with variable
|
||||
data, or data retrieved from external sources. This is handled
|
||||
using 'extensions.'
|
||||
|
||||
Extensions are found in ``syntribos/extensions/`` .
|
||||
|
||||
|
|
@ -72,6 +48,89 @@ usernames when fuzzing a create user call.
|
|||
The extension function can return one value or be used as a generator if
|
||||
you want it to change for each test.
|
||||
|
||||
Built in functions
|
||||
------------------
|
||||
|
||||
Syntribos comes with a slew of utility functions/extensions, these functions can
|
||||
be used to dynamically inject data into templates.
|
||||
|
||||
.. list-table:: **Utility Functions**
|
||||
:widths: 15 35 40
|
||||
:header-rows: 1
|
||||
|
||||
* - Method
|
||||
- Parameters
|
||||
- Description
|
||||
* - hash_it
|
||||
- [data, hash_type (optional hash type, default being SHA256)]
|
||||
- Returns hashed value of data
|
||||
* - hmac_it
|
||||
- [data, key, hash_type (optional hash type, default being SHA256)]
|
||||
- Returns HMAC based on the has algorithm, data and the key provided
|
||||
* - epoch_time
|
||||
- [offset (optional integer offset value, default is zero)]
|
||||
- Returns the current time minus offset since epoch
|
||||
* - utc_datetime
|
||||
- []
|
||||
- Returns current UTC date time
|
||||
* - base64_encode
|
||||
- [data]
|
||||
- Returns base 64 encoded value of data supplied
|
||||
* - url_encode
|
||||
- [url]
|
||||
- Returns encoded URL
|
||||
|
||||
All these utility functions can be called using:
|
||||
|
||||
::
|
||||
|
||||
CALL_EXTERNAL|common_utils.client.{method_name}:{comma separated parameters in square brackets}
|
||||
|
||||
For example:
|
||||
|
||||
::
|
||||
|
||||
"encoded_url": "CALL_EXTERNAL|common_utils.client:url_encode:['http://localhost:5000']|
|
||||
|
||||
There are a few other functions that return random values as well, they are:
|
||||
|
||||
.. list-table:: **Random Functions**
|
||||
:widths: 15 35 40
|
||||
:header-rows: 1
|
||||
|
||||
* - Method
|
||||
- Parameters
|
||||
- Description
|
||||
* - get_uuid
|
||||
- []
|
||||
- Returns a random UUID
|
||||
* - random_port
|
||||
- []
|
||||
- Returns random port number between 0 and 65535
|
||||
* - random_ip
|
||||
- []
|
||||
- Returns random ipv4 address
|
||||
* - random_mac
|
||||
- []
|
||||
- Returns random mac address
|
||||
* - random_integer
|
||||
- [beg (optional beginning value, default is 0), end (optional end value)]
|
||||
- Returns an integer value between 0 and 1468029570 by default
|
||||
* - random_utc_datetime
|
||||
- []
|
||||
- Returns random UTC datetime
|
||||
|
||||
These can be called using:
|
||||
|
||||
::
|
||||
|
||||
CALL_EXTERNAL|random_data.client.{method_name}:{comma separated parameters in square brackets}
|
||||
|
||||
For example,
|
||||
|
||||
::
|
||||
|
||||
"address": "CALL_EXTERNAL|random_data.client:random_ip:[]|"
|
||||
|
||||
Action Field
|
||||
~~~~~~~~~~~~
|
||||
|
|
@ -86,3 +145,36 @@ follows:
|
|||
"ACTION_FIELD:id": "1a16f348-c8d5-42ec-a474-b1cdf78cf40f"
|
||||
|
||||
The ID provided will remain static for every test.
|
||||
|
||||
Running a specific test
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As mentioned above, 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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ def find_docs():
|
|||
"about", "installation",
|
||||
"configuration", "commands",
|
||||
"running", "logging",
|
||||
"test.anatomy", "unittests",
|
||||
"test-anatomy", "unittests",
|
||||
"contributing"]
|
||||
|
||||
for fname in whitelist:
|
||||
|
|
|
|||
Loading…
Reference in New Issue