Chef Software ReportingService API
The ReportingService API from Chef Software — 12 operation(s) for reportingservice.
OpenAPI Specification
swagger: '2.0'
info:
title: external/applications/applications.proto ApplicationsService ReportingService API
version: version not set
consumes:
- application/json
produces:
- application/json
tags:
- name: ReportingService
paths:
/api/v0/compliance/reporting/controls:
post:
summary: List Controls
description: 'Lists controls from the last run, with optional filtering.
Supports filtering,pagination but not sorting.
Limited to 100 results by default.
Authorization Action:
```
compliance:controlItems:list
```'
operationId: ReportingService_ListControlItems
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ControlItems'
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.reporting.v1.ControlItemRequest'
tags:
- ReportingService
/api/v0/compliance/reporting/controls/search:
post:
summary: List Controls Search
description: 'Lists controls from the last run, with optional filtering.
Supports filtering,pagination but not sorting.
Limited to 100 results by default.
Gets the summary of each control.
The API supports date range filters when `end_time` is the current time
and `start_time` is any time in last 90 days. In case, the `end_time` is any
date other than the current date, the API would return data only for the `end_time`.
Example:
```
{"filters":
[
{"type":"start_time","values":["2019-09-09T00:00:00Z"]},
{"type":"end_time","values":["2019-09-11T23:59:59Z"]}
],
"page_number":1, "size": 3,
}
```
Authorization Action:
```
compliance:controlItems:list
```'
operationId: ReportingService_ListControlItemsRange
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ControlItems'
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.reporting.v1.ControlItemRequest'
tags:
- ReportingService
/api/v0/compliance/reporting/nodeheader/id/{id}:
post:
summary: Show Node Header Info From Report ID
description: 'Show specific details about node, report and metadate provided the report ID.
Supports filtering, but not pagination or sorting.
Authorization Action:
```
compliance:nodeheader:get
```'
operationId: ReportingService_ReadNodeHeader
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.NodeHeaderInfo'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique identifier.
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/nodes/id/{id}:
get:
summary: Show Node by ID
description: 'Show a specific node by ID.
Supports filtering by profile or control.
Does not support pagination or sorting.
Authorization Action:
```
compliance:reportNodes:get
```'
operationId: ReportingService_ReadNode
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Node'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique identifier.
in: path
required: true
type: string
tags:
- ReportingService
/api/v0/compliance/reporting/nodes/search:
post:
summary: List Nodes
description: 'List all nodes, with optional filtering, pagination, and sorting.
Max return payload size is 4MB, use pagination to fetch remaining data.
| Sort parameter | Sort value |
| --- | --- |
| environment | environment.lower |
| latest_report.controls.failed.critical | controls_sums.failed.critical |
| latest_report.controls.failed.total | controls_sums.failed.total |
| latest_report.end_time (default) | end_time |
| latest_report.status | status |
| name | node_name.lower |
| platform | platform.full |
| status | status |
The API supports date range filters when `end_time` is the current time
and `start_time` is any time in last 90 days. In case, the `end_time` is any
date other than the current date, the API would return data only for the `end_time`.
Example:
```
{
"filters":[
{"type":"environment","values":["dev*"]},
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]}
],
"page":1,"per_page":100,
"sort":"environment","order":"ASC"
}
```
Authorization Action:
```
compliance:reportNodes:list
```'
operationId: ReportingService_ListNodes
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Nodes'
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.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/profiles:
post:
summary: List Profiles
description: 'List all profiles in use, with optional filtering.
Supports pagination, filtering, and sorting.
Valid sort fields: name, title
The API supports date range filters when `end_time` is the current time
and `start_time` is any time in last 90 days. In case, the `end_time` is any
date other than the current date, the API would return data only for the `end_time`.
Example:
```
{"filters":
[
{"type":"start_time","values":["2019-09-09T00:00:00Z"]},
{"type":"end_time","values":["2019-09-11T23:59:59Z"]}
],
"page":1, "per_page": 3,
}
```
Authorization Action:
```
compliance:reportProfiles:list
```'
operationId: ReportingService_ListProfiles
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ProfileMins'
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.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/report-ids:
post:
summary: List Report IDs
description: 'List all IDs for the latest report for each node, with optional filtering.
Supports filtering, but not pagination or sorting.
Including more than one value for `profile_id`, or `profile_name` is not allowed.
Including values for both `profile_id` and `profile_name` in one request is not allowed.
Max return payload size is 4MB.
Authorization Action:
```
compliance:reportids:list
```'
operationId: ReportingService_ListReportIds
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ReportIds'
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.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/reportcontrols/id/{id}:
post:
summary: List Control Info
description: "Lists controls from the last run, with optional filtering.\nSupports filtering and pagination. Maximum 100 search can be \nmade when specifying the pagination from and size. Sum of from+size\nshould be less that 100. By default 10 results will be returned.\nAuthorization Action:\n```\ncompliance:ControlElements:list\n```"
operationId: ReportingService_ListControlInfo
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ControlElements'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique identifier.
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/reportmanager/export:
post:
summary: Export reports
description: 'Export multiple reports.
Supports filtering by profile or control. API returns an acknowledgement ID.
Authorization Action:
```
compliance:reports:list
```'
operationId: ReportingService_ExportReportManager
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.CustomReportResponse'
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.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/reports:
post:
summary: List Reports
description: 'Makes a list of reports. Adding a filter makes a list of all node reports that meet the filter criteria.
Supports pagination, filtering, and sorting.
Max return payload size is 4MB, use pagination to fetch remaining data.
Valid sort fields: latest_report.controls.failed.critical, latest_report.controls.failed.total, latest_report.end_time, latest_report.status, node_name
Example:
```
{"filters":
[
{"type":"start_time","values":["2019-09-09T00:00:00Z"]},
{"type":"end_time","values":["2019-09-11T23:59:59Z"]}
],
"page":1, "per_page": 3,
"sort": "latest_report.status", "order": "ASC"
}
```
Authorization Action:
```
compliance:reports:list
```'
operationId: ReportingService_ListReports
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ReportsSummaryLevelOne'
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.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/reports/id/{id}:
post:
summary: Show Report by ID
description: 'Show a specific report by ID. Supports filtering, but not pagination or sorting.
Including more than one value for `profile_id`, or `profile_name` is not allowed.
Including values for both `profile_id` and `profile_name` in one request is not allowed.
Authorization Action:
```
compliance:reports:get
```'
operationId: ReportingService_ReadReport
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Report'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique identifier.
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Query'
tags:
- ReportingService
/api/v0/compliance/reporting/suggestions:
post:
summary: List Reporting Suggestions
description: 'Get suggestions for compliance reporting resources based on matching text substrings.
Supports filtering, but not pagination or sorting.
`type` parameter is required. It must be one of the parameters from the following table.
| Suggestion type parameter | Suggestion type value |
| --- | --- |
| chef_server | source_fqdn |
| chef_tags | chef_tags |
| control | profiles.controls.title |
| control_tag_key | profiles.controls.string_tags.key |
| control_tag_value | profiles.controls.string_tags.values |
| environment | environment |
| inspec_version | version |
| node | node_name |
| organization | organization_name |
| platform | platform.name |
| platform_with_version | platform.full |
| policy_group | policy_group |
| policy_name | policy_name |
| profile | profiles.title |
| profile_with_version | profiles.full |
| recipe | recipes |
| role | roles |
Example:
```
{
"type":"environment",
"text":"aws*",
"filters":[
{"type":"start_time","values":["2019-10-26T00:00:00Z"]},
{"type":"end_time","values":["2019-11-05T23:59:59Z"]}
]
}
```
Authorization Action:
```
compliance:reportSuggestions:list
```'
operationId: ReportingService_ListSuggestions
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Suggestions'
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.reporting.v1.SuggestionRequest'
tags:
- ReportingService
definitions:
chef.automate.api.compliance.reporting.v1.SourceLocation:
type: object
properties:
ref:
type: string
description: The source code file the control is defined in.
line:
type: integer
format: int32
description: The line number the control is defined on.
chef.automate.api.compliance.reporting.v1.ControlItemRequest:
type: object
properties:
text:
type: string
description: The term to use to match resources on.
size:
type: integer
format: int32
description: The maximum number of controls to return (Default 100).
page_number:
type: integer
format: int32
title: The offset for paginating requests. An offset defines a place in the results in order to show the next page of the results. (Default 1)
filters:
type: array
items:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ListFilter'
description: The criteria used to filter the controls returned.
chef.automate.api.compliance.reporting.v1.ProfileCounts:
type: object
properties:
total:
type: integer
format: int32
description: The total number of nodes matching the filters.
failed:
type: integer
format: int32
description: The total number of failed nodes matching the filters.
skipped:
type: integer
format: int32
description: The total number of skipped nodes matching the filters.
passed:
type: integer
format: int32
description: The total number of passing nodes matching the filters.
waived:
type: integer
format: int32
description: The total number of waived nodes matching the filters.
description: Stats on the statuses of nodes matching the filters.
chef.automate.api.compliance.reporting.v1.Kv:
type: object
properties:
key:
type: string
description: The key of the tag.
value:
type: string
description: The value of the tag.
chef.automate.api.compliance.reporting.v1.Total:
type: object
properties:
total:
type: integer
format: int32
description: The total number of controls.
description: A subtotal of controls.
chef.automate.api.compliance.reporting.v1.Attribute:
type: object
properties:
name:
type: string
description: The name of the attribute.
options:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Option'
description: The options defined for the attribute.
chef.automate.api.compliance.reporting.v1.Failed:
type: object
properties:
total:
type: integer
format: int32
description: The total number of failed controls.
minor:
type: integer
format: int32
description: The number of failed controls with minor severity.
major:
type: integer
format: int32
description: The number of failed controls with major severity.
critical:
type: integer
format: int32
description: The number of failed controls with critical severity.
description: Stats of failed controls.
google.protobuf.Any:
type: object
properties:
type_url:
type: string
description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
value:
type: string
format: byte
description: Must be a valid serialized protocol buffer of the above specified type.
description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(&foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := &pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := &pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": <string>,\n \"lastName\": <string>\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }"
chef.automate.api.compliance.reporting.v1.ControlSummary:
type: object
properties:
total:
type: integer
format: int32
description: The total number of controls in the report.
passed:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Total'
description: Intentionally blank.
skipped:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Total'
description: Intentionally blank.
failed:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Failed'
description: Intentionally blank.
waived:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Total'
description: Intentionally blank.
description: A minimal representation of the statuses of the controls in the report.
chef.automate.api.compliance.reporting.v1.RemovedResultsCounts:
type: object
properties:
failed:
type: integer
format: int32
title: The number of results with status of `failed` that have been trimmed (removed) from a control
skipped:
type: integer
format: int32
title: The number of results with status of `skipped` that have been trimmed (removed) from a control
passed:
type: integer
format: int32
title: The number of results with status of `passed` that have been trimmed (removed) from a control
chef.automate.api.compliance.reporting.v1.ListFilter:
type: object
properties:
values:
type: array
items:
type: string
description: Filters applied to the list.
type:
type: string
description: The field to filter on.
chef.automate.api.compliance.reporting.v1.Group:
type: object
properties:
id:
type: string
description: The name of the file the controls are defined in.
title:
type: string
description: The title of control group.
controls:
type: array
items:
type: string
description: The ids of the controls defined in this file.
chef.automate.api.compliance.reporting.v1.ProfileMins:
type: object
properties:
profiles:
type: array
items:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ProfileMin'
description: Minimal representations of the profiles matching the filters.
counts:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ProfileCounts'
description: Intentionally blank.
chef.automate.api.compliance.reporting.v1.Suggestions:
type: object
properties:
suggestions:
type: array
items:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Suggestion'
description: The list of returned suggestions.
chef.automate.api.compliance.reporting.v1.OrigWaiverData:
type: object
properties:
expiration_date:
type: string
justification:
type: string
run:
type: boolean
skipped_due_to_waiver:
type: boolean
message:
type: string
title: 'OrigWaiverData as it originally came from the InSpec report
Will supplement this with waived_str to make consumption easier'
chef.automate.api.compliance.reporting.v1.Statistics:
type: object
properties:
duration:
type: number
format: float
description: The duration of the report's generation time.
description: Statistics of the report's run.
chef.automate.api.compliance.reporting.v1.ProfileMin:
type: object
properties:
name:
type: string
description: The name of the profile.
title:
type: string
description: The profile title.
id:
type: string
description: The profile ID.
version:
type: string
description: The profile version.
status:
type: string
description: The aggregated status of the profile across the nodes it has been run on.
description: Minimal representation of a profile.
chef.automate.api.compliance.reporting.v1.NodeHeaderProfileInfo:
type: object
properties:
name:
type: string
description: The name of the profile. Must be unique.
status:
type: string
description: The status of the profile in the generated report.
status_message:
type: string
description: A message to detail the reason why a profile is skipped or failed in the generated report.
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.reporting.v1.Control:
type: object
properties:
id:
type: string
description: The unique ID of this control.
code:
type: string
description: The full ruby code of the control defined in the profile.
desc:
type: string
description: The full description of the control.
impact:
type: number
format: float
description: The severity of the control.
title:
type: string
description: The compact description of the control.
source_location:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.SourceLocation'
description: Intentionally blank.
results:
type: array
items:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Result'
description: The results of running all tests defined in the control against the node.
refs:
type: array
items:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.Ref'
description: External supporting documents for the control.
tags:
type: string
description: Metadata defined on the control in key-value format.
waived_str:
type: string
title: Indicates if the control has been waived or not
waiver_data:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.OrigWaiverData'
title: Additional details for waived controls
removed_results_counts:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.RemovedResultsCounts'
description: When the control results are removed to reduce the size of the report, this summarize the status of the trimmed results.
chef.automate.api.compliance.reporting.v1.Query.OrderType:
type: string
enum:
- ASC
- DESC
default: ASC
description: Sort the results in ascending or descending order.
chef.automate.api.compliance.reporting.v1.ControlElements:
type: object
properties:
control_elements:
type: array
items:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ControlElement'
title: List of control elements
chef.automate.api.compliance.reporting.v1.ControlElement:
type: object
properties:
id:
type: string
description: The control's unique ID.
title:
type: string
description: The control's compact description.
profile:
type: string
description: Profile name.
impact:
type: number
format: float
description: The severity of the control.
results:
type: integer
format: int32
description: The total number of results.
status:
type: string
title: The control's status
profile_id:
type: string
title: Profile id
chef.automate.api.compliance.reporting.v1.Ref:
type: object
properties:
url:
type: string
description: The external document URL.
ref:
type: string
description: A description of the external document.
chef.automate.api.compliance.reporting.v1.ReportIds:
type: object
properties:
ids:
type: array
items:
type: string
description: The list of unique report identifiers found matching the query.
report_data:
type: array
items:
$ref: '#/definitions/chef.automate.api.compliance.reporting.v1.ReportData'
description: The list of unique report identifiers with their respective end_time, found matching the query.
chef.automate.api.compliance.reporting.v1.ProfileMeta:
type: object
properties:
name:
type: string
description: The name of the profile.
version:
type: string
description: The profile version.
id:
type: string
description: The profile unique ID.
status:
type: string
description: The status of the profile run against the node.
full:
type: string
description: The combined name and version of the profile.
chef.automate.api.compliance.reporting.v1.Result:
type: object
properties:
status:
type: string
description: The status of the test.
code_desc:
type: string
des
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chef-software/refs/heads/main/openapi/chef-software-reportingservice-api-openapi.yml