Skip to content

Update Alert

Request

Updates the triage state of a single alert in the token-linked SIEM: its lifecycle status, the analyst verdict, a comment and who it is assigned to.

Operation ID: siem_update_alert

Security
BearerAuth
Path
idstringrequired

Uid of the alert (URL encoded). This will be finding_info.uid in the OCSF model, as Query Alerts and Get Alert return it.

Query
metaArray of strings

Add metadata to the response by invoking meta functions. Documentation for meta functions is available. Not all meta functions are available at every endpoint.

Bodyapplication/jsonrequired
status_idinteger or null(ocsfv1.3.0detectionfindingStatusId)

The triage state to move the alert to, as an OCSF Detection Finding status_id:

  • 0: Unknown. Rejected with a 400.
  • 1: New.
  • 2: InProgress.
  • 3: Suppressed. Requires a verdict_id other than 2 (TruePositive); either violation is rejected with a 400.
  • 4: Resolved.
  • 99: Other. Rejected with a 400.

Providers with no distinct suppressed state read a closed alert with a false-positive (or equivalent) verdict back as 3.

verdict_idinteger or null(ocsfv1.3.0incidentfindingVerdictId)

The analyst verdict to record, as an OCSF Incident Finding verdict_id:

  • 0: Unknown. Clears the verdict where the provider supports it.
  • 1: FalsePositive.
  • 2: TruePositive.
  • 3: Disregard.
  • 4: Suspicious.
  • 5: Benign.
  • 6: Test.
  • 7: InsufficientData.
  • 8: SecurityRisk.
  • 9: ManagedExternally.
  • 10: Duplicate.
  • 99: Other. Rejected with a 400.

Providers store different subsets, some only on a closed alert, and a verdict the provider cannot store is rejected with a 400.

commentstring or null

A comment to append to the alert. Comments are appended, never replaced, so re-sending the same comment adds it twice.

assigneeobject or null(AlertAssignee)

Who to assign the alert to, by exactly one of email_addr or uid; {} unassigns where the provider supports it. Any other attribute, or an identifier sent as null, is rejected with a 400.

curl
curl -i -X POST \
  'https://api.synqly.com/v1/siem/alerts/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Bodyapplication/json
messagesobject or null(MessagesResponse)

Additional messages from the service response that may be helpful to the client.

metaobject or null(MetaResponse)

Various metadata about the results organized by group, then type, then field.

resultobject or null(ocsfv1.3.0detectionfindingDetectionFinding)

The updated alert, re-fetched from the provider after the write. Omitted when the write was applied but the alert could not be read back, for example because the re-fetch failed, was rate limited or did not find the alert. The response is still a 2xx in that case, and messages carries a problem explaining why result is missing. Every provider can omit it, so callers must not assume it is present.

Response
{ "result": { "action": "string", "action_id": 0, "activity_id": 0, "activity_name": "string", "actor": { … }, "api": { … }, "attacks": [ … ], "authorizations": [ … ], "category_name": "string", "category_uid": 0, "class_uid": 0, "cloud": { … }, "comment": "string", "confidence": "string", "confidence_id": 0, "confidence_score": 0, "count": 0, "custom_fields": {}, "device": { … }, "disposition": "string", "disposition_id": 0, "duration": 0, "end_time": 0, "end_time_dt": "2019-08-24T14:15:22Z", "enrichments": [ … ], "evidences": [ … ], "finding_info": { … }, "firewall_rule": { … }, "impact": "string", "impact_id": 0, "impact_score": 0, "malware": [ … ], "message": "string", "metadata": { … }, "observables": [ … ], "osint": [ … ], "raw_data": "string", "remediation": { … }, "resources": [ … ], "risk_details": "string", "risk_level": "string", "risk_level_id": 0, "risk_score": 0, "severity": "string", "severity_id": 0, "start_time": 0, "start_time_dt": "2019-08-24T14:15:22Z", "status": "string", "status_code": "string", "status_detail": "string", "status_id": 0, "time": 0, "time_dt": "2019-08-24T14:15:22Z", "timezone_offset": 0, "type_name": "string", "type_uid": 0, "unmapped": {}, "vulnerabilities": [ … ] }, "messages": { "problems": [ … ] }, "meta": { "stats": { … }, "api": { … }, "mapping": { … } } }