Agent management commands

Views:

List all agents

clish agent show

Purpose

Displays the list of all registered agents or detailed information about a specific agent List All Agents clish agent show

Agent Name  Hostname  State       Attrs             Version
----------  --------  ----------  ----------------  -------
demo-1      -         running     C:Y K:OK H:✓      v1.0.0
demo-2      -         onboarding  C:N K:MISS H:✓    v1.0.0
page 1/1

Attributes Explanation

C: Connection State (Y=Connected, N=Disconnected, ?=Unknown)
K: Credential State (OK=Configured, MISS=Missing/Invalid, ?=Unknown)
H: Health Status (✓=Healthy, ✗=Unhealthy, ?=Unknown)

Show specific agent details

clish agent show --instance <agent-name>

Example

clish agent show --instance demo-1

Output example

Agent Name       : demo-1
Agent ID         : f461e289-c396-4f5b-8119-bea0a697d513
Device Hostname  : -
State            : running
Health           : healthy
ONTAP Connected  : connected
Credential       : configured
Log Level        : info
Quarantine       : disabled
Agent Version    : v1.0.0
Last Seen        : -
Reason           : -

Available Flags

--instance <name>: Show details for specific agent
--page <number>: Page number for agent list (default: 1)

Create an agent instance

clish agent create

Purpose

Create a new agent instance

clish agent create --name <agent-name>

Example

clish agent create --name demo-3

Output example

Agent 'demo03' created successfully with ID: f461e289-c396-4f5b-8119-bea0a697d513

Requirements

The agent name must match pattern: ^[a-zA-Z0-9_-]{1,20}$. This mean that it must less then 20 characters, and contain only alpha-numeric characters and the following special characters: ^[]-_{}$
The name must be unique across all agents

Delete an agent instance

clish agent delete

Purpose

Delete an agent instance

clish agent delete --instance <agent-name> [--yes]

Example

# With confirmation prompt
clish agent delete --instance demo-1
# Skip confirmation prompt
clish agent delete --instance demo-1 --yes

Output example

Are you sure you want to delete agent 'demo-1'? (y/yes to confirm): y
Agent 'demo-1' deleted successfully

Available flags

--instance <name>: Agent instance name to delete (required)
-y, --yes: Skip confirmation prompt

Notes

By default, the command requires user confirmation before deletion
Use -y or --yes flag to skip the confirmation prompt (useful for automation)
Deletion is permanent and cannot be undone
All agent configurations, credentials, and quarantine data will be removed

Create an onboarding token

clish agent onboarding-token issue

Purpose

Generate an onboarding token for agent registration

clish agent onboarding-token issue --instance <agent-name>

Example

clish agent onboarding-token issue --instance demo-1

Output example

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fweJf36POk6yJV_adQssw5c

Notes

Token is required for agent initial connection
Token has limited validity period
Agent must use this token for WebSocket connection establishment

Re-onboard an agent

clish agent re-onboard

Purpose

Re-onboard an agent by resetting its state and issuing a new onboarding token

clish agent re-onboard --instance <agent-name>

Example

clish agent re-onboard --instance demo-1

Output example

Agent re-onboarded successfully!

Onboarding Token:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fweJf36POk6yJV_adQssw5c

Next Steps:
1. Update the agent's config.yaml with the new onboarding token
2. Restart the agent
3. The agent will automatically receive a new device token after onboarding
4. Re enter the credential using the 'agent credential modify' command

When to use

This command is designed for scenarios where:

Agent's device token has expired
Agent cannot reconnect to the management service
You need to reset agent's connection state while preserving its configuration

Notes

he agent must be in the disconnected state before re-onboarding
If the agent is currently connected, the command will fail with an error message
This operation preserves:
- Agent ID
- Agent settings (log level, quarantine configuration)
- Quarantine data
After re-onboarding, you must:
- Update the agent's configuration file with the new onboarding token
- Restart the agent
- Re-enter credentials using agent credential modify command

Error example

If you attempt to re-onboard a connected agent:

Agent:
                demo-1 (ID: f461e289-c396-4f5b-8119-bea0a697d513) Current State: running
              Connection: connected
              Error: Agent is currently
              connected. Please ensure the agent is disconnected before
          re-onboarding.

Update ONTAP SVM credentials

clish agent credential modify

Purpose

Update the ONTAP SVM credentials for an agent

clish agent credential modify --instance <agent-name>

Example

clish agent credential modify --instance demo-1
# Interactive prompts: 
# username: admin 
# password: [hidden input]

Output example

Credentials updated successfully

Credential validation process

When you update credentials, the management service performs real-time validation to ensure the credentials work correctly.

Possible error scenarios

Agent not connected
```
Error: agent 'demo-1' is not connected via WebSocket, cannot validate credentials
```
- Solution
  
  Ensure the agent is running and connected to management service
Invalid agent state
```
Error: agent 'demo-1' is in state 'onboarding', cannot set credentials
```
- Solution
  
  Wait for the agent to reach credential-required or running state
Validation timeout:
```
Error: Agent did not respond to credential validation within timeout period
```
- Possible causes:
  - Network connectivity issues between agent and SVM
  - The agent is processing other high-priority tasks
  - The agent service is unresponsive
- Solution:
  - Check the agent logs for connection errors
  - Verify network connectivity to SVM
  - Check the agent health status with clish agent show --instance <name>
Credentials rejected by agent:
```
Error: Agent rejected credentials: Failed to connect to SVM: authentication failed
```
- Possible causes
  - Incorrect username or password
  - SVM user account is locked or disabled
  - SVM is unreachable from agent
- Solution
  - Verify credentials are correct for the target SVM
  - Check SVM user account status
  - Test network connectivity between agent and SVM

Notes

Password input is hidden during entry
Credentials are stored in Kubernetes Secrets
Only affects the specified agent instance
Credentials are validated in real-time with automatic rollback on failure

Display agent log levels

clish agent loglevel show

Purpose

Display the current log level for an agent

clish agent loglevel show --instance <agent-name>

Example

clish agent loglevel show --instance demo-1

Output example

Log Level for demo-1 : info

Modify the agent log level

clish agent loglevel modify

Purpose

Change the log level for an agent

clish agent loglevel modify --instance <agent-name> --loglevel <level>

Example

clish agent loglevel modify --instance demo-1 --loglevel debug

Output example

Log level for demo-1 set to debug

Available Log Levels

info: Standard operational logging
warning: Warning and error messages only
error: Error messages only

Display the quarantine settings

clish agent quarantine show

Purpose

Display the quarantine settings for an agent

clish agent quarantine show --instance <agent-name>

Example:

clish agent quarantine show --instance demo-1

Output example

Quarantine for demo-1 : disabled

Modify the quarantine functionality

clish agent quarantine modify

Purpose

Enable or disable the quarantine functionality for an agent

clish agent quarantine modify --instance <agent-name> --enabled <true|false>

Examples

# Enable quarantine
clish agent quarantine modify --instance demo-1 --enabled true

# Disable quarantine  
clish agent quarantine modify --instance demo-1 --enabled false

Output example

Quarantine for demo-1 set to enabled

Display the quarantine file records

clish agent quarantine files show

Purpose

Display all quarantine file records for the agent, including their status, timestamps, and associated file paths.

clish agent quarantine files show [flags]

Available flags

--instance <name> : Agent instance name (optional, shows all agents files if not specified)
--page <number> : Page number for quarantined file list (default: 1)
--quarantine-id <id> : Show detailed information for a specific quarantine file by ID
--status <quarantined|restored|restoring|quarantine-error|restore-error> : Filter by status

Examples

Show all quarantine files for all agents:
```
clish agent quarantine files show
```
Show quarantine files for a specific agent with status "quarantined":
```
clish agent quarantine files show --status quarantined
```
Show detailed information for a specific quarantine file ID:
```
clish agent quarantine files show --quarantine-id 105
```

Output examples

Quarantine ID  Agent Name  Timestamp            Status            Original Path                                       Quarantine Path                                     
-------------  ----------  -------------------  ----------------  --------------------------------------------------  --------------------------------------------------  
108            agent-01    2025-11-26 08:14:38  quarantine-error  \\FS01.CORP.LOCAL\share\finance\budget_v4.txt       C:\ProgramData\Agent\Quar...budget_v4_150ba326.txt  
107            agent-01    2025-11-26 08:08:38  quarantined       \\FS01.CORP.LOCAL\share\public\unknown_file.exe     C:\ProgramData\Agent\Quar...nown_file_da098e5c.exe  
106            agent-01    2025-11-26 07:51:38  quarantined       \\FS01.CORP.LOCAL\share\hr\resume_batch_5.doc       C:\ProgramData\Agent\Quar...e_batch_5_c2616949.doc  
105            agent-01    2025-11-26 07:44:38  restore-error     \\FS01.CORP.LOCAL\share\hr\resume_batch_5.doc       C:\ProgramData\Agent\Quar...e_batch_5_785dd8bd.doc  
104            agent-02    2025-11-24 09:00:32  quarantined       \\FS02.CORP.LOCAL\users\test\macro_virus.xlsm       C:\ProgramData\Agent\Quar...cro_virus_bbb1b9f9.xlsm  
103            agent-02    2025-11-24 08:15:47  restored          \\FS02.CORP.LOCAL\users\test\macro_virus.xlsm       C:\ProgramData\Agent\Quar...cro_virus_4baf367a.xlsm  
102            agent-01    2025-11-24 06:12:49  restore-error     \\FS01.CORP.LOCAL\share\it\script_tool.ps1          C:\ProgramData\Agent\Quar...ript_tool_f402f3d5.ps1  
101            agent-01    2025-11-23 16:42:09  restored          \\FS01.CORP.LOCAL\share\it\script_tool.ps1          C:\ProgramData\Agent\Quar...ript_tool_df5bb5be.ps1  

Page 1/1 (8 total quarantine files)

Quarantine File Details
=======================
ID              : 105
Agent Name      : agent-01
Scan ID         : 73a12b4c-81de-493f-b253-ae3fefe76d28
Status          : restore-error
Reason Code     : 201
Reason          : File not found in quarantine area
Timestamp       : 2025-11-26 07:44:38

File Paths
----------
Original Path   : \\FS01.CORP.LOCAL\share\hr\resume_batch_5.doc
Quarantine Path : C:\ProgramData\Agent\Quarantine\resume_batch_5_785dd8bd.doc

Display the scan metrics

clish agent scan-metrics show

Purpose

Display the scan metrics for an agent or all agents within a specified time range

clish agent scan-metrics show [flags]

Available flags

--instance <name>: Agent instance name (optional, shows all agents summary if not specified)
--time-range <range>: Time range (1d, 7d, 30d)
--from <date>: Start date (format: 2025-01-01, max 6 months range)
--to <date>: End date (format: 2025-01-08, max 6 months range)

Examples

Show the metrics for all agents (last 1 day - default):
```
clish agent scan-metrics show
```

Show the metrics for specific agent (last 7 days):

clish agent scan-metrics show --instance demo-1 --time-range 7d

Show the metrics with custom date range:
clish agent scan-metrics show --instance demo-1 --from 2025-01-01 --to 2025-01-08

Output example

Agent Metrics

Agent/Time    Total Scans  Clean  Infected  Error  Quarantined  Dropped
----------    -----------  -----  --------  -----  -----------  -------
demo-1        1500         1450   30        15     25           5
demo-2        2000         1980   10        5      8            2

Summary:
  Total Scans      : 3500
  Clean            : 3430
  Infected         : 40
  Error            : 20
  Quarantined      : 33
  Dropped          : 7

Notes

Default time range is 1 day if no flags specified
Both --from and --to must be specified together
Maximum time range is 6 months
Start date cannot be more than 6 months in the past

Display scan events

clish agent scan-events show

Purpose

Display scan events for an agent or all agents, filtered by status

clish agent scan-events show [flags]

Available flags

--instance <name>: Agent instance name (optional, shows all agents events if not specified)
--id <event-id>: Show detailed info for specific event ID
--status <status>: Status (infected, error, quarantined) - required for list mode
--page <number>: Page number (default: 1, page size: 20)

Examples

Show infected events for all agents:

clish agent scan-events show --status infected

Show error events for specific agent (page 2):

clish agent scan-events show --instance demo-1 --status error --page 2

Show detailed information for specific event:
```
clish agent scan-events show --id 12345
```

Output examples

List mode - infected:

ID     Agent Name  Timestamp            Status    Filename                    File Type  Malware Name      Malware Type
--     ----------  ---------            ------    --------                    ---------  ------------      ------------
12345  demo-1      2025-01-15 10:30:45  infected  /data/suspicious.exe        PE32       Trojan.Generic    trojan
12346  demo-1      2025-01-15 11:22:10  infected  /data/malware.doc           Office     Macro.Downloader  macro

Page 1/5 (95 total events)

List mode - error:

ID     Agent Name  Timestamp            Status  Filename              File Type  Error Code  Error Msg
--     ----------  ---------            ------  --------              ---------  ----------  ---------
12347  demo-2      2025-01-15 09:15:30  error   /data/corrupted.zip   ZIP        1001        File corrupted
12348  demo-2      2025-01-15 10:45:22  error   /data/large.tar.gz    GZIP       1002        File size exceeded

Page 1/3 (58 total events)

Detail mode

Scan Event Details
==================
Scan ID    : abc123-def456-ghi789
Source     : ontap-agent
Client ID  : agent-demo-1
Timestamp  : 2025-01-15 10:30:45
Status     : infected

File Information
----------------
Filename   : /data/suspicious.exe
SHA256     : a1b2c3d4e5f6...
File Type  : PE32

Malware Details
---------------
Malware Name : Trojan.Generic
Malware Type : trojan

Tags
----
  - high-risk
  - external-source

Notes

--status flag is required for list mode (not when using --id)
Valid status values: infected, error, quarantined
Page size is fixed at 20 events per page
Detail mode (with --id) shows complete event information including tags
Different columns are displayed based on the event status