Version: 4.0

Updating Smart Monitor

Caution!

This instruction describes the process of updating Smart Monitor from version 3.2.* to 4.0.*.

Information

Conventions:

SMOS_40 - the directory where the Smart Monitor version 4.1 installation package is unpacked.
USER - a system user with administrator rights, usually admin.
OPENSEARCH_HOME - the OpenSearch home directory, usually /app/opensearch/.
OPENSEARCH_DATA - the directory where indexed data is stored, usually /app/data/.
OSD_HOME - the OpenSearch Dashboards home directory, usually /app/opensearch-dashboards/.
PATH_SSL - the location of the certificate, the admin private key, and the ca-cert, usually /app/opensearch/config/.

Attention!

Two methods are available for upgrading from version 3.2 to version 4.0: automated using the update script and manual mode.

The first step in updating is to determine the currently installed version of Smart Monitor. This can be done by viewing the module versions on the main page or by running the following command in the command line:

curl https://127.0.0.1:9200/_cat/plugins -k -u $USER

After entering this command, you will need to enter the password for the $USER account. It is recommended to use the admin user.

Let's consider the update procedure for each component. The 4.0 installer needs to be unpacked into a directory, for example, /app/distr/.

Caution!

Before starting work, it is strongly recommended to back up the main configuration files and Security settings.

Recommended Actions

It is recommended to create a directory, for example, /app/backup, where you should save:

The config directory, usually $OPENSEARCH_HOME/config or $OSD_HOME/config.
The systemd files, usually /etc/systemd/system/opensearch.service and /etc/systemd/system/opensearch-dashboards.service, /etc/systemd/system/sme-re.service.
The file /etc/sysctl.d/00-opensearch.conf.

A copy of the Security settings. This needs to be done once, and requires the certificate and private key of the admin user. (The command below will create a directory with the current date containing the OpenSearch security settings.)

JAVA_HOME=$OPENSEARCH_HOME/jdk/ $OPENSEARCH_HOME/plugins/opensearch-security/tools/securityadmin.sh -backup my-backup-directory \
  -icl \
  -nhnv \
  -cacert $OPENSEARCH_HOME/config/ca-cert.pem \
  -cert $OPENSEARCH_HOME/config/admin-cert.pem \
  -key $OPENSEARCH_HOME/config/admin-key.pem

Mitre Action and Mitre Objects Migration

Version 4.0 introduces significant changes to the internal storage structure of Mitre object documents. These changes require data migration to ensure proper system operation after upgrading from version 3.2 to 4.0.

The purpose of data migration is to transfer information from the existing .sm_jsc_jobs and .smos_mitre-yyyy.ww indices in accordance with the new storage structure, taking into account the changes introduced in version 4.0.

danger

The migration process must be performed before proceeding with the main update. These actions need to be performed once.

The actions described below are performed in the Developer Console. To access it, open the web interface (OpenSearch-Dashboards) and navigate to Navigation Menu - System Settings - Developer Console.

To ensure uninterrupted execution of scheduled jobs, migration must be performed according to the following algorithm:

Create a backup copy of the index by performing reindexing for .sm_jsc_jobs. It is recommended to specify backup_sm_jsc_jobs as the backup index. This step is necessary to ensure data safety in case of unexpected failures.

POST _reindex
{
  "source":{
    "index":".sm_jsc_jobs"
  },
  "dest":{
    "index":"backup_sm_jsc_jobs"
  }
}

Perform the migration process using the script.

Attention!

When executing the script, the following fields will be permanently deleted: technique_id, technique_name, technique, tech.

POST .sm_jsc_jobs/_update_by_query
{
   "script" : {
    "source": """
    
    for (int i = 0; i < ctx._source.actions.length; i++)
      if (ctx._source.actions[i].mitre != null) {
        HashMap mitre = ctx._source.actions[i].mitre;
        
        mitre.rule = mitre.index_fields.rule;
        mitre.index_fields.remove("rule");
        
        mitre.layers = mitre.index_fields.layers;
        mitre.index_fields.remove("layers");
        
        mitre.technique_id = [];
        mitre.technique_id.add(mitre.index_fields.technique_id);
        mitre.index_fields.remove("technique_id");
        mitre.index_fields.remove("technique_name");
        mitre.index_fields.remove("technique");
        mitre.index_fields.remove("tech");
        
        mitre.severity = mitre.index_fields.severity;
        mitre.index_fields.remove("severity");
        
        mitre.custom_fields = mitre.index_fields;
        mitre.remove("index_fields");
      }
    
    """,
    "params" : {},
    "lang": "painless"
  },
  "query": {
    "exists": {
      "field": "actions.mitre.index_fields"
    }
  }
}

Perform migration of Mitre objects using the script below:

Attention!

It is recommended to run the script for current data in .smos_mitre-yyyy.ww, where yyyy.ww should be replaced with the date in year-week format.

When executing the script, the following fields will be permanently deleted: technique, tech, tactic.

POST .smos_mitre-yyyy.ww/_update_by_query
{
  "script" : {
    "source": """
    
    ctx._source.remove("technique");
    ctx._source.remove("tech");
    ctx._source.remove("tactic");
    
    """,
    "params" : {},
    "lang": "painless"
  },
  "query": {
    "exists": {
      "field": "technique"
    }
  }
}

Migration actions are completed. After performing the above steps, update the Smart Monitor components.

Updating Interface Styles

The update to version 4.0 includes not only functional improvements but also changes to the user interface design. One such change is the update of interface styles and logo. To apply these changes, execute the command below:

POST .sm_settings/_update_by_query
{
  "query": {
    "match": {
      "_meta.id.keyword": "styles"
    }
  },
  "script" : {
    "source": "ctx._source.fontColor = \"#585857\";ctx._source.fontFamily = \"PT Sans, \\\"Source Sans 3\\\"\";ctx._source.mainGreen = \"#3B8646\";ctx._source.mainRed = \"#DC4E41\"; ctx._source.mainYellow = \"#F8BE32\";ctx._source.primaryColor = \"#3B8646\"; ctx._source.secondaryColor = \"#44686e\" ",
    "lang": "painless"
  }
}

This command updates the interface style parameters, including font color, font family, and primary colors.

Updating OpenSearch

In version 4.0, the OpenSearch and OpenSearch Dashboards plugins have been updated, along with the inventory and SME-RE components. The 4.1 installer must be extracted to a directory, for example, /app/distr/. Mark the location where you extract the archive contents as $SMOS_40.

SM_41=/app/distr/sm_4.1

Automatic Mode

The script requires the following pre-installed packages:

curl
zip
unzip

Note!

If you do not see the message indicating that Smart Monitor has been updated at the end, do not rerun the update script. Take a screenshot of where the script stopped and contact technical support.

The automatic update script automates the update process and is located at $SMOS_40/opensearch/update.sh. The file format is YAML and is similar to the configuration file used during installation.

Note!

Start the upgrade with nodes that do not have the master role. Data nodes can connect to older versions of master nodes, but not vice versa.

To start the update, run the script:

$SMOS_40/opensearch/update.sh

After launching, the script automatically finds the paths to the main directories:

OpenSearch Home Directory - the OpenSearch installation directory, usually /app/opensearch
OpenSearch Conf Directory - the OpenSearch configuration files directory, usually /app/opensearch/config/
OpenSearch Data Directory - the data directory, usually /app/data/
OpenSearch Logs Directory - the logs directory, usually /app/logs/

The update script does not perform any actions with the data and logs directories. The configuration files directory and systemd files will be saved to a temporary directory $SMOS_40/opensearch/staging/.

Note!

If you run the script again, the staging directory will be cleared.

================================================================================
SMART MONITOR UPDATE SCRIPT - OPENSEARCH
================================================================================

Current working directory: /app/distr/smos_4.0/opensearch

Current name of install's archive: opensearch-2.11.1-linux-x64.tar.gz

New version OpenSearch: 2.11.1

================================================================================
-- STEP 1. INSTALLATION DIRECTORIES

Opensearch home directory [/app/opensearch]:
Opensearch conf directory [/app/opensearch/config]:
Opensearch data directory [/app/data]: /app/data/opensearch
Opensearch logs directory [/app/logs]: /app/logs/opensearch

Final Opensearch home directory: /app/opensearch
Final Opensearch conf directory: /app/opensearch/config
Final Opensearch data directory: /app/data/opensearch
Final Opensearch logs directory: /app/logs/opensearch
Is this correct? [y/n]:

After entering the directories, you need to confirm the automatically found data by pressing y, or enter your directories manually by pressing n.

In the second step, you need to answer the question about allocation. If you enter y, the script will disable allocation before the update and enable it at the end of the script.

-- STEP 2. GET ADMIN PASSWORD

Enter password for user "admin":

In the third step, you will need to enter the password for the admin user. The password will not be displayed while typing.

Then, preparatory actions will be performed before the update. Before applying the update, you will be asked to continue. No changes are made to the system until this point. Some information about the current node and the cluster as a whole will also be displayed.

get current list of plugins
sm-core
sm-im
sm-inventory
sm-ism-action-clickhouse
sm-job-scheduler
sm-job-scheduler-actions-incident
sm-job-scheduler-actions-mitre
sm-knowledge-center
sm-mitre
sm-mssp
sm-rsm
sm-uba
sme
opensearch-security
Information about current node OpenSearch:
{
  "name" : "smos-node-00",
  "cluster_name" : "smos-cluster",
  "cluster_uuid" : "yKPPDCHGSA6rHQT948jokQ",
  "version" : {
    "distribution" : "opensearch",
    "number" : "2.11.1",
    "build_type" : "tar",
    "build_hash" : "6b1986e964d440be9137eba1413015c31c5a7752",
    "build_date" : "2023-11-29T21:43:10.135035992Z",
    "build_snapshot" : false,
    "lucene_version" : "9.7.0",
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

!!! AT THIS POINT WE START TO MAKE CHANGES IN OPERATING SYSTEM !!!
Do you want to continue? [y/N]:

Pressing Enter will interrupt the update; press y to continue.

Upon successful completion of the update, you should see the message SMART MONITOR SUCCESSFULLY UPDATED!. Information about the cluster and the current node will be displayed beforehand.

-- STEP 10. PRINT INFORMATION
current state of cluster
{
  "cluster_name" : "smos-cluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "discovered_master" : true,
  "discovered_cluster_manager" : true,
  "active_primary_shards" : 50,
  "active_shards" : 50,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 15,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 76.92307692307693
}
current state clusters nodes
172.16.0.27 14 99 8 1.47 0.63 0.26 dim data,ingest,master * smos-node-00
Information about current node OpenSearch:
{
  "name" : "smos-node-00",
  "cluster_name" : "smos-cluster",
  "cluster_uuid" : "yKPPDCHGSA6rHQT948jokQ",
  "version" : {
    "distribution" : "opensearch",
    "number" : "2.13.0",
    "build_type" : "tar",
    "build_hash" : "7ec678d1b7c87d6e779fdef94e33623e1f1e2647",
    "build_date" : "2024-03-26T00:02:39.659767978Z",
    "build_snapshot" : false,
    "lucene_version" : "9.10.0",
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

================================================================================
-- SMART MONITOR SUCCESSFULLY UPDATED!
================================================================================

Note that the update script takes into account the current list of installed plugins on OpenSearch nodes. If you need to install any additional plugins, you should do this manually at the end of the node update.

UpdatingOpenSearch Dashboards

This script automates the OpenSearch Dashboards update process. It requires the following pre-installed packages:

curl
zip
unzip

The automatic update script is located at $SMOS_40/opensearch-dashboards/update.sh. The file format is YAML and is identical to the installation configuration file.

During execution, the script backs up the systemd service file, opensearch-dashboards.yml, and the configuration directory to a temporary directory: $SM_41/opensearch-dashboards/staging/.

The update script does not modify the data and logs directories. The configuration directory and systemd files are backed up to the temporary directory $SMOS_40/opensearch-dashboards/staging/.

To update, run the script:

$SMOS_40/opensearch-dashboards/update.sh

The script automatically detects the main paths on the current server for the following directories:

OpenSearch Dashboards Home Directory - The OpenSearch Dashboards installation directory, typically /app/opensearch-dashboards
OpenSearch Dashboards Conf Directory - The OpenSearch Dashboards configuration directory, typically /app/opensearch-dashboards/config/
OpenSearch Dashboards Data Directory - The data directory, typically /app/data/
OpenSearch Dashboards Logs Directory - The logs directory, typically /app/logs/

================================================================================
SMART MONITOR INSTALL SCRIPT - OPENSEARCH DASHBOARDS
================================================================================

Current working directory: /app/distr/smos_4.0/opensearch-dashboards

Current name of install's archive: opensearch-dashboards-2.11.1-linux-x64.tar.gz

Current version OpenSearch-Dashboards: 2.11.1

================================================================================
-- STEP 1. INSTALLATION DIRECTORIES


Proceed with installation. Shutdown the running service OpenSearch-Dashboards.

Opensearch Dashboards home directory [/app/opensearch-dashboards]:
Opensearch Dashboards conf directory [/app/opensearch-dashboards/config]:
Opensearch Dashboards data directory [/app/data]: /app/data/opensearch-dashboards/
Opensearch Dashboards logs directory [/app/logs]: /app/logs/opensearch-dashboards/

Final Opensearch Dashboards home directory: /app/opensearch-dashboards
Final Opensearch Dashboards conf directory: /app/opensearch-dashboards/config
Final Opensearch Dashboards data directory: /app/data/opensearch-dashboards/
Final Opensearch Dashboards logs directory: /app/logs/opensearch-dashboards/
Is this correct? [y/n]:

After the directories are displayed, confirm the information by pressing y, or enter your directories manually by pressing n.

The script then performs preparatory actions for the update. Before applying the update, it prompts for confirmation. Up to this point, no actions affecting the system's operability are performed. Information about the current node and the cluster will also be displayed.

Current list of plugins:
-- smartMonitor
-- smartMonitorColumnChart
-- smartMonitorCyberSecurity
-- smartMonitorDrawio
-- smartMonitorHeatmapChart
-- smartMonitorHtmlChart
-- smartMonitorIncidentManager
-- smartMonitorInventory
-- smartMonitorKnowledgeCenter
-- smartMonitorLineChart
-- smartMonitorLookupManager
-- smartMonitorMitreAttack
-- smartMonitorPDFExport
-- smartMonitorPieChart
-- smartMonitorSingleValue
-- smartMonitorTable
-- smartMonitorUserBehaviorAnalytics

Current version of OpenSearch-Dashboards: 2.13.0

!!! AT THIS POINT WE START TO MAKE CHANGES IN OPERATING SYSTEM !!!
Do you want to continue? [y/N]:

Upon successful completion of the update script, the following message is displayed: SMART MONITOR DASHBOARDS SUCCESSFULLY UPDATED.

Information​

Recommended Actions​

Mitre Action and Mitre Objects Migration​

Updating Interface Styles​

Updating OpenSearch​

Automatic Mode​

UpdatingOpenSearch Dashboards​

Information

Recommended Actions

Mitre Action and Mitre Objects Migration

Updating Interface Styles

Updating OpenSearch

Automatic Mode

UpdatingOpenSearch Dashboards