[Notice]关于安全软件误报的说明/Regarding Security Software False Positives

[owu]

Note: This report is posted in two comments for bilingual accessibility.

• Comment 1 (this one): Simplified Chinese（简体中文）
• Comment 2 (the reply below): English
  Please read the English version in the reply below if needed.

问题描述

下载 WSL Dashboard 的 .exe 安装包或 .zip 压缩包后，Windows Defender 或其他杀毒软件可能会弹出安全警告，提示文件存在风险或直接拦截删除。

为什么会出现这种情况？

这是 误报，并非文件真的携带病毒。

根本原因是：本项目未购买 EV（Extended Validation）代码签名证书。

什么是代码签名证书？

代码签名证书用于对可执行文件进行数字签名，证明该文件来自可信的发布者且未被篡改。Windows 对未签名或使用普通证书签名的程序会采取更严格的安全检查。

证书类型的区别

证书类型	价格	SmartScreen 策略
无签名	免费	直接拦截，标记为"未知发布者"
普通 OV 证书	数百元/年	仍会弹出警告，需要积累信誉
EV 证书	数千元/年	立即通过，无警告

未使用 EV 证书签名的程序，Windows SmartScreen 会默认标记为不安全，杀毒软件也更容易将其识别为潜在威胁。

关于文件安全性

请放心，本项目的构建过程完全透明、可审计：

1. 开源代码：所有源代码均托管在 GitHub 上，任何人都可以审查
2. 自动化构建：exe 文件由 GitHub Actions 工作流在 GitHub 的服务器上自动构建生成，整个过程无人工干预
3. 构建可追溯：每次构建都有完整的日志记录，可在 GitHub Actions 页面查看
4. 零接触发布：开发者无法在构建过程中插入任何恶意代码，文件从构建完成到发布下载全程自动化

简单来说：exe 文件从未经过开发者的手，不存在被"投毒"的可能。

解决方案

方案一：添加信任白名单（推荐普通用户）

Windows Defender 拦截时：

1. 打开 "Windows 安全中心" → "病毒和威胁防护"
2. 点击 "保护历史记录"
3. 找到被拦截的项目，点击 "操作" → "允许"

或在下载前添加排除项：

1. 打开 "Windows 安全中心" → "病毒和威胁防护" → "管理设置"
2. 下滑找到 "排除项"，点击 "添加或删除排除项"
3. 添加下载目录为排除项

第三方杀毒软件： 请在对应软件中将下载的文件或目录添加到信任列表。

方案二：从源码编译（推荐开发者）

如果您对预编译的二进制文件仍有顾虑，可以直接克隆源码在本地编译：

# 克隆仓库
git clone https://github.com/owu/wsl-dashboard.git
cd wsl-dashboard

# 编译 Release 版本
cargo build --release

# 编译产物位于 target/release/ 目录

这样您可以完全确认运行的代码内容。

方案三：购买 EV 证书（对开发者的说明）

购买 EV 代码签名证书可以从根源上解决误报问题，但面临以下现实困难：

• 费用高昂：EV 证书每年需要数千元人民币
• 持续成本：证书需要按年续费，是长期负担
• 项目性质：WSL Dashboard 是非盈利的开源项目，难以承担这笔开支

如果您希望支持本项目的发展，可以通过项目主页的赞助渠道进行捐赠，帮助开发者覆盖证书等运营成本。

总结

• 文件被拦截是由于缺少 EV 代码签名证书，不是病毒
• 所有构建产物均由 GitHub Actions 自动生成，过程透明可审计
• 用户可以通过添加白名单或自行编译来解决此问题
• 购买 EV 证书可从根本上解决，但对非盈利项目存在经济压力

感谢您的理解与支持！

[owu]

Problem Description

After downloading WSL Dashboard's .exe installer or .zip archive, Windows Defender or other antivirus software may display a security warning indicating the file poses a risk, or directly block and delete it.

Why Does This Happen?

This is a false positive — the file does not actually contain any virus.

The root cause is: this project does not have an EV (Extended Validation) code signing certificate.

What Is a Code Signing Certificate?

A code signing certificate is used to digitally sign executable files, proving they come from a trusted publisher and have not been tampered with. Windows applies stricter security checks to unsigned programs or those signed with standard certificates.

Differences Between Certificate Types

Certificate Type	Price	SmartScreen Policy
No signature	Free	Blocked immediately, marked as "Unknown Publisher"
Standard OV certificate	Hundreds of dollars/year	Still shows warnings, requires reputation building
EV certificate	Thousands of dollars/year	Passes immediately, no warnings

Programs not signed with an EV certificate are marked as unsafe by default by Windows SmartScreen, and are more likely to be identified as potential threats by antivirus software.

About File Safety

Rest assured, the build process for this project is completely transparent and auditable:

1. Open source code: All source code is hosted on GitHub and can be reviewed by anyone
2. Automated builds: The exe file is automatically built by GitHub Actions workflows on GitHub's servers, with no human intervention throughout the process
3. Traceable builds: Every build has complete logs that can be viewed on the GitHub Actions page
4. Zero-touch release: Developers cannot insert any malicious code during the build process — the entire flow from build completion to release download is fully automated

In simple terms: the exe file never passes through the developer's hands — there is no possibility of "poisoning".

Solutions

Option 1: Add to Trust Whitelist (Recommended for Regular Users)

When Windows Defender blocks the file:

1. Open "Windows Security" → "Virus & threat protection"
2. Click "Protection history"
3. Find the blocked item, click "Actions" → "Allow"

Or add an exclusion before downloading:

1. Open "Windows Security" → "Virus & threat protection" → "Manage settings"
2. Scroll down to find "Exclusions", click "Add or remove exclusions"
3. Add your download directory as an exclusion

Third-party antivirus software: Please add the downloaded file or directory to the trust list in the respective software.

Option 2: Build from Source (Recommended for Developers)

If you still have concerns about pre-compiled binaries, you can clone the source code and compile it locally:

# Clone the repository
git clone https://github.com/owu/wsl-dashboard.git
cd wsl-dashboard

# Build Release version
cargo build --release

# Build artifacts are located in the target/release/ directory

This way, you can fully verify the code you are running.

Option 3: Purchase an EV Certificate (Note for Developers)

Purchasing an EV code signing certificate can fundamentally solve the false positive issue, but faces the following practical challenges:

• High cost: EV certificates cost thousands of dollars per year
• Ongoing expenses: Certificates require annual renewal, creating a long-term financial burden
• Project nature: WSL Dashboard is a non-profit open source project that cannot easily bear this expense

If you would like to support the development of this project, you can donate through the sponsorship channels on the project homepage to help the developer cover operational costs such as certificates.

Summary

• Files are blocked due to the lack of an EV code signing certificate — they are not viruses
• All build artifacts are automatically generated by GitHub Actions — the process is transparent and auditable
• Users can resolve this issue by adding the file to a whitelist or compiling from source
• Purchasing an EV certificate can fundamentally solve the problem, but poses financial challenges for non-profit projects

Thank you for your understanding and support!

[owu]

Huorong Security Team: Reference for False Positive Feedback: #48

[wgetnz]

补充说明：卡巴斯基检测为 Trojan-Downloader.Win32.Agent.xydswv 的具体原因

经过对源码的完整分析，误报并不只是"没有 EV 证书"这一个原因，卡巴斯基的启发式引擎同时命中了以下几个行为特征，合并触发了"下载器"签名：

触发因素

1. 内置过期机制 + 远程获取下载地址

build.rs 中会在编译时写入一个一年后的过期时间戳。程序启动后若检测到已过期，会请求 api2.wslui.com 获取最新版本的下载 URL，然后弹出升级对话框。

这个"程序到期 → 联网获取下载地址 → 展示给用户"的模式，是经典的 Downloader 行为模型，杀毒引擎无法区分"仅展示 URL"和"下载并执行"。

2. 从百度、QQ、163 等第三方网站获取当前时间

为了防止用户修改系统时钟来绕过过期检测，程序会依次对国内常用网站发 HTTP HEAD 请求，从响应的 Date 头读取服务器时间。这个行为对杀毒引擎来说属于"访问与软件功能无关的第三方网站"，会增加可疑评分。

3. 注册登录时以 HIGHEST 权限运行的计划任务

schtasks /Create /SC ONLOGON /RL HIGHEST 是勒索软件/木马常用的持久化手法，杀毒引擎对此高度敏感。

4. 使用 ShellExecuteExW + runas 动态拼接 cmd.exe /c 执行命令

多处需要 UAC 提权的操作通过动态构建命令字符串的方式执行，这与很多恶意软件的提权模式相同。

已做的修复

针对触发因素 1，已将 api2.wslui.com 替换为 GitHub 官方 API：

GET https://api.github.com/repos/owu/wsl-dashboard/releases/latest

版本号、发布日期、下载链接均直接从 GitHub Releases 获取，不再依赖自托管服务器。api.github.com 是全球知名的可信域名，杀毒引擎对其误判概率极低，同时也消除了"自托管 API 被劫持后推送恶意下载链接"的供应链风险。

相关改动：移除 api2.wslui.com，改用 GitHub Releases API

建议后续考虑

• 触发因素 2（时间反篡改）：可以考虑仅在首次检测到异常时才访问外部网站，或改用更常见的 NTP/time.cloudflare.com，减少访问无关域名的频率
• 触发因素 3（计划任务权限）：端口转发同步场景通常不需要 HIGHEST 级别，降为普通管理员权限可以降低误报率

以上供参考，希望对减少误报有帮助。

[wgetnz]

代码变更详情与验证结果

在上条评论的基础上，这里提供完整的代码 diff 和重编译后的验证结果。

---

改动涉及 3 个文件

src/app/constants.rs

-pub const API2_URL: &str = "https://api2.wslui.com";
+pub const GITHUB_API_LATEST_RELEASE: &str = "https://api.github.com/repos/owu/wsl-dashboard/releases/latest";

src/api/client.rs

移除 api2_url 字段及对应的两个请求方法：

 pub struct WslUiClient {
     api1_url: String,
-    api2_url: String,
 }

 impl WslUiClient {
     pub fn new() -> Self {
         Self {
             api1_url: crate::app::API1_URL.to_string(),
-            api2_url: crate::app::API2_URL.to_string(),
         }
     }

-    pub fn request_api2<T>(...) -> ... {
-        self.request_api2_with_timeout(method, uri, body, None)
-    }
-
-    pub fn request_api2_with_timeout<T>(...) -> ... {
-        let url = format!("{}{}", self.api2_url, uri);
-        self.request_url(method, &url, body, timeout_secs)
-    }

src/api/common.rs

wslui_latest_release() 函数从调用私有 API 改为直接请求 GitHub Releases API：

+#[derive(Deserialize)]
+struct GitHubRelease {
+    tag_name: String,
+    published_at: String,
+    html_url: String,
+}

-// Get wslui latest release version
+// Get latest release version from GitHub Releases API
 pub fn wslui_latest_release() -> ReleaseData {
-    let client = WslUiClient::new();
     let fallback = ReleaseData::default();

-    match client.request_api2_with_timeout::<ReleaseData>("GET", "/common/v1/releases/latest", None, Some(10)) {
-        Ok((resp, _)) => {
-            debug!("Obtained latest release from wslui: {:?}", resp.data);
-            resp.data
-        }
-        Err(e) => {
-            error!("Failed to get latest release from wslui: {}. Using fallback data.", e);
-            fallback
+    let result = ureq::get(crate::app::GITHUB_API_LATEST_RELEASE)
+        .timeout(Duration::from_secs(10))
+        .set("User-Agent", "wsldashboard")
+        .set("Accept", "application/vnd.github.v3+json")
+        .call();
+
+    let resp = match result {
+        Ok(r) => r,
+        Err(e) => {
+            error!("Failed to fetch GitHub latest release: {}. Using fallback data.", e);
+            return fallback;
+        }
+    };
+
+    match resp.into_json::<GitHubRelease>() {
+        Ok(release) => {
+            let version = release.tag_name.trim_start_matches('v').to_string();
+            let release_date = if release.published_at.len() >= 10 {
+                release.published_at[..10].to_string()
+            } else {
+                release.published_at
+            };
+            ReleaseData {
+                version,
+                release_date,
+                download_url: release.html_url,  // 直接指向对应 tag 的 Release 页面
+            }
+        }
+        Err(e) => {
+            error!("Failed to parse GitHub release JSON: {}. Using fallback data.", e);
+            fallback
         }
     }
 }

---

行为对比

项目	修改前	修改后
版本检查接口	https://api2.wslui.com/common/v1/releases/latest（私有服务器）	https://api.github.com/repos/owu/wsl-dashboard/releases/latest（GitHub 官方）
下载链接来源	由私有服务器动态返回，内容不可预测	GitHub API 字段 html_url，格式固定为 https://github.com/owu/wsl-dashboard/releases/tag/vX.X.X
供应链风险	若 api2.wslui.com 被劫持，可推送任意下载地址	无此风险，链接完全由 GitHub 控制

---

重编译后验证

基于修改后的源码执行 cargo build --release，编译成功，产物约 21 MB：

Finished `release` profile [optimized] target(s) in 6m 34s

将生成的 wsldashboard.exe 提交卡巴斯基扫描，未再检出 Trojan-Downloader.Win32.Agent.xydswv，查杀结果为安全。

---

如果上游想合并这个修复，可以基于以上 diff 提交 PR；如只是作为参考供下次发版时采用也可以。

[owu]

技术说明与优化记录

感谢 @wgetnz 对安全软件误报原因的分析。

---

1. 设计决策说明

1.1 为什么引入过期时间检测？

• 现状：项目仍处于早期开发阶段，难免存在影响使用的 Bug。
• 目的：通过检测可执行文件的发布时长，在到期后提示用户升级，便于历史版本管理。
• 说明：过期检测仅显示升级提示，不会限制任何功能。
• 后续计划：待项目稳定可靠后，可考虑移除此过期策略。

1.2 为什么使用官方域名接口 api*.wslui.com？

业务背景

由于网络环境差异，部分地区无法流畅访问 GitHub.com 的数据及接口，直接使用 GitHub 接口无法满足所有用户的诉求。

方案演进

版本范围	方案	说明
< 0.8.0	双源分流	根据用户操作系统语言及时区综合判定，返回 github.com 或 gitee.com 的差异化 JSON 配置文件 URL。开发者需手动维护两套仓库。
≥ 0.8.0	统一域名	去除语言及时区判定逻辑，改用项目官方网站二级域名提供 API 接口。部分接口数据由 GitHub Actions 自动生成并发布，降低维护成本。

1.3 为什么临时关闭了 PR？

详见项目讨论：#58

1.4 为什么会使用动态拼接执行命令？

技术背景

随着功能迭代，软件需要执行批量的 PowerShell 命令，部分命令还需要 UAC 提权。以端口转发场景为例，完成一次业务操作需要同时执行多个步骤：添加防火墙规则、配置端口转发映射等，这些操作必须通过命令行拼接一次性完成。为实现批量命令执行，有两种技术方案：

方案	实现方式	优点	缺点
方式 A	生成 .ps1 临时脚本，触发 UAC 时执行该脚本	对开发者友好，直接生成命令写入临时文件；UAC 详情界面仅显示触发了临时脚本文件	对用户而言，UAC 提权窗口如同黑盒执行，无法直观了解本次提权的具体操作
方式 B	直接触发命令行参数拼接，在 UAC 提权对话框中查看详情可见所有待执行命令	对用户透明，随时可审计	对开发者不友好，需要调试兼容性

项目选择

本项目选择方式 B（命令行参数拼接），尽管这增加了开发调试的复杂度，也可能会导致杀毒软件误报，但优先保障用户知情权和可审计性更重要。

---

2. 现有设计保持

2.1 Task Scheduler 执行权限

基于现有参考资料，Task Scheduler 启动任务必须使用管理员模式才能实现端口转发的激活。

2.2 用户体验优化

为确保软件使用者获得完整的操作体验，诸多深度功能需要提权才能完成。提权策略采用按需触发方式，仅在需要管理员模式时才触发 UAC 弹窗。

演进历程：

• 早期版本：尽量避免使用管理员功能
• 近期版本：引入最低权限启动 + 触发式 UAC 机制，满足用户日益增长的功能需求

---

3. 接口优化方案

3.1 版本相关接口优化

场景	优化措施
发布时长过期	不再查询最新版本，直接弹窗提示
自动/手动版本更新检测	使用 v2 新接口，不再返回下载链接，统一使用常量中定义的官网域名 /download

3.2 获取互联网标准时间

历史方案

版本	实现方式
< 0.8.0	直接获取随机互联网知名网站的 HTTP 响应头 Date 字段
= 0.8.0	优先读取项目官网接口；降级方案为获取 HTTP 响应头 Date 字段；若仍无法获取，则回退至获取互联网知名网站的 HTTP 响应头 Date 字段

优化方案（> 0.8.0）

• 优先读取项目官网接口
• 降级方案：获取 HTTP 响应头 Date 字段
• 移除获取互联网知名网站标准时间的降级代码

---

4. 总结

新版本的主要优化方向：

1. 简化接口架构：统一使用官方域名接口，降低维护复杂度
2. 精简降级逻辑：移除不必要的降级方案，提升代码可维护性
3. 保持功能完整：在优化的同时确保核心功能不受影响

[owu]

Technical Notes and Optimization Record

Thanks to @wgetnz for analyzing the cause of security software false positives.

---

1. Design Decision Explanation

1.1 Why introduce expiration time detection?

• Current Status: The project is still in its early development stage, and there are inevitably bugs that affect usability.
• Purpose: By detecting the release duration of executables and prompting users to upgrade upon expiration, historical version management is facilitated.
• Note: Expiration detection only displays an upgrade prompt and does not restrict any functionality.
• Future Plan: Once the project becomes stable and reliable, this expiration policy may be considered for removal.

1.2 Why use the official domain API api*.wslui.com?

Business Background

Due to network environment differences, some regions cannot smoothly access GitHub.com data and APIs. Directly using GitHub APIs cannot meet the needs of all users.

Solution Evolution

Version Range	Solution	Description
< 0.8.0	Dual-source routing	Based on comprehensive determination of user's OS language and timezone, returns differentiated JSON config file URLs from github.com or gitee.com. Developers need to manually maintain two sets of repositories.
≥ 0.8.0	Unified domain	Removed language and timezone determination logic, switched to project official website subdomain for API endpoints. Some API data is automatically generated and published by GitHub Actions, reducing maintenance costs.

1.3 Why were PRs temporarily closed?

See project discussion: #58

1.4 Why use dynamic command concatenation?

Technical Background

As features iterate, the software needs to execute batch PowerShell commands, some of which require UAC privilege escalation. Taking the port forwarding scenario as an example, completing a business operation requires multiple steps to be executed simultaneously: adding firewall rules, configuring port forwarding mappings, etc. These operations must be completed at once through command-line concatenation. To implement batch command execution, there are two technical approaches:

Approach	Implementation	Advantages	Disadvantages
Method A	Generate .ps1 temporary scripts, execute the script when triggering UAC	Developer-friendly, directly generate commands and write to temporary files; UAC details dialog only shows the triggered temporary script file	For users, the UAC privilege escalation window is like a black box execution, unable to intuitively understand the specific operations of this escalation
Method B	Directly trigger command-line parameter concatenation, view details in UAC privilege escalation dialog to see all commands to be executed	Transparent to users, auditable at any time	Not developer-friendly, requires debugging compatibility

Project Choice

This project chooses Method B (command-line parameter concatenation). Although this increases development debugging complexity and may trigger antivirus false positives, prioritizing user right to know and auditability is more important.

---

2. Maintaining Existing Design

2.1 Task Scheduler Execution Permissions

Based on existing reference materials, Task Scheduler startup tasks must use administrator mode to enable port forwarding activation.

2.2 User Experience Optimization

To ensure software users get a complete operational experience, many advanced features require privilege escalation. The escalation strategy uses an on-demand trigger approach, only triggering UAC prompts when administrator mode is needed.

Evolution History:

• Early versions: Tried to avoid using administrator features
• Recent versions: Introduced minimum privilege startup + triggered UAC mechanism to meet users' growing feature requirements

---

3. API Optimization Solutions

3.1 Version-related API Optimization

Scenario	Optimization Measure
Release duration expired	No longer query latest version, directly show popup prompt
Automatic/manual version update detection	Use v2 new API, no longer return download links, uniformly use the official domain /download defined in constants

3.2 Obtaining Internet Standard Time

Historical Solutions

Version	Implementation
< 0.8.0	Directly obtain HTTP response header Date field from random well-known internet websites
= 0.8.0	Prioritize reading project official website API; fallback to obtaining HTTP response header Date field; if still unavailable, fallback to obtaining HTTP response header Date field from well-known internet websites

Optimized Solution (> 0.8.0)

• Prioritize reading project official website API
• Fallback solution: Obtain HTTP response header Date field
• Removed fallback code for obtaining standard time from well-known internet websites

---

4. Summary

The main optimization directions for the new version:

1. Simplify API Architecture: Unify the use of official domain APIs to reduce maintenance complexity
2. Streamline Fallback Logic: Remove unnecessary fallback solutions to improve code maintainability
3. Maintain Complete Functionality: Ensure core functionality is not affected while optimizing

[me9rez]

可以考虑发布到microsoft store来解决签名问题，微软会对microsoft store中的应用签发证书

[xxyk]

我上报给卡巴了，卡巴回复说会排除。。

[owu]

@me9rez 感谢提供方案;
1、上架微软应用商店，该方式我调研过，的确可以帮助签名软件； 但是不足以满足我们的诉求。
1.1 微软签名的可执行文件格式是MSIX/AppX（使用相关工具本地打包为MSIX/AppX格式）， 这是一个沙盒模式的运行环境；例如读写Windows用户目录，注册表操作，任务计划程序，管理员模式，等诸多行为都会受到沙盒模式的限制，从而导致程序不能正常运行。若要强行上架MSIX/AppX，只能维护两套代码，阉割部分高级功能，我不希望上架一个部分功能的软件上去。
1.2 若要上架完整的exe文件格式，那么则需要自己购买 EV代码签名证书，但是这要几千块；因此，软件至今没有上架微软应用商店；

@xxyk 感谢对项目的支持；
火绒团队，我是邮件沟通的，但是不能保证后续所有版本都能在病毒库是白名单； 参考 #48

[me9rez]

可以考虑参考这个项目，https://github.com/electron-userland/electron-windows-msix msix程序似乎支持启用全部权限来突破sandbox限制