Auth

pom.xml

@@ -181,6 +181,16 @@
                             <targetPackage>com.webfuzzing.commons.report</targetPackage>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>auth.yaml</id>
+                        <goals>
+                            <goal>generate</goal>
+                        </goals>
+                        <configuration>
+                            <sourceDirectory>${basedir}/src/main/resources/wfc/schemas/auth.yaml</sourceDirectory>
+                            <targetPackage>com.webfuzzing.commons.auth</targetPackage>
+                        </configuration>
+                    </execution>
                 </executions>
             </plugin>
             <plugin>

release_notes.md

@@ -1,3 +1,6 @@
 
+# 0.0.2
+Support for auth
+
 # 0.0.1
 First draft version

src/main/resources/wfc/schemas/auth.yaml

@@ -11,12 +11,12 @@ properties:
     description: "List of authentication information for different users."
     type: array
     items:
-      $ref: "#/$def/AuthenticationInfo"
+      $ref: "#/$defs/AuthenticationInfo"
   authTemplate:
     description: "Optional authentication information template. This is used to avoid duplication in the auth list. \
                  Entries defined in the template will be applied to all elements in the auth list that do not specify them."
     allOf:
-    - $ref: "#/$def/AuthenticationInfo"
+    - $ref: "#/$defs/AuthenticationInfo"
     - type: object
   configs:
     description: "Optional map of configuration parameters, in the form key:value strings. \
@@ -26,9 +26,140 @@ properties:
     additionalProperties:
       type: string
 required: ["auth"]
-$def:
+$defs:
+#  TODO unfortunately, tools like jsonschema2pojo-maven-plugin have major limitations when dealing with enums.
+#  This is not created as a top-level class
+  HttpVerb:
+    type: string
+    enum:
+      - POST
+      - GET
+      - PATCH
+      - DELETE
+      - PUT
+  Header:
+    description: "HTTP header information"
+    type: object
+    properties:
+      name:
+        description: "The header name, e.g., 'Authorization'."
+        type: string
+      value:
+        description: "The value of the header"
+        type: string
+    required: ["name","value"]
   AuthenticationInfo:
     type: object
-
-
-
+    properties:
+      name:
+        description: "The name given to this authentication info. \
+                      This works as a unique id for this authentication configuration."
+        type: string
+      requireMockHandling:
+        description: "Specify that the authentication for this user requires setting up mock responses from an external service. \
+                      This will be done as part of the fuzzing, although only possible for white-box testing. \
+                      One consequence here is that, even if we provide correct auth info as input, then a request might still \
+                      fail due to unauthorized access if the fuzzing process does not properly set up these mocked responses in the API itself."
+        type: boolean
+      fixedHeaders:
+        description: "The headers needed for authentication. \
+                      This is used to represent cases in which auth info is static/fixed, e.g., \
+                      when passing an id or username/password through a HTTP header (and not \
+                      using for example a dynamically generated token from a login endpoint first)."
+        type: array
+        items:
+          $ref: "#/$defs/Header"
+      loginEndpointAuth:
+          $ref: "#/$defs/LoginEndpoint"
+    required: ["name"]
+  ###
+  LoginEndpoint:
+    description: "Used to represent the case in which a login endpoint is used to obtain the authentication credentials. \
+                      These can be cookies, or a token extracted from the login endpoint's response. \
+                      This token can then be added to an HTTP header in the following requests."
+    type: object
+    properties:
+      endpoint:
+        description: "The endpoint path (eg '/login') where to execute the login. \
+                      It assumes it is on same server of API.\
+                      If not, rather use 'externalEndpointURL'."
+        type: string
+      externalEndpointURL:
+        description: "If the login endpoint is on a different server, here can rather specify the full URL for it."
+        type: string
+      payloadRaw:
+        description: "The raw payload to send, as a string."
+        type: string
+      payloadUserPwd:
+        $ref: "#/$defs/PayloadUsernamePassword"
+      headers:
+        description: "HTTP headers needed when calling the login endpoint. \
+                      Username/password could be passed by headers instead of by the body payload."
+        type: array
+        items:
+          $ref: "#/$defs/Header"
+      verb:
+#        description: "The verb used to connect to the login endpoint. \
+#                     Most of the time, this will be a 'POST'."
+#        type: string
+#        enum:
+#            - POST
+#            - GET
+#            - PATCH
+#            - DELETE
+#            - PUT
+        $ref: "#/$defs/HttpVerb"
+        ## FIXME: unfortunately, plugin is not able to handle this... need new schema version with $ref not replacing everything
+#        description: "The verb used to connect to the login endpoint. \
+#                      Most of the time, this will be a 'POST'."
+#        allOf:
+#          - $ref: "#/$defs/HttpVerb"
+#          - type: string
+      contentType:
+        description: "Specify the format in which the payload is sent to the login endpoint. \
+                      A common example is 'application/json'."
+        type: string
+      token:
+        $ref: "#/$defs/TokenHandling"
+      expectCookies:
+        description: "Specify if we are expecting to get cookies from the login endpoint. \
+                      If so, a fuzzer can use those as auth info in following requests, instead of trying to extract \
+                      an auth token from the response payload."
+        type: boolean
+    required: ["verb"]
+  ###
+  TokenHandling:
+    description: "Specify how to extract token from response, and how to use it for auth in following requests. \
+                  Not needed if rather expect to get back a cookie."
+    type: object
+    properties:
+      extractFromField:
+        description: "How to extract the token from a JSON response, as such JSON could have few fields, possibly nested. \
+                      It is expressed as a JSON Pointer (RFC 6901)."
+        type: string
+      httpHeaderName:
+        description: "When sending a token in an HTTP header, specify to which header to add it (e.g., 'Authorization')."
+        type: string
+      headerPrefix:
+        description: " When sending out the obtained token in an HTTP header, specify if there should be any \ 
+                       prefix (e.g., 'Bearer ' or 'JWT '). If needed, make sure it has trailing space(s)."
+        type: string
+  ###
+  PayloadUsernamePassword:
+    description: "Payload with username and password information. \
+                  It will be automatically formatted in a proper payload based on content type."
+    type: object
+    properties:
+      username:
+        description: "The id of the user."
+        type: string
+      password:
+        description: "The password of the user, in plain-text. This must NOT be hashed."
+        type: string
+      usernameField:
+        description: "The name of the field in the body payload containing the username."
+        type: string
+      passwordField:
+        description: "The name of the field in the body payload containing the password"
+        type: string
+    required: ["username","usernameField","password","passwordField"]

src/main/resources/wfc/schemas/report.yaml

@@ -19,18 +19,18 @@ properties:
     format: date-time
     description: "The timestamp of when this report file was created."
   faults:
-    $ref: "#/$def/Faults"
+    $ref: "#/$defs/Faults"
 #### Unfortunately, there is no support for oneOf in jsonschema2pojo
 #  problem_details:
 #    type: object
 #    oneOf:
-#      - $ref: "#/$def/RESTReport"
+#      - $ref: "#/$defs/RESTReport"
 #      # TODO GraphQL, RPC and Web
   problem_details:
     type: object
     properties:
       rest:
-        $ref: "#/$def/RESTReport"
+        $ref: "#/$defs/RESTReport"
       # TODO GraphQL, RPC and Web
       # expressing that only 1 should be present is possible, but super-verbose and convoluted
   total_tests:
@@ -40,24 +40,24 @@ properties:
   test_file_paths:
     type: array
     items:
-      $ref: "#/$def/TestFilePath"
+      $ref: "#/$defs/TestFilePath"
     uniqueItems: true
     description: "The list of relative paths (compared to this document) of all the generated test suite files."
   test_cases:
     description: "Information on each generated test case."
     type: array
     items:
-      $ref: "#/$def/TestCase"
+      $ref: "#/$defs/TestCase"
   #OPTIONAL
   extra:
     description: "Extra, optional coverage information, collected by different tools."
     type: array
     items:
-      $ref: "#/$def/Coverage"
+      $ref: "#/$defs/Coverage"
 
 required: ["schema_version","tool_name","tool_version","creation_time","faults","problem_details","total_tests","test_file_paths","test_cases"]
 
-$def:
+$defs:
   OperationId:
     description: "A unique identifier for an operation. For example, in REST, it would be a HTTP endpoint, including 
                   verb, e.g., 'GET:/users/{id}'."
@@ -85,15 +85,15 @@ $def:
     type: object
     properties:
       endpoint_id:
-        $ref: "#/$def/OperationId"
+        $ref: "#/$defs/OperationId"
       test_case_id:
-        $ref: "#/$def/TestCaseId"
+        $ref: "#/$defs/TestCaseId"
       http_status:
         description: "As in a test case the same endpoint could be called more than once, here we report all of the 
         obtained HTTP status codes"
         type: array
         items:
-          $ref: "#/$def/HttpStatus"
+          $ref: "#/$defs/HttpStatus"
         minItems: 1
         uniqueItems: true
     required: ["endpoint_id","test_case_id","http_status"]
@@ -107,13 +107,13 @@ $def:
     type: object
     properties:
       operation_id:
-        $ref: "#/$def/OperationId"
+        $ref: "#/$defs/OperationId"
       test_case_id:
-        $ref: "#/$def/TestCaseId"
+        $ref: "#/$defs/TestCaseId"
       fault_categories:
         type: array
         items:
-          $ref: "#/$def/FaultCategoryId"
+          $ref: "#/$defs/FaultCategoryId"
         minItems: 1
         uniqueItems: true
     required: ["endpoint_id","test_case_id","fault_categories"]
@@ -130,22 +130,22 @@ $def:
         description: "Unique ids of all the endpoints in the tested API."
         type: array
         items:
-          $ref: "#/$def/OperationId"
+          $ref: "#/$defs/OperationId"
         uniqueItems: true
       covered_http_status:
         description: "List of which HTTP status codes were covered, based on endpoints."
         type: array
         items:
-          $ref: "#/$def/CoveredEndpoint"
+          $ref: "#/$defs/CoveredEndpoint"
     required: ["total_http_calls","endpoint_ids","covered_http_status"]
 
   TestCase:
     type: object
     properties:
       id:
-        $ref: "#/$def/TestCaseId"
+        $ref: "#/$defs/TestCaseId"
       file_path:
-        $ref: "#/$def/TestFilePath"
+        $ref: "#/$defs/TestFilePath"
       name:
         description: "The name of the test case, as it appears in the generated test file."
         type: string
@@ -171,7 +171,7 @@ $def:
         description: "Information on all the identified potential faults."
         type: array
         items:
-          $ref: "#/$def/FoundFault"
+          $ref: "#/$defs/FoundFault"
     required: ["total_number","found_faults"]
 
   Coverage:
@@ -183,7 +183,7 @@ $def:
       criteria:
         type: array
         items:
-          $ref: "#/$def/CoverageCriterion"
+          $ref: "#/$defs/CoverageCriterion"
     required: ["tool_name","criteria"]
 
   CoverageCriterion: