代理程式管理命令

檢視次數:

列出所有代理

clish agent show

用途

顯示所有已註冊代理的列表或特定代理的詳細資訊列出所有代理 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: 連線狀態 (Y=已連線, N=未連線, ?=未知)
K: 憑證狀態 (OK=已配置, MISS=缺失/無效, ?=未知)
H: 健康狀態 (✓=正常, ✗=不正常, ?=未知)

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>：顯示特定代理的詳細資訊
--page <number>：代理列表的頁碼（預設：1）

建立代理實例

clish agent create

用途

建立新的代理實例

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

代理名稱必須符合模式：^[a-zA-Z0-9_-]{1,20}$。這意味著它必須少於 20 個字元，且僅包含字母數字字元和以下特殊字元：^[]-_{}$
名稱必須在所有代理中保持唯一

刪除代理執行個體

clish agent delete

用途

刪除代理執行個體

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>：要刪除的代理實例名稱（必填）
-y, --yes：跳過確認提示

注意

預設情況下，該命令需要用戶確認後才能刪除
使用 -y 或 --yes 標誌來跳過確認提示（對於自動化很有用）
刪除是永久性的，無法復原
所有代理配置、憑證和隔離資料將被移除

建立入門憑證

clish agent onboarding-token issue

用途

為代理註冊生成入門令牌

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

Example

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

Output example

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fweJf36POk6yJV_adQssw5c

注意

代理初始連線需要權杖
憑證的有效期限有限
代理必須使用此權杖來建立 WebSocket 連線

重新啟用代理程式

clish agent re-onboard

用途

通過重置代理的狀態並發出新的上線令牌來重新上線代理

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

此命令適用於以下情況：

代理的裝置權杖已過期
代理程式無法重新連接到管理服務
您需要重置代理的連接狀態，同時保留其配置

注意

代理必須處於斷線狀態才能重新上線
如果代理目前已連接，該命令將失敗並顯示錯誤訊息
此操作保留：
- 代理程式 ID
- 代理設定（日誌級別、隔離配置）
- 隔離資料
重新加入後，您必須：
- 更新代理的配置檔案以使用新的啟動令牌
- 重新啟動代理程式
- 使用agent credential modify指令重新輸入憑證

Error example

如果您嘗試重新啟動已連接的代理：

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.

更新 ONTAP SVM 憑證

clish agent credential modify

用途

更新代理的 ONTAP SVM 憑證

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

當您更新憑證時，管理服務會執行即時驗證，以確保憑證正常運作。

Possible error scenarios

Agent not connected
```
Error: agent 'demo-1' is not connected via WebSocket, cannot validate credentials
```
- Solution
  
  確保代理程式正在運行並已連接到管理服務
Invalid agent state
```
Error: agent 'demo-1' is in state 'onboarding', cannot set credentials
```
- Solution
  
  等待代理達到需要憑證或運行狀態
Validation timeout：
```
Error: Agent did not respond to credential validation within timeout period
```
- Possible causes：
  - 代理與 SVM 之間的網路連接問題
  - 代理程式正在處理其他高優先級任務
  - 代理服務無回應
- Solution：
  - 檢查代理日誌以查找連接錯誤
  - 驗證與 SVM 的網路連接
  - 使用 clish agent show --instance <name> 檢查代理健康狀態
Credentials rejected by agent：
```
Error: Agent rejected credentials: Failed to connect to SVM: authentication failed
```
- Possible causes
  - 使用者名稱或密碼錯誤
  - SVM 使用者帳號已被鎖定或停用
  - 無法從代理程式訪問 SVM
- 解決方案
  - 驗證目標 SVM 的憑證是否正確
  - 檢查 SVM 使用者帳號狀態
  - 測試代理與SVM之間的網路連接

注意

輸入密碼時將隱藏顯示
憑證儲存在 Kubernetes Secrets 中
僅影響指定的代理程式實例
憑證會即時驗證，失敗時自動還原

顯示代理日誌級別

clish agent loglevel show

用途

顯示代理的當前日誌級別

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

Example

clish agent loglevel show --instance demo-1

Output example

Log Level for demo-1 : info

修改代理日誌級別

clish agent loglevel modify

用途

更改代理的日誌級別

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：標準操作記錄
warning: 僅限警告和錯誤訊息
error：僅限錯誤訊息

顯示隔離設定

clish agent quarantine show

用途

顯示代理的隔離設定

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

Example：

clish agent quarantine show --instance demo-1

Output example

Quarantine for demo-1 : disabled

修改隔離功能

clish agent quarantine modify

用途

啟用或關閉代理的隔離功能

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

範例

# 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

顯示隔離檔案記錄

clish agent quarantine files show

用途

顯示代理的所有隔離檔案記錄，包括其狀態、時間戳記和相關的檔案路徑。

clish agent quarantine files show [flags]

Available flags

--instance <name>：代理實例名稱（可選，若未指定則顯示所有代理文件）
--page <number>：隔離檔案清單的頁碼（預設值：1）
--quarantine-id <id> : 顯示特定隔離檔案的詳細資訊，依據 ID
--status <quarantined|restored|restoring|quarantine-error|restore-error>：按狀態篩選

範例

顯示所有代理的所有隔離檔案：
```
clish agent quarantine files show
```
顯示狀態為「已隔離」的特定代理的隔離檔案：
```
clish agent quarantine files show --status quarantined
```
顯示特定隔離檔案 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

顯示掃瞄指標

clish agent scan-metrics show

用途

顯示指定時間範圍內單個代理或所有代理的掃瞄指標

clish agent scan-metrics show [flags]

Available flags

--instance <name>：代理程式實例名稱（可選，若未指定則顯示所有代理程式摘要）
--time-range <range>：時間範圍（1天、7天、30天）
--from <date>：開始日期（格式：2025-01-01，最大範圍為6個月）
--to <date>：結束日期（格式：2025-01-08，最大範圍為6個月）

範例

顯示所有代理的指標（過去 1 天 - 預設）：
```
clish agent scan-metrics show
```

顯示特定代理的指標（過去 7 天）：

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

顯示具有自訂日期範圍的指標：
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

注意

如果未指定標誌，預設時間範圍為 1 天
必須同時指定 --from 和 --to
最大時間範圍為6個月
開始日期不能早於過去6個月

顯示掃瞄事件

clish agent scan-events show

用途

顯示代理或所有代理的掃瞄事件，並依狀態已過濾

clish agent scan-events show [flags]

Available flags

--instance <name>：代理程式實例名稱（可選，若未指定則顯示所有代理程式事件）
--id <event-id>：顯示特定事件 ID 的詳細資訊
--status <status>：狀態（中毒、錯誤、隔離）- 列表模式所需
--page <number>：頁碼（預設值：1，頁面大小：20）

範例

顯示所有代理的中毒事件：

clish agent scan-events show --status infected

顯示特定代理的錯誤事件（第 2 頁）：

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

顯示特定事件的詳細資訊：
```
clish agent scan-events show --id 12345
```

Output examples

列表模式 - 中毒：

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)

列表模式 - 錯誤：

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

注意

--status 標誌在列表模式中是必需的（使用 --id 時則不需要）
有效狀態值：infected、error、quarantined
每頁的事件數固定為20個
詳細模式（使用--id）顯示完整的事件資訊，包括標籤
根據事件狀態顯示不同的欄位