Merge branch 'dev'

Author: danielonsecurity

.github/workflows/pylint.yml .github/workflows/lint.yml

@@ -18,6 +18,11 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install pylint
+        pip install flake8
+        pip install mypy
     - name: Analysing the code with pylint
       run: |
         pylint $(git ls-files 'raider/*.py')
+    - name: Analysing the code with flake8
+      run: |
+        flake8 'raider/'

.github/workflows/python-publish.yml

@@ -0,0 +1,12 @@
+name: "Sphinx docs build check"
+on:
+  [push]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "docs/"

.github/workflows/sphinx.yml

@@ -3,24 +3,16 @@
 exclude: ^docs/|^scripts/
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
+    rev: v4.3.0
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-yaml
   - repo: https://github.com/psf/black
-    rev: 21.9b0
+    rev: 22.6.0
     hooks:
     -   id: black
   - repo: https://github.com/PyCQA/isort
-    rev: 5.9.3
+    rev: 5.10.1
     hooks:
     -   id: isort
-  - repo: https://github.com/PyCQA/flake8
-    rev: 3.9.2
-    hooks:
-    -   id: flake8
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.910
-    hooks:
-    -   id: mypy

.pre-commit-config.yaml

@@ -11,35 +11,42 @@ object containing the definition of the request. This definition can
 contain :class:`Plugins <raider.plugins.Plugin>` whose value will be
 used when sending the HTTP request.
 
+There are two types of Flow, the regular one using the :class:`Flow
+<raider.flow.Flow>` class, and the authentication Flows using the
+:class:`AuthFlow <raider.flow.AuthFlow>` class. Only difference is
+that AuthFlow ones are treated as changing the authentication state
+while the regular ones don't. Use AuthFlow to define the process
+necessary to reach from unauthenticated state to authenticated
+one. Use regular Flows for any other requests you want to test using
+Raider.
+
 .. automodule:: raider.flow
    :members:
 
 
 Examples
 --------
 
-Create the variable ``initialization`` with the Flow. It'll send a
-request to the :ref:`_base_url <var_base_url>` using the path
-``admin/``. If the HTTP response code is 200 go to next stage
-``login``.
+Create the variable ``initialization`` with the AuthFlow. It'll send a
+GET request to ``https://example.com/admin/``. If the HTTP response
+code is 200 go to next stage ``login``.
 
 .. code-block:: hylang
 
     (setv initialization
-          (Flow
-            :name "initialization"
+          (AuthFlow
             :request (Request
                        :method "GET"
-                       :path "admin/")
+                       :url "https://example.com/admin/")
             :operations [(Http
                            :status 200
                            :action (NextStage "login"))]))
     
 
-Define Flow ``login``. It will send a POST request to
-``https://www.example.com/admin/login`` with the username and the
-password in the body. Extract the cookie ``PHPSESSID`` and store it in
-the ``session_id`` plugin. If server responds with HTTP 200 OK, print
+Define AuthFlow ``login``. It will send a POST request to
+``https://example.com/admin/login`` with the username and the password
+in the body. Extract the cookie ``PHPSESSID`` and store it in the
+``session_id`` plugin. If server responds with HTTP 200 OK, print
 ``login successfully``, otherwise quit with the error message ``login
 error``.
 
@@ -50,8 +57,7 @@ error``.
     (setv session_id (Cookie "PHPSESSID"))
 
     (setv login
-          (Flow
-            :name "login"
+          (AuthFlow
             :request (Request
                        :method "POST"
                        :url "https://www.example.com/admin/login"
@@ -78,12 +84,39 @@ authentication (MFA)>` was enabled and the ``multi_factor`` :term:`stage`
 needs to run next. Otherwise, try to log in again. Here the password
 is asked from the user by a :class:`Prompt <raider.plugins.Prompt>`.
 
+Also define the regular Flow named ``get_nickname`` to extract the
+username of the logged in user. This request doesn't affect the
+authentication state which is why Flow is used instead of AuthFlow.
+
 .. code-block:: hylang
 
+    ;; Gets `username` from active user's object defined in `users`.
     (setv username (Variable "username"))
+
+    ;; Gets the password by manual input.
     (setv password (Prompt "password"))
+
+    ;; Gets `PHPSESSID` from the cookie.
     (setv session_id (Cookie "PHPSESSID"))
-    
+
+    ;; Gets the OTP code by manual input.
+    (setv mfa_code (Prompt "OTP code"))
+
+    ;; Extract nickname from the HTML code. It looks for a tag like this:
+    ;; <input id="nickname" value="admin">
+    ;; and returns `admin`.
+    (setv nickname
+          (Html
+            :name "nickname"
+            :tag "input"
+            :attributes
+            {:id "nickname"}
+            :extract "value"))
+
+    ;; Extracts the name of the CSRF token from HTML code. It looks
+    ;; for a tag similar to this:
+    ;; <input name="0123456789" value="0123456789012345678901234567890123456789012345678901234567890123" type="hidden">
+    ;; and returns 0123456789.
     (setv csrf_name
           (Html
             :name "csrf_name"
@@ -93,7 +126,11 @@ is asked from the user by a :class:`Prompt <raider.plugins.Prompt>`.
              :value "^[0-9A-Fa-f]{64}$"
              :type "hidden"}
             :extract "name"))
-    
+
+    ;; Extracts the value of the CSRF token from HTML code. It looks
+    ;; for a tag similar to this:
+    ;; <input name="0123456789" value="0123456789012345678901234567890123456789012345678901234567890123" type="hidden">
+    ;; and returns 0123456789012345678901234567890123456789012345678901234567890123.    
     (setv csrf_value
           (Html
             :name "csrf_value"
@@ -104,24 +141,52 @@ is asked from the user by a :class:`Prompt <raider.plugins.Prompt>`.
              :type "hidden"}
             :extract "value"))
 
-
+    ;; Defines the `login` AuthFlow. Sends a POST request to
+    ;; https://example.com/login.php. Use the username, password
+    ;; and both the CSRF name and values in the POST body.
+    ;; Extract the new CSRF values, and moves to the next stage
+    ;; if HTTP response is 200.
     (setv login
-          (Flow
-            :name "login"
+          (AuthFlow
             :request (Request
                        :method "POST"
-                       :path "/login.php"
+                       :url "https://example.com/login.php"
                        :cookies [session_id]
                        :data
-                       {"open" "login"
-                        "action" "customerlogin"
-                        "password" password
+                       {"password" password
                         "username" username
-                        "redirect" "myaccount"
                         csrf_name csrf_value})
             :outputs [csrf_name csrf_value]
             :operations [(Http
                            :status 200
                            :action (NextStage "multi_factor")
                            :otherwise (NextStage "login"))]))
+
+    ;; Defines the `multi_factor` AuthFlow. Sends a POST request to
+    ;; https://example.com/login.php. Use the username, password,
+    ;; CSRF values, and the MFA code in the POST body.
+    (setv multi_factor
+          (AuthFlow
+            :request (Request
+                       :method "POST"
+                       :url "https://example.com/login.php"
+                       :cookies [session_id]
+                       :data
+                       {"password" password
+                        "username" username
+			"otp" mfa_code
+                        csrf_name csrf_value})
+            :outputs [csrf_name csrf_value]))
+
+    ;; Extracts the nickname and print it. Send a GET request to
+    ;; https://example.com/settings.php and extract the nickname
+    ;; from the HTML response.
+    (setv get_nickname
+          (Flow
+            :request (Request
+                       :method "GET"
+                       :url "https://example.com/settings.php"
+                       :cookies [session_id])
+            :outputs [nickname]
+	    :operations [(Print nickname)]))
 		

docs/dev/flows.rst

@@ -45,10 +45,9 @@ Basic
 Variable
 ++++++++
 
-Use this when the value of the plugin should be extracted from the
-user data. At the moment only ``username`` and ``password`` are
-working. Future versions will allow adding and accessing arbitrary
-data from the users.
+The Variable plugin extracts the value of a variable.
+
+.. autoclass:: Variable
 
 Example:
 
@@ -64,8 +63,7 @@ Example:
 Prompt
 ++++++
 
-Prompt plugin should be used when the information is not known in
-advance, for example when receiving the SMS code.
+The prompt plugin accepts user input mid-flow.
 
 Example:
 
@@ -81,7 +79,7 @@ Example:
 Cookie
 ++++++
 
-Use Cookie plugin to extract and set new cookies:
+The cookie plugin extracts and sets new cookies.
 
 Example:
 
@@ -98,9 +96,7 @@ Example:
 Header
 ++++++
 
-Use Header plugin to extract and set new headers. It also allows
-easier setup for basic and bearer authentication using the provided
-classmethods.
+The Header plugin extracts and sets new headers.
 
 Example:
 
@@ -122,12 +118,11 @@ Example:
 .. autoclass:: Header
    :members:	       
 
-
-
 File
 ++++
 
-TODO
+The File plugin sets the plugin's value to the contents of a provided file
+and allows string substitution within the content.
 
 Example:
 
@@ -140,8 +135,7 @@ Example:
 Command
 +++++++
 
-Use Command plugin if you want to extract information using a shell
-command.
+The Command plugin runs shell commands and extracts their output. 
 
 Example:
 
@@ -160,9 +154,7 @@ Example:
 Regex
 +++++
 
-Use Regex plugin if the data you want extracted can be easily
-identified with a regular expression. The string matched in between
-``(`` and ``)`` will be stored as the plugin's value.
+The Regex plugin extracts a matched expression from a provided string.
 
 Example:
 
@@ -183,12 +175,7 @@ Example:
 Html
 ++++
 
-Use the Html plugin when the data you want can be easily extracted by
-parsing HTML tags. Create a new plugin by giving it a name, the tag
-where the information is located, some attributes to identify whether
-the tag is the right one, and the name of the tag attribute you want
-to extract. The attributes are created as a dictionary, and its values
-can be regular expressions.
+The Html plugin extracts tags matching attributes specified by the user.
 
 Example:
 
@@ -213,6 +200,8 @@ Example:
 Json
 ++++
 
+The Json plugin extracts fields from JSON tables.
+
 .. autoclass:: Json
    :members: