API docs by Redocly

Security Onion Connect API

Download OpenAPI specification:

URL: http://github.com/security-onion-solutions/securityonion/discussions License: Elastic 2.0 Terms of Service

Perform SOC operations via server-to-server integration using a client API account via OAuth2.0.

Security Onion Documentation Online

Assistant

Get Assistant Sessions

Get chat session metadata from a specific user.

Authorizations:
bearer
path Parameters
userId
required
string

ID of the user to retrieve sessions from

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Assistant Session History

Retrieve a chat session's messages for a given user and session.

Authorizations:
bearer
path Parameters
userId
required
string

ID of the user to retrieve the session from

sessionId
required
string

ID of the session to retrieve, it must belong to the indicated user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Assistant Sessions

Get a list of all previous chat session metadata across all users.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Usage Statistics

Retrieve usage statistics of the AI assistant over a specified date range for every user.

Authorizations:
bearer
query Parameters
range
required
string
Example: range=2024/12/03 03:09:31 PM - 2024/12/04 03:09:31 PM

Date range, in the specified timezone

zone
required
string
Example: zone=America/New_York

Timezone of the date range

format
required
string
Example: format=2006/01/02 3:04:05 PM

Date range date format. Use the example, exactly as shown, if not familiar with date formats

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Assistant Balance

Retrieve the current balance/usage information for the AI assistant.

Authorizations:
bearerbearer
path Parameters
modelAndAdapter
required
string
Example: qwen/qwen2.5-small@MyOpenAIChatAdapter

Model Id (including slashes) and Adapter Name to get balance for

Responses

Response samples

Content type
application/json
{
  • "credits": 1,
  • "input_tokens": 5,
  • "output_tokens": 10
}

Send Chat Message

Send a message to the AI assistant and receive a response. Supports both streaming (SSE) and non-streaming responses.

Authorizations:
bearer
query Parameters
entityType
string

Type of entity associated with this session (e.g., 'alert_investigation')

entityId
string

ID of the entity associated with this session (e.g., alert's soc_id)

Request Body schema: application/json
required

Chat message object with message text and optional session ID

msg
string
sessionId
string

Responses

Request samples

Content type
application/json
{
  • "msg": "string",
  • "sessionId": "string"
}

Response samples

Content type
[
  • {
    }
]

Get Assistant Sessions

Retrieve a list of all previous chat session metadata for the authenticated user.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Session

Delete a specific chat session and all its associated messages.

Authorizations:
bearer
path Parameters
sessionId
required
string

Session ID to delete

Responses

Get Session Details

Retrieve the complete chat history and usage for a specific session. Can lookup deleted sessions.

Authorizations:
bearerbearer
path Parameters
sessionId
required
string

Session ID to retrieve history for

Responses

Response samples

Content type
application/json
{
  • "history": [
    ],
  • "session": {
    }
}

Update metadata for a Session

Allow a user to modify their own session tags.

Authorizations:
bearer
path Parameters
sessionId
required
string

Session ID to modify

Request Body schema: application/json
required

Indicate what field we're doing what operation with.

action
string
tag
string

Responses

Request samples

Content type
application/json
{
  • "action": "add",
  • "tag": "shared"
}

Response samples

Content type
application/json
{ }

Execute Tool

Execute a tool on behalf of the assistant and continue the conversation with the result. Note that more permissions may be checked depending on the tool being executed.

Authorizations:
bearer
path Parameters
name
required
string

Name of the tool to execute

Request Body schema: application/json
required

Tool execution request containing session ID, tool use ID, and parameters

object (model.ToolRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
[
  • {
    }
]

Cases

Create Case

Create a new case given a populated case object as input.

Authorizations:
bearer
Request Body schema: application/json
required

New case object. ID will be generated by the server.

assigneeId
string

The user ID that is assigned to work on this case.

category
string

A category is a way to group similar cases together and can be arbitrary values, or static values, depending on how the system if configured.

completeTime
string

The date and time that the case was completed. A case is completed when the status is changed to 'closed'. This is a read-only field.

createTime
string

The date and time that this object was created. This is a read-only field.

description
string

The full description of the case.

id
string

The ID assigned to this object by the server. This is a read-only field.

kind
string

The kind of object. This is a read-only field.

operation
string

The operation that was applied to the object. This is a read-only field.

pap
string

The Permissiable Actions Protocol value.

priority
integer

The priority of the case. Lower values typically represent increasing importance.

severity
string

The serverity of the case. Typical values are: critical, high, medium, low

startTime
string

The date and time that the case status was changed to 'in progress'. This is a read-only field.

status
string

The state of the case. Typical values are: new, in progress, closed

tags
Array of strings

A tag is another way to group similar cases together and can be arbitrary values, or static values, depending on how the system if configured.

template
string

A case ID representing the case to use as a template when creating this case. The template case fields will be copied into the new case.

title
string

The brief case title or summary

tlp
string

The Traffic Light Protocol value.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "assigneeId": "022d1936-6ca3-49c1-b3ee-6a5b27d1b8b1",
  • "category": "general",
  • "completeTime": "2024-11-14T15:33:02Z",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered anomalous events during the overnight hours of November 14-15. Atypical large network volumes passed through SMTP server.",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "pap": "white",
  • "priority": 1,
  • "severity": "high",
  • "startTime": "2024-11-14T15:03:22Z",
  • "status": "new",
  • "tags": [
    ],
  • "template": "some_case_id_to_be_used_as_template",
  • "title": "Possible intrusion via SMTP server",
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Response samples

Content type
application/json
{
  • "assigneeId": "022d1936-6ca3-49c1-b3ee-6a5b27d1b8b1",
  • "category": "general",
  • "completeTime": "2024-11-14T15:33:02Z",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered anomalous events during the overnight hours of November 14-15. Atypical large network volumes passed through SMTP server.",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "pap": "white",
  • "priority": 1,
  • "severity": "high",
  • "startTime": "2024-11-14T15:03:22Z",
  • "status": "new",
  • "tags": [
    ],
  • "template": "some_case_id_to_be_used_as_template",
  • "title": "Possible intrusion via SMTP server",
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Update Case

Updates an existing case with a provided case object as input.

Authorizations:
bearer
Request Body schema: application/json
required

Replacement case object. The provided ID will be used to match the existing case.

assigneeId
string

The user ID that is assigned to work on this case.

category
string

A category is a way to group similar cases together and can be arbitrary values, or static values, depending on how the system if configured.

completeTime
string

The date and time that the case was completed. A case is completed when the status is changed to 'closed'. This is a read-only field.

createTime
string

The date and time that this object was created. This is a read-only field.

description
string

The full description of the case.

id
string

The ID assigned to this object by the server. This is a read-only field.

kind
string

The kind of object. This is a read-only field.

operation
string

The operation that was applied to the object. This is a read-only field.

pap
string

The Permissiable Actions Protocol value.

priority
integer

The priority of the case. Lower values typically represent increasing importance.

severity
string

The serverity of the case. Typical values are: critical, high, medium, low

startTime
string

The date and time that the case status was changed to 'in progress'. This is a read-only field.

status
string

The state of the case. Typical values are: new, in progress, closed

tags
Array of strings

A tag is another way to group similar cases together and can be arbitrary values, or static values, depending on how the system if configured.

template
string

A case ID representing the case to use as a template when creating this case. The template case fields will be copied into the new case.

title
string

The brief case title or summary

tlp
string

The Traffic Light Protocol value.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "assigneeId": "022d1936-6ca3-49c1-b3ee-6a5b27d1b8b1",
  • "category": "general",
  • "completeTime": "2024-11-14T15:33:02Z",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered anomalous events during the overnight hours of November 14-15. Atypical large network volumes passed through SMTP server.",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "pap": "white",
  • "priority": 1,
  • "severity": "high",
  • "startTime": "2024-11-14T15:03:22Z",
  • "status": "new",
  • "tags": [
    ],
  • "template": "some_case_id_to_be_used_as_template",
  • "title": "Possible intrusion via SMTP server",
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Response samples

Content type
application/json
{
  • "assigneeId": "022d1936-6ca3-49c1-b3ee-6a5b27d1b8b1",
  • "category": "general",
  • "completeTime": "2024-11-14T15:33:02Z",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered anomalous events during the overnight hours of November 14-15. Atypical large network volumes passed through SMTP server.",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "pap": "white",
  • "priority": 1,
  • "severity": "high",
  • "startTime": "2024-11-14T15:03:22Z",
  • "status": "new",
  • "tags": [
    ],
  • "template": "some_case_id_to_be_used_as_template",
  • "title": "Possible intrusion via SMTP server",
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Get Case

Retrieves a case given the provided case ID and returns the case details. 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"

Authorizations:
bearer
path Parameters
id
required
string

The case ID to retrieve

Responses

Response samples

Content type
application/json
{
  • "assigneeId": "022d1936-6ca3-49c1-b3ee-6a5b27d1b8b1",
  • "category": "general",
  • "completeTime": "2024-11-14T15:33:02Z",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered anomalous events during the overnight hours of November 14-15. Atypical large network volumes passed through SMTP server.",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "pap": "white",
  • "priority": 1,
  • "severity": "high",
  • "startTime": "2024-11-14T15:03:22Z",
  • "status": "new",
  • "tags": [
    ],
  • "template": "some_case_id_to_be_used_as_template",
  • "title": "Possible intrusion via SMTP server",
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Update Case Artifact

Updates an existing case artifact with a provided artifact object as input. Important: The artifact value and type cannot be modified.

Authorizations:
bearer
Request Body schema: application/json
required

Replacement artifact object. The provided ID will be used to match the existing artifact.

artifactType
required
string

The artifact type as set by the server. This is an internal, read-only field.

caseId
required
string

The case ID for which this artifact is to be attached, or is already attached.

createTime
string

The date and time that this object was created. This is a read-only field.

description
string

A description that explains how this artifact relates to the case.

groupId
string

The group ID as set by the server. This is an internal, read-only field.

groupType
string

The group type as set by the server. This is an internal, read-only field.

id
string

The ID assigned to this object by the server. This is a read-only field.

ioc
boolean

A flag representing whether this artifact is an indicator of compromise (IoC).

kind
string

The kind of object. This is a read-only field.

md5
string

An MD5 hash of the artifact stream. This field is determined by the server upon file upload and is ready-only.

mimeType
string

The mime type of the artifact stream. This field is determined by the server upon file upload and is read-only.

operation
string

The operation that was applied to the object. This is a read-only field.

protected
boolean

A flag representing whether this file artifact is protected. A protected file will be automatically zipped by the server before being retrieved, to avoid accidentally executing a potentially harmful attachment.

sha1
string

A SHA-1 hash of the artifact stream. This field is determined by the server upon file upload and is ready-only.

sha256
string

A SHA-256 hash of the artifact stream. This field is determined by the server upon file upload and is ready-only.

streamId
string

The stream ID of the artifact stream. This field is determined by the server upon file upload and is ready-only.

streamLength
integer

The length of the artifact stream. This field is determined by the server upon file upload and is ready-only.

tags
Array of strings

Tags to assign to this artifact.

tlp
string

The traffic light protocol value for this artifact.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

value
required
string

The value of this artifact. Essentially this is the content of the artifact itself, such as an IP address, a hostname, a filename, etc.

Responses

Request samples

Content type
application/json
{
  • "artifactType": "ip",
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Additional supporting evidence",
  • "groupId": "",
  • "groupType": "evidence",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "ioc": false,
  • "kind": "case",
  • "md5": "d9cca721a735dac4efe709e0f3518373",
  • "mimeType": "application/json",
  • "operation": "create",
  • "protected": false,
  • "sha1": "a0571c5b9493187adb5bd07ad0faf279a86251df",
  • "sha256": "9c1f8398f5a92eee44aee58d000a4dc1705f9c25e29683f7730215bc1274cff1",
  • "streamId": "f2fS-DajPqlMo-221Nmn",
  • "streamLength": 4096,
  • "tags": [
    ],
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "1.2.3.4"
}

Response samples

Content type
application/json
{
  • "artifactType": "ip",
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Additional supporting evidence",
  • "groupId": "",
  • "groupType": "evidence",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "ioc": false,
  • "kind": "case",
  • "md5": "d9cca721a735dac4efe709e0f3518373",
  • "mimeType": "application/json",
  • "operation": "create",
  • "protected": false,
  • "sha1": "a0571c5b9493187adb5bd07ad0faf279a86251df",
  • "sha256": "9c1f8398f5a92eee44aee58d000a4dc1705f9c25e29683f7730215bc1274cff1",
  • "streamId": "f2fS-DajPqlMo-221Nmn",
  • "streamLength": 4096,
  • "tags": [
    ],
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "1.2.3.4"
}

Create Case Artifact

Attach an observable to an existing case. Observables are considered "artifacts" in SOC internal terminology. If not creating a file artifact then only the artifact itself should be sent as the body, in JSON format. 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.

Authorizations:
bearer
Request Body schema: application/json
required

New case artifact object. ID will be generated by the server.

artifactType
required
string

The artifact type as set by the server. This is an internal, read-only field.

caseId
required
string

The case ID for which this artifact is to be attached, or is already attached.

createTime
string

The date and time that this object was created. This is a read-only field.

description
string

A description that explains how this artifact relates to the case.

groupId
string

The group ID as set by the server. This is an internal, read-only field.

groupType
string

The group type as set by the server. This is an internal, read-only field.

id
string

The ID assigned to this object by the server. This is a read-only field.

ioc
boolean

A flag representing whether this artifact is an indicator of compromise (IoC).

kind
string

The kind of object. This is a read-only field.

md5
string

An MD5 hash of the artifact stream. This field is determined by the server upon file upload and is ready-only.

mimeType
string

The mime type of the artifact stream. This field is determined by the server upon file upload and is read-only.

operation
string

The operation that was applied to the object. This is a read-only field.

protected
boolean

A flag representing whether this file artifact is protected. A protected file will be automatically zipped by the server before being retrieved, to avoid accidentally executing a potentially harmful attachment.

sha1
string

A SHA-1 hash of the artifact stream. This field is determined by the server upon file upload and is ready-only.

sha256
string

A SHA-256 hash of the artifact stream. This field is determined by the server upon file upload and is ready-only.

streamId
string

The stream ID of the artifact stream. This field is determined by the server upon file upload and is ready-only.

streamLength
integer

The length of the artifact stream. This field is determined by the server upon file upload and is ready-only.

tags
Array of strings

Tags to assign to this artifact.

tlp
string

The traffic light protocol value for this artifact.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

value
required
string

The value of this artifact. Essentially this is the content of the artifact itself, such as an IP address, a hostname, a filename, etc.

Responses

Request samples

Content type
application/json
{
  • "artifactType": "ip",
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Additional supporting evidence",
  • "groupId": "",
  • "groupType": "evidence",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "ioc": false,
  • "kind": "case",
  • "md5": "d9cca721a735dac4efe709e0f3518373",
  • "mimeType": "application/json",
  • "operation": "create",
  • "protected": false,
  • "sha1": "a0571c5b9493187adb5bd07ad0faf279a86251df",
  • "sha256": "9c1f8398f5a92eee44aee58d000a4dc1705f9c25e29683f7730215bc1274cff1",
  • "streamId": "f2fS-DajPqlMo-221Nmn",
  • "streamLength": 4096,
  • "tags": [
    ],
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "1.2.3.4"
}

Response samples

Content type
application/json
{
  • "artifactType": "ip",
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Additional supporting evidence",
  • "groupId": "",
  • "groupType": "evidence",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "ioc": false,
  • "kind": "case",
  • "md5": "d9cca721a735dac4efe709e0f3518373",
  • "mimeType": "application/json",
  • "operation": "create",
  • "protected": false,
  • "sha1": "a0571c5b9493187adb5bd07ad0faf279a86251df",
  • "sha256": "9c1f8398f5a92eee44aee58d000a4dc1705f9c25e29683f7730215bc1274cff1",
  • "streamId": "f2fS-DajPqlMo-221Nmn",
  • "streamLength": 4096,
  • "tags": [
    ],
  • "tlp": "red",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "1.2.3.4"
}

Get Case Artifacts

Searches for all artifacts attached to the given case ID and returns the matching artifacts, if any. Observables are considered "artifacts" in SOC internal terminology. If the case does not exist, this method will respond with a 200 status and an empty list.

Authorizations:
bearer
path Parameters
groupType
required
string
Example: attachments

The type of artifacts to retrieve [attachments, evidence]

query Parameters
id
required
string

The case ID to use for searching all artifacts

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Case Artifact

Removes a case artifact. Observables are considered "artifacts" in SOC internal terminology.

Authorizations:
bearer
path Parameters
id
required
string

The artifact ID to remove

Responses

Get Artifact Stream

Returns the artifact stream for the given artifact ID. Artifact streams are typically file artifacts.

Authorizations:
bearer
path Parameters
id
required
string

The artifact's stream ID

Responses

Update Case Comment

Updates an existing case comment with a provided comment object as input.

Authorizations:
bearer
Request Body schema: application/json
required

Replacement comment object. The provided ID will be used to match the existing comment.

caseId
required
string

The case ID for which this comment is to be attached, or is already attached.

createTime
string

The date and time that this object was created. This is a read-only field.

description
required
string

The comment content itself. Can contain limited markdown syntax.

hours
number

The number of hours spent on the work referenced in this comment. Can be a decimal value.

id
string

The ID assigned to this object by the server. This is a read-only field.

kind
string

The kind of object. This is a read-only field.

operation
string

The operation that was applied to the object. This is a read-only field.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered another anomaly around the same time involving missing logs on server xyz.",
  • "hours": 2.5,
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Response samples

Content type
application/json
{
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered another anomaly around the same time involving missing logs on server xyz.",
  • "hours": 2.5,
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Create Case Comment

Add a new comment to an existing case.

Authorizations:
bearer
Request Body schema: application/json
required

New comment object. ID will be generated by the server.

caseId
required
string

The case ID for which this comment is to be attached, or is already attached.

createTime
string

The date and time that this object was created. This is a read-only field.

description
required
string

The comment content itself. Can contain limited markdown syntax.

hours
number

The number of hours spent on the work referenced in this comment. Can be a decimal value.

id
string

The ID assigned to this object by the server. This is a read-only field.

kind
string

The kind of object. This is a read-only field.

operation
string

The operation that was applied to the object. This is a read-only field.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Discovered another anomaly around the same time involving missing logs on server xyz.",
  • "hours": 2.5,
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Response samples

Content type
application/json
{
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "createTime": "2024-11-14T15:03:22Z",
  • "fields": {
    },
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Delete Case Comment

Removes a case comment from a case and deletes the comment.

Authorizations:
bearer
path Parameters
id
required
string

The comment ID to remove

Responses

Get Case Comments

Searches for all comments assigned to the given case ID and returns the matching comments, if any. If the case does not exist, this method will respond with a 200 status and an empty list.

Authorizations:
bearer
path Parameters
id
required
string

The case ID to use for searching all related comments

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Case Related Event

Attach a related event to an existing case.

Authorizations:
bearer
Request Body schema: application/json
required

Query object used to find original events to attach to a given case. RelatedEvent IDs will be generated by the server.

acknowledged
boolean

Whether to attach events that are already acknowledged: true = act on acknowledged events, false = act on unacknowledged events

caseId
required
string

The case ID for which this related event is to be attached, or is already attached.

dateRange
string

The date range to use for searching for matching events

dateRangeFormat
string

The date range format. If unsure how to use this then use the example value exactly as shown.

escalated
boolean

Whether to attach events that are already escalated to a case: true = act on escalated events, false = act on unescalated events

required
object

A mapping of related event field names and their values.

timezone
string

The timezone to use with the date range

Responses

Request samples

Content type
application/json
{
  • "acknowledged": true,
  • "caseId": "PdFc-JIBLkNJ8-bDfz47",
  • "dateRange": "2024/12/03 02:31:35 PM - 2024/12/04 02:31:35 PM",
  • "dateRangeFormat": "2006/01/02 3:04:05 PM",
  • "escalated": false,
  • "fields": {
    },
  • "timezone": "America/New_York"
}

Response samples

Content type
application/json
{
  • "count": 120
}

Delete Case Related Event

Removes a related event from a case.

Authorizations:
bearer
path Parameters
id
required
string

The related event ID to remove

Responses

Get Related Events

Searches for all related events associated with the given case ID and returns the matching events, if any. If the case does not exist, this method will respond with a 200 status and an empty list.

Authorizations:
bearer
path Parameters
id
required
string

The case ID to use for searching all related events

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Case History

Returns all audit history associated with the given case ID.

Authorizations:
bearer
path Parameters
id
required
string

The case ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clients

Get API Clients

Returns all existing API clients.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create API Clients

Creates a new API client with the given Client object

Authorizations:
bearer
Request Body schema: application/json
required

The Client object to create. Only the 'name' and 'note' properties are used.

createTime
string

The date and time when this API client was created

id
string

The ID assigned to this API client

name
string

The client name

note
string

An optional note to associate with this API client

permissions
Array of strings

The list of permissions assigned to this client

searchUsername
string

An optional Elasticsearch user that this client will run as when accessing event data

secret
string

The generated client secret (only returned on new client creation and regeneration of the secret)

updateTime
string

The date and time when this API client was last modified

Responses

Request samples

Content type
application/json
{
  • "createTime": "2024-12-03T21:04:59.970640998Z",
  • "id": "socl_my_new_api_client",
  • "name": "My New API Client",
  • "note": "This client is used for automating case observable attachments",
  • "permissions": [
    ],
  • "searchUsername": "",
  • "secret": "ERa5jp9Z6WbLm1YC5FCM",
  • "updateTime": "0001-01-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "createTime": "2024-12-03T21:04:59.970640998Z",
  • "id": "socl_my_new_api_client",
  • "name": "My New API Client",
  • "note": "This client is used for automating case observable attachments",
  • "permissions": [
    ],
  • "searchUsername": "",
  • "secret": "ERa5jp9Z6WbLm1YC5FCM",
  • "updateTime": "0001-01-01T00:00:00Z"
}

Update API Clients

Updates an existing API client with the given Client object

Authorizations:
bearer
Request Body schema: application/json
required

The Client object to update. Only the 'name', and 'note' properties are used.

createTime
string

The date and time when this API client was created

id
string

The ID assigned to this API client

name
string

The client name

note
string

An optional note to associate with this API client

permissions
Array of strings

The list of permissions assigned to this client

searchUsername
string

An optional Elasticsearch user that this client will run as when accessing event data

secret
string

The generated client secret (only returned on new client creation and regeneration of the secret)

updateTime
string

The date and time when this API client was last modified

Responses

Request samples

Content type
application/json
{
  • "createTime": "2024-12-03T21:04:59.970640998Z",
  • "id": "socl_my_new_api_client",
  • "name": "My New API Client",
  • "note": "This client is used for automating case observable attachments",
  • "permissions": [
    ],
  • "searchUsername": "",
  • "secret": "ERa5jp9Z6WbLm1YC5FCM",
  • "updateTime": "0001-01-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "createTime": "2024-12-03T21:04:59.970640998Z",
  • "id": "socl_my_new_api_client",
  • "name": "My New API Client",
  • "note": "This client is used for automating case observable attachments",
  • "permissions": [
    ],
  • "searchUsername": "",
  • "secret": "ERa5jp9Z6WbLm1YC5FCM",
  • "updateTime": "0001-01-01T00:00:00Z"
}

Remove API Client

Removes an API client. Future API requests from this client will immediately be rejected.

Authorizations:
bearer
path Parameters
id
required
string
Example: socl_my_new_api_client

The API client ID

Responses

Remove Client Permission

Removes a permission from an existing API client. A new access token is not required. Future API calls will immediately be affected.

Authorizations:
bearer
path Parameters
id
required
string
Example: socl_my_new_api_client

The API client ID from which the permission will be removed

perm
required
string
Example: events/read

The permission to remove

Responses

Assign Client Permission

Assigns a permission to an existing API client. A new access token is not required. Future API calls will immediately be affected.

Authorizations:
bearer
path Parameters
id
required
string
Example: socl_my_new_api_client

The API client ID to which the permission will be assigned

perm
required
string
Example: events/read

The permission to assign

Responses

Regenerate Client Secret

Regenerates a new client secret for the given API client ID. Pre-existing access tokens that have not yet expired will remain valid through their expiration.

Authorizations:
bearer
path Parameters
id
required
string
Example: socl_my_new_api_client

The API client ID

Responses

Response samples

Content type
application/json
{
  • "createTime": "2024-12-03T21:04:59.970640998Z",
  • "id": "socl_my_new_api_client",
  • "name": "My New API Client",
  • "note": "This client is used for automating case observable attachments",
  • "permissions": [
    ],
  • "searchUsername": "",
  • "secret": "ERa5jp9Z6WbLm1YC5FCM",
  • "updateTime": "0001-01-01T00:00:00Z"
}

Get Permissions

Retrieves the set of available client permissions. Note: User roles are made up of assigned permissions. API clients do not use roles and instead are directly assigned individual permissions since each API client is expected to be configured for a specific task.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • "string"
]

Config

Get Configuration

Retrieves the full set of configuration settings and associated metadata. This response can be very large, particularly when the advanced parameter is set to 'true'.

Authorizations:
bearer
query Parameters
advanced
boolean
Example: advanced=true

If true, all configuration settings will be retrieved, otherwise only the commonly adjusted settings are retrieved

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Save Setting

Sets a configuration setting to a new value.

Authorizations:
bearer
Request Body schema: application/json
required

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

advanced
boolean

(metadata) Indicates whether this setting should only be shown when the 'Show advanced settings' option is enabled in the user interface.

default
string

(metadata) The default value for this configuration setting, if available

defaultAvailable
boolean

(metadata) Indicates whether there is a default value available for this configuration setting

description
string

(metadata) A description explaining the purpose of the configuration setting, if one is available.

duplicates
boolean

(metadata) Indicates whether this setting can be duplicated. Duplicating settings is a complex area that can lead to system or upgrade failures so this is used sparingly.

file
boolean

(metadata) Indicates whether the ID of this setting refers to a file on disk, in which case the changing the setting's value will replace the contents of the file on disk.

forcedType
string

(metadata) The type that the value will be converted to internally before applied to the component that uses it.

global
boolean

(metadata) Indicates whether this setting only applies to the grid as a whole

helpLink
string

(metadata) An HTML page, relative to the doc URL, that may assist the user in understanding the purpose of this setting.

id
string

The ID of the configuration setting. Each period represents a nested level.

jinjaEscaped
boolean

(metadata) Indicates whether the setting value allows Jinja2 escape characters. By default these are prohibited as a security precaution.

multiline
boolean

(metadata) Indicates whether this setting's user interface display should allow the user to enter values onto multiple lines

node
boolean

(metadata) Indicates whether this setting can be applied differently per each node in the grid

nodeId
string

The node ID to which this setting's value applies

optionSeparator
string

(metadata) For multi-select options, the separator string used to store them into a single string

options
Array of strings

(metadata) List of static values for a setting

readonly
boolean

(metadata) Indicates whether this setting is read-only. Read-only settings should not be modified.

readonlyUi
boolean

(metadata) Indicates whether this setting is read-only in the user interface only, but may be adjusted by the system itself.

regex
string

(metadata) An optional regular expression pattern that the value of this setting must match

regexFailureMessage
string

(metadata) The failure message to show on the user interface when the user enters a value that fails to match the regex.

required
boolean

(metadata) If true this UI element must be specified by the user before it can be saved

sensitive
boolean

(metadata) Indicates whether this setting's value should be masked in the user interface to prevent obtaining the existing value, while still permitting new values to be applied.

syntax
string

(metadata) An optional syntax designator for validating the given setting value.

title
string

(metadata) The configuration setting more human-friendly title, if one is available.

Array of objects (model.UiElement)

(metadata) List of UiElement objects describing how the UI should present the field for input

uiElementsDeleteMessage
string

(metadata) Confirmation message to show when user clicks the delete button on a ui element. If omitted, no message will be shown.

value
string

The value of this specific configuration setting. Note that a setting exist multiple times if different values are applied to specific nodes

Responses

Request samples

Content type
application/json
{
  • "advanced": false,
  • "default": "some default value",
  • "defaultAvailable": true,
  • "description": "Optional configuration parameters made available as defaults for all rules and alerters",
  • "duplicates": false,
  • "file": false,
  • "forcedType": "[]string",
  • "global": true,
  • "helpLink": "elastalert",
  • "id": "elastalert.alerter_parameters",
  • "jinjaEscaped": false,
  • "multiline": true,
  • "node": false,
  • "nodeId": "chi-so-001_standalone",
  • "optionSeparator": "string",
  • "options": [
    ],
  • "readonly": false,
  • "readonlyUi": false,
  • "regex": "^(true|false)$",
  • "regexFailureMessage": "Only true or false values are accepted",
  • "required": true,
  • "sensitive": true,
  • "syntax": "yaml",
  • "title": "Custom Configuration Parameters",
  • "uiElements": [
    ],
  • "uiElementsDeleteMessage": "string",
  • "value": "some custom value"
}

Delete Setting

Removes a custom setting value. This effectively reverts to the default setting value.

Authorizations:
bearer
path Parameters
id
required
string
Example: elastalert.alerter_parameters

The setting ID to remove

minion
string
Example: chi-so-001_standalone

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.

Responses

Sync Configuration

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.

Authorizations:
bearer

Responses

Sync Specific Module Configuration

Synchronizes a specific module's state to apply recent configuration changes to the grid. If async is true, this will queue up a Salt state.apply, which can take several minutes to complete, or longer if another highstate is already in progress. If async is false and another state is already in progress, this will return an error.

Authorizations:
bearer
path Parameters
module
required
string
Example: soc

The module name to sync

query Parameters
async
string
Example: async=true

If true, runs the synchronization in the background

Responses

Detections

Create Detection

Creates a new detection by providing the detection object as the request body, in JSON format. Detections marked as community detections cannot be created with this API. While the public ID is required for some engines, the internal ID will always be populated by the server.

Authorizations:
bearer
Request Body schema: application/json
required

The detection object to create

aiSummary
string

The detection summary generated by artificial intelligence

aiSummaryReviewed
boolean

Reserved for future use

author
string

The original author of this detection. This can be a mixture of email address, organization name, first name, or any freeform value

category
string

Used for categorizing this detection into a broader grouping such as firewalls or web servers

content
string

The underlying detection rule source content

createTime
string

The date and time that this object was created. This is a read-only field.

description
string

Brief explanation of this detection

engine
string (model.EngineName)

The engine that processes this detection

id
string

The ID assigned to this object by the server. This is a read-only field.

isCommunity
boolean

Indicates whether this detection originated from a community ruleset. Duplicated detections will show 'false'.

isEnabled
boolean

Indicates whether this detection is currently enabled in the Security Onion grid

isReporting
boolean

Indicates whether this detection is currently triggering alerts. Not yet fully implemented.

isSummaryStale
boolean

Indicates whether this detection's AI summary is current (true) or if the detection source has changed but the generated summary has not yet been updated to reflect the change"

kind
string

The kind of object. This is a read-only field.

language
string (model.SigLanguage)
Enum: "sigma" "suricata" "yara"

The language that this detection uses.

license
string

The license that applies to this detection

operation
string

The operation that was applied to the object. This is a read-only field.

Array of objects (model.Override)

A list of tuning overrides that apply to this detection.

product
string

Used by Sigma rules for filtering log outputs to a specific product, such as the Windows eventlog types

publicId
string

The public ID shared across all Security Onion grids

ruleset
string

The name of the ruleset from which this detection originated, or custom if the ruleset was created outside of a ruleset

service
string

Used by Sigma rules for filtering a subset of log ouputs to a specific server.

severity
string (model.Severity)
Enum: "unknown" "informational" "low" "medium" "high" "critical"

The severity classification of this detection

sourceCreated
string

The date and time when the underlying detection rule source was created. This is not when the detection was added to this grid.

sourceUpdated
string

The date and time when the underlying detection rule source was last updated. This is not when the detection was updated in this grid.

tags
Array of strings

An optional list of user-defined tags, useful for grouping similar detections together

title
string

Summarized title of the detection

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Response samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Update Detection

Updates an existing detection by providing the new detection object as the request body, in JSON format.

Authorizations:
bearer
Request Body schema: application/json
required

The detection object to create

aiSummary
string

The detection summary generated by artificial intelligence

aiSummaryReviewed
boolean

Reserved for future use

author
string

The original author of this detection. This can be a mixture of email address, organization name, first name, or any freeform value

category
string

Used for categorizing this detection into a broader grouping such as firewalls or web servers

content
string

The underlying detection rule source content

createTime
string

The date and time that this object was created. This is a read-only field.

description
string

Brief explanation of this detection

engine
string (model.EngineName)

The engine that processes this detection

id
string

The ID assigned to this object by the server. This is a read-only field.

isCommunity
boolean

Indicates whether this detection originated from a community ruleset. Duplicated detections will show 'false'.

isEnabled
boolean

Indicates whether this detection is currently enabled in the Security Onion grid

isReporting
boolean

Indicates whether this detection is currently triggering alerts. Not yet fully implemented.

isSummaryStale
boolean

Indicates whether this detection's AI summary is current (true) or if the detection source has changed but the generated summary has not yet been updated to reflect the change"

kind
string

The kind of object. This is a read-only field.

language
string (model.SigLanguage)
Enum: "sigma" "suricata" "yara"

The language that this detection uses.

license
string

The license that applies to this detection

operation
string

The operation that was applied to the object. This is a read-only field.

Array of objects (model.Override)

A list of tuning overrides that apply to this detection.

product
string

Used by Sigma rules for filtering log outputs to a specific product, such as the Windows eventlog types

publicId
string

The public ID shared across all Security Onion grids

ruleset
string

The name of the ruleset from which this detection originated, or custom if the ruleset was created outside of a ruleset

service
string

Used by Sigma rules for filtering a subset of log ouputs to a specific server.

severity
string (model.Severity)
Enum: "unknown" "informational" "low" "medium" "high" "critical"

The severity classification of this detection

sourceCreated
string

The date and time when the underlying detection rule source was created. This is not when the detection was added to this grid.

sourceUpdated
string

The date and time when the underlying detection rule source was last updated. This is not when the detection was updated in this grid.

tags
Array of strings

An optional list of user-defined tags, useful for grouping similar detections together

title
string

Summarized title of the detection

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Response samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Generate Public ID

Requests the server generate an unused public ID.

Authorizations:
bearer
path Parameters
engine
required
string
Enum: "elastalert" "suricata\""

The detection engine

Responses

Response samples

Content type
application/json
{
  • "publicId": "fb58abf3-0a6d-49af-b1a0-1eeabec07716"
}

Delete Detection

Deletes an existing detection.

Authorizations:
bearer
path Parameters
id
required
string
Example: zC73PJABrNRFAsnEYkqy

The internal detection ID

Responses

Get Detection

Retrieves a specific detection given an internal detection ID. This ID is unique only to this particular grid. 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"

Authorizations:
bearer
path Parameters
id
required
string
Example: zC73PJABrNRFAsnEYkqy

The detection ID to retrieve

Responses

Response samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Get Detection Comments

Retrieves the comments associated with the given detection ID.

Authorizations:
bearer
path Parameters
id
required
string
Example: zC73PJABrNRFAsnEYkqy

The internal detection ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Duplicate Detection

Copies the detection associated with the given ID into a new detection. A new ID will be assigned to the duplicated detection.

Authorizations:
bearer
path Parameters
id
required
string
Example: zC73PJABrNRFAsnEYkqy

The detection ID to duplicate

Responses

Response samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Get Detection History

Retrieves a specific detection's audit history given an internal detection ID.

Authorizations:
bearer
path Parameters
id
required
string
Example: zC73PJABrNRFAsnEYkqy

The detection ID to retrieve

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Override Note

Updates an existing override note.

Authorizations:
bearer
path Parameters
id
required
string
Example: zC73PJABrNRFAsnEYkqy

The internal detection ID

overrideIndex
required
number

The 0-based index of the override within the detection

Request Body schema: application/json
required

The note object that will replace the existing override note

note
string

The note content to replace on an existing override.

Responses

Request samples

Content type
application/json
{
  • "note": "corrected note"
}

Manage Detections in Bulk

Enables, disables, or deletes multiple detections asynchronously.

Authorizations:
bearer
path Parameters
newStatus
required
string
Enum: "enable" "disable" "delete"

The new status of the detection

Request Body schema: application/json
required

The bulk detection search criteria

ids
Array of strings

The list of detection IDs to bulk update when a specific query is not provided

query
string

The query string to use for matching detections, or leave empty if providing a list of internal detection IDs"

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "query": "severity: low AND ruleset: ETOPEN"
}

Response samples

Content type
application/json
{
  • "count": 120
}

Delete Detection Comment

Deletes the comment associated with the given comment ID.

Authorizations:
bearer
path Parameters
id
required
string
Example: MeEcnpMB4OVrR03M4und

The detection comment ID

Responses

Get Detection Comment

Retrieves the comment associated with the given comment ID.

Authorizations:
bearer
path Parameters
id
required
string
Example: MeEcnpMB4OVrR03M4und

The detection comment ID

Responses

Response samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "detectionId": "CwR86o8B-vS4HfrbMV5Y",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "This detection is known to trigger FPs on the first of the month"
}

Create Detection Comment

Creates a new detection comment for the detection associated with the provided detection ID.

Authorizations:
bearer
path Parameters
id
required
string
Example: zC73PJABrNRFAsnEYkqy

The internal detection ID

Request Body schema: application/json
required

A detection comment object with the new content; any provided detection ID will be ignored

createTime
string

The date and time that this object was created. This is a read-only field.

detectionId
string

The detection ID to which this comment was added

id
string

The ID assigned to this object by the server. This is a read-only field.

kind
string

The kind of object. This is a read-only field.

operation
string

The operation that was applied to the object. This is a read-only field.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

value
string

The comment text or markdown content

Responses

Request samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "detectionId": "CwR86o8B-vS4HfrbMV5Y",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "This detection is known to trigger FPs on the first of the month"
}

Response samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "detectionId": "CwR86o8B-vS4HfrbMV5Y",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "This detection is known to trigger FPs on the first of the month"
}

Update Detection Comment

Updates the comment associated with the given comment ID with the provided content.

Authorizations:
bearer
path Parameters
id
required
string
Example: MeEcnpMB4OVrR03M4und

The detection comment ID

Request Body schema: application/json
required

A detection object with the new content

createTime
string

The date and time that this object was created. This is a read-only field.

detectionId
string

The detection ID to which this comment was added

id
string

The ID assigned to this object by the server. This is a read-only field.

kind
string

The kind of object. This is a read-only field.

operation
string

The operation that was applied to the object. This is a read-only field.

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

value
string

The comment text or markdown content

Responses

Request samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "detectionId": "CwR86o8B-vS4HfrbMV5Y",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "operation": "create",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client",
  • "value": "This detection is known to trigger FPs on the first of the month"
}

Convert Rule Query

Converts the given Sigma Detection rule into an Elasticsearch query. NOTE: The API method only works with Sigma rules.

Authorizations:
bearer
Request Body schema: application/json
required

The Sigma detection object with the Content and optional Overrides populated

aiSummary
string

The detection summary generated by artificial intelligence

aiSummaryReviewed
boolean

Reserved for future use

author
string

The original author of this detection. This can be a mixture of email address, organization name, first name, or any freeform value

category
string

Used for categorizing this detection into a broader grouping such as firewalls or web servers

content
string

The underlying detection rule source content

createTime
string

The date and time that this object was created. This is a read-only field.

description
string

Brief explanation of this detection

engine
string (model.EngineName)

The engine that processes this detection

id
string

The ID assigned to this object by the server. This is a read-only field.

isCommunity
boolean

Indicates whether this detection originated from a community ruleset. Duplicated detections will show 'false'.

isEnabled
boolean

Indicates whether this detection is currently enabled in the Security Onion grid

isReporting
boolean

Indicates whether this detection is currently triggering alerts. Not yet fully implemented.

isSummaryStale
boolean

Indicates whether this detection's AI summary is current (true) or if the detection source has changed but the generated summary has not yet been updated to reflect the change"

kind
string

The kind of object. This is a read-only field.

language
string (model.SigLanguage)
Enum: "sigma" "suricata" "yara"

The language that this detection uses.

license
string

The license that applies to this detection

operation
string

The operation that was applied to the object. This is a read-only field.

Array of objects (model.Override)

A list of tuning overrides that apply to this detection.

product
string

Used by Sigma rules for filtering log outputs to a specific product, such as the Windows eventlog types

publicId
string

The public ID shared across all Security Onion grids

ruleset
string

The name of the ruleset from which this detection originated, or custom if the ruleset was created outside of a ruleset

service
string

Used by Sigma rules for filtering a subset of log ouputs to a specific server.

severity
string (model.Severity)
Enum: "unknown" "informational" "low" "medium" "high" "critical"

The severity classification of this detection

sourceCreated
string

The date and time when the underlying detection rule source was created. This is not when the detection was added to this grid.

sourceUpdated
string

The date and time when the underlying detection rule source was last updated. This is not when the detection was updated in this grid.

tags
Array of strings

An optional list of user-defined tags, useful for grouping similar detections together

title
string

Summarized title of the detection

updateTime
string

The date and time that this object was last modified. This is a read-only field.

userId
string

The user ID (or API client ID) that initiated this event. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Response samples

Content type
application/json
{
  • "query": "somefield: somevalue AND anotherfield: 123"
}

Get Detection By Public ID

Retrieves a specific detection given a public detection ID. This ID is assigned by the ruleset author.

Authorizations:
bearer
path Parameters
id
required
string
Example: 2038279

The detection public ID to retrieve

Responses

Response samples

Content type
application/json
{
  • "aiSummary": "This rule detects antivirus alerts reporting the presence of ransomware,...",
  • "aiSummaryReviewed": false,
  • "author": "Security Onion Solutions",
  • "category": "ps_script",
  • "content": "title: CobaltStrike Named Pipe\nid: ...\n logsource:\n ...\ncondition: selection\nfalsepositives:\n...",
  • "createTime": "2024-11-14T15:03:22Z",
  • "description": "Detects when a user fails to login to a grid node via SSH. Review associated logs for username and source IP.",
  • "engine": "string",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "isCommunity": true,
  • "isEnabled": true,
  • "isReporting": false,
  • "isSummaryStale": false,
  • "kind": "case",
  • "language": "sigma",
  • "license": "DRL",
  • "operation": "create",
  • "overrides": [
    ],
  • "product": "windows",
  • "publicId": "923421c7-9b1e-45d4-80cc-e21d060c8723",
  • "ruleset": "__custom__",
  • "service": "sshd",
  • "severity": "unknown",
  • "sourceCreated": "string",
  • "sourceUpdated": "string",
  • "tags": [
    ],
  • "title": "Security Onion - Grid Node Login Failure (SSH)",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Sync Detections

Initiates an asynchronous synchronization of the specified detection engine.

Authorizations:
bearer
path Parameters
engine
required
string
Enum: "all" "elastalert" "suricata" "strelka\""

The detection engine to sync

type
required
string
Enum: "full" "update"

The type of sync to perform

Responses

Query

Query Data

Given a search query, fetch all matching results, up to the maximum number requested, or the maximum that the backend data server will provide.

Query Structure

The query structure resembles the following:

(field_name1:required_value AND field_name2:>50) OR field_name3:"some string value" | groupby field_name1 field_name2 | sortby field_name1 field_name3 | ...

Everything the left of the | "pipe" character must be in Lucene syntax.

The operation keywords, such as AND, OR, NOT must always be capitalized.

For more information on the query syntax, refer to the Security Onion documentation and search for OQL.

Authorizations:
bearer
query Parameters
query
required
string
Example: query=tags:conn | groupby source.ip destination.ip network.protocol destination.port

User defined search query

range
required
string
Example: range=2024/12/03 03:09:31 PM - 2024/12/04 03:09:31 PM

Date range, in the specified timezone

zone
required
string
Example: zone=America/New_York

Timezone of the date range

format
required
string
Example: format=2006/01/02 3:04:05 PM

Date range date format. Use the example, exactly as shown, if not familiar with date formats

metricLimit
required
integer
Example: metricLimit=10

Maximum number of metrics to include in each aggregation

eventLimit
required
integer
Example: eventLimit=100

Maximum number of events to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Acknowledge Alerts

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.

Authorizations:
bearer
Request Body schema: application/json
required

Ack criteria

acknowledge
boolean

Whether to acknowledge or unacknowledge the events: true = acknowledge, false = unacknowledge

dateRange
string

The date range to use for searching for matching events

dateRangeFormat
string

The date range format. If unsure how to use this then use the example value exactly as shown.

escalate
boolean

Whether the events have also been escalated to a case: true = escalated, false = has not been escalated

object

Optional event filters to further narrow down matching events to acknowledge. These are field:value pairs.

searchFilter
string

The search filter to utilize when searching for matching events to acknowledge.

timezone
string

The timezone to use with the date range

Responses

Request samples

Content type
application/json
{
  • "acknowledge": true,
  • "dateRange": "2024/12/03 02:31:35 PM - 2024/12/04 02:31:35 PM",
  • "dateRangeFormat": "2006/01/02 3:04:05 PM",
  • "escalate": false,
  • "eventFilter": {
    },
  • "searchFilter": "tags:alert AND NOT event.acknowledged:true AND NOT event.escalated:true | groupby rule.name event.module* event.severity_label rule.uuid",
  • "timezone": "America/New_York"
}

Response samples

Content type
application/json
{
  • "completeTime": "2024-12-04T19:54:33.822293482Z",
  • "createTime": "2024-12-04T19:54:33.519514906Z",
  • "criteria": {
    },
  • "elapsedMs": 299,
  • "errors": [
    ],
  • "unchangedCount": 0,
  • "updatedCount": 1
}

Build Query

Requests the server provide a new query for the SOC client to show, given a particular change needed in the query.

Authorizations:
bearer
path Parameters
operation
required
string
Example: grouped

The type of operation for this query update. Supports: grouped, filtered, sorted

Request Body schema: application/x-www-form-urlencoded
required

The operation mode.

string

Responses

Get Active Queries

Returns a list of active event/data queries within the grid. Users will only see their queries unless they have privileged access to see active queries across all users. Requires a Security Onion Pro license.

Authorizations:
bearer
query Parameters
filter
boolean
Example: filter=true

If set to true the internal, child, uncancelable, and related queries will be filtered out of the results

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Cancel Active Query

Requests that the event storage system cancel a specific query identified by the provided input ID. Note that not all queries can be canceled. Requires a Security Onion Pro license.

Authorizations:
bearer
path Parameters
queryId
required
string
Example: jSliTqa12bOPhdW195TuuZ:321

The unique query ID to cancel

Responses

Response samples

Content type
application/json
{ }

DNS Reverse Lookup

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.

Authorizations:
bearer
Request Body schema: application/json
required

List of IP addresses to reverse lookup

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Grid

Get Grid Nodes

Retrieves the list of nodes that have recently checked-in with SOC. Nodes are grid members that have recently checked in with SOC. Under certain scenarios this may not include nodes that are accepted members of the grid but currently offline. Effectively, the results of this API call will match the view of the Grid screen in SOC (Not the Grid Members screen).

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Grid Status

Retrieves the status of the grid overall. Includes grid health status information related to nodes, alerts, detection engines, etc.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Grid Members

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. 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.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Manage Grid Member

Manages a grid member by performing the specified operation.

Available grid membership operations:

  • reject: Explicitly deny the node that is attempting to join the grid. The node will remain in the list of nodes that have been rejected unless a subsequent request uses the delete operation on the node.
  • add: Accepts the new grid member into this grid and allow it to participate in the grid synchronization process. For newly setup nodes, this will cause the remainder of the node setup to begin, which can take up to an hour to complete on some systems.
  • delete: Deletes the grid member. If the node was previously accepted into the grid it will be removed from the grid and removed from the grid member list. The SOC grid list will continue to show the node until the SOC process (or the manager node itself) is restarted.
  • test: Ingests preselected test data into the node. This should only be executed on sensor nodes, such as standalone nodes, forward nodes, etc.
  • restart: Restarts the operating system on the given node. Note that restarting the manager node will take SOC offline for several minutes. Restarting all grid nodes concurrently can result in missed network data.
Authorizations:
bearer
path Parameters
id
required
string
Example: so_standalone

The grid member ID to be managed

operation
required
string
Example: reject

The operation to perform: add, reject, delete, test, restart

Responses

Import Data

Imports the data from the given file. This is commonly used for importing PCAP and EVTX data directly into the node. The max file size defaults to 25MB unless customized in the server configuration. Example directory listing of a PCAP file being uploaded for import:

-rw-r--r--  1 jertel jertel    1355 Jan 27 18:15  hdcp_authentication_sample.pcap

Example POST request, with some of the noteworthy headers shown:

POST /connect/gridmembers/manager_standalone/import

...
content-length: 1584
content-type: multipart/form-data; boundary=----WebKitFormBoundaryaKfZhnMSKrgA9HJh
...

------WebKitFormBoundaryaKfZhnMSKrgA9HJh
Content-Disposition: form-data; name="attachment"; filename="hdcp_authentication_sample.pcap"
Content-Type: application/vnd.tcpdump.pcap

<< raw bytes >>

------WebKitFormBoundaryaKfZhnMSKrgA9HJh--
Authorizations:
bearer
path Parameters
id
required
string
Example: manager_standalone

The full node ID (name_role) into which this data will be imported

Request Body schema: multipart/form-data
required

The raw file data to import. This request must use multipart/form-data content type and the body must include one form part containing form-data content named 'attachment' with a filename attribute, a Content-Type header representing the file stream MIME type, and then the associated raw data stream.

file

Responses

Get Server Information

Requests the Security Onion grid general details.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "customReports": {
    },
  • "elasticVersion": "8.14.3",
  • "forceUserOtp": true,
  • "license": "Elastic License 2.0 (ELv2)",
  • "licenseKey": {
    },
  • "licenseStatus": "active",
  • "mgmtMac": "11:22:33:AA:BB:CC",
  • "parameters": {
    },
  • "srvToken": "string",
  • "subgrids": [
    ],
  • "timezones": [
    ],
  • "userId": "socl_my_so_api_client",
  • "version": "2.4.110"
}

Node Check-in

Used by Security Onion agent nodes to check-in with their current metrics and request any pending jobs assigned to it. It is not recommended to make calls to this API endpoint, as this is intended to be used exclusively by official Security Onion nodes only.

Authorizations:
bearer
Request Body schema: application/json
required

The node object with recent metrics

address
string

The IP address of this node

captureLossPct
number

The current percentage capture loss experienced by the network, if applicable to this node

connectionStatus
string

The connectivity status between this node and the manager node: unknown, ok, fault

consumptionEps
integer

The events per second (EPS) consumed by this node

cpuUsedPct
number

The current CPU usage of the node, across all cores

description
string

The node's optional description

diskTotalNsmGB
number

Total size, in gigabytes, of the NSM data disk/partition

diskTotalRootGB
number

Total size, in gigabytes, of the root operating system disk/partition

diskUsedElasticGB
number

The disk space used, in gigabytes, on the backend data store system (Elasticsearch)

diskUsedInfluxDbGB
number

The disk space used, in gigabytes, on the metrics data store system (InfluxDB)

diskUsedNsmPct
number

Percentage usage of the NSM data disk/partition

diskUsedRootPct
number

Percentage usage of the root system disk/partition

epochTime
string

The node's data epoch; this is the date and time of the oldest known PCAP data available to the node

eventstoreStatus
string

The event storage status; this refers to the backend status, such as Elasticsearch: unknown, ok, fault

failedEvents
integer

The count of failed events (currently not in use)"

fpsEnabled
integer

Indicates whether federal information processing standards are enabled on this node

gmdEnabled
integer

Indicates whether guaranteed message delivery is enabled on this node

gridId
string

Grid ID, used for subgrids

highstateAgeSeconds
integer

How long ago, in seconds, the last highstate completed on this node

id
string

The node ID

imageBack
string

The Security Onion appliance back image, if available

imageFront
string

The Security Onion appliance front image, if available

ioWaitPct
number

The IO wait percentage for this node

lksEnabled
integer

Indicates whether disk encryption is enabled on this node

load5m
number

The node's 5-minute load metric

load15m
number

The node's 15-minute load metric

load1m
number

The node's 1-minute load metric

memoryTotalGB
number

Total size, in gigabytes, of the system memory, or RAM

memoryUsedPct
number

Percentage usage of the system memory, or RAM

metricsEnabled
boolean

Indicates whether the metric subsytem is available

mgmtMac
string

The MAC address assigned to this node's management NIC

model
string

The Seurity Onion appliance model, or N/A if this is not an official Security Onion appliance

nonCriticalNode
boolean

Indicates whether this node is a non-critical node of the overall grid. An examples of a non-critical nodes is a desktop node

onlineTime
string

The date and time when this node first came online; best estimate based on the node's apparent file system age

osNeedsRestart
integer

Indicates whether the node needs to be restarted to apply kernel updates: 0 = no restart needed, 1 = needs restarted

osUptimeSeconds
integer

The number of seconds that the operating system has been "up" since its last reboot

pcapDays
number

The number of days of PCAP storage available to this node

processJson
string

The status of each individual process on the node, in JSON format

processStatus
string

The overall status of the node's Security Onion processes: unknown, ok, fault

productionEps
integer

The events per second (EPS) produced by this node (not currently populated)

raidStatus
string

The raid status, if applicable: unknown, ok, fault

redisQueueSize
integer

The backlog of events waiting to be processed

role
string

The node's assigned role; assigned during node setup

status
string

The current state of the node: unknown, ok, fault, pending, restart

suriLossPct
number

The current percentage packet loss experienced by Suricata, if applicable to this node

suriRulesFailed
integer

The number of Suricata rules that failed to load, if applicable to this node

suriRulesLoaded
integer

The number of Suricata rules currently loaded, if applicable to this node

suriRulesReloadTime
string

The timestamp of the last Suricata rule reload, if applicable to this node

suriRulesStatus
string

The status of Suricata rule loading: ok, unknown

swapTotalGB
number

Total size, in gigabytes, of the system swap memory

swapUsedPct
number

Percentage usage of the system swap memory

trafficManInMbs
number

The inbound traffic rate, in megabytes per second, to this node's management network interface

trafficManOutMbs
number

The outbound traffic rate, in megabytes per second, from this node's management network interface

trafficMonInDropsMbs
number

The inbound traffic packet drop rate, in megabytes per second, to this node's monitor network interface

trafficMonInMbs
number

The inbound traffic rate, in megabytes per second, to this node's monitor network interface

updateTime
string

The date and time when this node was most recently updated"

uptimeSeconds
integer

The number of seconds since this node first came online and joined the grid

version
string

The version of Security Onion installed on this node

zeekLossPct
number

The current percentage packet loss experienced by Zeek, if applicable to this node

Responses

Request samples

Content type
application/json
{
  • "address": "4.3.2.1",
  • "captureLossPct": 24.0605,
  • "connectionStatus": "fault",
  • "consumptionEps": 110,
  • "cpuUsedPct": 5.0035165275079265,
  • "description": "East coast sensor",
  • "diskTotalNsmGB": 772.7962808320001,
  • "diskTotalRootGB": 314.41920000000005,
  • "diskUsedElasticGB": 386.948,
  • "diskUsedInfluxDbGB": 1.922272,
  • "diskUsedNsmPct": 84.28509193998036,
  • "diskUsedRootPct": 20.944604461814038,
  • "epochTime": "2024-12-01T03:24:01Z",
  • "eventstoreStatus": "ok",
  • "failedEvents": 0,
  • "fpsEnabled": 0,
  • "gmdEnabled": 0,
  • "gridId": "so1",
  • "highstateAgeSeconds": 220,
  • "id": "sensor-001",
  • "imageBack": "5000v2_back_thumb.jpg",
  • "imageFront": "5000v2_front_thumb.jpg",
  • "ioWaitPct": 0.21099,
  • "lksEnabled": 1,
  • "load5m": 0.96,
  • "load15m": 1.09,
  • "load1m": 0.43,
  • "memoryTotalGB": 33.176731648,
  • "memoryUsedPct": 60.66793353109983,
  • "metricsEnabled": true,
  • "mgmtMac": "AA:BB:CC:11:22:33",
  • "model": "SOS5000-DE02",
  • "nonCriticalNode": false,
  • "onlineTime": "2024-01-26T21:17:25Z",
  • "osNeedsRestart": 1,
  • "osUptimeSeconds": 1384801,
  • "pcapDays": 1.8762268518518517,
  • "processJson": "{\"status_code\":0, \"containers\":[{\"Name\":\"so-dockerregistry\", \"Status\":\"running\",\"Details\":\"Up 2 weeks\"}, ... ]}",
  • "processStatus": "ok",
  • "productionEps": 0,
  • "raidStatus": "unknown",
  • "redisQueueSize": 0,
  • "role": "so-standalone",
  • "status": "ok",
  • "suriLossPct": 1.1345,
  • "suriRulesFailed": 0,
  • "suriRulesLoaded": 45879,
  • "suriRulesReloadTime": "2025-12-04T01:04:07.994734+0000",
  • "suriRulesStatus": "ok",
  • "swapTotalGB": 8.589930496000001,
  • "swapUsedPct": 63.27341235800379,
  • "trafficManInMbs": 0.031592,
  • "trafficManOutMbs": 0.030966666666666667,
  • "trafficMonInDropsMbs": 0,
  • "trafficMonInMbs": 1.6864359999999998,
  • "updateTime": "2024-12-03T15:42:21.723166638Z",
  • "uptimeSeconds": 26936696,
  • "version": "2.4.110",
  • "zeekLossPct": 0
}

Response samples

Content type
application/json
[
  • {
    }
]

Jobs

Create Job

Create a new job.

Authorizations:
bearer
Request Body schema: application/json
required

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.

completeTime
string

The date and time when the job was completed

createTime
string

The date and time when the job was created

failCount
integer

The number of times the job was processed but failed

failTime
string

The date and time when the job last failed and was marked incomplete

failure
string

The failure reason

fileExtension
string

The file extension for any attached job result/output data

object (model.Filter)

Optional filter for the job, typically used for packet filtering

id
integer

The unique Job ID

kind
string

The kind of job that this object represents; blank values represent pcap jobs

nodeId
string

The unique node ID that is responsible for completing this job

owner
string

Owner field [not actively used by the API]

Array of objects (model.JobResult)

The array of job results; will be empty for jobs that only attach output streams

sensorId
string

Legacy sensor ID field

size
integer

The size of the job stream output, if a stream output was attached

status
integer

The current state of the job. 0 = pending, 1 = complete, 2 = incomplete, 3 = deleted

userId
string

The unique user ID that created this job

Responses

Request samples

Content type
application/json
{
  • "completeTime": "2024-10-07T12:15:09.12424556Z",
  • "createTime": "2024-10-07T06:45:49.52456415Z",
  • "failCount": 0,
  • "failTime": "0001-01-01T00:00:00Z",
  • "failure": "",
  • "fileExtension": "bin",
  • "filter": {
    },
  • "id": 1004,
  • "kind": "analyze",
  • "nodeId": "sensor-001",
  • "owner": "",
  • "results": [
    ],
  • "sensorId": "string",
  • "size": 3781,
  • "status": 1,
  • "userId": "39314a6b-0b79-4210-1233-4e3fbcd7bfec"
}

Response samples

Content type
application/json
{
  • "completeTime": "2024-10-07T12:15:09.12424556Z",
  • "createTime": "2024-10-07T06:45:49.52456415Z",
  • "failCount": 0,
  • "failTime": "0001-01-01T00:00:00Z",
  • "failure": "",
  • "fileExtension": "bin",
  • "filter": {
    },
  • "id": 1004,
  • "kind": "analyze",
  • "nodeId": "sensor-001",
  • "owner": "",
  • "results": [
    ],
  • "sensorId": "string",
  • "size": 3781,
  • "status": 1,
  • "userId": "39314a6b-0b79-4210-1233-4e3fbcd7bfec"
}

Update Job

Update an existing job with the provided job details.

Authorizations:
bearer
Request Body schema: application/json
required

The job details. Any provided user ID or node ID will be ignored as those fields are read-only after initial job creation.

completeTime
string

The date and time when the job was completed

createTime
string

The date and time when the job was created

failCount
integer

The number of times the job was processed but failed

failTime
string

The date and time when the job last failed and was marked incomplete

failure
string

The failure reason

fileExtension
string

The file extension for any attached job result/output data

object (model.Filter)

Optional filter for the job, typically used for packet filtering

id
integer

The unique Job ID

kind
string

The kind of job that this object represents; blank values represent pcap jobs

nodeId
string

The unique node ID that is responsible for completing this job

owner
string

Owner field [not actively used by the API]

Array of objects (model.JobResult)

The array of job results; will be empty for jobs that only attach output streams

sensorId
string

Legacy sensor ID field

size
integer

The size of the job stream output, if a stream output was attached

status
integer

The current state of the job. 0 = pending, 1 = complete, 2 = incomplete, 3 = deleted

userId
string

The unique user ID that created this job

Responses

Request samples

Content type
application/json
{
  • "completeTime": "2024-10-07T12:15:09.12424556Z",
  • "createTime": "2024-10-07T06:45:49.52456415Z",
  • "failCount": 0,
  • "failTime": "0001-01-01T00:00:00Z",
  • "failure": "",
  • "fileExtension": "bin",
  • "filter": {
    },
  • "id": 1004,
  • "kind": "analyze",
  • "nodeId": "sensor-001",
  • "owner": "",
  • "results": [
    ],
  • "sensorId": "string",
  • "size": 3781,
  • "status": 1,
  • "userId": "39314a6b-0b79-4210-1233-4e3fbcd7bfec"
}

Response samples

Content type
application/json
{
  • "completeTime": "2024-10-07T12:15:09.12424556Z",
  • "createTime": "2024-10-07T06:45:49.52456415Z",
  • "failCount": 0,
  • "failTime": "0001-01-01T00:00:00Z",
  • "failure": "",
  • "fileExtension": "bin",
  • "filter": {
    },
  • "id": 1004,
  • "kind": "analyze",
  • "nodeId": "sensor-001",
  • "owner": "",
  • "results": [
    ],
  • "sensorId": "string",
  • "size": 3781,
  • "status": 1,
  • "userId": "39314a6b-0b79-4210-1233-4e3fbcd7bfec"
}

Delete Job

Deletes an existing job and its related output results.

Authorizations:
bearer
path Parameters
jobId
required
integer
Example: 1004

The job ID

Responses

Get Job

Retrieves a specific job that matches the given job ID.

Authorizations:
bearer
path Parameters
jobId
required
integer
Example: 1004

The job ID

Responses

Response samples

Content type
application/json
{
  • "completeTime": "2024-10-07T12:15:09.12424556Z",
  • "createTime": "2024-10-07T06:45:49.52456415Z",
  • "failCount": 0,
  • "failTime": "0001-01-01T00:00:00Z",
  • "failure": "",
  • "fileExtension": "bin",
  • "filter": {
    },
  • "id": 1004,
  • "kind": "analyze",
  • "nodeId": "sensor-001",
  • "owner": "",
  • "results": [
    ],
  • "sensorId": "string",
  • "size": 3781,
  • "status": 1,
  • "userId": "39314a6b-0b79-4210-1233-4e3fbcd7bfec"
}

Create PCAP Job from Event

Given a TCP or UDP network connection log event, create a PCAP lookup job that would best locate the PCAP from that event.

Authorizations:
bearer
query Parameters
time
required
string
Example: time=2024-01-29T12:31:59.220Z

Time timestamp of the event

esid
string
Example: esid=P5mgnpEB0JpjNDZz1bIN

The event document ID. If this is not specified then the ncid param is required.

ncid
string
Example: ncid=1:URggUwcolUh/BgIWApL6rUUZUK4=

The network.community_id value for the event. Ignored if the esid param is provided.

Responses

Get Jobs

Retrieves the list of jobs that match the given parameters.

Authorizations:
bearer
query Parameters
kind
required
string
Example: kind=analyzer

The job kind, such as 'analyze'. Specify an empty value for PCAP jobs

parameters[artifact][id]
string
Example: parameters[artifact][id]=P5mgnpEB0JpjNDZz1bIN

Optional case ID to locate matching analyze jobs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get PCAP Packets

Retrieves the packets collected and attached to the job represented by the given job ID. This request assumes the job is a PCAP job.

Authorizations:
bearer
path Parameters
jobId
required
integer
Example: 1004

The job ID

query Parameters
unwrap
boolean
Example: unwrap=true

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.

offset
integer
Example: offset=100

The starting offset of the packet to retrieve; used for paging large packet results. Defaults to 0.

count
integer
Example: count=100

The maximum number of packets to retrieve; used for paging large packet results. Defaults to 5000, or an optional server-side configuration value/

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download Job Output

Returns the full job output stream for the given job ID. An example of a job stream is a packet capture (PCAP) file.

Authorizations:
bearer
path Parameters
jobId
required
integer
Example: 1004

The job ID

query Parameters
ext
string
Example: ext=pcap

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.

unwrap
boolean
Example: unwrap=true

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.

Responses

Upload Job Output

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.

Authorizations:
bearer
path Parameters
jobId
required
integer
Example: 1004

The job ID

Request Body schema:
required

The job output stream byte content

string <binary>

Responses

Response samples

Content type
application/json
"string"

Playbooks

Get Playbook by ID

Retrieves playbooks given an internal playbook ID.

Authorizations:
bearer
path Parameters
id
required
string
Example: 6F64990A-ACDA-40B6-AB71-134C073013B5

The playbook ID to retrieve

Responses

Response samples

Content type
application/json
{
  • "contributors": [
    ],
  • "createTime": "2024-11-14T15:03:22Z",
  • "created": "2023-10-01T12:00:00Z",
  • "description": "This is a sample playbook",
  • "detection_category": "process_creation",
  • "detection_id": "ac5856cd-7e4c-4a61-8b15-6fc9148ff7f2",
  • "detection_type": "nids",
  • "id": "PdFc-JIBLkNJ8-bDfz47",
  • "kind": "case",
  • "modified": "2023-10-01T12:00:00Z",
  • "name": "Sample Playbook",
  • "operation": "create",
  • "questions": [
    ],
  • "updateTime": "2024-11-14T15:33:02Z",
  • "userId": "socl_my_new_client"
}

Get Playbook For Detection

Retrieves playbooks that apply to the indicated detection.

Authorizations:
bearer
path Parameters
id
required
string
Example: 6F64990A-ACDA-40B6-AB71-134C073013B5

The public Id for the detection

query Parameters
raw
boolean

If true, return the playbook in raw YAML format

Responses

Response samples

Content type
[
  • {
    }
]

Get Event-Specific Playbook

Fetches the playbook for a specific event.

Authorizations:
bearer
path Parameters
id
required
string

The SOC Id for the alert

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Users

Get Roles

Retrieves the set of available user roles.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Users

Returns all SOC users.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create User

Creates a new SOC user.

Authorizations:
bearer
Request Body schema: application/json
required

User object to be created. The provided email address, firstname, lastname, note, roles, and password will be used. All other fields are ignored.

createTime
string

The date and time that this user was created. This is a read-only field.

email
string

The email address for this user.

firstName
string

The user's first name.

id
string

The ID assigned to this user by the server. This is a read-only field.

lastName
string

The user's last name, or family name.

note
string

A custom note about this user.

oidcStatus
string

The OIDC status for this user. This is a read-only field.

password
string

The password must have a length of at least 8 characters and no more than 72 characters and cannot contain the following: ' " $ \

passwordChanged
boolean

A rough determination of whether this user has changed their password since the user was created. Technically this can only detect if the user has been updated after creation and is therefore an imperfect estimator for whether the password has been changed. This is a read-only field.

roles
Array of strings

A list of assigned roles to this user.

searchUsername
string

An alternate username (typically an email address) to use when performing backend (Ex: Elasticsearch) data searches and updates.

status
string

The login status of this user.

totpStatus
string

The TOTP MFA status for this user. This is a read-only field.

updateTime
string

The date and time that this user was last modified. This is a read-only field.

webauthnStatus
string

The WebAuthn (Passwordless) status for this user. This status field is not ready for production use. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "email": "someone@somewhere.invalid",
  • "firstName": "John",
  • "id": "3610b2cf-a2e7-4037-9c51-227f0c2e79ff",
  • "lastName": "Smith",
  • "note": "Employment terminated on Nov 10, 2023",
  • "oidcStatus": "enabled",
  • "password": "string",
  • "passwordChanged": true,
  • "roles": [
    ],
  • "searchUsername": "someoneelse@somewhere.invalid",
  • "status": "locked",
  • "totpStatus": "enabled",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "webauthnStatus": "enabled"
}

Response samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "email": "someone@somewhere.invalid",
  • "firstName": "John",
  • "id": "3610b2cf-a2e7-4037-9c51-227f0c2e79ff",
  • "lastName": "Smith",
  • "note": "Employment terminated on Nov 10, 2023",
  • "oidcStatus": "enabled",
  • "password": "string",
  • "passwordChanged": true,
  • "roles": [
    ],
  • "searchUsername": "someoneelse@somewhere.invalid",
  • "status": "locked",
  • "totpStatus": "enabled",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "webauthnStatus": "enabled"
}

Delete User

Deletes the provided user ID.

Authorizations:
bearer
path Parameters
id
required
string

The user ID

Responses

Update User

Update a user with the provided user object data.

Authorizations:
bearer
path Parameters
id
required
string

The user ID

Request Body schema: application/json
required

User object containing new updates. The provided email address, firstname, lastname, and note will be updated. All other fields are ignored.

createTime
string

The date and time that this user was created. This is a read-only field.

email
string

The email address for this user.

firstName
string

The user's first name.

id
string

The ID assigned to this user by the server. This is a read-only field.

lastName
string

The user's last name, or family name.

note
string

A custom note about this user.

oidcStatus
string

The OIDC status for this user. This is a read-only field.

password
string

The password must have a length of at least 8 characters and no more than 72 characters and cannot contain the following: ' " $ \

passwordChanged
boolean

A rough determination of whether this user has changed their password since the user was created. Technically this can only detect if the user has been updated after creation and is therefore an imperfect estimator for whether the password has been changed. This is a read-only field.

roles
Array of strings

A list of assigned roles to this user.

searchUsername
string

An alternate username (typically an email address) to use when performing backend (Ex: Elasticsearch) data searches and updates.

status
string

The login status of this user.

totpStatus
string

The TOTP MFA status for this user. This is a read-only field.

updateTime
string

The date and time that this user was last modified. This is a read-only field.

webauthnStatus
string

The WebAuthn (Passwordless) status for this user. This status field is not ready for production use. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "email": "someone@somewhere.invalid",
  • "firstName": "John",
  • "id": "3610b2cf-a2e7-4037-9c51-227f0c2e79ff",
  • "lastName": "Smith",
  • "note": "Employment terminated on Nov 10, 2023",
  • "oidcStatus": "enabled",
  • "password": "string",
  • "passwordChanged": true,
  • "roles": [
    ],
  • "searchUsername": "someoneelse@somewhere.invalid",
  • "status": "locked",
  • "totpStatus": "enabled",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "webauthnStatus": "enabled"
}

Response samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "email": "someone@somewhere.invalid",
  • "firstName": "John",
  • "id": "3610b2cf-a2e7-4037-9c51-227f0c2e79ff",
  • "lastName": "Smith",
  • "note": "Employment terminated on Nov 10, 2023",
  • "oidcStatus": "enabled",
  • "password": "string",
  • "passwordChanged": true,
  • "roles": [
    ],
  • "searchUsername": "someoneelse@somewhere.invalid",
  • "status": "locked",
  • "totpStatus": "enabled",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "webauthnStatus": "enabled"
}

Toggle User Enabled

Update a user's status to enabled or disabled

Authorizations:
bearer
path Parameters
id
required
string

The user ID

toggle
required
string

Desired toggle action. Set to 'enable' or 'disable'.

Responses

Change Password

Update a user's password with the provided value.

Authorizations:
bearer
path Parameters
id
required
string

The user ID

Request Body schema: application/json
required

User object containing the new password. All other fields are ignored.

createTime
string

The date and time that this user was created. This is a read-only field.

email
string

The email address for this user.

firstName
string

The user's first name.

id
string

The ID assigned to this user by the server. This is a read-only field.

lastName
string

The user's last name, or family name.

note
string

A custom note about this user.

oidcStatus
string

The OIDC status for this user. This is a read-only field.

password
string

The password must have a length of at least 8 characters and no more than 72 characters and cannot contain the following: ' " $ \

passwordChanged
boolean

A rough determination of whether this user has changed their password since the user was created. Technically this can only detect if the user has been updated after creation and is therefore an imperfect estimator for whether the password has been changed. This is a read-only field.

roles
Array of strings

A list of assigned roles to this user.

searchUsername
string

An alternate username (typically an email address) to use when performing backend (Ex: Elasticsearch) data searches and updates.

status
string

The login status of this user.

totpStatus
string

The TOTP MFA status for this user. This is a read-only field.

updateTime
string

The date and time that this user was last modified. This is a read-only field.

webauthnStatus
string

The WebAuthn (Passwordless) status for this user. This status field is not ready for production use. This is a read-only field.

Responses

Request samples

Content type
application/json
{
  • "createTime": "2024-11-14T15:03:22Z",
  • "email": "someone@somewhere.invalid",
  • "firstName": "John",
  • "id": "3610b2cf-a2e7-4037-9c51-227f0c2e79ff",
  • "lastName": "Smith",
  • "note": "Employment terminated on Nov 10, 2023",
  • "oidcStatus": "enabled",
  • "password": "string",
  • "passwordChanged": true,
  • "roles": [
    ],
  • "searchUsername": "someoneelse@somewhere.invalid",
  • "status": "locked",
  • "totpStatus": "enabled",
  • "updateTime": "2024-11-14T15:33:02Z",
  • "webauthnStatus": "enabled"
}

Deny User Role

Denies an existing user a role. The user will no longer have permissions that this role provides.

Authorizations:
bearer
path Parameters
id
required
string

The user ID

role
required
string

The role name

Responses

Grant User Role

Grants an existing user a role. The user will then have permissions that this role provides.

Authorizations:
bearer
path Parameters
id
required
string

The user ID

role
required
string

The role name

Responses

Synchronize Users

Synchronizes all SOC users across the grid. This is an asynchronous request. The background operation can take several minutes to complete.

Authorizations:
bearer

Responses

Authentication

Obtain Access Token

Exchanges a client ID and client secret for a temporary access token needed for calling Security Onion Connect API methods. The client ID and client secret are provided within the SOC Administration -> API Clients screen, when creating a new API client or when regenerating an API client's secret. The client secrets are only temporarily visible during those two specific times. The returned access token will expire within 1-2 hours, by default. Ensure the custom integration application is capable of exchanging for a new access token prior to the expiration.

Authorizations:
basic
Request Body schema: application/x-www-form-urlencoded
required

The body of this POST request must contain the required fields as shown below.

grant_type
required
string

Must be set to client_credentials

Responses

Response samples

Content type
application/json
{
  • "access_token": "ory_at_arkgYuJXYp5zwU8Xyh8-URW6QIUbaZVf4JwDPoNZh0g.YcF4W5i2qoQ2RTWZvLYLNIeUjGaUhYuewz9Gua0y7YA",
  • "expires_in": 3599,
  • "scope": "",
  • "token_type": "bearer"
}