Add webhooks Open API Specification (#748)

* feat: add owasp validation rules

* chore: add validator package.json task and update GHA

* chore: ignore API lint rule - no property description

* feat: refine OWASP lint rules

* feat: add xero webhooks open api specification

* chore: update linting and workflows for xero-webhooks.yaml

Author: rpocklin

.github/workflows/lint.yml

@@ -8,7 +8,7 @@ jobs:
       - name: yaml-lint
         uses: ibiqlik/action-yamllint@v3
         with:
-          file_or_dir: xero_accounting.yaml xero_assets.yaml xero_bankfeeds.yaml xero_files.yaml xero-app-store.yaml xero-identity.yaml xero-payroll-au.yaml xero-payroll-nz.yaml xero-payroll-uk.yaml xero-projects.yaml
+          file_or_dir: xero_accounting.yaml xero_assets.yaml xero_bankfeeds.yaml xero_files.yaml xero-app-store.yaml xero-identity.yaml xero-payroll-au.yaml xero-payroll-nz.yaml xero-payroll-uk.yaml xero-projects.yaml xero-webhooks.yaml
           config_data: |
             extends: default
             rules:

.github/workflows/spectral-lint.yml

@@ -4,7 +4,13 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-      - name: spectral-lint
-        run: ./validator/scripts/validate-all.sh
+    - uses: actions/checkout@v3
+    - uses: actions/setup-node@v3
+    - name: Install yarn
+      run: npm install -g yarn
+    - name: yarn
+      working-directory: ./validator
+      run: yarn install --immutable
+    - name: spectral-lint
+      working-directory: ./validator
+      run: yarn lint

.gitignore

@@ -1,4 +1,6 @@
 .DS_Store
 
+node_modules
+
 # JetBrains generated files
 .idea

validator/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "xero-openapi-validator",
+  "version": "1.0.0",
+  "description": "Validation for Xero OpenAPI specifications using Spectral",
+  "type": "module",
+  "scripts": {
+    "lint": "spectral lint '../xero*.yaml'"
+  },
+  "dependencies": {
+    "@stoplight/spectral-cli": "^6.0.0",
+    "@stoplight/spectral-owasp-ruleset": "2.0.1"
+  }
+}

validator/scripts/validate-all.sh

@@ -1,32 +1,2 @@
-extends: ["spectral:oas", "./xero-spectral.yaml"]
-
-rules:
-  # Override default rules to be more lenient for existing Xero API specs
-
-  # Re-enabled: operation-description (produces warnings only - acceptable for documentation improvement)
-  # operation-description: off
-
-  # Disabled: info-description (xero_accounting.yaml missing description)
-  info-description: off
-
-  # Disabled: operation-tag-defined (many APIs use undeclared tags)
-  operation-tag-defined: off
-
-  # Disabled: no-$ref-siblings (xero_accounting.yaml uses this pattern with type field)
-  no-$ref-siblings: off
-
-  # Disabled: example validation rules (legacy string examples would cause many errors)
-  oas3-valid-media-example: off
-  oas3-valid-schema-example: off
-
-  # Re-enabled: oas3-unused-component (produces warnings only - helps identify unused schemas)
-  # oas3-unused-component: off
-
-  # Re-enabled: oas3-server-trailing-slash (produces warnings only - helps clean up URLs)
-  # oas3-server-trailing-slash: off
-
-  # Disabled: path-params (FileId/FolderId path conflicts in xero_files.yaml)
-  path-params: off
-
-  # Re-enabled: oas3-operation-security-defined (produces warnings only - helps identify security gaps)
-  # oas3-operation-security-defined: off
+extends:
+  - "./xero-spectral.yaml"

validator/spectral.yaml

@@ -1,3 +1,7 @@
+extends:
+  - "spectral:oas"                      # Base OpenAPI validation
+  - "@stoplight/spectral-owasp-ruleset" # OWASP API security ruleset
+
 rules:
   # Custom rules specific to Xero APIs
   xero-info-required-fields:
@@ -85,7 +89,7 @@ rules:
   xero-schema-properties-description:
     description: "Schema properties should have descriptions for better documentation"
     given: "$.components.schemas[*].properties[*]"
-    severity: info
+    severity: off
     then:
       field: "description"
       function: truthy
@@ -118,3 +122,40 @@ rules:
     then:
       field: "description"
       function: truthy
+  operation-description: off          # Disable operation description rule for now
+  operation-tags: off                 # Disable operation tags rule for now
+  oas3-schema: warn                  # Re-enable schema validation with reduced severity
+  info-contact:
+    severity: warn                    # Re-enabled with reduced severity
+    given: $.info.contact             # Scope: info.contact field
+    then:
+      function: truthy               # Ensure the field is truthy
+  info-license:
+    severity: warn                    # Re-enabled with reduced severity
+    given: $.info.license             # Scope: info.license field
+    then:
+      function: truthy               # Ensure the field is truthy
+
+
+  # OWASP Rules
+  owasp:api2:2023-no-http-basic: off  # Disable HTTP Basic authentication rule
+  owasp:api4:2023-string-limit: off   # Disable string length limit checks
+  owasp:api4:2023-array-limit: off    # Disable array size limit checks
+  owasp:api4:2023-integer-limit-legacy: off # Disable integer limit checks
+  owasp:api4:2023-rate-limit: off     # Disable rate limiting headers check
+  owasp:api2:2023-jwt-best-practices: off # Disable JWT best practices check
+  owasp:api8:2023-define-error-responses-401: off  # Disable missing 401 response rule
+  owasp:api8:2023-define-error-responses-500: off  # Disable missing 500 response rule
+  owasp:api4:2023-rate-limit-responses-429: off  # Disable missing 429 rate limit response rule
+  oas3-valid-media-example: off                 # Disable media example validation
+  owasp:api4:2023-integer-format: off           # Disable integer format validation
+  no-$ref-siblings: off                        # Disable $ref sibling validation
+  oas3-valid-schema-example: off               # Disable schema example validation
+  owasp:api9:2023-inventory-access: off          # Disable server audience declaration rule
+  owasp:api9:2023-inventory-environment: off   # Disable server environment declaration rule
+  owasp:api2:2023-short-lived-access-tokens: off # Disable short-lived access tokens rule
+  owasp:api8:2023-define-error-validation: off  # Disable missing error response validation rule
+  operation-tag-defined: off  # Disable operation tags defined in global tags rule
+  owasp:api4:2023-string-restricted: off  # Disable string restricted rule to address warnings
+  path-params: off  # Disable path parameter validation to address mapping key issues
+  owasp:api8:2023-define-cors-origin: off  # Disable CORS origin header requirement