From 79e15064e2c18f7f358cb6f300878d5b227ed439 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 27 Feb 2025 12:55:37 -0500 Subject: [PATCH 1/5] Adding operations for Delta engine Adding API endpoints to describe: - operation to run an evaluation and provide results - operation to record a item to be skipped - operation to remove reference to skipped - operation to restore value for entire item or single property --- SHIELD.json | 247 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) diff --git a/SHIELD.json b/SHIELD.json index 1ddc605..44d1454 100644 --- a/SHIELD.json +++ b/SHIELD.json @@ -109,6 +109,30 @@ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } + }, + "configId": { + "description": "Reference of the configuration property in the template used during deploy.Reference of the configuration property in the template used during deploy.", + "in": "query", + "name": "configId", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "example": "42ff150d-2ff0-4b38-849e-fe6aa5eedb49" + } + }, + "path": { + "description": "Location of the item in the object structure flattened for predictable navigation.", + "in": "query", + "name": "path", + "required": true, + "schema": { + "type": "string", + "example": "roleScopeTagIds" + } } }, "responses": { @@ -770,6 +794,51 @@ "example": "Privileged", "title": "Type of security class the object(s) belongs to", "type": "string" + }, + "Shield.Deploy.Delta.Restore": { + "title": "SHIELD - Deploy - Delta - Restore", + "description": "Payload expected for Restore operation", + "type": "object", + "properties": { + "configId": { + "description": "Reference of the configuration property in the template used during deploy.Reference of the configuration property in the template used during deploy.", + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "example": "8c9befc8-b25b-44b6-9778-350d7c511557" + }, + "path": { + "description": "Location of the item in the object structure flattened for predictable navigation.", + "type": "string", + "example": "displayName" + } + }, + "required": [ "configId", "path" ] + + }, + "Shield.Deploy.Delta.Skip": { + "title": "SHIELD - Deploy - Delta - Skip", + "description": "Payload expected for Skip operation", + "type": "object", + "properties": { + "configId": { + "description": "Reference of the configuration property in the template used during deploy.Reference of the configuration property in the template used during deploy.", + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "example": "42ff150d-2ff0-4b38-849e-fe6aa5eedb49" + }, + "path": { + "description": "Location of the item in the object structure flattened for predictable navigation.", + "type": "string", + "example": "roleScopeTagIds" + } + }, + "required": [ "configId", "path" ] } }, "securitySchemes": { @@ -1282,6 +1351,184 @@ "security": [] } }, + "/API/Deploy/Delta": { + "get": { + "summary": "Initiate evaluation for configuration discrepancies", + "description": "Runs the comparison between configuration templates and live data to find discrepancies to be addressed.", + "operationId": "/API/Deploy/Delta/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "invalid": { + "additionalProperties": { + "description": "String with details of the error response.", + "type": "string" + }, + "description": "Collection of the configuration items where request for live data responded with error.", + "type": "object" + }, + "missing": { + "additionalProperties": { + "description": "String indicating name and description of the configuration item.", + "type": "string" + }, + "description": "Collection of the configuration items that are present in the template but do not have reference to indicate they were deployed.", + "type": "object" + }, + "results": { + "additionalProperties": { + "items": { + "properties": { + "actions": { + "items": { + "type": "string" + }, + "description": "List of operations available to be performed on the entity.", + "type": "array", + "minItems": 1 + }, + "message": { + "description": "Detailed information about the discrepancy for the entity.", + "type": "string" + }, + "path": { + "description": "Location in the object where evaluated property encountered an error.", + "type": "string" + } + }, + "type": "object", + "required": [ "actions", "message", "path" ] + }, + "type": "array" + }, + "description": "Collection of the configuration items where discrepancies where found.", + "type": "object" + } + }, + "type": "object", + "required": [ "invalid", "missing", "results"], + "example": { + "invalid": { + "a14402b8-98c5-41e3-ba99-e5e1a536f68d": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found.", + "9af9209d-d191-4b42-9f65-dfd8b7882bba": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + }, + "missing": { + "78afd77c-c2a6-4328-9c61-b9fd44114823": "Microsoft.Policies.PowerToysMicrosoft.Policies.PowerToys - Version 0.86.0" + }, + "results": { + "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86": [ + { + "actions": [ "ignore", "restore" ], + "message": "Value mismatch for property 'displayName' with current value being 'Audit Platform and Configuration Updates2'", + "path": "displayName" + }, + { + "actions": [ "ignore" ], + "message": "Expected object at level 'groupPolicyUploadedLanguageFiles', but encountered 'Array'", + "path": "groupPolicyUploadedLanguageFiles" + } + ], + "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4": [ + { + "actions": [ "restore" ], + "message": "Array value at level 'roleScopeTagIds/1' is not found in the returned value", + "path": "roleScopeTagIds/1" + } + ] + } + } + } + } + }, + "description": "OK" + } + }, + "tags": [ + "Delta" + ] + } + }, + "/API/Deploy/Delta/Restore": { + "patch": { + "summary": "Restores the intended structure", + "description": "Applies a change to restore configuration item or its property to the value from the template.", + "operationId": "/API/Deploy/Delta/Restore/Patch", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Shield.Deploy.Delta.Restore" + } + } + } + }, + "responses": { + "204":{ + "description": "Restoration of configuration item or its property is successful" + }, + "400": { + "description": "The body does not match expected format!" + } + }, + "tags": [ + "Delta" + ] + } + }, + "/API/Deploy/Delta/Skip": { + "post": { + "summary": "Records intention to bypass evaluation", + "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.", + "operationId": "/API/Deploy/Delta/Skip/Post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Shield.Deploy.Delta.Skip" + } + } + } + }, + "responses": { + "204":{ + "description": "Recorded successfully" + }, + "400": { + "description": "The body does not match expected format!" + } + }, + "tags": [ + "Delta" + ] + }, + "delete": { + "summary": "Removes entry that allowed to bypass evaluation", + "description": "Deletes the reference to the entity so that evaluation process does not skip over it.", + "operationId": "/API/Deploy/Delta/Skip/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/configId" + }, + { + "$ref": "#/components/parameters/path" + } + ], + "responses": { + "204":{ + "description": "Record has been removed successfully" + }, + "400": { + "description": "Required fields are not found among query parameters!" + } + }, + "tags": [ + "Delta" + ] + } + }, "/API/Deploy/Version": { "get": { "description": "Gets the version of the API server and the architecture version deployed as well as the supported version of the architecture spec from the server.", From 859aa28b02f2675af514bcec927da90d92fbd2c2 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 20 Mar 2025 16:36:06 -0400 Subject: [PATCH 2/5] Adjusting endpoints Updating endpoints to reflect new schema. Enhancing descriptions for clarity and to include relevant information. Adding new endpoint definition. --- SHIELD.json | 140 +++++++++++++++++++++++++++------------------------- 1 file changed, 74 insertions(+), 66 deletions(-) diff --git a/SHIELD.json b/SHIELD.json index 1a5cf3d..9e53227 100644 --- a/SHIELD.json +++ b/SHIELD.json @@ -125,8 +125,8 @@ } }, "configId": { - "description": "Reference of the configuration property in the template used during deploy.Reference of the configuration property in the template used during deploy.", - "in": "query", + "description": "Reference of the configuration property in the architecture template used during deploy.", + "in": "path", "name": "configId", "required": true, "schema": { @@ -137,16 +137,6 @@ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "example": "42ff150d-2ff0-4b38-849e-fe6aa5eedb49" } - }, - "path": { - "description": "Location of the item in the object structure flattened for predictable navigation.", - "in": "query", - "name": "path", - "required": true, - "schema": { - "type": "string", - "example": "roleScopeTagIds" - } } }, "responses": { @@ -1046,50 +1036,18 @@ "title": "Type of security class the object(s) belongs to", "type": "string" }, - "Shield.Deploy.Delta.Restore": { - "title": "SHIELD - Deploy - Delta - Restore", - "description": "Payload expected for Restore operation", - "type": "object", - "properties": { - "configId": { - "description": "Reference of the configuration property in the template used during deploy.Reference of the configuration property in the template used during deploy.", - "type": "string", - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "example": "8c9befc8-b25b-44b6-9778-350d7c511557" - }, - "path": { - "description": "Location of the item in the object structure flattened for predictable navigation.", - "type": "string", - "example": "displayName" - } - }, - "required": [ "configId", "path" ] - - }, - "Shield.Deploy.Delta.Skip": { - "title": "SHIELD - Deploy - Delta - Skip", - "description": "Payload expected for Skip operation", + "Shield.Deploy.Delta.Action": { + "title": "SHIELD - Deploy - Delta - Action", + "description": "Payload expected for various operations related to Delta Engine", "type": "object", "properties": { - "configId": { - "description": "Reference of the configuration property in the template used during deploy.Reference of the configuration property in the template used during deploy.", - "type": "string", - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "example": "42ff150d-2ff0-4b38-849e-fe6aa5eedb49" - }, "path": { - "description": "Location of the item in the object structure flattened for predictable navigation.", + "description": "Location of the item in the object structure of the architecture reference template flattened for predictable navigation.", "type": "string", - "example": "roleScopeTagIds" + "example": "/roleScopeTagIds" } }, - "required": [ "configId", "path" ] + "required": [ "path" ] } }, "securitySchemes": { @@ -1750,10 +1708,10 @@ "security": [] } }, - "/API/Deploy/Delta": { + "/API/Deploy/Delta/": { "get": { "summary": "Initiate evaluation for configuration discrepancies", - "description": "Runs the comparison between configuration templates and live data to find discrepancies to be addressed.", + "description": "Runs the comparison between configuration templates and live data to find discrepancies to be addressed. Returns results split into several categories.\n\nThis endpoint requires the `Deploy.Read`, or `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Get", "responses": { "200": { @@ -1850,16 +1808,21 @@ ] } }, - "/API/Deploy/Delta/Restore": { + "/API/Deploy/Delta/Restore/{configId}/": { "patch": { "summary": "Restores the intended structure", - "description": "Applies a change to restore configuration item or its property to the value from the template.", - "operationId": "/API/Deploy/Delta/Restore/Patch", + "description": "Applies a change to restore configuration item or its property to the value from the template.\n\nThis endpoint requires the `Deploy.ReadWrite` scope (permission).", + "operationId": "/API/Deploy/Delta/Restore/:configId/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/configId" + } + ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Shield.Deploy.Delta.Restore" + "$ref": "#/components/schemas/Shield.Deploy.Delta.Action" } } } @@ -1877,16 +1840,55 @@ ] } }, - "/API/Deploy/Delta/Skip": { + "/API/Deploy/Delta/Skip/": { + "get": { + "summary": "Retrieve list of existing override rules.", + "description": "Retrieves the details of override property in the Settings Engine and returns list grouped by architecture reference.\n\nThis endpoint requires `Deploy.Read`, or `Deploy.ReadWrite` scope (permission).", + "operationId": "/API/Deploy/Delta/Skip/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string", + "description": "Flat path representing entire item or specific nested property in the architecture configuration template item." + } + }, + "description": "Collection of object with UUID string as property name and array of strings as value.", + "example": { + "f47ac10b-58cc-4372-a567-0e02b2c3d479": ["/"], + "9c858901-8a57-4791-81fe-4c455b099bc9": ["/description", "/name"] + } + } + } + }, + "description": "OK" + } + }, + "tags": [ + "Delta" + ] + } + }, + "/API/Deploy/Delta/Skip/{configId}/": { "post": { "summary": "Records intention to bypass evaluation", - "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.", - "operationId": "/API/Deploy/Delta/Skip/Post", + "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.\n\nThis endpoint requires the `Deploy.ReadWrite` scope (permission).", + "operationId": "/API/Deploy/Delta/Skip/:configId/Post", + "parameters": [ + { + "$ref": "#/components/parameters/configId" + } + ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Shield.Deploy.Delta.Skip" + "$ref": "#/components/schemas/Shield.Deploy.Delta.Action" } } } @@ -1905,16 +1907,22 @@ }, "delete": { "summary": "Removes entry that allowed to bypass evaluation", - "description": "Deletes the reference to the entity so that evaluation process does not skip over it.", - "operationId": "/API/Deploy/Delta/Skip/Delete", + "description": "Deletes the reference to the entity so that evaluation process does not skip over it.\n\nThis endpoint requires the `Deploy.ReadWrite` scope (permission).", + "operationId": "/API/Deploy/Delta/Skip/:configId/Delete", "parameters": [ { "$ref": "#/components/parameters/configId" - }, - { - "$ref": "#/components/parameters/path" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Shield.Deploy.Delta.Action" + } + } + } + }, "responses": { "204":{ "description": "Record has been removed successfully" @@ -1928,7 +1936,7 @@ ] } }, - "/API/Deploy/Version": { + "/API/Deploy/Version/": { "get": { "description": "Gets the version of the API server and the architecture version deployed as well as the supported version of the architecture spec from the server.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Version/Get", From ab75d61f2636261e8ed02f5635e4905b10c4ae60 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Tue, 25 Mar 2025 15:30:53 -0400 Subject: [PATCH 3/5] Adjust for API changes Split operation into 2 endpoints with different behavior for the existing one Extract common response object --- SHIELD.json | 205 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 123 insertions(+), 82 deletions(-) diff --git a/SHIELD.json b/SHIELD.json index 9e53227..cddf97c 100644 --- a/SHIELD.json +++ b/SHIELD.json @@ -1036,6 +1036,97 @@ "title": "Type of security class the object(s) belongs to", "type": "string" }, + "Shield.Deploy.Delta.Response": { + "title": "SHIELD - Deploy - Delta - Response", + "description": "Object returned as a result of query for cached data or re-evaluation operation.", + "type": "object", + "properties": { + "invalid": { + "additionalProperties": { + "description": "String with details of the error response.", + "type": "string" + }, + "description": "Collection of the configuration items where request for live data responded with error.", + "type": "object" + }, + "lastRunTimestamp": { + "description": "Point in time expressed in ISO 8601 format when the evaluation results were generated last. ", + "example": "2025-03-25T14:28:54Z", + "type": "string", + "format": "date-time", + "nullable": true + }, + "missing": { + "additionalProperties": { + "description": "String indicating name and description of the configuration item.", + "type": "string" + }, + "description": "Collection of the configuration items that are present in the template but do not have reference to indicate they were deployed.", + "type": "object" + }, + "results": { + "additionalProperties": { + "items": { + "properties": { + "actions": { + "items": { + "type": "string" + }, + "description": "List of operations available to be performed on the entity.", + "type": "array", + "minItems": 1 + }, + "message": { + "description": "Detailed information about the discrepancy for the entity.", + "type": "string" + }, + "path": { + "description": "Location in the object where evaluated property encountered an error.", + "type": "string" + } + }, + "type": "object", + "required": [ "actions", "message", "path" ] + }, + "type": "array" + }, + "description": "Collection of the configuration items where discrepancies where found.", + "type": "object" + } + }, + "required": [ "invalid", "lastRunTimestamp", "missing", "results"], + "example": { + "invalid": { + "a14402b8-98c5-41e3-ba99-e5e1a536f68d": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found.", + "9af9209d-d191-4b42-9f65-dfd8b7882bba": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + }, + "lastRunTimestamp": "2025-03-25T14:28:54Z", + "missing": { + "78afd77c-c2a6-4328-9c61-b9fd44114823": "Microsoft.Policies.PowerToysMicrosoft.Policies.PowerToys - Version 0.86.0" + }, + "results": { + "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86": [ + { + "actions": [ "ignore", "restore" ], + "message": "Value mismatch for property 'displayName' with current value being 'Audit Platform and Configuration Updates2'", + "path": "displayName" + }, + { + "actions": [ "ignore" ], + "message": "Expected object at level 'groupPolicyUploadedLanguageFiles', but encountered 'Array'", + "path": "groupPolicyUploadedLanguageFiles" + } + ], + "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4": [ + { + "actions": [ "restore" ], + "message": "Array value at level 'roleScopeTagIds/1' is not found in the returned value", + "path": "roleScopeTagIds/1" + } + ] + } + } + }, "Shield.Deploy.Delta.Action": { "title": "SHIELD - Deploy - Delta - Action", "description": "Payload expected for various operations related to Delta Engine", @@ -1710,93 +1801,43 @@ }, "/API/Deploy/Delta/": { "get": { - "summary": "Initiate evaluation for configuration discrepancies", - "description": "Runs the comparison between configuration templates and live data to find discrepancies to be addressed. Returns results split into several categories.\n\nThis endpoint requires the `Deploy.Read`, or `Deploy.ReadWrite` scope (permission).", + "summary": "Retrieves cached evaluation results", + "description": "Retrieves cached results of the comparison between configuration templates and live data to find discrepancies to be addressed. Results split into several categories and include timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.Read`, or `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Get", "responses": { "200": { "content": { "application/json": { "schema": { - "properties": { - "invalid": { - "additionalProperties": { - "description": "String with details of the error response.", - "type": "string" - }, - "description": "Collection of the configuration items where request for live data responded with error.", - "type": "object" - }, - "missing": { - "additionalProperties": { - "description": "String indicating name and description of the configuration item.", - "type": "string" - }, - "description": "Collection of the configuration items that are present in the template but do not have reference to indicate they were deployed.", - "type": "object" - }, - "results": { - "additionalProperties": { - "items": { - "properties": { - "actions": { - "items": { - "type": "string" - }, - "description": "List of operations available to be performed on the entity.", - "type": "array", - "minItems": 1 - }, - "message": { - "description": "Detailed information about the discrepancy for the entity.", - "type": "string" - }, - "path": { - "description": "Location in the object where evaluated property encountered an error.", - "type": "string" - } - }, - "type": "object", - "required": [ "actions", "message", "path" ] - }, - "type": "array" - }, - "description": "Collection of the configuration items where discrepancies where found.", - "type": "object" - } - }, - "type": "object", - "required": [ "invalid", "missing", "results"], - "example": { - "invalid": { - "a14402b8-98c5-41e3-ba99-e5e1a536f68d": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found.", - "9af9209d-d191-4b42-9f65-dfd8b7882bba": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." - }, - "missing": { - "78afd77c-c2a6-4328-9c61-b9fd44114823": "Microsoft.Policies.PowerToysMicrosoft.Policies.PowerToys - Version 0.86.0" - }, - "results": { - "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86": [ - { - "actions": [ "ignore", "restore" ], - "message": "Value mismatch for property 'displayName' with current value being 'Audit Platform and Configuration Updates2'", - "path": "displayName" - }, - { - "actions": [ "ignore" ], - "message": "Expected object at level 'groupPolicyUploadedLanguageFiles', but encountered 'Array'", - "path": "groupPolicyUploadedLanguageFiles" - } - ], - "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4": [ - { - "actions": [ "restore" ], - "message": "Array value at level 'roleScopeTagIds/1' is not found in the returned value", - "path": "roleScopeTagIds/1" - } - ] - } - } + "$ref": "#/components/schemas/Shield.Deploy.Delta.Response" + } + } + }, + "description": "OK" + } + }, + "tags": [ + "Delta" + ] + } + }, + "/API/Deploy/Delta/Check": { + "post": { + "summary": "Performs evaluation and return results", + "description": "Initiates evaluation process to calculate and return the results of the comparison between configuration templates and live data to find discrepancies to be addressed. Results split into several categories and include timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.ReadWrite` scope (permission).", + "operationId": "/API/Deploy/Delta/Check/Post", + "requestBody": { + "description": "No payload is expected or needed for this operation", + "content": { + "application/json": {} + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Shield.Deploy.Delta.Response" } } }, @@ -1842,7 +1883,7 @@ }, "/API/Deploy/Delta/Skip/": { "get": { - "summary": "Retrieve list of existing override rules.", + "summary": "Retrieves list of existing override rules.", "description": "Retrieves the details of override property in the Settings Engine and returns list grouped by architecture reference.\n\nThis endpoint requires `Deploy.Read`, or `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Skip/Get", "responses": { From 6ffcf7dce353631dd6c9e280ab6faf1feb8e18bb Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Wed, 26 Mar 2025 15:44:38 -0400 Subject: [PATCH 4/5] Update text to follow guideline Ensure capitalization is applied --- SHIELD.json | 46 +++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/SHIELD.json b/SHIELD.json index cddf97c..edf021c 100644 --- a/SHIELD.json +++ b/SHIELD.json @@ -1185,7 +1185,7 @@ "Core" ], "security": [], - "summary": "Indicates if the System Requirements are met or not." + "summary": "Indicates if the System Requirements Are Met or Not" } }, "/API/Auth/Id/": { @@ -1227,7 +1227,7 @@ "Authentication" ], "security": [], - "summary": "Retrieves the IDs required to authenticate." + "summary": "Retrieves the IDs Required to Authenticate" } }, "/API/Auth/Authenticator/": { @@ -1256,7 +1256,7 @@ }, "/API/Auth/Authenticator/Cache/Status/": { "get": { - "summary": "Indicates if SHIELD is waiting for any credentials.", + "summary": "Indicates if SHIELD Is Waiting for Any Credentials", "description": "Provides a breakdown view of if SHIELD is waiting for any specific type of credential or credentials.\n\nThis endpoint requires the `Authentication.Read`, `Authentication.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/API/Auth/Authenticator/Cache/Status/Get", "responses": { @@ -1319,7 +1319,7 @@ "description": "Credential was successfully stored" } }, - "summary": "Provide Your SHIELD Authenticator Credentials - SCC Auth", + "summary": "Provide Your SHIELD Authenticator Credentials - Scc Auth", "tags": [ "Authentication" ] @@ -1365,7 +1365,7 @@ }, "/API/Update/": { "get": { - "summary": "Check if an Update Is Pending", + "summary": "Checks if an Update Is Pending", "description": "Provides the state of the update engine. Where `true` means there is an update detected and `false` means there isn't an update available. This endpoint is available to all authorization levels.", "operationId": "/API/Update/Get", "responses": { @@ -1387,7 +1387,7 @@ }, "/API/Update/Check/": { "get": { - "summary": "Check for a New Version", + "summary": "Checks for a New Version", "description": "Checks with data gateway and compares the reported version to the version that is locally installed. If there is a difference, a new update is marked as available. Always returns the latest version available on data gateway, even if that version is installed locally.\n\nThis endpoint requires the `Update.Read`, `Update.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/API/Update/Check/Get", "responses": { @@ -1465,7 +1465,7 @@ }, "/API/Update/Install/Channel/{Update Channel Name}/": { "post": { - "summary": "Installs SHIELD Core Update from Channel", + "summary": "Installs SHIELD Core Update From Channel", "description": "Installs the latest version that is available from SHI Data Gateway in the specified channel. Even if that version is the same that is installed.\n\nThis endpoint requires the `Update.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/API/Update/Install/Channel/UpdateChannelName/Post", "parameters": [ @@ -1510,7 +1510,7 @@ }, "/API/Discover/Status/": { "get": { - "summary": "State of the Discover Module.", + "summary": "State of the Discover Module", "description": "Provides a detailed breakdown of the current state of the discover module and it progress.\n\nThis endpoint requires the `Discover.Read`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/API/Discover/Status/Get", "responses": { @@ -1727,7 +1727,7 @@ "$ref": "#/components/responses/401" } }, - "summary": "Get the current status of the infrastructure deployment", + "summary": "Get the Current Status of the Infrastructure Deployment", "tags": [ "Infrastructure Deployment" ] @@ -1792,7 +1792,7 @@ "$ref": "#/components/responses/401" } }, - "summary": "Deploy the core infrastructure architecture specification", + "summary": "Deploy the Core Infrastructure Architecture Specification", "tags": [ "Infrastructure Deployment" ], @@ -1801,7 +1801,7 @@ }, "/API/Deploy/Delta/": { "get": { - "summary": "Retrieves cached evaluation results", + "summary": "Retrieves Cached Evaluation Results", "description": "Retrieves cached results of the comparison between configuration templates and live data to find discrepancies to be addressed. Results split into several categories and include timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.Read`, or `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Get", "responses": { @@ -1823,7 +1823,7 @@ }, "/API/Deploy/Delta/Check": { "post": { - "summary": "Performs evaluation and return results", + "summary": "Performs Evaluation and Return Results", "description": "Initiates evaluation process to calculate and return the results of the comparison between configuration templates and live data to find discrepancies to be addressed. Results split into several categories and include timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Check/Post", "requestBody": { @@ -1851,7 +1851,7 @@ }, "/API/Deploy/Delta/Restore/{configId}/": { "patch": { - "summary": "Restores the intended structure", + "summary": "Restores the Intended Structure", "description": "Applies a change to restore configuration item or its property to the value from the template.\n\nThis endpoint requires the `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Restore/:configId/Patch", "parameters": [ @@ -1883,7 +1883,7 @@ }, "/API/Deploy/Delta/Skip/": { "get": { - "summary": "Retrieves list of existing override rules.", + "summary": "Retrieves List of Existing Override Rules", "description": "Retrieves the details of override property in the Settings Engine and returns list grouped by architecture reference.\n\nThis endpoint requires `Deploy.Read`, or `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Skip/Get", "responses": { @@ -1917,7 +1917,7 @@ }, "/API/Deploy/Delta/Skip/{configId}/": { "post": { - "summary": "Records intention to bypass evaluation", + "summary": "Records Intention to Bypass Evaluation", "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.\n\nThis endpoint requires the `Deploy.ReadWrite` scope (permission).", "operationId": "/API/Deploy/Delta/Skip/:configId/Post", "parameters": [ @@ -2013,7 +2013,7 @@ "$ref": "#/components/responses/401" } }, - "summary": "Gets the version of SHIELDs components", + "summary": "Gets the Version of SHIELDs Components", "tags": [ "Infrastructure Deployment" ] @@ -2052,7 +2052,7 @@ "$ref": "#/components/responses/525" } }, - "summary": "Retrieves all AVD Intermediary Instances", + "summary": "Retrieves All Avd Intermediary Instances", "tags": [ "Intermediary" ] @@ -2194,7 +2194,7 @@ "$ref": "#/components/responses/525" } }, - "summary": "Removes the assignment of the specified users", + "summary": "Removes the Assignment of the Specified Users", "tags": [ "Intermediary" ] @@ -2234,7 +2234,7 @@ "$ref": "#/components/responses/525" } }, - "summary": "List all assigned users (paginated)", + "summary": "List All Assigned Users (Paginated)", "tags": [ "Intermediary" ] @@ -2316,7 +2316,7 @@ "$ref": "#/components/responses/525" } }, - "summary": "Assigns the list of specified users", + "summary": "Assigns the List of Specified Users", "tags": [ "Intermediary" ] @@ -2358,7 +2358,7 @@ "$ref": "#/components/responses/525" } }, - "summary": "Get a specific assigned user", + "summary": "Get a Specific Assigned User", "tags": [ "Intermediary" ] @@ -3041,6 +3041,10 @@ { "description": "WARNING AUTHENTICATION IS DISABLED WHEN DEBUG MODE IS ENABLED!!! Endpoints that are exposed only in debug mode. You can use these to see as the app sees.", "name": "Debug Mode" + }, + { + "description": "Manages the data and processes involved in identifying discrepancies between the desired architecture template and the deployed infrastructure outcomes.", + "name": "Delta" } ] } \ No newline at end of file From a0f4584cd659045c60350c9ba3b7357d6f97bf28 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Wed, 23 Apr 2025 12:20:36 -0400 Subject: [PATCH 5/5] Updating identifier and description Changes in response to review comments --- specs/SHIELD.json | 55 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 16 deletions(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index 3ed2118..ed0b6f1 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -1038,9 +1038,9 @@ "title": "Type of security class the object(s) belongs to", "type": "string" }, - "Shield.Deploy.Delta.Response": { - "title": "SHIELD - Deploy - Delta - Response", - "description": "Object returned as a result of query for cached data or re-evaluation operation.", + "Shield.Deploy.Delta.State": { + "title": "SHIELD - Deploy - Delta - State", + "description": "Object with the outcome of live evaluation of the infrastructure or cached data from an earlier run.", "type": "object", "properties": { "invalid": { @@ -1088,7 +1088,11 @@ } }, "type": "object", - "required": [ "actions", "message", "path" ] + "required": [ + "actions", + "message", + "path" + ] }, "type": "array" }, @@ -1096,7 +1100,12 @@ "type": "object" } }, - "required": [ "invalid", "lastRunTimestamp", "missing", "results"], + "required": [ + "invalid", + "lastRunTimestamp", + "missing", + "results" + ], "example": { "invalid": { "a14402b8-98c5-41e3-ba99-e5e1a536f68d": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found.", @@ -1109,19 +1118,26 @@ "results": { "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86": [ { - "actions": [ "ignore", "restore" ], + "actions": [ + "ignore", + "restore" + ], "message": "Value mismatch for property 'displayName' with current value being 'Audit Platform and Configuration Updates2'", "path": "displayName" }, { - "actions": [ "ignore" ], + "actions": [ + "ignore" + ], "message": "Expected object at level 'groupPolicyUploadedLanguageFiles', but encountered 'Array'", "path": "groupPolicyUploadedLanguageFiles" } ], "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4": [ { - "actions": [ "restore" ], + "actions": [ + "restore" + ], "message": "Array value at level 'roleScopeTagIds/1' is not found in the returned value", "path": "roleScopeTagIds/1" } @@ -1140,7 +1156,9 @@ "example": "/roleScopeTagIds" } }, - "required": [ "path" ] + "required": [ + "path" + ] } }, "securitySchemes": { @@ -1811,7 +1829,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Shield.Deploy.Delta.Response" + "$ref": "#/components/schemas/Shield.Deploy.Delta.State" } } }, @@ -1839,7 +1857,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Shield.Deploy.Delta.Response" + "$ref": "#/components/schemas/Shield.Deploy.Delta.State" } } }, @@ -1871,7 +1889,7 @@ } }, "responses": { - "204":{ + "204": { "description": "Restoration of configuration item or its property is successful" }, "400": { @@ -1903,8 +1921,13 @@ }, "description": "Collection of object with UUID string as property name and array of strings as value.", "example": { - "f47ac10b-58cc-4372-a567-0e02b2c3d479": ["/"], - "9c858901-8a57-4791-81fe-4c455b099bc9": ["/description", "/name"] + "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ + "/" + ], + "9c858901-8a57-4791-81fe-4c455b099bc9": [ + "/description", + "/name" + ] } } } @@ -1937,7 +1960,7 @@ } }, "responses": { - "204":{ + "204": { "description": "Recorded successfully" }, "400": { @@ -1967,7 +1990,7 @@ } }, "responses": { - "204":{ + "204": { "description": "Record has been removed successfully" }, "400": {