You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Welcome to the G DATA Verdict-as-a-Service (VaaS) integration for Nextcloud. This project aims to provide an additional layer of security to your Nextcloud instance by enabling automatic and manual scanning of files for malicious content.
13
22
14
-
VaaS scans files and tags them with either `Clean`or `Malicious` verdicts, providing users with immediate feedback about the safety of their files. Unscanned files are tagged as `Unscanned` and queued for background scanning.
23
+
VaaS scans files and tags them with either `Clean`, `Malicious`or `PUP (Potentially Unwanted Program)` verdicts, providing users with immediate feedback about the safety of their files. Unscanned files are tagged as `Unscanned` and queued for background scanning.
15
24
16
25
Verdict-as-a-Service is a cloud-based service provided by G DATA CyberDefense AG. It is designed to work on your own infrastructure as a self-hosted variant, ensuring a high level of security and privacy. If you are interested in using VaaS on-premise or have any questions, please contact [email protected] for more information or check out the [repository of our helm chart](https://github.com/GDATASoftwareAG/vaas-helm) for self-hosting the VaaS backend.
17
26
@@ -46,13 +55,21 @@ The support and maintenance of the versions of this app is based on the official
46
55
47
56
## Settings
48
57
49
-
The app offers a variety of settings to customize the behavior of the antivirus. The settings can be found in the Nextcloud admin settings page under the "Verdict-as-a-Service" section.
58
+
The app offers a variety of settings to customize the behavior of the antivirus. The settings can be found in the Nextcloud admin settings page under the "G DATA Antivirus" section.
50
59
51
-
-**Authentication Method:** If you have created your own account on https://vaas.gdata.de/login, select 'Resource Owner Password Flow' here. If you have received access data from your provider (Client ID and Secret), select 'Client Credentials Flow'. You can simply leave the other fields empty.
60
+
-**Authentication Method:** If you have created your own account on https://vaas.gdata.de/login, select 'Resource Owner Password Flow' here. If you have received access data from your provider (Client ID and Secret), select 'Client Credentials Flow'.
52
61
-**Scan only this:** Equivalent to an allowlist. If the values here are separated by commas, e.g. "Documents, .exe, Scan", only those containing the corresponding values in the path are scanned. In this example, *.exe files and the contents of the Documents/ and Scan/ folders would be scanned.
53
62
-**Do not scan this:** Equivalent to a blocklist. If there are values separated by commas, e.g. "Documents, .exe, Scan", these are not scanned.time until all files are scanned. Recommended are values between 10 and 100.
63
+
-**Quarantine folder:** If an existing file is found to be malicious, it is moved to this folder in the user's home directory. If the folder does not exist, it is created automatically. If you do not want to use a quarantine folder, leave this field empty.
64
+
-**Notify mails:** If an email address is entered here (or multiple comma seperated), a notification is sent to this address when a user uploads a file that is found to be malicious.
65
+
-**Maximum scan size:** Files larger than this size (in MB) are not scanned and tagged as "Won't Scan". Recommended values are between 10 and 300 MB.
66
+
-**Timeout:** The time (in seconds) the app waits for a response from the VaaS backend before considering the scan as failed. Recommended values are between 10 and 300 seconds. Please note: If the timeout is set too short, it will restrict the scanning of large files, which take a little longer.
67
+
-**Cache:** If this option is disabled, each file is always scanned again and no results are cached.
68
+
-**Hash lookup:** During a hash lookup, the SHA256 checksum is transmitted to the G DATA Cloud before the scan to check whether a result is already available, thereby saving unnecessary network traffic, resource load, and time.
54
69
-**Advanced Settings:** The token endpoint and the VaaS URL determine the scan backend. By default, the public G DATA Cloud is used for scanning. If the VaaS backend is self-hosted, the corresponding values for the self-hosted instance must be entered here.
55
70
71
+
You can always hover over the settings name for more information.
72
+
56
73
## Self-hosting the scanning backend (VaaS)
57
74
58
75
If you want to self-host the scanning backend, take a look at the [repository of our helm chart](https://github.com/GDATASoftwareAG/vaas-helm).
@@ -104,43 +121,88 @@ The following commands are available for managing and interacting with the G DAT
104
121
105
122
## Setting up a development environment
106
123
107
-
Before you start, make sure you have the following tools installed:
124
+
This project ships Make targets that set up and run a full Nextcloud dev instance in Docker.
125
+
126
+
The easiest way to get started is to use the Devcontainer with VSCode. It has all prerequisites installed and automatically mounts the app into the container.
127
+
128
+
But you can also set up the environment manually on your host machine:
129
+
130
+
### Prerequisites
131
+
132
+
Install these locally (or ensure your devcontainer provides them):
- php-scoper (only for make appstore - if you want to execute bats tests or want the production app, not development version)
114
141
115
-
Also, you need to make an ```npm install```, ```npm run build``` and ```composer install``` to install dependencies and build the node modules.
116
-
You always need to do this before you start the development environment or copy the app to your Nextcloud instance manually.
117
-
If you copy the app directory manually in your Nextcloud instance you have to rename the folder to ```gdatavaas```.
142
+
Note: The Makefile will download composer.phar if Composer isn’t available, but it still requires a local PHP CLI to run it.
118
143
119
-
### Linux
120
-
* Make sure you have the tools mentioned above installed.
121
-
* With the provided `./install.sh` script you can install the dependencies and build the node modules.
144
+
### Quick start: run Nextcloud with the app mounted
122
145
123
-
### `install.sh` Script
146
+
```bash
147
+
# From the repository root
148
+
make local
149
+
```
150
+
151
+
What this does:
152
+
- Builds backend and frontend assets (make build → make composer + make npm).
153
+
- Starts a Nextcloud dev container on http://localhost:8080 and bind-mounts this app into /var/www/html/apps-extra/gdatavaas.
154
+
- Installs PHP dependencies on the host so local tooling works.
124
155
125
-
The `install.sh` script is used to set up and configure a Nextcloud instance with the G DATA VaaS app and Smtp4Dev. Below is an explanation of the script's features:
156
+
After the container is up, open Nextcloud at http://localhost:8080 and enable the app via the Apps UI:
157
+
- Find `G DATA Antivirus` in your apps and click `Enable`.
158
+
- Important: Enable only. Do not upgrade to the app store version. That overrides your local code in the container.
126
159
127
-
1.**Environment Variables in `.env-local`**:
128
-
-`CLIENT_ID`: Sets the client ID for the G DATA VaaS app.
129
-
-`CLIENT_SECRET`: Sets the client secret for the G DATA VaaS app.
160
+
### Day-to-day workflow
130
161
131
-
If you want to use the ResourceOwnerPasswordFlow you have to set these settings manually in the Nextcloud settings after the installation.
162
+
- Edit PHP (server) code: changes are picked up immediately by the container via the bind mount; just refresh the page.
163
+
- Edit frontend (JS/CSS/Vue): rebuild assets explicitly (no hot reload) and refresh the page without cache (CTRL + F5):
132
164
133
-
2.**Specify the Nextcloud server version**:
134
-
- The Nextcloud version defaults to 30.0.0
135
-
- You can start the `install.sh` script with the desired Nextcloud version as an argument, e.g. `./install.sh 30`
165
+
```bash
166
+
make npm
167
+
```
136
168
137
-
3.**Smtp4Dev**:
138
-
- Starts a container with the Smtp4Dev tool to capture emails sent by Nextcloud.
139
-
- The tool is accessible at `http://localhost:8081` and can be used to view emails sent by Nextcloud.
169
+
### Available Make targets
170
+
171
+
- make build
172
+
- Fetches PHP dependencies and builds frontend assets.
173
+
- make composer
174
+
- Installs/upgrades PHP dependencies. If Composer isn’t installed, a local composer.phar is fetched and used.
175
+
- make npm
176
+
- Installs Node dependencies and builds JS/CSS bundles. Re-run this whenever you change frontend code.
177
+
- make oc
178
+
- Clones the Nextcloud server into ./nextcloud-server (used for local development that requires private OC namespaces).
179
+
- make local
180
+
- Rebuilds the app and runs a Nextcloud dev container on http://localhost:8080 with this app mounted. Safe to re-run; it replaces any existing container named nextcloud-container.
181
+
- make clean
182
+
- Removes the build/ directory.
183
+
- make distclean
184
+
- Also removes vendor/, node_modules/, js/node_modules/, nextcloud-server/, composer.lock, etc.
185
+
- make unittests
186
+
- Runs PHP unit tests via ./vendor/bin/phpunit using tests/unittests/bootstrap.php. Installs Composer deps first.
187
+
- make bats
188
+
- Spins up a complete environment using Docker Compose and runs end-to-end Bats tests from tests/bats with the production build of the app.
189
+
- Requirements: Bats installed locally and two environment variables set: CLIENT_ID and CLIENT_SECRET (valid VaaS credentials).
190
+
- make appstore
191
+
- Builds a distributable tarball at build/artifacts/gdatavaas.tar.gz. Intended for releases; requires php-scoper available in PATH.
192
+
193
+
### Stopping and restarting
194
+
195
+
- Stop/remove the dev container manually if needed:
196
+
197
+
```bash
198
+
docker stop nextcloud-container ||true
199
+
```
140
200
141
-
4.**Additional Install Script**:
142
-
- Sources `install.local` if it exists for any additional installation steps.
201
+
- Re-run make local to rebuild and restart the environment.
143
202
203
+
Notes:
204
+
- SMTP testing (smtp4dev) is available when using the Docker Compose-based test setup; it listens on http://localhost:8081. The simple make local flow runs a single Nextcloud container on port 8080.
205
+
- The helper script scripts/run-app.sh orchestrates CI and test flows; for local development, stick to the Make targets above.
144
206
145
207
### Useful commands
146
208
@@ -155,8 +217,9 @@ The `install.sh` script is used to set up and configure a Nextcloud instance wit
155
217
156
218
### Smtp4Dev
157
219
158
-
For more information about Smtp4Dev, please refer to the [official README](https://github.com/rnwood/smtp4dev/blob/master/README.md).
220
+
When developing locally, SMTP4Dev is launched on port 8081 to simulate sending emails through the app.
159
221
222
+
For more information about Smtp4Dev, please refer to the [official README](https://github.com/rnwood/smtp4dev/blob/master/README.md).
0 commit comments