nShield Audit Log Service

Introduction

The nShield Audit Log Service (nshieldauditd) retrieves and removes audit logs from HSMs that are available to the local hardserver and are listed in the nShield audit log service’s configuration file. There are two types of audit logs: nCore audit logs and signed system logs.

It retrieves nCore audit logs, see Audit Logging, from PCIe HSMs running firmware version 13.5 or later and from network-attached HSMs running firmware version 13.6 or later.

nShield Audit Log Service and the new audit databases support the new audit logs for 13.5 firmware onwards only. It does not retrieve the CEF-format audit logs from earlier firmware versions (the legacy audit configuration settings in [auditlog_settings] continue to be supported for those logs, and verification thereof can be done with the separate cef-audit-verify tool).

It also retrieves signed system logs from nShield 5s HSMs running firmware version 13.5 or later and nShield 5c HSMs running firmware version 13.6 or later. See System logging (nShield 5 HSMs).

Both types of logs are saved in separate local database files stored by default in a subdirectory of NFAST_KMDATA.

The service must be configured to enable log fetching from available HSMs. Once configured, the service runs automatically in the background without user intervention.

Connect XC and 5c HSMs enrolled in a Security World with audit-logging enabled (including a Common-Criteria (CMTS) compatible Security World) will continuously generate nCore audit-logs and, if these audit-logs are not transferred and removed by the nshieldauditd service, the HSMs may run out of disk space and will not process certain commands until their audit-logs are transferred and removed.
5s and 5c HSMs generate signed system logs internally in v13.5 onwards. These logs also need to be transferred and removed by the nShield Audit Log Service. This is true even when the Security World does not have audit-logging enabled.

nShield Audit Log Service configuration

The nShield Audit Log Service is configured by editing a YAML-format configuration file. Configuration changes can be applied by restarting the service.

Restarting nshieldauditd on Linux

The nShield Audit Log Service can be restarted on Linux by running the following command as root:

/opt/nfast/scripts/init.d/nshieldauditd restart

Instead of restart use stop followed by start parameters to explicitly stop and start the service respectively.

Restarting nshieldauditd on Windows

The service can be stopped and started from an elevated (Administrator) Windows command prompt using these commands:

net stop "nShield Audit Log Service"
net start "nShield Audit Log Service"

To restart the service as a single operation, run the following PowerShell command from an elevated (Administrator) PowerShell shell:

Restart-Service "nShield Audit Log Service"

Editing the configuration file on Linux

The configuration file is located at /opt/nfast/kmdata/auditlogs/nshieldauditd.conf. Editing the file requires membership of the nfast group.

Editing the configuration file on Windows

The configuration file is located at C:\ProgramData\nCipher\Key Management Data\auditlogs\nshieldauditd.conf by default. Editing the file requires the privileges of the built-in local Administrators group.

Default configuration file

The default configuration is created when the service first starts, and looks as follows:

# nShield Audit Log Service config file
#
# This configuration file is in yaml format.

#--------------------------------------------------------------------
# modules is the list of ESNs of HSMs from which to fetch nCore and
# (if applicable) syslog audit.
# By default, no modules are included in the list.
# Set modules: ["AAAA-AAAA-AAAA", "BBBB-BBBB-BBBB"] to enable fetching
# of audit from modules with ESNs AAAA-AAAA-AAAA and BBBB-BBBB-BBBB
# Comment out or delete the modules: [] line to fetch audit from
# all modules.

modules: []

#--------------------------------------------------------------------
# syslog_fetch_interval_hours specifies the time in hours to wait
# between fetching the nShield 5 HSM syslog audit.
# It is always fetched when the service first starts.
# Default value is 12.

#syslog_fetch_interval_hours: 12

#--------------------------------------------------------------------
# suppress_repeat_logs_interval specifies the time
# to wait for repeated log messages to be logged again.
# Set interval values in 's'(seconds), 'm'(minutes), or 'h'(hours),
# for example: '0s', '5m', '10h' etc.
# If set to '0s' then no logs will be suppressed.
# Recommended to set it to '0s' while in debug mode.
# Default value is '5m'.

#suppress_repeat_logs_interval: '5m'

#--------------------------------------------------------------------
# logging_level controls the verbosity of log messages from the nShield Audit Log Service's own operations (not the audit logs themselves)
# Available levels in increasing order of severity are DEBUG, INFO, WARNING, ERROR, or CRITICAL (default is INFO)

#logging_level: INFO

Configurable options

modules

The nShield Audit Log Service only fetches logs from the modules that are specified in the configuration file. If the modules field is commented out or absent then all HSMs available to the local hardserver will be monitored by the nShield Audit log service; this provides a shorthand if the goal is to fetch audit from all enrolled modules.

By default, the modules field is an empty list, so this must be configured to enable the fetching of logs. Only one client system of the modules should enable log fetching, otherwise the audit log services will conflict with each other; that is why the user must explicitly opt-in to enable the fetching, to prevent any conflicts from default configuration. You can add or remove a module by editing the configuration file and restarting the nShield Audit Log Service. The ESN of each module to be enrolled should be specified within quotes and separated with a comma.

To fetch nCore or signed system logs from a network-attached HSM (Connect XC or 5c) the client machine where the nShield Audit Log Service has been configured must have been enrolled as a privileged client of that HSM.
Security World HSM estates with multiple client machines must configure just one client’s nShield Audit Log Service to monitor any given HSM, although different nShield Audit Log Services may be configured to monitor different subsets of HSMs. If multiple services fetch logs from the same HSM, then each client’s databases will only contain some of the log records.

syslog_fetch_interval_hours

This option configures how often the service should fetch the signed system logs from the HSM.

By default, syslog_fetch_interval_hours is commented out and the default value of 12 hours will be used.

The interval in the configuration file is in hours. The interval must be set in between 1 and 168 hours.

Signed system logs are produced at a relatively low rate, and fetching and removing the logs itself produces an audit record. This is why fetching of the logs is infrequent, unlike the continuous streaming of records that is done for nCore audit.
Signed system logs are not produced by nShield Solo XC and nShield Connect XC HSMs.

suppress_repeat_logs_interval

This option configures how often the service should show repeated log messages.

By default, suppress_repeat_logs_interval is commented out and the default value of 5 minutes will be used,

The interval for log suppression can be set in seconds, minutes or hours.

It is recommended to set the suppress_repeat_logs_interval to 0 when debugging.

logging_level

This option configures how much debug information is recorded in the service’s application log. This is for monitoring the nShield Audit Log Service’s operation in fetching nCore and signed system logs, and does not control the verbosity of that actual audit log data.

By default the service logging level is set to INFO, which will also report any higher severity messages. This is the recommended setting, although logging can be reduced by setting WARNING, ERROR, or CRITICAL to restrict only to messages at that log level or above.

If additional logging is desired, the DEBUG setting can be set, but note that this will write considerably more information to the service log, and will also slow down service operation as it will also include a human-readable representation of the nCore audit logs as they arrive. This is only recommended when investigating issues or if advised to do so by nShield Support.

On Linux, the service debug log is /opt/nfast/log/nshieldauditd.log. On Windows, the service debug log can be viewed in the Windows Event Viewer (nCipherAuditSvc event source) or can be queried using nshieldeventlog -s nCipherAuditSvc -c 10 (for example) to view the most recent 10 lines of the service Event Log (adjust -c parameter for a larger number of lines, or use the -f parameter to write to a file).

When first configuring the system, it is recommended to check the service debug log to ensure that it reports that it has detected the intended modules and enabled log fetching for them.

Warrants

The nShield Audit Log Service attempts to retrieve the KLF2 warrant for each configured module automatically. It stores the warrants in the nCore audit log database for their module.

In nShield 5 HSMs, this warrant is embedded in the module and is always available.

In nShield XC HSMs, the KLF2 warrant must be present in one of the following locations in the filesystem of the machine running the nShield Audit Log Service, depending on how you are interacting with the HSM:

  • /opt/nfast/kmdata/warrants (Linux) or C:\ProgramData\nCipher\Key Management Data\warrants (Windows)
    This is the same location as where a warrant should be placed if using nShield Remote Administration smartcards.

  • /opt/nfast/kmdata/hsm-<ESN>/warrants (Linux) or C:\ProgramData\nCipher\Key Management Data\hsm-<ESN>\warrants (Windows)
    Where <ESN> is the ESN of the relevant module.
    This is where nShield Connect XC warrants are automatically placed on the RFS. If the warrant is not here, you will need to reconfigure (see rfs-setup) and reboot the HSM to copy the warrant to the correct location.

nShield Connect XC

To run the nShield Audit Log Service on a different client machine to the RFS, you must first copy the warrant file to /opt/nfast/kmdata/warrants or C:\ProgramData\nCipher\Key Management Data\warrants.

If there was no warrant present when the nShield Audit Log Service was started, you can still verify the chain up to the root of trust post-hoc with nshieldaudit. Copy the warrant to /opt/nfast/kmdata/warrants or C:\ProgramData\nCipher\Key Management Data\warrants on the machine where you are running nshieldaudit. When it displays the information, for example in nshieldaudit ncore query, it always re-runs the verification of the chain and will pick up the warrant from the aforementioned location.

Log databases

The nShield Audit Log Service saves the nCore audit logs and signed system logs in local database files. Logs for each module are saved in their own database in a subdirectory of the auditlogs directory named after the ESN of that module.

To back-up the log databases, first stop the nShield Audit Log Service, recursively copy the auditlogs directory, then start the service again. Stopping the service during backup ensures that a consistent state of the database files is copied, with no temporary transaction files being present. If restoring from backup, the original permissions and ownership of files and directories should be restored.

Linux

The databases are located in /opt/nfast/kmdata/auditlogs.

The directory and its contents have read and write permissions for nfast group by default. To restrict access to a different group, run the /opt/nfast/sbin/install script with NSHIELDAUDITD_GROUP environment variable set to the name of the alternate group. This must be set every time install is run in order to retain this setting. The nshieldauditd service user will be added to the alternate group automatically, and the group will be created during install if it does not already exist.

Windows

The databases are located in C:\ProgramData\nCipher\Key Management Data\auditlogs.

Access is restricted to members of the built-in Administrators group (with elevated privilege) and the nShield Audit Log Service itself. To allow access to other users or groups without elevated privilege, the DACL of the directory may be modified, but note that it will be reset to defaults when the nShield software is re-installed.

Alternative log database directory

The above log database locations can be overridden by setting the environment variable NFAST_AUDIT_LOGDIR to the alternative location. This can be another local directory, or a network share.

If NFAST_AUDIT_LOGDIR is set, that also changes the service configuration file location to be inside that directory, that is, NFAST_AUDIT_LOGDIR/nshieldauditd.conf. Set the environment variable NFAST_AUDIT_SERVICE_CONF if a different location is desired for the configuration file.

These environment variables must be set in the environment of the service, and of any tools which read the logs. On Windows, set the environment variables in the Windows system variables, and on Linux in the /etc/nfast.conf file, in order to make them visible to the service. The service must be restarted for the change to take effect.

If you already have audit logs stored in the default location, it is recommended that the nShield Audit Log Service be stopped, the existing contents moved to the new location, and then the service started after setting the environment variables, so that the existing portion of the logs are not lost.

Reading the audit log databases

The nShield Audit Log Service databases are accessed with the command line tool nshieldaudit which manages logs using different subcommands as explained in the following sections. By default, running the nshieldaudit subcommands requires membership of nfast group on Linux and an elevated (Administrator) command prompt on Windows.

nshieldaudit <subcommand>
The audit logs in the databases are not in a human-readable format. Therefore, to be made human-readable, they must be exported to a file using the nshieldaudit tool.
Timestamps reported by nshieldaudit and in the audit logs themselves are UTC.

nshieldaudit supports the following subcommands:

Reading signed system logs

The nshieldaudit syslogs subcommand allows the user to access the signed system logs stored in the database.

nshieldaudit syslogs [-h] {query,export,info}

This subcommand takes the following parameters:

Parameter Description

--help or -h

Show the help message and exit

query

Show the contents of the signed system logs database

export

Export the audit data to a file in JSON format

info

An overview of one or more log entries

Querying available signed system logs

Use the nshieldaudit syslogs query subcommand to quickly see what signed system logs databases are available, an overview of the date and sequence ranges of their content, and a "Log Status" to summarize any detected verification errors or missing data.

 nshieldaudit syslogs query [-h] [-e ESN(s) [ESN(s) ...]]

The subcommand nshieldaudit syslog query takes the following parameters:

Parameter Description

--help or -h

Show the help message and exit

-e ESN(s) [ESN(s) …​] or --esn ESN(s) [ESN(s) …​]

One or more ESN(s) of the HSM(s) that generated the audits

A typical output looks like the following:

$ nshieldaudit syslogs query
--esn AAA1-BBB2-CCC3
    Sequence numbers:          --start 1 --end 7775
    Time:                      --from 2024-01-13_12:11:03 --to 2024-05-28_08:31:40
    Malformed Logs:            0
    Unverified Logs:           0
    Unattested Logs:           0
    Missing Sequences:         None
    Log Status:                OK
--esn 1ABC-1DEF-1GHI
    Sequence numbers:          --start 13 --end 125
    Time:                      --from 2024-05-23_13:05:48 --to 2024-05-28_07:48:33
    Malformed Logs:            0
    Unverified Logs:           0
    Unattested Logs:           0
    Missing Sequences:         1-12
    Log Status:                Issues found

nshieldaudit syslogs info

This subcommand allows the user to see a more detailed summary of the available signed syslogs, for a given ESN, than the nshieldaudit syslogs query subcommand. It allows the time ranges and number of log lines in each of the sequence numbers in the signed syslogs to be listed, in support of constraining the range of interest when retrieving the log contents using the export subcommand.

nshieldaudit syslogs info [-h] -e ESN(s) [ESN(s) ...] [--start START_INDEX] [--end END_INDEX] [--from FROM_DATE] [--to TO_DATE]

The subcommand nshieldaudit syslog info takes the following parameters:

Parameter Description

--help or -h

Show the help message and exit

-e ESN(s) [ESN(s) …​] or --esn ESN(s) [ESN(s) …​]

One or more ESN(s) of the HSM(s) that generated the audits

The subcommand nshieldaudit syslog info allows the user to add the following filters:

Parameter Description

--start START_INDEX

Start index of the audits desired

--end END_INDEX

End index of the audits desired

--from FROM_DATE

Start date of the audits desired (UTC)

--to TO_DATE

End date of the audits desired (UTC)

Exporting signed system logs to JSON format or text format

Use the subcommand nshieldaudit syslogs export to export the signed system logs data to a file. The output file is written in JSON format (default), or in the human-readable text format if the -t or --text parameter is added.

nshieldaudit syslogs export [-h] -e ESN(s) [ESN(s) ...] [-v] -f FILE [--overwrite] [--malformed] [-t] [--start START_INDEX] [--end END_INDEX] [--from FROM_DATE] [--to TO_DATE]

The subcommand nshieldaudit syslog export takes the following parameters:

Parameter Description

--help or -h

Shows the help message and exits

-e ESN --esn ESN

Required: the ESN of the module whose signed system logs is to be exported

-v, --verify

Re-verify signatures whilst exporting; this significantly increases export time. (default is to report cached verification status)

-f FILE, --file FILE

Required: Store output in this file (in JSON format)

--overwrite

Overwrite the output file if it exists

--malformed

Export malformed logs

-t, --text

Export of human-readable summary of logs in the text format rather than full JSON

The subcommand nshieldaudit syslog export allows the user to add the following filters:

Parameter Description

--start START_INDEX

Start index of the audits desired

--end END_INDEX

End index of the audits desired

--from FROM_DATE

Start date of the audits desired (UTC)

--to TO_DATE

End date of the audits desired (UTC)

Run nshieldaudit syslogs query first in order to get parameters that can be copied to produce the nshieldaudit syslogs export command-line.

By default, the output format is JSON format (it is formatted with whitespace indentation to also be human-readable). To emit in a more compact human-readable text format, add the --text parameter. In many cases --text will be the more convenient format to use for browsing the data, and it is faster to export and produces a smaller output file.

Example command (text output):

nshieldaudit syslogs export --esn 5323-D01E-6DC0 -t

The output file will contain content like the following.

2024-11-12 06:51:19 HDR to=2024-11-12 07:51:33 esn=5323-D01E-6DC0 seq_no=1231
2024-11-12 06:51:19 nshield5 monitor[3987]: New log file: current seq-no=1231
2024-11-12 06:51:19 nshield5 monitor[3987]: Last log: {'signature': {'key': 'AAAA...', 'sig': 'AAAA...', 'mech': 'ecds...', 'hash': 'a684...'}, 'seq-no': 1230}
2024-11-12 06:51:19 nshield5 monitor[3987]: Command response: {'log-data': '2024-11-12 05:51:06 nshield5 moni...', 'signature': {'key': 'AAAA...', 'sig': 'AAAA...', 'mech': 'ecds...', 'hash': 'a684...'}, 'seq-no': 1230}
2024-11-12 06:51:28 nshield5 monitor[4002]: Command args: {'subcommand': 'expirelog', 'seq_no': 1230}
2024-11-12 06:51:28 nshield5 monitor[4002]: Removed saved log file messages.saved.1230
2024-11-12 06:51:28 nshield5 monitor[4002]: Command response: None
2024-11-12 07:51:33 nshield5 monitor[4017]: Command args: {'subcommand': 'exportlog', 'saved_log': False}

Run nshieldaudit syslogs export --malformed to export malformed logs into a file. By default the export file will be in JSON format unless -t or --text parameter is added.

nshieldaudit syslogs export --malformed -f ./log_export -e 5323-D01E-6DC0 --text --overwrite

Reading nCore audit logs

The nshieldaudit ncore subcommand allows the user to read nCore audit logs from the database.

nshieldaudit ncore [-h] {query,export}

This subcommand takes the following parameters:

Parameter Description

--help or -h

Show the help message and exit

query

Shows the contents of the audit logs database

export

Export the audit data to a file in JSON (default) or text format

Querying available nCore audit logs

Use the nshieldaudit ncore query subcommand to quickly see what nCore audit log databases are available, an overview of the date and index ranges of their content, and a "Log Status" to summarize any detected verification errors or missing data.

nshieldaudit ncore query [-h] [-e ESN(s) [ESN(s) ...]] [-l LOGID [LOGID ...]]

This subcommand takes the following parameters:

Parameter Description

--help or -h

Show the help message and exit

-e ESN(s) [ESN(s) …​] or --esn ESN(s) [ESN(s) …​]

One or more ESN(s) of the HSM(s) that generated the audits

-l LOGID [LOGID …​] or --logid LOGID [LOGID …​]

One or more LogID(s) of the nCore audit-log(s)

A typical output looks like this:

$ nshieldaudit ncore query
--esn A1A1-B2B2-C3C3 --logid f515236b5a4970f0e0ac7a3c2852c6b53fee28e3
    Indexes:                 --start 1 --end 6546650
    Time:                    --from 2024-05-30_12:21:56 --to 2024-06-04_13:16:25
    KML Status:              Verification chain OK
    Finalized Status:        Finalized
    Malformed Segments:      0
    Unverified Segments:     0
    Missing indexes:         None
    Log Status:              OK

A brief description of each field:

Parameter Description

Indexes

First and last Audit Index present in the local database for this log.

Time

UTC timestamps of the first and last audit records for this log.

KML Status

Status of verification chain of the KML public key (used to sign audit records) up to the nShield HSM root of trust.

KML Error

This field only appears if there is an error in KML Status, to give more details on KML verification error.

KML Warning

This field only appears if it was not possible to find a warrant to verify the chain of trust.

Finalized Status

Finalized if the module has been re-initialized (with initunit or by loading a Security World again) and Unfinalized otherwise.

Malformed Segments

Count of the number of audit log segments that could not be processed.

Unverified Segments

Count of the number of audit log segments that failed to verify with the KML key.

Missing indexes

List of the ranges of Audit Indexes that are missing in the database. This is inclusive counting, for example 1-2 means both Audit Index 1 and 2 are missing.

Log Status

OK if there are no detected issues with this log, and Issues Found if there are any errors or warnings reported in the other fields.

Exporting nCore audit to JSON or text format

Use the nshieldaudit ncore export subcommand to export the audit data to a file. The output file is written in JSON format (default), or in the human-readable text format if the -t or --text parameter is added.

nshieldaudit ncore export [-h] -e ESN(s) [ESN(s) ...] -l LOGID [LOGID ...] [-v] -f FILE [--overwrite] [-t] [--start START_INDEX] [--end END_INDEX] [--from FROM_DATE] [--to TO_DATE]
The nshieldaudit ncore export command can take some time if there is a very large amount of data to export.

The subcommand nshieldaudit ncore export takes the following parameters:

Parameter Description

--help or -h

Show the help message and exit

-e ESN or --esn ESN

Required: ESN of the module whose logs to export

-l LOGID or --logid LOGID

Required: The specific LogID from this module to export

-t, --text

Export of human-readable summary of logs in text format rather than full JSON

-v, --verify

Re-verify signatures whilst exporting; this significantly increases export time. (default is to report cached verification status)

-f FILE, --file FILE

Required: Store output in this file

--overwrite

Overwrite the output file if it exists

--malformed

Export malformed logs

The subcommand nshieldaudit ncore export allows the user to add the following filters:

Parameter Description

--start START_INDEX

Start index of the audits desired

--end END_INDEX

End index of the audits desired

--from FROM_DATE

Start date of the audits desired (UTC)

--to TO_DATE

End date of the audits desired (UTC)

Run nshieldaudit ncore query first in order to get parameters that can be copied to produce the nshieldaudit ncore export command-line.

The --esn and --logid options must be supplied to specify the log whose data to export (the nshieldaudit ncore query command can be used to get these parameters), along with the --file parameter to specify the output file path.

By default, the output format is JSON format (it is formatted with whitespace indentation to also be human-readable). To emit in a more compact human-readable text format, add the --text parameter. In many cases --text will be the more convenient format to use for browsing the data, and it is faster to export and produces a smaller output file.

Example command (text output):

$ nshieldaudit ncore export --esn 4210-02E0-D947 --logid 9455993eca529189f44a4861d2c23ef359f549ff --text --file ncore.audit.4210-02E0-D947.txt
100%

The output file will contain content like the following. Note that identical repeated operations within each "segment" of log like this are collated with the "REPEAT=+17" field which indicates that this command was repeated a further 17 times, that is, 18 times total. This reduces the verbosity of data when the system is under load.

2024-06-07 22:43:59.876 HDR logid=9455993eca529189f44a4861d2c23ef359f549ff runid=2 start=36398476 end=36398546 signtime=2024-06-07_22:43:59.883
2024-06-07 22:43:59.876 idx=36398476 src=Host cmd=Sign rc=OK obj=162 REPEAT=+17
2024-06-07 22:43:59.877 idx=36398477 src=Host cmd=Sign rc=OK obj=161 REPEAT=+19
2024-06-07 22:43:59.877 idx=36398480 src=Host cmd=Sign rc=OK obj=163 REPEAT=+15
2024-06-07 22:43:59.878 idx=36398484 src=Host cmd=Sign rc=OK obj=160 REPEAT=+16

Run nshieldaudit ncore export --malformed to export malformed logs into a file. By default the export file will be in JSON format unless -t or --text parameter is added.

nshieldaudit ncore export --malformed -f ./log_export_ncore -e 5323-D01E-6DC0 --text --overwrite -l 0032bf17c0aeb84aefa31c29f846886d39710eff
Audit records are verified automatically as they arrive by the nShield Audit Log Service. To re-verify records when exporting, pass the --verify option, otherwise the cached verification status is reported in the output file. Re-verification will significantly increase the time to export the logs.

Monitoring and managing audit data sources

Hardserver audit database storage limit

The hardserver has its own audit database as the temporary staging area for nCore audit records from modules that are local to it. This ensures that the audit records are not lost whilst waiting to be handed over to the nShield Audit Log Service.

  • For Linux it is located at /opt/nfast/hardserver.d/audit.db.

  • For Windows it is located at C:\ProgramData\nCipher\hardserver.d\audit.db.

  • For network-attached HSMs (Connect XC and 5c), it is stored internally on the device.

This is not the same database as the nShield Audit Log Service database which is located as described in Log databases.

There is a configuration section auditdb_settings, which is present on both client-side and in network-attached HSMs configuration. If the section is missing, then the defaults will be applied. To learn more about the configuration section, see Audit Database setting.

A default auditdb_settings configuration section is as follows:

[auditdb_settings]
# Start of the auditdb_settings section
# Hardserver settings for (new format v13.5 and later) nCore audit logging
# database.
# Each entry has the following fields:
#
# Minimum available megabytes of free-space for audit DB to operate.
# (default=0 for auto-configured)
#  free_space_min_mb=MB
#
# Maximum total size of audit DB in megabytes. (default=0 for no limit)
#  db_size_max_mb=MB
#
# Maximum number of audit indexes in audit DB. (default=0 for no limit)
#  audit_indexes_max=COUNT
This is not the same configuration file as the nShield Audit Log Service configuration file (which is described in nShield Audit Log Service configuration).

By default network-attached HSMs (5c or Connect XC) pause HSM auditing when 500 MB of free space is left in the appliance, and client-side hardservers pause auditing of local HSMs when 50 MB of free space is left in the local storage. When HSM auditing is paused, any nCore commands which require the creation of an audit record will be denied. The paused status of an HSM will also be visible in the output of the enquiry tool in the hardware status field.

The configuration section changes can be applied dynamically by pushing configuration to a network-attached HSM. For local modules run the cfg-reread command to apply a change.

Checking nCore audit temporary storage usage

In normal usage, when the nShield Audit Log Service is operating correctly, the amount of temporary storage consumed for audit on HSMs should be small, as the data is being offloaded to the long-term databases. The following commands can be used to monitor to help detect issues.

Checking temporary storage for nCore audit usage for on a network-attached HSM (Connect XC or 5s) can be checked using the command stattree RemoteServers 1 ServerGlobals (replacing 1 with whatever the module number is).

Local temporary storage for nCore audit usage for Solo XC or 5s can be checked using the command stattree ServerGlobals.

The AuditDBUsedSpaceMB field states the number of megabytes of space consumed by the temporary database (where data is staged before being fetched by the nShield Audit Log Service). The AuditDBFreeSpaceMB field states the number of megabytes of available space on the same partition as that temporary database.

Example output (for local storage usage):

stattree ServerGlobals | grep AuditDB
   -AuditDBFreeSpaceMB   102694
   -AuditDBUsedSpaceMB   45

Checking or repairing hardserver audit database

The nshieldaudit serveradmin subcommand enables the system administrator to check or repair, if needed, the temporary database of nCore audit logs not yet processed by the nShield Audit Log Service. It requires a privileged connection to the hardserver (membership of nfast group by default on Linux, and elevated Administrator command prompt by default on Windows). If managing a network-attached HSM, that must also have been enrolled as privileged.

This command only interacts with the hardserver to query its internal staging database that temporarily stores nCore audit data, and does not relate to the long-term databases that the nshieldaudit ncore and nshieldaudit syslogs subcommands provide access to.

To learn more about the hardserver internal audit.db, see hardserver audit database.

nshieldaudit serveradmin [-h] [-m MODULE] [-q] [-e ESN] [-l LOGID] [--delete] [--end END] [--force] [--delete-status] [--recreate-db] [--no-confirm]

This subcommand takes the following parameters:

Parameter Description

-m or --module

Module ID of source data server. Use 0 to refer to local hardserver.

-e or --esn

ESN of the log. Required when deleting.

-q or --query

query status of logs

-l or --logid

Log id of audit logs. Required when deleting.

--delete

Manually delete logs. Log deletion is normally automatic. This option should only be used in a recovery situation.

--end

When deleting audit logs the index of the last logs to be deleted.

--force

When deleting override check on whether logs have already been exported.

--delete-status

Delete the audit export status information. Not recommended unless the LogID is reported as finalized.

--recreate-db

Deletes entire database and creates a new empty database. Not recommended except in a recovery situation.

--no-confirm

Omits the interactive confirmation for --delete and --recreate-db options.

Querying hardserver database contents

Run nshieldaudit serveradmin --query to query the contents of the hardserver’s temporary staging database.

The required hardware capabilities of the host machine running the nShield Audit Log Service depend on the amount of audit-log data that it needs to export, verify and expire. By running nshieldaudit serveradmin --query the user can monitor that the nShield Audit Log Service is successfully keeping up with offloading nCore audit records.

nshieldaudit serveradmin --query reports on the local system’s hardserver by default (this will show information for audit from Solo XC and 5s modules). To query the temporary staging database of a network-attached HSM (Connect XC or 5c), add the -m or --module parameter to specify the module number of that HSM.

Example output (showing both the completed offload of a "Finalized" log as well as the in-progress offload of the log for the currently loaded Security World):

nshieldaudit serveradmin --query -m1
--esn=4210-02E0-D947 --logid=1330c21f241db5b2d86f5ddb99bccaacf12453df
    Indexes still on source data server (inclusive): --start=0 --end=0
    Total remaining index count: 0
    Exported to index: 218871
    Log creation time: 2024-04-08 10:12:56.145
    Log status: Finalized
--esn=4210-02E0-D947 --logid=9455993eca529189f44a4861d2c23ef359f549ff
    Indexes still on source data server (inclusive): --start=749879020 --end=749880109
    Total remaining index count: 1090
    Exported to index: 749879019
    Log creation time: 2024-06-07 20:57:03.480
    Log status: Unfinalized

Placeholder records of previously encountered logids seen by the system are kept by default (as in the "Finalized" log example above). If you wish to delete these placeholders for a "Finalized" log, you may issue the command nshieldaudit serveradmin --delete --delete-status --esn=4210-02E0-D947 --logid=1330c21f241db5b2d86f5ddb99bccaacf12453df -m1 (replacing 1 with the module number in -m1 - this may be omitted if it is a local module, and passing the actual --esn and --logid values for the log status information to be deleted).

Forcibly deleting records or re-creating hardserver database

The nshieldaudit serveradmin --delete command can be used to delete records up to a specified --end value.

The nshieldaudit serveradmin --recreate-db command can be used to delete the entire database, that is, all status tracking information and any nCore audit records not yet offloaded will be lost.

In both cases, if interacting with a remote module, add the -m1 (or appropriate module number) parameter to specify which hardserver the command should be sent to.

These commands will prompt for confirmation by default. They are not intended to be issued except in non-production test systems or as emergency recovery options if advised to do so by nShield Support.

Checking signed system logs HSM storage

The percentage free space for signed system logs temporary storage for a 5s or 5c can be queried using the command appliance-cli -m1 gethsmenvstats, replacing 1 with the module number. This is not applicable to XC modules.

Example output showing 90% free space, that is, only 10% used:

appliance-cli -m1 gethsmenvstats | grep log_free_space
            "log_free_space": 90,

Large consumption of this storage space is not expected in normal usage as signed system logs are only written occasionally, and the HSM stores the logs in a compressed form.