Skip to content

Commit a8ea65d

Browse files
AntoineSauzeauAntoineSauzeau
authored
Add specs for alert and finding endpoints of security_analytics plugin (#907)
* Add specs for alert and finding endpoints of security_analytics plugin Signed-off-by: Antoine Sauzeau <[email protected]> * Add tests Signed-off-by: Antoine Sauzeau <[email protected]> * Fix schemas Signed-off-by: Antoine Sauzeau <[email protected]> * Fix linting mistakes Signed-off-by: Antoine Sauzeau <[email protected]> * Modifications after review Signed-off-by: Antoine Sauzeau <[email protected]> * Modifications after review and addition of a few missing parameters Signed-off-by: Antoine Sauzeau <[email protected]> --------- Signed-off-by: Antoine Sauzeau <[email protected]>
1 parent 2990ed7 commit a8ea65d

File tree

5 files changed

+832
-0
lines changed

5 files changed

+832
-0
lines changed

‎CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
55
## [Unreleased]
66

77
### Added
8+
9+
- Added specs for alert and finding endpoints of security_analytics plugin ([#907](https://github.com/opensearch-project/opensearch-api-specification/pull/907))
810
- Added `template` to `QueryContainer` ([#904](https://github.com/opensearch-project/opensearch-api-specification/pull/904))
911
- Added specs for Search Relevance Workbench plugin for stats endpoints ([#920](https://github.com/opensearch-project/opensearch-api-specification/pull/920))
1012
- Added `time_in_execution` and `time_in_execution_millis` to `PendingTask` ([#922](https://github.com/opensearch-project/opensearch-api-specification/pull/922))

‎spec/namespaces/security_analytics.yaml

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
openapi: 3.1.0
2+
info:
3+
title: OpenSearch Security Analytics API
4+
description: OpenSearch Security Analytics API.
5+
version: 1.0.0
6+
paths:
7+
/_plugins/_security_analytics/alerts:
8+
get:
9+
operationId: security_analytics.get_alerts.0
10+
x-operation-group: security_analytics.get_alerts
11+
x-version-added: '2.4'
12+
description: Retrieve alerts related to a specific detector type or detector ID.
13+
externalDocs:
14+
url: https://docs.opensearch.org/docs/latest/security-analytics/api-tools/alert-finding-api/#get-alerts
15+
parameters:
16+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.alertState'
17+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.detectorType'
18+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.detector_id'
19+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.endTime'
20+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.missing'
21+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.searchString'
22+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.severityLevel'
23+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.size'
24+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.sortOrder'
25+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.sortString'
26+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.startIndex'
27+
- $ref: '#/components/parameters/security_analytics.get_alerts::query.startTime'
28+
responses:
29+
'200':
30+
$ref: '#/components/responses/security_analytics.get_alerts@200'
31+
32+
/_plugins/_security_analytics/findings/_search:
33+
get:
34+
operationId: security_analytics.get_findings.0
35+
x-operation-group: security_analytics.get_findings
36+
x-version-added: '2.4'
37+
description: Retrieve findings related to a specific detector type or detector ID.
38+
externalDocs:
39+
url: https://docs.opensearch.org/docs/latest/security-analytics/api-tools/alert-finding-api/#get-findings
40+
parameters:
41+
- $ref: '#/components/parameters/security_analytics.get_findings::query.detectionType'
42+
- $ref: '#/components/parameters/security_analytics.get_findings::query.detectorType'
43+
- $ref: '#/components/parameters/security_analytics.get_findings::query.detector_id'
44+
- $ref: '#/components/parameters/security_analytics.get_findings::query.endTime'
45+
- $ref: '#/components/parameters/security_analytics.get_findings::query.findingIds'
46+
- $ref: '#/components/parameters/security_analytics.get_findings::query.missing'
47+
- $ref: '#/components/parameters/security_analytics.get_findings::query.searchString'
48+
- $ref: '#/components/parameters/security_analytics.get_findings::query.severity'
49+
- $ref: '#/components/parameters/security_analytics.get_findings::query.size'
50+
- $ref: '#/components/parameters/security_analytics.get_findings::query.sortOrder'
51+
- $ref: '#/components/parameters/security_analytics.get_findings::query.sortString'
52+
- $ref: '#/components/parameters/security_analytics.get_findings::query.startIndex'
53+
- $ref: '#/components/parameters/security_analytics.get_findings::query.startTime'
54+
responses:
55+
'200':
56+
$ref: '#/components/responses/security_analytics.get_findings@200'
57+
58+
/_plugins/_security_analytics/findings/correlate:
59+
get:
60+
operationId: security_analytics.search_finding_correlations.0
61+
x-operation-group: security_analytics.search_finding_correlations
62+
x-version-added: '2.7'
63+
description: List correlations for a finding.
64+
externalDocs:
65+
url: https://docs.opensearch.org/docs/latest/security-analytics/api-tools/correlation-eng/#list-correlations-for-a-finding-belonging-to-a-log-type
66+
parameters:
67+
- $ref: '#/components/parameters/security_analytics.search_finding_correlations::query.detector_type'
68+
- $ref: '#/components/parameters/security_analytics.search_finding_correlations::query.finding'
69+
- $ref: '#/components/parameters/security_analytics.search_finding_correlations::query.nearby_findings'
70+
- $ref: '#/components/parameters/security_analytics.search_finding_correlations::query.time_window'
71+
responses:
72+
'200':
73+
$ref: '#/components/responses/security_analytics.search_finding_correlations@200'
74+
75+
components:
76+
responses:
77+
security_analytics.get_alerts@200:
78+
content:
79+
application/json:
80+
schema:
81+
$ref: '../schemas/security_analytics.alerts.yaml#/components/schemas/GetAlertsResponse'
82+
security_analytics.get_findings@200:
83+
content:
84+
application/json:
85+
schema:
86+
$ref: '../schemas/security_analytics.findings.yaml#/components/schemas/GetFindingsResponse'
87+
security_analytics.search_finding_correlations@200:
88+
content:
89+
application/json:
90+
schema:
91+
$ref: '../schemas/security_analytics.findings.yaml#/components/schemas/SearchFindingCorrelationsResponse'
92+
93+
parameters:
94+
security_analytics.get_alerts::query.detector_id:
95+
name: detector_id
96+
in: query
97+
description: The ID of the detector used to fetch alerts. Optional when `detectorType` is specified. Otherwise required.
98+
schema:
99+
type: string
100+
security_analytics.get_alerts::query.detectorType:
101+
name: detectorType
102+
in: query
103+
description: The type of detector used to fetch alerts. Optional when `detector_id` is specified. Otherwise required.
104+
schema:
105+
type: string
106+
security_analytics.get_alerts::query.endTime:
107+
name: endTime
108+
in: query
109+
description: The end timestamp (in ms) of the time window in which you want to retrieve alerts. Optional.
110+
schema:
111+
type: integer
112+
format: int64
113+
required: false
114+
security_analytics.get_alerts::query.severityLevel:
115+
name: severityLevel
116+
in: query
117+
description: Used to filter by alert severity level. Optional.
118+
schema:
119+
$ref: '../schemas/security_analytics.alerts.yaml#/components/schemas/AlertSeverityLevel'
120+
required: false
121+
security_analytics.get_alerts::query.alertState:
122+
name: alertState
123+
in: query
124+
description: Used to filter by alert state. Optional.
125+
schema:
126+
$ref: '../schemas/security_analytics.alerts.yaml#/components/schemas/AlertState'
127+
required: false
128+
security_analytics.get_alerts::query.sortString:
129+
name: sortString
130+
in: query
131+
description: The string used by Security Analytics to sort the alerts. Optional.
132+
schema:
133+
type: string
134+
default: start_time
135+
required: false
136+
security_analytics.get_alerts::query.sortOrder:
137+
name: sortOrder
138+
in: query
139+
description: The order used to sort the list of findings. Possible values are `asc` or `desc`. Optional.
140+
schema:
141+
$ref: '../schemas/_common.yaml#/components/schemas/SortOrder'
142+
default: asc
143+
required: false
144+
security_analytics.get_alerts::query.missing:
145+
name: missing
146+
in: query
147+
description: Used to sort by whether the field `missing` exists or not in the documents associated with the alert. Optional.
148+
schema:
149+
type: string
150+
required: false
151+
security_analytics.get_alerts::query.size:
152+
name: size
153+
in: query
154+
description: The maximum number of results returned in the response. Optional.
155+
schema:
156+
type: integer
157+
format: int64
158+
default: 20
159+
required: false
160+
security_analytics.get_alerts::query.startIndex:
161+
name: startIndex
162+
in: query
163+
description: The pagination index. Optional.
164+
schema:
165+
type: integer
166+
format: int64
167+
default: 0
168+
required: false
169+
security_analytics.get_alerts::query.searchString:
170+
name: searchString
171+
in: query
172+
description: The alert attribute you want returned in the search. Optional.
173+
schema:
174+
type: string
175+
required: false
176+
security_analytics.get_alerts::query.startTime:
177+
name: startTime
178+
in: query
179+
description: The beginning timestamp (in ms) of the time window in which you want to retrieve alerts. Optional.
180+
schema:
181+
type: integer
182+
format: int64
183+
required: false
184+
security_analytics.get_findings::query.detector_id:
185+
name: detector_id
186+
in: query
187+
description: The ID of the detector used to fetch alerts. Optional when the `detectorType` is specified. Otherwise required.
188+
schema:
189+
type: string
190+
security_analytics.get_findings::query.detectorType:
191+
name: detectorType
192+
in: query
193+
description: The type of detector used to fetch alerts. Optional when the `detector_id` is specified. Otherwise required.
194+
schema:
195+
type: string
196+
security_analytics.get_findings::query.endTime:
197+
name: endTime
198+
in: query
199+
description: The end timestamp (in ms) of the time window in which you want to retrieve findings. Optional.
200+
schema:
201+
type: string
202+
required: false
203+
security_analytics.get_findings::query.findingIds:
204+
name: findingIds
205+
in: query
206+
description: The comma-separated id list of findings for which you want retrieve details. Optional.
207+
schema:
208+
type: string
209+
required: false
210+
security_analytics.get_findings::query.missing:
211+
name: missing
212+
in: query
213+
description: Used to sort by whether the field `missing` exists or not in the documents associated with the finding. Optional.
214+
schema:
215+
type: string
216+
required: false
217+
security_analytics.get_findings::query.sortOrder:
218+
name: sortOrder
219+
in: query
220+
description: The order used to sort the list of findings. Possible values are `asc` or `desc`. Optional.
221+
schema:
222+
$ref: '../schemas/_common.yaml#/components/schemas/SortOrder'
223+
default: asc
224+
required: false
225+
security_analytics.get_findings::query.size:
226+
name: size
227+
in: query
228+
description: The maximum number of results returned in the response. Optional.
229+
schema:
230+
type: integer
231+
format: int64
232+
default: 20
233+
required: false
234+
security_analytics.get_findings::query.searchString:
235+
name: searchString
236+
in: query
237+
description: The finding attribute you want returned in the search. To search in a specific index, specify the index name in the request path. For example, to search findings in the indexABC index, use `searchString=indexABC’. Optional.
238+
schema:
239+
type: string
240+
required: false
241+
security_analytics.get_findings::query.sortString:
242+
name: sortString
243+
in: query
244+
description: The string used by the Alerting plugin to sort the findings. Optional.
245+
schema:
246+
type: string
247+
default: timestamp
248+
required: false
249+
security_analytics.get_findings::query.startIndex:
250+
name: startIndex
251+
in: query
252+
description: The pagination index. Optional.
253+
schema:
254+
type: integer
255+
format: int64
256+
default: 0
257+
required: false
258+
security_analytics.get_findings::query.startTime:
259+
name: startTime
260+
in: query
261+
description: The beginning timestamp (in ms) of the time window in which you want to retrieve findings. Optional.
262+
schema:
263+
type: integer
264+
format: int64
265+
required: false
266+
security_analytics.get_findings::query.detectionType:
267+
name: detectionType
268+
in: query
269+
description: The detection type that dictates the retrieval type for the findings. When the detection type is `threat`, it fetches threat intelligence feeds. When the detection type is `rule`, findings are fetched based on the detector’s rule. Optional.
270+
schema:
271+
$ref: '../schemas/security_analytics.findings.yaml#/components/schemas/DetectionType'
272+
default: rule
273+
required: false
274+
security_analytics.get_findings::query.severity:
275+
name: severity
276+
in: query
277+
description: The rule severity for which retrieve findings. Severity can be `critical`, `high`, `medium`, or `low`. Optional.
278+
schema:
279+
$ref: '../schemas/security_analytics.findings.yaml#/components/schemas/RuleSeverity'
280+
required: false
281+
security_analytics.search_finding_correlations::query.finding:
282+
name: finding
283+
in: query
284+
description: The finding ID for which you want to find other findings that are correlated. Required.
285+
schema:
286+
type: string
287+
required: true
288+
security_analytics.search_finding_correlations::query.detector_type:
289+
name: detector_type
290+
in: query
291+
description: The log type of findings you want to correlate with the specified finding. Required.
292+
schema:
293+
type: string
294+
required: true
295+
security_analytics.search_finding_correlations::query.nearby_findings:
296+
name: nearby_findings
297+
in: query
298+
description: The number of nearby findings you want to return. Optional.
299+
schema:
300+
type: integer
301+
format: int64
302+
default: 10
303+
required: false
304+
security_analytics.search_finding_correlations::query.time_window:
305+
name: time_window
306+
in: query
307+
description: The time window (in ms) in which all of the correlations must have occurred together. Optional.
308+
schema:
309+
type: integer
310+
format: int64
311+
default: 300000
312+
required: false

0 commit comments

Comments
 (0)