From 3d9636584588bbadf604948bf7c7b547972ca5c6 Mon Sep 17 00:00:00 2001 From: liss-bot Date: Sun, 3 Apr 2022 01:32:15 +0000 Subject: [PATCH] Auto Publish new pages --- configuring.md | 6 +- credits.md | 20 +-- privacy.md | 377 ++++++++++++++++++++++++++++----------------- showcase.md | 21 +++ troubleshooting.md | 7 + widgets.md | 17 ++ 6 files changed, 293 insertions(+), 155 deletions(-) diff --git a/configuring.md b/configuring.md index 71356c3..16e3bcc 100644 --- a/configuring.md +++ b/configuring.md @@ -77,6 +77,7 @@ The following file provides a reference of all supported configuration options. --- | --- | --- | --- **`title`** | `string` | Required | The text to display on the link button **`path`** | `string` | Required | The URL to navigate to when clicked. Can be relative (e.g. `/about`) or absolute (e.g. `https://example.com` or `http://192.168.1.1`) +**`target`** | `string` | _Optional_ | The opening method (external links only). Can be either `newtab`, `sametab`, `top` or `parent`. Defaults to `newtab` **[⬆️ Back to Top](#configuring)** @@ -91,7 +92,8 @@ The following file provides a reference of all supported configuration options. **`statusCheckInterval`** | `boolean` | _Optional_ | The number of seconds between checks. If set to `0` then service will only be checked on initial page load, which is usually the desired functionality. If value is less than `10` you may experience a hit in performance. Defaults to `0` **`webSearch`** | `object` | _Optional_ | Configuration options for the web search feature, set your default search engine, opening method or disable web search. See [`webSearch`](#appconfigwebsearch-optional) **`backgroundImg`** | `string` | _Optional_ | Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load -**`enableFontAwesome`** | `boolean` | _Optional_ | Where `true` is enabled, if left blank font-awesome will be enabled only if required by 1 or more icons +**`enableFontAwesome`** | `boolean` | _Optional_ | If set to `true` font-awesome will be loaded, if set to `false` they will not be. if left blank font-awesome will be enabled only if required by 1 or more icons +**`enableMaterialDesignIcons`** | `boolean` | _Optional_ | If set to `true` mdi icons will be loaded, if set to `false` they will not be. Where `true` is enabled, if left blank material design icons will be enabled only if required by 1 or more icons **`fontAwesomeKey`** | `string` | _Optional_ | If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g. `13014ae648`) **`faviconApi`** | `enum` | _Optional_ | Only applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to `local` to do this locally, without using an API. Services running locally will use this option always. Available options are: `local`, `faviconkit`, `iconhorse`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/icons.md#favicons) for more info **`auth`** | `object` | _Optional_ | All settings relating to user authentication. See [`auth`](#appconfigauth-optional) @@ -206,6 +208,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`statusCheckHeaders`** | `object` | _Optional_ | If you're endpoint requires any specific headers for the status checking, then define them here **`statusCheckAllowInsecure`** | `boolean` | _Optional_ | By default, any request to insecure content will be blocked. Setting this option to `true` will disable the `rejectUnauthorized` option, enabling you to ping non-HTTPS services for the current item. Defaults to `false` **`statusCheckAcceptCodes`** | `string` | _Optional_ | If your service's response code is anything other than 2xx, then you can opt to specify an alternative success code. E.g. if you expect your server to return 403, but still want the status indicator to be green, set this value to `403` +**`statusCheckMaxRedirects`** | `number` | _Optional_ | If your service redirects to another page, and you would like status checks to follow redirects, then specify the maximum number of redirects here. Defaults to `0` / will not follow redirects **`color`** | `string` | _Optional_ | An optional color for the text and font-awesome icon to be displayed in. Note that this will override the current theme and so may not display well **`backgroundColor`** | `string` | _Optional_ | An optional background fill color for the that given item. Again, this will override the current theme and so might not display well against the background **`provider`** | `string` | _Optional_ | The name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name @@ -220,6 +223,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`options`** | `object` | _Optional_ | Some widgets accept either optional or required additional options. Again, see the [Widget Docs](/docs/widgets.md) for full list of options **`updateInterval`** | `number` | _Optional_ | You can keep a widget constantly updated by specifying an update interval, in seconds. See [Continuous Updates Docs](/docs/widgets.md#continuous-updates) for more info **`useProxy`** | `boolean` | _Optional_ | Some widgets make API requests to services that are not CORS-enabled. For these instances, you will need to route requests through a proxy, Dashy has a built in CORS-proxy, which you can use by setting this option to `true`. Defaults to `false`. See the [Proxying Requests Docs](/docs/widgets.md#proxying-requests) for more info +**`timeout`** | `number` | _Optional_ | Request timeout in milliseconds, defaults to ½ a second (`500`) **[⬆️ Back to Top](#configuring)** diff --git a/credits.md b/credits.md index 4198e29..0fcdaf5 100644 --- a/credits.md +++ b/credits.md @@ -32,28 +32,21 @@ Vlad Timofeev - - - aghybris -
- Aghybris - - Byolock
Byolock - - + hugalafutro
Hugalafutro - + + KierenConnell @@ -61,6 +54,13 @@ Kieren Connell + + + gdepountis +
+ gdepountis + + ratty222 diff --git a/privacy.md b/privacy.md index a4ab105..f2e0223 100644 --- a/privacy.md +++ b/privacy.md @@ -1,144 +1,233 @@ -# Privacy & Security - -Dashy was built with privacy in mind. -Self-hosting your own apps and services is a great way to protect yourself from the mass data collection employed by big tech companies, and Dashy was designed to keep your local services organized and accessible from a single place. - -It's fully open source, and I've tried to keep to code as clear and thoroughly documented as possible, which will make it easy for you to understand exactly how it works, and what goes on behind the scenes. - -For privacy and security tips, check out another project of mine: **[Personal Security Checklist](https://github.com/Lissy93/personal-security-checklist)**. - ---- - -## External Requests -By default, Dashy will not make any external requests, unless you configure it to. Some features (which are off by default) do require internat access, and this section outlines those features, the services used, and links to their privacy policies. - -### Font Awesome -If either any of your sections or items are using font-awesome icons, then these will be fetched directly from font-awesome on page load. See the [Font Awesome Privacy Policy](https://fontawesome.com/privacy) for more info. - -### Favicon Fetching -If an item's icon is set to `favicon`, then it will be auto-fetched from the corresponding URL. Since not all websites have their icon located at `/favicon.ico`, and if they do, it's often very low resolution (like `16 x 16 px`). Therefore, the default behavior is for Dashy to check if the URL is public, and if so will use an API to fetch the favicon. For self-hosted services, the favion will be fetched from the default path, and no external requests will be made. - -The default favicon API is [Favicon Kit](https://faviconkit.com/), but this can be changed by setting `appConfig.faviconApi` to an alternate source (`google`, `clearbit`, `webmasterapi` and `allesedv` are supported). If you do not want to use any API, then you can set this property to `local`, and the favicon will be fetched from the default path. For hosted services, this will still incur an external request. - -### Generative Icons -If an item has the icon set to `generative`, then an external request it made to [Dice Bear](https://dicebear.com/) to fetch the uniquely generated icon. The URL of a given service is used as the key for generating the icon, but it is first hashed and encoded for basic privacy. For more info, please reference the [Dicebear Privacy Policy](https://avatars.dicebear.com/legal/privacy-policy) - - -### Other Icons -Section icons, item icons and app icons are able to accept a URL to a raw image, if the image is hosted online then an external request will be made. To avoid the need to make external requests for icon assets, you can either use a self-hosted CDN, or store your images within `./public/item-icons` (which can be mounted as a volume if you're using Docker). - -### Web Assets -By default, all assets required by Dashy come bundled within the source, and so no external requests are made. If you add an additional font, which is imported from a CDN, then that will incur an external request. The same applies for other web assets, like external images, scripts or styles. - -### Status Checking -The status check util will ping your services directly, and does not rely on any third party. If you are checking the uptime status of a public/ hosted application, then please refer to that services privacy policy. For all self-hosted services, requests happen locally within your network, and are not external. - -### Update Checks -When the application loads, it checks for updates. The results of which are displayed in the config menu of the UI. This was implemented because using a very outdated version of Dashy may have unfixed issues. Your version is fetched from the source (local request), but the latest version is fetched from GitHub, which is an external request. This can be disabled by setting `appConfig.disableUpdateChecks: true` - -### Anonymous Error Reporting -Error reporting is disabled by default, and no data will ever be sent without your explicit consent. In fact, the error tracking method will not even be imported unless you have actively enabled it. [Sentry](https://github.com/getsentry/sentry) is used for this, it's an open source error tracking and performance monitoring tool, which is used to identify any issues which occur in the production app (if you enable it). - -The crash report includes the file or line of code that triggered the error, and a 2-layer deep stack trace. Reoccurring errors will also include the following user information: OS type (Mac, Windows, Linux, Android or iOS) and browser type (Firefox, Chrome, IE, Safari). Data scrubbing is enabled. IP address will not be stored. If any potentially identifiable data ever finds its way into a crash report, it will be automatically and permanently erased. All statistics collected are anonomized and stored securely, and ae automatically deleted after 14 days. For more about privacy and security, see the [Sentry Docs](https://sentry.io/security/). - -Enabling anonymous error reporting helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. Error reporting is activated by setting `appConfig.enableErrorReporting: true`. - -If you need to monitor bugs yourself, then you can [self-host your own Sentry Server](https://develop.sentry.dev/self-hosted/), and use it by setting `appConfig.sentryDsn` to your Sentry instances [Data Source Name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/), then just enable error reporting in Dashy. - -### Widgets - ---- - -## Local Storage -In order for user preferences to be persisted between sessions, certain data needs to be stored in the browsers local storage. No personal info is kept here, none of this data can be accessed by other domains, and no data is ever sent to any server without your prior consent. -You can view your browsers session storage by opening up the dev tools (F12) --> Application --> Storage. - -The following section outlines all data that is stored in the browsers, as cookies or local storage. - -#### Cookies -- `AUTH_TOKEN` - A unique token, generated from a hash of users credentials, to verify they are authenticated. Only used when auth is enabled - -#### Local Storage -- `LANGUAGE` - The locale to show app text in -- `HIDE_WELCOME_BANNER` - Set to true once user dismissed welcome message, so that it's not shown again -- `LAYOUT_ORIENTATION` - Preferred section layout, either horizontal, vertical or auto -- `COLLAPSE_STATE` - Remembers which sections are collapsed -- `ICON_SIZE` - Size of items, either small, medium or large -- `THEME` - Users applied theme -- `CUSTOM_COLORS` - Any color modifications made to a given theme -- `BACKUP_ID` - If a backup has been made, the ID is stored here -- `BACKUP_HASH` - A unique hash of the previous backups meta data -- `HIDE_SETTINGS` - Lets user hide or show the settings menu -- `USERNAME` - If user logged in, store username. Only used to show welcome message, not used for auth -- `CONF_SECTIONS` - Array of sections, only used when user applies changes locally -- `PAGE_INFO` - Config page info, only used when user applies changes locally -- `APP_CONFIG` - App config, only used when user applies changes locally -- `MOST_USED` - If smart sort is used to order items by most used, store open count -- `LAST_USED` - If smart sort is used to order items by last used, store timestamps - ---- - -## Dependencies -As with most web projects, Dashy relies on several [dependencies](https://github.com/Lissy93/dashy/blob/master/docs/credits.md#dependencies-). For links to each, and a breakdown of their licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md). - -Dependencies can introduce security vulnerabilities, but since all these packages are open source any issues are usually very quickly spotted. Dashy is using Snyk for dependency security monitoring, and you can see [the latest report here](https://snyk.io/test/github/lissy93/dashy). If any issue is detected by Snyk, a note about it will appear at the top of the Reamde, and will usually be fixed within 48 hours. - -Note that packages listed under `devDependencies` section are only used for building the project, and are not included in the production environment. - ---- - -## Securing your Environment -Running your self-hosted applications in individual, containerized environments (such as containers or VMs) helps keep them isolated, and prevent an exploit in one service effecting another. - -There is very little complexity involved with Dashy, and therefore the attack surface is reasonably small, but it is still important to follow best practices and employ monitoring for all your self-hosted apps. A couple of things that you should look at include: -- Use SSL for securing traffic in transit -- Configure [authentication](/docs/authentication.md#alternative-authentication-methods) to prevent unauthorized access -- Keep your system, software and Dashy up-to-date -- Ensure your server is appropriately secured -- Manage users and SSH correctly -- Enable and configure firewall rules -- Implement security, malware and traffic scanning -- Setup malicious traffic detection -- Understand the [Docker attack fronts](https://docs.docker.com/engine/security/), and follow [Docker Security Best Practices](https://snyk.io/blog/10-docker-image-security-best-practices/) - -This is covered in more detail in [App Management](/docs/management.md). - ---- - -## Security Features - -#### Subresource Integrity -[Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) or SRI is a security feature that enables browsers to verify that resources they fetch are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match. This prevents the app from loading any resources that have been manipulated, by verifying the files hashes. It safeguards against the risk of an attacker injecting arbitrary malicious content into any files served up via a CDN. - -Dashy supports SRI, and it is recommended to enable this if you are hosting your dashboard via a public CDN. To enable SRI, set the `INTEGRITY` environmental variable to `true`. - -#### Authentication -Dashy supports both basic auth, as well as server-based SSO using Keycloak. Full details of which, along with alternate authentication methods can be found in the [Authentication Docs](/docs/authentication.md). If your dashboard is exposed to the internet and/ or contains any sensitive info it is strongly recommended to configure access control with Keycloak or another server-side method. - ---- - -## Disabling Features -You may wish to disable features that you don't want to use, if they involve storing data in the browser or making network requests. -- To disable smart-sort (uses local storage), set `appConfig.disableSmartSort: true` -- To disable update checks (makes external request to GH), set `appConfig.disableUpdateChecks: true` -- To disable web search (redirect to external / internal content), set `appConfig.disableWebSearch: true` -- To keep status checks disabled (external/ internal requests), set `appConfig.statusCheck: false` -- To keep font-awesome icons disabled (external requests), set `appConfig.enableFontAwesome: false` -- To keep error reporting disabled (external requests and data collection), set `appConfig.enableErrorReporting: false` -- To keep the service worker disabled (stores cache of app in browser data), set `appConfig.enableServiceWorker: false` - ---- - -## Reporting a Security Issue -If you think you've found a critical issue with Dashy, please send an email to `security@mail.alicia.omg.lol`. You can encrypt it, using [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7). You should receive a response within 48 hours. - -All non-critical issues can be raised as a ticket. - -Please include the following information: -- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) -- Full paths of source file(s) related to the manifestation of the issue -- The location of the affected source code (tag/branch/commit or direct URL) -- Any special configuration required to reproduce the issue -- Step-by-step instructions to reproduce the issue -- Proof-of-concept or exploit code (if possible) -- Impact of the issue, including how an attacker might exploit the issue +# Privacy & Security + +Dashy was built with privacy in mind. +Self-hosting your own apps and services is a great way to protect yourself from the mass data collection employed by big tech companies, and Dashy was designed to keep your local services organized and accessible from a single place. + +It's fully open source, and I've tried to keep to code as clear and thoroughly documented as possible, which will make it easy for you to understand exactly how it works, and what goes on behind the scenes. + +For privacy and security tips, check out another project of mine: **[Personal Security Checklist](https://github.com/Lissy93/personal-security-checklist)**. + +- [External Requests](#external-requests) + - [Themes](#themes) + - [Icons](#icons) + - [Features](#features) + - [Widgets](#widgets) +- [Browser Storage](#browser-storage) +- [App Dependencies](#dependencies) +- [Security Features](#security-features) +- [Securing your Environment](#securing-your-environment) +- [Reporting a Security Issue](#reporting-a-security-issue) + +--- + +## External Requests +By default, Dashy will not make any external requests, unless you configure it to. Some features (which are off by default) do require internat access, and this section outlines those features, the services used, and links to their privacy policies. + +The following section outlines all network requests that are made when certain features are enabled. + +### Themes + +### Icons + +#### Font Awesome +If either any of your sections, items or themes are using icons from font-awesome, then it will be automatically enabled. But you can also manually enable or disable it by setting `appConfig.enableFontAwesome` to `true` / `false`. Requests are made directly to Font-Awesome CDN, for more info, see the [Font Awesome Privacy Policy](https://fontawesome.com/privacy). + +#### Material Design Icons +If either any of your sections, items or themes are mdi icons, then it will be automatically enabled. But you can also manually enable or disable it by setting `appConfig.enableMaterialDesignIcons` to `true` / `false`. Requests are made directly to Material-Design-Icons CDN, for more info, see the [Material Design Icons Website](https://materialdesignicons.com/). + + +#### Favicon Fetching +If an item's icon is set to `favicon`, then it will be auto-fetched from the corresponding URL. Since not all websites have their icon located at `/favicon.ico`, and if they do, it's often very low resolution (like `16 x 16 px`). Therefore, the default behavior is for Dashy to check if the URL is public, and if so will use an API to fetch the favicon. For self-hosted services, the favion will be fetched from the default path, and no external requests will be made. + +The default favicon API is [allesedv.com](https://favicon.allesedv.com/), but this can be changed by setting `appConfig.faviconApi` to an alternate source (`iconhorse`, `clearbit`, `faviconkit`, `besticon`, `duckduckgo`, `google` and `allesedv` are supported). If you do not want to use any API, then you can set this property to `local`, and the favicon will be fetched from the default path. For hosted services, this will still incur an external request. + +#### Generative Icons +If an item has the icon set to `generative`, then an external request it made to [Dice Bear](https://dicebear.com/) to fetch the uniquely generated icon. The URL of a given service is used as the key for generating the icon, but it is first hashed and encoded for basic privacy. For more info, please reference the [Dicebear Privacy Policy](https://avatars.dicebear.com/legal/privacy-policy) + +As a fallback, if Dicebear fails, then [Evatar](https://evatar.io/) is used. + + +#### Other Icons +Section icons, item icons and app icons are able to accept a URL to a raw image, if the image is hosted online then an external request will be made. To avoid the need to make external requests for icon assets, you can either use a self-hosted CDN, or store your images within `./public/item-icons` (which can be mounted as a volume if you're using Docker). + +#### Web Assets +By default, all assets required by Dashy come bundled within the source, and so no external requests are made. If you add an additional font, which is imported from a CDN, then that will incur an external request. The same applies for other web assets, like external images, scripts or styles. + +### Features + +#### Status Checking +The status checking feature allows you to ping your apps/ services to check if they are currently operational. + +Dashy will ping your services directly, and does not rely on any third party. If you are checking the uptime status of a public/ hosted application, then please refer to that services privacy policy. For all self-hosted services, requests happen locally within your network, and are not external. + +#### Update Checks +When the application loads, it checks for updates. The results of which are displayed in the config menu of the UI. This was implemented because using a very outdated version of Dashy may have unfixed issues. Your version is fetched from the source (local request), but the latest version is fetched from GitHub, which is an external request. This can be disabled by setting `appConfig.disableUpdateChecks: true` + +#### Anonymous Error Reporting +Error reporting is disabled by default, and no data will ever be sent without your explicit consent. In fact, the error tracking code isn't even imported unless you have actively enabled it. [Sentry](https://github.com/getsentry/sentry) is used for this, it's an open source error tracking and performance monitoring tool, used to identify any issues which occur in the production app (if you enable it). + +The crash report includes the file or line of code that triggered the error, and a 2-layer deep stack trace. Reoccurring errors will also include the following user information: OS type (Mac, Windows, Linux, Android or iOS) and browser type (Firefox, Chrome, IE, Safari). Data scrubbing is enabled. IP address will not be stored. If any potentially identifiable data ever finds its way into a crash report, it will be automatically and permanently erased. All statistics collected are anonomized and stored securely, and ae automatically deleted after 14 days. For more about privacy and security, see the [Sentry Docs](https://sentry.io/security/). + +Enabling anonymous error reporting helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. Error reporting is activated by setting `appConfig.enableErrorReporting: true`. + +If you need to monitor bugs yourself, then you can [self-host your own Sentry Server](https://develop.sentry.dev/self-hosted/), and use it by setting `appConfig.sentryDsn` to your Sentry instances [Data Source Name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/), then just enable error reporting in Dashy. + +### Widgets + +Dashy supports [Widgets](/docs/widgets.md) for displaying dynamic content. The following widgets make external data requests: + +- **[Weather](/docs/widgets.md#weather)** and **[Weather Forecast](/docs/widgets.md#weather-forecast)**: `https://api.openweathermap.org` + - [OWM Privacy Policy](https://openweather.co.uk/privacy-policy) +- **[RSS Feed](/docs/widgets.md#rss-feed)**: `https://api.rss2json.com/v1/api.json` + - [Rss2Json Privacy Policy](https://rss2json.com/privacy-policy) +- **[IP Address](/docs/widgets.md#public-ip)**: `https://ipapi.co/json` or `http://ip-api.com/json` + - [IPGeoLocation Privacy Policy](https://ipgeolocation.io/privacy.html) + - [IP-API Privacy Policy](https://ip-api.com/docs/legal) +- **[Crypto Watch List](/docs/widgets.md#crypto-watch-list)** and **[Token Price History](/docs/widgets.md#crypto-token-price-history)**: `https://api.coingecko.com` + - [CoinGecko Privacy Policy](https://www.coingecko.com/en/privacy) +- **[Wallet Balance](/docs/widgets.md#wallet-balance)**: `https://api.blockcypher.com/` + - BlockCypher Privacy Policy](https://www.blockcypher.com/privacy.html) +- **[Code::Stats](/docs/widgets.md#code-stats)**: `https://codestats.net` + - [Code::Stats Privacy Policy](https://codestats.net/tos#privacy) +- **[AnonAddy](/docs/widgets.md#anonaddy)**: `https://app.anonaddy.com` + - [AnonAddy Privacy Policy](https://anonaddy.com/privacy/) +- **[Vulnerability Feed](/docs/widgets.md#vulnerability-feed)**: `https://www.cvedetails.com` + - [CVE Details Privacy Policy](https://www.cvedetails.com/privacy.php) +- **[Exchange Rate](/docs/widgets.md#exchange-rates)**: `https://v6.exchangerate-api.com` + - [ExchangeRateAPI Privacy Policy](https://www.exchangerate-api.com/terms) +- **[Public Holidays](/docs/widgets.md#public-holidays)**: `https://kayaposoft.com` + - [jurajmajer/enrico](https://github.com/jurajmajer/enrico) +- **[Covid-19 Status](/docs/widgets.md#covid-19-status)**: `https://codestats.net` + - [disease-sh/api](https://github.com/disease-sh/api) +- **[Sports Scores](/docs/widgets.md#sports-scores)**: `https://thesportsdb.com` + - No Policy Availible +- **[News Headlines](/docs/widgets.md#news-headlines)**: `https://api.currentsapi.services` + - [CurrentsAPI Privacy Policy](https://currentsapi.services/privacy) +- **[TFL Status](/docs/widgets.md#tfl-status)**: `https://api.tfl.gov.uk` + - [TFL Privacy Policy](https://tfl.gov.uk/corporate/privacy-and-cookies/) +- **[Stock Price History](/docs/widgets.md#stock-price-history)**: `https://alphavantage.co` + - [AlphaVantage Privacy Policy](https://www.alphavantage.co/privacy/) +- **[ETH Gas Prices](/docs/widgets.md#eth-gas-prices)**: `https://ethgas.watch` + - [wslyvh/ethgaswatch](https://github.com/wslyvh/ethgaswatch) +- **[Joke](/docs/widgets.md#joke)**: `https://v2.jokeapi.dev` + - [SV443's Privacy Policy](https://sv443.net/privacypolicy/en) +- **[Flight Data](/docs/widgets.md#flight-data)**: `https://aerodatabox.p.rapidapi.com` + - [AeroDataBox](https://www.aerodatabox.com/#h.p_CXtIYZWF_WQd) +- **[Astronomy Picture of the Day](/docs/widgets.md#astronomy-picture-of-the-day)**: `https://apodapi.herokuapp.com` + - [NASA's Privacy Policy](https://www.nasa.gov/about/highlights/HP_Privacy.html) +- **[GitHub Trending](/docs/widgets.md#github-trending)** and **[GitHub Profile Stats](/docs/widgets.md#github-profile-stats)**: `https://api.github.com` + - [GitHub's Privacy Policy](https://docs.github.com/en/github/site-policy/github-privacy-statement) +- **[Cron Monitoring (Health Checks)](/docs/widgets.md#cron-monitoring-health-checks)**: `https://healthchecks.io` + - [Health-Checks Privacy Policy](https://healthchecks.io/privacy/) + +--- + +## Browser Storage +In order for user preferences to be persisted between sessions, certain data needs to be stored in the browsers local storage. No personal info is kept here, none of this data can be accessed by other domains, and no data is ever sent to any server without your prior consent. +You can view your browsers session storage by opening up the dev tools (F12) --> Application --> Storage. + +The following section outlines all data that is stored in the browsers, as cookies or local storage. + +#### Cookies +> Cookies have a pre-defined lifetime + +- `AUTH_TOKEN` - A unique token, generated from a hash of users credentials, to verify they are authenticated. Only used when auth is enabled + +#### Session Storage +> [Session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is deleted when the current session ends (tab / window is closed) + +- `SW_STATUS` - The current status of any service workers +- `ERROR_LOG` - List of recent errors + +#### Local Storage +> [Local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) is persisted between sessions, and only deleted when manually removed + +- `LANGUAGE` - The locale to show app text in +- `HIDE_WELCOME_BANNER` - Set to true once user dismissed welcome message, so that it's not shown again +- `LAYOUT_ORIENTATION` - Preferred section layout, either horizontal, vertical or auto +- `COLLAPSE_STATE` - Remembers which sections are collapsed +- `ICON_SIZE` - Size of items, either small, medium or large +- `THEME` - Users applied theme +- `CUSTOM_COLORS` - Any color modifications made to a given theme +- `BACKUP_ID` - If a backup has been made, the ID is stored here +- `BACKUP_HASH` - A unique hash of the previous backups meta data +- `HIDE_SETTINGS` - Lets user hide or show the settings menu +- `USERNAME` - If user logged in, store username. Only used to show welcome message, not used for auth +- `CONF_SECTIONS` - Array of sections, only used when user applies changes locally +- `PAGE_INFO` - Config page info, only used when user applies changes locally +- `APP_CONFIG` - App config, only used when user applies changes locally +- `MOST_USED` - If smart sort is used to order items by most used, store open count +- `LAST_USED` - If smart sort is used to order items by last used, store timestamps + +#### Deleting Stored Data +You can manually view and delete session storage, local storage and cookies at anytime. Fist [open](/docs/troubleshooting.md#how-to-open-browser-console) your browsers developer tools (usually F12), then under the Application tab select the storage category. Here you will see a list of stored data, and you can select any item and delete it. + +--- + +## Dependencies +As with most web projects, Dashy relies on several [dependencies](https://github.com/Lissy93/dashy/blob/master/docs/credits.md#dependencies-). For links to each, and a breakdown of their licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md). + +Dependencies can introduce security vulnerabilities, but since all these packages are open source any issues are usually very quickly spotted. Dashy is using Snyk for dependency security monitoring, and you can see [the latest report here](https://snyk.io/test/github/lissy93/dashy). If any issue is detected by Snyk, a note about it will appear at the top of the Reamde, and will usually be fixed within 48 hours. + +Note that packages listed under `devDependencies` section are only used for building the project, and are not included in the production environment. + +--- + +## Securing your Environment +Running your self-hosted applications in individual, containerized environments (such as containers or VMs) helps keep them isolated, and prevent an exploit in one service effecting another. + +There is very little complexity involved with Dashy, and therefore the attack surface is reasonably small, but it is still important to follow best practices and employ monitoring for all your self-hosted apps. A couple of things that you should look at include: +- Use SSL for securing traffic in transit +- Configure [authentication](/docs/authentication.md#alternative-authentication-methods) to prevent unauthorized access +- Keep your system, software and Dashy up-to-date +- Ensure your server is appropriately secured +- Manage users and SSH correctly +- Enable and configure firewall rules +- Implement security, malware and traffic scanning +- Setup malicious traffic detection +- Understand the [Docker attack fronts](https://docs.docker.com/engine/security/), and follow [Docker Security Best Practices](https://snyk.io/blog/10-docker-image-security-best-practices/) + +This is covered in more detail in [App Management](/docs/management.md). + +--- + +## Security Features + +#### Subresource Integrity +[Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) or SRI is a security feature that enables browsers to verify that resources they fetch are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match. This prevents the app from loading any resources that have been manipulated, by verifying the files hashes. It safeguards against the risk of an attacker injecting arbitrary malicious content into any files served up via a CDN. + +Dashy supports SRI, and it is recommended to enable this if you are hosting your dashboard via a public CDN. To enable SRI, set the `INTEGRITY` environmental variable to `true`. + +#### SSL +Native SSL support is enabled, for setup instructions, see the [Management Docs](/docs/management.md#ssl-certificates) + +#### Authentication +Dashy supports both basic auth, as well as server-based SSO using Keycloak. Full details of which, along with alternate authentication methods can be found in the [Authentication Docs](/docs/authentication.md). If your dashboard is exposed to the internet and/ or contains any sensitive info it is strongly recommended to configure access control with Keycloak or another server-side method. + +--- + +## Disabling Features +You may wish to disable features that you don't want to use, if they involve storing data in the browser or making network requests. +- To disable smart-sort (uses local storage), set `appConfig.disableSmartSort: true` +- To disable update checks (makes external request to GH), set `appConfig.disableUpdateChecks: true` +- To disable web search (redirect to external / internal content), set `appConfig.disableWebSearch: true` +- To keep status checks disabled (external/ internal requests), set `appConfig.statusCheck: false` +- To keep font-awesome icons disabled (external requests), set `appConfig.enableFontAwesome: false` +- To keep error reporting disabled (external requests and data collection), set `appConfig.enableErrorReporting: false` +- To keep the service worker disabled (stores cache of app in browser data), set `appConfig.enableServiceWorker: false` + +--- + +## Reporting a Security Issue +If you think you've found a critical issue with Dashy, please send an email to `security@mail.alicia.omg.lol`. You can encrypt it, using [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7). You should receive a response within 48 hours. + +All non-critical issues can be raised as a ticket. + +Please include the following information: +- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) +- Full paths of source file(s) related to the manifestation of the issue +- The location of the affected source code (tag/branch/commit or direct URL) +- Any special configuration required to reproduce the issue +- Step-by-step instructions to reproduce the issue +- Proof-of-concept or exploit code (if possible) +- Impact of the issue, including how an attacker might exploit the issue diff --git a/showcase.md b/showcase.md index b9eeb86..be6602d 100644 --- a/showcase.md +++ b/showcase.md @@ -16,6 +16,13 @@ --- +### Hugalafutro Dashy +> By [@hugalafutro](https://github.com/hugalafutro) [#505](https://github.com/Lissy93/dashy/discussions/505) + +[![hugalafutro-dashy-screenshot](https://i.ibb.co/PDpLDKS/hugalafutro-dashy.gif)](https://i.ibb.co/PDpLDKS/hugalafutro-dashy.gif) + +--- + ### Networking Services > By [@Lissy93](https://github.com/lissy93) @@ -126,6 +133,13 @@ --- +### Croco_Grievous +> By [u/Croco_Grievous](https://www.reddit.com/user/Croco_Grievous/) via [reddit](https://www.reddit.com/r/selfhosted/comments/t4xk3z/everything_started_with_pihole_on_a_raspberry_pi/) + +![screenshot-croco-grievous-dashy](https://i.ibb.co/59XR8KL/dashy-Croco-Grievous.png) + +--- + ### Crypto Dash > Example usage of widgets to monitor cryptocurrencies news, prices and data. Config is [available here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10#file-example-8-dashy-crypto-widgets-conf-yml) @@ -134,6 +148,13 @@ --- +### Stefantigro +> By [u/stefantigro](https://www.reddit.com/user/stefantigro/) via [reddit](https://www.reddit.com/r/selfhosted/comments/t5oril/been_selfhosting_close_to_half_a_year_now_all/) + +![screenshot-stefantigro-dashy](https://i.ibb.co/1Kb43Yy/dashy-stefantigro.png) + +--- + ### Yet Another Homelab ![screenshot-yet-another-homelab](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/9-home-lab-oblivion.png) diff --git a/troubleshooting.md b/troubleshooting.md index b98ca4b..ffa5c0f 100644 --- a/troubleshooting.md +++ b/troubleshooting.md @@ -278,12 +278,19 @@ If you're serving Dashy though a CDN, instead of using the Node server or Docker ## Widget Errors +#### Find Error Message If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't addequatley explain the problem, then you can [open the browser console](/docs/troubleshooting.md#how-to-open-browser-console) to see more details. +#### Check Config Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct. +#### Timeout Error +If the error message in the console includes: `Error: timeout of 500ms exceeded`, then your Glances endpoint is slower to respond than expected. You can fix this by [setting timeout](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md#setting-timeout) to a larger value. This is done on each widget, with the `timeout` attribute, and is specified in ms. E.g. `timeout: 5000` would only fail if no response is returned within 5 seconds. + +#### CORS error If the console message mentions to corss-origin blocking, then this is a CORS error, see: [Fixing Widget CORS Errors](#widget-cors-errors) +#### More Info If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman. --- diff --git a/widgets.md b/widgets.md index 20334b4..0919e8f 100644 --- a/widgets.md +++ b/widgets.md @@ -69,6 +69,7 @@ Dashy has support for displaying dynamic content in the form of widgets. There a - [Widget Usage Guide](#widget-usage-guide) - [Continuous Updates](#continuous-updates) - [Proxying Requests](#proxying-requests) + - [Setting Timeout](#setting-timeout) - [Custom CSS Styling](#widget-styling) - [Customizing Charts](#customizing-charts) - [Language Translations](#language-translations) @@ -1289,6 +1290,7 @@ All Glance's based widgets require a `hostname`. All other parameters are option **`apiVersion`** | `string` | _Optional_ | Specify an API version, defaults to V `3`. Note that support for older versions is limited **`limit`** | `number` | _Optional_ | For widgets that show a time-series chart, optionally limit the number of data points returned. A higher number will show more historical results, but will take longer to load. A value between 300 - 800 is usually optimal +Note that if auth is configured, requests must be proxied with `useProxy: true` ##### Info - **CORS**: 🟢 Enabled - **Auth**: 🟠 Optional @@ -1726,6 +1728,21 @@ Vary: Origin --- +### Setting Timeout + +If the endpoint you are requesting data from is slow to respond, you may see a timeout error in the console. This can easily be fixed by specifying the `timeout` property on the offending widget. This should be an integer value, in milliseconds. By default timeout is `2500` ms (2½ seconds). + +For example: + +```yaml +- type: gl-current-cpu + timeout: 8000 + options: + hostname: https://glances.dns-device.local +``` + +--- + ### Widget Styling Like elsewhere in Dashy, all colours can be easily modified with CSS variables.