Document security findings triage endpoints (SEC-31359)

examples/v2/security-monitoring/AttachServiceNowTicket.rb

@@ -0,0 +1,33 @@
+# Attach security findings to a ServiceNow ticket returns "OK" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.attach_service_now_ticket".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
+
+body = DatadogAPIClient::V2::AttachServiceNowTicketRequest.new({
+  data: DatadogAPIClient::V2::AttachServiceNowTicketRequestData.new({
+    attributes: DatadogAPIClient::V2::AttachServiceNowTicketRequestDataAttributes.new({
+      servicenow_ticket_url: "https://example.service-now.com/now/nav/ui/classic/params/target/incident.do?sys_id=abcdef0123456789abcdef0123456789",
+    }),
+    relationships: DatadogAPIClient::V2::AttachServiceNowTicketRequestDataRelationships.new({
+      findings: DatadogAPIClient::V2::Findings.new({
+        data: [
+          DatadogAPIClient::V2::FindingData.new({
+            id: "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
+            type: DatadogAPIClient::V2::FindingDataType::FINDINGS,
+          }),
+        ],
+      }),
+      project: DatadogAPIClient::V2::CaseManagementProject.new({
+        data: DatadogAPIClient::V2::CaseManagementProjectData.new({
+          id: "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
+          type: DatadogAPIClient::V2::CaseManagementProjectDataType::PROJECTS,
+        }),
+      }),
+    }),
+    type: DatadogAPIClient::V2::ServiceNowTicketsDataType::SERVICENOW_TICKETS,
+  }),
+})
+p api_instance.attach_service_now_ticket(body)

examples/v2/security-monitoring/CreateServiceNowTickets.rb

@@ -0,0 +1,38 @@
+# Create ServiceNow tickets for security findings returns "Created" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.create_service_now_tickets".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
+
+body = DatadogAPIClient::V2::CreateServiceNowTicketRequestArray.new({
+  data: [
+    DatadogAPIClient::V2::CreateServiceNowTicketRequestData.new({
+      attributes: DatadogAPIClient::V2::CreateServiceNowTicketRequestDataAttributes.new({
+        assignee_id: "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0",
+        description: "A description of the ServiceNow ticket.",
+        priority: DatadogAPIClient::V2::CasePriority::NOT_DEFINED,
+        title: "A title for the ServiceNow ticket.",
+      }),
+      relationships: DatadogAPIClient::V2::CreateServiceNowTicketRequestDataRelationships.new({
+        findings: DatadogAPIClient::V2::Findings.new({
+          data: [
+            DatadogAPIClient::V2::FindingData.new({
+              id: "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
+              type: DatadogAPIClient::V2::FindingDataType::FINDINGS,
+            }),
+          ],
+        }),
+        project: DatadogAPIClient::V2::CaseManagementProject.new({
+          data: DatadogAPIClient::V2::CaseManagementProjectData.new({
+            id: "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
+            type: DatadogAPIClient::V2::CaseManagementProjectDataType::PROJECTS,
+          }),
+        }),
+      }),
+      type: DatadogAPIClient::V2::ServiceNowTicketsDataType::SERVICENOW_TICKETS,
+    }),
+  ],
+})
+p api_instance.create_service_now_tickets(body)

examples/v2/security-monitoring/UpdateFindingsAssignee.rb

@@ -0,0 +1,28 @@
+# Assign or unassign security findings returns "Accepted" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.update_findings_assignee".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
+
+body = DatadogAPIClient::V2::AssigneeRequest.new({
+  data: DatadogAPIClient::V2::AssigneeRequestData.new({
+    attributes: DatadogAPIClient::V2::AssigneeRequestDataAttributes.new({
+      assignee_id: "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0",
+    }),
+    id: "00000000-0000-0000-0000-000000000001",
+    relationships: DatadogAPIClient::V2::AssigneeRequestDataRelationships.new({
+      findings: DatadogAPIClient::V2::Findings.new({
+        data: [
+          DatadogAPIClient::V2::FindingData.new({
+            id: "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
+            type: DatadogAPIClient::V2::FindingDataType::FINDINGS,
+          }),
+        ],
+      }),
+    }),
+    type: DatadogAPIClient::V2::AssigneeDataType::ASSIGNEE,
+  }),
+})
+p api_instance.update_findings_assignee(body)

features/scenarios_model_mapping.rb

@@ -2008,6 +2008,9 @@
             "page_limit" => "Integer",
             "sort" => "SecurityFindingsSort",
     },
+    "v2.UpdateFindingsAssignee" => {
+            "body" => "AssigneeRequest",
+    },
     "v2.DetachCase" => {
             "body" => "DetachCaseRequest",
     },
@@ -2030,6 +2033,12 @@
     "v2.SearchSecurityFindings" => {
             "body" => "SecurityFindingsSearchRequest",
     },
+    "v2.AttachServiceNowTicket" => {
+            "body" => "AttachServiceNowTicketRequest",
+    },
+    "v2.CreateServiceNowTickets" => {
+            "body" => "CreateServiceNowTicketRequestArray",
+    },
     "v2.ListAssetsSBOMs" => {
             "page_token" => "String",
             "page_number" => "Integer",

features/v2/security_monitoring.feature

@@ -41,6 +41,30 @@ Feature: Security Monitoring
     When the request is sent
     Then the response status is 200 OK
 
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Assign or unassign security findings returns "Accepted" response
+    Given operation "UpdateFindingsAssignee" enabled
+    And new "UpdateFindingsAssignee" request
+    And body with value {"data": {"attributes": {"assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0"}, "id": "00000000-0000-0000-0000-000000000001", "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}}, "type": "assignee"}}
+    When the request is sent
+    Then the response status is 202 Accepted
+
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Assign or unassign security findings returns "Bad Request" response
+    Given operation "UpdateFindingsAssignee" enabled
+    And new "UpdateFindingsAssignee" request
+    And body with value {"data": {"attributes": {"assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0"}, "id": "00000000-0000-0000-0000-000000000001", "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}}, "type": "assignee"}}
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Assign or unassign security findings returns "Not Found" response
+    Given operation "UpdateFindingsAssignee" enabled
+    And new "UpdateFindingsAssignee" request
+    And body with value {"data": {"attributes": {"assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0"}, "id": "00000000-0000-0000-0000-000000000001", "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}}, "type": "assignee"}}
+    When the request is sent
+    Then the response status is 404 Not Found
+
   @team:DataDog/k9-investigation
   Scenario: Attach security finding to a Jira issue returns "OK" response
     Given new "AttachJiraIssue" request
@@ -87,6 +111,30 @@ Feature: Security Monitoring
     And the response "data.attributes.insights" has item with field "resource_id" with value "MTNjN2ZmYWMzMDIxYmU1ZDFiZDRjNWUwN2I1NzVmY2F-YTA3MzllMTUzNWM3NmEyZjdiNzEzOWM5YmViZTMzOGM="
     And the response "data.attributes.jira_issue.result.issue_url" is equal to "https://datadoghq-sandbox-538.atlassian.net/browse/CSMSEC-105476"
 
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Attach security findings to a ServiceNow ticket returns "Bad Request" response
+    Given operation "AttachServiceNowTicket" enabled
+    And new "AttachServiceNowTicket" request
+    And body with value {"data": {"attributes": {"servicenow_ticket_url": "https://example.service-now.com/now/nav/ui/classic/params/target/incident.do?sys_id=abcdef0123456789abcdef0123456789"}, "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}, "project": {"data": {"id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001", "type": "projects"}}}, "type": "servicenow_tickets"}}
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Attach security findings to a ServiceNow ticket returns "Not Found" response
+    Given operation "AttachServiceNowTicket" enabled
+    And new "AttachServiceNowTicket" request
+    And body with value {"data": {"attributes": {"servicenow_ticket_url": "https://example.service-now.com/now/nav/ui/classic/params/target/incident.do?sys_id=abcdef0123456789abcdef0123456789"}, "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}, "project": {"data": {"id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001", "type": "projects"}}}, "type": "servicenow_tickets"}}
+    When the request is sent
+    Then the response status is 404 Not Found
+
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Attach security findings to a ServiceNow ticket returns "OK" response
+    Given operation "AttachServiceNowTicket" enabled
+    And new "AttachServiceNowTicket" request
+    And body with value {"data": {"attributes": {"servicenow_ticket_url": "https://example.service-now.com/now/nav/ui/classic/params/target/incident.do?sys_id=abcdef0123456789abcdef0123456789"}, "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}, "project": {"data": {"id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001", "type": "projects"}}}, "type": "servicenow_tickets"}}
+    When the request is sent
+    Then the response status is 200 OK
+
   @team:DataDog/k9-investigation
   Scenario: Attach security findings to a case returns "Bad Request" response
     Given new "AttachCase" request
@@ -482,6 +530,30 @@ Feature: Security Monitoring
     When the request is sent
     Then the response status is 404 Not Found
 
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Create ServiceNow tickets for security findings returns "Bad Request" response
+    Given operation "CreateServiceNowTickets" enabled
+    And new "CreateServiceNowTickets" request
+    And body with value {"data": [{"attributes": {"assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0", "description": "A description of the ServiceNow ticket.", "priority": "NOT_DEFINED", "title": "A title for the ServiceNow ticket."}, "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}, "project": {"data": {"id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001", "type": "projects"}}}, "type": "servicenow_tickets"}]}
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Create ServiceNow tickets for security findings returns "Created" response
+    Given operation "CreateServiceNowTickets" enabled
+    And new "CreateServiceNowTickets" request
+    And body with value {"data": [{"attributes": {"assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0", "description": "A description of the ServiceNow ticket.", "priority": "NOT_DEFINED", "title": "A title for the ServiceNow ticket."}, "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}, "project": {"data": {"id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001", "type": "projects"}}}, "type": "servicenow_tickets"}]}
+    When the request is sent
+    Then the response status is 201 Created
+
+  @generated @skip @team:DataDog/k9-investigation
+  Scenario: Create ServiceNow tickets for security findings returns "Not Found" response
+    Given operation "CreateServiceNowTickets" enabled
+    And new "CreateServiceNowTickets" request
+    And body with value {"data": [{"attributes": {"assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0", "description": "A description of the ServiceNow ticket.", "priority": "NOT_DEFINED", "title": "A title for the ServiceNow ticket."}, "relationships": {"findings": {"data": [{"id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "findings"}]}, "project": {"data": {"id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001", "type": "projects"}}}, "type": "servicenow_tickets"}]}
+    When the request is sent
+    Then the response status is 404 Not Found
+
   @skip-validation @team:DataDog/k9-cloud-siem
   Scenario: Create a cloud_configuration rule returns "OK" response
     Given new "CreateSecurityMonitoringRule" request

features/v2/undo.json

@@ -6414,6 +6414,12 @@
       "type": "safe"
     }
   },
+  "UpdateFindingsAssignee": {
+    "tag": "Security Monitoring",
+    "undo": {
+      "type": "idempotent"
+    }
+  },
   "DetachCase": {
     "tag": "Security Monitoring",
     "undo": {
@@ -6470,6 +6476,25 @@
       "type": "safe"
     }
   },
+  "AttachServiceNowTicket": {
+    "tag": "Security Monitoring",
+    "undo": {
+      "type": "idempotent"
+    }
+  },
+  "CreateServiceNowTickets": {
+    "tag": "Security Monitoring",
+    "undo": {
+      "operationId": "DetachCase",
+      "parameters": [
+        {
+          "name": "body",
+          "template": "{\n  \"data\": {\n    \"type\": \"cases\",\n    \"relationships\": {\n      \"findings\": {\n        \"data\": [\n          {\n              \"type\": \"findings\",\n              \"id\": \"{{data[0].attributes.insights[0].resource_id}}\"\n          }\n        ]\n      }\n    }\n  }\n}"
+        }
+      ],
+      "type": "unsafe"
+    }
+  },
   "ListAssetsSBOMs": {
     "tag": "Security Monitoring",
     "undo": {

lib/datadog_api_client/configuration.rb

@@ -325,6 +325,7 @@ def initialize
             "v2.get_aws_cloud_auth_persona_mapping": false,
             "v2.list_aws_cloud_auth_persona_mappings": false,
             "v2.activate_content_pack": false,
+            "v2.attach_service_now_ticket": false,
             "v2.batch_get_security_monitoring_dataset_dependencies": false,
             "v2.bulk_create_sample_log_generation_subscriptions": false,
             "v2.bulk_export_security_monitoring_terraform_resources": false,
@@ -334,6 +335,7 @@ def initialize
             "v2.create_sample_log_generation_subscription": false,
             "v2.create_security_monitoring_dataset": false,
             "v2.create_security_monitoring_integration_config": false,
+            "v2.create_service_now_tickets": false,
             "v2.create_static_analysis_ast": false,
             "v2.create_static_analysis_server_analysis": false,
             "v2.deactivate_content_pack": false,
@@ -375,6 +377,7 @@ def initialize
             "v2.mute_findings": false,
             "v2.run_historical_job": false,
             "v2.search_security_monitoring_histsignals": false,
+            "v2.update_findings_assignee": false,
             "v2.update_security_monitoring_dataset": false,
             "v2.update_security_monitoring_integration_config": false,
             "v2.validate_security_monitoring_integration_config": false,

lib/datadog_api_client/inflector.rb

@@ -1474,6 +1474,16 @@ def overrides
           "v2.asset_risks" => "AssetRisks",
           "v2.asset_type" => "AssetType",
           "v2.asset_version" => "AssetVersion",
+          "v2.assignee_data_type" => "AssigneeDataType",
+          "v2.assignee_request" => "AssigneeRequest",
+          "v2.assignee_request_data" => "AssigneeRequestData",
+          "v2.assignee_request_data_attributes" => "AssigneeRequestDataAttributes",
+          "v2.assignee_request_data_relationships" => "AssigneeRequestDataRelationships",
+          "v2.assignee_response" => "AssigneeResponse",
+          "v2.assignee_response_data" => "AssigneeResponseData",
+          "v2.assignee_response_data_attributes" => "AssigneeResponseDataAttributes",
+          "v2.assignee_response_meta" => "AssigneeResponseMeta",
+          "v2.assignment_result" => "AssignmentResult",
           "v2.assign_seats_user_request" => "AssignSeatsUserRequest",
           "v2.assign_seats_user_request_data" => "AssignSeatsUserRequestData",
           "v2.assign_seats_user_request_data_attributes" => "AssignSeatsUserRequestDataAttributes",
@@ -1495,6 +1505,10 @@ def overrides
           "v2.attachment_data_attributes_attachment_type" => "AttachmentDataAttributesAttachmentType",
           "v2.attachment_data_relationships" => "AttachmentDataRelationships",
           "v2.attachment_included" => "AttachmentIncluded",
+          "v2.attach_service_now_ticket_request" => "AttachServiceNowTicketRequest",
+          "v2.attach_service_now_ticket_request_data" => "AttachServiceNowTicketRequestData",
+          "v2.attach_service_now_ticket_request_data_attributes" => "AttachServiceNowTicketRequestDataAttributes",
+          "v2.attach_service_now_ticket_request_data_relationships" => "AttachServiceNowTicketRequestDataRelationships",
           "v2.audit_logs_event" => "AuditLogsEvent",
           "v2.audit_logs_event_attributes" => "AuditLogsEventAttributes",
           "v2.audit_logs_events_response" => "AuditLogsEventsResponse",
@@ -2433,6 +2447,10 @@ def overrides
           "v2.create_ruleset_request_data_attributes_rules_items_reference_table" => "CreateRulesetRequestDataAttributesRulesItemsReferenceTable",
           "v2.create_ruleset_request_data_attributes_rules_items_reference_table_field_pairs_items" => "CreateRulesetRequestDataAttributesRulesItemsReferenceTableFieldPairsItems",
           "v2.create_ruleset_request_data_type" => "CreateRulesetRequestDataType",
+          "v2.create_service_now_ticket_request_array" => "CreateServiceNowTicketRequestArray",
+          "v2.create_service_now_ticket_request_data" => "CreateServiceNowTicketRequestData",
+          "v2.create_service_now_ticket_request_data_attributes" => "CreateServiceNowTicketRequestDataAttributes",
+          "v2.create_service_now_ticket_request_data_relationships" => "CreateServiceNowTicketRequestDataRelationships",
           "v2.create_status_page_request" => "CreateStatusPageRequest",
           "v2.create_status_page_request_data" => "CreateStatusPageRequestData",
           "v2.create_status_page_request_data_attributes" => "CreateStatusPageRequestDataAttributes",
@@ -3090,6 +3108,8 @@ def overrides
           "v2.finding_mute_reason" => "FindingMuteReason",
           "v2.finding_rule" => "FindingRule",
           "v2.findings" => "Findings",
+          "v2.finding_service_now_ticket" => "FindingServiceNowTicket",
+          "v2.finding_service_now_ticket_result" => "FindingServiceNowTicketResult",
           "v2.finding_status" => "FindingStatus",
           "v2.finding_type" => "FindingType",
           "v2.finding_vulnerability_type" => "FindingVulnerabilityType",
@@ -6241,6 +6261,7 @@ def overrides
           "v2.service_now_ticket_create_request" => "ServiceNowTicketCreateRequest",
           "v2.service_now_ticket_resource_type" => "ServiceNowTicketResourceType",
           "v2.service_now_ticket_result" => "ServiceNowTicketResult",
+          "v2.service_now_tickets_data_type" => "ServiceNowTicketsDataType",
           "v2.service_now_user_attributes" => "ServiceNowUserAttributes",
           "v2.service_now_user_data" => "ServiceNowUserData",
           "v2.service_now_users_response" => "ServiceNowUsersResponse",