openapi: "3.0.3"
info:
  title: "Scanner"
  description: "
    # Authentication

    The API supports two kinds of authentication methods:

    - API Key

    - Certificates


    The authentication modes are set within a configuration file or via the argument list, when starting the server.

    The authentication is required for each request except for a HEAD request.

    ## API Key

    An API key is a token that the client provides when doing API requests and are used to authorize access.
    The `X-API-KEY` must be in the header.


    <!--More details about this method follows with its implementation.-->


    ## Certificates

    This option uses [X.509](https://en.wikipedia.org/wiki/X.509), based on CA to verify derived certificates to allow access.


    <!--More details about this method follows with its implementation.-->
    "
  contact:
    name: "Greenbone AG"
    url: "https://www.greenbone.net/"
  license:
    name: "GPL-2.0-or-later"
    url: "https://spdx.org/licenses/GPL-2.0-or-later.html"
  version: "0.1"
servers:
  - url: /
tags:
  - name: general
    description: General requests
  - name: scan
    description: Scan resource
  - name: feed
    description: Feed related
paths:
  /health:
    head:
      description: "Get the response header. It contains the API version, feed version and available authentication methods."
      operationId: "head_health"
      tags:
        - "general"
      responses:
        "200":
          headers:
            api-version:
              description: "Comma separated list of available API versions"
              schema:
                type: "string"
            feed-version:
              description: "The version of the VT feed"
              schema:
                type: "string"
            authentication:
              description: "Supported authentication methods"
              schema:
                type: "string"
          description: "Authenticated and authorized"
  /health/alive:
    get:
      description: "Get application's health information"
      operationId: "get_health_alive"
      tags:
        - "health"
      responses:
        "200":
          description: "Ok"

  /health/ready:
    get:
      description: "Get application's health information"
      operationId: "get_health_ready"
      tags:
        - "health"
      responses:
        "200":
          description: "Ok"
        "503":
          description: "Service Unavailable"
  /health/started:
    get:
      description: "Get application's health information"
      operationId: "get_health_started"
      tags:
        - "health"
      responses:
        "200":
          description: "Ok"

  /notus:
    head:
      description: "Get the response header. It contains the API version, feed version and available authentication methods."
      operationId: "head_notus"
      tags:
        - "general"
      responses:
        "200":
          headers:
            api-version:
              description: "Comma separated list of available API versions"
              schema:
                type: "string"
            feed-version:
              description: "The version of the VT feed"
              schema:
                type: "string"
            authentication:
              description: "Supported authentication methods"
              schema:
                type: "string"
          description: "Authenticated and authorized"
    get:
      description: "Get Notus supported OS products"
      operationId: "get_notus"
      tags:
        - "notus"
      responses:
        "200":
          description: "Ok"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  type: "string"
              examples:
                schema:
                  description: "Schema of supported OS products"
                get notus products:
                  $ref: "#/components/examples/notus_products"

  /notus/{os}:
    post:
      description: "Runs Notus with the given package list for the given OS"
      operationId: "notus_run"
      tags:
        - "notus"
      parameters:
        - $ref: "#/components/parameters/NotusOS"
      requestBody:
        description: "Run Notus."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotusPkgList"
            examples:
              schema:
                description: "Schema of package list"
              create simple scan:
                $ref: "#/components/examples/notus_simple"
      responses:
        "200":
          description: "A list of results"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotusResult"
              examples:
                schema:
                  description: "Schema of a list of results response"
                get results:
                  $ref: "#/components/examples/notus_results"
        "400":
          description: "Bad request body"
        "404":
          description: "Scan not found"
        "406":
          description: "Unable to perform action because of the current scan status"
        "501":
          description: "Action not supported"

  /scans:
    head:
      description: "Get the response header. It contains the API version, feed version and available authentication methods."
      operationId: "get_info_auth"
      tags:
        - "general"
      responses:
        "204":
          headers:
            api-version:
              description: "Comma separated list of available API versions"
              schema:
                type: "string"
            feed-version:
              description: "The version of the VT feed"
              schema:
                type: "string"
            authentication:
              description: "Supported authentication methods"
              schema:
                type: "string"
          description: "Authenticated and authorized"
        "401":
          headers:
            api-version:
              description: "Comma separated list of available API versions"
              schema:
                type: "string"
            feed-version:
              description: "The version of the VT feed"
              schema:
                type: "string"
            authentication:
              description: "Supported authentication methods"
              schema:
                type: "string"
          description: "Unauthorized. Required or invalid client certificates"
    post:
      description: "This request just creates the scan. It can be started afterwards with the scan_action request."
      operationId: "create_scan"
      tags:
        - "scan"
      requestBody:
        description: "Scan to add"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScanReq"
            examples:
              schema:
                description: "Schema of a Scan."
              create simple scan:
                $ref: "#/components/examples/scan_simple"
              create complex scan:
                $ref: "#/components/examples/scan_full_req"
      responses:
        "201":
          description: "Scan created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScanID"
              examples:
                created scan:
                  $ref: "#/components/examples/scan_id"
        "400":
          description: "Bad Request body"
        "403":
          description: "ScanID already in use"

  /scans/preferences:
    get:
      description: "Get all preferences available for a scan. These can be set, when creating a scan via scan_preferences."
      operationId: "get_preferences"
      tags:
        - "scan"
      responses:
        "200":
          description: "Get Preferences"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Preferences"
              examples:
                preferences:
                  $ref: "#/components/examples/preferences"

  /scans/{id}:
    get:
      description: "Get a scan from the scan manager."
      operationId: "get_scan"
      tags:
        - "scan"
      parameters:
        - $ref: "#/components/parameters/ScanID"
      responses:
        "200":
          description: "Get Scan"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScanResp"
              examples:
                scan:
                  $ref: "#/components/examples/scan_full_resp"

        "404":
          description: "Scan not found"
    post:
      description: "Perform an action to a scan."
      operationId: "scan_action"
      tags:
        - "scan"
      parameters:
        - $ref: "#/components/parameters/ScanID"
      requestBody:
        description: "Action to perform."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScanAction"
            examples:
              start scan:
                $ref: "#/components/examples/scan_action_start"
              stop scan:
                $ref: "#/components/examples/scan_action_stop"
      responses:
        "204":
          description: "Action performed"
        "400":
          description: "Bad request body"
        "404":
          description: "Scan not found"
        "406":
          description: "Unable to perform action because of the current scan status"
        "501":
          description: "Action not supported"
    delete:
      description: "Delete a scan from the scan manager."
      operationId: "delete_scan"
      tags:
        - "scan"
      parameters:
        - $ref: "#/components/parameters/ScanID"
      responses:
        "204":
          description: "Scan deleted"
        "404":
          description: "Scan not found"
        "406":
          description: "A running scan cannot be deleted"

  /scans/{id}/results:
    get:
      description: "Get results from a scan."
      operationId: "get_results"
      tags:
        - "scan"
      parameters:
        - $ref: "#/components/parameters/ScanID"
        - name: range
          in: query
          description: "Get a range of results (e.g. `0-12`).
            In case only a single number is given (e.g. `13`), all available results from this index on are returned.
            If the scan is still running, new results will occur and must be collected with new request starting from the last processed index.
            If no results are in the given range, an empty array is returned."
          required: false
          schema:
            type: "string"
      responses:
        "200":
          description: "A list of results"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/Result"
              examples:
                schema:
                  description: "Schema of a list of results response"
                get results 0-3:
                  $ref: "#/components/examples/scan_results"
        "400":
          description: "Bad range format"
        "404":
          description: "Scan not found"
        "406":
          description: "A scan, that has not started, does not contain results"

  /scans/{id}/results/{rid}:
    get:
      description: "Get a specific result from the scan."
      operationId: "get_result"
      tags:
        - "scan"
      parameters:
        - $ref: "#/components/parameters/ScanID"
        - $ref: "#/components/parameters/ResultID"
      responses:
        "200":
          description: "The requested result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
              examples:
                schema:
                  description: "Schema of a result"
                get result 3:
                  $ref: "#/components/examples/scan_result"
                host detail:
                  $ref: "#/components/examples/host_detail"
        "404":
          description: "Result or Scan not found"
        "406":
          description: "A scan that has not started, cannot contain results"

  /scans/{id}/status:
    get:
      description: "Get the current status of a scan."
      operationId: "get_scan_status"
      tags:
        - "scan"
      parameters:
        - $ref: "#/components/parameters/ScanID"
      responses:
        "200":
          description: "The requested status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
              examples:
                schema:
                  description: "Schema of a status response."
                status of a stored scan:
                  $ref: "#/components/examples/scan_status_stored"
                status of a running scan:
                  $ref: "#/components/examples/scan_status_running"
                status of a succeeded scan:
                  $ref: "#/components/examples/scan_status_success"
                status of a failed scan:
                  $ref: "#/components/examples/scan_status_fail"
        "404":
          description: "Scan not found"

  /vts:
    head:
      description: "Get the response header. It contains the API version, feed version and available authentication methods."
      operationId: "head_vts"
      tags:
        - "general"
      responses:
        "200":
          headers:
            api-version:
              description: "Comma separated list of available API versions"
              schema:
                type: "string"
            feed-version:
              description: "The version of the VT feed"
              schema:
                type: "string"
            authentication:
              description: "Supported authentication methods"
              schema:
                type: "string"
          description: "Authenticated and authorized"
    get:
      description: "Get a Identifier list of all VTs that are available to the scanner."
      operationId: "get_vts"
      tags:
        - "feed"
      responses:
        "200":
          description: "A list of available VTs."
          content:
            application/json:
              schema:
                type: "array"
                items:
                  type: "string"
              examples:
                list of OIDs:
                  $ref: "#/components/examples/list_of_oids"
        "503":
          description: "The list of OIDs is currently updated. Please try again later."

components:
  parameters:
    ScanID:
      name: id
      in: path
      description: "ID of a Scan"
      required: true
      schema:
        type: "string"
    ResultID:
      name: rid
      in: path
      description: "ID of a Result"
      required: true
      schema:
        type: "string"
    NotusOS:
      name: os
      in: path
      description: "Operative System"
      required: true
      schema:
        type: "string"

  schemas:
    ScanID:
      description: "A scan ID to identify a scan."
      type: "string"

    ScanReq:
      description: "Model representing a scan request."
      type: "object"
      properties:
        target:
          $ref: "#/components/schemas/Target"
        scan_preferences:
          description: "Overwrite the default settings of the Scanner."
          type: "array"
          items:
            $ref: "#/components/schemas/ScannerPreference"
        vts:
          type: "array"
          description: "A collection of VTs, which are run for the given target."
          items:
            $ref: "#/components/schemas/VT"
      required:
        - target
        - vts

    NotusPkgList:
      description: "List of packages installed in the target"
      type: "array"
      items:
        description: "Package"
        type: "string"
      required:
        - package_list

    ScanResp:
      description: "Model representing a scan response."
      type: "object"
      properties:
        scan_id:
          $ref: "#/components/schemas/ScanID"
        target:
          $ref: "#/components/schemas/Target"
        scan_preferences:
          description: "Overwrite the default settings of the Scanner."
          type: "array"
          items:
            $ref: "#/components/schemas/ScannerPreference"
        vts:
          type: "array"
          description: "A collection of VTs, which are run for the given target."
          items:
            $ref: "#/components/schemas/VT"
      required:
        - target
        - vts

    Target:
      description: "A target is a list of hosts to scan, including their UDP and TCP ports. Additionally for further access to the systems credentials can be given."
      type: "object"
      properties:
        hosts:
          description: "A list of hosts."
          type: "array"
          items:
            description: "Contains either an IPv4, IPv6, IPv4 range, IPv6 range, IPv4 CIDR, IPv6 CIDR or hostname."
            type: "string"
        excluded_hosts:
          description: "A list of excluded hosts."
          type: "array"
          items:
            description: "Contains either an IPv4, IPv6, IPv4 range, IPv6 range, IPv4 CIDR, IPv6 CIDR or hostname."
            type: "string"
        ports:
          description: "A list of ports."
          type: "array"
          items:
            $ref: "#/components/schemas/PortRange"
        credentials:
          description: "A list of credentials used for further access to a target system."
          type: "array"
          items:
            $ref: "#/components/schemas/Credential"
        alive_test_ports:
          description: "Dedicated port list for alive detection. Used for TCP-SYN and TCP-ACK ping when Boreas is enabled."
          type: "array"
          items:
            $ref: "#/components/schemas/PortRange"
        alive_test_methods:
          description: "List of alive test to be performed against the target. Can be one or a combination of icmp, tcp_syn, tcp_ack, arp, consider_alive methods"
          type: "array"
          items:
            $ref: "#/components/schemas/AliveTestMethod"
        reverse_lookup_unify:
          description: "If multiple IP addresses resolve to the same DNS name the DNS name will only get scanned once."
          type: "boolean"
        reverse_lookup_only:
          description: "Only scan IP addresses that can be resolved into a DNS name."
          type: "boolean"
      required:
        - hosts
        - ports

    AliveTestMethod:
      description: "Alive test method to be performed against the target"
      type: "string"
      enum:
        - icmp
        - tcp_syn
        - tcp_ack
        - arp
        - consider_alive

    PortRange:
      description: "A port range for either UDP or TCP ports"
      type: "object"
      properties:
        protocol:
          description: "The protocol for the port range. If missing the port range is applied for UDP and TCP."
          type: "string"
          enum:
            - udp
            - tcp
        range:
          type: "array"
          description: "A list of ranges"
          items:
            type: "object"
            properties:
              start:
                type: "number"
                description: "The inclusive start port. When end is not set only the start port is used"
              end:
                type: "number"
                description: "The inclusive end port."
      required:
        - range

    Credential:
      description: "Data for authentication for a target system."
      type: "object"
      properties:
        service:
          description: "The service used for authentication."
          type: "string"
          enum:
            - ssh
            - smb
            - esxi
            - snmp
            - krb5
        port:
          description: "The port the authentication service is running."
          type: "integer"
          format: "int32"
        up:
          $ref: "#/components/schemas/UP"
        krb5:
          $ref: "#/components/schemas/KRB5"

        usk:
          $ref: "#/components/schemas/USK"
        snmp:
          $ref: "#/components/schemas/SNMP"

    UP:
      description: "Authentication via Username and Password."
      type: "object"
      properties:
        username:
          description: "Username for authentication."
          type: "string"
        password:
          description: "Password for authentication."
          type: "string"
        privilege_username:
          description: "Privilege username for authentication."
          type: "string"
        privilege_password:
          description: "Privilege password for authentication."
          type: "string"
      required:
        - username

    KRB5:
      description: "Authentication via Kerberos GSA."
      type: "object"
      properties:
        username:
          description: "Username for authentication."
          type: "string"
        password:
          description: "Password for authentication."
          type: "string"
        realm:
          description: "Realm to be used by KRB5"
          type: "string"
        kdc:
          description: "KDC to be defined within the realm."
          type: "string"
      required:
        - username
        - password
        - realm
        - kdc

    USK:
      description: "Authentication via Username and Security Key."
      type: "object"
      properties:
        username:
          description: "Username for authentication."
          type: "string"
        password:
          description: "Password for Security Key."
          type: "string"
        private:
          description: "SSH private key."
          type: "string"
        privilege_username:
          description: "Privilege username for authentication."
          type: "string"
        privilege_password:
          description: "Privilege password for authentication."
          type: "string"
      required:
        - username
        - private

    SNMP:
      description: "Authentication via SNMP."
      type: "object"
      properties:
        username:
          description: "Username for SNMP authentication."
          type: "string"
        password:
          description: "Password for SNMP authentication."
          type: "string"
        community:
          description: "Community string for SNMP authentication."
          type: "string"
        auth_algorithm:
          description: "Algorithm for SNMP authentication."
          type: "string"
          enum:
            - md5
            - sha1
        privacy_password:
          description: "Privacy Password for SNMP authentication."
          type: "string"
        privacy_algorithm:
          description: "Algorithm used for encrypting privacy password."
          type: "string"
          enum:
            - aes
            - des

    ScannerPreference:
      description: "Consists of a preference ID and its value."
      type: "object"
      properties:
        id:
          description: "ID of the preference to set."
          type: "string"
        value:
          description: "Value of the preference."
          type: "string"
      required:
        - value
        - id

    Parameter:
      description: "Consists of a parameter ID and its value."
      type: "object"
      properties:
        id:
          description: "ID of the parameter to set."
          type: "integer"
          format: "int32"
        value:
          description: "Value of the parameter."
          type: "string"
      required:
        - value
        - id

    VT:
      description: "A single VT and its parameters."
      type: "object"
      properties:
        oid:
          description: "The identifier for a VT"
          type: "string"
        parameters:
          description: "A list of parameters for the VT. In case a VT has parameters but these are not set here, then the defaults will be applied. A default exists for any parameter."
          type: "array"
          items:
            $ref: "#/components/schemas/Parameter"

    NotusResult:
      description: "A dictionary of Notus results, where the key is an OID corresponding to the advisory and the value is a list of found vulnerable packages."
      type: "object"
      additionalProperties:
        type: "array"
        items:
          $ref: "#/components/schemas/NotusVulnPkgs"

    NotusVulnPkgs:
      description: "A vulnerable package"
      type: "object"
      properties:
        name:
          description: "Name of the vulnerable package"
          type: "string"
        installed_version:
          description: "Version installed of the vulnerable package"
          type: "string"
        fixed_version:
          oneOf:
            - $ref: "#/components/schemas/FixedPackage"
            - $ref: "#/components/schemas/FixedRange"
    FixedPackage:
      description: "A fixed package"
      type: "object"
      properties:
        version:
          description: "Version of the fixed package"
          type: "string"
        specifier:
          description: "Specifier of the fixed package"
          type: "string"
          enum:
            - ">"
            - ">="
            - "<"
            - "<="
            - "="
    FixedRange:
      description: "A fixed range. The start version is inclusive and the end version exclusive"
      type: "object"
      properties:
        start:
          description: "Start version of the fixed range"
          type: "string"
        end:
          description: "End version of the fixed range"
          type: "string"
    Result:
      description: "A result of a Scan"
      type: "object"
      properties:
        id:
          description: "An ID, which is unique for the scan. It is auto incremental and starts at 0 for the first result."
          type: "integer"
          format: "int32"
        type:
          description: "The type of the result."
          type: "string"
          enum:
            - alarm
            - log
            - error
            - host_start
            - host_stop
            - host_detail
        ip_address:
          description: "The IPv4 or IPv6 of the target the result was found."
          type: "string"
        hostname:
          description: "The hostname of the target the result was found."
          type: "string"
        oid:
          description: "The identifier of the VT in which found the result."
          type: "string"
        port:
          description: "The port that was used to find the result."
          type: "integer"
          format: "int32"
        protocol:
          description: "The protocol that was used to find the result, corresponding to the port."
          type: "string"
          enum:
            - udp
            - tcp
        message:
          description: "Additional information about the result."
          type: "string"
        detail:
          description: "The detail object is only used for results of type host_detail. It contains information about a scanned hosted such as hardware information, architecture and many more."
          type: "object"
          properties:
            name:
              description: "descriptive name of the detail"
              type: "string"
            value:
              description: "value of the host detail"
              type: "string"
            source:
              description: "source of the host detail"
              type: "object"
              properties:
                type:
                  description: "type of the source, e.g. nvt"
                  type: "string"
                name:
                  description: "descriptive name of the source, in case of type nvt this is its OID"
                  type: "string"
                description:
                  description: "Optional information about the detection, could contain how the data actually was collected."
                  type: "string"
              required:
                - type
                - name
          required:
            - name
            - value
            - source

      required:
        - type

    Status:
      description: "The status of a scan"
      type: "object"
      properties:
        start_time:
          description: "A UNIX time format describing when the scan started."
          type: "integer"
          format: "int32"
        end_time:
          description: "A UNIX time format describing when the scan ended."
          type: "integer"
          format: "int32"
        status:
          description: "In which phase the scan is currently in."
          type: "string"
          enum:
            - stored
            - requested
            - running
            - stopped
            - failed
            - succeeded
        host_info:
          $ref: "#/components/schemas/HostInfo"
      required:
        - status

    HostInfo:
      description: "Information about the progress for each host of the scan."
      type: "object"
      properties:
        all:
          description: "The number of host in the target of the scan."
          type: "integer"
          format: "int32"
        excluded:
          description: "The number of hosts excluded from the target if the scan."
          type: "integer"
          format: "int32"
        dead:
          description: "The number of host detected as not reachable."
          type: "integer"
          format: "int32"
        alive:
          description: "The number of hosts that are reachable and will be scanned."
          type: "integer"
          format: "int32"
        queued:
          description: "The number of hosts that are waiting to be scanned."
          type: "integer"
          format: "int32"
        finished:
          description: "The number hosts that are finished with scanning."
          type: "integer"
          format: "int32"
        scanning:
          description: "The IP Addresses of the currently scanned hosts."
          type: "array"
          items:
            type: "string"

      required:
        - all
        - excluded
        - dead
        - alive
        - queued
        - finished

    ScanAction:
      description: "An action to perform on a scan"
      type: "object"
      properties:
        action:
          description: "The action to perform"
          type: "string"
          enum:
            - start
            - stop
      required:
        - "action"

    Preferences:
      description: "List of preferences available"
      type: "array"
      items:
        type: "object"
        properties:
          id:
            description: "ID of the preference"
            type: "string"
          type:
            description: "Type of the preference"
          name:
            description: "Display name for the preference"
            type: "string"
          description:
            description: "Description of the preference"
            type: "string"
          default:
            description: "Default value for scans"
            type: "string"
          values:
            description: "Allowed values"
            type: "string"

  examples:
    scan_simple:
      description: "A simple example for creating a scan."
      value:
        {
          "target":
            {
              "hosts": ["127.0.0.1"],
              "ports": [{ "range": [{ "start": 22 }] }],
            },
          "vts": [{ "oid": "1.3.6.1.4.1.25623.1.0.10267" }],
        }
    scan_full_req:
      description: "A complex example for creating a scan, that uses all available fields."
      value:
        {
          "target":
            {
              "hosts":
                [
                  "127.0.0.1",
                  "192.168.0.1-15",
                  "10.0.5.0/24",
                  "::1",
                  "2001:db8:0000:0000:0000:0000:0000:0001-00ff",
                  "2002::1234:abcd:ffff:c0a8:101/64",
                  "examplehost",
                ],
              "excluded_hosts": ["192.168.0.14"],
              "ports":
                [
                  {
                    "protocol": "udp",
                    "range": [{ "start": 22 }, { "start": 1024, "end": 1030 }],
                  },
                  { "protocol": "tcp", "range": [{ "start": 24, "end": 30 }] },
                  { "range": [{ "start": 100, "end": 1000 }] },
                ],
              "credentials":
                [
                  {
                    "service": "ssh",
                    "port": 22,
                    "usk":
                      {
                        "username": "user",
                        "password": "pw",
                        "private": "ssh-key...",
                      },
                  },
                  {
                    "service": "smb",
                    "up": { "username": "user", "password": "pw" },
                  },
                  {
                    "service": "snmp",
                    "snmp":
                      {
                        "username": "user",
                        "password": "pw",
                        "community": "my_community",
                        "auth_algorithm": "md5",
                        "privacy_password": "priv_pw",
                        "privacy_algorithm": "aes",
                      },
                  },
                ],
              "alive_test_ports":
                [
                  { "protocol": "tcp", "range": [{ "start": 1, "end": 100 }] },
                  { "range": [{ "start": 443 }] },
                ],
              "alive_test_methods":
                ["icmp", "tcp_syn", "tcp_ack", "arp", "consider_alive"],
              "reverse_lookup_unify": true,
              "reverse_lookup_only": false,
            },
          "scan_preferences":
            [
              { "id": "target_port", "value": "443" },
              { "id": "use_https", "value": "1" },
              { "id": "profile", "value": "fast_scan" },
            ],
          "vts":
            [
              {
                "oid": "1.3.6.1.4.1.25623.1.0.10662",
                "parameters":
                  [{ "id": 1, "value": "200" }, { "id": 2, "value": "yes" }],
              },
              { "oid": "1.3.6.1.4.1.25623.1.0.10330" },
            ],
        }
    scan_full_resp:
      description: "A complex example for creating a scan, that uses all available fields."
      value:
        {
          "scan_id": "6c591f83-8f7b-452a-8c78-ba35779e682f",
          "target":
            {
              "hosts":
                [
                  "127.0.0.1",
                  "192.168.0.1-15",
                  "10.0.5.0/24",
                  "::1",
                  "2001:db8:0000:0000:0000:0000:0000:0001-00ff",
                  "2002::1234:abcd:ffff:c0a8:101/64",
                  "examplehost",
                ],
              "ports":
                [
                  {
                    "protocol": "udp",
                    "range": [{ "start": 22 }, { "start": 1024, "end": 1030 }],
                  },
                  { "protocol": "tcp", "range": [{ "start": 24, "end": 30 }] },
                  { "range": [{ "start": 100, "end": 1000 }] },
                ],
              "credentials":
                [
                  {
                    "service": "ssh",
                    "port": 22,
                    "usk":
                      {
                        "username": "user",
                        "password": "pw",
                        "private": "ssh-key...",
                      },
                  },
                  {
                    "service": "smb",
                    "up": { "username": "user", "password": "pw" },
                  },
                  {
                    "service": "snmp",
                    "snmp":
                      {
                        "username": "user",
                        "password": "pw",
                        "community": "my_community",
                        "auth_algorithm": "md5",
                        "privacy_password": "priv_pw",
                        "privacy_algorithm": "aes",
                      },
                  },
                ],
              "alive_test_ports":
                [
                  { "protocol": "tcp", "range": [{ "start": 1, "end": 100 }] },
                  { "range": [{ "start": 443 }] },
                ],
              "alive_test_methods":
                ["icmp", "tcp_syn", "tcp_ack", "arp", "consider_alive"],
              "reverse_lookup_unify": true,
              "reverse_lookup_only": false,
            },
          "scan_preferences":
            [
              { "id": "target_port", "value": "443" },
              { "id": "use_https", "value": "1" },
              { "id": "profile", "value": "fast_scan" },
            ],
          "vts":
            [
              {
                "oid": "1.3.6.1.4.1.25623.1.0.10662",
                "parameters":
                  [{ "id": 1, "value": "200" }, { "id": 2, "value": "yes" }],
              },
              { "oid": "1.3.6.1.4.1.25623.1.0.10330" },
            ],
        }
    scan_id:
      description: "The ID of the created scan"
      value: "6c591f83-8f7b-452a-8c78-ba35779e682f"
    scan_action_start:
      description: "Start a scan"
      value: { "action": "start" }
    scan_action_stop:
      description: "Stop a running scan"
      value: { "action": "stop" }

    scan_results:
      description: "Example for getting results.
        The query range for this example could be either

        - 0-3

        - 0

        - missing


        In case it is 0 or missing the running scan has only generated 4 results so far."
      value:
        [
          {
            "id": 0,
            "type": "host_start",
            "ip_address": "127.0.0.1",
            "port": 22,
            "protocol": "tcp",
            "message": "Thu Mar 23 15:16:37 2023",
          },
          {
            "id": 1,
            "type": "error",
            "ip_address": "127.0.0.1",
            "hostname": "localhost",
            "protocol": "tcp",
            "message": "MQTT initialization failed",
          },
          {
            "id": 2,
            "type": "log",
            "ip_address": "127.0.0.1",
            "hostname": "localhost",
            "oid": "1.3.6.1.4.1.25623.1.0.117628",
            "port": 22,
            "protocol": "tcp",
            "message": "FTP is enabled on the remote SSH service.",
          },
          {
            "id": 3,
            "type": "alarm",
            "ip_address": "127.0.0.1",
            "hostname": "localhost",
            "oid": "1.3.6.1.4.1.25623.1.0.147696",
            "protocol": "tcp",
            "message": "Installed version: 9.53.3\nFixed version:     9.55\nInstallation\npath / port:       /usr/bin/gs",
          },
        ]

    scan_result:
      description: "Example for getting a single result. The Result ID in the request path was set to 3."
      value:
        {
          "id": 3,
          "type": "alarm",
          "ip_address": "127.0.0.1",
          "hostname": "localhost",
          "oid": "1.3.6.1.4.1.25623.1.0.147696",
          "port": 22,
          "protocol": "tcp",
          "message": "Installed version: 9.53.3\nFixed version:     9.55\nInstallation\npath / port:       /usr/bin/gs",
        }
    host_detail:
      description: "Example for a result of type host detail"
      value:
        {
          "id": 3,
          "type": "host_detail",
          "ip_address": "127.0.0.1",
          "hostname": "localhost",
          "oid": "1.3.6.1.4.1.25623.1.0.103997",
          "detail":
            {
              "name": "OS",
              "value": "Debian GNU/Linux 11.5",
              "source":
                {
                  "type": "nvt",
                  "name": "1.3.6.1.4.1.25623.1.0.50282",
                  "description": "Determine OS and list of installed packages via SSH login",
                },
            },
        }

    scan_status_stored:
      description: "Status of a queued Scan"
      value: { "status": "stored" }

    scan_status_running:
      description: "Status of a running Scan"
      value:
        {
          "start_time": 1679649183,
          "status": "running",
          "host_info":
            {
              "all": 14,
              "excluded": 0,
              "dead": 4,
              "alive": 6,
              "queued": 1,
              "finished": 1,
              "scanning": ["127.0.0.1", "10.0.5.1", "10.0.5.2", "10.0.5.3"],
            },
        }

    scan_status_success:
      description: "Status of a successfully finished Scan"
      value:
        {
          "start_time": 1679649183,
          "end_time": 1679656139,
          "status": "succeeded",
          "host_info":
            {
              "all": 14,
              "excluded": 0,
              "dead": 4,
              "alive": 10,
              "queued": 0,
              "finished": 10,
            },
        }

    scan_status_fail:
      description: "Status of an interrupted Scan. Except for the status, a stopped scan could look like the same."
      value:
        {
          "start_time": 1679649183,
          "end_time": 1679656139,
          "status": "failed",
          "host_info":
            {
              "all": 14,
              "excluded": 0,
              "dead": 4,
              "alive": 10,
              "queued": 1,
              "finished": 8,
            },
        }

    list_of_oids:
      description: "
        A small list of OIDs for requesting the available VTs.
        For a regular feed this is typically over 100K OIDs."
      value:
        [
          "1.3.6.1.4.1.25623.1.0.100196",
          "1.3.6.1.4.1.25623.1.0.100127",
          "1.3.6.1.4.1.25623.1.0.10441",
          "1.3.6.1.4.1.25623.1.0.100313",
        ]
    notus_products:
      description: "A simple example for supported OS products by notus"
      value:
        [
          "debian_10",
          "debian_11",
          "debian_12",
          "debian_12",
          "slackware_10.0",
          "suse_linux_enterprise_module_for_live_patching_15-sp1",
          "suse_manager_debian_9.0",
          "slackware_10.1",
          "slackware_10.2",
        ]
    notus_simple:
      description: "A simple example for notus run."
      value: ["foo", "bar", "foo2"]
    notus_results:
      description: "A simple example for notus run response including a vulnerable package list and their fix"
      value:
        {
          "1.3.6.1.4.1.25623.1.1.1.2.2022.3200":
            [
              {
                "name": "foo",
                "installed_version": "1.2.3",
                "fixed_version": { "start": "1.2.2", "end": "1.2.5" },
              },
              {
                "name": "bar",
                "installed_version": "1.2.4",
                "fixed_version": { "version": "1.2.5", "specifier": ">=" },
              },
            ],
        }

    preferences:
      description: "A example with a list of preferences"
      value:
        [
          {
            "id": "optimize_test",
            "name": "Optimize Test",
            "default": true,
            "description": "By default, optimize_test is enabled which means openvas does trust the remote host banners and is only launching plugins against the services they have been designed to check. For example it will check a web server claiming to be IIS only for IIS related flaws but will skip plugins testing for Apache flaws, and so on. This default behavior is used to optimize the scanning performance and to avoid false positives. If you are not sure that the banners of the remote host have been tampered with, you can disable this option.",
          },
          {
            "id": "plugins_timeout",
            "name": "Plugins Timeout",
            "default": 5,
            "description": "This is the maximum lifetime, in seconds of a plugin. It may happen that some plugins are slow because of the way they are written or the way the remote server behaves. This option allows you to make sure your scan is never caught in an endless loop because of a non-finishing plugin. Doesn't affect ACT_SCANNER plugins, use 'ACT_SCANNER plugins timeout' for them instead.",
          },
        ]