Chef Software JobsService API

swagger: '2.0'
info:
  title: external/applications/applications.proto ApplicationsService JobsService API
  version: version not set
consumes:
- application/json
produces:
- application/json
tags:
- name: JobsService
paths:
  /api/v0/compliance/scanner/jobs:
    post:
      summary: Create a scan job
      description: "Creates a scan job. A scan job executes Chef InSpec against the specified nodes.\nRequires a user-specified name. Type should be `detect` (checks if the node is reachable and reports the\nplatform information for the nodes) or `exec` (executes a set of profiles against the nodes).\nNodes to scan may be specified by including an array of node IDs to scan or a node manager ID along with some optional\nfiltering information.\nExec jobs require at least one profile to be used as part of the Chef InSpec scan.\nOptional recurrence schedules enable regularly scheduled (repeating) scans.\n\nExample:\n```\n{  \n\"name\": \"my testjob\",\n\"tags\": [],\n\"type\": \"exec\",\n\"nodes\": [\"i07uc612-7e97-43f2-9b19-256abh785820\"],\n\"profiles\": [\"https://github.com/dev-sec/linux-baseline/archive/master.tar.gz\", \"compliance://admin/ssh-baseline#2.2.0\"],\n\"retries\": 1,\n\"node_selectors\":[\n{\n\"manager_id\":\"e69dc612-7e67-43f2-9b19-256afd385820\",\n\"filters\":[{\"key\":\"name\",\"values\":[\"ins*\"],\"exclude\":false}]\n}\n],\n\"recurrence\":\"DTSTART=20191231T045100Z;FREQ=DAILY;INTERVAL=1\"\n}\n```\n\nAuthorization Action:\n\n```\ncompliance:scannerJobs:create\n```"
      operationId: JobsService_Create
      responses:
        '200':
          description: A successful response.
          schema:
            $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Id'
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/grpc.gateway.runtime.Error'
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Job'
      tags:
      - JobsService
  /api/v0/compliance/scanner/jobs/id/{id}:
    get:
      summary: Read a scan job
      description: 'Read the details of a scan job given an ID.


        Authorization Action:


        ```

        compliance:scannerJobs:get

        ```'
      operationId: JobsService_Read
      responses:
        '200':
          description: A successful response.
          schema:
            $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Job'
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) assigned to object.
        in: path
        required: true
        type: string
      - name: name
        description: Name of object.
        in: query
        required: false
        type: string
      tags:
      - JobsService
    delete:
      summary: Delete a scan job
      description: 'Delete a scan job given an ID. Note this does not delete the report(s) generated by the scan job.


        Authorization Action:


        ```

        compliance:scannerJobs:delete

        ```'
      operationId: JobsService_Delete
      responses:
        '200':
          description: A successful response.
          schema:
            properties: {}
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) assigned to object.
        in: path
        required: true
        type: string
      - name: name
        description: Name of object.
        in: query
        required: false
        type: string
      tags:
      - JobsService
    put:
      summary: Update a job
      description: "PUT operation to update the details for a scan job, such as the name, profiles, node set, or recurrence schedule.\nPlease note that this is a PUT operation, so all scan job details included in the create function\nshould be included in the PUT message to update.\t\n\nAuthorization Action:\n\n```\ncompliance:scannerJobs:update\n```"
      operationId: JobsService_Update
      responses:
        '200':
          description: A successful response.
          schema:
            properties: {}
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) of the scan job.
        in: path
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Job'
      tags:
      - JobsService
  /api/v0/compliance/scanner/jobs/rerun/id/{id}:
    get:
      summary: Rerun a scan job
      description: "Does not create a new job in the database. Reads the job info given the job ID\nand runs a scan. The latest job information is then updated to reflect this latest run.\t\n\nAuthorization Action:\n\n```\ncompliance:scannerJobs:rerun\n```"
      operationId: JobsService_Rerun
      responses:
        '200':
          description: A successful response.
          schema:
            $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.RerunResponse'
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) assigned to object.
        in: path
        required: true
        type: string
      - name: name
        description: Name of object.
        in: query
        required: false
        type: string
      tags:
      - JobsService
  /api/v0/compliance/scanner/jobs/search:
    post:
      summary: List of scan jobs
      description: "Returns a list of scan jobs matching the query.\nSupports filtering, sorting, and pagination.\nValid filtering fields: job_type, parent_job, status\nValid sorting fields: name, type, status, start_time, end_time\n\nExample:\n```\n{\n\"filters\":[\n{\"key\":\"job_type\",\"values\":[\"exec\"]},\n{\"key\":\"parent_job\",\"values\":[\"\"]}\n],\n\"page\":1,\n\"per_page\":100,\n\"sort\":\"end_time\",\n\"order\":\"DESC\"\n} \n```\n\nAuthorization Action:\n\n```\ncompliance:scannerJobs:list\n```"
      operationId: JobsService_List
      responses:
        '200':
          description: A successful response.
          schema:
            $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Jobs'
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/grpc.gateway.runtime.Error'
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Query'
      tags:
      - JobsService
definitions:
  chef.automate.api.compliance.scanner.jobs.v1.ResultsRow:
    type: object
    properties:
      node_id:
        type: string
        description: ID of the scanned node.
      report_id:
        type: string
        description: ID of the report generated by the scan.
      status:
        type: string
        description: Status of the scan (completed, failed, aborted).
      result:
        type: string
        description: Result error message for failed scans.
      job_id:
        type: string
        description: ID of the scan.
      start_time:
        type: string
        format: date-time
        description: Start time of the scan.
      end_time:
        type: string
        format: date-time
        description: End time of the scan.
  chef.automate.api.compliance.scanner.jobs.v1.Job:
    type: object
    properties:
      id:
        type: string
        description: Unique ID (UUID) of the scan job.
      name:
        type: string
        description: User-specified name of the scan job.
      type:
        type: string
        description: Determines the type of Chef InSpec run, `detect` or `exec`.
      timeout:
        type: integer
        format: int32
        description: 'Desired timeout (in seconds) for the scan job execution. Default: 7200 for exec jobs, 600 for detect jobs.'
      tags:
        type: array
        items:
          $ref: '#/definitions/chef.automate.api.common.query.Kv'
        description: Tags to assign to the scan job.
      start_time:
        type: string
        format: date-time
        description: Start time of the scan job, assigned by the service.
      end_time:
        type: string
        format: date-time
        description: End time of the scan job, assigned by the service.
      status:
        type: string
        description: Status of the scan job, assigned by the service.
      retries:
        type: integer
        format: int32
        description: 'Number of times to retry the scan job. Default: 3.'
      retries_left:
        type: integer
        format: int32
        description: Number of retries left, assigned by the service.
      results:
        type: array
        items:
          $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.ResultsRow'
        description: Results of the scan job, including a report ID if one was generated.
      nodes:
        type: array
        items:
          type: string
        description: List of node IDs to associate with the scan job.
      profiles:
        type: array
        items:
          type: string
        description: List of profiles to execute as part of the scan job.
      node_count:
        type: integer
        format: int32
        description: Count of nodes to be scanned as part of the job, assigned by the service.
      profile_count:
        type: integer
        format: int32
        description: Count of profiles to be executed as part of the job.
      node_selectors:
        type: array
        items:
          $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.ManagerFilter'
        description: Set of node manager IDs and filters to associate with the scan job.
      scheduled_time:
        type: string
        format: date-time
        description: Next scheduled scan execution time.
      recurrence:
        type: string
        description: Recurrence schedule string for the job.
      parent_id:
        type: string
        description: ID of parent job to associate with the job, if any.
      job_count:
        type: integer
        format: int32
        description: Count of scans executed by the job.
      deleted:
        type: boolean
        description: Boolean used to denote the job has been marked as "deleted" by the user.
  chef.automate.api.compliance.scanner.jobs.v1.ManagerFilter:
    type: object
    properties:
      manager_id:
        type: string
        description: Unique ID of a node manager.
      filters:
        type: array
        items:
          $ref: '#/definitions/chef.automate.api.common.query.Filter'
        description: Use filters to limit the set of items returned.
  chef.automate.api.common.query.Kv:
    type: object
    properties:
      key:
        type: string
        description: Tag key.
      value:
        type: string
        description: Tag value.
  chef.automate.api.compliance.scanner.jobs.v1.Query.OrderType:
    type: string
    enum:
    - ASC
    - DESC
    default: ASC
    description: Return the results in ascending or descending order.
  chef.automate.api.compliance.scanner.jobs.v1.RerunResponse:
    type: object
  chef.automate.api.compliance.scanner.jobs.v1.Query:
    type: object
    properties:
      filters:
        type: array
        items:
          $ref: '#/definitions/chef.automate.api.common.query.Filter'
        description: Use filters to limit the set of items returned.
      order:
        $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Query.OrderType'
      sort:
        type: string
        description: Sort the results on a specific field.
      page:
        type: integer
        format: int32
        description: Starting page for the results.
      per_page:
        type: integer
        format: int32
        description: The number of results on each page.
  google.protobuf.Any:
    type: object
    properties:
      type_url:
        type: string
      value:
        type: string
        format: byte
  grpc.gateway.runtime.Error:
    type: object
    properties:
      error:
        type: string
      code:
        type: integer
        format: int32
      message:
        type: string
      details:
        type: array
        items:
          $ref: '#/definitions/google.protobuf.Any'
  chef.automate.api.compliance.scanner.jobs.v1.Jobs:
    type: object
    properties:
      jobs:
        type: array
        items:
          $ref: '#/definitions/chef.automate.api.compliance.scanner.jobs.v1.Job'
        description: List of jobs.
      total:
        type: integer
        format: int32
        description: Total number of jobs in the system.
  chef.automate.api.common.query.Filter:
    type: object
    properties:
      key:
        type: string
        description: Field to filter on.
      exclude:
        type: boolean
        description: "Include matches for this filter.(boolean)\n`true` (default) *includes* all nodes that match this filter. \n`false` *excludes* all nodes that match this filter."
      values:
        type: array
        items:
          type: string
        description: Field values to filter on.
  chef.automate.api.compliance.scanner.jobs.v1.Id:
    type: object
    properties:
      id:
        type: string
        description: Unique ID (UUID) assigned to object.
      name:
        type: string
        description: Name of object.