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.