diff --git a/model/event.go b/model/event.go index adbca77d..af13b26f 100644 --- 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 index 7c999338..1e241b9f 100644 --- 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 index afd6a03b..13c6884d 100644 --- 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 index fc1db587..6fed0c75 100644 --- 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) diff --git a/server/detectionhandler.go b/server/detectionhandler.go index 170a57f5..1edef1f5 100644 --- a/server/detectionhandler.go +++ b/server/detectionhandler.go @@ -93,7 +93,8 @@ func RegisterDetectionRoutes(srv *Server, r chi.Router, prefix string) { // @Summary Get Detection // @Description Retrieves a specific detection given an internal detection ID. This ID is unique only to this particular grid. -// @Tags Detections +// @Description Use the "Query Data" API to search for detections using other criteria, specifying a query parameter that includes the following, at a minimum: _index:"*:so-detection" +// @Tags Detections // @Security bearer[detections/read, events/read] // @Param id path string true "The detection ID to retrieve" example(zC73PJABrNRFAsnEYkqy) // @Success 200 {object} model.Detection "The detection was successfully retrieved" @@ -140,7 +141,7 @@ func (h *DetectionHandler) getDetection(w http.ResponseWriter, r *http.Request) // @Summary Get Detection By Public ID // @Description Retrieves a specific detection given a public detection ID. This ID is assigned by the ruleset author. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read] // @Param id path string true "The detection public ID to retrieve" example(2038279) // @Success 200 {object} model.Detection "The detection was successfully retrieved" @@ -194,7 +195,7 @@ func (h *DetectionHandler) getByPublicId(w http.ResponseWriter, r *http.Request) // @Description Creates a new detection by providing the detection object as the request body, in JSON format. // @Description Detections marked as community detections cannot be created with this API. // @Description While the public ID is required for some engines, the internal ID will always be populated by the server. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write,events/write, users/read] // @Param request body model.Detection true "The detection object to create" // @Success 200 {object} model.Detection "Returns the detection that was successfully created" @@ -324,7 +325,7 @@ func (h *DetectionHandler) createDetection(w http.ResponseWriter, r *http.Reques // @Summary Get Detection History // @Description Retrieves a specific detection's audit history given an internal detection ID. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read] // @Param id path string true "The detection ID to retrieve" example(zC73PJABrNRFAsnEYkqy) // @Success 200 {array} model.Auditable "The array of history audit objects. Note that these objects will also contain either the Detection fields or a DetectionComment fields." @@ -352,7 +353,7 @@ func (h *DetectionHandler) getDetectionHistory(w http.ResponseWriter, r *http.Re // @Summary Duplicate Detection // @Description Copies the detection associated with the given ID into a new detection. A new ID will be assigned to the duplicated detection. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param id path string true "The detection ID to duplicate" example(zC73PJABrNRFAsnEYkqy) // @Success 200 {object} model.Detection "The duplicated detection object." @@ -395,7 +396,7 @@ func (h *DetectionHandler) duplicateDetection(w http.ResponseWriter, r *http.Req // @Summary Update Detection // @Description Updates an existing detection by providing the new detection object as the request body, in JSON format. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param request body model.Detection true "The detection object to create" // @Success 200 {object} model.Detection "Returns the detection that was successfully updated" @@ -539,7 +540,7 @@ func (h *DetectionHandler) updateDetection(w http.ResponseWriter, r *http.Reques // @Summary Update Override Note // @Description Updates an existing override note. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param id path string true "The internal detection ID" example(zC73PJABrNRFAsnEYkqy) // @Param overrideIndex path number true "The 0-based index of the override within the detection" example(0) @@ -585,7 +586,7 @@ func (h *DetectionHandler) updateOverrideNote(w http.ResponseWriter, r *http.Req // @Summary Delete Detection // @Description Deletes an existing detection. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param id path string true "The internal detection ID" example(zC73PJABrNRFAsnEYkqy) // @Success 200 "The override note was deleted successfully" @@ -630,7 +631,7 @@ func (h *DetectionHandler) deleteDetection(w http.ResponseWriter, r *http.Reques // @Summary Manage Detections in Bulk // @Description Enables, disables, or deletes multiple detections asynchronously. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param newStatus path string true "The new status of the detection" Enums(enable, disable, delete) // @Param request body BulkOp true "The bulk detection search criteria" @@ -1015,7 +1016,7 @@ func syncLocalDetections(ctx context.Context, srv *Server, detections []*model.D // @Summary Create Detection Comment // @Description Creates a new detection comment for the detection associated with the provided detection ID. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param id path string true "The internal detection ID" example(zC73PJABrNRFAsnEYkqy) // @Param request body model.DetectionComment true "A detection comment object with the new content; any provided detection ID will be ignored" @@ -1051,7 +1052,7 @@ func (h *DetectionHandler) createComment(w http.ResponseWriter, r *http.Request) // @Summary Get Detection Comment // @Description Retrieves the comment associated with the given comment ID. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read] // @Param id path string true "The detection comment ID" example(MeEcnpMB4OVrR03M4und) // @Success 200 {object} model.DetectionComment "The comment has been successfully retrieved" @@ -1076,7 +1077,7 @@ func (h *DetectionHandler) getDetectionComment(w http.ResponseWriter, r *http.Re // @Summary Update Detection Comment // @Description Updates the comment associated with the given comment ID with the provided content. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param id path string true "The detection comment ID" example(MeEcnpMB4OVrR03M4und) // @Param request body model.DetectionComment true "A detection object with the new content" @@ -1113,7 +1114,7 @@ func (h *DetectionHandler) updateComment(w http.ResponseWriter, r *http.Request) // @Summary Delete Detection Comment // @Description Deletes the comment associated with the given comment ID. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read, detections/write, events/write] // @Param id path string true "The detection comment ID" example(MeEcnpMB4OVrR03M4und) // @Success 200 "The comment has been successfully deleted" @@ -1138,7 +1139,7 @@ func (h *DetectionHandler) deleteComment(w http.ResponseWriter, r *http.Request) // @Summary Get Detection Comments // @Description Retrieves the comments associated with the given detection ID. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/read, events/read] // @Param id path string true "The internal detection ID" example(zC73PJABrNRFAsnEYkqy) // @Success 200 {array} model.DetectionComment "The comments have been successfully retrieved" @@ -1169,7 +1170,7 @@ func (h *DetectionHandler) getDetectionComments(w http.ResponseWriter, r *http.R // @Summary Convert Rule Query // @Description Converts the given Sigma Detection rule into an Elasticsearch query. // @Description NOTE: The API method only works with Sigma rules. -// @Tags Detections +// @Tags Detections // @Security bearer // @Param request body model.Detection true "The Sigma detection object with the Content and optional Overrides populated" // @Success 200 {object} ConvertContentResp "The rule has been converted successfully" @@ -1200,7 +1201,7 @@ func (h *DetectionHandler) convertContent(w http.ResponseWriter, r *http.Request // @Summary Sync Detections // @Description Initiates an asynchronous synchronization of the specified detection engine. -// @Tags Detections +// @Tags Detections // @Security bearer[detections/write] // @Param engine path string true "The detection engine to sync" Enums(all, elastalert, suricata, strelka") // @Param type path string true "The type of sync to perform" Enums(full, update) @@ -1243,7 +1244,7 @@ func (h *DetectionHandler) syncEngineDetections(w http.ResponseWriter, r *http.R // @Summary Generate Public ID // @Description Requests the server generate an unused public ID. -// @Tags Detections +// @Tags Detections // @Security bearer // @Param engine path string true "The detection engine" Enums(elastalert, suricata") // @Success 200 {object} GenPublicIdResp "The ID has been generated" diff --git a/server/eventhandler.go b/server/eventhandler.go index d7ed2b3b..ba791273 100644 --- a/server/eventhandler.go +++ b/server/eventhandler.go @@ -45,11 +45,11 @@ func (h *EventHandler) eventsEnabled(next http.Handler) http.Handler { }) } -// @Summary Search for Events +// @Summary Query Data // @Description Given a search query, fetch all matching results, up to the maximum number requested, or the maximum that the backend data server will provide. // @Description.markdown get_events -// @Tags Events // @Security bearer[events/read] +// @Tags Query // @Param query query string true "User defined search query" example(tags:conn | groupby source.ip destination.ip network.protocol destination.port) // @Param range query string true "Date range, in the specified timezone" example(2024/12/03 03:09:31 PM - 2024/12/04 03:09:31 PM) // @Param zone query string true "Timezone of the date range" example(America/New_York) @@ -93,10 +93,10 @@ func (h *EventHandler) getEvent(w http.ResponseWriter, r *http.Request) { web.Respond(w, r, http.StatusOK, results) } -// @Summary Acknowledge Events -// @Description Acknowledges the alert event. Note that this will not remove the event from connected SOC users' Alert screens when the same alert event happens to be also present on their Alert screen. However, if they refresh the Alert screen the alert event will no longer be list. -// @Tags Events +// @Summary Acknowledge Alerts +// @Description Acknowledges the alert event(s) matching the given query. Note that this will not remove the event from connected SOC users' Alert screens when the same alert event happens to be also present on their Alert screen. However, if they refresh the Alert screen the alert event will no longer be listed. // @Security bearer[events/ack,events/write] +// @Tags Query // @Param request body model.EventAckCriteria true "Ack criteria" // @Accept json // @Produce json diff --git a/server/gridhandler.go b/server/gridhandler.go index b1825707..71bab33c 100644 --- a/server/gridhandler.go +++ b/server/gridhandler.go @@ -31,7 +31,7 @@ func RegisterGridRoutes(srv *Server, r chi.Router, prefix string) { // @Description Retrieves the list of nodes that have recently checked-in with SOC. Nodes are grid members that have recently checked in with SOC. // @Description Under certain scenarios this may not include nodes that are accepted members of the grid but currently offline. // @Description Effectively, the results of this API call will match the view of the Grid screen in SOC (Not the Grid Members screen). -// @Tags Grid +// @Tags Grid // @Security bearer[nodes/read] // @Produce json // @Success 200 {array} model.Node "The list of grid nodes" diff --git a/server/gridmembershandler.go b/server/gridmembershandler.go index 0563a32d..6220732c 100644 --- a/server/gridmembershandler.go +++ b/server/gridmembershandler.go @@ -58,7 +58,7 @@ func (h *GridMembersHandler) gridMembersEnabled(next http.Handler) http.Handler // @Summary Get Grid Members // @Description Retrieves the complete list of all machine members associated, in some capacity, with this grid. A grid member is not necessarily an official grid node. // @Description For example, this list includes members that are not yet accepted into the grid, as well as members that have been rejected from joining the grid. -// @Tags Grid +// @Tags Grid // @Security bearer[grid/read] // @Produce json // @Success 200 {array} model.GridMember "The list of grid members" @@ -83,7 +83,7 @@ func (h *GridMembersHandler) getGridMembers(w http.ResponseWriter, r *http.Reque // @Description Imports the data from the given file. This is commonly used for importing PCAP and EVTX data directly into the node. // @Description The max file size defaults to 25MB unless customized in the server configuration. // @Description The multipart-form value must include an attachment with a filename and associated data stream. -// @Tags Grid +// @Tags Grid // @Security bearer[events/write] // @Param id path string true "The node ID into which this data will be imported" example(so_standalone) // @Param attachment formData file true "The data to import (note this request must use multipart/form-data content type)" @@ -271,7 +271,7 @@ func (h *GridMembersHandler) postImport(w http.ResponseWriter, r *http.Request) // @Summary Manage Grid Member // @Description Manages a grid member by performing the specified operation. // @Description.markdown manage_grid_member -// @Tags Grid +// @Tags Grid // @Security bearer[grid/write] // @Param id path string true "The grid member ID to be managed" example(so_standalone) // @Param operation path string true "The operation to perform: add, reject, delete, test, restart" example(reject) diff --git a/server/infohandler.go b/server/infohandler.go index e7f4838d..97071c60 100644 --- a/server/infohandler.go +++ b/server/infohandler.go @@ -37,7 +37,7 @@ func RegisterInfoRoutes(srv *Server, r chi.Router, prefix string) { // @Summary Get Server Information // @Description Requests the Security Onion grid general details. -// @Tags Grid +// @Tags Grid // @Security bearer // @Produce json // @Success 200 {object} model.Info "The retrieved Info object" diff --git a/server/jobhandler.go b/server/jobhandler.go index bcba62f2..f5f86b38 100644 --- a/server/jobhandler.go +++ b/server/jobhandler.go @@ -39,7 +39,7 @@ func RegisterJobRoutes(srv *Server, r chi.Router, prefix string) { // @Summary Get Job // @Description Retrieves a specific job that matches the given job ID. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/read] // @Param jobId path integer true "The job ID" example(1004) // @Produce json @@ -74,7 +74,7 @@ func (h *JobHandler) getJob(w http.ResponseWriter, r *http.Request) { // @Summary Create Job // @Description Create a new job. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/write] // @Param request body model.Job true "The job details. The job ID, create timestamp, status, and other processing-related fields will be populated by the server. For a new analyze job, only the kind (analyze), nodeId, and parameters should be specified. For the parameters, the caseId, artifactType, and other relevant fields needed by the analyzers should be submitted." // @Produce json @@ -107,7 +107,7 @@ func (h *JobHandler) postJob(w http.ResponseWriter, r *http.Request) { // @Summary Update Job // @Description Update an existing job with the provided job details. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/write] // @Param request body model.Job true "The job details. Any provided user ID or node ID will be ignored as those fields are read-only after initial job creation." // @Produce json @@ -141,7 +141,7 @@ func (h *JobHandler) putJob(w http.ResponseWriter, r *http.Request) { // @Summary Delete Job // @Description Deletes an existing job and its related output results. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/delete] // @Param jobId path integer true "The job ID" example(1004) // @Success 200 "The job was successfully deleted" diff --git a/server/jobshandler.go b/server/jobshandler.go index 5abdbece..aec17c49 100644 --- a/server/jobshandler.go +++ b/server/jobshandler.go @@ -31,7 +31,7 @@ func RegisterJobsRoutes(srv *Server, r chi.Router, prefix string) { // @Summary Get Jobs // @Description Retrieves the list of jobs that match the given parameters. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/read] // @Param kind query string true "The job kind, such as 'analyze'. Specify an empty value for PCAP jobs" example(analyzer) // @Param parameters[artifact][id] query string false "Optional case ID to locate matching analyze jobs" example(P5mgnpEB0JpjNDZz1bIN) diff --git a/server/nodehandler.go b/server/nodehandler.go index 5dbe4af5..71c18ddd 100644 --- a/server/nodehandler.go +++ b/server/nodehandler.go @@ -31,7 +31,7 @@ func RegisterNodeRoutes(srv *Server, r chi.Router, prefix string) { // @Summary Node Check-in / Get Pending Jobs // @Description Used by Security Onion agent nodes to check-in with their current metrics and request any pending jobs assigned to it. -// @Tags Grid, Jobs +// @Tags Grid, Jobs // @Security bearer[nodes/write,jobs/process] // @Param request body model.Node true "The node object with recent metrics" // @Produce json diff --git a/server/packethandler.go b/server/packethandler.go index d4c22cb4..08b9c50e 100644 --- a/server/packethandler.go +++ b/server/packethandler.go @@ -31,7 +31,7 @@ func RegisterPacketRoutes(srv *Server, r chi.Router, prefix string) { // @Summary Get PCAP Packets // @Description Retrieves the packets collected and attached to the job represented by the given job ID. This request assumes the job is a PCAP job. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/read] // @Param jobId path integer true "The job ID" example(1004) // @Param unwrap query boolean false "If true, and if the stream data is eligible the stream data will be unwrapped. An example of wrapped stream data is VXLAN packet data." example(true) diff --git a/server/queryhandler.go b/server/queryhandler.go index 0700587e..d6b5d6c8 100644 --- a/server/queryhandler.go +++ b/server/queryhandler.go @@ -32,9 +32,9 @@ func RegisterQueryRoutes(srv *Server, r chi.Router, prefix string) { } // @Summary Build Query -// @Description Requests the server provide a new query for the client to show, given a particular change needed in the query. -// @Tags Events +// @Description Requests the server provide a new query for the SOC client to show, given a particular change needed in the query. // @Security bearer +// @Tags Query // @Param operation path string true "The type of operation for this query update. Supports: grouped, filtered, sorted" example(grouped) // @Param query formData string true "The current query string to be modified" example(somefield: somevalue | groupby anotherfield) // @Param field formData string true "The field to be used for the operation" example(newfield) diff --git a/server/roleshandler.go b/server/roleshandler.go index b910cb0a..8b286149 100644 --- a/server/roleshandler.go +++ b/server/roleshandler.go @@ -46,7 +46,7 @@ func rolesEnabled(server *Server) func(next http.Handler) http.Handler { // @Summary Get Roles // @Description Retrieves the set of available user roles. -// @Tags Users +// @Tags Users // @Security bearer[roles/read] // @Produce json // @Success 200 {array} string "List of user role names" @@ -67,7 +67,7 @@ func (h *RolesHandler) getRoles(w http.ResponseWriter, r *http.Request) { // @Description Note: User roles are made up of assigned permissions. API clients do not // @Description use roles and instead are directly assigned individual permissions since // @Description each API client is expected to be configured for a specific task. -// @Tags Clients +// @Tags Clients // @Security bearer[permissions/read] // @Produce json // @Success 200 {array} string "List of permission names" diff --git a/server/streamhandler.go b/server/streamhandler.go index 14976615..9d2991d9 100644 --- a/server/streamhandler.go +++ b/server/streamhandler.go @@ -43,7 +43,7 @@ func RegisterStreamRoutes(srv *Server, r chi.Router, prefix string) { // @Summary Download Job Output // @Description Returns the full job output stream for the given job ID. An example of a job stream is a packet capture (PCAP) file. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/read] // @Param jobId path integer true "The job ID" example(1004) // @Param ext query string false "Optional filename extension to use on the returned stream. Appends extension to stream name, unless stream name already contains '.bin' in which case it replaces that extension." example(pcap) @@ -126,7 +126,7 @@ func (h *StreamHandler) getStream(w http.ResponseWriter, r *http.Request) { // @Summary Upload Job Output // @Description Sends the job output up to the server for posterity and future retrieval. Not all jobs will have binary job output to upload. The job ID is used to reference the job for this output stream. -// @Tags Jobs +// @Tags Jobs // @Security bearer[jobs/process] // @Param jobId path integer true "The job ID" example(1004) // @Param request body object true "The job output stream byte content" diff --git a/server/usershandler.go b/server/usershandler.go index e2e0aeb4..d2f5c0de 100644 --- a/server/usershandler.go +++ b/server/usershandler.go @@ -66,7 +66,7 @@ func (h *UsersHandler) usersEnabled(next http.Handler) http.Handler { // @Summary Get Users // @Description Returns all SOC users. -// @Tags Users +// @Tags Users // @Security bearer[users/read] // @Produce json // @Success 200 {array} model.User "List of user objects, or empty list if not permitted to view user list" @@ -88,7 +88,7 @@ func (h *UsersHandler) getUsers(w http.ResponseWriter, r *http.Request) { // @Summary Create User // @Description Creates a new SOC user. -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Param request body model.User true "User object to be created. The provided email address, firstname, lastname, note, roles, and password will be used. All other fields are ignored." // @Accept json @@ -129,7 +129,7 @@ func (h *UsersHandler) postUser(w http.ResponseWriter, r *http.Request) { // @Description Grants an existing user a role. The user will then have permissions that this role provides. // @Param id path string true "The user ID" // @Param role path string true "The role name" -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Success 200 "The role was successfully granted to the user" // @Failure 400 "The provided input object or parameters are malformed or invalid" @@ -166,7 +166,7 @@ func (h *UsersHandler) postAddRole(w http.ResponseWriter, r *http.Request) { // @Summary Update User // @Description Update a user with the provided user object data. -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Param id path string true "The user ID" // @Param request body model.User true "User object containing new updates. The provided email address, firstname, lastname, and note will be updated. All other fields are ignored." @@ -208,7 +208,7 @@ func (h *UsersHandler) putUser(w http.ResponseWriter, r *http.Request) { // @Summary Synchronize Users // @Description Synchronizes all SOC users across the grid. This is an asynchronous request. // @Description The background operation can take several minutes to complete. -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Success 200 "The synchronization request has been submitted" // @Failure 401 "Request was not properly authenticated" @@ -229,7 +229,7 @@ func (h *UsersHandler) putSync(w http.ResponseWriter, r *http.Request) { // @Summary Change Password // @Description Update a user's password with the provided value. -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Param id path string true "The user ID" // @Param request body model.User true "User object containing the new password. All other fields are ignored." @@ -274,7 +274,7 @@ func (h *UsersHandler) putPassword(w http.ResponseWriter, r *http.Request) { // @Summary Toggle User Enabled // @Description Update a user's status to enabled or disabled -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Param id path string true "The user ID" // @Param toggle path string true "Desired toggle action. Set to 'enable' or 'disable'." @@ -316,7 +316,7 @@ func (h *UsersHandler) putToggleUser(w http.ResponseWriter, r *http.Request) { // @Summary Delete User // @Description Deletes the provided user ID. -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Param id path string true "The user ID" // @Success 200 "User successfully deleted" @@ -348,7 +348,7 @@ func (h *UsersHandler) deleteUser(w http.ResponseWriter, r *http.Request) { // @Description Denies an existing user a role. The user will no longer have permissions that this role provides. // @Param id path string true "The user ID" // @Param role path string true "The role name" -// @Tags Users +// @Tags Users // @Security bearer[users/write] // @Success 200 "The role was successfully removed from the user" // @Failure 400 "The provided input object or parameters are malformed or invalid" diff --git a/server/utilhandler.go b/server/utilhandler.go index 94d8ff2c..a2c3dc7c 100644 --- a/server/utilhandler.go +++ b/server/utilhandler.go @@ -38,9 +38,9 @@ func RegisterUtilRoutes(srv *Server, r chi.Router, prefix string) { } // @Summary DNS Reverse Lookup -// @Description Performs a reverse name lookup on a list of provided IP addresses. The configured list of DNS overrides is checked first, and if no match is found a DNS reverse lookup is performed. The input listed is deduplicated first to avoid repeated lookups in the same request. -// @Tags Events +// @Description Performs a reverse name lookup query on a list of provided IP addresses. The configured list of DNS overrides is checked first, and if no match is found a DNS reverse lookup is performed. The input listed is deduplicated first to avoid repeated lookups in the same request. // @Security bearer +// @Tags Query // @Param request body []string true "List of IP addresses to reverse lookup" // @Accept json // @Produce json