NKCKI: Installation and configuration

Contents

• Overview
  • Package contents
• Installation sequence
  • Step 1. Prepare for installation
  • Step 2. Install objects with the utility
  • Step 3. Place the active action script
  • Step 4. Configure the connection
  • Step 5. Assign the incident type and workflow to tasks
  • Step 6. Verify the installation
    • 1. Verify objects with the utility
    • 2. Verify the incident type
    • 3. Verify the workflow
    • 4. Verify the active action
    • 5. Verify the dashboard
    • 6. Verify submission
• Troubleshooting

---

Overview

This article describes how to install and configure the integration between Incident Manager and the NKCKI personal account. For an overview of the integration, including notification types and limitations, see NKCKI Integration. For instructions on completing the incident card and submitting a notification, see NKCKI: Submit notifications.

Package contents

Component	Purpose
Installation utility maker/bin/nkcki_maker.py	Creates and updates integration objects in Smart Monitor
Active action script tools/nkcki_send_incident.py	Validates card fields, submits a notification to the account, and records the result in the card
Connection settings example tools/config.example.env	Template for the Smart Monitor Web environment file

The installation utility creates the following objects:

Object type	Objects
Incident fields	86 fields with the nkcki_ prefix, added to the incident card
Incident type	NKCKI (nkcki)
Active action	Submit incident to NKCKI
Workflow	NKCKI (workflow-nkcki)
Dashboard	NKCKI Incidents

The utility and script use only the Python standard library; no additional packages are required.

Information

After installation, transitions in the NKCKI workflow are available only to the all_access role. To make them available to operators, add their roles in workflow settings.

---

Installation sequence

Step 1. Prepare for installation

You need:

• Python 3.10 or later on the computer used to run the installation utility and on the Smart Monitor Web node
• a Smart Monitor account with administrator permissions
• network access from the installation computer to the Smart Monitor Web API (usually port 5601) and the Smart Monitor Data Storage API (usually port 9200)
• network access from the Smart Monitor Web node to the account API over HTTPS
• an API token for the selected account
• details about the organization that owns the information resource: short and full legal names, INN, KPP, OGRN, CII facility category, area of operation, and region code in ISO 3166-2 format, for example RU-KYA

Extract the distribution archive, go to the maker directory, and check the Python version:

cd <distribution-directory>/maker
python3 --version

Step 2. Install objects with the utility

Set the Smart Monitor account password and the Smart Monitor Data Storage API address in the current session environment variables, then run the installation:

export SM_PASSWORD='<password>'
export SM_URL='https://<smart-monitor-data-storage-address>:9200'
python3 bin/nkcki_maker.py deploy --host <smart-monitor-web-address>:5601 --user <username>

Utility parameters:

Parameter	Required	Default value	Description
deploy, show, render-defaults	Yes	-	Command: install objects, verify installed objects, or display default values without installing
--host	Yes	-	Smart Monitor Web API address in <node>:<port> format, without a protocol
--user	No	admin	Smart Monitor account
--sm-url	No	SM_URL value	Smart Monitor Data Storage API address. The deploy command requires this parameter or the SM_URL variable
--non-interactive	No	-	Use default values from environment variables instead of prompting

Answer the utility prompts. The answers are saved as default values for the NKCKI incident type and populated in each new card:

Prompt	Answer format
MSSP organization	MSSP organization name. If submission is not through an MSSP, press Enter
Short name of the resource owner	Text
CII facility categorization information	Option number from the list
Subject area of operation	Option number from the list
Location	Region code in ISO 3166-2 format, for example RU-KYA
Full legal name of the organization	Text. Enter keeps the previous value
Response teams engaged	Text. Enter keeps the previous value
INN	10 or 12 digits; required
KPP	9 digits; required
OGRN	13 or 15 digits; required

When the utility finishes, it displays the list of created and updated objects.

Warning

Running deploy again overwrites the fields, incident type, active action, NKCKI workflow, and dashboard from the distribution. Any manual changes to these objects are lost. Save them before running the command again.

When rerunning the utility, an empty answer to the MSSP organization or resource owner name prompt clears the previous default value.

Install without prompts

With --non-interactive, the utility reads default values from environment variables. An unset variable does not change its current default value. For the first installation, NKCKI_DEFAULT_INN, NKCKI_DEFAULT_KPP, and NKCKI_DEFAULT_OGRN are required.

Variable	Value
NKCKI_DEFAULT_MSSP	MSSP organization
NKCKI_DEFAULT_OWNER	Short name of the resource owner
NKCKI_DEFAULT_FULL_NAME	Full legal name of the organization
NKCKI_DEFAULT_OKII	CII facility category; exact option text, for example CII facility of significance category 3
NKCKI_DEFAULT_FUNCTION	Area of operation; exact option text, for example Healthcare
NKCKI_DEFAULT_LOCATION	Region code in ISO 3166-2 format
NKCKI_DEFAULT_RESPONSE_TEAM	Response teams engaged
NKCKI_DEFAULT_INN	INN
NKCKI_DEFAULT_KPP	KPP
NKCKI_DEFAULT_OGRN	OGRN

To display the values that will be applied without installing anything, run:

python3 bin/nkcki_maker.py render-defaults --host <smart-monitor-web-address>:5601 --non-interactive

Step 3. Place the active action script

Copy tools/nkcki_send_incident.py from the distribution to the active actions directory on the Smart Monitor Web node:

sudo cp nkcki_send_incident.py /app/opensearch-dashboards/config/actions/

Scripts in this directory are retained when plugins are updated. For details about placing scripts, see Create an active action script.

Step 4. Configure the connection

On the Smart Monitor Web node, open the service environment file:

sudo nano /app/opensearch-dashboards/config/environment

Add the connection parameters and keep the other file settings:

NKCKI_BASE_URL=https://<nkcki-account-api-address>/api/v2
NKCKI_API_TOKEN=<account-api-token>
NKCKI_INSECURE_TLS=false
NKCKI_MODE=direct
NKCKI_ENVIRONMENT=production
NKCKI_TIMEOUT_MS=30000

SM_URL=https://<smart-monitor-data-storage-address>:9200
SM_USER=<username>
SM_PASSWORD=<password>
SM_INSECURE_TLS=false
SM_DIRECT_INCIDENT_UPDATE=true

Variable	Required	Default value	Purpose
NKCKI_BASE_URL	Yes	-	Account API address; HTTPS only. Include the /api/v2 prefix if it is used
NKCKI_API_TOKEN	Yes	-	Account API token
NKCKI_INSECURE_TLS	No	false	true disables account certificate verification
NKCKI_MODE	No	direct	direct submits on behalf of the organization; mssp submits with an MSSP organization, making MSSP organization required
NKCKI_ENVIRONMENT	No	production	Label for the submission log; does not change the API address
NKCKI_TIMEOUT_MS	No	30000	Account request timeout in milliseconds
SM_URL	Yes	-	Smart Monitor Data Storage API address used to read the card, write the result, and record submission logs
SM_USER	Yes	-	Smart Monitor account. Requires permissions to read and update incidents and write to the sm-nkcki-exchange index
SM_PASSWORD	Yes	-	Password for the SM_USER account
SM_INSECURE_TLS	No	false	true disables Smart Monitor Data Storage certificate verification
SM_DIRECT_INCIDENT_UPDATE	No	true	Write the submission result to the incident card. If false, the result is not written to the card

Submission logs are stored in the sm-nkcki-exchange index in Smart Monitor Data Storage. You can override the log address and credentials with these optional variables:

Variable	Default value	Purpose
NKCKI_AUDIT_URL	<SM_URL>/sm-nkcki-exchange/_doc	Submission log endpoint
NKCKI_AUDIT_LOCK_URL	<SM_URL>/sm-nkcki-exchange/_create	Endpoint for recording duplicate-submission locks
NKCKI_AUDIT_TOKEN	-	Bearer token for writing to the log. If unset, SM_USER and SM_PASSWORD are used
NKCKI_AUDIT_INSECURE_TLS	SM_INSECURE_TLS value	true disables certificate verification when writing to the log

Warning

The environment file contains the account token and Smart Monitor password. Restrict access to the file and do not share its contents with third parties.

Restart Smart Monitor Web to apply the parameters and reload the active actions directory:

sudo systemctl restart opensearch-dashboards
sudo systemctl status opensearch-dashboards --no-pager

Verify that the service loads the environment file:

systemctl cat opensearch-dashboards | grep EnvironmentFile

The output must show the /app/opensearch-dashboards/config/environment path.

Step 5. Assign the incident type and workflow to tasks

The utility does not modify Job Scheduler tasks. For each task whose incidents must be submitted to NKCKI:

1. Open the task: Main Menu - Job Scheduler - Jobs List
2. In the Create Incident active action, set Incident type to NKCKI and Workflow to NKCKI
3. Check which card fields are populated from the task results. The operator must fill in the information that is not present in the task data before submitting
4. Save the task

Creating an incident with a task does not submit a notification to the account. The operator starts submission from the incident card. Check the type and workflow of existing incidents separately.

Step 6. Verify the installation

1. Verify objects with the utility

Run the utility with the show command:

python3 bin/nkcki_maker.py show --host <smart-monitor-web-address>:5601 --user <username>

Expected output:

NKCKI fields: 86/86
NKCKI type: present
NKCKI dashboard: present (1)

2. Verify the incident type

Verify that the NKCKI incident type exists: Main Menu - System Settings - Module Settings - Incident Manager - Incident Types. The type must have the Submit incident to NKCKI active action selected.

3. Verify the workflow

Verify that the NKCKI workflow exists and includes the New incident, In progress, Information submitted to NKCKI, Submission error, and Incident closed states: Main Menu - System Settings - Module Settings - Incident Manager - Workflow.

4. Verify the active action

Verify that the Submit incident to NKCKI active action with the nkcki_send_incident script exists: Main Menu - System Settings - Module Settings - Incident Manager - Active Actions. If the script is not listed, check Step 3 and restart Smart Monitor Web.

5. Verify the dashboard

Verify that the dashboard exists: Main Menu - Overview - Dashboards - NKCKI Incidents.

6. Verify submission

Create a test incident with the NKCKI type and workflow, then submit it as described in NKCKI: Submit notifications.

Warning

A notification submitted to the production account is registered with NKCKI. Use a test account for verification if one is available.

---

Troubleshooting

Error or symptom	What to check
Environment variable SM_PASSWORD is required.	SM_PASSWORD is set in the same terminal session used to run the utility
For deploy, specify --sm-url or SM_URL.	The --sm-url parameter is passed or the SM_URL variable is set
For a new installation, specify the required values: ...	When running with --non-interactive, NKCKI_DEFAULT_INN, NKCKI_DEFAULT_KPP, and NKCKI_DEFAULT_OGRN are set
“Field name”: value is missing from the dictionary.	NKCKI_DEFAULT_OKII and NKCKI_DEFAULT_FUNCTION exactly match an option in the list
API connection error during installation	The --host and SM_URL addresses and ports, network access, and account permissions
NKCKI_BASE_URL is not set. NKCKI_API_TOKEN is not set.	Parameters in the environment file, whether the service loads the file, and whether Smart Monitor Web has been restarted
NKCKI_BASE_URL must use HTTPS.	The account address starts with https://
To write the NKCKI response to Smart Monitor, set environment variables: ...	The SM_URL, SM_USER, and SM_PASSWORD variables in the environment file
certificate verify failed	Python trust chain on the Smart Monitor Web node and the NKCKI_INSECURE_TLS or SM_INSECURE_TLS variable for the relevant connection
Active action is missing from the incident card	The card's incident type is NKCKI, the script is in place, and Smart Monitor Web has been restarted
The operator cannot use workflow transitions	The operator's roles are included in the NKCKI workflow transitions

For errors that occur while submitting a notification, see NKCKI: Submit notifications.