REST API

Overview

This chapter provides documentation for the Energy Logserver SIEM APIs, covering REST endpoints, authentication methods, and data operations.

Energy Logserver SIEM exposes multiple API layers for different operational needs:

ELS REST API: Core data operations and cluster management.
ELS Console API: Dashboard management, saved objects, and visualizations.
ELS-specific APIs: License management, SIEM operations, and agent communication.

Connecting to API

To connect to APIs, you can use basic authorization or an authorization token.

To generate the authorization token, run the following command:

curl -XPUT http://localhost:9200/_logserver/login -H 'Content-type: application/json' -d '
{
  "username": "$USER",
  "password": "$PASSWORD"
}'

The result of the command will return the value of the token, and you can use it in the API by passing it as a “token” header, for example:

curl -H 'token: 192783916598v51j928419b898v1m79821c2' -X GET "http://localhost:9200/_cluster/health"

Dashboards API

The Dashboards import/export APIs allow users to import dashboards along with all corresponding saved objects, such as visualizations, saved searches, and index patterns.

Dashboards Import API

Request:

POST /api/opensearch-dashboards/dashboards/import

Query Parameters:

force (optional, boolean) - Overwrite any existing objects on ID conflict.
exclude (optional, array) - Saved object types that should not be imported.

Example:

curl -XPOST -ulogserver: -H "osd-xsrf: true" -H "Content-Type: application/json" "https://127.0.0.1:5601/api/opensearch-dashboards/dashboards/import?force=true" -d@"${DASHBOARD-FILE}"

Dashboards Export API

Request:

GET /api/opensearch-dashboards/dashboards/export

Query Parameters:

dashboard (required, array|string) - The ID(s) of the dashboard(s) to export.

Example:

curl -XGET -ulogserver: -H "osd-xsrf: true" -H "Content-Type: application/json" "https://127.0.0.1:5601/api/opensearch-dashboards/dashboards/export?dashboard=${DASHBOARD-ID}" > ${DASHBOARD-FILE}

Energy Logserver API

The Energy Logserver API is a typical REST API, and data is received in JSON format over the HTTP protocol. By default, the tcp/9200 port is used to communicate with the Energy Logserver API. For the purposes of examples, communication with the Energy Logserver API will be carried out using the curl application.

Program syntax:

curl -XGET -u login:password '127.0.0.1:9200'

Available methods:

PUT - sends data to the server.
POST - sends a request to the server for a change.
DELETE - deletes the index/document.
GET - gets information about the index/document.
HEAD - is used to check if the index/document exists.

Available APIs by roles:

Index API - manages indexes.
Document API - manages documents.
Cluster API - manages the cluster.
Search API - is used to search for data.

Energy Logserver Index API

The indices APIs are used to manage individual indices, index settings, aliases, mappings, and index templates.

Adding Index

Adding Index - automatic method:

curl -XPUT -u login:password '127.0.0.1:9200/syslog-2024.04.14/_doc/1?pretty=true' -d'{
    "host" : "firewall-01",
    "@timestamp" : "2024-04-14T10:00:00",
    "message" : "Connection accepted from 10.0.0.5"
    }'

You should see the output:

{
  "_index" : "syslog-2024.04.14",
  "_id" : "1",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

The parameter action.auto_create_index must be set to true.

Adding Index – manual method:

Setting the number of shards and replicas:

curl -XPUT -u login:password '127.0.0.1:9200/winlogbeat-2024.04.14?pretty=true' -d'{
	"settings" : {
	"number_of_shards" : 1,
    "number_of_replicas" : 1
    }
 }'

You should see the output:

{
  "acknowledged" : true
}

Command for manual index generation:

curl -XPUT -u login:password '127.0.0.1:9200/winlogbeat-2024.04.14/_doc/1?pretty=true' -d'{
    "host" : "dc-01",
    "@timestamp" : "2024-04-14T10:00:00",
    "message" : "User logon event"
}'

You should see the output:

{
  "_index" : "winlogbeat-2024.04.14",
  "_id" : "1",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

Delete Index

Delete Index - to delete an index you need to use the following command:

curl -XDELETE -u login:password '127.0.0.1:9200/syslog-2024.04.14?pretty=true'

The delete index API can also be applied to more than one index, by either using a comma-separated list, or on all indices by using _all or * as index:

curl -XDELETE -u login:password '127.0.0.1:9200/syslog-2024*?pretty=true'

To allow deletion of indices via wildcards, set the action.destructive_requires_name setting in the configuration to false.

API Useful Commands

Get information about replicas and shards:

curl -XGET -u login:password '127.0.0.1:9200/syslog-2024.04.14/_settings?pretty=true'

curl -XGET -u login:password '127.0.0.1:9200/winlogbeat-2024.04.14/_settings?pretty=true'

Get information about mapping and alias in the index:

curl -XGET -u login:password '127.0.0.1:9200/syslog-2024.04.14/_mappings?pretty=true'

curl -XGET -u login:password '127.0.0.1:9200/syslog-2024.04.14/_aliases?pretty=true'

Get all information about the index:

curl -XGET -u login:password '127.0.0.1:9200/syslog-2024.04.14?pretty=true'

Check if the index exists:

curl -XHEAD -u login:password '127.0.0.1:9200/syslog-2024.04.14?pretty=true'

Close the index:

curl -XPOST -u login:password '127.0.0.1:9200/syslog-2024.04.14/_close?pretty=true'

Open the index:

curl -XPOST -u login:password '127.0.0.1:9200/syslog-2024.04.14/_open?pretty=true'

Get the status of all indexes:

curl -XGET -u login:password '127.0.0.1:9200/_cat/indices?v'

Get the status of one specific index:

curl -XGET -u login:password '127.0.0.1:9200/_cat/indices/syslog-2024.04.14?v'

Display how much memory is used by the indexes:

curl -XGET -u login:password '127.0.0.1:9200/_cat/indices?v&h=i,tm&s=tm:desc'

Display details of the shards:

curl -XGET -u login:password '127.0.0.1:9200/_cat/shards?v'

Energy Logserver Document API

Create Document

Create a document with a specified ID:

curl -XPUT -u login:password '127.0.0.1:9200/syslog-2024.04.14/_doc/1?pretty=true' -d'{
    "host" : "firewall-01",
    "@timestamp" : "2024-04-14T10:00:00",
    "message" : "Connection accepted from 10.0.0.5"
}'

You should see the output:

{
  "_index" : "syslog-2024.04.14",
  "_id" : "1",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

Creating a document with an automatically generated ID (note: PUT -> POST):

curl -XPOST -u login:password '127.0.0.1:9200/syslog-2024.04.14/_doc?pretty=true' -d'{
    "host" : "firewall-01",
    "@timestamp" : "2024-04-14T10:10:00",
    "message" : "Connection denied from 192.168.1.100"
}'

You should see the output:

{
  "_index" : "syslog-2024.04.14",
  "_id" : "AV49sTlM8NzerkV9qJfh",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 1,
  "_primary_term" : 1
}

Delete Document

Delete a document by ID:

curl -XDELETE -u login:password '127.0.0.1:9200/syslog-2024.04.14/_doc/1?pretty=true'

curl -XDELETE -u login:password '127.0.0.1:9200/syslog-2024.04.14/_doc/AV49sTlM8NzerkV9qJfh?pretty=true'

Useful Commands

Get information about the document:

curl -XGET -u login:password '127.0.0.1:9200/syslog-2024.04.14/_doc/1?pretty=true'

You should see the output:

{
    "_index" : "syslog-2024.04.14",
    "_id" : "1",
    "_version" : 1,
    "_seq_no" : 0,
    "_primary_term" : 1,
    "found" : true,
    "_source" : {
        "host" : "firewall-01",
        "@timestamp" : "2024-04-14T10:00:00",
        "message" : "Connection accepted from 10.0.0.5"
    }
}

Get the source of the document:

curl -XGET -u login:password '127.0.0.1:9200/syslog-2024.04.14/_source/1?pretty=true'