Chef Software JobsService API

openapi: 3.2.0
info:
  title: external/applications/applications.proto ApplicationsService Jobs Service API
  version: version not set
servers:
- url: https://automate.chef.io/api/v0
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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.compliance.scanner.jobs.v1.Id'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      tags:
      - JobsService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.compliance.scanner.jobs.v1.Job'
        required: true
  /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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.compliance.scanner.jobs.v1.Job'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) assigned to object.
        in: path
        required: true
        schema:
          type: string
      - name: name
        description: Name of object.
        in: query
        required: false
        schema:
          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.
          content:
            application/json:
              schema:
                properties: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) assigned to object.
        in: path
        required: true
        schema:
          type: string
      - name: name
        description: Name of object.
        in: query
        required: false
        schema:
          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.
          content:
            application/json:
              schema:
                properties: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) of the scan job.
        in: path
        required: true
        schema:
          type: string
      tags:
      - JobsService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.compliance.scanner.jobs.v1.Job'
        required: true
  /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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.compliance.scanner.jobs.v1.RerunResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: id
        description: Unique ID (UUID) assigned to object.
        in: path
        required: true
        schema:
          type: string
      - name: name
        description: Name of object.
        in: query
        required: false
        schema:
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.compliance.scanner.jobs.v1.Jobs'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      tags:
      - JobsService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.compliance.scanner.jobs.v1.Query'
        required: true
components:
  schemas:
    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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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.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.Query:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.common.query.Filter'
          description: Use filters to limit the set of items returned.
        order:
          $ref: '#/components/schemas/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.
    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.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.Id:
      type: object
      properties:
        id:
          type: string
          description: Unique ID (UUID) assigned to object.
        name:
          type: string
          description: Name of object.
    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: '#/components/schemas/google.protobuf.Any'
    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.ManagerFilter:
      type: object
      properties:
        manager_id:
          type: string
          description: Unique ID of a node manager.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.common.query.Filter'
          description: Use filters to limit the set of items returned.
    chef.automate.api.compliance.scanner.jobs.v1.Jobs:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/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.