Syntribos는 주로 Linux 및 Mac 환경에서 개발되었으며, 대부분의 Unix 및 Linux 기반 운영 체제에서 작동합니다. 현재로서는 Windows를 지원하지 않지만, 향후 변경될 수 있습니다.

.. _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

============
설치
============

Syntribos는 `pypi와 pip를 통해 <https://pypi.python.org/pypi/pip>`__ 직접 설치할 수 있습니다.

::

   pip install syntribos

최신 변경 사항을 적용하려면 `소스 <https://www.github.com/openstack/syntribos.git>`__ 에서
`pip <https://pypi.python.org/pypi/pip>`__ 를 통해 syntribos를 설치하세요.

저장소를 복제합니다::

   $ git clone https://github.com/openstack/syntribos.git

복제된 저장소 디렉터리로 이동하여 pip로 설치합니다::

   $ cd syntribos
   $ pip install .

======================================
syntribos 환경 초기화
======================================

syntribos가 설치되면, syntribos 환경을 초기화해야 합니다. 이것은 수동으로 또는 ``init`` 명령어로 수행할 수 있습니다.

::

    $ syntribos init

.. Note::
    기본적으로 ``syntribos init``는 저희 개발 팀이 유지 관리하는
    `원격 저장소 <https://github.com/openstack/syntribos-payloads>`_ 에서 기본 페이로드 파일 세트를 가져옵니다.
    이 페이로드 파일은 퍼즈 테스트 실행에 필요합니다.
    이 동작을 비활성화하려면 ``--no_downloads`` 플래그와 함께 syntribos를 실행하세요.
    페이로드 파일은 언제든지 ``syntribos download --payloads`` 명령을 실행하여 가져올 수도 있습니다.

syntribos가 설치될 사용자 정의 루트를 지정하려면
``--custom_root`` 플래그를 지정하세요. 이렇게 하면 터미널에서 정보 입력을 위한
프롬프트가 생략되며, Jenkins 작업이나 사용자 입력을 받을 수 없는 상황에서 유용합니다.

이미 ``init`` 명령을 실행했지만 새 환경으로 다시 시작하려면 ``--force`` 플래그를
지정하여 기존 파일을 덮어쓸 수 있습니다. ``--custom_root``와 ``--force`` 플래그를 결합하여
사용자 정의 설치 루트의 파일을 덮어쓸 수 있습니다.

참고: 사용자 정의 설치 루트에 syntribos를 설치하는 경우, syntribos를 실행할 때
``--custom_root`` 플래그를 제공해야 합니다.

**예시:**

::

    $ syntribos --custom_root /your/custom/path init --force
    $ syntribos --custom_root /your/custom/path run



=============
설정
=============

모든 설정 파일에는 ``[syntribos]`` 섹션이 있어야 합니다.
사용 중인 확장 기능과 테스트 대상에 따라 다른 섹션을 추가하세요.
예를 들어, 내장된 ID 확장 기능을 사용하는 경우 ``[user]``
섹션이 필요합니다. ``[logging]`` 및 ``[remote]`` 섹션은 선택 사항입니다.

syntribos 설정 파일의 기본 구조는 다음과 같습니다::

    [syntribos]
    #
    # 테스트할 서비스의 엔드포인트 URL 및 버전.
    #
    endpoint=http://localhost:5000
    # 페이로드 및 템플릿 경로 설정
    templates=<템플릿_디렉터리_위치/파일>
    payloads=<페이로드_디렉터리_위치>

    [user]
    #
    # AUTH_TOKEN을 얻기 위한 사용자 자격 증명 및 엔드포인트 URL
    # 이 섹션은 ID 확장 기능을 사용하는 경우에만 필요합니다.
    #
    endpoint=
    username=<사용자이름>
    password=<비밀번호>

    [remote]
    #
    # 선택 사항, 원격 URI 및 cache_dir을 명시적으로 정의하려면
    #
    templates_uri=<템플릿 세트가 포함된 tar 파일의 URI>
    payloads_uri=<페이로드 세트가 포함된 tar 파일의 URI>
    cache_dir=<다운로드한 파일을 저장할 로컬 경로>

    [logging]
    log_dir=<디버그 로그를 저장할 위치>

``[syntribos]`` 섹션에 지정된 엔드포인트 URL은 syntribos가 테스트하는 엔드포인트 URL입니다.
``[user]`` 섹션의 엔드포인트 URL은 AUTH_TOKEN을 얻는 데 사용됩니다.
프로젝트를 테스트하려면 ``[syntribos]`` 아래의 엔드포인트 URL을
API를 가리키도록 업데이트하고 필요한 경우 사용자 자격 증명도 수정하세요.

템플릿 및 페이로드를 원격으로 다운로드하기~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Payload and template files can be downloaded remotely in syntribos.
In the config file under the ``[syntribos]`` section, if the ``templates``
and ``payloads`` options are not set, by default syntribos will
download all the latest payloads and the templates for a few OpenStack
projects.

To specify a URI to download custom templates and payloads
from, use the ``[remotes]`` section in the config file.
Available options under ``[remotes]`` are ``cache_dir``, ``templates_uri``,
``payloads_uri``, and ``enable_cache``. The ``enable_cache`` option is
``True`` by default; set to ``False`` to disable caching of remote
content while syntribos is running. If the ``cache_dir`` set to a path,
syntribos will attempt to use that as a base directory to save downloaded
template 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
could directly use the well defined templates available with this option.

This option also helps to easily manage different versions of templates
remotely, without the need to maintain a set of different versions offline.

Testing OpenStack keystone API

$ 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

$ syntribos --config-file keystone.conf run

It is possible to limit syntribos to run a specific test type using
the ``-t`` flag.

::

    $ syntribos --config-file keystone.conf -t SQL run


This will match all tests that contain ``SQL`` in their name. For example:
``SQL_INJECTION_HEADERS``, ``SQL_INJECTION_BODY``, etc.

Specifying a custom root directory

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
connection errors, encountered on that run.

Example failure object:

::

    {
       "defect_type": "xss_strings",
       "description": "The string(s): '[\"<STYLE>@import'http://xss.rocks/xss.css';</STYLE>\"]',
       known to be commonly returned after a successful XSS attack, have been found in the
       response. This could indicate a vulnerability to XSS attacks.",
       "failure_id": 33,
       "instances": [
          {
            "confidence": "LOW",
            "param": {
              "location": "data",
              "method": "POST",
              "type": null,
              "variables": [
                "type",
                "details/name",
              ]
          },
          "severity": "LOW",
          "signals": {
             "diff_signals": [
               "LENGTH_DIFF_OVER"
             ],
             "init_signals": [
               "HTTP_CONTENT_TYPE_JSON",
               "HTTP_STATUS_CODE_2XX_201"
             ],
             "test_signals": [
               "FAILURE_KEYS_PRESENT",
               "HTTP_CONTENT_TYPE_JSON",
               "HTTP_STATUS_CODE_2XX_201",
             ]
          },
          "strings": [
            "<STYLE>@import'http://xss.rocks/xss.css';</STYLE>"
             ]
          }
       ],
       "url": "127.0.0.1/test"
    }


Error form:

::

    ERROR:
    {
      "error": "Traceback (most recent call last):\n  File \"/Users/test/syntribos/tests/fuzz/base_fuzz.py\",
       line 58, in tearDownClass\n    super(BaseFuzzTestCase, cls).tearDownClass()\n
       File \"/Users/test/syntribos/tests/base.py\", line 166, in tearDownClass\n
       raise sig.data[\"exception\"]\nReadTimeout: HTTPConnectionPool(host='127.0.0.1', port=8080):
       Read timed out. (read timeout=10)\n",
       "test": "tearDownClass (syntribos.tests.fuzz.sql.image_data_image_data_get.template_SQL_INJECTION_HEADERS_sql-injection.txt_str21_model1)"
    }


Debug Logs
~~~~~~~~~~

Debug logs include details about HTTP requests, HTTP responses, and other
debugging information such as errors and warnings across the project. The
path where debug logs are saved by default is ``.syntribos/logs/``.
Debug logs are arranged in directories based on the timestamp in these
directories and files are named according to the templates.

For example:

::

    $ 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

::

    $ ls .syntribos/logs/2016-09-16_13:31:36.362584
    API_Versions::list_versions_template.log
    API_Versions::show_api_details_template.log
    availability_zones::get_availability_zone_detail_template.log
    availability_zones::get_availability_zone_template.log
    cells::delete_os_cells_template.log
    cells::get_os_cells_capacities_template.log
    cells::get_os_cells_data_template.log

Each log file includes some essential debugging information such as the string
representation of the request object, signals, and checks used for tests, etc.

Example request::

    ------------
    REQUEST SENT
    ------------
    request method.......: PUT
    request url..........: http://127.0.0.1/api
    request params.......:
    request headers size.: 7
    request headers......: {'Content-Length': '0', 'Accept-Encoding': 'gzip, deflate',
    'Accept': 'application/json',
    'X-Auth-Token': <uuid>, 'Connection': 'keep-alive',
    'User-Agent': 'python-requests/2.11.1', 'content-type': 'application/xml'}
    request body size....: 0
    request body.........: None

Example response::

    -----------------
    RESPONSE RECEIVED
    -----------------
    response status..: <Response [415]>
    response headers.: {'Content-Length': '70',
    'X-Compute-Request-Id': <random id>,
    'Vary': 'OpenStack-API-Version, X-OpenStack-Nova-API-Version',
    'Openstack-Api-Version': 'compute 2.1', 'Connection': 'close',
    'X-Openstack-Nova-Api-Version': '2.1', 'Date': 'Fri, 16 Sep 2016 14:15:27 GMT',
    'Content-Type': 'application/json; charset=UTF-8'}
    response time....: 0.036277
    response size....: 70
    response body....: {"badMediaType": {"message": "Unsupported Content-Type", "code": 415}}
    -------------------------------------------------------------------------------
    [2590]  :  XSS_BODY
    (<syntribos.clients.http.client.SynHTTPClient object at 0x102c65f10>, 'PUT',
    'http://127.0.0.1/api')
    {'headers': {'Accept': 'application/json', 'X-Auth-Token': <uuid> },
    'params': {}, 'sanitize': False, 'data': '', 'requestslib_kwargs': {'timeout': 10}}
    Starting new HTTP connection (1): 127.0.0.1
    "PUT http://127.0.0.1/api HTTP/1.1" 501 93

Example signals captured::

    Signals: ['HTTP_STATUS_CODE_4XX_400', 'HTTP_CONTENT_TYPE_JSON']
    Checks used: ['HTTP_STATUS_CODE', 'HTTP_CONTENT_TYPE']

Debug logs are sanitized to prevent storing secrets to log files.
Passwords and other sensitive information are marked with asterisks using a
slightly modified version of `oslo_utils.strutils.mask_password <https://docs.openstack.org/developer/oslo.utils/api/strutils.html#oslo_utils.strutils.mask_password>`__.

Debug logs also include string compression, wherein long fuzz strings are
compressed before being written to the logs. The threshold to start data
compression is set to 512 characters. Although it is not recommended to turn
off compression, it is possible by setting the variable
``"http_request_compression"``, under the logging section in the config file,
to ``False``.


=============================
Anatomy of a request template
=============================

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.

Using external functions in templates

CALL_EXTERNAL|{extension dot path}:{function name}:[arguments]

X-Auth-Token: CALL_EXTERNAL|syntribos.extensions.identity.client:get_token_v3:["user"]|

"username": "CALL_EXTERNAL|syntribos.extensions.random_data.client:get_uuid:[]|"

CALL_EXTERNAL|common_utils.client.{method_name}:{comma separated parameters in square brackets}

"encoded_url": "CALL_EXTERNAL|common_utils.client:url_encode:['http://localhost:5000']|

CALL_EXTERNAL|random_data.client.{method_name}:{comma separated parameters in square brackets}

"address": "CALL_EXTERNAL|random_data.client:random_ip:[]|"

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.

Meta Variable File

{
    "user_password": {
        "val": 1234
    },
    "user_name": {
        "type": config,
        "val": "user.username"
        "fuzz_types": ["ascii"]
    },
    "user_token": {
        "type": "function",
        "val": "syntribos.extensions.identity:get_scoped_token_v3",
        "args": ["user"],
        "fuzz": false
    }
}

POST /user HTTP/1.1
X-Auth-Token: |user_token|

{
    "user": {
        "username": "|user_name|",
        "password": "|user_password|"
    }
}

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), SSL, Regex Denial of Service,
JSON Parser Depth Limit, and User defined.

In order to run a specific test, 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, see below:

::

    $ syntribos --config-file keystone.conf -t SQL run

To run SQL injection tests against the template body only, see below:

::

    $ syntribos --config-file keystone.conf -t SQL_INJECTION_BODY run

For all tests against HTTP headers only, see below:

::

    $ syntribos --config-file keystone.conf -t HEADERS run


============
Unit testing
============

To execute unit tests automatically, navigate to the ``syntribos`` root
directory and install the test requirements.

::

    $ pip install -r test-requirements.txt

Now, run the ``unittest`` as below:

::

    $ python -m unittest discover tests/unit -p "test_*.py"

If you have configured tox you could also run the following:

::

    $ tox -e py27
    $ tox -e py35

This will run all the unit tests and give you a result output
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 <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 cover

Anyone 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 Gerrit
described 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 all
breaking 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.