Orchard Core Antivirus 模块实战指南：基于 ClamAV 的上传文件前置扫描与拒绝机制

CMS后端Web框架【免费下载链接】OrchardCoreOrchard Core is an open-source modular and multi-tenant application framework built with ASP.NET Core, and a content management system (CMS) built on top of that framework.项目地址https://gitcode.com/gh_mirrors/or/OrchardCore点击查看免费下载导读本指南聚焦 Orchard Core 的OrchardCore.Antivirus模块讲解如何通过 ClamAVclamd守护进程在上传文件被永久存储或导入之前完成恶意软件扫描。你将掌握 ClamAV 功能的配置方式JSON 与环境变量两种写法、扫描失败时的拒绝语义、底层 TCP 连接复用机制以及该模块如何通过IFileEventHandler融入 Orchard Core 共享的上传安全管线从而在不修改媒体与部署流程的前提下为上传面统一加装病毒扫描。模块总览先扫描后存储OrchardCore.Antivirus模块的设计目标非常明确在 Orchard Core 永久存储或导入上传文件之前先对文件内容进行检查。模块的声明位于 Manifest.cs其中定义了一个名为OrchardCore.Antivirus.ClamAV、分类为Security的功能Feature模块名称ClamAV Antivirus Scanner功能 IDOrchardCore.Antivirus.ClamAV功能描述Scans files with ClamAV before Orchard Core stores them.在 Orchard Core 存储文件之前使用 ClamAV 扫描文件模块采用「功能按需启用」的架构Startup.cs中的基类Startup不做任何服务注册真正生效的是带[Feature(OrchardCore.Antivirus.ClamAV)]特性的ClamAVStartup。这意味着只有显式启用该功能后扫描器才会被装配进容器未启用时模块对上传流程零开销。相关注册逻辑见 Startup.cs。ClamAV 功能OrchardCore.Antivirus.ClamAV启用该功能后模块会通过 TCP 与一个clamd服务通信对上传文件执行实时病毒扫描。其核心行为有三条全部在模块文档中有明确定义并在源码中得到印证恶意软件检出即拒绝扫描发现病毒时上传在存储之前就被拒绝。连接 / 超时 / 协议失败同样拒绝上传即使扫描器不可达、响应超时或返回了无法识别的响应上传同样会被中止——这是一种“默认拒绝”fail-closed的安全语义。连接按配置复用TCP 客户端按配置键缓存复用避免每次扫描都新建连接降低频繁上传场景下的握手开销。从源码结构看ClamAV 功能由 4 个核心类型构成位于 src/OrchardCore.Modules/OrchardCore.Antivirus/ClamAV 目录类型职责ClamAvOptions承载连接配置主机、端口、超时ClamAvConnection封装 TCP 连接与INSTREAM扫描协议ClamAvConnectionFactory按配置键缓存并复用连接ClamAvFileEventHandler作为IFileEventHandler参与上传管线扫描器如何接入上传流程IFileEventHandlerClamAV 扫描器并不是被某个控制器或服务直接调用的而是以IFileEventHandler的形式注册进 Orchard Core 的文件事件处理抽象。模块文档明确指出这样做的价值在于上传校验可以在存储之前完成而无需把媒体和部署流程耦合到某个扫描器专属的接口上。关键链路如下ClamAvFileEventHandler实现IFileEventHandler定义于 IFileEventHandler.cs并在 Startup.cs 中以单例注册。上传发生时FileCreationService会先调用所有处理器的CreatingAsync()再执行存储存储成功后才调用CreatedAsync()。当ClamAV返回失败的FileCreatingResult时FileCreationService会中止上传文件不会被写入任何永久位置。也就是说ClamAV 复用的是 Orchard Core 内置的共享安全管线FileCreationService而非各自实现一套扫描入口。关于该管线的完整用法——包括如何在自定义上传流程中调用FileCreationService、在存储前中止被拒绝的文件——请参阅权威指南 File Upload Security。已覆盖的上传面Notes模块文档的 Notes 部分给出了当前被审计覆盖的上传面共两大类媒体上传media uploads因媒体上传流经DefaultMediaFileStore而DefaultMediaFileStore内部会经过FileCreationService所以媒体文件在存储前必然被扫描。部署包导入deployment package imports含本地与远程部署包zip/json上传会在 Orchard Core 将文件写入临时归档位置之前完成扫描。这解释了为什么该模块无需改动媒体与部署模块本身即可让两处上传面同时获得扫描能力。配置 ClamAV 连接ClamAV 的连接配置来自应用配置appsettings.json或环境变量。模块文档特别强调设置键保持为OrchardCore_Antivirus_ClamAV以维持兼容性。JSON 配置{ OrchardCore: { OrchardCore_Antivirus_ClamAV: { Host: localhost, Port: 3310, ConnectTimeoutSeconds: 5, TransferTimeoutSeconds: 30 } } }环境变量配置同一组设置也可以用环境变量提供注意 .NET 配置的分层命名法双下划线__表示层级分隔OrchardCore__Antivirus_ClamAV__Hostlocalhost OrchardCore__Antivirus_ClamAV__Port3310 OrchardCore__Antivirus_ClamAV__ConnectTimeoutSeconds5 OrchardCore__Antivirus_ClamAV__TransferTimeoutSeconds30配置项与默认值以上配置项在 ClamAVOptions.cs 中有完整定义其绑定节为Antivirus_ClamAVStartup通过_configuration.GetSection(ClamAvOptions.ConfigSection)绑定即OrchardCore根节下的OrchardCore_Antivirus_ClamAV配置项类型默认值含义Hoststring无必填clamd服务所在主机名或 IPPortint3310clamd监听端口ClamAV 默认端口即 3310ConnectTimeoutSecondsint5TCP 建连超时秒TransferTimeoutSecondsint30单次扫描传输/响应的超时秒ClamAvFileEventHandler.ValidateOptions()见 ClamAvFileEventHandler.cs会在每次扫描前校验配置合法性Host缺失空或纯空白→ 抛出AntivirusScanningException“enabled but the host setting is missing”Port不在165535→ 抛出配置非法异常两个超时值必须大于 0否则同样拒绝扫描。这意味着只要功能被启用配置不完整或非法时上传会被拒绝而不会静默跳过扫描。使用步骤按照模块文档的 Usage 章节启用扫描只需三步配置 ClamAV 设置按上文 JSON 或环境变量方式提供Host、Port及超时参数。启用功能在站点管理中启用ClamAV Antivirus Scanner功能OrchardCore.Antivirus.ClamAV。确保clamd实例可达在配置的Host:Port上运行可用的clamd守护进程。模块文档同时给出了一个重要警告如果在没有有效 ClamAV 连接的情况下启用该功能上传会被拒绝直到扫描器能够验证文件为止。也就是说该模块采用**默认拒绝fail-closed**策略扫描器不可达、超时或协议异常都会导致上传失败而不是“放行后补扫”。这是与“先存储、后扫描”方案的本质区别——恶意文件在任何情况下都不会被持久化。底层原理TCP 连接复用与 INSTREAM 扫描协议为了让“连接复用”与“超时失败”这两个行为更可信这里结合源码展开其底层实现。连接复用ClamAvConnectionFactoryClamAvConnectionFactory.cs 使用静态的ConcurrentDictionarystring, LazyClamAvConnection按配置键缓存连接var key ${options.Host}:{options.Port}:{options.ConnectTimeoutSeconds}:{options.TransferTimeoutSeconds}; return s_connections.GetOrAdd(key, _ new LazyClamAvConnection(...)).Value;配置键由主机、端口、两个超时值共同决定不同配置对应不同连接互不串扰LazyT保证同一配置下并发首次调用只创建一个连接工厂通过IHostApplicationLifetime.ApplicationStopped注册释放回调应用停止时统一清理所有缓存连接见Release()同时用引用计数s_refCount协调多租户多个 shell下的创建与释放避免提前释放仍被其他租户使用的连接。这正对应文档中“ClamAV connection is reused per configuration to avoid creating a new TCP client for every scan”的描述。扫描协议ClamAvConnection.ScanAsyncClamAvConnection.cs 实现了与clamd的INSTREAM流式扫描协议以SemaphoreSlim串行化扫描避免并发扫描共用同一 TCP 流导致数据交错若连接未建立则先建连建连受ConnectTimeoutSeconds约束通过CancellationTokenSource.CancelAfter实现向clamd写入nINSTREAM\n命令以 81920 字节的缓冲区循环读取上传流每块前附加 4 字节网络字节序IPAddress.HostToNetworkOrder的长度前缀后写入网络流写入 4 个零字节表示流结束new byte[sizeof(int)]读取响应直到换行符返回 ASCII 字符串如stream: OK或stream: Signature FOUND。若传输过程中发生IOException、SocketException、OperationCanceledException超时或ObjectDisposedException连接会被重置ResetConnection()后重新抛出保证下次扫描不会复用已损坏的 TCP 连接。响应判定与拒绝结果ClamAvFileEventHandler.TryCreateFailureResult()见 ClamAvFileEventHandler.cs对响应字符串做三种分支响应为stream: OK→ 返回 null即扫描通过继续存储流程响应以FOUND结尾 → 解析出病毒签名取: 之后、去掉尾部FOUND的部分将流指针复位后返回FileCreatingResult.Failed(...)错误消息形如“The uploaded file {fileName} was rejected because ClamAV detected {signature}”其他任何响应 → 视为协议异常抛出AntivirusScanningException“unexpected response”。扫描流处理与非可寻址流CreatingAsync()对输入流做了适配见 ClamAvFileEventHandler.cs若流可寻址CanSeek则把Position复位到 0 后直接扫描若流不可寻址如某些网络上传流则通过ITempDirectoryProvider落盘为临时文件流FileOptions.DeleteOnClose关闭即删除扫描完成后供后续存储使用超时、Socket 异常、IO 异常分别被捕获并包装为AntivirusScanningException且会及时释放临时流。AntivirusScanningException继承自FileStoreException见 AntivirusScanningException.cs因此它可以沿着文件存储的异常体系向上传播被上传入口统一处理。常见问题与注意事项为什么启用功能后没有配置也能上传失败因为ValidateOptions()与 fail-closed 语义只要功能启用配置缺失、端口越界、超时非正数或clamd不可达都会让CreatingAsync返回失败或抛异常上传在存储前即被中止。连接超时与传输超时的区别ConnectTimeoutSeconds只约束 TCP 建连阶段TransferTimeoutSeconds同时作用于整个扫描传输过程发送数据、接收响应以及 TCP 的SendTimeout/ReceiveTimeout见EnsureConnectedAsync。多租户环境连接工厂通过静态缓存 引用计数在多个 shell 间共享连接应用进程停止时统一释放。自定义上传流程如果业务代码自己接收文件并写入持久化存储绕过IMediaFileStore应调用FileCreationService.CreateAsync()触发同一管线并对失败的FileCreatingResult中止上传完整代码示例见 File Upload Security。小结OrchardCore.Antivirus模块以“先扫描、后存储”为原则通过IFileEventHandler将 ClamAV 扫描器无缝接入 Orchard Core 的共享上传安全管线使媒体上传与部署包导入本地/远程在上传落盘前自动获得恶意软件检测。配置仅需Host、Port与两个超时参数启用OrchardCore.Antivirus.ClamAV功能并确保clamd可达即可生效一旦启用任何检测失败、连接失败或超时都会拒绝上传保证恶意文件不会被持久化。对于需要自定义上传入口的开发者建议同时阅读 File Upload Security 以正确接入该管线。赞分享CMS后端Web框架【免费下载链接】OrchardCoreOrchard Core is an open-source modular and multi-tenant application framework built with ASP.NET Core, and a content management system (CMS) built on top of that framework.项目地址https://gitcode.com/gh_mirrors/or/OrchardCore点击查看免费下载相关推荐OpenProject 附件管理实战大小限制、上传白名单与 ClamAV 病毒扫描配置OpenProject 附件管理实战大小限制、上传白名单与 ClamAV 病毒扫描配置 在 OpenProject 中工作包Work Package允许后端前端项目管理企业应用协同办公Yii 2 文件上传实战指南基于 UploadedFile 与 FileValidator 构建安全可靠的上传机制Yii 2 文件上传实战指南基于 UploadedFile 与 FileValidator 构建安全可靠的上传机制 文件上传是 Web 开发中的高频需求也是后端Web框架Yii 2 文件上传实战指南基于 UploadedFile、ActiveForm 与 FileValidator 构建安全可靠的上传机制Yii 2 文件上传实战指南基于 UploadedFile、ActiveForm 与 FileValidator 构建安全可靠的上传机制 Yii 2 的文件上后端Web框架上一篇终极NTFS读写解决方案Mac用户必备的免费开源工具完整指南下一篇ComfyUI-BrushNet完全指南三步掌握AI图像精准修复与智能编辑技术创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考