Difference between revisions of "Protect:OX Protect"

(added middleware API)
(update for 2.0)
Line 97: Line 97:
 
OX Protect is available with the following backend packages:
 
OX Protect is available with the following backend packages:
  
* open-xchange-protect
+
* open-xchange-protect-core
 +
* open-xchange-protect-web
 +
* open-xchange-protect-web-ui
 
* open-xchange-notificationcenter
 
* open-xchange-notificationcenter
  
Line 111: Line 113:
  
 
  $ apt-get update
 
  $ apt-get update
  $ apt-get install open-xchange-protect open-xchange-notificationcenter
+
  $ apt-get install open-xchange-protect-core open-xchange-protect-web open-xchange-protect-web-ui open-xchange-notificationcenter
  
 
==== RHEL 7 and CentOS 7 ====
 
==== RHEL 7 and CentOS 7 ====
Line 127: Line 129:
 
and run
 
and run
  
  $ yum install open-xchange-protect open-xchange-notificationcenter
+
  $ yum install open-xchange-protect-core open-xchange-protect-web open-xchange-protect-web-ui open-xchange-notificationcenter
  
 
== Configuration ==
 
== Configuration ==
Line 177: Line 179:
 
Configuration files are read from /etc/protect. Prepare the required yaml files in /etc/protect from the commented samples in this directory provided by the installation.
 
Configuration files are read from /etc/protect. Prepare the required yaml files in /etc/protect from the commented samples in this directory provided by the installation.
  
==== protect-backend.yaml ====
+
==== protect-core-backend.yaml ====
  
The OX Protect Middleware is based on several backend components. Access to these is configured in protect-backend.yaml.
+
The OX Protect Middleware Core is based on several backend components. Access to these is configured in protect-core-backend.yaml.
  
 
Mandatory entries are "db" for information about the used database and "pdns" for addressing the PowerDNS platform.
 
Mandatory entries are "db" for information about the used database and "pdns" for addressing the PowerDNS platform.
  
Optional are "notify" (required for email, SMS, Mobile Push notification functionality provided by the NC) and identity (required for authentication with an identity server).
+
Optional are "notify" (required for email, SMS, Mobile Push notification functionality provided by the NC) and the location of the PDNS security reporting service.
  
==== protect-server.yaml ====
+
==== protect-core-server.yaml ====
  
OX Protect Middleware parameters are configured in protect-server.yaml. Most have reasonable defaults or work unchanged as provided in the sample file.
+
OX Protect Middleware Core parameters are configured in protect-core-server.yaml. Most have reasonable defaults or work unchanged as provided in the sample file.
  
 
Mandatory entries that need to be edited are
 
Mandatory entries that need to be edited are
Line 198: Line 200:
  
 
If not changed the authentication method used is "password" which utilizes the internal database.
 
If not changed the authentication method used is "password" which utilizes the internal database.
 +
 +
==== protect-web-backend.yaml ====
 +
 +
OX Protect Middleware Web parameters describing the used services are maintained in protect-web-backend.yaml. The DB persists session data.
 +
The location of Middleware Core has to be provided.
 +
 +
Optional is the configuration of authentication with an identity server.
 +
 +
==== protect-web-server.yaml ====
 +
 +
OX Protect Middleware Web parameters configure the location and behaviour of the UI.
 +
This includes the public server name and URL path. Also session properties including lifetime is specified here.
 +
 +
If Two-Factor Authentication is used parameters like token-lifetime and sender address can be set. Otherwise defaults and notificationcenter settings apply.
  
 
==== logging ====
 
==== logging ====

Revision as of 12:09, 15 October 2019

OX Protect

Meet OX Protect

It protects traditional digital equipment as well as IoT devices against malware, phishing and other harmful online content. At the same time, it gives users easy to configure, flexible control over which sites each family member can visit and allows users to restrict access to certain content at different times, like off-time or bedtime.

Additional privacy features
OX Protect provides your subscribers with parental control options to create a safe browsing experience for their entire family. Access to categories of websites with unsuitable content such as gambling, violence, and more can be defined and managed per user, profile, group and device easily.

Restrict access to the internet at different times
Time windows help parents restrict temporary access to several categories of websites. Off-time and bedtime can be configured as well as Netflix and social media access.

Secure devices with malware protection
OX Protect also secures from malware, phishing, and malicious domains based on lookups in white- and blacklists. It protects your subscribers’ devices from being infected or hacked.

Real-time notifications on malware and access attempts
Immediate notifications about infected devices and attempts to access malicious websites let subscribers rest and parents keep calm while their kids are exploring the internet.

Web portal and mobile apps to configure and manage family filters
OX Protect comes with a white labeled web control panel and a brandable mobile app for iOS and Android. Users can configure and manage their very own protection including specific user settings and device filters for single profiles and groups of multiple family members or devices at once.

No additional hardware needed
Unlike other solutions in the market, OX Protect does not require additional end-user hardware. Malware protection and all parental control options are applied on a DNS level.

What’s New in General and Feature Overviews

Open-Xchange now provides more detailed overviews, data sheet and product guide, relating to new product release. These can be found at https://www.open-xchange.com/portfolio/whats-new/

Additionaly, a more detailed overview of OX Protect can be found at https://software.open-xchange.com/products/protect/doc/Whitepaper_OX_Protect_1_0_0.pdf

Requirements

Requirement System / Platform / User Interface
   
OX Protect in General PDNS Platform version 2.5.x or higher is required.
Required Database engine: MySQL or PostgreSQL
Supported Platforms: Debian Stretch (9) and RHEL 7
Notification Center Required Database engine: MySQL or PostgreSQL 10 or higher
Supported Platforms: Debian Stretch (9) and RHEL 7

OX Protect Component Description

OX Protect Middleware

The OX Protect Middleware provides a REST API for customer applications and GUIs such as Self-care portals or mobile apps. This API is end-user focused and includes support for end user configuration, authentication/authorization, etc. The API can be used to integrate with customer OSS/BSS systems, existing mobile apps, self-care portals, and customer care systems to interact with the solution.

The API supports OAUTH2 for authorization, enabling easy embedding of the functionality into existing apps or services.

This API is also used by Open-Xchange’s own mobile apps and web UI.

Notification Center

OX Protect includes support for notifications in its Notification Center. The main characteristics of this component is the modular setup that is fully API-based to allow customers to choose to utilize for example their existing services. This allows deployment in combination with existing components on the Telco’s infrastructure.

The notification center will distribute the end-user messages according to the triggers, instructions, and parameters it receives from other components, e.g. PowerDNS platform.

  • Its main task is to:
    • Distributes/pushes messages to end-user
    • Decides channel, priority, destination, user settings
    • Store notifications for later use (log-files, investigation, retrieval for UI display)
  • Supports Push Notifications to the OX Protect Mobile Apps, as well as Email, SMS, and other channels, for which it requires custom integration.

OX Protect Client Apps

OX Protect includes iOS and Android apps that integrate through the OX Protect Middleware REST APIs. The apps include:

  • User Centric control apps
    • For Apple iOS and Android
    • Centralized End-User Notifications and Control
  • Configuration management
    • Control Filtering settings for household and individual devices
    • Real-time Permissions
  • Push Notifications
    • Controllable Push Notifications of suspicious events

Branding for Partners and Customers

With OX Protect it is possible for customers and partners to request the addition, and change, of a variety of branding elements in the app. This includes changing colors, graphical assets and icons.

For more information about branding, the cost of this service and what can be done please contact Open-Xchange Sales.

Download & Installation

PowerDNS Platform

OX Protect - the Middlware - functionality is based on the PowerDNS platform. PDNS Platform version 2.5.x or higher is required. For more information about PowerDNS, download and installation, please contact Open-Xchange.

OX Protect Middleware and OX Notification Center

OX Protect is available with the following backend packages:

  • open-xchange-protect-core
  • open-xchange-protect-web
  • open-xchange-protect-web-ui
  • open-xchange-notificationcenter

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

Debian GNU/Linux 9.0

Add the following repositories to your Open-Xchange apt configuration:

deb https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/protect/stable/protect/DebianStretch/

and run

$ apt-get update
$ apt-get install open-xchange-protect-core open-xchange-protect-web open-xchange-protect-web-ui open-xchange-notificationcenter

RHEL 7 and CentOS 7

Add the following repositories to your Open-Xchange yum configuration:

[open-xchange-protect]
name=open-xchange-protect
baseurl= https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/protect/stable/protect/RHEL7/
gpgkey= https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum install open-xchange-protect-core open-xchange-protect-web open-xchange-protect-web-ui open-xchange-notificationcenter

Configuration

Preparation of PowerDNS Platform

OX Protect needs some preparation of the PowerDNS Platform with data about platforms, categories and mapping of the corresponding codes (depending on the categorization provider).

The related files are available in the directory ~protect/conf in an OX Protect installation.

File Purpose
   
OXP_oxfeed_classification.csv Classification Codes including Platforms and Uncategorized
OXP_categories.json Categories with the mapped codes and Filter Presets
OXP_policies.json Policy Rules adding Malware Protection, Pause Internet, Offtimes, Platforms, Safesearch

Here are short example command lines showing how the configuration is shown resp. applied with manage.py. For a detailed description see the PowerDNS Platform documentation and the tool's help output.

[root@protect-adm-01 data]# pwd
/usr/share/pdns-platform-filter-admin/data
[root@protect-adm-01 data]# ../bin/manage.py import_classification_codes OXP_oxfeed_classification.csv
[root@protect-adm-01 data]# ../bin/manage.py export_category_schema
[root@protect-adm-01 data]# ../bin/manage.py import_category_schema --delete-other OXP_categories.json
[root@protect-adm-01 data]# ../bin/manage.py dumpdata --format=json --indent=2 --natural-foreign --natural-primary policies lists
[root@protect-adm-01 data]# ../bin/manage.py loaddata --format=json --indent=2 --natural-foreign --natural-primary policies lists

The above mentioned policy rules will also attach categorization provider codes to the malware protection policy rule ("security-codes").

Database

OX Protect works with MySQL or PostgreSQL (version 10 and later) as database engine. PostgreSQL is recommended as this is a requirement of PowerDNS and the PowerDNS Platform. Ensure that the database server is up and running and credentials are available for the OX Protect configuration.

For both components - OX Protect Middleware and Notification Center - the database with schema and other elements will be created initially if necessary. Detailed information about Notification Center access to the database with reduced privileges are available from the sample configuration file.

Middleware

Configuration files are read from /etc/protect. Prepare the required yaml files in /etc/protect from the commented samples in this directory provided by the installation.

protect-core-backend.yaml

The OX Protect Middleware Core is based on several backend components. Access to these is configured in protect-core-backend.yaml.

Mandatory entries are "db" for information about the used database and "pdns" for addressing the PowerDNS platform.

Optional are "notify" (required for email, SMS, Mobile Push notification functionality provided by the NC) and the location of the PDNS security reporting service.

protect-core-server.yaml

OX Protect Middleware Core parameters are configured in protect-core-server.yaml. Most have reasonable defaults or work unchanged as provided in the sample file.

Mandatory entries that need to be edited are

"secret" for signing the session ID cookie

"provisioning" / "token" to allow access to the provisioning API of the OX Protect Middleware

"api" / "token" to allow access to the privileged access to the OX Protect User Account API

If not changed the authentication method used is "password" which utilizes the internal database.

protect-web-backend.yaml

OX Protect Middleware Web parameters describing the used services are maintained in protect-web-backend.yaml. The DB persists session data. The location of Middleware Core has to be provided.

Optional is the configuration of authentication with an identity server.

protect-web-server.yaml

OX Protect Middleware Web parameters configure the location and behaviour of the UI. This includes the public server name and URL path. Also session properties including lifetime is specified here.

If Two-Factor Authentication is used parameters like token-lifetime and sender address can be set. Otherwise defaults and notificationcenter settings apply.

logging

With the default configuration OX Protect Middleware logs in files ~protect/.pm2/pm2.log resp. -protect/.pm2/logs/main-out.log and main-error.log.

For management of these logfiles a sample logrotate file can be found at ~protect/conf/protect.logrotate for installation in /etc/logrotate.d

One can change the behaviour so that logging data is sent to stdout/stderr which is managed by systemd journal. In the file ~protect/conf/open-xchange-protect.service, change the line

ExecStart=/usr/share/open-xchange-protect/node_modules/pm2/bin/pm2 start /usr/share/open-xchange-protect/app/main.js

to

ExecStart=/usr/share/open-xchange-protect/node_modules/pm2/bin/pm2 start /usr/share/open-xchange-protect/app/main.js --output /dev/stdout --error /dev/stderr

Notification Center

Notification Center reads its configuration from files in /etc/notificationcenter

Main Configuration File notificationcenter.yaml

A sample file is provided as notificationcenter.yaml.sample. Mandatory changes have to be applied to the following sections.

database (with type, host, application username and application password)

security / tokenlist (name, value to grant access to the NC API)

notification / middlewareUrl (base URL used to generate deep links in outgoing messages)

mail (MTA host and port, From: header for outgoing emails)

smartphone (iOS and Android certificates for push notifications)

sms (sipgate access data for outgoing SMS)

Outgoing channels that are not configured are ignored.

Reload of the configuration

Some of the configuration entries are reloadable. You can use curl to trigger the reload of the configuration:

curl -X POST http://notificationcenter.example.com/notificationcenter/api/v1/refresh -H "x-api-key: <token>"

Logging

Logging of the Notification Center is configured in logback-spring.xml (customize as described in https://docs.spring.io/spring-boot/docs/current/reference/html/howto-logging.html)

Customization of Message Templates

Templates for messages sent out via email, SMS and Mobile Push are located in /etc/notificationcenter/notificationtemplates.

In templates placeholders can be used as listed in notificationcenter.yaml.sample (see also the description of FreeMarker Template Language (FTL) and it's expressions).

Metrics

Runtime metrics of the Notification Center are provided by JMX via jolokia. curl can be used to submit POST requests to the http://notificationcenter.example.com/notificationcenter/api/v1/jolokia endpoint.

The x-api-key header with a valid token has to be added to the request. Example:

curl -X POST http://notificationcenter.example.com/notificationcenter/api/v1/jolokia -H "x-api-key: <token>" -d '{"mbean" : "metrics:name=com.openxchange.notificationcenter.notification.db.insert.counter", "type" : "read"}'
mbean Example response Description
     
metrics:name=com.openxchange.notificationcenter.notification.db.insert.counter
  {  
  "request":{
  "mbean":"metrics:name=com.openxchange.notificationcenter.notification.db.insert.counter",
  "type":"read"
  },
  "value":{
     "Count":0
  },
  "timestamp":1529065664,
  "status":200
  }
The Notification Center writes the received notifications asynchronously to the database. If the Notification Center receives more notifications than it can write to the database the count of this metric will increase. This value indicates how many notifications were not written to the database yet.
java.lang:type=OperatingSystem
  {
  "request":{
     "mbean":"java.lang:type=OperatingSystem",
     "type":"read"
  },
  "value":{
     "OpenFileDescriptorCount":307,
     "CommittedVirtualMemorySize":3764346880,
     "FreePhysicalMemorySize":354066432,
     "SystemLoadAverage":0.04,
     "Arch":"amd64",
     "ProcessCpuLoad":0.0065645514223194755,
     "FreeSwapSpaceSize":0,
     "TotalPhysicalMemorySize":3974090752,
     "Name":"Linux",
     "ObjectName":{
        "objectName":"java.lang:type=OperatingSystem"
     },
     "TotalSwapSpaceSize":0,
     "ProcessCpuTime":111790000000,
     "MaxFileDescriptorCount":65536,
     "SystemCpuLoad":0.018964259664478483,
     "Version":"3.10.0-862.3.2.el7.x86_64",
     "AvailableProcessors":2
  },
  "timestamp":1529065489,
  "status":200
  }
You can see different information about the host where the Notification Center is installed.
metrics:name=com.openxchange.notificationcenter.notifications.storeToDb
  {
  "request":{
     "mbean":"metrics:name=com.openxchange.notificationcenter.notifications.storeToDb",
     "type":"read"
  },
  "value":{
     "Mean":0.0,
     "StdDev":0.0,
     "75thPercentile":0.0,
     "98thPercentile":0.0,
     "RateUnit":"events\/second",
     "95thPercentile":0.0,
     "99thPercentile":0.0,
     "Max":0.0,
     "Count":0,
     "FiveMinuteRate":0.0,
     "50thPercentile":0.0,
     "MeanRate":0.0,
     "Min":0.0,
     "OneMinuteRate":0.0,
     "DurationUnit":"milliseconds",
     "999thPercentile":0.0,
     "FifteenMinuteRate":0.0
  },
  "timestamp":1529091380,
  "status":200
  }
Information about how long it takes to store a block of received notifications to the database.
metrics:name=com.openxchange.notificationcenter.outboundchannel.android
  {
  "request":{
     "mbean":"metrics:name=com.openxchange.notificationcenter.outboundchannel.android",
     "type":"read"
  },
  "value":{
     "Mean":0.0,
     "StdDev":0.0,
     "75thPercentile":0.0,
     "98thPercentile":0.0,
     "RateUnit":"events\/second",
     "95thPercentile":0.0,
     "99thPercentile":0.0,
     "Max":0.0,
     "Count":0,
     "FiveMinuteRate":0.0,
     "50thPercentile":0.0,
     "MeanRate":0.0,
     "Min":0.0,
     "OneMinuteRate":0.0,
     "DurationUnit":"milliseconds",
     "999thPercentile":0.0,
     "FifteenMinuteRate":0.0
  },
  "timestamp":1529091625,
  "status":200
  }
Information about how long it takes to send a push notification to an Android device. If this time increases the Notification Center has problems to deliver push notifications for Android.
metrics:name=com.openxchange.notificationcenter.outboundchannel.ios
  {
  "request":{
     "mbean":"metrics:name=com.openxchange.notificationcenter.outboundchannel.ios",
     "type":"read"
  },
  "value":{
     "Mean":0.0,
     "StdDev":0.0,
     "75thPercentile":0.0,
     "98thPercentile":0.0,
     "RateUnit":"events\/second",
     "95thPercentile":0.0,
     "99thPercentile":0.0,
     "Max":0.0,
     "Count":0,
     "FiveMinuteRate":0.0,
     "50thPercentile":0.0,
     "MeanRate":0.0,
     "Min":0.0,
     "OneMinuteRate":0.0,
     "DurationUnit":"milliseconds",
     "999thPercentile":0.0,
     "FifteenMinuteRate":0.0
  },
  "timestamp":1529091625,
  "status":200
  }
Information about how long it takes to send a push notification to an iOS device. If this time increases the Notification Center has problems to deliver push notifications for iOS.
metrics:name=com.openxchange.notificationcenter.outboundchannel.sms
  {
  "request":{
     "mbean":"metrics:name=com.openxchange.notificationcenter.outboundchannel.sms",
     "type":"read"
  },
  "value":{
     "Mean":0.0,
     "StdDev":0.0,
     "75thPercentile":0.0,
     "98thPercentile":0.0,
     "RateUnit":"events\/second",
     "95thPercentile":0.0,
     "99thPercentile":0.0,
     "Max":0.0,
     "Count":0,
     "FiveMinuteRate":0.0,
     "50thPercentile":0.0,
     "MeanRate":0.0,
     "Min":0.0,
     "OneMinuteRate":0.0,
     "DurationUnit":"milliseconds",
     "999thPercentile":0.0,
     "FifteenMinuteRate":0.0
  },
  "timestamp":1529091625,
  "status":200
  }
Information about how long it takes to send a SMS notification. If this time increases the Notification Center has problems to deliver push notifications via SMS.
metrics:name=com.openxchange.notificationcenter.outboundchannel.email
  {
  "request":{
     "mbean":"metrics:name=com.openxchange.notificationcenter.outboundchannel.email",
     "type":"read"
  },
  "value":{
     "Mean":0.0,
     "StdDev":0.0,
     "75thPercentile":0.0,
     "98thPercentile":0.0,
     "RateUnit":"events\/second",
     "95thPercentile":0.0,
     "99thPercentile":0.0,
     "Max":0.0,
     "Count":0,
     "FiveMinuteRate":0.0,
     "50thPercentile":0.0,
     "MeanRate":0.0,
     "Min":0.0,
     "OneMinuteRate":0.0,
     "DurationUnit":"milliseconds",
     "999thPercentile":0.0,
     "FifteenMinuteRate":0.0
  },
  "timestamp":1529091625,
  "status":200
  }
Information about how long it takes to send an email. If this time increases the Notification Center has problems to deliver emails.

Loadbalancer

OX Protect MIddleware and the Notification Center can run behind a proxy / loadbalander.

Some limit the size the of requests. For example for nginx increase it from the default 1MB to 5MB to allow larger profile avatars.

client_max_body_size 1m; # default 1mb

Provisioning

After successful installation the system needs to be provisioned with user accounts.

The full description of the OX Protect APIs are available as part of the product and on the Open-Xchange website

To create a user in OX Protect (Middleware and subsystems PowerDNS platform and Notification Center) and set the initial password one can use:

curl -H "Authorization: Token <provisioning token> -H "Content-Type: application/json" -X PUT -d "{\"user_id\":\"anewuser\",\"user_id_pdns\":\"anewuser\",\"user_id_notify\":\"anewuser\"}"
 http://middleware.example.com/protect/provisioning/v1/user?provision_pdns=1&provision_notify=1
curl -H "Authorization: Token <api token>" -H "Content-Type: application/json" -X PATCH -d "{\"password\":\"secret\"}"
http://middleware.example.com/protect/api/v1/user/anewuser/settings/password