Merge pull request #719 from Security-Onion-Solutions/jertel/wip

Clarify how to search for data collections, like cases and detections…
Security-Onion-Solutions · Jan 15, 2025 · 17cc333 · 17cc333
2 parents 2ceed84 + a1e7ab4
commit 17cc333
Show file tree

Hide file tree

Showing 18 changed files with 82 additions and 80 deletions.
diff --git a/model/event.go b/model/event.go
@@ -201,7 +201,7 @@ func (results *EventUpdateResults) AddEventUpdateResults(newResults *EventUpdate
 
 type EventAckCriteria struct {
 	// The search filter to utilize when searching for matching events to acknowledge.
-	SearchFilter string `json:"searchFilter" example:"(*) AND tags:alert AND NOT event.acknowledged:true AND NOT event.escalated:true | groupby rule.name event.module* event.severity_label rule.uuid"`
+	SearchFilter string `json:"searchFilter" example:"tags:alert AND NOT event.acknowledged:true AND NOT event.escalated:true | groupby rule.name event.module* event.severity_label rule.uuid"`
 	// Optional event filters to further narrow down matching events to acknowledge. These are field:value pairs.
 	EventFilter map[string]interface{} `json:"eventFilter" example:"event.module:sigma,rule.name:Security Onion - SOC Login Failure,rule.uuid:bf86ef21-41e6-417b-9a05-b9ea6bf28a38"`
 	// The date range to use for searching for matching events

diff --git a/server/casehandler.go b/server/casehandler.go
@@ -88,7 +88,7 @@ func (h *CaseHandler) caseEnabled(next http.Handler) http.Handler {
 
 // @Summary      Create Case
 // @Description  Create a new case given a populated case object as input.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        request  body  model.Case true "New case object. ID will be generated by the server."
 // @Accept       json
@@ -121,7 +121,7 @@ func (h *CaseHandler) createCase(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Create Case Related Event
 // @Description  Attach a related event to an existing case.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        request  body  model.RelatedEvent true "New related event object. ID will be generated by the server."
 // @Accept       json
@@ -154,7 +154,7 @@ func (h *CaseHandler) createEvent(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Create Case Comment
 // @Description  Add a new comment to an existing case.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        request  body  model.Comment true "New comment object. ID will be generated by the server."
 // @Accept       json
@@ -190,7 +190,7 @@ func (h *CaseHandler) createComment(w http.ResponseWriter, r *http.Request) {
 // @Description  Observables are considered "artifacts" in SOC internal terminology.
 // @Description  If not creating a file artifact then only the artifact itself should be sent as the body, in JSON format.
 // @Description  If creating a file artifact then two multipart-form values should be supplied: "json" (the artifact object), and "attachment" (the file bytes). The file size, hashes, mime type will be automatically generated and populated into the artifact object on the server.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        request  body  model.Artifact true "New case artifact object. ID will be generated by the server."
 // @Accept       json
@@ -299,7 +299,7 @@ func (h *CaseHandler) createArtifact(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Update Case
 // @Description  Updates an existing case with a provided case object as input.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        request  body  model.Case true "Replacement case object. The provided ID will be used to match the existing case."
 // @Accept       json
@@ -333,7 +333,7 @@ func (h *CaseHandler) updateCase(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Update Case Comment
 // @Description  Updates an existing case comment with a provided comment object as input.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        request  body  model.Comment true "Replacement comment object. The provided ID will be used to match the existing comment."
 // @Accept       json
@@ -367,7 +367,7 @@ func (h *CaseHandler) updateComment(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Update Case Artifact
 // @Description  Updates an existing case artifact with a provided artifact object as input. Important: The artifact value and type cannot be modified.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        request  body  model.Artifact true "Replacement artifact object. The provided ID will be used to match the existing artifact."
 // @Accept       json
@@ -401,7 +401,7 @@ func (h *CaseHandler) updateArtifact(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Delete Case Comment
 // @Description  Removes a case comment from a case and deletes the comment.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        id  path  string  true  "The comment ID to remove"
 // @Success      200        "The comment was successfully removed"
@@ -431,7 +431,7 @@ func (h *CaseHandler) deleteComment(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Delete Case Related Event
 // @Description  Removes a related event from a case.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        id  path  string  true  "The related event ID to remove"
 // @Success      200        "The related event was successfully removed from the case"
@@ -462,7 +462,7 @@ func (h *CaseHandler) deleteEvent(w http.ResponseWriter, r *http.Request) {
 // @Summary      Delete Case Artifact
 // @Description  Removes a case artifact.
 // @Description  Observables are considered "artifacts" in SOC internal terminology.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, cases/write, events/read, events/write]
 // @Param        id  path  string  true  "The artifact ID to remove"
 // @Success      200       "The artifact was successfully removed from the case"
@@ -491,8 +491,9 @@ func (h *CaseHandler) deleteArtifact(w http.ResponseWriter, r *http.Request) {
 }
 
 // @Summary      Get Case
-// @Description  Searches for a given case ID and returns the case details.
-// @Tags	     Cases
+// @Description  Retrieves a case given the provided case ID and returns the case details.
+// @Description  Use the "Query Data" API to search for cases using other criteria, specifying a query parameter that includes the following, at a minimum: _index:"*:so-case"
+// @Tags         Cases
 // @Security     bearer[cases/read, events/read]
 // @Produce      json
 // @Param        id  path  string  true  "The case ID to retrieve"
@@ -524,7 +525,7 @@ func (h *CaseHandler) getCase(w http.ResponseWriter, r *http.Request) {
 // @Summary      Get Case Comments
 // @Description  Searches for all comments assigned to the given case ID and returns the matching comments, if any.
 // @Description  If the case does not exist, this method will respond with a 200 status and an empty list.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, events/read]
 // @Param        id  path  string  true  "The case ID to use for searching all related comments"
 // @Produce      json
@@ -555,7 +556,7 @@ func (h *CaseHandler) getComment(w http.ResponseWriter, r *http.Request) {
 // @Summary      Get Related Events
 // @Description  Searches for all related events associated with the given case ID and returns the matching events, if any.
 // @Description  If the case does not exist, this method will respond with a 200 status and an empty list.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, events/read]
 // @Param        id  path  string  true  "The case ID to use for searching all related events"
 // @Produce      json
@@ -585,7 +586,7 @@ func (h *CaseHandler) getEvent(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Get Artifact Stream
 // @Description  Returns the artifact stream for the given artifact ID. Artifact streams are typically file artifacts.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, events/read]
 // @Param        id  path  string  true  "The artifact's stream ID"
 // @Produce      octet-stream
@@ -620,7 +621,7 @@ func (h *CaseHandler) getTask(w http.ResponseWriter, r *http.Request) {
 // @Description  Searches for all artifacts attached to the given case ID and returns the matching artifacts, if any.
 // @Description  Observables are considered "artifacts" in SOC internal terminology.
 // @Description  If the case does not exist, this method will respond with a 200 status and an empty list.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, events/read]
 // @Param        id  path  string  true  "The case ID to use for searching all artifacts"
 // @Produce      json
@@ -653,7 +654,7 @@ func (h *CaseHandler) getArtifact(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Get Case History
 // @Description  Returns all audit history associated with the given case ID.
-// @Tags	     Cases
+// @Tags         Cases
 // @Security     bearer[cases/read, events/read]
 // @Param        id  path  string  true  "The case ID"
 // @Produce      json

diff --git a/server/clientshandler.go b/server/clientshandler.go
@@ -45,7 +45,7 @@ func RegisterClientsRoutes(srv *Server, r chi.Router, prefix string) {
 
 // @Summary      Get API Clients
 // @Description  Returns all existing API clients.
-// @Tags	     Clients
+// @Tags         Clients
 // @Security     bearer[clients/read]
 // @Produce      json
 // @Success      200  {array}   model.Client		 "The array of Client objects"
@@ -67,7 +67,7 @@ func (h *ClientsHandler) getClients(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Create API Clients
 // @Description  Creates a new API client with the given Client object
-// @Tags	     Clients
+// @Tags         Clients
 // @Security     bearer[clients/write]
 // @param        request body model.Client true "The Client object to create. Only the 'name' and 'note' properties are used."
 // @Produce      json
@@ -106,7 +106,7 @@ func (h *ClientsHandler) postClient(w http.ResponseWriter, r *http.Request) {
 // @Summary      Assign Client Permission
 // @Description  Assigns a permission to an existing API client.
 // @Description  A new access token is not required. Future API calls will immediately be affected.
-// @Tags	     Clients
+// @Tags         Clients
 // @Security     bearer[clients/write]
 // @param        id  path  string  true  "The API client ID to which the permission will be assigned" example(socl_my_new_api_client)
 // @param        perm  path  string  true  "The permission to assign" example(events/read)
@@ -147,7 +147,7 @@ func (h *ClientsHandler) postAddPermission(w http.ResponseWriter, r *http.Reques
 // @Summary      Regenerate Client Secret
 // @Description  Regenerates a new client secret for the given API client ID.
 // @Description  Pre-existing access tokens that have not yet expired will remain valid through their expiration.
-// @Tags	     Clients
+// @Tags         Clients
 // @Security     bearer[clients/write]
 // @param        id  path  string  true  "The API client ID" example(socl_my_new_api_client)
 // @Produce      json
@@ -177,7 +177,7 @@ func (h *ClientsHandler) getGeneratedSecret(w http.ResponseWriter, r *http.Reque
 
 // @Summary      Update API Clients
 // @Description  Updates an existing API client with the given Client object
-// @Tags	     Clients
+// @Tags         Clients
 // @Security     bearer[clients/write]
 // @param        request body model.Client true "The Client object to update. Only the 'name', and 'note' properties are used."
 // @Produce      json
@@ -221,7 +221,7 @@ func (h *ClientsHandler) putClient(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Remove API Client
 // @Description  Removes an API client. Future API requests from this client will immediately be rejected.
-// @Tags	     Clients
+// @Tags         Clients
 // @Security     bearer[clients/write]
 // @param        id  path  string  true  "The API client ID" example(socl_my_new_api_client)
 // @Success      200                         "The API client was successfully removed"
@@ -251,7 +251,7 @@ func (h *ClientsHandler) deleteClient(w http.ResponseWriter, r *http.Request) {
 // @Summary      Remove Client Permission
 // @Description  Removes a permission from an existing API client.
 // @Description  A new access token is not required. Future API calls will immediately be affected.
-// @Tags	     Clients
+// @Tags         Clients
 // @Security     bearer[clients/write]
 // @param        id  path  string  true  "The API client ID from which the permission will be removed" example(socl_my_new_api_client)
 // @param        perm  path  string  true  "The permission to remove" example(events/read)

diff --git a/server/confighandler.go b/server/confighandler.go
@@ -57,7 +57,7 @@ func (h *ConfigHandler) configEnabled(next http.Handler) http.Handler {
 // @Summary      Get Configuration
 // @Description  Retrieves the full set of configuration settings and associated metadata.
 // @Description  This response can be very large, particularly when the advanced parameter is set to 'true'.
-// @Tags	     Config
+// @Tags         Config
 // @Security     bearer[config/read]
 // @param        advanced  query  boolean  false  "If true, all configuration settings will be retrieved, otherwise only the commonly adjusted settings are retrieved" example(true)
 // @Success      200  {array} model.Setting   "The configuration setting objects"
@@ -84,7 +84,7 @@ func (h *ConfigHandler) getConfig(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Save Setting
 // @Description  Sets a configuration setting to a new value.
-// @Tags	     Config
+// @Tags         Config
 // @Security     bearer[config/read,config/write]
 // @param        request  body  model.Setting  true  "The setting to update. Only non-metadata fields are required, specifically 'id' and 'value', and optionally the 'nodeId' field if this is being applied to a specific node"
 // @Success      200                         "The new setting values has been saved"
@@ -120,7 +120,7 @@ func (h *ConfigHandler) putSetting(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Sync Configuration
 // @Description  Synchronizes the grid to apply recent configuration changes to the grid. Internally this is queuing up a Salt highstate, which can take several minutes to complete, or longer if another highstate is already in progress.
-// @Tags	     Config
+// @Tags         Config
 // @Security     bearer[config/write]
 // @Success      200                         "The synchronization request has been successfully queued"
 // @Failure      401                         "Request was not properly authenticated"
@@ -142,7 +142,7 @@ func (h *ConfigHandler) putSync(w http.ResponseWriter, r *http.Request) {
 
 // @Summary      Delete Setting
 // @Description  Removes a custom setting value. This effectively reverts to the default setting value.
-// @Tags	     Config
+// @Tags         Config
 // @Security     bearer[config/read,config/write]
 // @Param        id  path  string  true  "The setting ID to remove" example(elastalert.alerter_parameters)
 // @Param        minion  path  string  false  "The optional node ID from which to remove this setting. If omitted, the setting will be removed from the global grid and any node-specific setting values will remain in place." example(chi-so-001_standalone)