openapi.yaml

openapi: 3.1.0
info:
  title: PHP2Shell check
  version: "1"
  license:
    name: BSD-2-Clause
paths:
  /api/v1/check:
    post:
      summary: Check one website
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [url]
              properties:
                url:
                  type: string
                  description: A host name, an address or an http(s) URL.
                attested:
                  type: boolean
                  description: The visitor owns the site or may test it; adds bounded session-handling requests and, without a version, the phpinfo() requests. Each session request carries the invalid session ID as a cookie and as a form field. Session observations do not establish complete fixes for either CVE.
                refresh:
                  type: boolean
                  description: Run a fresh check when the cached result is at least a minute old, for example after patching.
      responses:
        "200":
          description: The verdict, cached when the host was checked within the cooldown.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Report" }
        "400":
          description: invalid_request, invalid_target, non_global_address or unresolvable.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "403":
          description: csrf_origin_mismatch.
        "413":
          description: request_too_large.
        "429":
          description: rate_limited, with Retry-After.
        "502":
          description: check_failed.
        "503":
          description: busy, with Retry-After.
        "504":
          description: check_timeout.
  /api/v1/version:
    get:
      summary: The build version
      responses:
        "200":
          description: The version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version: { type: string }
  /api/v1/info:
    get:
      summary: This instance's limits
      responses:
        "200":
          description: The version, the rate limit, the cooldown and the lab switch.
components:
  schemas:
    Report:
      type: object
      required: [target, verdict, confidence, summary, recommendations, oracle_run, local_check, checked_at, cached]
      properties:
        target: { type: string }
        verdict:
          type: string
          description: Current checks emit likelihoods or inconclusive results. The legacy vulnerable and patched codes remain reserved for compatibility.
          enum: [vulnerable, patched, likely_vulnerable, possibly_backported, eol_branch, likely_patched, inconclusive, no_php_signal, unreachable, inspection_blocked]
        confidence:
          type: string
          enum: [high, medium, low]
        summary: { type: string }
        php_version:
          type: object
          properties:
            raw: { type: string }
            major: { type: integer }
            minor: { type: integer }
            patch: { type: integer }
            suffix: { type: string }
            distro: { type: string }
        recommendations:
          type: array
          items: { type: string }
        oracle_run: { type: boolean }
        evidence:
          type: object
          properties:
            passive: { $ref: "#/components/schemas/PageEvidence" }
            discovery:
              type: array
              items: { $ref: "#/components/schemas/PageEvidence" }
            phpinfo_requests:
              type: array
              items: { $ref: "#/components/schemas/PageEvidence" }
            https_error:
              type: string
              description: Why an assumed HTTPS failed before the check used plain HTTP.
            oracle_requests:
              type: array
              items: { $ref: "#/components/schemas/SessionObservation" }
        local_check:
          type: array
          items: { type: string }
        checked_at: { type: string, format: date-time }
        cached: { type: boolean }
        refresh_at:
          type: string
          format: date-time
          description: On a cached result, when a refresh runs a fresh check.
    PageEvidence:
      type: object
      properties:
        final_url: { type: string, format: uri }
        status: { type: integer }
        error:
          type: string
          description: The request got no response.
        body_incomplete:
          type: boolean
          description: The body was cut short by a read error or the configured body cap; headers and partial passive evidence still count.
        read_error:
          type: string
          description: Why the body broke off.
        inspection_blocked: { type: string }
        server: { type: string }
        x_powered_by: { type: string }
        phpinfo_version: { type: string }
        phpinfo_settings:
          type: object
          additionalProperties: { type: string }
          description: Server API, display_errors, session.save_handler and session.upload_progress.enabled as a phpinfo() page shows them.
        server_signature: { type: string }
        front_layers:
          type: array
          items: { type: string }
          description: CDNs, firewalls and caches that showed themselves in the response.
        other_platforms:
          type: array
          items: { type: string }
          description: Non-PHP platforms whose documented defaults the answers carried.
        cookies:
          type: array
          items: { type: string }
        redirects:
          type: array
          items: { type: string, format: uri }
        redirect_not_followed: { type: string, format: uri }
        discovered_paths:
          type: array
          items: { type: string, format: uri }
        php_hints:
          type: array
          items: { type: string }
        fingerprints:
          type: array
          items: { $ref: "#/components/schemas/Fingerprint" }
    SessionObservation:
      type: object
      required: [url, response_complete, session_result, invalid_id, failed_read, failed_write]
      properties:
        url: { type: string, format: uri }
        status: { type: integer }
        response_complete: { type: boolean }
        error: { type: string }
        inspection_blocked: { type: string }
        session_result:
          type: string
          enum: [unpatched_path, patched_path, silent]
          description: A path-specific session-handling observation, not a CVE verdict. Blocked and 4xx or 5xx responses are silent. All three warnings count however the body ended; the first two alone need a complete body or 1 KiB of output after them. A patched_path does not establish a complete fix.
        invalid_id: { type: integer }
        failed_read: { type: integer }
        failed_write: { type: integer }
        lines:
          type: array
          items: { type: string }
    Fingerprint:
      type: object
      required: [technology, signal, scope, confidence, source, url]
      properties:
        technology: { type: string }
        signal: { type: string }
        scope:
          type: string
          enum: [declared, component, default_cookie]
        confidence:
          type: string
          enum: [medium, low]
        source: { type: string, format: uri }
        url: { type: string, format: uri }
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string }
            message: { type: string }