mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2026-02-22 21:49:07 -06:00
Code Issues Packages Projects Releases Wiki Activity

improve antivirus documentation

Browse Source 
Co-authored-by: Martin <github@diemattels.at>
This commit is contained in:
kobergj
2023-03-17 12:08:18 +01:00
committed by jkoberg
parent c550390d82
commit fc4ba499b1
4 changed files with 61 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/services/antivirus/_index.md
View File

@@ -10,8 +10,45 @@ geekdocCollapseSection: true
## Abstract
wating for readme to be approved
## Table of Contents
{{< toc-tree >}}
## Antivirus Service
The `antivirus` service is responsible for scanning files for viruses.
### Configuration
#### Antivirus Scanner Type
The antivirus service currently supports [icap](https://tools.ietf.org/html/rfc3507) and [clamav](http://www.clamav.net/index.html) as antivirus scanners. The `ANTIVIRUS_SCANNER_TYPE` environment variable is used to select the scanner. The detailed configuration for each scanner heavily depends on the scanner type selected. See the environment variables for more details.
- For `icap`, only scanners using the `X-Infection-Found` header are currently supported.
- For `clamav` only local sockets can currently be configured.
#### Maximum Scan size
Several factors can make it necessary to limit the maximum filesize the antivirus service will use for scanning. Use the `ANTIVIRUS_MAX_SCAN_SIZE` environment variable to scan only a given amount of bytes. Obviously it is recommended to scan the whole file, but several factors like scanner type and version, bandwith, performance issues, etc. might make a limit necessary.
#### Infected File Handling
The antivirus service allows three different ways of handling infected files. Those can be set via the `ANTIVIRUS_INFECTED_FILE_HANDLING` environment variable:
- `delete`: (default): Infected files will be deleted immediately, further postprocessing is cancelled.
- `abort`: (advanced option): Infected files will be kept, further postprocessing is cancelled. Files can be manually retrieved and inspected by an admin. To identify the file for further investigation, the antivirus service logs the abort/infected state including the file ID. The file is located in the `storage/users/uploads` folder of the ocis data directory and persists until it is manually deleted by the admin via the [Manage Unfinished Uploads](https://doc.owncloud.com/ocis/next/deployment/services/s-list/storage-users.html#manage-unfinished-uploads) command.
- `continue`: (obviously not recommended): Infected files will be marked via metadata as infected but postprocessing continues normally. Note: Infected Files are moved to their final destination and therefore not prevented from download which includes the risk of spreading viruses.
In all cases, a log entry is added declaring the infection and handling method and a notification via the `userlog` service sent.
#### Scanner Inaccessability
In case a scanner is not accessible by the antivirus service like a network outage, service outage or hardware outage, the antivirus service uses the `abort` case for further processing, independent of the actual setting made. In any case, an error is logged noting the inaccessability of the scanner used.
### Operation Modes
The antivirus service can scan files during `postprocessing`. `on demand` scanning is currently not available and might be added in a future release.
#### Postprocessing
The antivirus service will scan files during postprocessing. It listens for a postprocessing step called `"virusscan"`. This step can be added in the environment variable `POSTPROCESSING_STEPS`. Read the documentation of the [postprocessing service](https://github.com/owncloud/ocis/tree/master/services/postprocessing) for more details.

3
docs/services/antivirus/configuration.md
View File

@@ -10,6 +10,3 @@ geekdocCollapseSection: true
## Example YAML Config
{{< include file="services/_includes/antivirus.yaml" language="yaml" >}}
{{< include file="services/_includes/antivirus_configvars.md" >}}

36
services/antivirus/README.md
View File

@@ -1,36 +1,38 @@
# Antivirus Service
The `antivirus` service is responsible for scanning files for viruses
The `antivirus` service is responsible for scanning files for viruses.
## Configuration
### Antivirus Scanner Type
The antivirus service currently supports `icap` and `clamav` as antivirus scanners. Use `ANTIVIRUS_SCANNER_TYPE` to configure this.
Note that configuration depends heavily on chosen antivirus scanner. See Enviroment Variable descriptions for details.
The antivirus service currently supports [icap](https://tools.ietf.org/html/rfc3507) and [clamav](http://www.clamav.net/index.html) as antivirus scanners. The `ANTIVIRUS_SCANNER_TYPE` environment variable is used to select the scanner. The detailed configuration for each scanner heavily depends on the scanner type selected. See the environment variables for more details.
- For `icap`, only scanners using the `X-Infection-Found` header are currently supported.
- For `clamav` only local sockets can currently be configured.
### Maximum Scan size
Since several factors might make need necessary to limit the maximum filesize the `antivirus` service has an option to set a max scan size.
Use `ANTIVIRUS_MAX_SCAN_SIZE` to scan only that amount of bytes of a file. Obviously it is recommended to set this as high as possible, but several factors (scanner type and version, bandwith and performance issues, ...) might force to set this to a certain filesize.
Several factors can make it necessary to limit the maximum filesize the antivirus service will use for scanning. Use the `ANTIVIRUS_MAX_SCAN_SIZE` environment variable to scan only a given amount of bytes. Obviously it is recommended to scan the whole file, but several factors like scanner type and version, bandwith, performance issues, etc. might make a limit necessary.
### Infected File Handling
The `antivirus` service allows three different ways of handling infected files. Those can be set via the `ANTIVIRUS_INFECTED_FILE_HANDLING` envvar:
- `delete` (default): Infected files will be deleted immediately. Further postprocessing is cancelled.
- `abort`: Infected files will be kept. Further postprocessing is cancelled. Files can be manually retrieved and inspected by an admin. (Advanced option)
- `continue`: Infected files will be marked as infected but postprocessing continues normally. Note: Infected Files are not prevented from download. Risk of spreading viruses. (Obviously not recommended)
The antivirus service allows three different ways of handling infected files. Those can be set via the `ANTIVIRUS_INFECTED_FILE_HANDLING` environment variable:
- `delete`: (default): Infected files will be deleted immediately, further postprocessing is cancelled.
- `abort`: (advanced option): Infected files will be kept, further postprocessing is cancelled. Files can be manually retrieved and inspected by an admin. To identify the file for further investigation, the antivirus service logs the abort/infected state including the file ID. The file is located in the `storage/users/uploads` folder of the ocis data directory and persists until it is manually deleted by the admin via the [Manage Unfinished Uploads](https://doc.owncloud.com/ocis/next/deployment/services/s-list/storage-users.html#manage-unfinished-uploads) command.
- `continue`: (obviously not recommended): Infected files will be marked via metadata as infected but postprocessing continues normally. Note: Infected Files are moved to their final destination and therefore not prevented from download which includes the risk of spreading viruses.
In all cases, a log entry is added declaring the infection and handling method and a notification via the `userlog` service sent.
### Scanner Inaccessability
In case a scanner is not accessible by the antivirus service like a network outage, service outage or hardware outage, the antivirus service uses the `abort` case for further processing, independent of the actual setting made. In any case, an error is logged noting the inaccessability of the scanner used.
## Operation Modes
The `antivirus` service can scan files during postprocessing. `on demand` scanning will be added in the future.
The antivirus service can scan files during `postprocessing`. `on demand` scanning is currently not available and might be added in a future release.
### Postprocessing
Note: Needs to be configured via the [postprocessing service](https://github.com/owncloud/ocis/tree/master/services/postprocessing)
The `antivirus` service will scan files during postprocessing. It listens for a postprocessing step called `"virusscan"`
### On Demand
On demand scanning is currently not supported
The antivirus service will scan files during postprocessing. It listens for a postprocessing step called `"virusscan"`. This step can be added in the environment variable `POSTPROCESSING_STEPS`. Read the documentation of the [postprocessing service](https://github.com/owncloud/ocis/tree/master/services/postprocessing) for more details.

6
services/antivirus/pkg/config/config.go
View File

@@ -13,7 +13,7 @@ type Config struct {
Service Service `yaml:"-"`
InfectedFileHandling string `yaml:"infected-file-handling" env:"ANTIVIRUS_INFECTED_FILE_HANDLING" desc:"Defines the behaviour when a virus has been found. Options are: 'delete', 'continue' and 'abort '. Delete will delete the file. Continue will mark the file as infected but continues further processing. Abort will keep the file in the upload folder for further admin inspection and will not move it to its target space."`
InfectedFileHandling string `yaml:"infected-file-handling" env:"ANTIVIRUS_INFECTED_FILE_HANDLING" desc:"Defines the behaviour when a virus has been found. Supported options are: 'delete', 'continue' and 'abort '. Delete will delete the file. Continue will mark the file as infected but continues further processing. Abort will keep the file in the uploads folder for further admin inspection and will not move it to its final destination."`
Events Events
Scanner Scanner
MaxScanSize string `yaml:"max-scan-size" env:"ANTIVIRUS_MAX_SCAN_SIZE" desc:"The maximum scan size the virusscanner can handle. Only that much bytes of a file will be scanned. 0 means unlimited and is the default. Usable common abbreviations: [KB, KiB, GB, GiB, TB, TiB, PB, PiB, EB, EiB], example: 2GB."`
@@ -53,7 +53,7 @@ type Events struct {
// Scanner provides configuration options for the antivirusscanner
type Scanner struct {
Type string `yaml:"type" env:"ANTIVIRUS_SCANNER_TYPE" desc:"The scanner to use. Must be one of: clamav, icap"`
Type string `yaml:"type" env:"ANTIVIRUS_SCANNER_TYPE" desc:"The antivirus scanner to use. Supported values are 'clamav' and 'icap'."`
ClamAV ClamAV // only if Type == clamav
ICAP ICAP // only if Type == icap
@@ -68,5 +68,5 @@ type ClamAV struct {
type ICAP struct {
Timeout int64 `yaml:"timeout" env:"ANTIVIRUS_ICAP_TIMEOUT" desc:"Timeout for the ICAP client."`
URL string `yaml:"url" env:"ANTIVIRUS_ICAP_URL" desc:"URL of the ICAP server."`
Service string `yaml:"service" env:"ANTIVIRUS_ICAP_SERVICE" desc:"Name of the ICAP server."`
Service string `yaml:"service" env:"ANTIVIRUS_ICAP_SERVICE" desc:"The name of the ICAP service."`
}