BW-Tech File Firewall #

The file_firewall app blocks file access according to rules you define: by IP range, group, device, time of day, file size, file type, tag, or type of request. A request is blocked if it meets all conditions of a rule group. The app is meant for admins who have to restrict file access to, for example, the company network, office hours, or certain devices.

Requirements #

Installation #

1. Request the API key from BW-Tech GmbH.
2. Open Market from the app menu in the top left. In the left column under Settings, click Add API Key.
3. Paste the key into the "Your personal API Key" field and click Save. The Market checks the key with the Marketplace and reloads the catalog. If the key was accepted, the entry in the left column now reads Edit API Key. If it still reads Add API Key, the key was rejected and not saved.
4. Go to the "BW-Tech File Firewall" app and click Install.

On the command line:

sudo -u www-data php8.4 occ config:app:set market key --value '<KEY>'
sudo -u www-data php8.4 occ market:install file_firewall

market:install downloads, installs, and enables the app. If the app is already present but disabled, run sudo -u www-data php8.4 occ app:enable file_firewall.

Notes on the key:

• On the command line, the key ends up in your shell history. With the Audit Log app enabled, the command including the key is also written to the audit log.
• Alternatively, put the key into config/config.php: 'marketplace.key' => '<KEY>',. This entry takes precedence, and the key can then no longer be changed in the web interface.
• After config:app:set, the Market keeps working with the cached catalog without the key for up to 30 minutes. During that time, market:install reports the app as unknown ("Unknown app (file_firewall)"). Click Clear cache in the Market or wait the 30 minutes.

During installation and after every update, the app takes over the rules of an earlier firewall installation, including its logging setting, if there are any: from firewall.rules in config/config.php and from the app values of the app ID firewall. If file_firewall already has rule groups of its own, it takes over nothing and reports how many groups it skipped. Compare them by hand with occ firewall:list.

Configuration #

The rules are under Settings → Admin → Security, in the "BW-Tech File Firewall" section.

1. Add Group creates a "New Rule Group". Give it a name. Blocked users see this name in the error message.
2. Choose the condition type, operator, and value. Add Condition adds more conditions. A request is blocked only if all of them apply.
3. For a new rule, check "Test mode (log only)". Matching requests then only go to the log and to the "Test hits" counter.
4. Click Save Rules. Changes take effect only then, including deleted groups and conditions.

Each rule group has the "Enabled" switch, test mode, and the "Hits" counter. "Test hits" appears once there are any; "Last hit" (time in UTC) shows when you hover over the counter. Reset statistics asks for confirmation and then sets all counters to zero right away, without Save Rules.

"Logging" controls what the app writes to the server log:

The app always logs matches in test mode, whatever this option says.

Conditions #

About the request time: the default "Server time" is UTC in owncloud.online. For office hours, pick a time zone such as Europe/Berlin. A time window may cross midnight, for example 18:00 to 06:00.

Write regular expressions with delimiters (/secret/i) or without (secret\.txt$, then matched case-insensitively).

Assign your own branded clients to a device type in config/config.php. The app compares the pattern with the user agent, ignoring case. A * at the start means "ends with", a * at the end means "starts with", and a * at both ends means "contains"; without *, the whole user agent must match. The client name usually sits in the middle of the user agent, so *name* is normally the right choice. You find the exact user agent in the web server's access log.

'firewall.branded_clients' => [
    '*mycompany-android*' => 'android_branded',
    '*mycompany-ios*' => 'ios_branded',
    '*mycompany-desktop*' => 'desktop_branded',
],

The "User Device" condition then also offers "… (Branded)", "All branded clients", and "All non-branded clients".

Command line #

# show the rules (logging, groups, conditions, counters)
sudo -u www-data php8.4 occ firewall:list
sudo -u www-data php8.4 occ firewall:list --output=json

# block access from outside the company network
sudo -u www-data php8.4 occ firewall:add-rule "Company network only" \
  -c "ip_range_ipv4:is_not:10.0.0.0/8"

# block uploads of the group external after hours, in test mode first
sudo -u www-data php8.4 occ firewall:add-rule "External after hours" \
  -c "user_group:is:external" \
  -c "request_type:is:upload" \
  -c "time:is:18:00-06:00@Europe/Berlin" \
  --test-mode

# delete the first rule group in the list (index 0)
sudo -u www-data php8.4 occ firewall:delete-rule 0

# back up the rules and import them again
sudo -u www-data php8.4 occ firewall:export /tmp/firewall-rules.json
sudo -u www-data php8.4 occ firewall:import /tmp/firewall-rules.json
sudo -u www-data php8.4 occ firewall:import --replace /tmp/firewall-rules.json

Write a condition as type:operator:value. On the command line the operators are is, is_not, matches, not_matches, contains, not_contains, less, greater_equal, begins_with, not_begins_with, ends_with, and not_ends_with. --disabled creates a group that is switched off.

Write a time window as HH:MM-HH:MM, optionally followed by @<timezone>. The app silently drops an unknown time zone, and UTC applies. For regex, append the target field after a |, for example -c 'regex:is:secret|request_url'; a | inside the expression itself therefore works only in the web interface. The target fields are user_group, user_agent, ip_range_ipv4, ip_range_ipv6, request_url, and file_mimetype.

firewall:list numbers the groups from 1 ("Rule Group 1"), firewall:delete-rule counts from 0. To delete the first group in the list, run firewall:delete-rule 0. The command does not ask for confirmation.

firewall:import appends the groups from the file; --replace replaces all existing ones. If the file contains a logLevel, the import also sets the logging option. The web server user must be able to read the file. Do not keep exports in the installation directory.

REST API #

For scripts, there is an OCS interface under /ocs/v2.php/apps/file_firewall/api/v1. It requires an admin account with Basic Auth and the OCS-APIREQUEST: true header. If the account uses two-factor authentication, log in with an app password.

curl -u admin -H "OCS-APIREQUEST: true" \
  "https://cloud.example.com/ocs/v2.php/apps/file_firewall/api/v1/rules?format=json"

POST /rules replaces the complete list. To add a group, read the rules first and send them back together with the new group.

Usage #

Blocked access over WebDAV, that is from the desktop client, the mobile apps, or a mapped drive, ends with HTTP 403 and the message Blocked by BW-Tech File Firewall: <rule group name>. The web interface shows the same message when an upload is blocked. A blocked public link also returns HTTP 403. A blocked read outside WebDAV returns the error of the app that reads the file, for example HTTP 404 for a preview or HTTP 400 in the text editor.

Limits and notes #

• Admins are never blocked. Test rules with a regular account.
• Command line and cron are exempt.
• Login. The app blocks file access, not the login. It checks requests without a login only for public links.
• OCS calls themselves are not blocked. A rule of type api applies only to file access during such a call. Creating a share over OCS, for example, still works.
• Errors during evaluation. If evaluating a rule fails with an error, the app lets the request through. Test new rules in test mode and read the log.
• System tags are detected only for WebDAV access by logged-in accounts. For ZIP downloads in the web interface (folders, multiple selection) and for public links, the "System File Tag" condition does not apply.
• IP rules behind a reverse proxy need trusted_proxies; otherwise every request appears to come from the proxy's address.
• Rule group names are visible to blocked users in the error message. Choose names that can be shown to users.
• Storage. Rules, the logging option, and the counters are stored as app values in the database. A database backup contains them; occ firewall:export also writes them to a JSON file.