Support

Support for business applications

Kaspersky Endpoint Agent

Managing Kaspersky Endpoint Agent using the command line interface

Managing Standard IOC Scan tasks

Kaspersky Endpoint Agent
Нет результатов
Online Help
FAQ Forum Contact support Recovery tools Product videos

Managing Standard IOC Scan tasks

November 17, 2023

ID 194147

Standard IOC Scan tasks are group or local tasks that are created and configured manually in Kaspersky Security Center or through the command line interface. IOC files prepared by the user are used to run the tasks.

Only the files with IOC rules can be specified for the IOC Scan task. Files with other types of rules are not supported for the IOC Scan task.

To create and configure a Standard IOC Scan task using the command line interface:

  1. On the device, run a command line interpreter (for example, Command Prompt cmd.exe) with the permissions of the local administrator.
  2. Using the cd command, navigate to the folder where the Agent.exe file is located.

    For example, enter the command cd "C:\Program Files (x86)\Kaspersky Lab\Endpoint Agent\" and press ENTER.

  3. Run the following command and press Enter:

    agent.exe --scan-ioc {[--path=<path to folder with IOC files>] | [<full path to IOC file>]} [--process=no] [--hint=<full path to executable file of the process|full path to file>] [--registry=no] [--dnsentry=no] [--arpentry=no] [--ports=no] [–services=no] [--system=no] [--users=no] [--volumes=no] [--eventlog=no] [--datetime=<event publication date>] [--channels=<list of channels>] [--files=no] [--network=no] [--url=no] [--drives=<all|system|critical|custom>] [--excludes=<list of exclusions>][--scope=<configurable list of folders>] [--retro]

    If the --scan-ioc command is passed with only the required parameters, Kaspersky Endpoint Agent will perform the scan with the default settings.

    If the --scan-ioc command is passed together with the two required parameters (--path=<path to the folder with IOC files> and <full path to the IOC file>), Kaspersky Endpoint Agent scans the submitted IOC files.

    Command parameters for running and configuring Standard IOC Scan tasks

    Parameters

    Description

    --scan-ioc

    Required parameter.

    Starts the Standard IOC Scan tasks on the device.

    --path=<path to folder with IOC files>

    Path to the folder with the IOC files that you want to scan.

    Required parameter if the <full path to the IOC file> parameter is not specified.

    <full path to IOC file>

    Full path to the IOC file, with ioc or xml extension, that you want to scan.

    A required parameter if the --path=<path to the folder with IOC files> parameter is not specified.

    Passed without the --path argument.

    --process=<no>

    Optional parameter.

    This parameter disables the analysis of process data during scans.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent does not consider the processes running on the device during scanning. If the IOC file contains IOC terms of the ProcessItem IOC document, they are ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only scan the process data if the ProcessItem IOC document is described in the IOC file submitted for scanning.

    --hint=<full path to the executable file of the process|full path to file>

    Optional parameter.

    This parameter allows you to narrow the scope of data analyzed while checking the ProcessItem and FileItem IOC documents by specifying a particular file.

    The parameter value can be set as:

    • <full path to the executable file of the process> – ProcessItem
    • <full path to the file> – FileItem

    This parameter can only be passed together with the --process=yes and --files=yes arguments.

    --dnsentry=no

    Optional parameter.

    This parameter disables the analysis of data on records in the local DNS cache (DnsEntryItem IOC document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not scan the local DNS cache. If the IOC file contains the terms of the DnsEntryItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only scan the local DNS cache if the DnsEntryItem IOC document is described in the IOC file submitted for scanning.

    --arpentry=no

    Optional parameter.

    This parameter disables the analysis of data in ARP table (ArpEntryItem document) records during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not scan the ARP table. If the IOC file contains the terms of the ArpEntryItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only scan the ARP table if the ArpEntryItem IOC document is described in the IOC file submitted for scan.

    --ports=no

    Optional parameter.

    This parameter disables the analysis of data on ports that are open for listening (PortItem document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not scan the table of active connections on the device. If the IOC file contains the terms of the PortItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only scan the table of active connections if the PortItem IOC document is described in the IOC file submitted for scanning.

    --services=no

    Optional parameter.

    This parameter disables the analysis of data on services installed on the device (ServiceItem document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not scan data on services installed on the device. If the IOC file contains the terms of the ServiceItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only scans the data on services if the ServiceItem IOC document is described in the IOC file submitted for scanning.

    --volumes=no

    Optional parameter.

    This parameter disables the analysis of volume data (VolumeItem document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not scan volume data on the device. If the IOC file contains the terms of the VolumeItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only scan the data on volumes if the VolumeItem IOC document is described in the IOC file submitted for scanning.

    --eventlog=no

    Optional parameter.

    This parameter disables the analysis of data about Windows Event Log entries (EventLogItem document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not scan Windows Event Log entries. If the IOC file contains the terms of the EventLogItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only scan Windows Event Log entries if the EventLogItem IOC document is described in the IOC file submitted for scanning.

    --datetime=<event publication date>

    Optional parameter.

    This parameter allows you to enable or disable accounting for the date and time when the event was registered in the Windows Event Log when determining the IOC scan area for the corresponding IOC document.

    During IOC scanning, Kaspersky Endpoint Agent will only process events that were registered within the time interval between the specified date and time and the task execution time.

    Kaspersky Endpoint Agent allows you to specify the event registration date as the parameter value. Scans will be performed only for events registered in the Windows Event Log between the specified date and the time when the IOC scan is performed.

    If the parameter is not passed, Kaspersky Endpoint Agent will scan events with any registration date. The TaskSettings::BaseSettings::EventLogItem::datetime parameter cannot be changed.

    This parameter is only used if the EventLogItem IOC document is described in the IOC file submitted for scanning.

    --channel=<list of channels>

    Optional parameter.

    This parameter allows you to pass a list of the names of channels (logs) for which IOC scanning is required.

    If this parameter is passed, Kaspersky Endpoint Agent will only consider events published in the specified logs when performing the IOC Scan task.

    The name of the log is specified as a string based on the name of the log (channel) specified in the properties of this log (the Full Name parameter) or in the properties of the event (the <Channel></Channel> parameter in the xml-scheme of the event).

    By default (including in the case that the parameter is not passed), IOC scanning is performed for the Application, System, and Security channels.

    Several values, separated by spaces, can be passed to the parameter.

    This parameter is only used if the EventLogItem IOC document is described in the IOC submitted for scanning.

    --system=no

    Optional parameter.

    This parameter disables the analysis of environmental data (SystemInfoItem IOC document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not analyze environmental data. If the IOC file contains the terms of the SystemInfoItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only analyze environmental data if the SystemInfoItem IOC document is described in the IOC file submitted for scanning.

    --users=no

    Optional parameter.

    This parameter disables the analysis of user data (UserItem IOC document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not analyze the data on users created in the system. If the IOC file contains the terms of the UserItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only analyze data on users created in the system if the UserItem IOC document is described in the IOC file submitted for scanning.

    --files=no

    Optional parameter.

    This parameter disables the analysis of data on files (FileItem IOC document) during IOC scanning.

    If the parameter is passed with the <no> value, Kaspersky Endpoint Agent will not analyze data on files. If the IOC file contains the terms of the FileItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only analyze data on files if the FileItem IOC document is described in the IOC file submitted for scanning.

    --network=no

    Optional parameter.

    This parameter enables threat lookup based on the Network IOC document during IOC scanning.

    If the <no> value is set for the parameter, Kaspersky Endpoint Agent does not perform threat lookup based on the Network IOC document. If the IOC file contains the terms of the Network IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent only enables threat lookup based on the Network IOC document if the Network IOC document is described in the IOC file submitted for scanning.

    --url=no

    Optional parameter.

    This parameter enables threat lookup based on the UrlHistoryItem IOC document during IOC Scanning.

    If the <no> value is set for the parameter, Kaspersky Endpoint Agent will not perform threat lookup based on the UrlHistoryItem IOC document. If the IOC file contains the terms of the UrlHistoryItem IOC document, they will be ignored (defined as no match).

    If the parameter is not passed, Kaspersky Endpoint Agent will only enable threat lookup based on the UrlHistoryItem IOC document if the UrlHistoryItem IOC document is described in the IOC file submitted for scanning.

    --drives=<all|system|critical|custom>

    Optional parameter.

    This parameter allows you to specify the scope of the IOC scan when analyzing data for the FileItem IOC document.

    This parameter can have one of the following values:

    • <all> – the application scans all available file areas.
    • <system> – the application only scans files that are located in the folders where the operating system is installed.
    • <critical> – the application only scans temporary files that are located in user and system folders.
    • <custom> – the application only scans files that are located in the areas specified by the user.

    If the parameter is not passed, critical areas will be scanned.

    --excludes=<list of exclusions>

    Optional parameter.

    This parameter allows you to specify exclusion scopes when analyzing data for the FileItem IOC document. Several values separated by space can be passed by the parameter.

    If the parameter is not passed, all folders will be scanned, with no exclusions.

    --scope=<configurable list of folders>

    Optional parameter.

    This parameter becomes required if the --drives=custom parameter is passed.

    This parameter allows you to specify a list of scan areas. Several values separated by space can be passed by the parameter.

    --retro

    Optional parameter.

    This parameter is used to start the task in Retrospective IOC Scan mode.

    In addition to this parameter, you can specify the time interval within which the application will perform a retrospective IOC scan using the following parameters:

    • --start-time=<date and time of the start of the interval>
    • --end-time=<interval end time>

      Example:

      agent.exe --scan-ioc --path=<path to the folder with IOC files> --retro --start-time=2021-05-21T10:30:00Z --end-time=2021-05-24T10:30:00Z

    If the time interval is not specified, the default interval will be used, starting one day before the task was started and ending at the moment the task was launched.

Return codes of the --scan-ioc command:

  • -1 – command is not supported by Kaspersky Endpoint Agent version installed on the device.
  • 0 – command successfully executed.
  • 1 – required argument is not passed to the command.
  • 2 – general error.
  • 4 – syntax error.

If the command was executed successfully (code 0) and indicators of compromise were detected during the command execution, Kaspersky Endpoint Agent displays the following data on the task execution results in the command line:

Data displayed by the application in the command line when an IOC is detected

Uuid

IOC file identifier from the header of the IOC file structure (<ioc id=""> tag)

Name

IOC file description from the header of the IOC file structure (<description></description> tag)

Matched Indicator Items

The list of identifiers of all triggered indicators.

Matched objects

Data on each IOC document where a match was detected.

Date

Creation date of the file where indicators of compromise were detected.

Created

Only for FileItem. Creation time of the object where indicators of compromise were detected.

Pid

Identifier of the process for which indicators of compromise were detected.

Upid

Unique identifier of the process for which indicators of compromise were detected.

ParentPid

Identifier of the parent object that contains the process for which indicators of compromise were detected.

Username

Name of the user who made changes to the object being scanned.

StartTime

Start time of the process for which indicators of compromise were detected.

See also

IOC Scan

About IOC Scan tasks in Kaspersky Endpoint Agent

Did you find this article helpful?
What can we do better?
Thank you for your feedback! You're helping us improve.
Thank you for your feedback! You're helping us improve.