openapi: "3.0.0"

info:
  description: "This is the API documentation for Patrowl Engines usage."
  version: "1.0.0"
  title: "Swagger API-REST for Patrowl Engines"
  contact:
    email: "getsupport@patrowl.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

servers: 
  - url: http://localhost:5001/engines/nmap/
  - url: http://localhost:5004/engines/ssllabs/
  - url: http://localhost:5005/engines/arachni/
  - url: http://localhost:5006/engines/owl_dns/
  - url: http://localhost:5007/engines/virustotal/
  - url: http://localhost:5008/engines/urlvoid/
  - url: http://localhost:5009/engines/cortex/
  - url: http://localhost:5012/engines/owl_leaks/
  - url: http://localhost:5013/engines/owl_code/
  - url: http://localhost:5014/engines/sslscan/
  
tags:
- name: "patrowl-engine"
  description: "SSLScan API documentation"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/Patrowl/PatrowlDocs"

paths:
  /:
    get:
      tags:
      - "patrowl-engine"
      summary: "Index page"
      description: "Return index page"
      operationId: "getDefaultPage"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  
  /liveness:
    get:
      tags:
      - "patrowl-engine"
      summary: "Liveness page"
      description: "Return liveness page"
      operationId: "getLivenessPage"
      responses:
        200:
          description: "successful operation"
          
  /readiness:
    get:
      tags:
      - "patrowl-engine"
      summary: "Readiness page"
      description: "Return liveness page"
      operationId: "getReadinessPage"
      responses:
        200:
          description: "successful operation"
          
  /test:
    get:
      tags:
      - "patrowl-engine"
      summary: "Test page"
      description: "Return test page"
      operationId: "getTestPage"
      responses:
        200:
          description: "successful operation"

  /reloadconfig:
    get:
      tags:
      - "patrowl-engine"
      summary: "Configuration reloading page"
      description: "Reload the configuration file."
      operationId: "reloadConfigurationPage"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /info:
    get:
      tags:
      - "patrowl-engine"
      summary: "Engine info page"
      description: "Return information on engine."
      operationId: "getInfoPage"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  
  /clean:
    get:
      tags:
      - "patrowl-engine"
      summary: "Clean all scans"
      description: "Clean all current scans."
      operationId: "CleanScansPage"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
   
  /clean/{scanId}:
    get:
      tags:
      - "patrowl-engine"
      summary: "Clean scan"
      description: "Clean scan identified by id."
      operationId: "CleanScanPage"
      parameters:
        - in: path
          name: scanId
          schema:
            type: integer
          required: true
          description: Numeric ID of the scan to clean
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
                
  /status:
    get:
      tags:
      - "patrowl-engine"
      summary: "Status on all scans"
      description: "Status all current scans."
      operationId: "StatusScansPage"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'              
  
  /status/{scanId}:
    get:
      tags:
      - "patrowl-engine"
      summary: "Status of a scan"
      description: "Status of a scan identified by id."
      operationId: "StatusScanPage"
      parameters:
        - in: path
          name: scanId
          schema:
            type: integer
          required: true
          description: Numeric ID of the scan to get status
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  
  /stopscans:
    get:
      tags:
      - "patrowl-engine"
      summary: "Stop all scans"
      description: "Stop all current scans."
      operationId: "StopScansPage"
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'              
  
  /stop/{scanId}:
    get:
      tags:
      - "patrowl-engine"
      summary: "Stop a scan"
      description: "Stop a scan identified by id."
      operationId: "StopScanPage"
      parameters:
        - in: path
          name: scanId
          schema:
            type: integer
          required: true
          description: Numeric ID of the scan to stop
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  
  /getfindings/{scanId}:
    get:
      tags:
      - "patrowl-engine"
      summary: "Get findings on finished scans"
      description: "Get findings on finished scans."
      operationId: "GetFindingPage"
      parameters:
        - in: path
          name: scanId
          schema:
            type: integer
          required: true
          description: Numeric ID of the scan to get findings
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Findings'
  
  /startscan:
    post:
      tags:
      - "patrowl-engine"
      summary: "Start a new scan"
      description: "Start a new scan."
      operationId: "StartScanPage"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanDefinition'
            
      responses:
        200:
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'              
components:
  schemas:
    ApiResponse:
      properties:
        status:
          type: string
        page:
          type: string
          
    Findings:
      type: array
      items:
        type: object
        properties:
          issue_id:
            type: integer
          type:
            type: string
          title:
            type: string
          description:
            type: string
          solution:
            type: string
          severity:
            type: string
            enum: ["info", "low", "medium", "high"]
          confidence:
            type: string
          raw:
            type: string
          target_addrs:
            type: array
            items:
              type: string
          target_proto:
            type: array
            items:
              type: string
          meta_links:
            type: array
            items:
              type: string
          meta_tags:
            type: array
            items:
              type: string
          meta_vuln_refs:
            type: object
            properties:
              cve:
                type: array
                items:
                  type: string
              cwe:
                type: array
                items:
                  type: string
              cpe:
                type: array
                items:
                  type: string
              bid:
                type: array
                items:
                  type: string
          meta_risk:
            type: object
            properties:
              cvss_vector:
                type: array
                items:
                  type: string
              cvss_base_score:
                type: array
                items:
                  type: string
              exploit_available:
                type: array
                items:
                  type: string
              exploitability_ease:
                type: array
                items:
                  type: string
              patch_publication_date:
                type: array
                items:
                  type: string
          timestamp:
            type: string
            format: date-time
          
    ScanDefinition:
      properties:
        scan_id:
          type: integer
          example: 1
        options:
          type: object
        assets:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: '3'
              value:
                type: string
                example: '8.8.8.8'
              criticity:
                type: string
                enum: ["low", "medium", "high"]
              datatype:
                type: string
                enum: ["ip", "ip-range", "ip-subnet", "fqdn", "domain", "url", "keyword", "person", "organisation", "path", "application"]

externalDocs:
  description: "Find out more about Patrowl"
  url: "https://github.com/Patrowl/PatrowlDocs"