To enable Advanced Patching, you must acquire a Puppet Enterprise Advanced license. Contact your Puppet Enterprise administrator or Contact our sales team to acquire a license and enable this feature.

Before you begin

See Advanced Patching.

Create a blackout window

POST /v1/command/create-blackout-window

Important: To create a blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z"
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	any	true	none

Response format


Status	Meaning	Description	Schema
201	Created	Created.	entity-id
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Delete a blackout window

POST /v1/command/delete-blackout-window

Important: To delete a blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	object	true	none
» id	body	string(uuid)	true	none

Response format

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}Copied!

Responses


Status	Meaning	Description	Schema
204	No Content	Deletion of the blackout window was successful.	None
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error

Get a list of blackout windows

GET /v1/blackout-windows

Important: To get a list of blackout windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none

Enumerated values


Parameter	Value
order_by	name
order_by	description
order_by	id
order_by	next_instance
order	asc
order	desc

Response format

{
  "items": [
    {
      "name": "string",
      "description": "string",
      "window_start": "2019-08-24T14:15:22Z",
      "window_end": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "next_instance": "2019-08-24"
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0
  }
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of blackout windows.	Inline
401	Unauthorized	Authentication failed	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[oneOf]	false	none	none

oneOf


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
»»» anonymous	one-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» window_start	string(date-time)	true	none	The start of the valid period for the window. If not specified, defaults to `now`
»»»» window_end	string(date-time)	true	none	The end of the valid period of the window. If not specified, implies the end of time.

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for this one-time-window. Not present if the time is in the past

xor


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
anonymous	repeated-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
»»»» series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
»»»» series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a sub window are not valid.
»»»»» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format
»»»»» duration	object	true	none	none
»»»»»» amount	integer	true	none	none
»»»»»» unit	string	true	none	Unit of time: s - seconds, m - minutes, h - hours, d - days

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for the next instance of this window. Not present if the time is in the past.

continued


Name	Type	Required	Restrictions	Description
» pagination	pagination	false	none	none
»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	true	none	The number of records skipped before collecting the results.
»» order_by	string	true	none	none
»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»» total	integer	true	none	The total number of records available, ignoring limit and offset

Enumerated values


Property	Value
unit	s
unit	h
unit	m
unit	d
order	asc
order	desc

Get a single blackout window

GET /v1/blackout-windows/{id}

Important: To get a single blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	true	none

Response format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "patch_groups": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "next_instance": "2019-08-24"
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of blackout windows.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Blackout window not found.	error

Response schema


Property	Value
unit	s
unit	h
unit	m
unit	d

Create a maintenance window

POST /v1/command/create-maintenance-window

Important: To create a maintenance window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z"
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	any	true	none

Response-format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}Copied!

Responses


Status	Meaning	Description	Schema
201	Created	Created.	entity-id
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Delete a maintenance window

POST /v1/command/delete-maintenance-window

Important: To delete a maintenance window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	object	true	none
» id	body	string(uuid)	true	none

Response format

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}Copied!

Responses


Status	Meaning	Description	Schema
204	No Content	Deletion of the maintenance window was successful.	None
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error

Get a list of maintenance windows

GET /v1/maintenance-windows

Important: To get a list of maintenance windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none

Enumerated values


Parameter	Value
order_by	name
order_by	description
order_by	id
order_by	next_instance
order	asc
order	desc

Response format

{
  "items": [
    {
      "name": "string",
      "description": "string",
      "window_start": "2019-08-24T14:15:22Z",
      "window_end": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "next_instance": "2019-08-24"
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0
  }
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of maintenance windows.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[oneOf]	false	none	none

oneOf


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
»»» anonymous	one-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» window_start	string(date-time)	true	none	The start of the valid period for the window. If not specified, defaults to `now`
»»»» window_end	string(date-time)	true	none	The end of the valid period of the window. If not specified, implies the end of time.

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for this one-time-window. Not present if the time is in the past

xor


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
anonymous	repeated-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
»»»» series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
»»»» series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a sub window are not valid.
»»»»» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format
»»»»» duration	object	true	none	none
»»»»»» amount	integer	true	none	none
»»»»»» unit	string	true	none	Unit of time: s - seconds, m - minutes, h - hours, d - days

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for the next instance of this window. Not present if the time is in the past.

continued


Name	Type	Required	Restrictions	Description
» pagination	pagination	false	none	none
»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	true	none	The number of records skipped before collecting the results.
»» order_by	string	true	none	none.
»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»» total	integer	true	none	The total number of records available, ignoring limit and offset.

Enumerated values


Property	Value
unit	s
unit	h
unit	m
unit	d
order	asc
order	desc

Get a single maintenance window

GET /v1/maintenance-windows/{id}

Important: To get a single maintenance window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	true	none

Response format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "patch_groups": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "next_instance": "2019-08-24"
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an individual maintenance window.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Maintenance window not found.	error

Response schema


Property	Value
unit	s
unit	h
unit	m
unit	d

Create a patch group

POST /v1/command/create-patch-group

Important: To create a patch group, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

Note: rule is an optional parameter. For more information about formatting see Rule condition grammar.

{
  "patch_group": {
    "name": "string",
    "description": "string",
    "node_list": [
      "string"
    ],
    "rule": [],
    "maintenance_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "blackout_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  },
  "options": {
    "force_move": false
  }
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	create-patch-group-payload	true	none

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "operation": "fc63ceec-84f0-4df1-a7e8-77c5f8c0b283"
}Copied!

Responses


Status	Meaning	Description	Schema
201	Created	Created.	patch-group-with-operation-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
409	Conflict	Node already exists in a different patch group and force is false.	collision-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Delete a patch group

Delete a patch group and any patch jobs targeting it, along with their scheduled tasks.POST /v1/command/delete-patch-group

Request format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	object	true	none
» id	body	string(uuid)	true	none

Response format

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}Copied!

Responses


Status	Meaning	Description	Schema
204	No Content	Deletion of the patch group and associated jobs was successful.	None
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have edit permissions on patch groups.	forbidden-request-error

Get a single patch group

GET /v1/patch-groups/{id}

Important: To get a single patch group, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	true	none

Response format

Note: rule is an optional parameter. For more information about formatting see Rule condition grammar.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "node_list": [
    "string"
  ],
  "rule": [],
  "maintenance_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "blackout_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "state": "pending",
  "package_updates": [
    "string"
  ],
  "security_package_updates": [
    "string"
  ],
  "last_package_update_time": "2019-08-24T14:15:22Z",
  "nodes_with_package_updates": [
    "string"
  ]
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an individual patch group.	patch-group-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Patch group not found.	error

Get patch group nodes

GET /v1/patch-groups/{id}/nodes

Get the set of nodes that resolve to the patch group through rule evaluation and pinned nodes.

Important: To get a single patch group, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	true	none

Response format

{
  "nodes": [
    "string"
  ]
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns the nodes for the individual patch group including pinned nodes and resolved rules.	patch-group-nodes-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Patch group not found.	error

Get a list of patch groups

GET /v1/patch-groups

Important: To get a list of patch groups, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none
with_updates_only	query	boolean	false	none

Enumerated values


Parameter	Value
order_by	name
order_by	description
order_by	id
order	asc
order	desc

Response format

Note: rule is an optional parameter. For more information about formatting see Rule condition grammar.

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "node_list": [
        "string"
      ],
      "rule": [],
      "maintenance_windows": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "blackout_windows": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "state": "pending",
      "package_updates": [
        "string"
      ],
      "security_package_updates": [
        "string"
      ],
      "last_package_update_time": "2019-08-24T14:15:22Z",
      "nodes_with_package_updates": [
        "string"
      ]
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0
  }
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of patch groups.	Inline
401	Unauthorized	Authentication failed,	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Tupe	Required	Restrictions	Description
items	[patch-group-response]	false	none	none.
»» id	identifier(uuid)	true	none	none.
»» name	string	true	none	A unique name for the patch group.
»» description	string	false	none	A user defined description for the group.
»» node_list	[node]	true	none	none.
»» maintenance_windows	[identifier]	false	none	none.
»» blackout_windows	[identifier]	false	none	none.
»» state	string	true	none	none.
»» package_updates	[string]	true	none	The set of pending package updates for the nodes in the patch group.
»» security_package_updates	[string]	true	none	The set of pending security package updates for the nodes in the patch group. These are also listed in the package_updates.
»» last_package_update_time	string(date-time)	false	none	none.
»» nodes_with_package_updates	[string]	true	none	nodes in the patch group that have pending package updates.
» pagination	pagination	false	none	none.
»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	true	none	The number of records skipped before collecting the results.
»» order_by	string	true	none	none.
»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»» total	integer	true	none	The total number of records available, ignoring limit and offset.

Enumerated values


Property	Value
state	pending
state	failed
state	ready
order	asc
order	desc

Validate a proposed patch group

Validate a proposed patch group name to ensure that it is well formed and does not collide with any other names. POST /v1/command/validate-patch-group-name

Important: To get a list of blackout windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "name": "string"
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	patch-group-validate-name-payload	true	none

Response-format

{
  "valid": true,
  "reasons": [
    "string"
  ]
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns state of the operation.	entity-id
401	Unauthorized	Authentication failed.	not-authenticated-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» valid	boolean	true	none	none
» reasons	[string]	false	none	none

Create a patch job

POST /v1/command/create-patch-job

Important: To create a patch job, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false
}Copied!

Parameters


Name	In	Type	Required	Description
body	body	patch-job	true	none

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}Copied!

Responses


Status	Meaning	Description	Schema
201	Created	Created.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
409	Conflict	Node already exists in a different patch group and force is false.	collision-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Response schema


Name	In	Type	Required	Description
» id	string(uuid)	true	none	none

Get a list of patch jobs

GET /v1/patch-jobs

Important: To get a list of patch jobs, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
limit	query	limit	false	none
offset	query	offset	false	none

Response format

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "description": "string",
      "parameters": {
        "yum_params": "string",
        "dpkg_params": "string",
        "zypper_params": "string",
        "reboot": "always",
        "timeout": 3600,
        "security_only": false,
        "clean_cache": true
      },
      "scope": {
        "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
      },
      "schedule": {
        "frequency": "now",
        "timestamp": "2019-08-24T14:15:22Z"
      },
      "ignore_maintenance_windows": false,
      "ignore_blackout_windows": false,
      "next_run_time": "2019-08-24T14:15:22Z",
      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4"
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0
  }
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of patch jobs.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[allOf]	false	none	none

allOf


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none
»»» id	identifier(uuid)	false	none	none

and


Name	Type	Required	Restrictions	Description
»» anonymous	patch-job	false	none	none
»»» description	string	false	none	none
»»» parameters	patch-job-parameters	false	none	none
»»»» yum_params	string	false	none	Any additional parameters to include in the yum upgrade command (such as including/excluding repos)
»»»» dpkg_params	string	false	none	Any additional parameters to include in the dpkg command
»»»» zypper_params	string	false	none	Any additional parameters to include in the zypper update command
»»»» reboot	string	false	none	Should the server reboot after patching has been applied? (Defaults to 'never')
»»»» timeout	integer	false	none	How many seconds should we wait until timing out the patch run?
»»»» security_only	boolean	false	none	Limit patches to those tagged as security related?
»»»» clean_cache	boolean	false	none	Should the yum/dpkg caches be cleaned at the start of the task? (Defaults to false)
»»» scope	object	false	none	none
»»»» patch_group_id	string(uuid)	false	none	none
»»» schedule	object	true	none	none
»»»» frequency	string	true	none	How often the job should run. If `now`, the rest of the schedule is ignored, and will be run at the first opportunity.

oneOf


Name	Type	Required	Restrictions	Description
»» anonymous	one-time-execution	false	none	none
»»»»» timestamp	string(date-time)	false	none	none

xor


Name	Type	Required	Restrictions	Description
»»»» anonymous	repeated-time-interval	false	none	none
»»»»» name	string	true	none	A user defined unique name for the interval
»»»»» description	string	false	none	A user defined description for the interval
»»»»» series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
»»»»» series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
»»»»» series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a subwindow are not valid.
»»»»»» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format

and


Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none
»»» next_run_time	string(date-time)	false	none	When the job will next run, if applicable
»»» created_by	string(uuid)	false	none	User id that created the job

continued


Name	Type	Required	Restrictions	Description
pagination	object	false	none	none
»» limit	limit	false	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	false	none	The number of records skipped before collecting the results.

Enumerated values


Property	Value
reboot	always
reboot	never
reboot	patched
reboot	smart
frequency	now
frequency	once
frequency	recurring

Get a single patch job

GET /v1/patch-jobs/{id}

Important: To get a single patch job, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	true	none

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false,
  "next_run_time": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4"
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an individual patch job.	patch-job-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Patch job not found.	error

Get a list of operations

GET /v1/operations

Important: To get a list of blackout windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none
type	query	string	false	none

Enumerated values


Parameter	Value
order_by	type
order_by	id
order_by	creator
order_by	created_on
order_by	state
order	asc
order	desc

Response format

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "creator": "1dccd4a6-75d2-43aa-a088-76d941f1b60a",
      "created_on": "2019-08-24T14:15:22Z",
      "state": "queued",
      "type": "string",
      "history": [
        {
          "description": "string",
          "state": "created",
          "stage": "string",
          "result": {},
          "timestamp": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0,
    "type": "string"
  }
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of operations	Inline
401	Unauthorized	Authentication failed	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[operation]	false	none	none.
»» id	identifier(uuid)	true	none	none.
»» creator	identifier(uuid)	false	none	none.
»» created_on	string(date-time)	false	none	Time the operation was created.
»» state	operation-state	true	none	none.
»» type	operation-type	false	none	none.
»» history	[event]	false	none	none.
»»» description	string	false	none	A human readable string describing what is happening in this step.
»»» state	string	false	none	none
»»» stage	string	false	none	The stage of the operation that succeeds this step.
»»» result	object	false	none	none.
»»» timestamp	string(date-time)	true	none	The time the event was inserted.
» pagination	any	false	none	none.

allOf


Name	Type	Required	Restrictions	Description
»» anonymous	pagination	false	none	none.
»»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»»» offset	offset	true	none	The number of records skipped before collecting the results.
»»» order_by	string	true	none	none.
»»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»»» total	integer	true	none	The total number of records available, ignoring limit and offset.

and


Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none
»»» type	string	false	none	Limit results to only operations of this type.

Enumerated values


Property	Value
state	queued
state	running
state	finished
state	failed
state	created
state	success
state	failed
order	asc
order	desc

Get a single operation

GET /v1/operations/{id}

Important: To get a single blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
last_step_index	query	operation-step-index	false	The last seen history entry for this operation. This value is used for long-polling waiting for a change in state unless the operation is finished or failed.
id	path	identifier	true	The operation in question to retrieve.

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "creator": "1dccd4a6-75d2-43aa-a088-76d941f1b60a",
  "created_on": "2019-08-24T14:15:22Z",
  "state": "queued",
  "type": "string",
  "history": [
    {
      "description": "string",
      "state": "created",
      "stage": "string",
      "result": {},
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ]
}Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns state of the operation.	operation
401	Unauthorized	Authentication failed.	not-authenticated-error
404	Not Found	Operation not found.	error

Schemas

offset

The number of records skipped before collecting the results.

0
Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	The number of records skipped before collecting the results.

limit

The maximum number of records returned. Zero indicates no limit.

1000
Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	The maximum number of records returned. Zero indicates no limit.

sort_order

The sorting direction to apply, 'asc' for ascending, 'desc' for descending.

"asc"
Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.

Enumerated values


Property	Value
anonymous	asc
anonymous	desc

one-time-window

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A user defined unique name for the window
description	string	false	none	A user defined description for the window
window_start	string(date-time)	true	none	The start of the valid period for the window. If not specified, defaults to `now`
window_end	string(date-time)	true	none	The end of the valida period of the window. If not specified, implies the end of time.

one-time-window response

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "next_instance": "2019-08-24"
}Copied!

Properties

allOf


Name	Type	Required	Restrictions	Description
anonymous	one-time-window	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» id	identifier	false	none	none
» next_instance	string(date)	false	none	The start date for this one-time-window. Not present if the time is in the past.

repeated-time-interval

{
  "name": "string",
  "description": "string",
  "series_start": "2019-08-24",
  "series_end": "2019-08-24",
  "series": {
    "cron": "string"
  }
}Copied!

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A user defined unique name for the interval
description	string	false	none	A user defined description for the interval
series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a subwindow are not valid.
» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format

repeated-time-window

{
  "name": "string",
  "description": "string",
  "series_start": "2019-08-24",
  "series_end": "2019-08-24",
  "series": {
    "cron": "string",
    "duration": {
      "amount": 1,
      "unit": "s"
    }
  }
}Copied!

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A user defined unique name for the window
description	string	false	none	A user defined description for the window
series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a subwindow are not valid.
» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format
» duration	object	true	none	none
»» amount	integer	true	none	none
»» unit	string	true	none	Unit of time: s - seconds, m - minutes, h - hours, d - days

Enumerated values


Property	Value
unit	s
unit	h
unit	m
unit	d

repeated-time-window-response

{
  "name": "string",
  "description": "string",
  "series_start": "2019-08-24",
  "series_end": "2019-08-24",
  "series": {
    "cron": "string",
    "duration": {
      "amount": 1,
      "unit": "s"
    }
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "next_instance": "2019-08-24"
}Copied!

Properties

allOf


Name	Type	Required	Restrictions	Description
anonymous	repeated-time-window	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» id	identifier	false	none	none
» next_instance	string(date)	false	none	The start date for the next instance of this window. Not present if the time is in the past.

identifier

"497f6eca-6276-4993-bfeb-53cbbbba6f08"
Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	string(uuid)	false	none	none

entity-id

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
id	identifier	false	none	none

error

{
  "kind": "string",
  "msg": "string",
  "details": {}
}Copied!

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	an indication of the type of error from a service perspective
msg	string	true	none	More detail about the error.
details	object	false	none	Detailed information about the error, payload can vary

collision-error

{
  "kind": "node-in-use",
  "msg": "A node specified in the request is already in use in a patch group",
  "details": {
    "nodes": [
      {
        "node": "string",
        "patch_group": "6b8b4f36-ff74-424f-993a-8d6fb0151c60"
      }
    ]
  }
}Copied!

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	an indication of the type of error from a service perspective.
msg	string	true	none	More detail about the error.
details	object	true	none	Detailed information about collisions.
» nodes	[object]	true	none	none.
»» node	node	true	none	none.
»» patch_group	identifier	true	none	none.

Enumerated values


Property	Value
kind	node-in-use
msg	A node specified in the request is already in use in a patch group
msg	Nodes specified in the request are already used in a patch group

content-type-error

{
  "kind": "unsupported type",
  "msg": "string"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	none
msg	string	true	none	none

Enumerated values


Property	Value
kind	unsupported type

not-authenticated-error

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	none
msg	string	true	none	none

Enumerated values


Property	Value
kind	puppetlabs.rbac/user-revoked
kind	puppetlabs.rbac/token-expired
kind	puppetlabs.rbac/token-revoked
kind	puppetlabs.rbac/invalid-token
kind	puppetlabs.rbac/user-unauthenticated

forbidden-request-error

{
  "kind": "forbidden-request",
  "msg": "string"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	none
msg	string	true	none	none

Enumerated values


Property	Value
kind	forbidden-request

node

"string"Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

base-patch-group

{
  "name": "string",
  "description": "string",
  "node_list": [
    "string"
  ],
  "maintenance_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "blackout_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}Copied!

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A unique name for the patch group
description	string	false	none	A user defined description for the group
node_list	[node]	true	none	none
maintenance_windows	[identifier]	false	none	none
blackout_windows	[identifier]	false	none	none

patch-group-response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "node_list": [
    "string"
  ],
  "maintenance_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "blackout_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "state": "pending",
  "package_updates": [
    "string"
  ],
  "security_package_updates": [
    "string"
  ],
  "last_package_update_time": "2019-08-24T14:15:22Z",
  "nodes_with_package_updates": [
    "string"
  ]
}Copied!

Properties


Name	Type	Required	Restrictions	Description
id	identifier	true	none	the unique identifier for this patch group
name	string	true	none	A unique name for the patch group
description	string	false	none	A user defined description for the group
node_list	[node]	true	none	none
maintenance_windows	[identifier]	false	none	none
blackout_windows	[identifier]	false	none	none
state	string	true	none	none
package_updates	[string]	true	none	The set of pending package updates for the nodes in the patch group
security_package_updates	[string]	true	none	The set of pending security package updates for the nodes in the patch group. These are also listed in the package_updates.
last_package_update_time	string(date-time)	false	none	none
nodes_with_package_updates	[string]	true	none	nodes in the patch group that have pending package updates.

Enumerated values


Property	Value
state	pending
state	failed
state	ready

patch-group-with-operation-response

{
  {
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "operation": "fc63ceec-84f0-4df1-a7e8-77c5f8c0b283"
}
Copied!

Properties


Name	Type	Required	Restrictions	Description
id	identifier	true	none	the unique identifier for this patch group
operation	identifier	true	none	the unique identifier for the operation associated with the creation of this patch group

event

{
  "description": "string",
  "state": "created",
  "stage": "string",
  "result": {},
  "timestamp": "2019-08-24T14:15:22Z"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
description	string	false	none	A human readable string describing what is happening in this step.
state	string	false	none	none
stage	string	false	none	The stage of the operation that succeeds this step.
result	object	false	none	none
timestamp	string(date-time)	true	none	The time the event was inserted

Enumerated values


Property	Value
state	created
state	success
state	failed

operation-step-index

An index of history in the operation, can be used with long-polling to wait for the resource to change.

0Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	An index of history in the operation, can be used with long-polling to wait for the resource to change.

operation

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "creator": "1dccd4a6-75d2-43aa-a088-76d941f1b60a",
  "created_on": "2019-08-24T14:15:22Z",
  "state": "queued",
  "type": "string",
  "history": [
    {
      "description": "string",
      "state": "created",
      "stage": "string",
      "result": {},
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ]
}Copied!

Properties


Name	Type	Required	Restrictions	Description
id	identifier	true	none	Unique identifier for this operation
creator	identifier	false	none	User id for the user responsible for starting the operation
created_on	string(date-time)	false	none	Time the operation was created
state	operation-state	true	none	State of the operation
type	operation-type	false	none	none
history	[event]	false	none	none

operation-state

"queued"Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated values


Property	Value
anonymous	queued
anonymous	running
anonymous	finished
anonymous	failed

operation-type

"string"Copied!

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

create-patch-group-payload

{
  "patch_group": {
    "name": "string",
    "description": "string",
    "node_list": [
      "string"
    ],
    "maintenance_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "blackout_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  },
  "options": {
    "force_move": false
  }
}Copied!

Properties


Name	Type	Required	Restrictions	Description
patch_group	base-patch-group	true	none	none
options	object	false	none	none
» force_move	boolean	false	none	In the case that a node exists in another patch group, a true value of this flag indicates that it is be forcibly moved from one to the other.

patch-group-validate-name-payload

{
  "name": "string"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	none

pagination

{
  "limit": 1000,
  "offset": 0,
  "order_by": "string",
  "order": "asc",
  "total": 0
}Copied!

Properties


Name	Type	Required	Restrictions	Description
limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
offset	offset	true	none	The number of records skipped before collecting the results.
order_by	string	true	none	none
order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
total	integer	true	none	The total number of records available, ignoring limit and offset

patch-job-parameters

{
  "yum_params": "string",
  "dpkg_params": "string",
  "zypper_params": "string",
  "reboot": "always",
  "timeout": 3600,
  "security_only": false,
  "clean_cache": true
}Copied!

Properties


Name	Type	Required	Restrictions	Description
yum_params	string	false	none	Any additional parameters to include in the yum upgrade command (such as including/excluding repos)
dpkg_params	string	false	none	Any additional parameters to include in the dpkg command
zypper_params	string	false	none	Any additional parameters to include in the zypper update command
reboot	string	false	none	Should the server reboot after patching has been applied? (Defaults to 'never')
timeout	integer	false	none	How many seconds we wait until timing out the patch run?
security_only	boolean	false	none	Limit patches to those tagged as security related?
clean_cache	boolean	false	none	Should the yum/dpkg caches be cleaned at the start of the task? (Defaults to false)

Enumerated values


Property	Value
reboot	always
reboot	never
reboot	patched
reboot	smart

one-time-execution

{
  "timestamp": "2019-08-24T14:15:22Z"
}Copied!

Properties


Name	Type	Required	Restrictions	Description
timestamp	string(date-time)	false	none	none

patch-job

{{
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false
}Copied!

Properties


Name	Type	Required	Restrictions	Description
description	string	false	none	none
parameters	patch-job-parameters	false	none	none
scope	object	false	none	none
» patch_group_id	string(uuid)	false	none	none
schedule	object	true	none	none
» frequency	string	true	none	How often the job runs. If `now`, the rest of the schedule is ignored, and runs at the first opportunity.

oneOf


Name	Type	Required	Restrictions	Description
» anonymous	one-time-execution	false	none	none

xor


Name	Type	Required	Restrictions	Description
» anonymous	repeated-time-interval	false	none	none

continued


Name	Type	Required	Restrictions	Description
ignore_maintenance_windows	boolean	false	none	Allow this job run outside the defined maintenance windows
ignore_blackout_windows	boolean	false	none	Allow this job run inside the defined blackout windows

Enumerated values


Property	Value
frequency	now
frequency	once
frequency	recurring

patch-job-response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false,
  "next_run_time": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4"
}Copied!

Properties

allOf


Name	Type	Required	Restrictions	Description
anonymous	entity-id	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	patch-job	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» next_run_time	string(date-time)	false	none	When the job runs next, if applicable
» created_by	string(uuid)	false	none	User id that created the job

Vulnerability Remediation API

To enable vulnerability remediation capabilities, you must acquire a Puppet Enterprise Advanced license. Contact your Puppet Enterprise administrator or Contact our sales team to acquire a license and enable this feature.

You can use the Vulnerability Remediation API to handle transformer operations and manage vulnerability data and associated results from scan reports.

The Vulnerability Remediation API accepts well-formed HTTPS requests and requires authentication
Use the Command endpoints to manage and operate the transformer and run remediation patch jobs
Use Get requests to request vulnerability data
URI path: https://${primary_host}:8146/vrs
Default port: 8146

Authentication

Token (X-Authentication Header)
Parameter Name: X-Authentication, in: header

Command endpoint

POST__v1_command_activate-transformer/{id}
POST__v1_command_delete-transformer/{id}
POST__v1_command_remediate-patch-job

The following are used only by the transformer:

POST__v1_command_add-results/{id}} Transformer scanner report
POST__v1_command_register-transformer/{id} Transformer registration

Get requests

GET/v1_transformer
GET/v1/vulnerabilities
GET/v1/vulnerabilities/{id}
GET/v1/vulnerability-nodes/{id}
GET/v1/vulnerability-patch-groups/{id}
GET/v1/node-vulnerabilities/{id}

Get a transformer

get__v1_transformer

Important: To get a transformer, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

GET /v1/transformer HTTP/1.1 
Accept: application/json Copied!

Example response

200 Response: Request was successful, returns an active/pending transformer.

{ 
  "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
  "name": "Nessus", 
  "description": "Nessus scanner transformer", 
  "status": "active", 
  "last_scan_date": "2021-07-15T10:00:00Z", 
  "last_approval_date": "2021-07-15T10:00:00Z", 
  "last_approval_request": "2021-07-15T10:00:00Z", 
  "deleted_date": "2019-08-24T14:15:22Z", 
  "last_import_date": "2021-07-15T10:00:00Z" 
} Copied!

Response format


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an active/pending transformer.	transformer-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have view permissions.	forbidden-request-error
404	Not Found	Transformer not found.	transformer-error
409	Conflict	Multiple transformers found, expected only one.	transformer-error

Get all vulnerabilities

GET /v1/vulnerabilities

Important: To get vulnerabilities, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

GET /v1/vulnerabilities HTTP/1.1 
Accept: application/json Copied!

200 Response: A list of vulnerabilities

{ 
  "vulnerabilities": [ 
    { 
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
      "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
      "severity": "Low", 
      "cvss_score": 7.5, 
      "cvss_version": "3.0", 
      "nodes_affected": 10 
    } 
  ] 
} Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an active/pending transformer.	transformer-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have view permissions.	forbidden-request-error
404	Not Found	Transformer not found.	transformer-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Get a specific vulnerability

GET /v1/vulnerabilities/{id}

Important: To get a vulnerability, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

GET /v1/vulnerabilities/{id} HTTP/1.1 
Accept: application/json Copied!

Parameters


Name	In	Type	Required	Description	Schema
id	path	string(uuid)	true	UUID of the vulnerability.	vulnerability-with-details

Example response

200 Response: A specific vulnerability.

{ 
  { 
  "vulnerability": { 
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
    "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
    "severity": "Low", 
    "cvss_score": 7.5, 
    "cvss_version": "3.0", 
    "cves": [ 
      "CVE-2021-3456" 
    ], 
    "summary": "A flaw was found in the way the TLS/SSL protocol was implemented in OpenSSL.", 
    "solution": "Upgrade the openssl packages.", 
    "packages": [ 
      "openssl" 
    ], 
    "nodes_affected": 10 
  } 
} Copied!

Response format


Status	Meaning	Description	Schema
200	OK	A specific vulnerability.	vulnerability-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have create permissions.	forbidden-request-error
404	Not Found	Vulnerability not found.	error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Get nodes with a specific vulnerability

GET /v1/vulnerability-nodes/{id}

Important:  To get nodes with a specific vulnerability, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

GET /v1/vulnerability-nodes/{id} HTTP/1.1 
Accept: application/json Copied!

Parameters


Name	In	Type	Required	Description	Schema
id	path	string(uuid)	true	UUID of the vulnerability.	nodes

Example response

200 Response: A list of vulnerability nodes.

{ 
  "nodes": [ 
    { 
      "certname": "server1.example.com", 
      "required_packages": [ 
        "openssl" 
      ], 
      "available_packages": [ 
        "openssl" 
      ], 
      "scheduled_patch": "string", 
      "patch_available": true 
    } 
  ] 
} Copied!

Response format


Status	Meaning	Description	Schema
200	OK	A list of nodes for a vulnerability.	vulnerability-nodes-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have create permissions.	forbidden-request-error
404	Not Found	Nodes not found for vulnerability.	error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Get patch groups for a specific vulnerability

GET /v1/vulnerability-patch-groups/{id}

Important: To get patch groups for a vulnerability, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

GET /v1/vulnerability-patch-groups/{id} HTTP/1.1 
Accept: application/json Copied!

Parameters


Name	In	Type	Required	Description	Schema
id	path	string(uuid)	true	UUID of the vulnerability.	groups

Example response

200 Response: A list of patch groups for the vulnerability.

{ 
  "groups": [ 
    { 
      "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
      "name": "Group 1", 
      "nodes_affected": 10, 
      "patching_scheduled": "partial", 
      "nodes_with_patches_available": 10 
    } 
  ], 
  "pagination": { 
    "limit": 1000, 
    "offset": 0, 
    "order_by": "string", 
    "order": "asc", 
    "total": 0 
  } 
} Copied!

Response format


Status	Meaning	Description	Schema
200	OK	A list of patch groups for the vulnerability.	vulnerability-patch-groups-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have create permissions.	forbidden-request-error
404	Not Found	Vulnerability patch group not found.	error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Get vulnerabilities on a specific node

GET /v1/node-vulnerabilities/{id}

Important: To get vulnerabilities on a specific node, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

GET /v1/node-vulnerabilities/{id} HTTP/1.1 
Accept: application/json Copied!

Parameters


Name	In	Type	Required	Description	Schema
id	path	string	true	Hostname of the node.	vulnerabilities

Example response

200 Response: A list of node vulnerabilities.

{ 
  "vulnerabilities": [ 
    { 
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
      "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
      "severity": "Low", 
      "cvss_score": 7.5, 
      "cvss_version": "3.0", 
      "nodes_affected": 10, 
      "patch_available": true 
    } 
  ] 
} Copied!

Response format


Status	Meaning	Description	Schema
200	OK	A list of vulnerabilities for node.	node-vulnerabilities- response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have create permissions.	forbidden-request-error
404	Not Found	Node vulnerabilities not found.	error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Transformer scan report

Used by transformer only.

post__v1_command_add-results_{id}

Important: Performing this operation requires authentication by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

POST /v1/command/add-results/{id}?scan_date=2019-08-24T14%3A15%3A22Z HTTP/1.1 
Content-Type: application/json 
Accept: application/json Copied!

Body parameter

[ 
  { 
    "hostname": "server1.example.com", 
    "ipaddress": "192.168.1.10", 
    "vulnerabilities": [ 
      { 
        "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
        "summary": "A flaw was found in the way the TLS/SSL protocol was implemented in OpenSSL.", 
        "solution": "Upgrade the openssl packages.", 
        "severity": "Low", 
        "cvss_score": 7.5, 
        "cvss_version": "3.0", 
        "packages": [ 
          "openssl-1.0.2k-19.el7" 
        ], 
        "cves": [ 
          "CVE-2021-3456" 
        ] 
      } 
    ] 
  } 
] Copied!

Parameters


Name	In	Type	Required	Description
id	path	string(uuid)	true	Transformer ID.
scanDate	query	string(date-time)	true	Date and time of the scan in ISO 8601 format.
body	body	add-results-payload	true	none

Example response

200 Response

{ 
  "kind": "success", 
  "message": "Transform run 51c88281-b3f1-459d-b21a-d729483e8f54 completed successfully" 
} Copied!

Response format


Status	Meaning	Description	Schema
201	Created	Created.	run-id
400	Bad Request	Bad request.	error
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have view permissions.	forbidden-request-error
409	Conflict	Conflict with scan date or running import.	error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Transformer registration

Used by transformer only.

post__v1_command_register-transformer_{id}

Important: Performing this operation requires authentication by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

POST /v1/command/register-transformer/{id} HTTP/1.1 
Content-Type: application/json 
Accept: application/json  Copied!

Body parameter

{ 
  "name": "Nessus", 
  "description": "Nessus transformer" 
} Copied!

Parameters


Name	In	Type	Required	Description
id	path	string(uuid)	true	Transformer ID.
body	body	register-transformer-payload	true	none

Example response

200 Response

{ 
  "status": "pending" 
} Copied!

Response format


Status	Meaning	Description	Schema
200	OK	Transformer is active.	register-transformer-response
202	Accepted	Transformer registration pending.	register-transformer-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have view permissions.	forbidden-request-error
409	Conflict	Conflict with existing transformer.	transformer-error

Activate a transformer

post__v1_command_activate-transformer_{id}

Important:  To activate a transformer, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

POST /v1/command/activate-transformer/{id} HTTP/1.1  
Accept: application/json  Copied!

Parameters


Name	In	Type	Required	Description
id	path	string(uuid)	true	Transformer ID.

Example response

200 Response

{ 
  "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
  "name": "Nessus", 
  "description": "Nessus scanner transformer", 
  "status": "active", 
  "last_scan_date": "2021-07-15T10:00:00Z", 
  "last_approval_date": "2021-07-15T10:00:00Z", 
  "last_approval_request": "2021-07-15T10:00:00Z", 
  "deleted_date": "2019-08-24T14:15:22Z", 
  "last_import_date": "2021-07-15T10:00:00Z" 
} Copied!

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an active transformer.	transformer-response
400	Bad Request	Invalid Transformer ID.	None
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have view permissions.	forbidden-request-error
404	Not Found	Transformer not found.	transformer-error
409	Conflict	Conflict with existing transformer.	transformer-error

Delete transformer

post__v1_command_delete-transformer_{id}

Important: To delete a transformer, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

POST /v1/command/delete-transformer/{id} HTTP/1.1   
Accept: application/json  Copied!

Parameters


Name	In	Type	Required	Description
id	path	string(uuid)	true	Transformer ID.

Example response

200 Response

{ 
  "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
  "name": "Nessus", 
  "description": "Nessus scanner transformer", 
  "status": "deleted", 
  "last_scan_date": "2021-07-15T10:00:00Z", 
  "last_approval_date": "2021-07-15T10:00:00Z", 
  "last_approval_request": "2021-07-15T10:00:00Z", 
  "deleted_date": "2021-07-15T10:00:00Z", 
  "last_import_date": "2021-07-15T10:00:00Z" 
} Copied!

Responses


Status	Meaning	Description	Schema
201	Created	Created.	remediate-patch-job-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have create permissions.	forbidden-request-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Create a patch job to perform remediation

post_v1_command_remediate-patch-job

Important: To create a remediation patch job, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Example

POST /v1/command/remediate-patch-job HTTP/1.1 
Content-Type: application/json   
Accept: application/json  Copied!

Request format

 {           
  "description": "Patch job for group 1", 
  "parameters": { 
    "yum_params": "string", 
    "dpkg_params": "string", 
    "zypper_params": "string", 
    "reboot": "always", 
    "timeout": 3600, 
    "security_only": false, 
    "clean_cache": true 
  }, 
  "scope": { 
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260" 
  }, 
  "schedule": { 
    "timestamp": "2024-12-18T10:00:00Z" 
  }, 
  "ignore_maintenance_windows": false, 
  "ignore_blackout_windows": false, 
  "certnames": [ 
    "string" 
  ],
  "vulnerabilities": [ 
    "string" 
  ] 
} Copied!

Parameters


Name	In	Type	Required	Description
body	body	remediate-patch-job-payload	true	none

Example response

201 Response

{ 
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" 
} Copied!

Response format


Status	Meaning	Description	Schema
201	Created	Created.	remediate-patch-job-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requestor does not have create permissions.	forbidden-request-error

Vulnerability Remediation schemas

The following schemas can be found here:

bad-request-error

{ 
  "kind": "unsupported type", 
  "msg": [ 
    [ 
      "Missing required field: 'severity'", 
      "Invalid value for 'scan_date': '2021-07-15T10:00:00Z' is not a valid date-time." 
    ] 
  ] 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	none
msg	string	true	none	none

Enumerated values


Property	Value
kind	bad request

transformer-error

{ 
  "message": "string" 
}Copied!

Properties


Name	Type	Required	Restrictions	Description
msg	string	true	none	none

cves

[ 
  "CVE-2021-3456" 
] Copied!

Properties

None

packages

[ 
  "openssl" 
] Copied!

Properties

None

nodes

[ 
  { 
    "certname": "server1.example.com", 
    "required_packages": [ 
      "openssl" 
    ], 
    "available_packages": [ 
      "openssl" 
    ], 
    "scheduled_patch": "string", 
    "patch_available": true 
  } 
] Copied!

Properties


Name	Type	Required	Restrictions	Description
certname	string	true	none	Certname of the node.
required_packages	[string]	true	none	Packages required for the vulnerability.
available_packages	[string]	true	none	Available packages for the node.
scheduled_patch	string	true	none	none
patch_available	boolean	true	none	Whether a patch is available for the vulnerability.

groups

[ 
  { 
    "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
    "name": "Group 1", 
    "nodes_affected": 10, 
    "patching_scheduled": "partial", 
    "nodes_with_patches_available": 10 
  }
] Copied!

Properties


Name	Type	Required	Restrictions	Description
id	string($uuid)	true	none	ID of the group.
name	string	true	none	Name of the group.
nodes_affected	string	false	none	Number of nodes affected by the vulnerability.
patching_scheduled	string	false	none	Whether there are patches scheduled for the group.
nodes_with_patches_available	number	false	none	Number of nodes with patches available.

add-results-vulnerability

{ 
  "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
  "summary": "A flaw was found in the way the TLS/SSL protocol was implemented in OpenSSL.", 
  "solution": "Upgrade the openssl packages.", 
  "severity": "Low", 
  "cvss_score": 7.5, 
  "cvss_version": "3.0", 
  "packages": [ 
    "openssl" 
  ], 
  "cves": [ 
    "CVE-2021-3456" 
  ] 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	Name of the vulnerability.
summary	string	true	none	Summary of the vulnerability.
solution	string	true	none	Solution to the vulnerability.
severity	string	true	none	none.
cvss_score	number($float)	true	none	Common Vulnerability Scoring System (CVSS) score.
cvss_version	string	true	none	Common Vulnerability Scoring System (CVSS) version.
packages	[string]	false	none	List of packages affected by the vulnerability.
cves	[string]	true	none	List of CVEs associated with the vulnerability.

Enumerated values


Property	Value
severity	Low
severity	Medium
severity	High
severity	Critical

add-results-payload

{ 
  "hostname": "server1.example.com", 
  "ipaddress": "192.168.1.10", 
  "vulnerabilities": [ 
    { 
      "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
      "summary": "A flaw was found in the way the TLS/SSL protocol was implemented in OpenSSL.", 
      "solution": "Upgrade the openssl packages.", 
      "severity": "Low", 
      "cvss_score": 7.5, 
      "cvss_version": "3.0", 
      "packages": [ 
        "openssl" 
      ], 
      "cves": [ 
        "CVE-2021-3456" 
      ] 
    } 
  ] 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
hostname	string	false	none	Hostname of the node.
ipaddress	String(ipv4)	true	none	IP address of the node.
vulnerabilities	add-results-vulnerability	true	none	List of CVEs associated with the node.

add-results-response

{ 
  "kind": "success", 
  "message": "Transform run 51c88281-b3f1-459d-b21a-d729483e8f54 completed successfully" 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	Status of the request.
message	string	true	none	Status of the request.

register-transformer-payload

{ 
  "name": "Nessus", 
  "description": "Nessus transformer" 
} Copied!

register-transformer-payload


Name	Type	Required	Restrictions	Description
name	string	true	none	A unique name for the transformer.
description	string	false	none	A transformer defined description for the transformer.

register-transformer-response

{ 
  "status": "pending" 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
status	string	true	none	Status of the transformer.

transformer-response

{ 
  "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
  "name": "Nessus", 
  "description": "Nessus scanner transformer", 
  "status": "active", 
  "last_scan_date": "2021-07-15T10:00:00Z", 
  "last_approval_date": "2021-07-15T10:00:00Z", 
  "last_approval_request": "2021-07-15T10:00:00Z", 
  "deleted_date": "2019-08-24T14:15:22Z", 
  "last_import_date": "2021-07-15T10:00:00Z" 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
id	string	true	none	Unique ID of the transformer.
name	string	true	none	Name of the transformer.
description	string	false	none	Description of the transformer.
status	string	true	none	Status of the transformer.
last_scan_date	string (date-time)	false	none	Date and time of last approval.
last_approval_date	string(date-time)	false	none	Date and time of last approval.
last_approval_request	string(date-time)	false	none	Date and time of last approval request.
deleted_date	string(date-time)	false	none	Date and time of last deletion.
last_import_date	string(date-time)	false	none	Date and time of last import.

transformer-deleted-response

{ 
  "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
  "name": "Nessus", 
  "description": "Nessus scanner transformer", 
  "status": "deleted", 
  "last_scan_date": "2021-07-15T10:00:00Z", 
  "last_approval_date": "2021-07-15T10:00:00Z", 
  "last_approval_request": "2021-07-15T10:00:00Z", 
  "deleted_date": "2021-07-15T10:00:00Z", 
  "last_import_date": "2021-07-15T10:00:00Z" 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
id	string	true	none	Unique ID of the transformer.
name	string	true	none	Name of the transformer.
description	string	false	none	Description of the transformer.
status	string	true	none	Status of the transformer.
last_scan_date	string (date-time)	false	none	Date and time of last approval.
last_approval_date	string(date-time)	false	none	Date and time of last approval.
last_approval_request	string(date-time)	false	none	Date and time of last approval request.
deleted_date	string(date-time)	false	none	Date and time of last deletion.
last_import_date	string(date-time)	false	none	Date and time of last import.

remediate-patch-job-parameters

{ 
  "yum_params": "string", 
  "dpkg_params": "string", 
  "zypper_params": "string", 
  "reboot": "always", 
  "timeout": 3600, 
  "security_only": false, 
  "clean_cache": true 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
yum_params	string	false	none	Any additional parameters to include in the yum upgrade command (such as including/excluding repos).
dpkg_params	string	false	none	Any additional parameters to include in the dpkg command.
zypper_params	string	false	none	Any additional parameters to include in the zypper update command.
reboot	string	false	none	Whether the server reboots after patching has been applied (Default to ‘never’).
timeout	integer	false	none	The number of seconds to wait before timing out the patch run.
security_only	boolean	false	none	Whether to limit patches to those tagged as security related.
clean_cache	boolean	false	none	Whether the yum/dpkg caches should be cleaned at the start of the task (Default to ‘false’).

Enumerated values


Property	Value
reboot	always
reboot	never
reboot	patched
reboot	smart

remediate-patch-job

{ 
  "jobId": "string", 
  "updates": [ 
    { 
      "hostnames": [ 
        "string" 
      ], 
      "packages": [ 
        "string" 
      ] 
    } 
  ] 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
jobID	string	false	none	None
updates	[object]	false	none	None
hostnames	[string]	false	none	None
packages	[string]	false	none	None

remediate-patch-job-payload

{ 
  "description": "Patch job for group 1", 
  "parameters": { 
    "yum_params": "string", 
    "dpkg_params": "string", 
    "zypper_params": "string", 
    "reboot": "always", 
    "timeout": 3600, 
    "security_only": false, 
    "clean_cache": true 
  }, 
  "scope": { 
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260" 
  }, 
  "schedule": { 
    "timestamp": "2024-12-18T10:00:00Z" 
  }, 
  "ignore_maintenance_windows": false, 
  "ignore_blackout_windows": false, 
  "certnames": [ 
    "string" 
  ], 
  "vulnerabilities": [ 
    "string" 
  ] 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
description	string	false	none	Description of the patch job.
parameters	remediate-patch-job-parameters	true	none	none
scope	object	true	none	none
patch_group_id	string(uuid)	false	none	none
schedule	object	false	none	Schedule for the patch job.
timestamp	string (date-time)	false	none	The specific time when the patch job should be executed (optional).
ignore_maintenance_windows	boolean	false	none	Allow this job run outside the defined maintenance windows.
ignore_blackout_windows	boolean	false	none	Allow this job run inside the defined blackout windows.
certnames	[string]	true	none	List of certnames to run the patch job on.
vulnerabilities	[string]	true	none	List of vulnerabilities to run the patch job on.

remediate-patch-job-response

{ 
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
id	string (uuid)	true	none	none

vulnerability-details

{ 
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
  "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
  "severity": "Low", 
  "cvss_score": 7.5, 
  "cvss_version": "3.0", 
  "cves": [ 
    "CVE-2021-3456" 
  ], 
  "summary": "A flaw was found in the way the TLS/SSL protocol was implemented in OpenSSL.", 
  "solution": "Upgrade the openssl packages.", 
  "packages": [ 
    "openssl" 
  ], 
  "nodes_affected": 10 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
id	string($uuid)	true	none	None
name	string	true	none	Name of the vulnerability.
severity	string	true	none	None
cvss_score	number($float)	true	none	Common Vulnerability Scoring System (CVSS) score.
cvss_version	string	true	none	Common Vulnerability Scoring System (CVSS) version.
cves	[string]	true	none	List of CVEs associated with the vulnerability.
summary	string	true	none	Summary of the vulnerability.
solution	string	true	none	Solution to the vulnerability.
packages	[string]	false	none	List of packages affected by the vulnerability.
nodes_affected	number	false	none	Number of nodes affected by the vulnerability.

Enumerated values


Property	Value
severity	Low
severity	Medium
severity	High
severity	Critical

node-vulnerability

{ 
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
  "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
  "severity": "Low", 
  "cvss_score": 7.5, 
  "cvss_version": "3.0", 
  "nodes_affected": 10, 
  "patch_available": true 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
id	string($uuid)	true	none	None
name	string	true	none	Name of the vulnerability.
severity	string	true	none	None
cvss_score	number($float)	true	none	Common Vulnerability Scoring System (CVSS) score.
cvss_version	string	true	none	Common Vulnerability Scoring System (CVSS) version.
nodes-affected	number	true	none	Number of nodes affected.
patch_available	boolean	false	none	Whether a patch is available.

Enumerated values


Property	Value
severity	Low
severity	Medium
severity	High
severity	Critical

node-vulnerabilities

[ 
  { 
    "hostname": "string", 
    "ipaddress": "192.168.0.1", 
    "vulnerabilities": [ 
      { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
        "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
        "severity": "Low", 
        "cvss_score": 7.5, 
        "cvss_version": "3.0", 
        "cves": [ 
          "CVE-2021-3456" 
        ], 
        "summary": "A flaw was found in the way the TLS/SSL protocol was implemented in OpenSSL.", 
        "solution": "Upgrade the openssl packages.", 
        "packages": [ 
          "openssl" 
        ], 
        "nodes_affected": 10 
      } 
    ] 
  } 
] Copied!

Properties


Name	Type	Required	Restrictions	Description
hostname	string	true	none	none
ipaddress	string(ipv4)	true	none	none
vulnerabilities	vulnerability-details	true	none	none

vulnerabilities-response

[ 
  { 
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
    "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
    "severity": "Low", 
    "cvss_score": 7.5, 
    "cvss_version": "3.0", 
    "nodes_affected": 10 
  } 
] Copied!

Properties


Name	Type	Required	Restrictions	Description
id	string($uuid)	true	none	None
name	string	true	none	Name of the vulnerability.
severity	string	true	none	None
cvss_score	number($float)	true	none	Common Vulnerability Scoring System (CVSS) score.
cvss_version	string	true	none	Common Vulnerability Scoring System (CVSS) version.
nodes-affected	number	true	none	Number of nodes affected.

Enumerated values


Property	Value
severity	Low
severity	Medium
severity	High
severity	Critical

vulnerability-response

{ 
  "vulnerability": { 
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
    "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
    "severity": "Low", 
    "cvss_score": 7.5, 
    "cvss_version": "3.0", 
    "cves": [ 
      "CVE-2021-3456" 
    ], 
    "summary": "A flaw was found in the way the TLS/SSL protocol was implemented in OpenSSL.", 
    "solution": "Upgrade the openssl packages.", 
    "packages": [ 
      "openssl" 
    ], 
    "nodes_affected": 10 Copied!

Properties


Name	Type	Required	Restrictions	Description
vulnerability	vulnerability-details	false	none	None

vulnerability-nodes-response

{ 
  "nodes": [ 
    { 
      "certname": "server1.example.com", 
      "required_packages": [ 
        "openssl" 
      ], 
      "available_packages": [ 
        "openssl" 
      ], 
      "scheduled_patch": "string", 
      "patch_available": true 
    } 
  ] 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
nodes	nodes	false	none	None

vulnerability-patch-groups-response

{ 
  "groups": [ 
    { 
      "id": "349d0d1e-4372-4bd8-9509-11bad057646", 
      "name": "Group 1", 
      "nodes_affected": 10, 
      "patching_scheduled": "partial", 
      "nodes_with_patches_available": 10 
    } 
  ], 
  "pagination": { 
    "limit": 1000, 
    "offset": 0, 
    "order_by": "string", 
    "order": "asc", 
    "total": 0 
  } 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
groups	groups	false	none	None
pagination	pagination	false	none	None

node-vulnerabilities-response

{ 
  "vulnerabilities": [ 
    { 
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
      "name": "Ubuntu 20.04: openssl(RHSA-2024:0)", 
      "severity": "Low", 
      "cvss_score": 7.5, 
      "cvss_version": "3.0", 
      "nodes_affected": 10, 
      "patch_available": true 
    } 
  ] 
} Copied!

Properties


Name	Type	Required	Restrictions	Description
vulnerabilities	node-vulnerability	false	none	None

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

Please enter your feedback and contact email

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.